CLI 常见问题

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

安装与初始化

comet init 会覆盖我现有的配置吗

不会。检测到已存在的组件时，comet init 会让你选择覆盖或跳过。hooks 是非破坏性合并，保留你已有的 hooks。--yes 模式下已存在组件默认跳过，强制刷新用 --overwrite。

Windows 上能跑吗，还需要 Git Bash 吗

0.4.0-beta.1 起所有脚本都通过 Node.js 运行，Windows 不再需要 Bash、Git Bash 或 WSL。macOS、Linux、Windows 用同一套命令。

项目级和全局安装怎么选

project 适合团队项目（配置写入仓库，便于协作），global 适合个人默认环境（写入用户目录，多项目共享）。不确定时先用项目级。详见CLI 快速上手。

comet init 支持哪些平台

31 个 AI 编码平台，包括 Claude Code、Codex、Cursor、Windsurf、GitHub Copilot 等。comet init 会自动检测项目里已存在的平台目录并预选。详见支持的平台。

comet status 和 comet doctor 有什么区别

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

doctor 报 warn 要不要管

warn 通常不阻塞（如 openspec CLI 未装但项目不依赖），fail 才是阻塞（如 Skill 缺失、状态损坏）。建议优先处理 fail。详见comet doctor。

comet status 显示阶段不对

先跑 comet doctor 看是否有畸形 .comet.yaml 或缺失证据。修复后重新跑 status。状态异常的排查详见状态损坏与恢复。

怎么升级 Comet

先升级 npm 包，再刷新已安装的 Skill 文件，最后确认健康：

npm install -g @rpamis/comet@latest
comet update --scope project --language zh
comet doctor

卸载会删除我的代码或 OpenSpec change 吗

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

update 和 init 该用哪个

升级版本后用 comet update 刷新 Skill/规则/脚本。comet init 用于首次安装或新增平台。两者都非破坏性保留用户配置。

comet skill 和 /comet-any 该用哪个

创建可复用 Skill 优先用 /comet-any，它会在内部调用 CLI 后端。comet skill 是低层工具，适合本地调试、Engine Run 和包管理。详见comet skill。

comet eval 和 comet skill eval 有什么区别

comet eval 评估一个 Skill 的产品能力，产出发布前证据。comet skill eval 检查某次 Engine Run 是否缺 artifact 或状态，不产出发布证据。发布 readiness 只需要 comet eval。详见comet eval。

comet bundle 和 comet publish 该用哪个

普通用户用 comet publish（用户发布入口）。comet bundle 是高级后端，只在排查后端状态、审计或自动化集成时直接使用。详见comet publish。

CI 里怎么非交互安装

用 --yes --json 跳过所有提示：

comet init --yes --scope project --language zh --json

--json 输出能稳定解析吗

能。status 和 doctor 的 JSON 结构是 CLI 契约的一部分。CI 门禁建议只对 doctor 的 fail 退出非零。详见CI/CD 集成。