Skip to main content
这页聚焦四类高频问题：安装初始化、状态诊断、升级卸载、以及 Skill 评估发布相关命令。

​
安装与初始化

不会。检测到已存在的组件时，comet init 会让你选择覆盖或跳过。hooks 是非破坏性合并，保留你已有的 hooks。--yes 模式下已存在组件默认跳过，强制刷新用 --overwrite。
该平台有文件复制失败（例如某个 Skill 或脚本文件没装上）。0.4.0-beta.1 起，部分失败会如实标记为 failed 并带失败计数。缺 comet-hook-guard.mjs 这类关键文件会静默破坏 phase guard，必须先修。重跑 comet init 或 comet update 补齐缺失文件。详见comet init · 安装摘要怎么看。
comet-hook-guard.mjs 在自身崩溃（bundle 损坏、import 失败、意外抛错）时会失败关闭：打印 [COMET-HOOK] crash: ... 诊断信息，并用退出码 2 直接阻塞写入。这表示 phase guard 已经不可用，最常见原因是安装不完整（例如关键脚本缺失）。处理顺序建议固定为三步：先运行 comet doctor 确认缺项，再运行 comet init 或 comet update 补齐文件，最后重试原操作。
0.4.0-beta.1 起所有脚本都通过 Node.js 运行，Windows 不再需要 Bash、Git Bash 或 WSL。macOS、Linux、Windows 用同一套命令。
project 适合团队项目（配置写入仓库，便于协作），global 适合个人默认环境（写入用户目录，多项目共享）。不确定时先用项目级。详见comet init。
当前版本支持 37 个 AI 编码平台，包括 Claude Code、Codex、Cursor、Windsurf、GitHub Copilot、Oh My Pi 和 DeepSeek Harness。comet init 会自动检测项目里已存在的平台目录并预选。不同平台支持的 Skill、Rule 和 Hook 能力不同，详见支持的平台。

​
状态与诊断

0.4.0-beta.4 起，安装或更新生成的项目说明会让 Agent 先运行只读恢复探测。只有一个明确相关、且不在决策点的 active change 时才会建议恢复；多个 change、未提交改动或请求无关时会先询问或正常回答，不会强行进入 workflow。详见恢复探测命令。
comet status 用来回答“现在做到哪一步、下一步跑什么”。 comet doctor 用来回答“为什么跑不动、哪里坏了”。实际使用时，可以先看 status，只有出现异常或恢复失败时再跑 doctor 做深度排查。
warn 多数是提醒级问题（例如某个可选依赖缺失），fail 才是阻塞项（例如 Skill 缺失、状态损坏）。排查时先清掉全部 fail，再按影响范围处理 warn。详见comet doctor。
CodeGraph CLI、项目索引、MCP 注册和 Agent 有效能力是四个独立状态。CLI 已安装且索引最新，只能证明项目数据已经准备好；对应 Agent 还需要注册指向 CodeGraph 服务的有效 MCP，才会显示为 effective。运行 comet doctor --json，检查 codegraph.cliStatus、indexStatus、mcpStatus、agents 和 effectiveForAgent。按输出中的实际诊断修复缺失环节，不要因为索引正常就跳过 MCP 检查。
先跑 comet doctor 看是否有畸形 .comet.yaml 或缺失证据。修复后重新跑 status。状态异常的排查详见状态损坏与恢复。
0.4.2 起，只读的 Classic 和 Native 查询会复用一个按需启动的项目级守护进程（daemon），避免每次查询都重新启动 Node。它是项目作用域的，空闲一段时间后自动退出，不可用时 Comet 自动回退到直接执行，不影响结果正确性。可以用以下命令管理：

​
升级与卸载

交互式更新可以更新适用的 npm 包并刷新已经登记项目中的 Skill、Rule、Hook、Runtime 和托管配置。完成后运行 Doctor 确认安装健康：
--current-project、--scope global 或 --json 默认只刷新资产，不更新 npm 包。使用这些限定模式并且需要同时升级 CLI 时，显式添加 --self-update：
RC1 的 Native Portable State、Supervisor、Personal Memory、Project Knowledge 和平台适配都依赖随版本发布的 Runtime 与托管资产，只升级 npm 包但不运行 comet update 会让项目继续使用旧资产。
不会。comet uninstall 只移除 Comet 管理的 Skill、规则和 hooks，保留你的 OpenSpec change、设计文档、实施计划和项目代码。详见comet uninstall。
comet init 用于“第一次装”或“给项目新增平台”。 comet update 用于“版本升级后刷新现有安装”。两者都按非破坏性策略处理已有配置；是否覆盖由你显式选择。

​
Skill、评估和发布命令

创建可复用 Skill 优先用 /comet-any，它会在内部调用 CLI 后端。comet skill 是低层工具，适合本地调试、高级 Skill 运行和包管理。详见comet skill。
comet eval 评估一个 Skill 的产品能力，产出发布前证据。comet skill check 检查某次 Skill 运行是否缺 artifact 或状态，不产出发布证据。发布 readiness 只需要 comet eval。详见comet eval。
普通用户用 comet publish（用户发布入口）。comet bundle 是高级后端，只在排查后端状态、审计或自动化集成时直接使用。详见comet publish。

​
CI/CD

用 --yes --json 跳过所有提示：
能。status 和 doctor 的 JSON 结构是 CLI 契约的一部分。CI 门禁建议只对 doctor 的 fail 退出非零。详见CI/CD 集成。
最后修改于 2026年9月21日