env-doctor

原生命令为主、薄脚本补盲区、模型推理综合诊断。

核心原则

1. 原生命令优先 — 每个环境的 built-in 诊断是最权威的，不重写
2. 脚本只做盲区 — 原生命令做不到的事才用脚本（跨环境、网络、历史模式）
3. 模型是大脑 — 调度策略由模型动态决定，不写死路由
4. 未知环境降级 — 遇到未注册的 agent 工具，用通用探测发现能力

调度策略（模型决策参考）

用户请求自检
    │
    ▼
 capabilities.json → 确认目标环境有无注册
    │
    ├── 存在 → 按注册环境调度
    │
    └── 不存在 → 运行时探测：which claude codex grok kimi
                                      └── 发现的视为"已知环境"
    │
    ├── 已知环境（claude/codex/grok/kimi）
    │       │
    │       ▼
    │   调度原生命令（第一优先级，权威数据）
    │       │
    │       ├── 原生命令覆盖的维度 → 直接信任
    │       │
    │       └── 原生命令的 blind_spots → 调度对应脚本补充
    │               │
    │               ▼
    │           脚本数据 + 原生数据 → 模型综合推理 → 报告
    │
    └── 未知环境（未注册）
            │
            ▼
        unknown_env_fallback 通用探测
            │
            ▼
        which / --version / --help / 配置目录 / 配置文件
            │
            ▼
        输出原始数据 + 建议模型是否值得深入

各环境的原生命令

脚本（只做原生命令的盲区）

调用示例

Preflight（每次运行前必做）

1. 验证 scripts/ 下 4 个脚本存在且可执行
   probe-network.sh / cross-path-audit.sh / drift-detector.py / history-match.py
   ├── 全部存在 → 继续
   └── 缺失 → 记录到报告 "scripts_missing: [...]"，跳过对应检查维度

2. 定位 capabilities.json
   ├── SKILL.md 同目录 /capabilities.json → 读取
   └── 不存在 → 降级为运行时探测（which <cmd> && <cmd> --version）

全量巡检（模型决策）

1. 读 capabilities.json 确认可用环境（或运行时探测）
2. 并行调度各环境原生命令（推荐并行，示例见下）
3. 从输出中提取 blind_spots 列表
4. 对每个 blind_spot 调用对应脚本
5. 综合所有数据生成报告

并行执行示例

# 各环境原生诊断并行调度
codex doctor --json & PID1=$!
grok inspect --json  & PID2=$!
kimi doctor config   & PID3=$!
wait $PID1 $PID2 $PID3

# 脚本层并行
python3 scripts/probe-network.sh & PID4=$!
python3 scripts/cross-path-audit.sh & PID5=$!
wait $PID4 $PID5

# 各环境原生诊断
codex doctor --json                           # Codex
grok inspect --json                           # Grok
kimi doctor config                            # Kimi Code

# 脚本补充
python3 scripts/probe-network.sh              # API 可达性
python3 scripts/cross-path-audit.sh           # PATH 冲突
python3 scripts/drift-detector.py             # Skill 漂移
python3 scripts/history-match.py              # 历史模式

针对性检查

# 只看网络
python3 scripts/probe-network.sh

# 只看 Claude 相关的历史模式
python3 scripts/history-match.py --env claude

# 只看 warning 级别的问题
python3 scripts/history-match.py --severity warning

未知环境降级探测

当遇到未注册的 agent 工具（如新的 XYZ Code）：

which xyz           # PATH 中是否存在
xyz --version       # 版本号
xyz --help 2>&1 | grep -iE 'doctor|check|status|config|debug'  # 发现诊断入口
ls -la ~/.<xyz>/    # 配置目录结构
cat ~/.<xyz>/config.*  # 配置健康度
ls ~/.<xyz>/skills/ # skill 安装数量

通用探测的目标：发现该环境的自诊断入口，输出原始数据供模型决定是否深入，不强行判断。

严重程度

退出码约定

脚本退出码对齐此约定：drift-detector.py 已对齐（0=clean, 1=drift），其余脚本遵循同一规则。

报告格式

=== env-doctor 诊断报告 ===
Date: ISO-8601
Version: 0.3.0
Environments: claude / codex / grok / kimi（实际检测到的）
Data Sources: /doctor + codex doctor --json + grok inspect + kimi doctor + N scripts

CRITICAL (N)
---
WARNING (N)
---
INFO (N)
---
PASS (N)
---

总结: [一句话评估]
建议: [按优先级排列的修复建议]

Path resolution

SD_ROOT="${SESSION_DIGGER_ROOT:-${CLAUDE_PLUGIN_ROOT:-${HERDR_PLUGIN_ROOT:-}}}"
[[ -z "$SD_ROOT" ]] && SD_ROOT="$(cd "$(dirname "${BASH_SOURCE[0]:-$0}")/../.." 2>/dev/null && pwd)"

下游协作

DO NOT

• 不重写原生命令已有的检查逻辑——调用它、信任它
• 不让脚本做模型能推理的事——脚本只采集原始数据
• 不在输出中暴露 API Key / token 完整值（只显示前 8 位 + 省略号）
• 不替代各环境原生的诊断命令——是补充和跨环境扩展
• 不对未知环境强行输出结论——只输出原始数据，让模型判断