> ## 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 CLI 到初始化项目、刷新资产、健康检查与卸载的完整流程。

本页把 Comet 的安装、初始化、更新、健康检查和卸载串成一条完整路径。每一步都链接到更详细的命令页，需要时再深入。

## 前置要求

* Node.js 22 或更高版本
* npm 或 npx
* Git

## 1. 安装 CLI

```bash theme={null}
npm install -g @rpamis/comet
```

确认命令可用：

```bash theme={null}
comet -v
```

## 2. 初始化项目

进入项目根目录运行安装入口：

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

`comet init` 会检测平台、安装 Comet Skill，并在项目级初始化时确定 `/comet` 的默认工作流。新项目默认启用 Native；已有明确 Classic 状态的项目保持 Classic。

完整选项与 Native/Classic 初始化边界见 [comet init](/zh/cli/init)。

### 安装范围：项目级还是全局

| 安装范围    | 适合场景             | 特点              |
| ------- | ---------------- | --------------- |
| project | 团队项目、仓库约定、需要提交配置 | 配置写入当前项目，便于协作   |
| global  | 个人默认环境、多个项目共享    | 配置写入用户目录，切项目更省事 |

不确定时先用项目级，它最容易让团队成员看到同一套 Comet 行为。

### 安装模式：复制还是符号链接

Classic 或 both 初始化在选择平台后会询问**安装模式**：

* **Copy**（默认）：为每个平台独立复制一份 Skill 文件，适合跨设备同步（提交到仓库）。
* **Symlink**：在各平台 `skills/` 目录创建指向 `.comet/skills/` 的符号链接，多平台共享同一份中央存储，一次更新全部生效。

仅安装 Native 时固定使用 Copy。两种模式的详细区别见 [支持的平台 · 安装模式](/zh/platforms#安装模式：复制-vs-符号链接)。

<Warning>
  符号链接依赖文件系统支持。某些 Windows 配置或同步工具（如部分云盘）可能不正确处理符号链接。遇到问题时回退到 <strong>Copy</strong> 模式即可。
</Warning>

## 3. 更新Comet

更新Comet可按如下操作，他会帮你拉取npm新包，刷新已安装的 Skill、Rule、Hook、Runtime及config配置：

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

交互式 `comet update` 选择更新所有已登记项目时会一并更新对应的 npm 包（全局包最多尝试一次）。

<Note>
  用 <code>--current-project</code> 或 <code>--json</code> 把范围限定到单个项目时，默认只刷新资产、不更新 npm
  包。这种模式下想同时更新包，再加 <code>--self-update</code>。
</Note>

更新范围、Native/Classic 更新差异详见 [comet update](/zh/cli/update)。

## 4. 健康检查

任何时候状态异常，用 `comet doctor` 做完整的安装健康检查：

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

`doctor` 会检查 Skill、脚本、工作目录和 change 状态：

* `fail` 是阻塞问题（如 Skill 缺失、状态损坏），必须优先处理。
* `warn` 通常不阻塞（如 openspec CLI 未装但项目不依赖）。

详见 [comet doctor](/zh/cli/doctor)。

## 5. 卸载

`comet uninstall` 只移除 Comet 管理的 Skill、规则和 hooks，保留你的 OpenSpec change、设计文档、实施计划和项目代码。

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

批量卸载需显式使用 `--all-projects`。详见 [comet uninstall](/zh/cli/uninstall)。

## 什么时候需要重装或更新

* 升级 `@rpamis/comet` 后。
* `comet doctor` 提示 Skill 或脚本版本不一致。
* 切换中文或英文 Skill。
* 团队更新了项目级 Comet 配置。
* 安装摘要里某平台显示 `failed`，或写文件时 hook 报 `[COMET-HOOK] crash`——通常是安装不完整，重跑 `comet init`/`comet update` 补齐文件。

## 下一步

* 首次完整上手流程：[快速开始](/zh/quickstart)。
* 支持的全部平台：[支持的平台](/zh/platforms)。
* 安装与初始化的更多疑问：[CLI 常见问题](/zh/cli/faq)。