harness-update

技能：harness-update

内容

目的与上下文

• 目的： 为旧项目执行一条命令，即可安装或更新 harness stack（L0–L4），并自动代替用户偿还 legacy wiki 欠账。
• 触发条件（适用场景）：“自维护框架”、“self-maintain”、“迁移 harness”、“更新 harness”、“更新 overstack”、“升级 harness”、“在旧项目中安装 harness”、“/harness-update”——项目有旧版 llmwiki 需要迁移（案例 B），或已有 harness 需要更新（案例 C）。
• 非目标： 不用于尚无任何内容、需要从代码生成 wiki 的项目——这应使用 /new-project-setup（案例 A）。不用于修复基础设施故障（网络、python3、验证器故障）。

< 30s： 使用 --self-heal 标志——安装程序会在同一进程中自动补齐欠账（Origin + index + OKF），然后重新审计一次。Agent 只需调用一条命令、读取一个结果并汇报。不再由 Agent 循环重新运行（这是旧版本变慢的原因——参见 [[230626-harness-update-sub30s]]）。

心智模型

installer --self-heal（1 个进程：安装 L0–L4 → 审计 → 补齐欠账 → 重新审计 → 激活 + smoke）→ rc（0 表示干净 · 3 表示仍有欠账 · 其他值表示基础设施故障）→ 验收 + 刷新 CAPABILITIES + 记录日志 → 汇报 4 项内容。

输入和输出约定

	字段	必填？	含义
输入	目标项目（当前目录）	是	有旧版 llmwiki（案例 B）或旧版 harness（案例 C）
输入	harness/scripts/install-harness.sh	否	如果缺少，则克隆模板 rheinmir/setup 的 orca 分支
输出	已安装 harness L0–L4 + 已补齐 wiki 欠账	是	rc=0 表示干净
输出	重新生成的 CAPABILITIES.md	存在 build-capabilities 时	旧版本没有时则跳过
输出	llmwiki/wiki/log.md 中的一条日志 + 4 项内容的报告	是	补齐数量取自 [audit] backfill xong 行

规则与能力

• RULE-01（MUST）：补齐操作只会新增内容，绝不修改或删除现有 wiki 内容（安装程序中的 self-heal 遵守此规则）。
• RULE-02（MUST）：任何情况下都不得触碰 raw/。
• RULE-03（MUST）：rc=3（仍有欠账）需要用户或技能处理一次；其他 rc（基础设施故障）由用户处理——必须明确区分，不要尝试修复基础设施故障。
• RULE-04（MUST）：不带 --self-heal 标志时，安装程序的行为与旧版完全相同（审计后若有欠账则以 3 退出）——向后兼容。
• RULE-05（MUST）：案例 A（尚无 llmwiki，需要读取代码并生成 wiki）→ 转至 /new-project-setup。
• 能力：本地运行安装程序（可通过网络克隆模板）；写入 harness、wiki（只新增）和日志；不写入 raw/。

故障边界

• rc=3 → 部分完成：欠账列表位于输出中，手动修复一次后重新运行 W01。
• 其他 rc（1/4）→ 受阻（基础设施故障）：停止，原样告知用户，不要自行猜测。
• 项目尚无 llmwiki（案例 A）→ 在此技能中 取消，转至 /new-project-setup。

用法

主工作流

步骤	类型	输入	操作	输出/退出条件	失败/下一步
W01	effect	目标项目	使用 --self-heal 运行一次 installer（缺少源时克隆模板）	output + rc	—
W02	deterministic	rc	读取退出码，禁止循环重跑	rc=0 → W03	rc=3 → B01；其他 rc → blocked
W03	effect	W01 的 output	验收 ⛔×3 + 刷新 CAPABILITIES + 可选 health-check + 记录日志	log + CAPABILITIES	没有 build-capabilities → 跳过
W04	deterministic	结果	向用户报告完整的 4 项内容	报告	—

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

1. 根据 LAYOUT 选择路径，然后只运行一次 installer：

• 下游项目的 dot layout（存在 .llmwiki/.harness-stamp — 所有从 v4 开始安装的机器）：engine 位于 GLOBAL，因此更新 = 重新运行 bootstrap。它会在版本不一致时刷新 ~/.claude/harness，在同一轮中拉取/更新 engine orca-graph 和 shim，重新写入 stamp，并且不会将 engine 复制到项目中：

curl -fsSL https://raw.githubusercontent.com/Rheinmir/setup/orca/harness/poc-vendor-neutral/bootstrap.sh | bash

在此 layout 下误调用 install-harness.sh . --self-heal → 脚本会自动停止，返回 rc 5，并打印正确命令（截至 20/09/2026：旧路径不会更新 global，反而会将 77 个 script 复制到项目中）。Agent 在带 pty 的 terminal 中运行时：添加 -s -- --with-graph，避免等待 60 秒的 checklist。

• 框架仓库（repo_role: framework）：不要在此运行 installer — installer 会自动拒绝并返回 rc 3。更新 framework = git pull。
• 旧式裸 layout（项目中有 llmwiki/ + harness/，尚无 stamp）— 使用 --self-heal 路径（自动检测迁移/更新；缺少源时克隆模板）：

test -f harness/scripts/install-harness.sh \
  && bash harness/scripts/install-harness.sh . --self-heal \
  || { git clone -q --depth 1 -b orca [email protected]:rheinmir/setup.git /tmp/llmwiki-tpl \
       && bash /tmp/llmwiki-tpl/harness/scripts/install-harness.sh . --self-heal ; rm -rf /tmp/llmwiki-tpl; }

Installer 会自动完成全部流程：安装 L0–L4 → audit（Origin/index/OKF 通过 audit.py 合并为 1 个 process）→ 如果有欠项则自动 backfill（Origin 通过 1 次 git log 为整批获取 hash；index 添加缺失的 row；OKF 将粗体 **Type:** 迁移为 YAML）→ 再次 audit 1 次 → activate + smoke。

2. 读取退出码（禁止循环重跑 — self-heal 已在内部运行）：

• rc=0 → 无问题（已自动完成 backfill）。进入第 3 步。
• rc=3 → 仍有 self-heal 无法自动修复的欠项（例如文件冲突、无法推断 OKF 类型）：列表就在 output 中。手动修复一次，然后重跑第 1 步。
• rc 其他值（1/4）→ 基础设施错误（network、python3、validator 故障）— 停止，原样告知用户，不要自行猜测。

3. 验收 + 记录日志：

• 确认第 1 步的 output 中，表格“Harness 自检”显示 ⛔×3 已阻止 ✓（如果有 pre-commit，installer 已运行 pre-commit install；如果没有，则提醒用户运行 pipx install pre-commit）。
• 刷新能力地图（让 Agent 在更新后看到正确的工具 — ADR-005）：运行 python3 ~/.claude/harness/hooks/build-capabilities.py --root .（与 hooks 一同部署的版本）或 python3 fdk/tools/build-capabilities.py（如果当前位于框架仓库中）→ 重新生成 CAPABILITIES.md。没有 build-capabilities 文件（旧版本）→ 跳过，不报错。
• Health-check（可选，确认更新后防护仍然生效）：运行 /health-check 或 python3 ~/.claude/harness/hooks/health-check.py。
• 追加到 llmwiki/wiki/log.md：## YYYY-MM-DD — harness-update — migrate/update xong (--self-heal), nợ đã backfill: <n> file。数据取自 output 中的 [audit] backfill xong — Origin:<a> index:<b> OKF:<c> 行。

4. 向用户报告（必须包含完整的 4 项内容）：

• 已运行的模式（migrate 或 update）+ self-heal 已 backfill 的欠项数量（Origin/index/OKF，取自 [audit] backfill xong 行）
• Settings root：如果有合并，说明备份文件 .bak.*
• 提醒：打开新 session 后 hooks 才会加载
• 邀请用户运行 /harness-tour，直观查看防护如何生效

分支

ID	类型	条件	行为	跳过/失败	返回
B01	recovery	rc=3	手动修复一次 self-heal 无法自动修复的欠项（列表在 output 中）	仍为 rc=3 → 告知用户	W01
B02	capability_optional	存在 build-capabilities.py（部署版或框架仓库）	重新生成 CAPABILITIES.md	旧版本中不存在 → 跳过，不报错	W03
B03	user_optional	想确认防护仍然生效	/health-check	跳过	W03

验证与停止

结论由安装脚本的返回码决定（必须遵守）＋“Harness 自检”表中的 ⛔×3。最多进行一轮 B01 → W01；返回码非 0 或 3 时立即停止。

示例

• **正向：**项目中有旧的 llmwiki，12 个页面缺少 ## Origin → install-harness.sh . --self-heal → [audit] backfill xong — Origin:12 index:0 OKF:0，返回码为 0 → 记录日志并报告“迁移、回填 12 个文件，打开新会话以加载 hooks”。
• **边界/失败：**机器上没有 python3 → 返回码为 1 → 停止，向用户原样报告错误，不要自行安装或重试。