@andyqiu/codeforge 0.3.10 → 0.3.12

package/assets/adr-init/scripts/adr-index-sync.mjs

@@ -0,0 +1,151 @@
+#!/usr/bin/env node
+/**
+ * adr-index-sync.mjs — 自动同步 docs/adr/README.md 索引表（泛化版，由 codeforge adr-init 下发）
+ *
+ * 与 CodeForge 自仓库 scripts/adr-index-sync.mjs 的区别：
+ *   - LEGACY_ID_MAP 默认为空（不展示「曾用编号」列）
+ *   - README marker 改为 HTML 注释锚点：`<!-- adr-index:start --> / <!-- adr-index:end -->`
+ *   - ROOT 支持 ADR_ROOT 环境变量参数化
+ *
+ * 用法：
+ *   node scripts/adr-index-sync.mjs           # 默认：写回 README.md
+ *   node scripts/adr-index-sync.mjs --check   # 仅检查，不写；不同步退出码 1
+ *
+ * 环境变量：
+ *   ADR_ROOT  项目根目录绝对/相对路径；默认 path.resolve(__dirname, "..")
+ *   ADR_DIR   ADR 目录；默认 <ROOT>/docs/adr
+ *
+ * 工作原理：
+ *   1. 扫 docs/adr/*.md（纯 slug 格式）取 frontmatter
+ *   2. 按 date 升序排序（同 date 按 id 二级排序）生成索引行
+ *   3. 在 README.md 找 marker `<!-- adr-index:start --> ... <!-- adr-index:end -->` 之间整段替换
+ *   4. --check 模式不写文件，diff 不为空则 exit 1
+ */
+
+import { existsSync, promises as fs } from "node:fs"
+import * as path from "node:path"
+import { fileURLToPath } from "node:url"
+
+const DEFAULT_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..")
+const ROOT = process.env.ADR_ROOT ? path.resolve(process.env.ADR_ROOT) : DEFAULT_ROOT
+const ADR_DIR = process.env.ADR_DIR ? path.resolve(process.env.ADR_DIR) : path.join(ROOT, "docs", "adr")
+const README = path.join(ADR_DIR, "README.md")
+const CHECK_ONLY = process.argv.includes("--check")
+
+const SLUG_RE = /^[a-z][a-z0-9-]*\.md$/
+const isTemplate = (f) => f === "template.md"
+const isReadme = (f) => f === "README.md"
+const isAdrFile = (f) => !isTemplate(f) && !isReadme(f) && SLUG_RE.test(f)
+
+// 模板行：固定 prepend 在首行；template.md 单独列出避免被 isAdrFile 排除
+const TEMPLATE_LINE = "| template | — | Template（模板） | — | — |"
+
+// 下发版默认为空映射；如目标项目从旧 NNNN- 编号体系迁移，可在此显式补充
+const LEGACY_ID_MAP = new Map()
+
+async function parseADR(filepath) {
+  const raw = await fs.readFile(filepath, "utf8")
+  const m = raw.match(/^---\n([\s\S]*?)\n---/)
+  if (!m) return null
+  const fm = {}
+  let curArr = null
+  for (const line of m[1].split("\n")) {
+    const kv = line.match(/^([a-z][\w-]*):\s*(.*)$/)
+    if (kv) {
+      const v = kv[2].trim()
+      if (/^\[.*\]$/.test(v)) {
+        fm[kv[1]] = v.slice(1, -1).split(",")
+          .map(s => s.trim().replace(/^["']|["']$/g, ""))
+          .filter(Boolean)
+        curArr = null
+      } else if (v === "" || v === "[]") {
+        fm[kv[1]] = []
+        curArr = fm[kv[1]]
+      } else {
+        fm[kv[1]] = v.replace(/^["']|["']$/g, "")
+        curArr = null
+      }
+    } else if (curArr && line.startsWith("  - ")) {
+      curArr.push(line.slice(4).trim().replace(/^["']|["']$/g, ""))
+    }
+  }
+  return fm
+}
+
+async function buildIndex() {
+  const files = (await fs.readdir(ADR_DIR)).filter(isAdrFile)
+  const rows = []
+  for (const f of files) {
+    const fm = await parseADR(path.join(ADR_DIR, f))
+    if (!fm) continue
+    const id = f.replace(/\.md$/, "")
+    const date = String(fm.date || "").trim() || "—"
+    const title = String(fm.title || "").replace(/^["']|["']$/g, "")
+    const status = fm.status || "?"
+    const sb = Array.isArray(fm["superseded-by"]) ? fm["superseded-by"].filter(Boolean) : []
+    const sup = Array.isArray(fm.supersedes) ? fm.supersedes.filter(Boolean) : []
+    let rel = "—"
+    if (sb.length) rel = `by ${sb.map((x) => String(x).trim()).join(", ")}`
+    else if (sup.length) rel = `Supersedes ${sup.map((x) => String(x).trim()).join(", ")}`
+    const statusCell = status === "Superseded" ? `**${status}**` : status
+    const titleCell = `[${title}](./${f})`
+    // LEGACY_ID_MAP 留作扩展：如目标项目有旧编号要展示，可在源码 const 处补充并改表头
+    rows.push({
+      id,
+      date,
+      title,
+      status,
+      sb,
+      sup,
+      file: f,
+      line: `| ${id} | ${date} | ${titleCell} | ${statusCell} | ${rel} |`,
+    })
+  }
+  rows.sort((a, b) => a.date.localeCompare(b.date) || a.id.localeCompare(b.id))
+  return [TEMPLATE_LINE, ...rows.map((r) => r.line)]
+}
+
+async function main() {
+  if (!existsSync(README)) {
+    console.error(`✗ 未找到 ${README}`)
+    process.exit(1)
+  }
+  const old = await fs.readFile(README, "utf8")
+  const rows = await buildIndex()
+  const tableHeader = "| ID | Date | 标题 | 状态 | 替换关系 |\n|---|---|---|---|---|"
+  const tableBlock = `${tableHeader}\n${rows.join("\n")}`
+
+  // marker：HTML 注释锚点
+  const markerRe = /(<!--\s*adr-index:start\s*-->)[\s\S]*?(<!--\s*adr-index:end\s*-->)/
+  const m = old.match(markerRe)
+  if (!m) {
+    console.error(`✗ README 找不到 marker "<!-- adr-index:start --> ... <!-- adr-index:end -->"`)
+    console.error(`  请确认 ${path.relative(ROOT, README)} 含一对 HTML 注释锚点。`)
+    process.exit(1)
+  }
+
+  const newContent = old.replace(markerRe, `$1\n${tableBlock}\n$2`)
+
+  if (CHECK_ONLY) {
+    if (newContent === old) {
+      console.log(`✓ README 索引与 ADR 文件同步（${rows.length} 行）`)
+      process.exit(0)
+    } else {
+      console.error(`✗ README 索引与 ADR 文件不同步`)
+      console.error(`  跑 \`node scripts/adr-index-sync.mjs\` 自动修复`)
+      process.exit(1)
+    }
+  }
+
+  if (newContent === old) {
+    console.log(`✓ README 索引已是最新（${rows.length} 行），未改动`)
+  } else {
+    await fs.writeFile(README, newContent, "utf8")
+    console.log(`✓ README 索引已更新：${rows.length} 行`)
+  }
+}
+
+main().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})

package/bin/codeforge.mjs

@@ -14,6 +14,8 @@
  *   rollback   [--target=<path>] [--dry-run]
  *                                     恢复到上一次 backup（auto_install 失败时手动救场）
  *   runtime where [<path>]            打印当前项目对应的全局运行时目录
+ *   adr-init   [--force] [--dry-run] [--write-prepare] [--no-pre-push]
+ *                                     把 ADR 体系（hooks + scripts + 模板）下发到当前 git 项目
  *   help [<cmd>]                      打印帮助
  *
  * 默认 --project（项目级，最安全）。
@@ -299,6 +301,79 @@ function cmdRuntime(args) {
   return r.status ?? 1
 }
 
+// ────────────────────────────────────────────────────────────────────
+// 子命令：adr-init —— 把 ADR 体系下发到当前 git 项目 (ADR:adr-distribution-init)
+// ────────────────────────────────────────────────────────────────────
+//
+// 实现走 dist/adr-init.js 这个**确定路径**（由 scripts/build-with-version.mjs 第二
+// bun build entry 产出）。既适用 npm 包安装（pkgRoot/dist/adr-init.js），也适用本
+// 仓库 dev 期（repoRoot/dist/adr-init.js）。没有 fallback —— 缺 dist 文件就明确报错
+// 提示跑 npm run build，比 ts-node / 源码动态 import 简单可靠。
+async function cmdAdrInit(args) {
+  const cwd = process.cwd()
+  const opts = {
+    cwd,
+    force: !!args.flags.force,
+    dryRun: !!args.flags["dry-run"] || !!args.flags.dryRun,
+    writePrepare: !!args.flags["write-prepare"] || !!args.flags.writePrepare,
+    installPrePush: args.flags["no-pre-push"] ? false : true,
+  }
+
+  const adrInitPath = path.join(REPO_ROOT, "dist", "adr-init.js")
+  if (!existsSync(adrInitPath)) {
+    err(`找不到 ${adrInitPath}`)
+    err(`如果是从源码运行：请先跑 npm run build`)
+    err(`如果是 npm 安装：可能是发布缺文件，请重装或反馈给 @andyqiu/codeforge`)
+    return 1
+  }
+
+  log(`CodeForge adr-init —— 下发 ADR 体系到 ${cwd}`)
+  log(`  force          : ${opts.force}`)
+  log(`  dry-run        : ${opts.dryRun}`)
+  log(`  write-prepare  : ${opts.writePrepare}`)
+  log(`  install pre-push: ${opts.installPrePush}`)
+  hr()
+
+  // ESM dynamic import 必须用 file:// URL，Win 路径才能正确解析
+  let mod
+  try {
+    mod = await import(url.pathToFileURL(adrInitPath).href)
+  } catch (e) {
+    err(`加载 ${adrInitPath} 失败：${e?.message ?? e}`)
+    return 1
+  }
+  if (typeof mod.runAdrInit !== "function") {
+    err(`${adrInitPath} 缺少 runAdrInit 导出（bundle 可能损坏，请重建 dist/）`)
+    return 1
+  }
+
+  let result
+  try {
+    result = await mod.runAdrInit(opts)
+  } catch (e) {
+    err(`adr-init 执行抛错：${e?.stack ?? e}`)
+    return 1
+  }
+
+  if (result.wrote?.length) {
+    ok(`已写入 ${result.wrote.length} 个文件：`)
+    for (const f of result.wrote) console.log(`  + ${f}`)
+  }
+  if (result.skipped?.length) {
+    warn(`已跳过 ${result.skipped.length} 个已存在文件（用 --force 覆盖）：`)
+    for (const f of result.skipped) console.log(`  · ${f}`)
+  }
+  if (result.backedUp?.length) {
+    ok(`已备份 ${result.backedUp.length} 个原文件：`)
+    for (const f of result.backedUp) console.log(`  ↳ ${f}`)
+  }
+  for (const s of result.suggestions ?? []) log(s)
+  for (const w of result.warnings ?? []) warn(w)
+  if (opts.dryRun) log("dry-run 模式：以上未实际写盘")
+  hr()
+  return result.ok === false ? 1 : 0
+}
+
 // ────────────────────────────────────────────────────────────────────
 
 // 子命令：help
@@ -313,6 +388,8 @@ function cmdHelp() {
   codeforge version
   codeforge rollback   [--target=<path>] [--dry-run]   # 恢复最近 backup（auto_install 失败救场）
   codeforge runtime where [<path>]   # 打印当前项目的全局运行时目录
+  codeforge adr-init   [--force] [--dry-run] [--write-prepare] [--no-pre-push]
+                                     # 把 ADR 校验体系（hooks + scripts + 模板）下发到当前 git 项目
 
 一行命令（远程安装）：
   npx @andyqiu/codeforge install
@@ -326,6 +403,12 @@ function cmdHelp() {
   --enable-legacy-tools  启用旧版 file-based tools（默认禁用，避免 zod 跨实例 bug）
   --target               rollback 子命令：指定 index.js 路径（默认自动探测）
 
+参数（adr-init 专用）：
+  --force                覆盖已存在文件（覆盖前自动 .bak.<ts> 备份）
+  --dry-run              只打印将要执行的写入计划，不实际写盘
+  --write-prepare        合并 git config core.hooksPath 到 package.json scripts.prepare（写前 backup package.json；默认只建议不写）
+  --no-pre-push          跳过 .githooks/pre-push 生成（只装 pre-commit）
+
 CodeForge 是 opencode 1.14+ 的单 bundle plugin（持续跟主线，src/index.ts → dist/index.js），
 通过往 opencode.json 写一行 plugin entry 来装载。
 不支持 Cursor / Claude Code / Codex —— 它们的扩展机制不同，强行映射只会变成
@@ -336,9 +419,12 @@ CodeForge 是 opencode 1.14+ 的单 bundle plugin（持续跟主线，src/index.
 }
 
 // ────────────────────────────────────────────────────────────────────
-// main
+// main —— async (ADR:adr-distribution-init: adr-init 需 dynamic import)
 // ────────────────────────────────────────────────────────────────────
-function main() {
+//
+// 改成 async 后所有同步 case `return <number>` 自动被包成 Promise<number>，外层 .then
+// 拿到数字调 process.exit 即可；现有 case 的 exit code 行为不变。
+async function main() {
   const argv = process.argv.slice(2)
   if (argv.length === 0 || ["-h", "--help"].includes(argv[0])) {
     return cmdHelp()
@@ -366,6 +452,8 @@ function main() {
       return cmdRollback(args)
     case "runtime":
       return cmdRuntime(args)
+    case "adr-init":
+      return cmdAdrInit(args)
 
     case "help":
       return cmdHelp()
@@ -376,4 +464,9 @@ function main() {
   }
 }
 
-process.exit(main())
+main()
+  .then((code) => process.exit(typeof code === "number" ? code : 0))
+  .catch((e) => {
+    err(`未捕获错误：${e?.stack ?? e}`)
+    process.exit(1)
+  })

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/adr-init.md

@@ -0,0 +1,67 @@
+---
+description: 一键把 ADR 体系（adr-check + git hooks + 模板）下发到当前 git 项目
+---
+
+<!-- ADR:adr-distribution-init -->
+<!--
+codeforge 元数据（opencode 不读，由 plugins / workflow-engine 解析）：
+  name: adr-init
+  version: 1.0.0
+  trigger_workflow: null
+  allowed_tools: adr-init
+  说明：单 tool 命令，把 CodeForge 的 ADR 体系一键下发到当前 git 项目
+-->
+
+
+# /adr-init — 一键下发 ADR 体系
+
+把 CodeForge 维护的 ADR 体系（决策先行 + 三向引用 + 触发式补全 + README 索引同步）下发到**当前 git 项目**：
+
+- `scripts/adr-check.mjs`、`scripts/adr-index-sync.mjs`（泛化版，支持 `ADR_ROOT` / `ADR_DIR` 环境变量）
+- `.githooks/pre-commit`（staged 模式校验）、`.githooks/pre-push`（last-commit 模式校验）
+- `docs/adr/README.md`（索引骨架，含 HTML 注释 marker）、`docs/adr/template.md`
+- `.github/pull_request_template.md`（ADR checklist）
+
+零 npm 依赖：用 `git config core.hooksPath .githooks`（自动启用，无需 husky）。
+
+## 输入
+
+可选参数：$ARGUMENTS
+
+支持的 flag（在用户对话里说，由 LLM 解析后传给 `adr-init` tool）：
+
+- `--force`：覆盖已存在文件（覆盖前自动 `.bak.<时间戳>` 备份）
+- `--dry-run`：只打印将要执行的写入计划，不实际写盘
+- `--write-prepare`：（npm 项目）自动合并 `git config core.hooksPath .githooks` 到 `package.json scripts.prepare`；写前自动 backup package.json
+- `--no-pre-push`：只装 pre-commit，不装 pre-push
+
+## 用法
+
+```
+/adr-init
+/adr-init --dry-run
+/adr-init --force
+/adr-init --write-prepare
+```
+
+也可在 shell 跑等价命令：
+
+```
+npx @andyqiu/codeforge adr-init [--force] [--dry-run] [--write-prepare] [--no-pre-push]
+```
+
+## 行为
+
+1. 检查当前目录是否 git 仓库（否则报错并停止）
+2. 解析 `assets/adr-init/` 资产根（兼容 npm 全局 / npx / 本仓库 dev 三种安装形态）
+3. 按清单复制文件：
+   - 默认 `exists → skip`；`--force` 覆盖前自动 `.bak.<ts>` 备份
+   - hook 文件自动 `chmod 0o755`（Windows 上吞错）
+4. 运行 `git config core.hooksPath .githooks` 启用 hooks
+5. 报告写入 / 跳过 / 备份 / 建议 / 警告
+
+## 失败回退
+
+- 当前目录非 git 仓库 → 返回 `reason: "not_git_repo"`，建议用户先 `git init`
+- 资产路径找不到（npm 包 `files` 未含 `assets/`）→ 返回 `reason: "assets_not_found"`，提示重装
+- `git config` 失败 → 仍返回 ok=true，但 warnings 含具体错误，请用户手动执行

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