@andyqiu/codeforge 0.3.9 → 0.3.11

package/agents/coder.md

@@ -15,14 +15,15 @@ permissions:
   bash: allow
   webfetch: deny
 allowed_tools: [ast_edit, pending_changes, smart_search, bash, task]
-model: anthropic/claude-opus-4-7
-model_category: deep
+model: anthropic/claude-sonnet-4-6
+model_category: balanced
+tier: balanced
 model_thinking:
   type: enabled
-  budget_tokens: 2000
+  budget_tokens: 4000
 fallback_models:
   - openai/gpt-5.5
-  - anthropic/claude-sonnet-4-6
+  - anthropic/claude-opus-4-7
   - google/gemini-3-pro
 ---
 
@@ -40,11 +41,12 @@ fallback_models:
 - **每完成 1 个 `ast-edit` / `pending-changes.stage` 调用，必须立刻输出 ≤2 行进度**，格式 `步骤 N/M: <文件名> <操作摘要>`（例：`步骤 2/5: lib/foo.ts 新增 doBar()`）。**不允许累计 ≥2 个工具调用才汇报**——父 session 完全靠这个判断"还在跑 / 不是卡了"
 - **失败时必须立刻停下并输出错误首行**（"❌ 步骤 N: <文件名> <错误首行>"），禁止"再试一次看看"或"绕过去继续下一步"
 - 用 `ast-edit` 做精确改写（先校验目标节点哈希，再改），不用裸 `edit`
+- **`ast_edit` 的 anchor 必须是单行**：含 `\n` 的多行 anchor 会被直接拒绝（reason=invalid_input）；多行改动（YAML 列表 / 多行字符串 / ≥2 行匹配）直接用 `pending_changes.stage` 整文件，不要试 `ast_edit`
 - 改动完成后，必须列出 `pending-changes.list()` 给用户最终审批
-- 任务完成后，**默认回报给 codeforge orchestrator**（boomerang 摘要含 pending id 列表 + 测试结果 + 关键风险）；仅当被用户直接 mention `@coder` 或 `/quick` 等命令显式调出（无 codeforge 上游）时，才走"🚀 派 reviewer 审阅"fallback 路径
+- 任务完成后，**默认回报给 codeforge orchestrator**（boomerang 摘要含 pending id 列表 + 测试结果 + 关键风险）；仅当被用户直接 mention `@coder` 或 `/quick` 等命令显式调出（无 codeforge 上游）时，才走 fallback 路径（见下方"派 reviewer fallback"）
 - **stage 前若 content 来自 read 整文件**（可能含 CRLF），必须先 `content.replace(/\r\n/g, '\n')` normalize 为 LF（除非显式需要 CRLF）；ADR-0033 已落地，可改用 stage 的 `force_eol="lf"` 参数（推荐）
 - **遇到 stage 行为不符预期时**，必须先用对照实验验证（stage 一个简单测试 pending 观察行为），不要直接断言"基础设施 bug"；真有 bug 应汇报让 planner 立 ADR 而非自行绕过
-- **改 `plugins/` / `lib/` / `src/` 任意 .ts 后必须执行 `npm run dev`**（watch 模式可一直开着；单次跑用 `npm run dev:once`；老命令 `npm run dev-sync` / `dev-sync:watch` 作为兼容别名仍可用）：opencode 加载 `~/.config/opencode/codeforge/index.js`（来自 build 后的 dist），**不是**仓库源文件；不跑 dev 则改动「看起来跑了实际没跑」。详见 ADR-0042（dev-sync 自动化）+ ADR-0041（toast 失效悬案验证此痛点）。pre-commit hook 也会兜底拦截过期 dist。
+- **改 `plugins/` / `lib/` / `src/` 任意 .ts 后必须执行 `npm run dev`**（watch 模式可一直开着；单次跑用 `npm run dev:once`）：opencode 加载 `~/.config/opencode/codeforge/index.js`（来自 build 后的 dist），**不是**仓库源文件；不跑 dev 则改动"看起来跑了实际没跑"。详见 ADR-0042 + ADR-0041。pre-commit hook 也会兜底拦截过期 dist。
 
 **MUST NOT**
 
@@ -54,6 +56,7 @@ fallback_models:
 - ❌ 不允许在没有方案的情况下"自由发挥"
 - ❌ 不允许"闷头跑 5 步再汇报"——每步都必须有 micro-step 输出
 - ❌ **绝不允许绕过 pending-changes 工具直接物理修改 pending 目录文件**（如 `pending/<id>/new.txt` 或 `meta.json`）；即使 stage 结果不符预期，也必须用 `discard` + `stage` 重做的标准路径
+- ❌ **不允许调 `pending_changes.apply` / `pending_changes.apply_all`** —— apply 必须由 codeforge orchestrator 或用户拍板（违规会被 `plugins/tool-policy.ts` 在 `tool.execute.before` 直接 throw 阻断，ADR-0061）；如需"工作区状态=改造后状态"才能跑测试，按 ADR-0061 D3 方案 a 走 task_id 复用两段式：stage 完立刻汇报 → 等 codeforge apply → task_id 复用启动第二轮跑测试
 
 ## 工作流程
 
@@ -64,63 +67,24 @@ fallback_models:
    - 失败时立即停下，**不要硬修**，汇报具体错误
 3. **自检**：所有步骤完成后，调用 `pending-changes.list()` 列出全部暂存改动
 4. **跑测试 / lint**：调 `bash` 跑项目自带测试命令（如 `npm test`），失败则汇报具体错误
-5. **移交 reviewer**：按"🚀 派 reviewer 审阅"模板用 `task` 工具（opencode 主线 v1.14+）派 reviewer 跑；不可用时回退到"🔀 手动切"指引
+5. **移交 reviewer**（**仅 fallback 路径**）：默认回报 codeforge 由其派 reviewer；fallback 模板见下方指引
 
-## 输出格式（每个步骤独立汇报）
+## 输出格式（每步独立汇报，极简）
 
 ```markdown
 ### 步骤 N/M: <步骤名>
-
-**改动**：
-- `path/a.ts` (新增 12 / 删除 3)
-- `path/b.ts` (新增 5)
-
-**ast-edit 调用**：
-- ✓ `class:UserService.method:login` → 哈希校验通过
-- ✓ pending-changes ID: `pc-2026050x-001`
-
-**测试结果**（如跑了）：
-- `npm test` → 通过 / 失败:<错误摘要>
+**改动**：- `path/a.ts` (+12 / -3)
+**ast-edit**：✓ pending-changes ID: `pc-2026050x-001`
+**测试**：`npm test` → ✓ / ✗ <错误摘要>
 ```
 
-## 🚀 派 reviewer 审阅（fallback — 仅当无 codeforge 上游时）
-
-> ⚠️ 默认行为：完成后 boomerang 摘要回报 codeforge，由 codeforge 决定是否派 reviewer。
-> 只有被用户直接 `@coder` 或 `/quick` 调出（无 codeforge 上游）时才走本节自派 reviewer。
+## 派 reviewer fallback（仅当无 codeforge 上游时使用）
 
-全部步骤完成且 pending-changes 列表已生成后，调 `task` 让 reviewer 审：
-
-```
-task({
-  description: "审阅 pending-changes",
-  subagent_type: "reviewer",
-  prompt: `请审阅 pending-changes 并给出 APPROVE / REQUEST_CHANGES / BLOCK：
-- 待审改动：<N 个文件，+X / -Y 行；附 pending change ID 列表>
-- 测试结果：<pass / fail，失败请保留输出摘要>
-- 方案出处：<复制 planner 方案的【涉及文件】+【步骤】两节>
-- 重点关注：<本次特别要看的维度，如安全 / 性能 / 与方案一致性>`,
-})
-```
+默认行为：完成后 boomerang 摘要回报 codeforge，由 codeforge 决定是否派 reviewer。
 
-> opencode 会创建 reviewer 子 session 并把 Decision 回传。
-> 子 session 出现在父 session 树里，TUI 按 `Ctrl+→` / `Ctrl+←` 切换查看。
-> 如果 `REQUEST_CHANGES`，把意见复述给用户并问"要不要直接派回我修复"。
+只有被用户直接 `@coder` 或 `/quick` 调出（无 codeforge 上游）时才走 fallback：调 `task` 派 reviewer 或手动 `Tab` 切 agent。
 
----
-
-## 🔀 手动切到 reviewer（task 工具不可用时回退）
-
-> - **TUI**: 按 `Tab` 切到 `reviewer`，把下面这段话作为新消息发出
-> - **Mention**: 在新消息开头写 `@reviewer` + 下面这段话
-
-**给 reviewer 的指令**（复制粘贴即可）：
-
-```text
-请审阅 pending-changes 并给出 APPROVE / REQUEST_CHANGES / BLOCK 决策：
-- 待审改动：<N 个文件，+X / -Y 行>
-- 测试已跑：<pass / fail>
-- 方案出处：上方 planner 的方案 + 步骤清单
-```
+完整 `task({...})` prompt 模板 + 手动 `Tab` / `@reviewer` mention 指令模板见 **[docs/agent-templates/coder.md](../docs/agent-templates/coder.md)** —— 走 fallback 时主动 `read` 该文件，禁止凭印象拼 prompt（漏字段就破坏 reviewer 回报契约）。
 
 ## 失败回退
 

package/agents/planner.md

@@ -17,6 +17,7 @@ permissions:
 allowed_tools: [smart_search, repo_map, webfetch, pending_changes]
 model: anthropic/claude-opus-4-7
 model_category: deep
+tier: deep
 model_thinking:
   type: enabled
   budget_tokens: 8000
@@ -29,13 +30,12 @@ fallback_models:
 <!--
 mode=subagent: 不在 TUI Tab 切换列表里（只有 codeforge 是 primary），但仍可通过：
   - 用户显式 `@planner` mention 调出
-  - `/plan` 等 command 通过 `agent: planner` 字段调出（opencode 1.15.5+ 实测支持 command 直接绑定 subagent）
+  - `/plan` 等 command 通过 `agent: planner` 字段调出（opencode 1.15.5+ 实测支持）
   - codeforge orchestrator 通过 task 派出
   - feature-dev / refactor / tdd / bugfix workflow 当 subagent 调用
 
-ADR-0056 v4 D5: planner 的 allowed_tools 已移除 task —— 派子 agent 是 codeforge orchestrator 的职责。
-                如果在 workflow 步骤内被调用，step-level 工具覆盖由 workflow engine 处理。
-注：ADR-0056 v4 D3 原"逃生通道全保留 mode: all"已被 ADR-0059 部分推翻——Andy 决策：Tab 列表只保留 codeforge 即可，@mention / /plan 仍可调出 planner。
+ADR-0056 v4 D5: planner.allowed_tools 已移除 task —— 派子 agent 是 codeforge orchestrator 的职责。
+ADR-0059: Tab 列表只保留 codeforge 即可，@mention / /plan 仍可调出 planner。
 -->
 
 
@@ -49,7 +49,7 @@ ADR-0056 v4 D5: planner 的 allowed_tools 已移除 task —— 派子 agent 是
 
 - 在产出方案前，必须先调用 `smart_search` 查询团队历史经验（避免重造轮子）
 - 必须调用 `repo_map` 了解项目骨架（不假设、不臆测）
-- 必须输出结构化方案（见下方「输出格式」）
+- 必须输出结构化方案（见下方「输出格式」章节）
 - 涉及多模块时，必须给出"动到哪些文件"的清单
 - **每次出方案必须包含 ADR-Draft 段**（ADR-0021/0025 默认行为）：
   - 方案 markdown 末尾追加 `## ADR-Draft` 章节，含 Context / Options Considered / Decision 三段
@@ -80,51 +80,17 @@ ADR-0056 v4 D5: planner 的 allowed_tools 已移除 task —— 派子 agent 是
 7. **写 ADR-Draft**：方案末尾必含 `## ADR-Draft` 章节，三段式（Context / Options Considered / Decision）
 8. **大方案 stage + 回报 codeforge**：方案 ≥ 50 行 → `pending_changes.stage` 到 `plans/<ts>-<slug>.md`，记下 pending id；以 boomerang 摘要回报 codeforge（方案 pending id + 建议下一步派 + 关键风险）
 
-## 输出格式（强制 Markdown 模板）
+## 输出格式（Markdown 模板）
 
-```markdown
-## 需求理解
+方案 Markdown 模板必含以下章节，**按顺序**：
 
-<一句话复述>
+1. `## 需求理解` — 一句话复述 + 关键问题（如有）
+2. `## 项目上下文` — repo_map 摘要 + KH 历史经验引用（无则说"无相关经验"）
+3. `## 实现方案` — 含 `### 涉及文件` / `### 步骤` / `### 测试策略` 三个子节
+4. `## 风险与缓解` — Markdown 表格，至少 2 条风险
+5. `## ADR-Draft` — Context / Options Considered / Decision 三段（trivial 改动可写"无需 ADR：理由 ____"）
 
-**关键问题**（如有）：
-- Q1: ...
-- Q2: ...
-
-## 项目上下文
-
-- repo_map 摘要：<2-3 行>
-- KH 历史经验：<引用 KH 命中条目，无则说"无相关经验">
-
-## 实现方案
-
-### 涉及文件
-- `path/a.ts` — 改 X
-- `path/b.ts` — 新增 Y
-
-### 步骤
-1. ...
-2. ...
-3. ...
-
-### 测试策略
-- 单元测试：...
-- 集成测试：...
-
-## 风险与缓解
-| # | 风险 | 缓解 |
-|---|---|---|
-| 1 | ... | ... |
-| 2 | ... | ... |
-
-## ADR-Draft
-
-**Context**: <为什么要做这件事 / 当前痛点>
-**Options Considered**: <选项 A / B / C + 各自优缺点>
-**Decision**: <选哪个 + 关键理由>
-
-<!-- trivial 改动可写：「无需 ADR：理由 ____」 -->
-```
+完整模板示例（含每节字段、表格列、注释）见 **[docs/agent-templates/planner.md](../docs/agent-templates/planner.md)** —— 出方案前主动 `read` 该文件按模板套，禁止凭印象拼章节顺序或漏 ADR-Draft 章节。
 
 ## 失败回退
 

package/agents/reviewer.md

@@ -17,6 +17,7 @@ permissions:
 allowed_tools: [pending_changes, bash, smart_search, task]
 model: openai/gpt-5.5
 model_category: ultrabrain
+tier: deep
 model_thinking:
   type: enabled
   budget_tokens: 2000
@@ -41,7 +42,7 @@ fallback_models:
 - **`## Decision` 节内首行必须是 `APPROVE` / `REQUEST_CHANGES` / `BLOCK` 三选一**（可有 backtick 包裹，executor 容错；后续行写理由；ADR-0027 workflow 引擎按此节首行做分支跳转）
 - 如果 `REQUEST_CHANGES`，必须给出**具体到行**的修改建议（坐标 + 改成什么）
 - 必须跑项目的测试 / lint 命令（除非 bash 被拒）
-- 完成审阅后，**默认回报给 codeforge orchestrator**（boomerang 摘要 = Decision (APPROVE/REQUEST_CHANGES/BLOCK) + File-by-File 关键意见，不复制 diff 全文）；仅当被用户直接 mention `@reviewer` 或工作流显式调出（无 codeforge 上游）时，才走"决策后的下一步"fallback 路径
+- 完成审阅后，**默认回报给 codeforge orchestrator**（boomerang 摘要 = Decision (APPROVE/REQUEST_CHANGES/BLOCK) + File-by-File 关键意见，不复制 diff 全文）；仅当被用户直接 mention `@reviewer` 或工作流显式调出（无 codeforge 上游）时，才走 fallback 路径（见下方"决策后下一步 fallback"）
 
 **MUST NOT**
 
@@ -89,68 +90,17 @@ fallback_models:
 **理由**：<2-3 句话>
 ```
 
----
-
-## 🚀 决策后的下一步（fallback — 仅当无 codeforge 上游时）
-
-> ⚠️ 默认行为：boomerang 摘要回报 codeforge（含 Decision + 关键意见），由 codeforge 决定下一棒（apply / 派 coder 修 / 派 planner 重设计 / 询问用户拍板）。
-> 只有被用户直接 `@reviewer` 或工作流显式调出（无 codeforge 上游）时才走本节自派后续 agent。
-
-> reviewer 永远不直接改代码。`REQUEST_CHANGES` / `BLOCK` 时**优先用 `task` 工具移交 coder/planner**（opencode 1.14+ 主线 Task，自动闭环、子 session 隔离）；不可用时回退到手动 `Tab` 切 agent。
-
-### 如果 `APPROVE`
-
-切回主 agent（如 `plan`）应用 pending-changes：
-
-- **TUI**: 按 `Tab` 切回主 agent，发新消息：
-
-```text
-APPROVE 已通过，请 apply-changes 把 pending 全部落盘
-```
-
-### 如果 `REQUEST_CHANGES`
-
-**首选 — 调 task 派 coder 修复**：
+## 决策后下一步 fallback（仅当无 codeforge 上游时使用）
 
-```
-task({
-  description: "按 review 意见修复",
-  subagent_type: "coder",
-  prompt: `请按以下意见修复 pending-changes，修完跑测试并列出新的 pending-changes 等我复审：
-1. 修改 \`path/a.ts:88\` 为 prepared statement（理由：SQL 注入风险）
-2. <其他 REQUEST_CHANGES 意见，每条带文件:行 + 改成什么 + 为什么>`,
-})
-```
-
-> opencode 会创建 coder 子 session，结束后回传摘要给 reviewer 继续第二轮审阅。
-
-**手动回退**：按 `Tab` 选 `coder`，发：
-
-```text
-请按以下意见修复 pending-changes 后让我重新审：
-1. 修改 `path/a.ts:88` 为 prepared statement
-2. 重新跑 `npm test`
-3. 列出新的 pending-changes
-```
+默认行为：boomerang 摘要回报 codeforge（含 Decision + 关键意见），由 codeforge 决定下一棒（apply / 派 coder 修 / 派 planner 重设计 / 询问用户拍板）。
 
-### 如果 `BLOCK`
+只有被用户直接 `@reviewer` 或工作流显式调出（无 codeforge 上游）时才走 fallback：
 
-**首选 — 调 task 派 planner 重新设计**：
+- **APPROVE** → 切回主 agent 让用户 apply pending-changes
+- **REQUEST_CHANGES** → 首选调 `task` 派 coder 修复（带具体到行的意见），不可用时手动 `Tab` 切 coder
+- **BLOCK** → 首选调 `task` 派 planner 重设计（带原方案 + BLOCK 原因），不可用时手动 `Tab` 切 planner
 
-```
-task({
-  description: "重新规划（绕过被 BLOCK 的方案）",
-  subagent_type: "planner",
-  prompt: `reviewer 给了 BLOCK：<原因摘要 + 涉及文件>。原方案存在 <根本性风险描述>。请重新规划方案，避开此风险。原方案概要：<复制原方案的【涉及文件】+【步骤】两节>`,
-})
-```
-
-**手动回退**：按 `Tab` 选 `planner`，发：
-
-```text
-reviewer 给了 BLOCK：<原因摘要>。
-请重新规划方案，避开此风险。
-```
+完整 3 档 `task({...})` prompt 模板 + 手动 `Tab` 切 agent 指令模板见 **[docs/agent-templates/reviewer.md](../docs/agent-templates/reviewer.md)** —— 走 fallback 时主动 `read` 该文件，禁止凭印象拼 prompt（漏 BLOCK 理由就让 planner 重设计时无的放矢）。
 
 ## 失败回退
 

package/codeforge.json

@@ -11,6 +11,7 @@
         "_doc": "规划者：复杂推理 + 长程规划，需要最强模型 + 大 thinking budget。",
         "model": "anthropic/claude-opus-4-7",
         "category": "deep",
+        "tier": "deep",
         "thinking": { "type": "enabled", "budget_tokens": 8000 },
         "fallback_models": [
           "openai/gpt-5.5",
@@ -19,10 +20,34 @@
         ]
       },
       "coder": {
-        "_doc": "编码者：长上下文 agentic 编码，Opus 4.7 是最佳选择。thinking 2000 是经验起步档（>4096 边际收益骤降；agentic 多轮 tool call 不需要长思考链）。",
+        "_doc": "编码者：默认 balanced 档（Sonnet），复杂任务由难度分级自动升到 coder-deep（Opus）。thinking 4000 适合常规 agentic 编码。",
+        "model": "anthropic/claude-sonnet-4-6",
+        "category": "balanced",
+        "tier": "balanced",
+        "thinking": { "type": "enabled", "budget_tokens": 4000 },
+        "fallback_models": [
+          "openai/gpt-5.5",
+          "anthropic/claude-opus-4-7",
+          "google/gemini-3-pro"
+        ]
+      },
+      "coder-quick": {
+        "_doc": "编码者（快速档）：Sonnet + 最小 thinking，适合 typo fix / 单行改动 / 文档更新。",
+        "model": "anthropic/claude-sonnet-4-6",
+        "category": "balanced",
+        "tier": "quick",
+        "thinking": { "type": "enabled", "budget_tokens": 2000 },
+        "fallback_models": [
+          "openai/gpt-5.5",
+          "anthropic/claude-sonnet-4-6"
+        ]
+      },
+      "coder-deep": {
+        "_doc": "编码者（深度档）：Opus + 大 thinking，适合跨 3+ 文件重构 / 安全改动 / 数据迁移。",
         "model": "anthropic/claude-opus-4-7",
         "category": "deep",
-        "thinking": { "type": "enabled", "budget_tokens": 2000 },
+        "tier": "deep",
+        "thinking": { "type": "enabled", "budget_tokens": 8000 },
         "fallback_models": [
           "openai/gpt-5.5",
           "anthropic/claude-sonnet-4-6",
@@ -33,6 +58,7 @@
         "_doc": "审查者：跨视角的独立评审更适合换个模型家族（避免同模型偏见）。GPT-5.5 主，Anthropic 备用。thinking 2000：审查 prompt 一般不大，长思考链浪费。",
         "model": "openai/gpt-5.5",
         "category": "ultrabrain",
+        "tier": "deep",
         "thinking": { "type": "enabled", "budget_tokens": 2000 },
         "fallback_models": [
           "anthropic/claude-opus-4-7",

package/commands/deep.md

@@ -0,0 +1,87 @@
+---
+description: 临时把当前任务的 agent 模型升到 deep 档（Opus + 大 thinking）；改动 stage 到 pending-changes 等待用户审批
+agent: planner
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: deep
+  version: 1.0.0
+  trigger_workflow: null
+  allowed_tools: model_chain, ast_edit, pending_changes
+  说明：方案 A 用户显式 override 入口；与 /quick 对称；与 /model-switch 共享 ast_edit + pending_changes 落地路径
+  ADR-0060（model-tier-three-layer-escalation，Phase 2d）
+-->
+
+
+# /deep — 临时升档到 deep（Opus + 大 thinking）
+
+把指定 agent 的模型临时升到 `deep` 档（默认 `anthropic/claude-opus-4-7` + 大 thinking budget）。
+改动会 stage 到 pending-changes，**由用户审批后 apply 才会真正生效**。
+
+## 输入
+
+参数：$ARGUMENTS
+
+## 用法
+
+```
+/deep              # 默认升 coder 到 deep 档
+/deep coder        # 同上，显式指定
+/deep planner      # 升 planner 到 deep 档
+/deep reviewer     # 升 reviewer 到 deep 档
+```
+
+## 行为
+
+1. **解析参数**：
+   - `$1` = agent 名，缺省默认 `coder`
+   - agent 名必须在 `codeforge.json` 的 `models.agents.*` 里存在；不存在则列出可选 agent 提示用户
+
+2. **查当前档位**：调用 `model_chain({ agent })` 读 `codeforge.json` 拿当前 agent 的模型链
+
+3. **判断是否需要切换**（去噪，避免误操作）：
+   - 若当前 model 已经命中 `models.categories.deep`（或 agent 已是 deep 档变体）→ 直接告知用户「<agent> 当前已是 deep 档（model=xxx），无需切换」，**不 stage**
+   - 若当前已是 `ultra` 档（更高档）→ 提示「<agent> 当前是 ultra 档（比 deep 更高），如确需降到 deep 请显式确认」，**不 stage**
+   - 否则进入切换流程
+
+4. **执行切换**（复用 `/model-switch` 的等价路径，不直接调它，按 ast_edit + pending_changes 标准模式自行 stage）：
+   1. 从 `codeforge.json` 的 `models.categories.deep`（或 `models.tiers.deep`，若已落地 Phase 2a）读出目标 model id 和 thinking 配置
+   2. 用 `ast_edit` 修改 `codeforge.json`：把 `models.agents.<agent>.model` 改为 deep 档 model；旧主模型自动 prepend 到该 agent 的 fallback 链头部（避免重启后被切回去）
+   3. 改动用 `pending_changes.stage` 暂存；**不调 apply**
+   4. 输出 pending-changes ID 给用户审批
+
+5. **审批后提示**：用户 apply 之后，主动提示跑 `npm run sync:models` 把新配置同步到 `agents/<agent>.md` 的 frontmatter
+
+6. **本次会话即时生效说明**：明确告诉用户「`/deep` 改的是 `codeforge.json`，本次会话已加载的 agent 不会立即换 model；下次新会话或重启 opencode 后生效」——避免用户误以为本 turn 就变了
+
+## 何时用
+
+- 当前任务跨多文件 / 涉及 refactor / 安全 / 数据迁移 / 架构决策，预判默认档（balanced）搞不定
+- reviewer 已经 REQUEST_CHANGES 或 BLOCK，需要更强模型重新出方案 / 重写代码
+- 想用 deep 档跑一遍对比 balanced 档的产出差异（benchmark 场景）
+
+## 与 /quick / /model-switch 的关系
+
+- `/quick` ←→ `/deep`：完全对称，方向相反
+- `/model-switch agent <model-id>`：底层通用切换；`/deep` 是它的「按档位语义糖」，自动算出 deep 档 model 不用用户记 id
+- 三者最终都走相同的 `ast_edit + pending_changes` 路径，没有"另一套"写文件机制
+
+## 安全约束
+
+- ❌ 禁止直接 apply pending-changes（必须用户审批）
+- ❌ 禁止改 `codeforge.json` 之外的文件
+- ❌ 禁止在没有 `models.categories.deep`（或 `models.tiers.deep`）配置时硬编码 model id —— 必须从配置读
+- ✅ stage 完一定要输出 pending id 给用户
+- ✅ apply 后一定要提示 `npm run sync:models`
+
+## 失败回退
+
+- `model_chain` 报 `config_not_found`：提示用户先在项目根创建 `codeforge.json`
+- `models.categories.deep` / `models.tiers.deep` 缺失：提示用户先在 `codeforge.json` 添加 deep 档定义，参考 `schemas/codeforge.schema.json`
+- agent 不在配置：列出所有可选 agent 名让用户选
+
+## 元数据
+
+- `agent`: planner（命令由 planner 角色执行配置类决策操作）
+- `trigger_workflow`: null

package/commands/quick.md

@@ -0,0 +1,92 @@
+---
+description: 临时把当前任务的 agent 模型降到 quick 档（Sonnet/Haiku 档，省 token）；改动 stage 到 pending-changes 等待用户审批
+agent: planner
+---
+
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: quick
+  version: 1.0.0
+  trigger_workflow: null
+  allowed_tools: model_chain, ast_edit, pending_changes
+  说明：方案 A 用户显式 override 入口；与 /deep 对称；与 /model-switch 共享 ast_edit + pending_changes 落地路径
+  ADR-0060（model-tier-three-layer-escalation，Phase 2d）
+-->
+
+
+# /quick — 临时降档到 quick（Sonnet/Haiku 档，省 token）
+
+把指定 agent 的模型临时降到 `quick` 档（默认 `anthropic/claude-sonnet-4-5` 或更轻量的 Haiku，按 `codeforge.json` 配置）。
+改动会 stage 到 pending-changes，**由用户审批后 apply 才会真正生效**。
+
+## 输入
+
+参数：$ARGUMENTS
+
+## 用法
+
+```
+/quick              # 默认降 coder 到 quick 档
+/quick coder        # 同上，显式指定
+/quick planner      # 降 planner 到 quick 档（不推荐——planner 出方案质量很影响后续）
+/quick reviewer     # 降 reviewer 到 quick 档（不推荐——会降低评审质量）
+```
+
+## 行为
+
+1. **解析参数**：
+   - `$1` = agent 名，缺省默认 `coder`
+   - agent 名必须在 `codeforge.json` 的 `models.agents.*` 里存在；不存在则列出可选 agent 提示用户
+
+2. **查当前档位**：调用 `model_chain({ agent })` 读 `codeforge.json` 拿当前 agent 的模型链
+
+3. **判断是否需要切换**（去噪，避免误操作）：
+   - 若当前 model 已经命中 `models.categories.quick`（或 agent 已是 quick 档变体）→ 直接告知用户「<agent> 当前已是 quick 档（model=xxx），无需切换」，**不 stage**
+   - 否则进入切换流程
+
+4. **质量风险提示（不可省）**：在 stage 之前主动给用户输出一段警告：
+   - 「⚠️ 降到 quick 档可能降低产出质量。建议仅在以下场景使用：①改 typo / 格式化等简单任务；②临时省 token 跑探索性 prompt；③明知任务简单想加速」
+   - 若用户降的是 `planner` 或 `reviewer`，额外提示「⚠️ <agent> 是质量关键节点，降档可能导致方案/评审失误」
+   - 仍按用户意图执行 stage（提示是软约束，不阻断）
+
+5. **执行切换**（复用 `/model-switch` 的等价路径，按 ast_edit + pending_changes 标准模式自行 stage）：
+   1. 从 `codeforge.json` 的 `models.categories.quick`（或 `models.tiers.quick`，若已落地 Phase 2a）读出目标 model id 和 thinking 配置
+   2. 用 `ast_edit` 修改 `codeforge.json`：把 `models.agents.<agent>.model` 改为 quick 档 model；旧主模型自动 prepend 到该 agent 的 fallback 链头部（避免重启后被切回去，方便升回去）
+   3. 改动用 `pending_changes.stage` 暂存；**不调 apply**
+   4. 输出 pending-changes ID 给用户审批
+
+6. **审批后提示**：用户 apply 之后，主动提示跑 `npm run sync:models` 把新配置同步到 `agents/<agent>.md` 的 frontmatter
+
+7. **本次会话即时生效说明**：明确告诉用户「`/quick` 改的是 `codeforge.json`，本次会话已加载的 agent 不会立即换 model；下次新会话或重启 opencode 后生效」
+
+## 何时用
+
+- 改 typo / 文档措辞 / 格式化等简单任务，不需要 opus 级推理
+- 跑探索性 prompt 想省 token（先 quick 探路，方向对了再 `/deep` 升档重做）
+- benchmark 场景：跑同任务对比 quick / balanced / deep 的产出差异
+
+## 与 /deep / /model-switch 的关系
+
+- `/deep` ←→ `/quick`：完全对称，方向相反
+- `/model-switch agent <model-id>`：底层通用切换；`/quick` 是它的「按档位语义糖」，自动算出 quick 档 model 不用用户记 id
+- 三者最终都走相同的 `ast_edit + pending_changes` 路径，没有"另一套"写文件机制
+
+## 安全约束
+
+- ❌ 禁止直接 apply pending-changes（必须用户审批）
+- ❌ 禁止改 `codeforge.json` 之外的文件
+- ❌ 禁止在没有 `models.categories.quick`（或 `models.tiers.quick`）配置时硬编码 model id —— 必须从配置读
+- ✅ 降档前必须输出质量风险提示
+- ✅ stage 完一定要输出 pending id 给用户
+- ✅ apply 后一定要提示 `npm run sync:models`
+
+## 失败回退
+
+- `model_chain` 报 `config_not_found`：提示用户先在项目根创建 `codeforge.json`
+- `models.categories.quick` / `models.tiers.quick` 缺失：提示用户先在 `codeforge.json` 添加 quick 档定义，参考 `schemas/codeforge.schema.json`
+- agent 不在配置：列出所有可选 agent 名让用户选
+
+## 元数据
+
+- `agent`: planner（命令由 planner 角色执行配置类决策操作）
+- `trigger_workflow`: null