doctor

OrchestKit 健康诊断

与宿主无关的工作流。通过技能名称（doctor）调用。Claude Code 斜杠路由、YAML 钩子加载器和 .claude/chain 详见 references/claude-code.md。

参数解析

FLAGS = "$ARGUMENTS"         # Full argument string, e.g., "--verbose" or "--json"
FLAG = "$ARGUMENTS[0]"       # First token: -v, --verbose, --json, --category=X
# $ARGUMENTS[0], $ARGUMENTS[1] for indexed access (CC 2.1.59)

步骤 0：选择范围（AskUserQuestion — M118 #1464）

完整的诊断运行约需 20 秒。大多数调用只需要检查一个部分。请预先询问用户，以便将语音快捷请求（例如“只检查 MCP”）准确对应到相应范围：

# Skip the prompt when an explicit scope arg or env override is present:
#   doctor cc      → skip, use cc-only
#   doctor mcp     → skip, use mcp-only
#   doctor plugin  → skip, use plugin-only
#   ORK_DOCTOR_SCOPE=all (or any of the above) → skip, use the env value
#
# Otherwise, ask:
AskUserQuestion(questions=[{
  "question": "What should doctor check?",
  "header": "Scope",
  "options": [
    {"label": "Everything (default)", "description": "Full system health — ~20s; runs all 15 categories"},
    {"label": "CC version & features only", "description": "Categories 10 + 13 + 14; ~3s — for 'is my CC up to date?'"},
    {"label": "MCP servers only", "description": "Category 12 (incl. pinning sub-check); ~5s — for 'are MCPs working?'"},
    {"label": "Plugin health only", "description": "Categories 0-3 + 5 (skills, agents, hooks, build); ~8s — for 'after npm run build'"}
  ]
}])

如果调用内容已明确指定范围，则完全跳过提示。快速范围只需 3–8 秒，比完整运行快 3–7 倍——语音用户说“只检查 MCP”，即可在 5 秒内得到答复。

概览

doctor 命令会对 OrchestKit 安装执行全面的健康检查。它会自动检测已安装的插件并验证 16 个类别：

1. 已安装的插件 - 检测 ork 插件
2. 技能验证 - Frontmatter、引用、令牌预算（动态计数）
3. Agent 验证 - Frontmatter、工具引用、技能引用（动态计数）
4. 钩子健康状况 - 注册、捆绑包、异步模式
5. 权限规则 - 检测无法触达的规则
6. 架构合规性 - 根据架构验证 JSON 文件
7. 协调系统 - 检查锁健康状况和注册表完整性
8. 上下文预算 - 监控令牌用量与预算的对比情况
9. 记忆系统 - 图记忆健康状况
10. Claude Code 版本 - 验证 Claude Code 版本是否 >= shared/cc-support.json 中的 supported_floor（请读取该文件；它是唯一事实来源）。旧版“建议使用 2.1.154+”说明所涵盖的全部功能（xhigh 推理强度、/ultrareview、stream-json plugin_errors）现在都由最低支持版本保证，因此不再需要任何建议
11. 外部依赖项 - 检查可选工具是否可用（agent-browser），并针对从其他市场安装的每个同级技能输出一行：通过 scripts/check-peer-skill.py，将 typesafe@typesafe-ai 的已安装版本与市场版本进行比较（市场缺失和插件缺失是两种不同的判定结果；修复说明会给出供应商的更新命令；#4233）
12. MCP 状态 - 检查活跃、已禁用和配置错误的 MCP，以及付费 MCP 的 API 密钥是否存在。CC 2.1.110：检测不同配置范围内的重复定义。子检查会在 .mcp.json 中的 HIGH 级服务器解析为 @latest 时发出警告（修复 #1462）
13. 插件验证 - 运行 claude plugin validate，验证官方 CC frontmatter 和 hooks.json（CC >= 2.1.77）
14. 推理强度/模型兼容性 - 仅在配置了 xhigh 推理强度，且可确定当前模型无法运行时发出警告。其他情况保持静默，因为回退本身也是静默的
15. 沙盒配置状态 - 检查所有四个设置范围内 CC Bash 沙盒的开启/关闭状态（包括 ~/.claude/settings.json，实际配置通常位于此处），并提示使用 /sandbox；子检查 15b 查询 macOS 统一日志中的近期沙盒拒绝事件（失败时默认拒绝：日志查询被拒时报告 UNOBSERVABLE，而不是 0）
16. 操作员设置状态 - 检测插件捆绑包无法包含的安全控制项（凭据读取拒绝规则、sandbox 块、CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS），因此除非操作员将其写入自己的设置，否则这些控制项会缺失

适用场景

• 安装或更新 OrchestKit 后
• 钩子未按预期触发时
• 部署到团队环境之前
• 调试协调问题时
• 运行 npm run build 后

快速开始

doctor           # Standard health check
doctor -v        # Verbose output
doctor --json    # Machine-readable for CI

CLI 选项

标志	说明
-v、--verbose	显示每项检查的详细输出
--json	输出 JSON，供 CI 集成使用
--category=X	仅运行指定类别

健康检查类别

详细检查流程：加载 Read("rules/diagnostic-checks.md")，查看各类别对应的 bash 命令和验证逻辑。

MCP 专项检查：加载 Read("rules/mcp-status-checks.md")，查看凭据验证和错误配置检测。

输出示例：加载 Read("references/health-check-outputs.md")，查看各类别的示例输出。

类别 0-3：核心验证

类别	检查内容	参考
0. 已安装插件	自动检测 ork 插件，并统计技能/Agent 数量	load rules/diagnostic-checks.md
1. 技能	Frontmatter、context 字段、令牌预算、链接、激活渠道可达性（没有孤立的用户可调用技能）	load references/skills-validation.md
2. Agent	Frontmatter、模型、技能引用、工具引用	load references/agents-validation.md
3. 钩子	hooks.json 架构、bundles、异步模式——涵盖三种钩子作用域：全局、Agent 作用域和技能作用域。检测常见钩子问题：文件缺失（已注册但磁盘上不存在）、hooks.json 或 bundles 中有语法错误、权限问题（脚本不可执行）以及过时引用（条目指向已重命名/移除的处理程序）	load references/hook-validation.md

**激活渠道孤岛（仓库 / 预发布版）：**用户可调用的技能应当能通过不止人工输入来触达——可以通过调用链（其他技能引用 /ork:<skill>）、子 Agent 授权（src/agents/*.md 中的 skills:），或后台触发器。如果某个技能没有任何渠道，它就是一座会悄然腐朽的“孤岛”。在仓库检出目录中，运行 npm run test:manifests:channels（由 CI 中的 test:manifests 门控）。修复孤岛的方法是接入任意一个渠道，或将其加入 STANDALONE_ALLOWLIST 并说明理由。

类别 4-5：系统健康

类别	检查内容	参考
4. 记忆	.claude/memory/ 图完整性及队列深度；自动记忆 MEMORY.md 索引预算；各 Agent 的 .claude/agent-memory/NAME/MEMORY.md（孤立项、陈旧项、150 行警告、机密信息/个人身份信息）	load references/memory-health.md and references/agent-memory-dir.md
5. 构建	plugins/ 与 src/ 同步情况、清单数量、孤立项	load rules/diagnostic-checks.md

**分析数据写入器存活状态（系统健康）：**本地分析数据管道在 ~/.claude/analytics/ 下有多个彼此独立的 JSONL 写入器（skill-usage、agent-usage、hook-timing）。某个写入器可能会静默失效，而其他写入器仍正常写入——曾有一次观察到 skill-usage.jsonl 连续四个月出现此情况（2026-03 至 2026-07）。该检查采用同级文件对比：标记最后写入时间距今 ≥48h、而同级文件在 24h 内有写入的所有受监控文件（stat -f '%m %N' ~/.claude/analytics/*.jsonl）。lifecycle/analytics-liveness-check SessionStart 钩子会持续执行相同的对比。

被标记的写入器意味着写入路径已从分发流程中移除，因此要检查两个位置——src/hooks/hooks.json 和条目映射（src/hooks/src/entries/*.ts）。钩子只存在于其中一处时，会显得已注册，实际上却已静默失效：这属于 #959 故障类型。telemetry-inspect 可深入检查各文件，覆盖此结构检查无法发现的字段级缺陷：常量字段和虚假行，这两类问题已在 #3034 和 #3035 中修复（两项均于 2026-07-20 关闭）。请将它们作为先例引用，而非未完成事项。

(本文件中的类别编号与上方概览列表不一致：概览将 4 编为钩子健康，而表格将 4 编为记忆。无论读者采用哪套编号，此检查都属于系统健康。)

类别 6-9：基础设施

类别	检查内容
6. 权限规则	检测无法触发的规则
7. 架构合规性	检查 JSON 文件是否符合架构
8. 协调	多工作树锁的健康状况、过期锁、稀疏路径配置
9. 上下文预算	检查令牌用量是否超出预算

类别 10-16：环境

类别	检查内容	参考
10. CC 版本	运行时版本是否满足最低要求	加载 references/version-compatibility.md
11. 外部依赖项	可选工具（agent-browser、portless）	加载 rules/diagnostic-checks.md
12. MCP 状态	启用/禁用状态、凭据检查、HIGH 级别的 @latest 固定版本警告	加载 rules/mcp-status-checks.md + references/mcp-pinning-check.md
13. 插件验证	官方 CC frontmatter 和 hooks.json 验证（CC >= 2.1.77）	加载 rules/diagnostic-checks.md
14. Effort/模型	在已确定无法运行该配置的模型上设置了 xhigh effort（见下文）。默认不提示	内联
15. 沙盒状态	检查 CC Bash 沙盒在全部四个设置范围内的启用/关闭状态，并提示使用 /sandbox（可选启用，仅限 Bash；信息级）。15b：通过 scripts/check-sandbox-violations.sh 对 macOS 统一日志进行有界只读查询，检查近期的 Sandbox 拒绝事件（警告级；若日志查询本身被拒绝，则默认安全关闭；非 macOS 系统会明确跳过）	加载 references/sandbox-posture.md
16. 操作员设置状态	插件包无法携带的控制项，因此只有操作员自行写入后才会存在：读取凭据的 permissions.deny 规则（纵深防御：pretool/read/credential-read-guard 已覆盖 Read 工具）、sandbox 块（包括 network.deniedDomains；出口防护只会对上传特征发出 ask，普通 GET 则不处理），以及 CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS（ork 自己的 agent-teams.ts 会检查此项）。从 CC 2.1.257 起，还会报告 permissions.blockReadsOutsideWorkingDirectories，并在其值为 true 且 additionalDirectories 中未包含 ~/.claude 时发出警告（ork 技能在项目目录之外执行的读取会被拒绝，而非提示）。从 #3877 起，还会指出项目级别的 sandbox.enabled: false 覆盖用户级别的 true（sandbox_override，项目文件:行号和用户文件:行号；项目文件优先，Bash 将在无沙盒环境下运行）。从 #3835 起，审计改为使用脚本：bash ${CLAUDE_SKILL_DIR}/scripts/check-operator-permissions.sh <project_dir> --json（所有有效负载规则均已强制执行时退出码为 0；有规则缺失并提供修复方法时为 1；无法观察时为 2）；修复方法见设置阶段 3.6，需经用户同意。警告级；输出可供粘贴的 JSON	加载 references/settings-posture.md

检查 16 的由来：plugins-reference.md:858 指出，插件附带的 settings.json 中“目前仅支持 agent 和 subagentStatusLine 键”。ork 过去在其中声明的其他所有内容都不起作用，因此看似随插件提供的保护从未生效。检查 16 是替代方案：检测 CC 实际读取的范围内是否存在缺项，然后向操作员提供准确的 JSON。ork:configure 技能中的 操作员范围设置 章节提供了可直接粘贴的代码块，并按照 #3424 的要求分阶段从宽松设置逐步收紧；完整 JSON 位于 ../configure/references/operator-scope-settings.md。

类别 14：Effort/模型兼容性（CC 2.1.111+）

CC 2.1.111 新增了 xhigh effort 层级。本类别存在的唯一原因是缺少提示：不支持 xhigh 的模型会静默地将请求降级为 high，没有错误、警告或日志记录，因此相关技能文档所述的额外深入处理轮次会丢失，且不会有任何可见信号。如果 CC 以后会提示降级情况，请删除本类别。

检查应当基于能力，而非模型名称。此处绝不要硬编码“当前的前沿模型”：新模型一发布，这就必然导致误报，而且会建议降级到已被取代的模型。

不要通过 src/hooks/src/lib/models.vocab.json 执行此检查。 该文件是模型 ID / 定价词汇表，完全不包含 effort 或能力字段，因此依赖它进行判断，会让此检查永久意外失效，而不是有意保持静默。

检测（仅在有确凿证据时发出警告）：

1. 按以下顺序解析已配置的 effort：.claude/settings.json → effort，然后是 $ORCHESTKIT_EFFORT（由 effort-detector hook 填充），最后是任何明确设置了 effort: xhigh 的 .claude/chain/*.json 条目。任何地方都没有 xhigh，则通过，不输出内容。
2. 解析当前活动的模型 ID。
3. 仅当该模型 ID 与 doctor 下方本地 XHIGH_UNSUPPORTED_PREFIXES 表中的前缀匹配时，才发出警告。其他所有情况（模型不在表中、无法解析模型 ID、设置文件缺失）均视为通过。无法确证问题的检查应保持静默。

# Doctor-local capability table. Deliberately a DENY-list, not an allow-list:
# a model absent from this table is assumed to support xhigh and emits nothing.
# Add an entry only from an OBSERVED silent degrade, citing the CC version it was
# seen on. Never add one by inferring from a model being new, old, or cheap.
XHIGH_UNSUPPORTED_PREFIXES = [
    # prefix        evidence
    "claude-3-",  # the whole Claude 3 line predates CC 2.1.111, which introduced the tier
]

表格为空或条目很少，才是正确的默认状态。此处保持静默，表示“doctor 无法确认存在问题”，这是真实的陈述；而对无法识别的模型按名称匹配并判定失败，则是错误的。

警告格式（不硬编码模型名称，双方均在运行时读取）：

WARNING: effort is set to `xhigh`, but <model-id> matches XHIGH_UNSUPPORTED_PREFIXES.
  Configured effort: xhigh (source: <settings.json | $ORCHESTKIT_EFFORT | chain>)
  Impact: the run degrades to `high` with no error and no log line, so the extra
          deepening pass is lost with nothing to notice it by.
  Fix: run this on a model that implements `xhigh`, or set effort to `high` so the
       config matches what actually executes.

退出代码：仅当实际触发警告时，--json 模式才返回非零退出代码；交互模式下发出软警告。静默通过时，退出代码为 0。

报告格式

每个类别都会明确报告通过 / 警告 / 失败状态；每条警告或失败都会附上具体修复步骤，说明应运行的确切命令、应编辑的文件或应更改的配置——doctor 既诊断，也提供解决方案，绝不只罗列问题。

加载 Read("references/report-format.md")，查看 ASCII 报告模板、JSON CI 输出架构和退出代码。

解读结果与故障排查

加载 Read("references/remediation-guide.md")，查看完整的结果解读表，以及技能验证、构建同步和记忆方面常见故障的排查步骤。

使用 --safe-mode 进行二分排查（CC 2.1.169+）： 当 doctor 的检查结果无法解释会话为何异常时，请使用 claude --safe-mode（或 CLAUDE_CODE_SAFE_MODE=1）重启——此模式会禁用所有自定义项（CLAUDE.md、包括 ork 在内的插件、技能、hooks、MCP）。如果问题消失，原因就在自定义项；逐半重新启用以隔离问题。如果问题仍然存在，原因就在 CC 本身——请向上游提交问题。

主机负载与会话负载（macOS）： 当 doctor 的检查结果显示会话运行正常，但机器速度很慢时，不要根据 memory_pressure 的“系统可用内存百分比”来判断：它曾显示可用内存为 84%，但实际已使用 64 GB 中的 59 GB，且交换空间已占用 8 GB 中的 6.9 GB；仅凭这个数字首先认定的罪魁祸首并不正确（实际负载来自另一个项目中的测试套件）。在归因之前先查看证据：使用 sysctl vm.swapusage 检查交换空间，使用 vm_stat 查看内存分布，并使用按内存用量排序的进程视图（例如 ps aux | sort -nrk 4 | head）确认实际占用内存的进程。

修复问题后

CC 2.1.69+：运行 /reload-plugins，无需重启即可在当前会话中激活插件更改。

CC 2.1.116+：/reload-plugins 和后台插件自动更新现在会从你已添加的市场中自动安装缺失的插件依赖项。如果 ork:doctor 标记了因缺少依赖项导致的插件加载失败，/reload-plugins 会就地解决问题，无需手动执行 plugin install。

CC 2.1.152+：对于技能目录（~/.claude/skills/ 或 .claude/skills/）中的非插件技能，运行 /reload-skills，即可无需重启重新扫描；它相当于技能版的 /reload-plugins。

CC 2.1.268+：/plugin 的安装、启用和停用操作会在菜单关闭时生效，因此之后不再需要运行 /reload-plugins。

链路：深入审计

健康检查报告无异常后，审计可观测性管道本身：

telemetry-inspect

doctor 会验证结构（清单、钩子、技能、Agent）；telemetry-inspect 会验证数据平面——每个遥测写入器的行数、架构锁定状态、增长趋势，以及结构检查无法覆盖的孤立分析文件。

相关技能

• ork:configure - 配置插件设置
• ork:telemetry-inspect - 结构检查无异常后审计遥测／分析管道
• ork:quality-gates - CI/CD 集成
• security-scanning - 全面审计

参考资料

按需使用 Read("references/<file>") 或 Read("rules/<file>") 加载：

文件	内容
rules/diagnostic-checks.md	各类别对应的 Bash 命令和验证逻辑
rules/mcp-status-checks.md	凭据验证和错误配置检测
references/remediation-guide.md	结果解读和故障排除步骤
references/health-check-outputs.md	各类别的示例输出
references/skills-validation.md	技能 frontmatter 和结构检查
references/agents-validation.md	Agent frontmatter 和工具引用检查
references/hook-validation.md	钩子注册和捆绑包检查
references/memory-health.md	记忆系统完整性检查
references/agent-memory-dir.md	每个 Agent 的 agent-memory 目录：孤立项、过时项、150 行警告、机密信息
references/permission-rules.md	权限规则检测
references/skill-preapproval.md	在托管的 allowManagedPermissionRulesOnly 下，allowed-tools 预先授权会失效的技能（CC 2.1.282、2.1.284）；检测和管理员补救措施
references/schema-validation.md	JSON 架构合规性
references/report-format.md	ASCII 报告模板和 JSON CI 输出
references/version-compatibility.md	CC 版本和通道验证
references/mcp-pinning-check.md	高等级 MCP @latest 警告逻辑及等级信息的权威来源
references/sandbox-posture.md	CC Bash 沙盒启用／停用检测、/sandbox 提醒（检查 15）和统一日志违规查询（15b）
references/settings-posture.md	操作者范围的安全态势：插件捆绑包无法包含的内容，以及如何检测其缺失（检查 16）