@andyqiu/codeforge

CodeForge — opencode 的零侵入扩展包。一行命令装好，重启 opencode 即可使用。

安装

需要 opencode ≥ 1.14 和 Node ≥ 20。

# 方式一：npm 全局安装（推荐，装完直接有 codeforge 命令）
npm install -g @andyqiu/codeforge
codeforge install --global

# 方式二：npx 免安装（一次性，不占全局）
npx @andyqiu/codeforge install --global

# 只装当前项目（不推荐，每个项目都要装）
npx @andyqiu/codeforge install

装完重启 opencode。

怎么用

进 opencode TUI 后，默认对话窗口就是 codeforge——它会判断你的需求该自己答还是派给专门的 agent，你不用关心。

直接对话

> 帮我把 user.ts 里的 getName 改成 getUserName
> 这个项目是怎么组织的？给我画个依赖图
> 修一下 login 接口 401 那个 bug

显式调用 agent（可选）

@planner   出实现方案，不写代码
@coder     按方案改代码（改动先暂存等你审）
@reviewer  审已暂存的改动，给 通过 / 改 / 拒

常用 slash 命令

| 命令 | 用途 | |---|---| | /plan <需求> | 让 planner 出方案 | | /ship <需求> | 完整链路：规划 → 编码 → 审阅 | | /review | 审当前暂存的改动 | | /refactor <目标> | 安全重构（先补测试锁行为，再改） | | /tdd <需求> | 严格 RED → GREEN → REFACTOR | | /parallel <任务1>,<任务2>,... | 多个独立任务并发跑 | | /adr-init | 为当前项目初始化 ADR 决策记录体系 |

ADR 决策记录（adr-init）

在任意 git 项目根目录执行一次，把完整的 ADR 校验体系下发到该项目：

# 方式一：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

下发后会在项目里生成：

| 文件 | 用途 | |---|---| | 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 后跑一次即可：

git config core.hooksPath .githooks

npm 项目可加 --write-prepare 让 npm install 自动完成上面这步。

难度分级与三道防线（Phase 2 引入）

CodeForge 给每个 agent 配三档变体，让简单任务省 token、复杂任务自动升档保质量：

| 档位 | 模型基线 | 用途 | |---|---|---| | coder-quick | 低成本快速模型 | typo / 单行改动 | | coder（默认） | 中端模型 | 单文件中等改动 | | coder-deep | 高端推理模型 | 跨文件重构 / 安全 / 数据迁移 |

三道防线决定最终用哪档（优先级递减）：

• A · 用户显式 override：/deep 升档、/quick 降档；锁定后 B/C 都不会覆盖
• B · 前置预判（Phase 2b 接线中）：派 task 前看跨文件数 / 关键词（auth / refactor / migration / schema）自动选档
• C · 运行时升档：reviewer 连续 REQUEST_CHANGES、stuck-detector 触发、测试连续失败 → 兜底升档（带 quota + debounce 去噪）

升档不会静默改配置——当前会记录日志并提示；完成 auto_escalate 接线后，配置变更才会 stage 到 pending-changes 等你 apply。完整设计见 docs/adr/model-tier-three-layer-escalation.md。

代码改动如何落地

所有 AI 写的代码先进暂存区，你看 diff 后决定是否真的写入：

pending_changes list           # 列出暂存
pending_changes diff <id>      # 看 diff
pending_changes apply <id>     # 同意写入
pending_changes discard <id>   # 丢弃

查版本 / 升级 / 回滚

# 查当前版本
cat ~/.config/opencode/codeforge/VERSION
# Windows：Get-Content "$env:USERPROFILE\.config\opencode\codeforge\VERSION"

# 立即升级到最新
npx @andyqiu/codeforge install --global

# 回滚到上一版
codeforge rollback

opencode 启动时自动后台检查新版并静默升级，下次启动生效。

关闭自动升级（编辑 ~/.config/opencode/codeforge/codeforge.json）：

{ "update": { "auto_install": false } }

Knowledge Hub（可选，团队共享经验）

启用后 AI 会主动查团队历史经验、自动沉淀踩坑记录。未配置不影响基础功能。

# macOS / Linux
export KNOWLEDGE_API_KEY=你的-token

# Windows PowerShell
[Environment]::SetEnvironmentVariable("KNOWLEDGE_API_KEY", "你的-token", "User")

详细配置 token 找你的团队管理员。

通知集成（可选）

支持把 AI 完成的任务、审阅结果推到 Slack / 飞书。三种配置方式，同时存在时按以下优先级合并（0.3.11 起补齐全局层，对齐 KH 配置惯例）：

| 优先级 | 来源 | 适用场景 | |---|---|---| | 1（最高）| CODEFORGE_CHANNELS_JSON env | CI / 本机临时覆盖 / 紧急静音（设为 [] 即全禁） | | 2 | <project>/.codeforge/channels.json | 团队 git 共享（0.3.11 推荐路径） | | 3（最低）| ~/.config/codeforge/channels.json | 个人跨项目共享 |

同名 channel：上层覆盖下层（env > project > global），覆盖时打 warn 提示。 env 显式为 [] 时清空 三层全部通知（0.3.11 行为变更，详见 CHANGELOG）。

0.3.10 兼容路径 <root>/.codeforge/config/channels.json 继续工作但启动 warn 提示迁移；两条路径同时存在时只读 0.3.11 推荐路径。

方式 ⓪ 全局个人配置（跨项目共享）

适用：你个人想在所有项目里都收同一个飞书/Slack 通知，不想每个项目都重配一遍。

# macOS / Linux
mkdir -p ~/.config/codeforge
cat > ~/.config/codeforge/channels.json <<'JSON'
[
  {
    "type": "lark",
    "name": "personal-lark",
    "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx"
  }
]
JSON
chmod 600 ~/.config/codeforge/channels.json  # 含 webhook secret，建议 600

# Windows PowerShell
$dir = "$env:USERPROFILE\.config\codeforge"
New-Item -ItemType Directory -Force -Path $dir | Out-Null
@'
[{"type":"lark","name":"personal-lark","webhook_url":"https://open.feishu.cn/open-apis/bot/v2/hook/xxx"}]
'@ | Set-Content -Encoding UTF8 "$dir\channels.json"

含 webhook secret，权限松（group/other 可读）时会启动打一次性 warn 提示 chmod 600，但不阻止加载。

方式 ① 项目共享配置（推荐团队场景）

在项目根创建 .codeforge/channels.json（0.3.11 推荐路径，可 git 提交）：

{
  "channels": [
    {
      "type": "slack",
      "name": "dev-alerts",
      "webhook_url": "https://hooks.slack.com/services/T.../B.../xxx",
      "events": ["workflow.failed", "approval.required"]
    },
    {
      "type": "lark",
      "name": "team-lark",
      "webhook_url": "https://open.feishu.cn/open-apis/bot/v2/hook/xxx",
      "secret": "可选签名密钥",
      "mentions": ["@all"]
    }
  ]
}

0.3.10 兼容路径 .codeforge/config/channels.json 仍可用，但启动会 warn 提示迁移到 .codeforge/channels.json（与 KH 配置 <root>/.codeforge/kh.json 风格统一）。0.3.10 用户继续工作不受影响。

完整字段定义见 lib/channels.ts 中 SlackChannel / LarkChannel 接口。

方式 ② 环境变量（CI 友好 / 临时覆盖）

export CODEFORGE_CHANNELS_JSON='[{"type":"lark","name":"ci","webhook_url":"https://..."}]'

⚠️ 老配置迁移

如果你按旧版 README 配过 ~/.config/opencode/codeforge/codeforge.json 里的 channels（该路径从未被 plugin 读取，原本就发不出通知），或者 0.3.10 配过 <root>/.codeforge/config/channels.json，请按下表迁移：

| 旧 | 新（0.3.11 推荐） | |---|---| | ~/.config/opencode/codeforge/codeforge.json 的 channels 字段 | ~/.config/codeforge/channels.json（全局）或 <project>/.codeforge/channels.json（项目） | | <project>/.codeforge/config/channels.json（0.3.10 兼容路径） | <project>/.codeforge/channels.json（0.3.11 推荐路径） | | { "type": "slack", "webhook": "..." } | { "type": "slack", "name": "<必填>", "webhook_url": "..." } | | { "type": "lark", "webhook": "...", "secret": "..." } | { "type": "lark", "name": "<必填>", "webhook_url": "...", "secret": "..." } |

变更点：

1. 加载路径：3 层 env > <project>/.codeforge/channels.json > ~/.config/codeforge/channels.json（旧 ~/.config/opencode/codeforge/codeforge.json 无效）
2. 字段名：webhook → webhook_url
3. 新必填：name（用于跨层合并去重）

配置错误时会在 plugin 启动日志打 warn，告知被忽略的 channel 名与缺失字段。

卸载

npx @andyqiu/codeforge uninstall --global

出问题怎么办

| 现象 | 处理 | |---|---| | 装完 opencode 没识别新命令 | 重启 opencode | | AI 改动没写入文件 | 看 pending_changes list，需要你 apply 才落地 | | 自动升级把功能搞坏了 | codeforge rollback 回上一版 | | 启动报"opencode 版本不兼容" | 升级 opencode：npm i -g opencode-ai@latest | | 命令找不到 | 全局装时确认 npm global bin 在 PATH：npm config get prefix |

其它问题联系 @andyqiu。

License

MIT