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

# Core 命令

> 使用 init、sync、doctor、catalog、docs 与 update 命令引导并维护 Forge 仓库，讲解 profile、settings、可逆卸载参数，无效 profile 提前中止，以及 FORGE_GUARD_STRICT 严格模式。

Core 分组负责引导一个仓库并保持它健康。

## `forge init`

搭建本仓库的配置——从一份共享源生成每个工具的配置。

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

生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等
(以及给 Roo Code 和 VS Code 的 MCP 服务器配置),外加 ledger 所需的 `.gitattributes` union-merge 规则。

`forge init` 还会把 Forge 的 hooks 和 permissions 合并到**全局**的
`~/.claude/settings.json`,因此在写入之前会先声明这次合并。该合并是幂等的、由标记保护的,
永远不会覆盖用户自己的条目。

### Init 参数

| 参数                  | 作用                                                                                                                                      |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `--profile <name>`  | 为本仓库选择策略 profile。接受 `minimal` 或 `standard`(默认)。无效的值会在任何搭建、`.forge/` 写入或合并动作之前中止。                                                        |
| `--no-settings`     | 完全跳过全局 `~/.claude/settings.json` 的合并——只写入仓库内的配置。                                                                                        |
| `--remove-settings` | 撤销一次过往的 settings 合并。Forge 形状的 hooks、permissions、statusline 以及 `_forge` 标记会被移除;会先写入一份带时间戳的备份,你自己的条目会被保留。也会被 `install.sh --uninstall` 调用。 |
| `--settings-only`   | 只合并全局 settings——不动仓库。被 `install.sh` 用来接线 hooks 和 permissions。                                                                           |

如果 settings 合并被拒绝或出错,`forge init` 会以 exit 1 失败,并把原因写到 stderr,而不是报告成功。

### 策略 profile

`--profile` 选择的规则集会被 `forge sync` 编译进每个工具的原生配置。只支持两个 profile:

* **`standard`**(默认)——完整的一套:共享记忆规则、影响分析,以及完整的护栏 hook 集合。
* **`minimal`**——面向小仓库或贡献者 fork 的更精简规则集。

旧名 `web-app`、`backend-service`、`library` 和 `regulated` 已被弃用,只是 `standard` 的别名。
它们仍然可用:`forge init` 会警告一次、以 `standard` 存储,已经持有旧名的配置会按 standard 同步。
新仓库应直接使用 `standard`。任何其他值都视为无效,会在 Forge 触及仓库之前中止。

```bash theme={null}
forge init --profile minimal            # 更精简的规则集
forge init --no-settings                # 只写仓库内配置,跳过全局合并
forge init --remove-settings            # 撤销一次过往的全局合并
```

## `forge sync`

把规范源重新编译为每个工具的原生配置文件。

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

幂等——只会重写发生变化的部分。编辑 `source/rules.json` 或仓库内的 `.forge/rules.json` 之后运行它。

## `forge doctor`

对已安装工具、护栏、MCP 授权和配置漂移做健康检查。

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

在工具、护栏、MCP 接线、配置漂移与更新状态上给出通过/失败结果。所有路径都是 fail-open。当配置了自定义 gateway 时,一条 **gateway models** 行会打印解析出的 `tier → model` 映射。

## `forge catalog`

Start Here——列出每一个工具、crew 与护栏,并附一句话说明它们的用途。

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

## `forge docs`

文档 ↔ 代码漂移。

```bash theme={null}
forge docs check     # 注册表对账——命令、环境变量、MCP 工具、CHANGELOG
forge docs sync      # diff 驱动的过期文档清扫
```

<Note>
  当命令、环境变量、MCP 工具或 CHANGELOG 与代码发生漂移时,`docs check` 会让 CI 失败。`docs sync` 会扫过 diff 并报告 UPDATED / STALE / VERIFIED-UNAFFECTED。
</Note>

## `forge update`

在三种安装模式下进行自更新。

```bash theme={null}
forge update              # 应用更新(git checkout 或 npm/copy 安装)
forge update --check      # 报告是否有更新可用
forge update --to <version>   # 锁定或回退到特定版本(v0.19+)
```

所有路径都是 fail-open——离线、无上游或 detached HEAD 都会返回 “unknown”,绝不会报错。`FORGE_NO_UPDATE_CHECK=1` 可以让 doctor 的提示保持静默。