comet doctor 用来定位“为什么 Comet 现在跑不动”。
它会检查安装环境、CLI 与依赖、项目目录、Skill/Rule/Hook、Runtime、CodeGraph，以及当前 change 状态。可以把它理解成环境与现场体检：comet status 负责告诉你流程位置，comet doctor 负责告诉你故障位置。
默认检查是只读的，不会因为诊断而修复或改写项目。只有显式使用 --repair 时，才会执行支持的修复动作。
CodeGraph 部分会分成四项独立结果：CLI 安装状态、项目索引状态、MCP 注册状态、以及各 Agent 的 effective 能力。索引最新只说明数据已经同步，不等于 Agent 一定能用 CodeGraph；需要精确定位时请查看 JSON 里的 codegraph 对象。
基本用法
先看文本输出
例如，在项目级 Skill 尚未安装、Classic 根目录缺失、CodeGraph 还有待同步内容时，comet doctor --scope project 会打印：
✓：该项检查通过，不需要处理。⚠：发现警告或可选组件缺失。多数情况下可以继续，但建议按输出提示尽快补齐。✗：该项检查失败。优先处理这一行及其run:后面的命令。
docs/openspec/，但目录不存在。先运行 comet classic root show 查看实际配置，再恢复该目录或使用 comet classic root move。current selection: no active Comet change 不是错误，只表示当前没有选中的 Comet change。
检查哪些问题
输出中的每一行对应一类检查：选择检查范围
--scope auto：默认值。先检查当前项目；如果项目没有完整安装，再检查可用的全局安装。--scope project：只检查当前项目，适合确认项目是否已经完成本地初始化。--scope global：只检查全局安装，适合排查全局 Skill、Rule、Hook 或 Runtime。
--scope auto 会报告全局安装可用，并把项目级副本视为可选项。只有当项目需要自己的 Comet 配置和 Skill 副本时，才运行：
JSON 输出怎么看
需要自动化处理时，使用：healthy: false 表示至少有一项 fail；具体处理方式在 results[].message 中。status: passed 且 healthy: true 才表示本次诊断没有失败项。runtime 和 codegraph 字段还会提供 Runtime 来源和 CodeGraph 的详细状态。
codegraph 对象包含 cliStatus、indexStatus、mcpStatus、agents 和 effectiveForAgent。只有 CLI 已安装、项目索引最新，并且对应 MCP 配置指向 CodeGraph 服务时，该 Agent 才会被标记为 effective。
什么时候使用 --repair
先运行不带 --repair 的 comet doctor，确认问题和建议动作。只有输出明确指向修复，或者你已经确认要修复 Comet 管理的 Hook、Rule、selection 或迁移现场时，才运行：
--repair 会执行写操作。Classic 根目录迁移中断时，根据现场选择 continue 或 rollback；涉及 CodeGraph 等需要你确认的项目修复时，再加 --yes。如果只想重新检查，请省略 --repair。