@andyqiu/codeforge 0.8.4 → 0.8.5

package/README.md

@@ -1,163 +1,97 @@
 # @andyqiu/codeforge
 
-CodeForge — [opencode](https://github.com/sst/opencode) 的零侵入扩展包。一行命令装好，重启 opencode 即可使用。
+[opencode](https://github.com/sst/opencode) 的零侵入 AI 编码扩展：让 AI 以「规划 → 编码 → 审阅」闭环完成任务，所有改动隔离在 session worktree，`/merge` 拍板才落地主仓。
 
 ## 安装
 
-需要 **opencode ≥ 1.14** 和 **Node ≥ 20**。
+需要 **opencode ≥ 1.14** 与 **Node ≥ 20**。
 
 ```bash
 npm install -g @andyqiu/codeforge
 ```
 
-装完**重启 opencode**。（postinstall 脚本会自动完成全局配置，无需额外操作。）
+postinstall 自动完成全局配置，装完**重启 opencode** 即生效。日后升级重跑同一条命令加 `@latest` 即可。
 
 ## 怎么用
 
-进 opencode TUI 后，默认对话窗口就是 `codeforge`——它会判断你的需求该自己答还是派给专门的 agent，你不用关心。
-
-### 直接对话
+进 opencode 后，默认对话窗口就是 `codeforge`——编排者，判断你的需求该自己答还是派给专门的 agent，你无需关心调度，直接说人话：
 
 ```
-> 帮我把 user.ts 里的 getName 改成 getUserName
-> 这个项目是怎么组织的？给我画个依赖图
-> 修一下 login 接口 401 那个 bug
+> 帮我修一下 login 接口 401 那个 bug
+> 这个项目怎么组织的？给我画个依赖图
 ```
 
-### 显式调用 agent（可选）
+需要时也可 `@` 显式调用某个角色。CodeForge 内置 9 个 agent：`codeforge`（编排）、`planner`（出方案不写码）、三档执行者 `coder-quick` / `coder` / `coder-deep`（按复杂度自动选档）、`reviewer` / `reviewer-lite`（审阅给 通过 / 改 / 拒）、`discover`（虚拟产品经理）及其对抗子 agent `discover-challenger`。
 
-```
-@planner   出实现方案，不写代码
-@coder     按方案改代码（改动先暂存等你审）
-@reviewer  审已暂存的改动，给 通过 / 改 / 拒
-```
+## 命令
 
-### 常用 slash 命令
+最常用一条龙：`/ship <需求>` 跑完整 planner → coder → reviewer → merge 链路。
 
 | 命令 | 用途 |
 |---|---|
-| `/plan <需求>` | 让 planner 出方案 |
-| `/ship <需求>` | 完整链路：规划 → 编码 → 审阅 |
-| `/review` | 审当前暂存的改动 |
-| `/refactor <目标>` | 安全重构（先补测试锁行为，再改） |
+| `/ship <需求>` | 完整链路：规划 → 编码 → 审阅 → 合并 |
+| `/plan <需求>` | 只出方案，不写代码 |
+| `/debug <问题>` | bugfix 流：取证 → 假设 → 复现 → 修复 → 回归 |
+| `/refactor <目标>` | 安全重构：先补测试锁行为，再改 |
 | `/tdd <需求>` | 严格 RED → GREEN → REFACTOR |
-| `/merge` | 触发 review + squash merge 入主仓 |
+| `/review` | 审当前 session 暂存的改动 |
+| `/merge` | 触发 review-fix-review 闭环 + squash 合并入主仓 |
 | `/discard-session` | 放弃当前 session 的所有改动 |
-| `/adr-init` | 为当前项目初始化 ADR 决策记录体系 |
-| `/debug <问题>` | 调试模式，深入分析问题根因 |
-| `/deep <需求>` | 强制升档用高端推理模型处理 |
-| `/quick <需求>` | 强制降档用快速模型处理 |
-| `/changes` | 查看当前 session 的改动摘要 |
+| `/changes` | 查看当前 session 改动摘要 |
+| `/deep <需求>` | 强制升档高端推理模型 |
+| `/quick <需求>` | 强制降档快速模型 |
+| `/parallel` | 显式并发多任务（默认已自动并行，保留兜底） |
 | `/pause` | 暂停当前任务 |
+| `/model-switch` | 查看 / 切换 agent 绑定的模型 |
+| `/adr-init` | 为任意 git 项目初始化 ADR 决策记录体系 |
+| `/gc-worktrees` | 清理僵尸 worktree |
 
-> 并行已成为 codeforge 默认能力（auto-parallel）：直接描述多个独立需求即可，codeforge 自动判断并并发到隔离 lane，汇聚后统一走合入闭环——**无需手动 `/parallel`**（旧命令已弃用，过渡期保留一个版本周期，下一 minor 移除）。
+## 核心机制
 
-### Discover Agent — 虚拟产品经理
+- **Session worktree 隔离**：每个 session 绑定独立 git worktree，AI 改动写在里面不碰主仓，`/merge` 通过审批后才 squash 落地。
+- **Auto-parallel**：描述多个独立需求时自动并发到隔离 lane，汇聚后统一走合入闭环，无需手动 `/parallel`。
+- **三档模型**：`coder-quick`（省钱）/ `coder`（默认）/ `coder-deep`（重型），codeforge 自动选档，也可 `/deep` `/quick` 手动 override。
+- **ADR 体系**：`/adr-init` 一键把 ADR 校验 hooks 下发到任意 git 项目。
+- **Knowledge Hub**（可选）：启用后 AI 自动查团队历史经验、自动沉淀踩坑，未配置不影响基础功能。
 
-需求不清晰时，用 discover 把模糊想法收敛成可执行 PRD：
-
-```
-@discover 我想做一个新人推荐 feed
-```
+## Discover —— 把模糊需求收敛成 PRD
 
-discover 会跑 5 个阶段：
-1. **散度** — 列各种可能解 + 边界
-2. **收敛** — 5 维加权打分筛选方向
-3. **红旗** — 召唤 `discover-challenger` 强对抗 sycophancy
-4. **PRD 起草** — 生成 EARS 句式 PRD.md + 机读 handoff.yaml
-5. **复核** — challenger 二次复核
+需求不清晰时用 `@discover`，跑 5 阶段（散度 → 收敛 → 红旗对抗 → PRD 起草 → 复核），产出 `docs/specs/<slug>/{PRD.md, handoff.yaml}`，被下游 codeforge / planner / coder 自动消费；`discover-challenger` 全程强对抗，防 sycophancy。详见 [docs/discover/README.md](./docs/discover/README.md)。
 
-产物在 `docs/specs/<slug>/{PRD.md, handoff.yaml}`，会被下游 codeforge / planner / coder **自动消费**。
+## ADR 决策记录
 
-详见 [docs/discover/README.md](./docs/discover/README.md)。
-
-### ADR 决策记录（adr-init）
-
-在任意 git 项目根目录执行一次，把完整的 ADR 校验体系下发到该项目：
+在任意 git 项目根执行一次，下发完整 ADR 校验体系（校验脚本 / 模板 / 索引 / PR 模板 / git hooks）：
 
 ```bash
-# CLI 命令
-codeforge adr-init
-
-# opencode 里直接说
-/adr-init
-
-# 常用选项
-codeforge adr-init --dry-run        # 只预览，不写文件
-codeforge adr-init --force          # 已有文件时覆盖（自动备份）
-codeforge adr-init --write-prepare  # 同时把 git config 写入 package.json prepare
+codeforge adr-init              # 或在 opencode 里说 /adr-init
+codeforge adr-init --dry-run    # 仅预览，不写文件
+codeforge adr-init --force      # 覆盖已有文件（自动备份）
 ```
 
-下发后会在项目里生成：
+把生成的文件提交进 git，协作者 clone 后执行 `git config core.hooksPath .githooks` 即可（npm 项目加 `--write-prepare` 可让 `npm install` 自动完成）。
 
-| 文件 | 用途 |
-|---|---|
-| `scripts/adr-check.mjs` | ADR 体系合规校验（commit 时自动跑） |
-| `scripts/adr-index-sync.mjs` | 自动同步 docs/adr/README.md 索引 |
-| `docs/adr/template.md` | ADR 模板（含三向引用字段） |
-| `docs/adr/README.md` | ADR 索引骨架 |
-| `.github/pull_request_template.md` | PR 模板（含 ADR checklist） |
-| `.githooks/pre-commit` | commit 时自动校验 ADR 规范 |
-| `.githooks/pre-push` | push 时全量校验 |
-
-**把生成的文件提交进 git**，其他人 clone 后跑一次即可：
-
-```bash
-git config core.hooksPath .githooks
-```
-
-npm 项目可加 `--write-prepare` 让 `npm install` 自动完成上面这步。
-
-### 代码改动如何落地
-
-每个 session 绑定独立 git worktree，AI 改动直接写到 worktree（不影响主仓）；审批通过 `/merge` 命令触发 review-fix-review 闭环，通过后 squash merge 入主仓。
+## Knowledge Hub（可选）
 
 ```bash
-/merge               # 触发 review + 合并闭环
-/discard-session     # 放弃当前 session 的所有改动
+export KNOWLEDGE_API_KEY=你的-token   # Windows 用 [Environment]::SetEnvironmentVariable(...)
 ```
 
-## Knowledge Hub（可选，团队共享经验）
-
-启用后 AI 会主动查团队历史经验、自动沉淀踩坑记录。**未配置不影响基础功能**。
-
-```bash
-# macOS / Linux
-export KNOWLEDGE_API_KEY=你的-token
-
-# Windows PowerShell
-[Environment]::SetEnvironmentVariable("KNOWLEDGE_API_KEY", "你的-token", "User")
-```
-
-详细配置 token 找你的团队管理员。
-
-## 升级
-
-opencode 启动时会自动检查并升级，无需手动操作。
-
-如需手动升级：
-
-```bash
-npm install -g @andyqiu/codeforge@latest
-```
-
-## 卸载
-
-```bash
-npm uninstall -g @andyqiu/codeforge
-```
+token 找团队管理员获取。未配置不影响基础功能。
 
 ## 出问题怎么办
 
 | 现象 | 处理 |
 |---|---|
 | 装完 opencode 没识别新命令 | 重启 opencode |
-| AI 改动没写入主仓 | 改动在 session worktree 内；用 `/merge` 触发审批 + 合并闭环 |
-| 启动报"opencode 版本不兼容" | 升级 opencode：`npm install -g opencode@latest` |
+| AI 改动没进主仓 | 改动在 session worktree 内，用 `/merge` 触发审批 + 合并 |
+| 启动报版本不兼容 | 升级 opencode：`npm install -g opencode@latest` |
 | 命令找不到 | 确认 npm global bin 在 PATH：`npm config get prefix` |
-| 需要查当前版本 | `codeforge --version` |
 
-其它问题联系 [@andyqiu](https://www.npmjs.com/~andyqiu)。
+## 卸载
+
+```bash
+npm uninstall -g @andyqiu/codeforge
+```
 
 ## License
 

package/dist/index.js

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

package/package.json

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