health-check
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseSkill: health-check
Skill: health-check
WHAT
概述
Purpose và context
目的与上下文
- Purpose: Trả lời nhanh 3 câu hỏi về bộ "pattern chuẩn" (tập file khai trong ) mà không cần diff tay từng file như
.template-manifest.json:sync-template- Đủ chưa? — mọi pattern khai báo có mặt trên disk không (MISSING).
- Có lệch local? — pattern nào đã bị sửa kể từ lần sync gần nhất (DRIFT).
- Cần sync remote? — remote có bản pattern mới hơn không (BEHIND / version cũ).
- Trigger (when to use):
- Đầu phiên harness tự chạy (SessionStart hook) — nếu lệch sẽ tự nhắc.
- Người dùng gọi để kiểm thủ công bất cứ lúc nào.
/health-check - Trước khi quyết định có chạy hay không.
/sync-template
- Non-goals: không tự kéo/đẩy file (đó là — health-check chỉ chẩn đoán), không soi nội dung wiki (broken link, orphan, stale — đó là
/sync-template).harness/scripts/wiki-health.py
- 目的: 快速回答有关“标准 pattern”集合(在 中声明的一组文件)的 3 个问题,无需像
.template-manifest.json那样逐个手动 diff 文件:sync-template- 是否齐全? — 所有声明的 pattern 是否都存在于 disk 上(MISSING)。
- local 是否偏移? — 自最近一次 sync 以来,哪些 pattern 已被修改(DRIFT)。
- 是否需要从 remote sync? — remote 是否有更新的 pattern 版本(BEHIND / version 较旧)。
- 触发条件(何时使用):
- harness 会话开始时自动运行(SessionStart hook)— 如果存在 drift,会自动提示。
- 用户可随时调用 手动检查。
/health-check - 在决定是否运行 之前。
/sync-template
- 非目标: 不自动拉取或推送文件(这是 的职责——health-check 只负责诊断),也不检查 wiki 内容(broken link、orphan、stale——这些由
/sync-template负责)。harness/scripts/wiki-health.py
Mental model
心智模型
Cơ chế: 1 file cấu hình duy nhất lưu + hash từng pattern. So 3 mốc: disk ↔ version.json (drift), local ↔ remote version.json (behind), manifest ↔ disk (missing). Kết quả mỗi pattern → · · → hành động khuyến nghị.
harness/version.jsontemplate_versionOKDRIFTNEEDS-SYNC机制:唯一的配置文件 保存 和每个 pattern 的 hash。比较 3 个基准:disk ↔ version.json(drift)、local ↔ remote version.json(behind)、manifest ↔ disk(missing)。每个 pattern 的结果为 · · → 推荐对应操作。
harness/version.jsontemplate_versionOKDRIFTNEEDS-SYNCInput và output contract
输入与输出约定
| Field | Required? | Ý nghĩa | |
|---|---|---|---|
| In | | có | tập pattern + fingerprint; thiếu version.json → báo phần local (fail-open) |
| In | | không | nhánh remote; bỏ fetch; output máy đọc; exit 2 cho gate CI |
| Out | báo cáo status từng nhóm + dòng OKF v0.1 | có | |
| Out | exit code | khi | 2 nếu nhóm chỉ định vi phạm |
| Out | | chỉ khi | hash khớp disk |
| 字段 | 必填? | 含义 | |
|---|---|---|---|
| 输入 | | 是 | pattern 集合与 fingerprint;缺少 version.json 时报告 local 部分(fail-open) |
| 输入 | | 否 | remote 分支;跳过 fetch;机器可读输出;为 CI gate 设置 exit 2 |
| 输出 | 按组划分的 status 报告 + OKF v0.1 行 | 是 | |
| 输出 | exit code | 使用 | 指定组违规时返回 2 |
| 输出 | 已刷新的 | 仅在 sync 后使用 | hash 与 disk 匹配 |
Rules và capabilities
规则与能力
- RULE-01 (MUST): Fail-open tuyệt đối: lỗi mạng / thiếu version.json → báo cáo phần local, KHÔNG chặn phiên.
- RULE-02 (MUST): là nguồn sự thật duy nhất cho version — không hardcode version ở chỗ khác.
harness/version.json - RULE-03 (MUST): Pattern set = trong
includes, TRỪ.template-manifest.jsonvà các file "sống" theo project (harness/version.json,index.md,log.md,active-context.md) — chúng được seed nhưng không tính drift.decisions.md - RULE-04 (MUST): chỉ ở repo template; project con chỉ
--bump.--update - RULE-05 (MUST): Thêm pattern mới: add vào
.template-manifest.jsonTRƯỚC, rồiincludes.--update - Capabilities: đọc disk + manifest + version.json cục bộ; đọc version.json remote (tuỳ chọn, có thể offline); ghi version.json chỉ khi .
--update
- RULE-01(MUST):必须绝对 fail-open:网络错误或缺少 version.json 时,报告 local 部分,不得阻止会话。
- RULE-02(MUST):是 version 的唯一事实来源——不得在其他位置 hardcode version。
harness/version.json - RULE-03(MUST):Pattern 集合 = 中的
.template-manifest.json,减去includes和各 project 的“动态”文件(harness/version.json、index.md、log.md、active-context.md)——这些文件会被 seed,但不计入 drift。decisions.md - RULE-04(MUST):只能在模板 repo 中使用;子 project 只能使用
--bump。--update - RULE-05(MUST):添加新 pattern 时:先将 pattern 添加到 的
.template-manifest.json中,然后运行includes。--update - 能力:读取 disk、本地 manifest 和 version.json;可选读取 remote version.json(可使用 offline 模式);仅在使用 时写入 version.json。
--update
Failure boundaries
失败边界
- Mạng lỗi / remote không với tới → báo phần local, partial, không chặn (RULE-01).
- Thiếu → báo phần kiểm được, không chặn.
harness/version.json - gặp nhóm vi phạm → failed (exit 2) cho gate CI.
--fail-on - DRIFT không rõ là cải tiến hay lỡ tay → clarify với user trước khi upstream hay revert.
- 网络错误或无法访问 remote → 报告 local 部分,结果标记为 partial,不得阻止会话(RULE-01)。
- 缺少 → 报告可检查的部分,不得阻止会话。
harness/version.json - 遇到指定组违规 → 状态为 failed(exit 2),用于 CI gate。
--fail-on - 无法确定 DRIFT 是有意改进还是误修改 → 在执行 upstream 或 revert 之前,先向用户 clarify。
HOW
操作指南
Main workflow
主工作流
| Step | Type | Inputs | Action | Outputs/exit | Failure/next |
|---|---|---|---|---|---|
| W01 | deterministic | repo, nhánh | Chạy báo cáo | bảng status + dòng OKF | offline → B01 |
| W02 | judgment | báo cáo | Đọc kết quả theo bảng status | hành động khuyến nghị | |
| W03 | effect | khuyến nghị | Hành động: | pattern đã đồng bộ/revert | DRIFT mơ hồ → clarify |
| W04 | effect | sau sync | Refresh fingerprint | version.json khớp disk | — |
Chi tiết từng bước (nguồn chân lý cho W01–W04):
| 步骤 | 类型 | 输入 | 操作 | 输出/退出状态 | 失败/下一步 |
|---|---|---|---|---|---|
| W01 | deterministic | repo、分支 | 运行 | status 表 + OKF 行 | offline → B01 |
| W02 | judgment | 报告 | 根据 status 表读取结果 | 推荐操作 | |
| W03 | effect | 推荐操作 | 执行操作:downstream/upstream | pattern 已同步或 revert | DRIFT 含义不明确 → clarify |
| W04 | effect | sync 后 | 刷新 fingerprint: | version.json 与 disk 匹配 | — |
各步骤详情(W01–W04 的事实来源):
1. Chạy báo cáo (đối chiếu cả remote)
1. 运行报告(同时对比 remote)
bash
python3 harness/scripts/health-check.py --root . --branch orca- : chỉ kiểm local (bỏ fetch remote) khi không có mạng.
--offline - : output máy đọc (dùng cho hook / CI).
--json - : exit 2 nếu nhóm chỉ định vi phạm (dùng cho gate CI).
--fail-on behind,drift,missing
bash
python3 harness/scripts/health-check.py --root . --branch orca- :无网络时仅检查 local(跳过 fetch remote)。
--offline - :输出机器可读格式(用于 hook / CI)。
--json - :指定组违规时返回 exit 2(用于 CI gate)。
--fail-on behind,drift,missing
2. Đọc kết quả
2. 读取结果
| status | nghĩa | hành động |
|---|---|---|
| pattern đủ + khớp remote | không cần làm gì |
| pattern bị sửa local | cân nhắc upstream ( |
| thiếu file hoặc remote mới hơn | chạy downstream |
Báo cáo còn kèm 1 dòng OKF v0.1: (mọi concept có YAML frontmatter + ) hoặc . Đây là câu trả lời nhanh "project đã đạt chuẩn OKF chưa?". Chưa đạt → .
✓ OKF v0.1: N/N concept đạt chuẩntype⟳ OKF v0.1: x/N … cần migratepython3 harness/scripts/okf-check.py --migrate| status | 含义 | 操作 |
|---|---|---|
| pattern 齐全且与 remote 匹配 | 无需操作 |
| pattern 在 local 被修改 | 考虑 upstream( |
| 缺少 file 或 remote 版本更新 | 运行 downstream |
报告还包含一行 OKF v0.1:(所有 concept 都包含 YAML frontmatter + ),或 。这是对“project 是否达到 OKF 标准?”的快速回答。如果尚未达标 → 。
✓ OKF v0.1: N/N concept đạt chuẩntype⟳ OKF v0.1: x/N … cần migratepython3 harness/scripts/okf-check.py --migrate3. Hành động theo khuyến nghị
3. 根据建议执行操作
- BEHIND / MISSING → gọi (downstream): kéo pattern mới/thiếu về.
/sync-template - DRIFT → nếu cải tiến muốn giữ: upstream; nếu lỡ sửa:
/sync-template.git checkout -- <file>
- BEHIND / MISSING → 调用 (downstream):拉取新的或缺失的 pattern。
/sync-template - DRIFT → 如果是希望保留的改进:upstream;如果是误修改:
/sync-template。git checkout -- <file>
4. Sau khi sync xong — refresh version.json
4. sync 完成后——刷新 version.json
Mỗi lần downstream sync đổi nội dung pattern, cập nhật lại fingerprint:
bash
python3 harness/scripts/health-check.py --update # giữ nguyên version
python3 harness/scripts/health-check.py --update --bump patch # khi PHÁT HÀNH bản mới (chỉ làm ở repo template)(major/minor/patch) CHỈ chạy ở repo template--bumpkhi muốn công bố version pattern mới cho mọi project. Project con chỉRheinmir/setup(không bump) để đồng bộ hash sau khi pull.--update
每次 downstream sync 更改 pattern 内容后,重新更新 fingerprint:
bash
python3 harness/scripts/health-check.py --update # giữ nguyên version
python3 harness/scripts/health-check.py --update --bump patch # khi PHÁT HÀNH bản mới (chỉ làm ở repo template)(major/minor/patch)只能在模板 repo--bump中运行,用于向所有 project 发布新的 pattern version。子 project 仅使用Rheinmir/setup(不 bump),以便在 pull 后同步 hash。--update
Branches
分支
| ID | Kind | Guard | Hành vi | Skip / failure | Rejoin |
|---|---|---|---|---|---|
| B01 | user_optional | không có mạng / user muốn chỉ kiểm local | thêm | lỗi mạng khi không cờ → vẫn báo phần local (fail-open) | W02 |
| B02 | conditional_required | đang ở repo template | | project con → chỉ | kết thúc |
| B03 | capability_optional | chạy trong gate CI/hook | | — | W02 (hoặc exit 2) |
| ID | 类型 | 条件 | 行为 | 跳过/失败 | 汇合 |
|---|---|---|---|---|---|
| B01 | user_optional | 无网络或用户只想检查 local | 添加 | 未设置该参数但发生网络错误时,仍报告 local 部分(fail-open) | W02 |
| B02 | conditional_required | 位于模板 repo | | 子 project → 仅使用 | 结束 |
| B03 | capability_optional | 在 CI gate/hook 中运行 | 使用 | — | W02(或 exit 2) |
Validation và stopping
验证与停止条件
Status do tính tất định (hash + so version), không do model đoán. Dừng khi status , hoặc sau khi hành động khuyến nghị xong và đã đồng bộ hash.
health-check.pyOK--updateStatus 由 确定性计算(hash + version 比较),不是由 model 猜测。当 status 为 时停止,或在完成推荐操作且 已同步 hash 后停止。
health-check.pyOK--updateExamples
示例
- Positive: đầu phiên, remote có
orcamới hơn → báotemplate_version(BEHIND) → gọiNEEDS-SYNCdownstream →/sync-template→ chạy lại rapython3 harness/scripts/health-check.py --update.OK - Boundary/failure: máy offline, chạy không → fetch remote lỗi, vẫn in phần local (DRIFT/MISSING) và không chặn phiên; nhóm BEHIND không xác định được.
--offline
- 正向示例: 会话开始时,remote 的
orca更新 → 报告template_version(BEHIND)→ 调用 downstreamNEEDS-SYNC→/sync-template→ 再次运行得到python3 harness/scripts/health-check.py --update。OK - 边界/失败: 机器处于 offline 状态且运行时未添加 → fetch remote 失败,仍会输出 local 部分(DRIFT/MISSING),且不会阻止会话;无法确定 BEHIND 组的状态。
--offline
Reference — Quan hệ với skill khác
参考——与其他 skill 的关系
- [[sync-template]] — health-check chẩn đoán (có cần sync không); sync-template thực thi (kéo/đẩy file). Luôn chạy health-check trước, sync-template sau.
- — anh em cùng tầng L4 nhưng soi nội dung wiki (broken link, orphan, stale), không soi version pattern.
harness/scripts/wiki-health.py
- [[sync-template]] — health-check 负责诊断(是否需要 sync);sync-template 负责执行(拉取/推送文件)。始终先运行 health-check,再运行 sync-template。
- — 同属 L4 层的兄弟工具,但负责检查 wiki 内容(broken link、orphan、stale),不检查 pattern version。
harness/scripts/wiki-health.py
Origin
来源
- Draft:
llmwiki/wiki/sources/draft/150626-health-check-pattern-sync.md
- Draft:
llmwiki/wiki/sources/draft/150626-health-check-pattern-sync.md