@wwkit/harness 1.0.17 → 1.0.18

package/skills/work-recovery/SKILL.md

@@ -2,7 +2,7 @@
 name: work-recovery
 description: |
   [work 专属 runbook] 仅供 work agent 通过 skill 工具显式调用（name=work-recovery），其他 agent / 普通对话禁止触发
-  恢复与护栏技能：覆盖重规划（触发条件 3 种、规则=复用 session_id/增量调整/不重做已完成、上限 3 轮超限升级用户）+ 退出条件（target 验收/重规划≤3/阻塞/预算超限/ESCALATE）+ 预算与超时（单任务超时=平台 timeout 优先/否则 prompt 软上限+maxSteps 硬兜底、等待纪律有界等待不静默阻塞、总预算护栏 4 项≤20 任务/≤30 分钟/并行≤5）+ 中断与回滚（用户中断保留现场、回滚限本任务 BASE..HEAD/工作树脏禁--hard/forbidden 文件强制 checkout/绝不 reset 早于 initial_base）+ 防失控护栏 5 条。
+  恢复与护栏技能：覆盖重规划（触发条件 3 种、规则=复用 session_id/增量调整/不重做已完成、上限 3 轮超限升级用户）+ 退出条件（target 验收/重规划≤3/阻塞/预算超限/ESCALATE）+ 预算与超时（单任务超时=prompt 软上限硬兜底、等待纪律有界等待不静默阻塞、总预算护栏 3 项≤20 任务/≤30 分钟/并行≤5）+ 中断与回滚（用户中断保留现场、回滚限本任务 BASE..HEAD/工作树脏禁--hard/forbidden 文件强制 checkout/绝不 reset 早于 initial_base）+ 防失控护栏 5 条。
   适用：work agent 运行期遇到计划级失败 / 超时 / 中断 / 需回滚 / 防失控检查时加载。
   不适用：单任务 review fix（用 work-review）；最终交付（用 work-finalize）；非 work 流程的普通恢复。
 license: MIT
@@ -42,14 +42,14 @@ work agent 运行期遇到以下任一情况时加载本技能对应阶段：
 用 `read` 工具按触发原因加载本技能 `references/` 下对应文件（相对路径基于本 skill 目录）：
 
 - `references/replan.md` → 重规划（触发条件 3 种、规则=复用 session_id/增量调整/不重做已完成、上限 3 轮超限升级用户）
-- `references/budget.md` → 退出条件（5 种）+ 预算与超时（单任务超时 / 等待纪律 / 总预算护栏 4 项）
+- `references/budget.md` → 退出条件（5 种）+ 预算与超时（单任务超时 / 等待纪律 / 总预算护栏 3 项）
 - `references/rollback.md` → 中断与回滚（用户中断 / 回滚规则 / forbidden 强制 checkout）+ 防失控护栏 5 条
 
 ### 阶段 2：按触发分支执行
 
 - **重规划**：按 `references/replan.md` 复用同一 `session_id`/`doc_dir`/Ledger，只重走第二步对未完成目标重新拆分并更新 `plan.md`，已完成任务保留标记 done 不重派发；Ledger 记 `replan round <R>/3`；最多 3 轮，超限升级用户。
 - **退出判定**：按 `references/budget.md` 退出条件 5 种逐项检查，命中即停止派发并如实报告。
-- **预算与超时**：派发 subagent 时优先用平台 `timeout`/`cancel`/后台执行；不支持则用 prompt 软上限（implementer ≤50 / fix ≤20 / reviewer ≤15）+ `maxSteps` 硬兜底；等待期有界等待不静默阻塞；总预算护栏 4 项超限即停派发记 Ledger 报告用户。
+- **预算与超时**：派发 subagent 时用 prompt 软上限（implementer ≤50 / fix ≤20 / reviewer ≤15）硬兜底；等待期有界等待不静默阻塞；总预算护栏 3 项超限即停派发记 Ledger 报告用户。
 - **中断与回滚**：用户中断立即停派发 + cancel 在途 + 记 Ledger + 保留现场；回滚限本任务 `BASE..HEAD`（BASE 从 Ledger `T<N>: base=` 读取），工作树脏禁 `--hard` 改用 `git revert` 或 `git reset --soft` + 手动 checkout，forbidden 文件强制 `git checkout -- <file>`，绝不 reset 早于 `initial_base`。
 - **防失控自检**：按 `references/rollback.md` 护栏 5 条周期自检（并发分型 / task 预算 / scoped re-review / Round 5 后裁决 / 外部信息用 general+webfetch）。
 
@@ -63,18 +63,18 @@ work agent 运行期遇到以下任一情况时加载本技能对应阶段：
 
 - 重规划复用同一 `session_id`/`doc_dir`/Ledger，是针对失败与未完成部分的增量调整，不重做已完成任务；最多 3 轮，超限升级用户不再自动继续。
 - 退出条件 5 种：target 验收通过 / 重规划 ≤3 轮 / 阻塞无法解除（含与 `constraints` 不可调和）/ 总预算超限 / subagent ESCALATE 且无法通过拆分任务/换模型解决。
-- 单任务超时：平台 `timeout`/`cancel` 优先（硬兜底），否则 prompt 软上限 + `maxSteps` 硬兜底叠加；超时立即记 Ledger `T<N>: timeout` 标 BLOCKED/ESCALATE，不无限同步等待。
-- 等待纪律：有界等待，不轮询短超时也不长时间静默；间隔（如 5 分钟）列一次在途 subagent 追查「已结束但仍未上报」的 child。
-- 总预算护栏 4 项：总任务数 ≤20 / 总运行时长 ≤30 分钟 / 总工具调用或 token 平台可观测时设上限 / 最大并行 explore ≤5；每项超限如实写进 Ledger 并报告，不静默续跑。
+- 单任务超时：prompt 软上限（implementer ≤50 / fix ≤20 / reviewer ≤15）硬兜底；超时立即记 Ledger `T<N>: timeout` 标 BLOCKED/ESCALATE，不无限同步等待。
+- 等待纪律：background 模式下主 agent 不阻塞，无需轮询；派发后继续做本地工作（写 Ledger、准备下一个 review package、读已返回的报告），收到 subagent 完成通知后处理返回。如果 subagent 异常长时间未返回（超过预算时间的 2 倍），记 Ledger `T<N>: timeout` 并标 BLOCKED/ESCALATE。
+- 总预算护栏 3 项：总任务数 ≤20 / 总运行时长 ≤30 分钟 / 最大并行 work-explore ≤5；每项超限如实写进 Ledger 并报告，不静默续跑。
 - 用户中断保留现场，不删除产物目录。
 - 回滚仅限本任务 `BASE..HEAD`；工作树脏禁 `--hard`；forbidden 文件强制 `git checkout -- <file>` 恢复；**绝不 `reset` 到早于 `initial_base`**。
-- 防失控护栏 5 条：只读 explore 可并行 ≤5 / 可写 general 必须串行；每个 task ≤10 分钟，失败先换模型/拆任务再重规划；每轮 fix 后必须 scoped re-review；Round 5 后才裁决，每条裁决都是 Ledger 条目禁止静默丢弃；需要外部信息用 `general` + `webfetch` 调研不嵌套再派发。
+- 防失控护栏 5 条：只读 work-explore 可并行 ≤5 / 可写 work-general 必须串行；每个 task ≤10 分钟，失败先换模型/拆任务再重规划；每轮 fix 后必须 scoped re-review；Round 5 后才裁决，每条裁决都是 Ledger 条目禁止静默丢弃；需要外部信息用 `work-general` + `webfetch` 调研不嵌套再派发。
 
 ## 资源目录
 
 ```
 references/
 ├── replan.md     # 重规划（触发 3 种/规则/上限 3 轮）
-├── budget.md     # 退出条件 5 种 + 预算与超时（单任务超时/等待纪律/总预算护栏 4 项）
+├── budget.md     # 退出条件 5 种 + 预算与超时（单任务超时/等待纪律/总预算护栏 3 项）
 └── rollback.md   # 中断与回滚（用户中断/回滚规则/forbidden 强制 checkout）+ 防失控护栏 5 条
 ```

package/skills/work-recovery/references/budget.md

@@ -1,7 +1,7 @@
 # 退出条件
 
 - 对照 `target` 验收标准，所有任务 `done`、review 通过 **且整体验收通过**
-- 重规划 ≤3 轮（整体步骤用平台最大步数配置兜底，如 `maxSteps`）
+- 重规划 ≤3 轮
 - 阻塞无法解除（含与 `constraints` 不可调和）
 - 总预算超限（见「预算与超时」）
 - subagent 返回 ESCALATE 且无法通过拆分任务/换模型解决 → 如实向用户报告
@@ -10,21 +10,21 @@
 
 ## 单任务超时（技术强制优先）
 
-- 派发 subagent 时，若 `task` 工具支持 `timeout` / `cancel` / 后台执行，必须显式带超时；超时后主 agent 立即记 Ledger `T<N>: timeout` 并标记 `BLOCKED`/`ESCALATE`，**不无限同步等待**（避免主 agent TUI 卡死）。
-- 若平台不支持超时/取消，仍以 prompt 级硬约束（implementer ≤50 / fix ≤20 / reviewer ≤15 次工具调用）为软上限，并在派发后主动推进，不静默阻塞。
-- 二者关系：prompt 中的工具调用上限是**软约束**，平台能力（timeout / maxSteps）是**硬兜底**，叠加使用。
+- 所有 `task` 派发**必须**在 `task` 调用中显式传 `background=true` 参数——这是 agent 行为约束。环境变量 `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` 由 opm harness 自动注入，使 `background=true` 参数生效。agent 只需在 task 调用中传 `background=true`，环境变量由 opm harness 自动注入。
+- background 模式下主 agent 不阻塞，subagent 异步运行，完成时自动通知注入结果。
+- prompt 中的工具调用上限（implementer ≤50 / work-explore ≤30 / fix ≤20 / reviewer ≤15 / re-reviewer ≤10 / final reviewer ≤30）是**软约束**，是唯一的行为限制——没有平台级硬超时兜底。
+- 如果 subagent 长时间未返回（超过预期时间），主 agent 可继续做本地工作，不阻塞。
 
 ## subagent 强制退出配置（实施细节）
 
-1. **`steps` 配置位置**：应配在 **subagent 定义**上（`agent.general.steps=50` / `agent.explore.steps=30`），不是 work agent 上——"卡住"的是 subagent（foreground 下 work 被 block），steps 达限强制结束的是被配置方。work 自身可加 `steps`（如 200）防 runaway，但次要。
-2. **background 模式启用**：在 opencode 配置中设 `OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true`，task 工具的 `background=true` 参数才生效——subagent 异步运行，主 agent 不 block，完成时自动通知注入结果。
-3. **escape 中断语义**：TUI `session_interrupt`（escape）中断的是**整个 session**（含所有子 session），不是只中断子 session。中断后可通过 `git log` + Ledger 恢复续跑。
+1. **background 模式启用**：`OPENCODE_EXPERIMENTAL_BACKGROUND_SUBAGENTS=true` 已由 opm harness 默认注入，task 工具的 `background=true` 参数直接生效——subagent 异步运行，主 agent 不 block，完成时自动通知注入结果。环境变量由 opm harness 自动注入，agent 只需在 task 调用中传 `background=true`。
+2. **escape 中断语义**：TUI `session_interrupt`（escape）中断的是**整个 session**（含所有子 session），不是只中断子 session。中断后可通过 `git log` + Ledger 恢复续跑。
+3. **subagent_depth**：限制嵌套深度（默认 1），防止 subagent 无限递归派发——限制的是嵌套层级，不是工具调用次数。
 
 ## 等待纪律（不静默阻塞）
 
-- 派发后不停摆：等待期间继续做本地工作（写 Ledger、准备下一个 review package、读已返回的报告）。
-- 空闲等待用**有界等待**：不轮询短超时，也不长时间静默；间隔一段（如 5 分钟，若平台允许）列一次在途 subagent，追查「已结束但仍未上报」的——child 的结果可能丢失，而 timeout 抓不到这种「结果丢了」的失败。
-- 发现 child 卡死/丢失：按单任务超时处理，记 Ledger `T<N>: timeout` 并标 BLOCKED/ESCALATE。
+- background 模式下主 agent 不阻塞，无需轮询。派发后继续做本地工作（写 Ledger、准备下一个 review package、读已返回的报告），收到 subagent 完成通知后处理返回。
+- 如果 subagent 异常长时间未返回（超过预算时间的 2 倍），记 Ledger `T<N>: timeout` 并标 BLOCKED/ESCALATE。
 
 ## 总预算护栏（防失控）
 
@@ -34,7 +34,6 @@
 |--------|--------|---------|
 | 总任务数 | ≤ 20 | 规划期由 2.3 范围闸门拦截；运行时超限停止拆分，评估重规划或升级用户 |
 | 总运行时长 | ≤ 30 分钟 | 停止派发，记 Ledger，报告用户 |
-| 总工具调用 / token | 平台可观测时设上限 | 同上 |
 | 最大并行 explore | ≤ 5（见 2.4） | 等待，不超额派发 |
 
 每项超限都**如实写进 Ledger** 并报告，不静默续跑。

package/skills/work-recovery/references/rollback.md

@@ -2,19 +2,19 @@
 
 ## 用户中断
 
-- 收到用户中断后：立即停止派发新 subagent；对在途 subagent 发送 cancel（若平台支持 `cancel`）；记 Ledger `T<N>: interrupted by user (commits <base7>..<head7>, uncommitted: <files>)`。
+- 收到用户中断后：立即停止派发新 subagent；对在途 subagent 发送 cancel；记 Ledger `T<N>: interrupted by user (commits <base7>..<head7>, uncommitted: <files>)`。
 - **保留现场**：不删除产物目录，便于续跑或复盘。
 
 ## 回滚
 
-- implementer 提交有误：回滚限定在本任务 `BASE..HEAD`（BASE 从 Ledger `T<N>: base=` 读取）。**若工作树干净**可用 `git reset --hard <BASE>`；**若工作树脏**（含起始检查中用户选择保留的脏文件），禁止 `--hard`（会连同脏文件一起丢弃），改用 `git revert <task commits>` 或 `git reset --soft <BASE>` + 手动 checkout 目标文件。回滚后在 Ledger 记 `T<N>: reverted to <sha>`。
+- implementer 提交有误：回滚限定在本任务 `BASE..HEAD`（BASE 从 Ledger `T<N>: base=` 读取）。起始检查已保证工作树干净（用户已 commit/stash），不存在起始脏文件。**若工作树干净**可用 `git reset --hard <BASE>`；**若工作树脏**（任务执行期间产生），禁止 `--hard`（会连同脏文件一起丢弃），改用 `git revert <task commits>` 或 `git reset --soft <BASE>` + 手动 checkout 目标文件。回滚后在 Ledger 记 `T<N>: reverted to <sha>`。
 - **forbidden 文件被改**：reviewer 检测到 `writable` 白名单外的变更（含 `constraints` 禁改文件）→ 记 Critical finding，强制 `git checkout -- <file>` 恢复，并在 Ledger 记 `T<N>: reverted forbidden <file>`。
 - 回滚仅限本运行产生的提交，**绝不 `reset` 到早于 `initial_base`**。
 
 # 防失控护栏
 
-1. 并发分型：只读 `explore` 可并行 ≤5；可写 `general` 必须串行（同一轮最多 1 个），杜绝并发写冲突与 review diff 污染。
+1. 并发分型：只读 `work-explore` 可并行 ≤5；可写 `work-general` 必须串行（同一轮最多 1 个），杜绝并发写冲突与 review diff 污染。
 2. 每个 task 预算 ≤10 分钟；worker 失败先换模型/拆任务重试，仍失败则重规划失败部分（见「重规划」）。
 3. 每轮 fix 后必须 scoped re-review，未审查的 fix 是回归的来源。
 4. Round 5 后才裁决，每条裁决都是 Ledger 条目，禁止静默丢弃。
-5. 需要外部信息时用 `general` + `webfetch` 调研，不在子代理里嵌套再派发。
+5. 需要外部信息时用 `work-general` + `webfetch` 调研，不在子代理里嵌套再派发。

package/skills/work-review/SKILL.md

@@ -52,7 +52,7 @@ work agent 完成第四步派发、implementer 返回 `DONE` 或 `DONE_WITH_CONC
 
 ### 阶段 3：派发 reviewer
 
-按 `references/reviewer-prompt.md` 渲染两阶段审查 prompt（Spec Compliance + Code Quality），用 `task` 工具派发，`subagent_type` 取 `general`（需写入 REVIEW_FILE）。reviewer 写入 `<doc_dir>/task-<N>-review.md`。
+按 `references/reviewer-prompt.md` 渲染两阶段审查 prompt（Spec Compliance + Code Quality），用 `task` 工具派发，`subagent_type` 取 `work-general`（需写入 REVIEW_FILE）。reviewer 写入 `<doc_dir>/task-<N>-review.md`。
 
 ### 阶段 4：处理结论
 
@@ -80,7 +80,7 @@ work agent 完成第四步派发、implementer 返回 `DONE` 或 `DONE_WITH_CONC
 - reviewer 不重跑测试：信任 Ledger 记录的测试结果。
 - fix prompt 引用 review 文件路径，不内联 findings——compaction 后 findings 可能丢失，文件不会。
 - fix 轮次硬上限 5 轮；Breaker 绝不在 Round 5 前提前裁决（6.5 即时 ESCALATE/BLOCKED 是技术与边界问题，不属「提前裁决 finding 正确性」）。
-- 能力假设退化：若平台不支持 session 续接，每轮新 implementer；若不支持模型切换，退化为「新 implementer + 更详细 brief」，不许静默失效。
+- 能力假设退化：每轮新 implementer；不假定模型可切换，退化为「新 implementer + 更详细 brief」，不许静默失效。
 - 本技能只审查与 fix，不规划、不派发初次 implementer、不改源码。
 
 ## 资源目录

package/skills/work-review/references/fix-loop.md

@@ -6,14 +6,20 @@ Review 报告 Spec ❌、任何 Critical/Important finding、或你确认的 ⚠
 
 ## 6.2 Fix 轮次策略
 
-| 轮次 | 策略 | 理由 |
-|------|------|------|
-| Round 1-3 | 恢复原 implementer（传 session_ref） | context 完整，知道自己的代码和选择 |
-| Round 4-5 | 新 implementer + 更强模型 | fresh eyes + capability bump |
+| 轮次 | 正常策略 | 理由 |
+|------|----------|------|
+| Round 1-3 | 复用原 implementer session（传 `task_id` 续接） | context 完整，知道自己的代码和选择 |
+| Round 4-5 | 新 implementer + 更强模型（若平台支持模型切换） | fresh eyes + capability bump |
 
-**能力假设**（不符则退化，不许静默失效）：
-- 「传 `session_ref` 续接同一 subagent 会话」依赖平台 `task` 工具支持会话续接；若不支持，改为每轮**新 implementer**（附完整 brief + report + review 文件路径，prompt 自包含）。
-- 「更强模型」为可选项：若 `task` 调用支持指定模型则用之；否则退化为「新 implementer + 更详细 brief」，**不假定模型可切换**。
+**平台能力分支**（正常策略依赖平台能力；若缺失则退化，不许静默失效）：
+
+**正常策略**（平台能力完整时）：
+- Round 1-3：复用原 implementer session，传 `task_id` 续接（同一 session 内 context 完整）。
+- Round 4-5：新 implementer + 更强模型（若平台支持模型切换）。
+
+**退化策略**（平台能力不完整时，按缺失项退化）：
+- 若不支持 session 续接（`task_id` 不生效）：每轮新 implementer，附完整 brief + report + review 文件路径，prompt 自包含。
+- 若不支持模型切换：退化为「新 implementer + 更详细 brief」，Round 4-5 仍用新 implementer 但不切换模型。
 
 ### 每轮 fix 的 prompt
 
@@ -49,7 +55,7 @@ Review 报告 Spec ❌、任何 Critical/Important finding、或你确认的 ⚠
 
 每轮 fix 后，取 Ledger 中该任务**最后一条** `reviewed_head=` 的值作为 `FIX_BASE`，`HEAD` = 当前 HEAD，生成 scoped review package 到 `<doc_dir>/task-<N>-review-<fix_base7>..<head7>.diff`（结构同 5.1）。
 
-派发 re-reviewer（`subagent_type` 取 `general`；唯一写操作是 `<REREVIEW_FILE>`，不得改源码/add/commit）：
+派发 re-reviewer（`subagent_type` 取 `work-general`；唯一写操作是 `<REREVIEW_FILE>`，不得改源码/add/commit）：
 
 ```
 你是一个 scoped re-reviewer。验证上一轮 review 的 findings 是否被解决，检查 fix diff 是否引入新问题。
@@ -115,4 +121,3 @@ fix 过程中出现的非正常返回按以下状态表处理（不分轮次，
 - `FIX_BASE` 语义：取 Ledger 中该任务**最后一条** `reviewed_head=` 的值（不是初始 `base=`），保证 scoped re-review 只看 fix diff。
 - re-reviewer 工具调用上限 10 次；写白名单仅 `<REREVIEW_FILE>`。
 - fix prompt 引用 review 文件路径，不内联 findings。
-- 能力假设退化不许静默失效：不支持 session 续接 → 每轮新 implementer；不支持模型切换 → 退化「新 implementer + 更详细 brief」。

package/skills/work-review/references/reviewer-prompt.md

@@ -1,6 +1,6 @@
 # 5.2 派发 task reviewer
 
-使用 `task` 工具，`subagent_type` 取 `general`（reviewer 需写入 REVIEW_FILE，explore 无写工具）。**只读约束写在 prompt 里，不体现在工具权限**：唯一允许的写操作是写入 `<REVIEW_FILE>`，不得改源码、不得 add/commit。
+使用 `task` 工具，`subagent_type` 取 `work-general`（reviewer 需写入 REVIEW_FILE，explore 无写工具）。**只读约束写在 prompt 里，不体现在工具权限**：唯一允许的写操作是写入 `<REVIEW_FILE>`，不得改源码、不得 add/commit。
 
 ## prompt 结构
 

package/skills/work-review/references/verdict-handling.md

@@ -8,7 +8,7 @@
 |------|------|
 | **Spec ✅ + Approved** | 写 Ledger `T<N>: reviewed_head=<head7>`、`T<N>: complete (commits <base7>..<head7>, review clean)`，勾单，下一任务 |
 | **Spec ❌ 或有 Critical/Important** | 先写 Ledger `T<N>: reviewed_head=<head7>`，再进入 fix loop（第六步） |
-| **⚠️ Cannot verify from diff** | 你自己核查（你持有计划和跨任务上下文）；若核查需读文件超过 3 次，改为派 `explore` 子任务核查，避免污染 context |
+| **⚠️ Cannot verify from diff** | 你自己核查（你持有计划和跨任务上下文）；若核查需读文件超过 3 次，改为派 `work-explore` 子任务核查，避免污染 context |
 
 ## Minor findings