skill-doctor

主机：Codex CLI — 此技能为 Claude Code 设计，并已适配 Codex。 交叉引用命令在 Codex 中使用已安装的技能名称，而不是 /octo:* 斜杠命令。 使用当前活动的 Codex shell 和子 Agent 工具。在当前会话明确提供之前，不要声称某个提供方、模型或主机子 Agent 可用。 主机工具的对应项请参阅 skills/blocks/codex-host-adapter.md。

环境诊断

概述

在 15 个检查类别中运行环境诊断。Doctor 2.0 可识别配置错误的提供方、已加载或缓存的过时插件版本、无效的插件组装、不可写的状态目录、非终止状态的运行记录、孤立进程证据、损坏的钩子，以及其他导致 Claude Octopus 无法正常工作的 问题。

核心原则： 在问题影响工作流之前发现它们。

何时使用

在以下情况下使用此技能：

• 某些功能无法正常工作，但你不确定原因
• 安装或更新插件后
• 演示或重要工作流运行前
• 检查提供方是否已正确完成身份验证
• 验证调度程序、钩子或技能是否配置正确

请勿用于：

• 首次设置（使用 /octo:setup — 它会引导你完成配置）
• 项目工作流状态（使用 /octo:status）
• 调试应用代码（使用 /octo:debug）

流程

第 1 步：解析插件根目录并运行完整诊断

运行 Octopus 脚本前，请使用此解析器。优先使用当前活动的主机根目录， 然后是稳定根目录或已安装的 CLI。收集诊断信息时，不要创建或替换稳定 链接。将其作为单次 Bash 调用运行。

OCTO_PLUGIN_ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-}}"
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="${HOME}/.claude-octopus/plugin"
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]] && command -v octopus >/dev/null 2>&1; then
  OCTO_BIN="$(command -v octopus)"
  OCTO_LINK_HOPS=0
  while [[ -L "$OCTO_BIN" ]]; do
    OCTO_LINK_HOPS=$((OCTO_LINK_HOPS + 1))
    if [[ "$OCTO_LINK_HOPS" -le 40 ]]; then
      OCTO_BIN_DIR="$(cd -P "$(dirname "$OCTO_BIN")" 2>/dev/null && pwd -P)" || { OCTO_BIN=""; break; }
      OCTO_LINK_TARGET="$(readlink "$OCTO_BIN")" || { OCTO_BIN=""; break; }
      case "$OCTO_LINK_TARGET" in
        /*) OCTO_BIN="$OCTO_LINK_TARGET" ;;
        *) OCTO_BIN="$OCTO_BIN_DIR/$OCTO_LINK_TARGET" ;;
      esac
    else
      OCTO_BIN=""
      break
    fi
  done
  if [[ -n "$OCTO_BIN" ]]; then
    OCTO_BIN_DIR="$(cd -P "$(dirname "$OCTO_BIN")" 2>/dev/null && pwd -P)" || OCTO_BIN_DIR=""
    [[ -z "$OCTO_BIN_DIR" ]] || OCTO_PLUGIN_ROOT="$(cd "$OCTO_BIN_DIR/.." 2>/dev/null && pwd -P)"
  fi
fi
if [[ ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  OCTO_PLUGIN_ROOT="$(
    find "${HOME}/.claude/plugins" -type f -path "*/scripts/orchestrate.sh" -print 2>/dev/null \
      | sed 's#/scripts/orchestrate.sh$##' \
      | { grep -E '(nyldn-plugins|claude-octopus|/octo(/[0-9]|$))' || true; } \
      | sort \
      | tail -1
  )"
fi
if [[ -z "$OCTO_PLUGIN_ROOT" || ! -x "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" ]]; then
  echo "Claude Octopus plugin root not found. Reinstall the octo plugin, then retry doctor diagnostics."
  exit 1
fi
export OCTO_PLUGIN_ROOT
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose

此操作会运行全部 15 个检查类别，并显示格式化报告。安装类别会报告稳定根目录缺失或不匹配，但不会修复它。

第 2 步：按类别筛选（可选）

如果用户询问特定方面的问题，请重复使用第 1 步中的解析器，并将其最后的 doctor --verbose 调用替换为以下某一行。这些是替换行，并非独立的 shell 调用；必须在同一次 Bash 调用中解析 OCTO_PLUGIN_ROOT。

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor providers
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor providers --live
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor companions
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor config
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor updates
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor state
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor smoke
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor hooks
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor scheduler
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor skills
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor conflicts
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor agents
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor recurrence
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor cache
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor installation

第 3 步：检查并安装依赖项

重复使用第 1 步中的解析器，并将其最后的调用替换为依赖项检查器，以查找缺失的 CLI、状态栏配置和推荐插件：

bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" check

如果检查报告缺少依赖项，请提出为用户安装：

bash "$OCTO_PLUGIN_ROOT/scripts/install-deps.sh" install

此操作会自动安装 Codex CLI、jq 和状态栏解析器。它会检测并报告 Antigravity CLI（agy）的设置情况，并提供安装指引。对于插件（claude-mem、document-skills），它会打印用户必须手动运行的 /plugin install 命令。

第 4 步：详细或 JSON 输出

如上所述，将这些内容作为第 1 步解析器调用的最后一行运行：

# Detailed output for troubleshooting
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --verbose

# Machine-readable output
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --json

# Combine: specific category + verbose
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth --verbose

Doctor 2.0 的 JSON 始终采用以下外层结构：

{
  "schema_version": "10.0",
  "summary": {"passed": 0, "warnings": 0, "failures": 0, "exit_code": 0},
  "results": []
}

状态为 fail 的检查会将 summary.exit_code 和进程退出码都设为 1，同时 stdout 仍为有效 JSON。警告会保留为结构化内容，但不会导致命令失败。未知标志、未知类别和多个类别参数都属于用法错误，退出码为 2；不要因此改为重试完整扫描。

providers --live 变体是明确且范围有限的 AGY 能力检查。它会发出一个小型真实请求，以验证 CLI 版本、实时模型目录和密钥环身份验证、已配置模型以及打印模式分派。不要在启动钩子或常规预检中运行它。如果目录或身份验证阶段失败，请告知用户启动普通的 agy 并完成浏览器登录；AGY 没有单独的登录 shell 子命令。在 macOS 上遇到密钥环错误时，请引导用户前往“钥匙串访问”、Antigravity CLI 项目及其“访问控制”设置。

第 5 步：交互式修复（可修复的问题必须执行）

运行诊断后，如果发现任何可修复的问题，必须使用 AskUserQuestion 提供修复选项。不要只打印操作说明。应提供执行修复的选项。

稳定根目录修复范围有限，且需要明确授权。首先显示 拟议的更改：

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" repair --dry-run

只有在用户授权执行该项确切修复后，才能运行：

bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" repair --apply

绝不要在解析器中重新创建稳定链接，也不要将其作为 doctor 自动执行的后续操作。清理缓存、清理过期 PID、登录、安装软件包和更新插件也都需要明确确认。

在执行每项获准的修复前，重述确切的目标和操作。配置修复必须使用经过验证的同级临时文件并通过原子重命名完成；如果任何步骤失败，应保留原文件并报告失败。清理缓存、清理过期 PID、登录、安装软件包和更新插件始终需要明确确认。修复后，先仅重新检查受影响的类别，然后再提供完整扫描选项。

未安装 RTK：

AskUserQuestion({
  questions: [{
    question: "RTK saves 60-90% on bash output tokens. Install it now?",
    header: "Install RTK",
    multiSelect: false,
    options: [
      {label: "Install via brew (Recommended)", description: "brew install rtk — fast, macOS"},
      {label: "Install via cargo", description: "cargo install rtk-token-killer"},
      {label: "Skip", description: "Continue without RTK"}
    ]
  }]
})

如果用户选择安装，则运行安装，然后提供配置钩子的选项。

已安装 RTK，但在 macOS/Linux 上尚未配置钩子：

在 Windows Git Bash 上，不要提供 rtk init -g 选项。RTK 在此环境中使用 CLAUDE.md 注入模式，因此应报告已跳过钩子检查。

AskUserQuestion({
  questions: [{
    question: "RTK is installed but the Claude Code hook isn't active. Configure it?",
    header: "RTK Hook",
    multiSelect: false,
    options: [
      {label: "Run rtk init -g (Recommended)", description: "Auto-installs Claude Code bash hook on macOS/Linux"},
      {label: "Skip", description: "I'll configure it later"}
    ]
  }]
})

缺少可选提供方：

AskUserQuestion({
  questions: [{
    question: "Some providers are missing. Install them?",
    header: "Providers",
    multiSelect: true,
    options: [
      {label: "Codex CLI", description: "npm install -g @openai/codex"},
      {label: "Antigravity CLI", description: "Install agy, then verify with agy --version && agy models"},
      {label: "Skip all", description: "Continue with available providers"}
    ]
  }]
})

身份验证已过期： 提供为已过期的提供方运行登录命令的选项。

**存在多个可修复问题：**适当时使用 multiSelect，将它们合并到一个 AskUserQuestion 中，而不是逐一询问。

检查类别

类别	检查内容
providers	Claude Code 版本、是否已安装 Codex CLI、是否已安装 Antigravity CLI、Perplexity API 密钥、本地 Ollama 大模型（服务端 + 模型）、断路器状态、提供方回退历史
companions	可选的配套工具和集成
auth	各提供方的身份验证状态
config	插件版本、安装范围、功能标志、严格的 claude plugin validate 结果
updates	已加载、已安装、目录和缓存版本；Claude 市场自动更新；是否需要重新加载
state	项目 state.json、工作区和探测缓存的可写性、过期结果、未结束的运行、孤立和过期 PID 证据
smoke	冒烟测试缓存、模型配置
hooks	hooks.json 有效性、钩子脚本
scheduler	调度器守护进程、作业、预算限制、终止开关
skills	已加载且有效的技能文件
conflicts	冲突插件检测
agents	Agent 定义、工作树隔离、CLI 注册、版本兼容性
recurrence	故障模式检测——标记重复的质量门失败、源代码热点、48 小时趋势
cache	缓存大小、新鲜度和整洁度
installation	已加载的插件根目录、稳定根目录、限定主机范围的安装元数据和上下文配置文件

软件依赖项的安装情况由第 3 步中的 scripts/install-deps.sh check 单独检查，包括 Node.js、jq、提供方 CLI、 RTK 令牌压缩、状态栏解析器和推荐插件。

结果解读

健康状态输出

所有检查均通过——无需采取任何操作。

常见问题及修复方法

问题	修复方法
找不到 Codex CLI	npm install -g @openai/codex，或通过 codex login 安装
找不到 Antigravity CLI	安装 agy，然后通过 agy --version 和 agy models 验证
未配置 Perplexity	export PERPLEXITY_API_KEY="pplx-..."（可选）
身份验证已过期	重新运行 codex login；对于 AGY，启动普通的 agy 并完成浏览器登录
断路器处于 OPEN 状态	提供商连续发生了 3 次或更多瞬时故障——等待冷却，或检查提供商状态
状态过时	删除 .octo/state.json 并重新初始化
hooks.json 无效	检查 hooks.json 语法——必须是有效的 JSON
未安装 RTK	提供安装选项：brew install rtk && rtk init -g（可节省 60-90% 的 token）。使用 AskUserQuestion 提供 brew 或 cargo install 选项。
已安装 RTK，但未配置钩子	在 macOS/Linux 上，提供 rtk init -g；在 Windows Git Bash 上，说明已跳过，因为 RTK 使用 CLAUDE.md 注入模式
RTK 增益统计不可用	先运行一些 bash 命令，然后检查 rtk gain 以查看 token 节省情况
插件冲突	卸载冲突插件或调整作用范围

与其他技能集成

场景	处理方式
Doctor 发现缺少提供商	建议使用 /octo:setup 进行配置
Doctor 发现项目状态过时	建议使用 /octo:status 进行检查
Doctor 发现钩子错误	指导用户修复 hooks.json
所有检查均通过，但用户仍遇到问题	建议使用 /octo:debug 进行深入调查

上下文和强度配置

安装报告会显示两个可选的上下文设置：

• OCTOPUS_CONTEXT_PROFILE 用于选择 core、orchestration 或 full 上下文 行为。octopus profile 命令会读取和写入此设置。
• OCTOPUS_HOOK_PROFILE 可使用 core、orchestration 或 full 覆盖可选的上下文钩子配置。

这些设置仅控制可选的上下文工作，绝不会禁用安全或生命周期钩子。钩子配置注册表缺失或无效时，将默认拒绝。

OCTO_PROFILE 是单独的旧版强度设置，其值为 budget、 balanced 和 quality。它不等同于任何一个上下文设置，也不得用来声称安全钩子已禁用。

旧版强度配置

某些较旧的工作流路径会将 OCTO_PROFILE 用作强度设置，用于模型选择、跳过阶段和控制上下文详细程度。此设置与上文的可选上下文钩子配置相互独立。

Doctor 检查内容

• 上下文配置：OCTOPUS_CONTEXT_PROFILE 的值，默认为 core
• 可选钩子配置：若设置了 OCTOPUS_HOOK_PROFILE，则使用其值；否则使用上下文配置
• 旧版强度：旧版工作流读取时使用的 OCTO_PROFILE
• 钩子控制：仅控制可选上下文钩子；安全和生命周期钩子保持启用
• 模型提示：每个阶段推荐使用的模型（sonnet/opus）
• 上下文详细程度：精简/标准/完整

旧版强度摘要

维度	budget	balanced	quality
模型	全程使用 Sonnet	使用 Sonnet，综合阶段使用 Opus	大多数阶段使用 Opus
阶段	提供上下文时跳过 discover	跳过重新发现	运行所有阶段
上下文	精简	标准	完整内联

可选上下文配置摘要

维度	core	orchestration	full
可选上下文钩子	关闭	仅工作流上下文	所有由配置管理的上下文钩子
安全和生命周期钩子	启用	启用	启用

项目层级提示

如果设置了 OCTO_TIER，也请报告。这只是建议提示，并非强制策略。

层级	Doctor 指引
prototype	优先采用更快的检查，并在高成本的提供方扇出操作前发出警告
mvp	使用均衡的默认设置，并对高风险更改采用共识机制
production	建议进行完整验证、安全审查，并设置更严格的发布门槛

如果未设置，请显示 OCTO_TIER=unset，并建议仅在项目风险状况稳定后再设置。

远程会话检查

如果 CLAUDE_CODE_REMOTE=true 或 OCTOPUS_REMOTE_SESSION=true，请报告：

• 检测到远程会话
• 未显式设置自主模式时，默认启用自主模式
• 跳过提供方探测以节省时间和配额
• 除非设置了 OCTOPUS_REMOTE_STATUSLINE=full，否则禁用完整 HUD
• 可能需要在云端设置脚本中安装提供方 CLI

仅建议使用 /octo:setup 获取配置指引；不要建议在远程会话中交互式登录提供方。

运行时上下文

Doctor 会检查项目级 RUNTIME.md——该文件为编排提示词提供特定于项目的上下文（API 端点、环境变量、测试命令、构建步骤）。

Doctor 检查内容

• 项目根目录中是否存在 RUNTIME.md（也会检查 .octopus/RUNTIME.md 和 .claude-octopus/RUNTIME.md）
• 如果缺失，建议根据模板创建：cp "${HOME}/.claude-octopus/plugin/config/templates/RUNTIME.md" ./RUNTIME.md
• 如果存在，确认其中至少有一个已填写的部分（而不只是模板默认内容）

重要性

没有 RUNTIME.md，编排提示词就缺少特定于项目的详细信息，导致对测试命令、环境变量和构建步骤的建议泛泛而谈。填写完整的 RUNTIME.md 能让每个工作流都更加准确。

快速参考

为保留 Claude Code 原生的 /doctor 命令，/octo:doctor 已在 v9.41.0 中移除。 请显式调用此手动技能，或直接运行 CLI：

要说 / 运行的内容	操作
/octo:skill-doctor	在 Claude Code 中运行全部 15 个类别的检查
octopus doctor providers	仅检查提供方安装情况
octopus doctor auth --verbose	查看详细的身份验证状态
octopus doctor --json	输出机器可读数据
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor auth --verbose	CLI 不可用时查看详细的身份验证状态
bash "$OCTO_PLUGIN_ROOT/scripts/orchestrate.sh" doctor --json	CLI 不可用时输出机器可读数据

如果 octopus CLI 不在 PATH 中，请使用 Step 1 解析器解析并导出 OCTO_PLUGIN_ROOT， 然后直接运行等效的 scripts/orchestrate.sh 命令。