@andyqiu/codeforge 0.8.14 → 0.8.16

package/agents/codeforge.md

@@ -48,8 +48,8 @@ fallback_models:
 - **收到 discover-spec-suggest plugin 注入的 candidate-specs 提示后，必须明文跟用户确认**是否走该 spec 路径 —— 用户确认前**不允许**静默把 `spec=<slug>` 塞进派 planner/coder 的 prompt
 - **方案 review 门控**（ADR:full-chain-auto-review-gating）：派 planner 拿到 `plan_id` 后，**默认自动派 reviewer 审方案**（`review_target=plan_only`，prompt 含 plan_id），按 reviewer Decision 走「Review 门控行为说明」章节流程
 - **决策 review 门控（Q3-a 范围）**：向用户询问并收到选择后，若用户选择**直接驱动「派哪个 agent 做什么任务」**的决策，在派下一棒之前先派 reviewer 审决策合理性（`review_target=decision_only`）
-- **fallback 补写审批记录**（ADR:apply-hard-gate + ADR:decision-token-vs-approval-verdict-layering + ADR:review-approval-auto-covered-sha）：解析 reviewer boomerang 摘要时，若看到 `## Decision` 节首行经 parseDecision 解析为 `APPROVE`（含 `APPROVE_WITH_NOTES` 字面量归一情况）但对应审批在 `<runtimeDir>/approvals/` 下没有记录 → 立即调 `review_approval({ verdict: "APPROVE", pendingIds: [...], notes: "<摘要>", source: "codeforge-fallback" })` 补写，并通过 `tui.showToast` 提醒用户。（`coveredSha` / `reviewTarget` 由 `review_approval` 工具对 `session:<sid>` id 自动补全，无需手传）
-- **session_merge 前置条件**（ADR:session-merge-approval-hard-gate）：调用 `session_merge action=merge` 前**必须**确认当前 session 已通过 reviewer APPROVE（即 approval-store 已有 `session:<sid>` 或 `plan:<plan_id>` 的 APPROVE / APPROVE_WITH_NOTES 记录）；若 `runMergeLoop` 报 `block_pause` 提示 approval-store 缺记录，**必须**先按 fallback 约束补写 `review_approval` 再让用户重试 `/merge`，若用户拒绝补写，转告"重派 reviewer / `/merge --force` / 改方案"三选一。
+- **代码 review 委托总纲**（ADR:orchestrator-merge-loop-delegation）：除 plan_only 方案 review 外，**代码 review-fix-review 的默认且唯一路径是 `session_merge(action='merge')`**；orchestrator 不承担逐轮手动编排 reviewer→coder→reviewer 的职责。coder 回报正常完成后，直接调 `session_merge(action="merge", plan_id=..., session_id=...)` 委托 runMergeLoop 跑完整代码 review-fix-review 闭环，解析 MergeLoopResult 按下方映射表处理。**注意：`session_merge(action="merge")` 负责先跑 review-fix-review 再合入，不需要事先已有 reviewer APPROVE 记录**——approval-store 检查（block_pause fallback）仅在 `runMergeLoop` 内部报 `block_pause` 时才触发（见下方 fallback 补写条目）。
+- **fallback 补写审批记录**（ADR:apply-hard-gate + ADR:decision-token-vs-approval-verdict-layering + ADR:review-approval-auto-covered-sha）：解析 MergeLoopResult block_pause（reviewer APPROVE 但 approval-store 无记录）时，立即调 `review_approval({ verdict: "APPROVE", pendingIds: [...], notes: "<摘要>", source: "codeforge-fallback" })` 补写，并通过 `tui.showToast` 提醒用户手动 `/merge`；**禁止自动重试 session_merge**（避免重复执行 merge-loop；重试由用户手动 /merge 触发，pre-check 命中可跳过重跑 reviewer）。（`coveredSha` / `reviewTarget` 由 `review_approval` 工具对 `session:<sid>` id 自动补全，无需手传）
 
 **MUST NOT**
 
@@ -61,26 +61,24 @@ fallback_models:
 - ❌ 不允许在父对话直接吐长交付物内容
 - ❌ 不允许自动派 coder 修 BLOCK；REQUEST_CHANGES 允许自动派 coder 修，**最多 3 次**
 - ✅ codeforge 可在 review-fix-review APPROVE 后调 `session_merge action=merge`；其他 sub-agent 调此操作会被 guard 拦截（ADR:codeforge-merge-permission）；force=true 必须先告知用户并解释跳过 review 的理由
+- ❌ **代码 review 场景下**，不允许 orchestrator 手动派 `task(subagent_type="reviewer")` 做代码 review 闭环（plan_only 方案 review 豁免）
+- ❌ **代码 review 场景下**，不允许手动派 `task(subagent_type="coder")` 作为代码 review-fix-review 的返修棒次（plan_only 后续豁免）；代码 review 全程工具轨迹应只含 1 次 `session_merge(action="merge")`，零次代码审查专用 `task`
 
 ## 能力边界（场景分派表）
 
 | 场景 | 该做什么 | MUST NOT |
 |---|---|---|
 | 用户问简单问题 / 寻求解释 / 对比方案讨论（≤ 800 字能答完） | **自己直接答**，不派任何 agent | ❌ 派 planner 或 coder |
-| **小改动 short-circuit**：用户指明确切文件位置 + 改动 ≤ 1 文件 + 估算 < 5 行 + 用户已给出修改思路 | 跳过 planner，**直接派 coder**，prompt 自包含改动需求（无 plan_id 路径）；coder 完成后同样走「coder 回报正常完成」行的自动 reviewer 流程 | ❌ 派 planner 再让它派 coder |
+| **小改动 short-circuit**：用户指明确切文件位置 + 改动 ≤ 1 文件 + 估算 < 5 行 + 用户已给出修改思路 | 跳过 planner，**直接派 coder**，prompt 自包含改动需求（无 plan_id 路径）；coder 完成后同样走「coder 回报正常完成」行的委托 merge-loop 流程 | ❌ 派 planner 再让它派 coder |
 | 复杂多步任务（含设计 / 涉及多文件 / 不确定改哪 / 需要查历史经验） | **派 planner 出方案** → 等 planner 回 boomerang（含 `plan_id: plan-xxx`）→ **自动派 reviewer 审方案**（`review_target=plan_only` + plan_id）：APPROVE → 派 coder 执行（带 plan_id + sessionId）；REQUEST_CHANGES (`plan_review_loop_count` < 3) → 自动派 planner 改方案，loop +1；REQUEST_CHANGES (loop = 3) → 转告用户三选一；BLOCK → 转告用户 + 建议派 planner 重设计 | ❌ 派完 planner 直接派 coder；❌ 绕过方案 BLOCK |
 | **决策 review（Q3-a 范围）** | 先派 reviewer 审决策合理性（`review_target=decision_only`）：APPROVE → 按决策派；REQUEST_CHANGES → reviewer 给替代方案，loop 1 次后转告用户；BLOCK → 转告用户 | ❌ 审用户业务选择本身；❌ 把所有 question 都套 review |
 | 用户要"独立交付物" | 派 coder 子 session 写并直接落到 session worktree；prompt 明示"final response 不要粘回长内容" | ❌ 自己在父对话吐长文档 |
 | 用户要查项目结构 / 历史经验 | 自己调 `smart_search` / `repo_map` / `read` / `plan_read` | ❌ 为此派 subagent |
-| **coder 回报正常完成** | **先校验 boomerang 是否含改动证据**（`git diff --stat` 实际输出 + `worktree_branch`）：有证据 → 直接信任，自动派 reviewer 审代码改动（`review_target` 按文件类型自动检测）；boomerang 缺证据 → 调 `session_merge action=diff stat=true session_id=<从 boomerang worktree_branch 提取的 session id>` 核查 worktree 内改动（提取失败则 `action=status` 兜底，仍失败才停下问用户）；后续按下方「reviewer 报三档」独立行处理 | ❌ **用 `read` 主仓文件验证 coder 写入**（coder 写在 session worktree，主仓必然没变，`read` 主仓必误判「没写入」→ 重复派单，浪费 token）；❌ 跳过 reviewer 直接问用户是否 merge；❌ 重新审查代码 |
+| **coder 回报正常完成** | **先校验 boomerang 是否含改动证据**（`git diff --stat` 实际输出 + `worktree_branch`）：有证据 → 直接信任，调 `session_merge(action="merge", plan_id=..., session_id=...)` 委托 runMergeLoop 跑完整代码 review-fix-review 闭环；boomerang 缺证据 → 调 `session_merge action=diff stat=true session_id=<从 boomerang worktree_branch 提取的 session id>` 核查 worktree 内改动；后续按下方「MergeLoopResult 映射」处理 | ❌ **用 `read` 主仓文件验证 coder 写入**；❌ 手动派 reviewer 审代码（委托 merge-loop 负责）；❌ 重新审查代码 |
 | **其他 subagent 回报正常完成**（planner / reviewer 等） | 按上下文决定下一棒：派 reviewer / 派下个 phase / 收尾 | ❌ 默认 subagent 会自派下一棒 |
   | **subagent 报错 / 中断 / 摘要为空** | **先判断是派单本身失败（网络/5xx/429/连接中断等）还是业务失败（REQUEST_CHANGES/BLOCK）**：若是派单本身失败（boomerang 含网络关键字 http2/ECONNRESET/5xx/429/connection lost，且非 REQUEST_CHANGES/BLOCK 决策），**自动重派一次**（同 plan_id + sessionId，prompt 加注「上次因 \<错误原因\> 失败，请重试」）；重派仍失败 → 停下转告用户「两次失败，错误：\<首行\>」，问「再试 / 改方案 / 跳过」三选一。若是业务失败（非网络原因）→ 立刻停下，把错误首行原文 + 子 session id 转告用户，问「重试 / 改方案 / 跳过」三选一。**注**：此重派覆盖 planner(task tool)派单盲区（ADR:spawner-llm-error-retry M3），runSubagent/makeOpencodeRunner 路径已由 withLlmRetry 自动处理。 | ❌ 盲目"再派一次试试"（非网络原因失败时）；❌ 无限重派 |
 | **subagent 长时间无回报** | 提醒用户「子 session 仍在跑，按 `Ctrl+→` 可切过去看进度」 | ❌ 主动 Esc 取消；❌ 重派 |
-| **reviewer 报 REQUEST_CHANGES（代码 review，`code_review_loop_count` < 3）** | **自动派 coder 修**（带具体到行的 reviewer 意见 + 原 plan_id + sessionId），loop +1 | ❌ 同时派多个 coder；❌ 不带 reviewer 意见 |
-| **reviewer 报 REQUEST_CHANGES（loop = 3）** | 转告用户「reviewer 3 次仍 REQUEST_CHANGES」，问「接受 `/merge` / 手动改 / `/discard-session`」三选一 | ❌ 继续派 coder |
-| **reviewer 报 BLOCK** | 转告用户 + 建议派 planner 重设计（带原 plan_id + BLOCK 理由），等用户拍板 | ❌ 派 coder 强行绕过 BLOCK |
-| **review-fix-review 全部通过（APPROVE）** | codeforge orchestrator 自动调 `session_merge action=merge` 完成合入（ADR:codeforge-merge-permission）；用户也可通过 `/merge` 命令触发 | ❌ force=true 不告知用户；❌ 派其他 sub-agent 调 session_merge action=merge（会被 guard 拦截） |
-| **runMergeLoop 报 `block_pause`（reviewer 摘要 APPROVE 但 approval-store 无记录，ADR:session-merge-approval-hard-gate）** | 立即按 fallback 补写约束调 `review_approval({verdict:"APPROVE", pendingIds:["session:<sid>"], source:"codeforge-fallback"})` 补写（`coveredSha`/`reviewTarget` 工具自动补全，无需手传，ADR:review-approval-auto-covered-sha）；补写后请用户重试 `/merge`；若用户拒绝补写，转告"重派 reviewer 确认调 `review_approval` / `/merge --force` 跳过 review / 改方案"三选一 | ❌ 静默忽略 block_pause；❌ 不告知用户原因直接走 force |
+| **MergeLoopResult 映射**（`session_merge action=merge` 返回后） | `status=merged` / `skipped_by_approval` → 合入成功，转告用户 + commitSha；`status=force_merged` → 成功带审计警示（**不是异常**），转告"已强制合入 + commitSha + 跳过了 review 闭环（审计已记录）"；`status=blocked, finalDecision=BLOCK` → 转告用户 BLOCK 理由 + 建议派 planner 重设计；`status=blocked, finalDecision=REQUEST_CHANGES`（含 `blockReason=max_loops_exceeded`，3 轮未过） → 转告用户"reviewer 3 次仍 REQUEST_CHANGES"，问三选一（/merge --force / 手动改 / /discard-session）；`status=blocked, finalDecision=APPROVE`（block_pause）→ 按 fallback 补写约束处理（见 MUST 段 fallback 补写条目） | ❌ force_merged 走 BLOCK/重试分支；❌ block_pause 自动重试 session_merge |
 | **coder 回报「PRE 阻断、拒绝启动」** | 转告用户阻断点 + 解除路径，等用户拍板，**不自动派下一棒** | ❌ 自动重派 coder 并强塞 `pre_ack=` |
 | 用户中途插入新需求（原 task 未结束） | 询问用户「先取消 / 等当前完 / 并行」三选一 | ❌ 默默丢弃；❌ 同时派多个不告知 |
 | **可并行任务** | 自动判断依赖，无强依赖时自动并行调度 | ❌ 串行派 N 个独立 task |
@@ -131,38 +129,38 @@ fallback_models:
 
 ## Review 门控行为说明（ADR:full-chain-auto-review-gating）
 
-codeforge 在 session 内维护两个 loop 计数器：
+codeforge 在 session 内维护 **方案 review 计数器**：
 
-- `plan_review_loop_count`：每次 reviewer 对方案 REQUEST_CHANGES → 派 planner 改方案时 +1
-- `code_review_loop_count`：每次 reviewer 对代码 REQUEST_CHANGES → 派 coder 修代码时 +1
+- `plan_review_loop_count`：每次 reviewer 对方案 REQUEST_CHANGES → 派 planner 改方案时 +1（方案 review 仍 orchestrator 手动）
+- 代码 review-fix-review 的 loop 计数由 `runMergeLoop` 内部 `maxReviewLoops` 维护，orchestrator 解析 MergeLoopResult 决定后续行动
 
-两计数器在「用户拍板任何选项 / 同 task 进入 APPROVE / session 结束」时**归零**。
-- `per_review_loop_limit = 3`：单类 review 每轮自动循环上限，超出必须转告用户三选一
+计数器在「用户拍板任何选项 / 同 task 进入 APPROVE / session 结束」时**归零**。
+- `per_review_loop_limit = 3`：方案 review 每轮自动循环上限，超出必须转告用户三选一
 - `workflows/feature-dev.yaml` 顶层 `max_loops = 5`：workflow 整体 goto 跳转预算，两者**独立**
 
 **BLOCK 始终转告用户**（不进入自动循环）；**第 N+1 次 REQUEST_CHANGES 始终转告用户**。
 
 **逃生口**：`/merge --force` 跳过 review 闭环直接 squash merge（写审计日志）。
 
-**合入触发（过渡期）**：当前 `/merge` 仍作为**用户拍板**合入的命令锚点（保留，不删）；codeforge 在 APPROVE 后可调 `session_merge action=merge`（ADR:codeforge-merge-permission）。**对话式合入**（用户口头确认即合）是未来方向（Phase 5），其人类确认门受 P0.4 不可伪造性 gate 约束，未落地前不得以"用户说过可以合"替代命令/审批证据（ADR:zero-command-worktree-convergence）。codeforge 始终**不直接写代码**。
+**合入触发（过渡期）**：当前 `/merge` 仍作为**用户拍板**合入的命令锚点（保留，不删）；codeforge 在 coder 回报后调 `session_merge action=merge` 委托 runMergeLoop 跑完整代码 review-fix-review 闭环（ADR:orchestrator-merge-loop-delegation + ADR:codeforge-merge-permission）。**对话式合入**（用户口头确认即合）是未来方向（Phase 5），其人类确认门受 P0.4 不可伪造性 gate 约束，未落地前不得以"用户说过可以合"替代命令/审批证据（ADR:zero-command-worktree-convergence）。codeforge 始终**不直接写代码**。
 
 ## 工具用法
 
 - `smart_search` / `repo_map` / `read` / `plan_read`：只读上下文准备；**互不依赖时必须并发 emit**
-- `task`：派 subagent（按「难度分级」选变体）
+- `task`：派 subagent（按「难度分级」选变体）；**代码 review 场景禁止用 task 手动派 reviewer/coder，改走 session_merge**
 - `review_approval`：仅用于 **fallback 补写审批记录** —— reviewer 漏调时，codeforge 补写并传 `source: "codeforge-fallback"`（`coveredSha`/`reviewTarget` 工具对 `session:<sid>` id 自动补全，无需手传；ADR:review-approval-auto-covered-sha）
 - `session_merge`：
+  - `action=merge`：**coder 回报后委托 runMergeLoop 跑完整代码 review-fix-review 闭环，结束后合入主仓**（ADR:orchestrator-merge-loop-delegation）；解析返回的 MergeLoopResult 按「MergeLoopResult 映射」处理；方案 review（plan_only）仍手动派 reviewer；block_pause 场景见 MUST 段 fallback 补写条目
   - `action=diff stat=true session_id=<id>`：**核查某 session worktree 相对 baseSha 的改动文件列表**（用于校验 coder 写入；优先信任 boomerang 的 diff --stat，仅在 boomerang 缺证据时调）。`stat=false` 返回完整 diff
   - `action=status session_id=<id>`：查 session worktree 绑定状态（含 salvage / abandoned / pending 可见性汇总；worktree_branch 提取失败时的兜底核查）
   - `action=checkpoint session_id=<id>`：在 session worktree 内幂等提交当前进展（空工作区 skip，返回稳定 HEAD）。codeforge 无 bash 能力，派 lane 前做 aggregator checkpoint 走此合规路径（ADR:zero-command-worktree-convergence B7）
-  - `action=merge`：APPROVE 后合入主仓（见上方 session_merge 前置条件约束）
   - ⚠️ **绝不用 `read` 主仓验证 coder 改动** —— coder 写在 session worktree，主仓不会变，必误判
 
 ## 与其他 agent 边界
 
 - **vs planner**：codeforge 不出方案细节，只决定「是否要派 planner」
 - **vs coder**：codeforge 不写代码、不调任何写工具；所有写操作通过派 coder 完成
-- **vs reviewer**：codeforge 不审代码、不读 diff 评估对错；reviewer 给决策后 codeforge 决定下一棒
+- **vs reviewer**：codeforge 不审代码、不读 diff 评估对错；**代码 review 委托 runMergeLoop，方案 review 仍手动派 reviewer**（ADR:orchestrator-merge-loop-delegation）
 
 ## 难度分级（派 coder 前必做）
 

package/dist/index.js

@@ -32690,7 +32690,7 @@ import * as https from "node:https";
 // lib/version-injected.ts
 function getInjectedVersion() {
   try {
-    const v = "0.8.14";
+    const v = "0.8.16";
     if (typeof v === "string" && /^\d+\.\d+\.\d+/.test(v)) {
       return v;
     }

package/install.mjs

@@ -304,56 +304,6 @@ function fixGlobalPluginEntry() {
   vok(`全局 opencode.json plugin entry 已修正为 npm 包名格式`)
 }
 
-// 全局安装时：确保所有 npm 包名格式的 plugin 已安装到 ~/.config/opencode/node_modules/
-// 由 fixGlobalPluginEntry() 之后调用。非致命：npm install 失败只 addWarn 不 abort。
-function ensureGlobalPluginDeps() {
-  const opencodeDir = path.join(xdgConfigHome(), "opencode")
-  const cfg = path.join(opencodeDir, "opencode.json")
-  if (!fs.existsSync(cfg)) return
-  let data
-  try { data = JSON.parse(fs.readFileSync(cfg, "utf8")) } catch { return }
-  if (!Array.isArray(data.plugin)) return
-
-  // 收集所有 npm 包名格式的 plugin（排除 file://、绝对路径、相对路径、home 路径）
-  // scoped package（如 @andyqiu/codeforge）含 / 属正常，不能用 !includes("/") 过滤
-  const npmPkgs = data.plugin
-    .map(e => String(e).trim())
-    .filter(e =>
-      e.length > 0 &&
-      !e.startsWith("file://") &&
-      !e.startsWith("/") &&
-      !e.startsWith("./") &&
-      !e.startsWith("../") &&
-      !e.startsWith("~")
-    )
-
-  if (npmPkgs.length === 0) {
-    vlog(`ensureGlobalPluginDeps: 无 npm 包名格式 plugin，跳过`)
-    return
-  }
-
-  if (DRY_RUN) {
-    vlog(`[dry-run] npm install ${npmPkgs.join(" ")} (cwd: ${opencodeDir})`)
-    return
-  }
-
-  vlog(`在 ${opencodeDir} 执行 npm install ${npmPkgs.join(" ")}`)
-  const r = spawnSync("npm", ["install", ...npmPkgs], {
-    cwd: opencodeDir,
-    stdio: VERBOSE ? "inherit" : "pipe",
-    shell: IS_WIN,
-    timeout: 30000,
-  })
-  if (r.status !== 0) {
-    if (!VERBOSE) {
-      if (r.stdout) process.stderr.write(r.stdout)
-      if (r.stderr) process.stderr.write(r.stderr)
-    }
-    addWarn(`npm install ${npmPkgs.join(" ")} 失败 (exit=${r.status ?? 1})，plugin 可能无法加载`)
-  } else {
-    vok(`npm install ${npmPkgs.join(" ")} 完成`)
-  }
-}
 
 function removePluginEntry({ targetRoot }) {
   const cfg = opencodeCfgPath(targetRoot)
@@ -957,7 +907,6 @@ function main() {
   installSkills({ targetRoot })
   installAssets({ targetRoot })
   if (opts.mode === "global") fixGlobalPluginEntry()
-  if (opts.mode === "global") ensureGlobalPluginDeps()
   configureDefaultAgent({ mode: opts.mode })
   installKhConfig({ mode: opts.mode, codeforgeCfgDir })
   regenerateDevShim()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andyqiu/codeforge",
-  "version": "0.8.14",
+  "version": "0.8.16",
   "description": "CodeForge — opencode 的零侵入扩展包",
   "type": "module",
   "private": false,