health-check

技能：health-check

内容

目的与背景

• 目的： 快速回答有关“标准模式集”（在 .template-manifest.json 中声明的文件集合）的 3 个问题，无需像 sync-template 那样手动逐个比较文件：
  1. 齐全吗？ — 声明的所有模式在磁盘上都存在吗（MISSING）。
  2. 本地有偏差吗？ — 哪些模式自上次同步后被修改过（DRIFT）。
  3. 需要同步远程吗？ — 远程是否有更新的模式版本（BEHIND／版本过旧）。
• 触发条件（何时使用）：
  • 会话开始时，harness 自动运行（SessionStart hook）——如果存在偏差，会自动提醒。
  • 用户随时调用 /health-check 手动检查。
  • 在决定是否运行 /sync-template 之前。
• 非目标： 不会自动拉取／推送文件（这是 /sync-template 的工作——health-check 只负责诊断），也不会检查 wiki 内容（断链、孤立页面、过期内容——这是 harness/scripts/wiki-health.py 的工作）。

心智模型

机制：唯一的配置文件 harness/version.json 保存 template_version 和每个模式的哈希值。比较 3 个基准：磁盘 ↔ version.json（偏差）、本地 ↔ 远程 version.json（落后）、清单 ↔ 磁盘（缺失）。每个模式的结果 → OK · DRIFT · NEEDS-SYNC → 建议采取的操作。

输入和输出约定

	字段	必需？	含义
输入	.template-manifest.json + harness/version.json	是	模式集合 + 指纹；缺少 version.json 时 → 报告本地部分（开放式失败）
输入	--branch / --offline / --json / --fail-on	否	远程分支；跳过 fetch；机器可读输出；CI gate 的退出码为 2
输出	各组状态报告 + OKF v0.1 行	是	OK / DRIFT / NEEDS-SYNC + ✓ OKF v0.1: N/N …
输出	退出码	使用 --fail-on 时	指定组存在违规时为 2
输出	已刷新的 harness/version.json	仅在同步后使用 --update 时	哈希与磁盘一致

规则与能力

• RULE-01（MUST）：始终开放式失败：网络错误／缺少 version.json 时 → 报告本地部分，不阻止会话。
• RULE-02（MUST）：harness/version.json 是版本的唯一真实来源——不得在其他地方硬编码版本。
• RULE-03（MUST）：模式集合 = .template-manifest.json 中的 includes，但不包括 harness/version.json 和项目专属的“活动”文件（index.md、log.md、active-context.md、decisions.md）——这些文件会被初始化，但不计入偏差检查。
• RULE-04（MUST）：--bump 仅用于模板仓库；下游项目只能使用 --update。
• RULE-05（MUST）：添加新模式：先将其添加到 .template-manifest.json 的 includes，再运行 --update。
• 能力：读取磁盘、本地 manifest 和 version.json；读取远程 version.json（可选，也可离线运行）；仅在使用 --update 时写入 version.json。

失败边界

• 网络错误／无法访问远程 → 报告本地部分，标记为部分结果，不阻止操作（RULE-01）。
• 缺少 harness/version.json → 报告可检查的部分，不阻止操作。
• --fail-on 检测到指定组违规 → CI gate 判定为失败（退出码为 2）。
• 无法确定 DRIFT 是改进还是误操作 → 在向上游提交或还原之前，先与用户确认。

用法

主要工作流

步骤	类型	输入	操作	输出／退出码	失败／后续
W01	确定性	仓库、分支	运行 harness/scripts/health-check.py 报告（可选是否检查远程）	状态表 + OKF 行	离线 → B01
W02	判断	报告	根据状态表解读结果	建议的操作	OK → 完成
W03	操作	建议	执行操作：下游／上游的 /sync-template 或 git checkout -- <file>	已同步／还原的模式	DRIFT 含义不明 → 确认
W04	操作	同步后	刷新指纹 --update（仅模板仓库可 bump，见 B02）	version.json 与磁盘一致	—

各步骤详情（W01–W04 的真实来源）：

1. 运行报告（与远程进行对照）

python3 harness/scripts/health-check.py --root . --branch orca

• --offline ：仅检查本地（跳过远程 fetch），用于无网络时。
• --json ：机器可读输出（供 hook／CI 使用）。
• --fail-on behind,drift,missing ：指定组存在违规时退出码为 2（用于 CI gate）。

2. 阅读结果

status	含义	操作
OK	pattern 完整且与远程匹配	无需操作
DRIFT	pattern 在本地被修改	考虑 upstream（/sync-template push）或还原
NEEDS-SYNC	缺少文件或远程版本更新	运行 downstream /sync-template

报告还会附带 1 行 OKF v0.1：✓ OKF v0.1: N/N concept đạt chuẩn（所有 concept 都有 YAML frontmatter 和 type），或 ⟳ OKF v0.1: x/N … cần migrate。这能快速回答“project 是否已符合 OKF 标准？”。尚未达标 → python3 harness/scripts/okf-check.py --migrate。

3. 根据建议采取操作

• BEHIND / MISSING → 调用 /sync-template（downstream）：拉取缺少的或新的 pattern。
• DRIFT → 如果想保留改进：/sync-template upstream；如果是不小心修改：git checkout -- <file>。

4. 完成 sync 后——刷新 version.json

每次 downstream sync 更改 pattern 内容后，都要更新 fingerprint：

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)

--bump（major/minor/patch）仅在模板 repo Rheinmir/setup 中运行，用于向所有 project 发布新的 pattern 版本。子 project 只运行 --update（不 bump），在 pull 后同步 hash。

分支

ID	类型	条件	行为	跳过 / 失败	汇合
B01	user_optional	无网络 / 用户只想检查本地	添加 --offline，跳过远程 fetch	未加标志时遇到网络错误 → 仍报告本地部分（fail-open）	W02
B02	conditional_required	当前位于模板 repo Rheinmir/setup，且要发布新的 pattern 版本	--update --bump patch（major/minor/patch）	子 project → 只运行 --update	结束
B03	capability_optional	在 CI/hook gate 中运行	使用 --json 和/或 --fail-on behind,drift,missing	—	W02（或 exit 2）

验证与停止条件

Status 由 health-check.py 确定性计算（hash + 版本比较），而非由模型猜测。满足以下条件时停止：status 为 OK，或已完成建议的操作且 --update 已同步 hash。

示例

• **正向：**会话开始时，远程 orca 的 template_version 较新 → 报告 NEEDS-SYNC（BEHIND）→ 调用 /sync-template downstream → python3 harness/scripts/health-check.py --update → 再次运行后得到 OK。
• **边界/失败：**机器离线，运行时未加 --offline → 远程 fetch 失败，但仍打印本地部分（DRIFT/MISSING），且不会阻止会话；BEHIND 组无法确定。

参考 — 与其他 skill 的关系

• [[sync-template]] — health-check 诊断（是否需要 sync）；sync-template 执行（拉取/推送文件）。始终先运行 health-check，再运行 sync-template。
• harness/scripts/wiki-health.py — 同属 L4 层级，但检查的是 wiki 内容（失效链接、孤立页面、过时内容），不检查 pattern 版本。

来源

• 草稿：llmwiki/wiki/sources/draft/150626-health-check-pattern-sync.md