> ## Documentation Index
> Fetch the complete documentation index at: https://docs.comet.rpamis.com/llms.txt
> Use this file to discover all available pages before exploring further.

# comet init

> 初始化项目或全局 Comet 环境，选择 Native 或 Classic，并安装对应能力。

`comet init` 是安装入口。它会检测平台、安装 Comet Skill，并在项目级初始化时确定 `/comet` 的默认工作流。

## 基本用法

```bash theme={null}
cd your-project
comet init
```

常用选项：

| 选项                  | 说明                                 |
| ------------------- | ---------------------------------- |
| `--yes`             | 非交互模式，自动安装缺失组件并跳过已有组件              |
| `--scope <scope>`   | 安装范围：`project` 或 `global`          |
| `--language <lang>` | Skill 语言：`zh` 或 `en`               |
| `--workflow <mode>` | 启用 `native`、`classic` 或 `both`     |
| `--platform <id>`   | 只初始化一个支持的平台或项目自定义平台                |
| `--codegraph <op>`  | 非交互选择 CodeGraph 索引：`init` 或 `skip` |
| `--root <path>`     | Native 产物根目录，例如 `docs`             |
| `--skip-existing`   | 跳过已有组件                             |
| `--overwrite`       | 覆盖 manifest 管理的文件                  |
| `--json`            | 输出 JSON                            |

## Native 与 Classic 初始化

交互式初始化在 project 和 global 范围都会提供 Native、Classic 或同时启用两者。项目级非交互初始化按以下规则选择默认工作流：

1. 合法的 `.comet/config.yaml` 是事实源。
2. `--workflow native|classic|both` 是显式选择，不迁移已有 change；`both` 默认让 `/comet` 进入 Native。
3. 没有有效 workflow 配置，但存在 Classic `.comet.yaml` 或旧版 Ambient Resume 证据时，保持 Classic。
4. 其他项目默认 Native；已有代码、普通 `openspec/` 或 `docs/superpowers/` 不会改变这个默认值。

Native 初始化安装 Comet 自有 Skill/runtime、统一工作流 Rule，以及平台支持时的单一 Hook Router，并创建：

```text theme={null}
.comet/config.yaml
<artifact-root>/comet/
```

它不会安装 OpenSpec、Superpowers 或 CodeGraph，也不会创建 Classic/OpenSpec change 或 `docs/superpowers/`。统一 Rule 与 Router 会按 `.comet/current-change.json` 把一次写入交给唯一 workflow Guard，不会同时运行 Native 与 Classic Guard。Classic 初始化保留原来的完整依赖与阶段治理。

Comet 只会在**所有选中平台的必需资产安装成功**，且已有 `/comet` 入口与 bundled routing contract 兼容后，才写入并激活 `.comet/config.yaml`。如果检测到不兼容的自定义 `/comet` 内容，初始化会原样保留它并把本次结果标记为 incomplete；确认要替换时显式重跑 `comet init --workflow native --overwrite`。

```bash theme={null}
comet init --workflow native --root docs
comet init --workflow classic
comet init --workflow both
comet init --scope global --workflow native
comet init --scope global --workflow classic
comet init --scope global --workflow both
```

global 范围下，`--workflow` 用于选择要全局安装的能力，但不会写入项目配置，也不会替项目选择默认工作流。非交互 global 初始化未传 `--workflow` 时仍默认使用 Classic。`--root` 仍只允许用于项目级 Native 初始化。

## 只处理一个平台

项目同时配置多个平台，但本次只需要安装或修复其中一个平台时，使用 `--platform`：

```bash theme={null}
comet init --platform claude --workflow native
comet init --platform my-team-platform --workflow classic
```

参数值可以是 Comet 支持的平台 ID，也可以是项目配置中定义的自定义平台。指定后只处理该目标；不指定时继续使用平台自动检测与现有回退规则。

非交互项目初始化还可以用 `--codegraph init` 明确创建或刷新 CodeGraph 索引，或用 `--codegraph skip` 明确跳过。普通检查不会自行修改索引；需要修复时可以先运行 `comet doctor` 查看状态。

## 项目级安装索引

0.4.0-beta.4 起，成功的项目级安装会登记到用户级项目索引。这个索引只保存后续更新和卸载所需的项目位置与已安装平台，不复制项目文件，也不上传使用数据。

登记后，交互式 `comet update` 和 `comet uninstall` 可以让你选择当前项目或所有已登记项目。`--json` 或显式 `--current-project` 会限定当前项目，`comet uninstall --force` 也保持当前项目；批量操作必须显式使用 `--all-projects`。自动化脚本应明确传入其中一个范围选项，不要依赖终端环境推断。

## 安装模式（复制 vs 符号链接）

Classic 或 both 初始化在选择平台后会询问**安装模式**，global 范围也一样（0.4.0-beta.1 起新增符号链接模式）。仅安装 Native 时固定使用 Copy；项目级 Native 不会创建 `.comet/skills/`，Native change 状态只存在于 `<artifact-root>/comet/`，共享项目配置与 selection 位于 `.comet/`。

* **Copy**（复制）：为每个平台独立复制一份 Skill 文件（传统方式）。
* **Symlink**（符号链接）：在各平台目录创建指向 `.comet/skills/` 的符号链接，所有平台共享同一份中央存储，节省空间且一次更新即全部生效。

如果平台已经有自己的 `skills/` 目录，Comet 会保留该目录，只在其中链接 Comet 管理的 Skill。已有的本地或第三方 Skill 不会因为选择 Symlink 而被删除或替换。

两种模式的详细区别和适用场景见 [支持的平台 · 安装模式](/zh/platforms#安装模式：复制-vs-符号链接)。

## 共享项目配置合并

Native 与 Classic 现在共用 `.comet/config.yaml`。初始化会按启用的工作流合并托管字段：

* **保留**你的现有配置值（如 `native.artifact_root`、`classic.review_mode`）
* **补齐**缺失的托管字段默认值
* **刷新**注释，对齐当前版本
* **保留**你额外添加的自定义字段
* 共享的 `default_workflow`、`workflows`、`ambient_resume` 与 `native.*`、`classic.*` 保持独立语义
* 无法安全解析的 workflow 配置会失败关闭，不会猜测默认值后覆盖

终端会提示 `项目配置已合并 (.comet/config.yaml)`。

## OpenSpec CLI 的安装范围

OpenSpec CLI 是 Classic 的跨项目命令行工具。Classic 即使选择项目级安装，也会把 OpenSpec CLI 作为全局工具安装或升级；它不会为了这个依赖在当前项目创建 `node_modules/`。Native 不检查或安装它。

## 初始化后检查

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

如果缺少平台目录、Skill 文件或脚本，先修复这些问题再开始 `/comet`。

## 安装摘要怎么看

`comet init`（和 `comet update`）按平台输出每个组件的安装状态。Skill/脚本复制是这样展示的：

```text theme={null}
Comet -> claude: installed (12 files) -> .claude/skills/
Comet -> claude: skipped (alreadyExists)
Comet -> opencode: failed (12 files, 1 failed) -> .opencode/skills/comet
```

| 状态          | 含义                     |
| ----------- | ---------------------- |
| `installed` | 全部文件复制成功               |
| `skipped`   | 已存在（未指定 `--overwrite`） |
| `failed`    | 有文件复制失败                |

<Warning>
  从 0.4.0-beta.1 起，<strong>部分失败的安装不再被掩盖成成功</strong>
  。如果某个平台有文件复制失败，该平台会标记 <code>failed</code> 并带失败计数。Classic 缺少{' '}
  <code>comet-hook-guard.mjs</code> 会破坏阶段检查；Native 缺少入口或 runtime
  同样不能写入项目默认配置。重跑 <code>comet init</code> 或 <code>comet update</code> 补齐缺失文件。
</Warning>