快速开始

从零到一个配置好的仓库并跑通第一次基座检查,大约需要一分钟。

1. 安装

/plugin marketplace add CodeWithJuber/forgekit
/plugin install forgekit

npm install -g @codewithjuber/forgekit

npm install -g github:CodeWithJuber/forgekit

对于 Claude Code 和 Codex,推荐走插件通道——护栏会自动接线,不需要合并任何东西。完整通道矩阵(包括开发者的 symlink 方案)见安装。

2. 配置一个仓库

生成每个工具的配置

cd ~/your-project
forge init

这会生成 AGENTS.md、CLAUDE.md、.gemini/settings.json、.aider.conf.yml 等——外加 ledger 所需的 .gitattributes union-merge 规则。现在 Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 都从各自的原生文件里读取同一套规则。

做一次健康检查

forge doctor

对已安装工具、护栏、MCP 授权和配置漂移的通过/失败检查。

以后要改规则

编辑 source/rules.json(或在仓库里放一份 .forge/rules.json),然后重新编译:

forge sync

sync 是幂等的——只会重写发生变化的部分。

3. 运行行动前关卡

基座是在模型编辑代码之前运行的那一层。一条命令就能跑完整个关卡:

forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests"
#   → 假设裁决 · 能胜任的最便宜模型 · 预测的爆炸半径
#     (包括你未点名的文件) · 范围聚类 · 验证清单

在 Claude Code 上,基座会通过 UserPromptSubmit 钩子在每次提示自动运行——仅作建议,对干净的任务保持安静。其他每个工具则会获得一条原生配置规则,外加 19 个可自行调用的 MCP 工具。

如果 forge substrate 返回 ASK FIRST,在编辑之前先问它返回的那些问题。在任何有变更的改动之前,先读一读预测受影响的文件——爆炸半径。

forge substrate "<task>" --json   # 机器可读的裁决
forge impact <symbol-or-file>     # 单独跑爆炸半径

4. 探索附加功能

forge atlas build          # 索引本仓库的符号 → .forge/atlas.json
forge atlas query useAuth  # 它在哪里定义?(比 grep + 阅读更便宜)
forge atlas has useAuth    # 它存在吗?“not found” = 很可能是幻觉
forge recall add "db port" "Postgres is on 5433 here, not 5432"
forge catalog              # 一切内容的 Start-Here 索引

5. 第二天:ledger 开始学习

基座在第一天学到的一切,都以主张形式落到了 .forge/ledger/。这就是携证记忆——从现在开始它会带来回报:

forge ledger stats                              # 本仓库知道什么,按类别与信任等级列出
forge ledger blame <id-prefix>                  # 谁写下的主张,每一次裁决结果
forge reuse query "<what you're about to build>"  # 你已经拥有的、已验证的代码

继续深入

阅读行动前关卡如何把各阶段合成一次裁决。

开始使用

核心概念

1. 安装

2. 配置一个仓库

3. 运行行动前关卡

4. 探索附加功能

5. 第二天:ledger 开始学习

继续深入

​1. 安装

​2. 配置一个仓库

​3. 运行行动前关卡

​4. 探索附加功能

​5. 第二天:ledger 开始学习

继续深入

1. 安装

2. 配置一个仓库

3. 运行行动前关卡

4. 探索附加功能

5. 第二天:ledger 开始学习