> ## Documentation Index
> Fetch the complete documentation index at: https://forgekit-docs-mintlify-7cd64f48.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 快速开始

> 安装 Forge,从同一份源生成每个工具的配置,并运行你的第一次行动前关卡——大约 60 秒。

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

## 1. 安装

<CodeGroup>
  ```bash Plugin (Claude Code / Codex) theme={null}
  /plugin marketplace add CodeWithJuber/forgekit
  /plugin install forgekit
  ```

  ```bash npm (any tool) theme={null}
  npm install -g @codewithjuber/forgekit
  ```

  ```bash No registry theme={null}
  npm install -g github:CodeWithJuber/forgekit
  ```
</CodeGroup>

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

## 2. 配置一个仓库

<Steps>
  <Step title="生成每个工具的配置">
    ```bash theme={null}
    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 都从各自的原生文件里读取**同一套**规则。
  </Step>

  <Step title="做一次健康检查">
    ```bash theme={null}
    forge doctor
    ```

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

  <Step title="以后要改规则">
    编辑 `source/rules.json`(或在仓库里放一份 `.forge/rules.json`),然后重新编译:

    ```bash theme={null}
    forge sync
    ```

    `sync` 是幂等的——只会重写发生变化的部分。
  </Step>
</Steps>

## 3. 运行行动前关卡

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

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

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

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

```bash theme={null}
forge substrate "<task>" --json   # 机器可读的裁决
forge impact <symbol-or-file>     # 单独跑爆炸半径
```

## 4. 探索附加功能

```bash theme={null}
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/`。这就是携证记忆——从现在开始它会带来回报:

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

<Card title="继续深入" icon="arrow-right" href="/zh-Hans/concepts/pre-action-gate">
  阅读行动前关卡如何把各阶段合成一次裁决。
</Card>