@andyqiu/codeforge

opencode 的零侵入 AI 编码扩展：让 AI 以「规划 → 编码 → 审阅」闭环完成任务，所有改动隔离在 session worktree，/merge 拍板才落地主仓。

安装

npm install -g @andyqiu/codeforge@latest

装完重启 opencode 即生效。

怎么用

进 opencode 后，默认对话窗口就是 codeforge——编排者，判断你的需求该自己答还是派给专门的 agent，你无需关心调度，直接说人话：

> 帮我修一下 login 接口 401 那个 bug
> 这个项目怎么组织的？给我画个依赖图

需要时也可 @ 显式调用某个角色。CodeForge 内置 9 个 agent：codeforge（编排）、planner（出方案不写码）、三档执行者 coder-quick / coder / coder-deep（按复杂度自动选档）、reviewer / reviewer-lite（审阅给 通过 / 改 / 拒）、discover（虚拟产品经理）及其对抗子 agent discover-challenger。

命令

最常用一条龙：/ship <需求> 跑完整 planner → coder → reviewer → merge 链路。

| 命令 | 用途 | |---|---| | /ship <需求> | 完整链路：规划 → 编码 → 审阅 → 合并 | | /plan <需求> | 只出方案，不写代码 | | /debug <问题> | bugfix 流：取证 → 假设 → 复现 → 修复 → 回归 | | /refactor <目标> | 安全重构：先补测试锁行为，再改 | | /tdd <需求> | 严格 RED → GREEN → REFACTOR | | /review | 审当前 session 暂存的改动 | | /merge | 触发 review-fix-review 闭环 + squash 合并入主仓 | | /discard-session | 放弃当前 session 的所有改动 | | /changes | 查看当前 session 改动摘要 | | /deep <需求> | 强制升档高端推理模型 | | /quick <需求> | 强制降档快速模型 | | /parallel | 已弃用（auto-parallel 已默认开，下一 minor 移除此命令） | | /pause | 暂停当前任务 | | /model-switch | 查看 / 切换 agent 绑定的模型 | | /adr-init | 为任意 git 项目初始化 ADR 决策记录体系 | | /gc-worktrees | 清理僵尸 worktree |

核心机制

• 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，跑 5 阶段（散度 → 收敛 → 红旗对抗 → PRD 起草 → 复核），产出 docs/specs/<slug>/{PRD.md, handoff.yaml}，被下游 codeforge / planner / coder 自动消费；discover-challenger 全程强对抗，防 sycophancy。详见 docs/discover/README.md。

ADR 决策记录

在任意 git 项目根执行一次，下发完整 ADR 校验体系（校验脚本 / 模板 / 索引 / PR 模板 / git hooks）：

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 自动完成）。

Knowledge Hub（可选）

export KNOWLEDGE_API_KEY=你的-token   # Windows 用 [Environment]::SetEnvironmentVariable(...)

token 找团队管理员获取。未配置不影响基础功能。

出问题怎么办

| 现象 | 处理 | |---|---| | 装完 opencode 没识别新命令 | 重启 opencode | | AI 改动没进主仓 | 改动在 session worktree 内，用 /merge 触发审批 + 合并 | | 启动报版本不兼容 | 升级 opencode：npm install -g opencode@latest | | 命令找不到 | 确认 npm global bin 在 PATH：npm config get prefix |

卸载

npm uninstall -g @andyqiu/codeforge

License

MIT