> ## 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.

# CLI 常见问题

> 解答 comet init/status/doctor/update、平台安装、Skill 管理和 CI 集成的常见疑问。

关于 Comet CLI 命令、安装、健康检查和平台支持的常见问题。

## 安装与初始化

<AccordionGroup>
  <Accordion title="comet init 会覆盖我现有的配置吗">
    不会。检测到已存在的组件时，`comet init` 会让你选择覆盖或跳过。hooks 是非破坏性合并，保留你已有的 hooks。`--yes` 模式下已存在组件默认跳过，强制刷新用 `--overwrite`。
  </Accordion>

  <Accordion title="安装摘要里某个平台显示 failed (12 files, 1 failed) 是什么意思">
    该平台有文件复制失败（例如某个 Skill 或脚本文件没装上）。0.4.0-beta.1 起部分失败不再被掩盖成成功——平台会标记 `failed` 并带失败计数，而不是把半安装状态报告为成功。缺 `comet-hook-guard.mjs` 这类关键文件会静默破坏 phase guard，必须先修。重跑 `comet init` 或 `comet update` 补齐缺失文件。详见[comet init · 安装摘要怎么看](/zh/cli/init#安装摘要怎么看)。
  </Accordion>

  <Accordion title="写文件时 hook 报 [COMET-HOOK] crash 并退出码 2 怎么办">
    `comet-hook-guard.mjs` 在自身崩溃（bundle 损坏、import 失败、意外抛错）时会**失败闭合**：打印 `[COMET-HOOK] crash: ...` 诊断信息并以退出码 2 阻塞写入，而不是留下模糊的退出码继续放行。这说明 phase guard 本身坏了——通常是安装不完整（缺脚本文件）。先跑 `comet doctor` 检查安装健康，必要时重跑 `comet init`/`comet update` 补齐文件。
  </Accordion>

  <Accordion title="Windows 上能跑吗，还需要 Git Bash 吗">
    0.4.0-beta.1 起所有脚本都通过 Node.js 运行，Windows 不再需要 Bash、Git Bash 或 WSL。macOS、Linux、Windows 用同一套命令。
  </Accordion>

  <Accordion title="项目级和全局安装怎么选">
    project 适合团队项目（配置写入仓库，便于协作），global 适合个人默认环境（写入用户目录，多项目共享）。不确定时先用项目级。详见[comet init](/zh/cli/init)。
  </Accordion>

  <Accordion title="comet init 支持哪些平台">
    31 个 AI 编码平台，包括 Claude Code、Codex、Cursor、Windsurf、GitHub Copilot 等。`comet init` 会自动检测项目里已存在的平台目录并预选。详见[支持的平台](/zh/platforms)。
  </Accordion>
</AccordionGroup>

## 状态与诊断

<AccordionGroup>
  <Accordion title="没有输入 /comet，只说“继续”会发生什么">
    0.4.0-beta.4 起，安装或更新生成的项目说明会让 Agent 先运行只读恢复探测。只有一个明确相关、且不在决策点的 active change 时才会建议恢复；多个 change、未提交改动或请求无关时会先询问或正常回答，不会强行进入 workflow。详见[恢复探测命令](/zh/cli/resume-probe)。
  </Accordion>

  <Accordion title="comet status 和 comet doctor 有什么区别">
    `comet status` 看活跃 change 的当前阶段和下一步命令，是日常恢复的第一条命令。`comet doctor` 做完整的安装健康检查（Skill、脚本、工作目录、change 状态），适合 `status` 显示异常时排查。
  </Accordion>

  <Accordion title="doctor 报 warn 要不要管">
    `warn` 通常不阻塞（如 openspec CLI 未装但项目不依赖），`fail` 才是阻塞（如 Skill 缺失、状态损坏）。建议优先处理 `fail`。详见[comet doctor](/zh/cli/doctor)。
  </Accordion>

  <Accordion title="comet status 显示阶段不对">
    先跑 `comet doctor` 看是否有畸形 `.comet.yaml` 或缺失证据。修复后重新跑 status。状态异常的排查详见[状态损坏与恢复](/zh/guides/state-recovery)。
  </Accordion>
</AccordionGroup>

## 升级与卸载

<AccordionGroup>
  <Accordion title="怎么升级 Comet">
    在项目目录运行更新器，再确认健康：

    ```bash theme={null}
    comet update
    comet doctor
    ```
  </Accordion>

  <Accordion title="卸载会删除我的代码或 OpenSpec change 吗">
    不会。`comet uninstall` 只移除 Comet 管理的 Skill、规则和 hooks，保留你的 OpenSpec change、设计文档、实施计划和项目代码。详见[comet uninstall](/zh/cli/uninstall)。
  </Accordion>

  <Accordion title="update 和 init 该用哪个">
    升级版本后用 `comet update` 刷新 Skill/规则/脚本。`comet init` 用于首次安装或新增平台。两者都非破坏性保留用户配置。
  </Accordion>
</AccordionGroup>

## Skill、评估和发布命令

<AccordionGroup>
  <Accordion title="comet skill 和 /comet-any 该用哪个">
    创建可复用 Skill 优先用 `/comet-any`，它会在内部调用 CLI 后端。`comet skill` 是低层工具，适合本地调试、高级 Skill 运行和包管理。详见[comet skill](/zh/cli/skill)。
  </Accordion>

  <Accordion title="comet eval 和 comet skill check 有什么区别">
    `comet eval` 评估一个 Skill 的产品能力，产出发布前证据。`comet skill check` 检查某次 Skill 运行是否缺 artifact 或状态，不产出发布证据。发布 readiness 只需要 `comet eval`。详见[comet eval](/zh/cli/eval)。
  </Accordion>

  <Accordion title="comet bundle 和 comet publish 该用哪个">
    普通用户用 `comet publish`（用户发布入口）。`comet bundle` 是高级后端，只在排查后端状态、审计或自动化集成时直接使用。详见[comet publish](/zh/cli/publish)。
  </Accordion>
</AccordionGroup>

## CI/CD

<AccordionGroup>
  <Accordion title="CI 里怎么非交互安装">
    用 `--yes --json` 跳过所有提示：

    ```bash theme={null}
    comet init --yes --scope project --language zh --json
    ```
  </Accordion>

  <Accordion title="--json 输出能稳定解析吗">
    能。`status` 和 `doctor` 的 JSON 结构是 CLI 契约的一部分。CI 门禁建议只对 `doctor` 的 `fail` 退出非零。详见[CI/CD 集成](/zh/guides/cicd-integration)。
  </Accordion>
</AccordionGroup>