| 1 | # 能力诊断 |
| 2 | |
| 3 | <a href="./CAPABILITY_DIAGNOSTICS.md">English</a> |
| 4 | · |
| 5 | <a href="./GUIDE.zh-CN.md">使用指南</a> |
| 6 | · |
| 7 | <a href="./PLUGIN_PACKAGES.zh-CN.md">插件包</a> |
| 8 | |
| 9 | Reasonix 提供 CLI 与桌面端 **设置 → 诊断** 共用的只读能力诊断模型，覆盖 Skills、 |
| 10 | Commands、Hooks、插件包、MCP 服务器，以及指令文件（`AGENTS.md` / |
| 11 | `REASONIX.md` / `CLAUDE.md`）。 |
| 12 | |
| 13 | **写入策略** |
| 14 | |
| 15 | | 模式 | 配置文件 | MCP stats / schema cache | 网络 / MCP 进程 | |
| 16 | | --- | --- | --- | --- | |
| 17 | | 静态（默认）+ 桌面端 | 永不写入（`LoadForRootReadOnly`） | 永不写入 | 无 | |
| 18 | | CLI `--live` | 永不写入 | **不写入**（`SkipPersistence`） | 在隔离 Host 中启动 automatic MCP | |
| 19 | |
| 20 | ## 怎么用（快速上手） |
| 21 | |
| 22 | | 目标 | 命令 / 入口 | |
| 23 | | --- | --- | |
| 24 | | 检查当前工作区的 skills / hooks / MCP / 插件 | `reasonix doctor capabilities` | |
| 25 | | 机器可读报告（CI / 报障） | `reasonix doctor capabilities --json` | |
| 26 | | 指定项目根目录 | `reasonix doctor capabilities --root /path/to/project` | |
| 27 | | 真实探测 MCP 启动（会启动第三方服务器） | `reasonix doctor capabilities --live --timeout 5s` | |
| 28 | | 让 Agent 按手册排障 | 会话中 `/reasonix-guide`，或自然语言描述症状 | |
| 29 | | GUI 健康视图 | 桌面端 **设置 → 诊断** | |
| 30 | |
| 31 | **默认是静态且安全的**：无网络、不启动 MCP 子进程。只有你明确需要启动 |
| 32 | automatic MCP 时才用 `--live`。 |
| 33 | |
| 34 | 其它既有 doctor 命令（行为不变）： |
| 35 | |
| 36 | ```bash |
| 37 | reasonix doctor # 环境 / provider / 沙箱快照 |
| 38 | reasonix doctor session <id> # 支持用会话包 |
| 39 | reasonix doctor redact-sessions # 脱敏会话中的密钥 |
| 40 | ``` |
| 41 | |
| 42 | ## 日常工作流 |
| 43 | |
| 44 | ### 1. 「Skill / 命令找不到或内容不对」 |
| 45 | |
| 46 | ```bash |
| 47 | reasonix doctor capabilities --json | jq '.skills.entries, .commands.entries, .issues' |
| 48 | ``` |
| 49 | |
| 50 | 关注： |
| 51 | |
| 52 | - `skill.shadowed` / `command.shadowed` — 更高优先级路径覆盖了它 |
| 53 | - `skill.disabled` — 名字在 `[skills].disabled_skills` 里 |
| 54 | - `skill.missing_description` — 能加载但索引描述很弱 |
| 55 | - `command.read_failed` — 文件读失败或解析失败 |
| 56 | |
| 57 | 然后到 **设置 → 技能**，或直接改 `.reasonix/skills` / `.reasonix/commands` 下的文件。 |
| 58 | |
| 59 | ### 2. 「项目 Hooks 不触发」 |
| 60 | |
| 61 | ```bash |
| 62 | reasonix doctor capabilities | sed -n '/Hooks/,/Plugins/p' |
| 63 | ``` |
| 64 | |
| 65 | 项目 Hooks 会从 `.reasonix/settings.json` 自动加载。若没有触发，请确认当前工作区， |
| 66 | 保存后重启 Reasonix。`match` 是**锚定**正则：`file` **不会**匹配 `read_file`。 |
| 67 | |
| 68 | ### 3. 「配置了 MCP 但模型看不到工具」 |
| 69 | |
| 70 | 1. 先做静态检查（无副作用）： |
| 71 | |
| 72 | ```bash |
| 73 | reasonix doctor capabilities --json | jq '.mcp.servers, .issues[] | select(.subsystem=="mcp")' |
| 74 | ``` |
| 75 | |
| 76 | 2. 仅在接受启动第三方服务器时： |
| 77 | |
| 78 | ```bash |
| 79 | reasonix doctor capabilities --live --timeout 10s --json |
| 80 | ``` |
| 81 | |
| 82 | 常见 code：`mcp.command_not_found`、`mcp.invalid_transport`、 |
| 83 | `mcp.start_failed`、`mcp.no_tools`。桌面端更推荐 **设置 → 诊断** 打开 |
| 84 | 「包含当前会话运行状态」——只读取**活动标签 Host**，不会再起第二个 Host。 |
| 85 | |
| 86 | 每个 MCP 条目通过 `source`、`source_path` 和 `effective` 标明真正生效的配置及其来源。 |
| 87 | 启动失败还会报告 `startup_stage`（`launch`、`authorization`、`initialize` 或 |
| 88 | `tools/list`）、`startup_elapsed_ms`，以及有长度上限且已做凭据脱敏的 `stderr` 尾部。 |
| 89 | 这可以区分重复/被覆盖的注册与真正缓慢或失败的握手，同时不会暴露完整进程输出。 |
| 90 | |
| 91 | ### 4. 让 Agent 按手册排查（`reasonix-guide`） |
| 92 | |
| 93 | 交互式会话中： |
| 94 | |
| 95 | ```text |
| 96 | /reasonix-guide |
| 97 | ``` |
| 98 | |
| 99 | 或： |
| 100 | |
| 101 | ```text |
| 102 | 我配置了 MCP 服务器 X，但模型始终看不到它的工具，请排查。 |
| 103 | ``` |
| 104 | |
| 105 | 该内置 Skill 是 **inline**（`runAs: inline`）。它会优先要求模型运行： |
| 106 | |
| 107 | ```bash |
| 108 | reasonix doctor capabilities --json |
| 109 | ``` |
| 110 | |
| 111 | 只有你明确允许启动外部 MCP 时才建议 `--live`。项目或全局同名 |
| 112 | `reasonix-guide` 会覆盖内置版；也可用 |
| 113 | `[skills].disabled_skills = ["reasonix-guide"]` 隐藏。 |
| 114 | |
| 115 | ## CLI 参考 |
| 116 | |
| 117 | ```bash |
| 118 | reasonix doctor capabilities [--root PATH] [--json] [--live] [--timeout 5s] |
| 119 | ``` |
| 120 | |
| 121 | | 参数 | 含义 | |
| 122 | | --- | --- | |
| 123 | | `--root` | 工作区根目录（默认当前目录），走 `config.LoadForRoot` | |
| 124 | | `--json` | 仅向 **stdout** 输出一个 JSON 对象（提示写 stderr） | |
| 125 | | `--live` | 在隔离 Host 中启动 **automatic** MCP（可能联网） | |
| 126 | | `--timeout` | 单服务器 live 超时，**1s–60s**，默认 `5s`，必须配合 `--live` | |
| 127 | |
| 128 | ### 模式 |
| 129 | |
| 130 | | 模式 | 行为 | |
| 131 | | --- | --- | |
| 132 | | **静态（默认）** | 无网络；不启动 stdio / HTTP / SSE MCP 子进程 | |
| 133 | | **Live（`--live`）** | stderr 风险提示；只探测 automatic 启动意图；`auto_start=false` → `skipped`；并发 4；始终关闭 Host | |
| 134 | |
| 135 | 桌面端「包含当前会话运行状态」**不等于** CLI `--live`：桌面只**读取**活动标签 Host， |
| 136 | 不启动 MCP。 |
| 137 | |
| 138 | ### 退出码 |
| 139 | |
| 140 | | 码 | 含义 | |
| 141 | | --- | --- | |
| 142 | | `0` | 无 `error` 级问题（warning/info 允许） | |
| 143 | | `1` | 存在 `error` 或 live MCP 启动失败 | |
| 144 | | `2` | 参数错误 | |
| 145 | |
| 146 | 示例： |
| 147 | |
| 148 | ```bash |
| 149 | # 当前目录、人类可读 |
| 150 | reasonix doctor capabilities |
| 151 | |
| 152 | # CI：仅有 error 时非零退出 |
| 153 | reasonix doctor capabilities --json |
| 154 | |
| 155 | # live 探测，超时 15 秒 |
| 156 | reasonix doctor capabilities --live --timeout 15s --json 2>live-warn.txt |
| 157 | ``` |
| 158 | |
| 159 | 既有 `reasonix doctor` / `doctor session` / `doctor redact-sessions` 的 JSON |
| 160 | schema **不会**混入新字段。 |
| 161 | |
| 162 | ## 桌面端 |
| 163 | |
| 164 | 打开 **设置 → 诊断**： |
| 165 | |
| 166 | | 控件 | 行为 | |
| 167 | | --- | --- | |
| 168 | | 打开页面 | 对活动工作区根加载**静态**报告 | |
| 169 | | 刷新 | 按当前「会话运行状态」开关重新收集 | |
| 170 | | 复制脱敏 JSON | 可安全粘贴的报告（路径已脱敏） | |
| 171 | | 包含当前会话运行状态 | 仅合并活动标签 Host 的 connected / failed / deferred / disabled | |
| 172 | | 前往设置（Issue 上） | 当 `settings_tab` 有值时跳到 MCP / Skills / Plugins / Hooks | |
| 173 | |
| 174 | 页面不提供自动编辑、执行 hooks、自动启用或自动重连。打开诊断页**不会** |
| 175 | rebuild controller，也不会 snapshot 会话。 |
| 176 | |
| 177 | ## JSON schema（version 1） |
| 178 | |
| 179 | 顶层字段：`schema_version`、`root`、`live`、`summary`、 |
| 180 | `instructions` / `skills` / `commands` / `hooks` / `plugins` / `mcp`、`issues`。 |
| 181 | |
| 182 | 插件包条目对 Manifest v1 是增量扩展：声明了代码型 Runtime 的插件还会 |
| 183 | 报告 `prompts` 与 `themes` 计数和 `runtime` 标记（见 |
| 184 | <a href="./PLUGIN_PACKAGES.zh-CN.md">插件包</a>）。旧读者可以忽略这些 |
| 185 | 字段；`schema_version` 保持 `1`。 |
| 186 | |
| 187 | Issue 含稳定 `code`、`severity`、`subsystem`、`source`、`message`、`remediation`、 |
| 188 | 可选 `settings_tab`。数组与 Issue 顺序确定，便于脚本与测试。 |
| 189 | |
| 190 | 常见 code： |
| 191 | |
| 192 | - `skill.shadowed`、`skill.missing_description`、`skill.disabled` |
| 193 | - `command.shadowed`、`command.read_failed` |
| 194 | - `hook.invalid_matcher`、`hook.missing_command`、`hook.malformed_settings` |
| 195 | - `plugin.missing_root`、`plugin.invalid_manifest`、`plugin.compatibility` |
| 196 | - `mcp.invalid_transport`、`mcp.command_not_found`、`mcp.missing_command`、`mcp.missing_url` |
| 197 | - `mcp.start_failed`、`mcp.no_tools`、`mcp.runtime_unavailable` |
| 198 | |
| 199 | ### 严重度 |
| 200 | |
| 201 | | 严重度 | 含义 | CLI | |
| 202 | | --- | --- | --- | |
| 203 | | `error` | 配置损坏或 live 启动失败 | 退出 `1` | |
| 204 | | `warning` | 需处理但非致命 | 退出 `0` | |
| 205 | | `info` | 遮蔽、禁用、无运行时等 | 退出 `0` | |
| 206 | |
| 207 | ## 路径与密钥安全 |
| 208 | |
| 209 | 路径显示为 `<workspace>/...`、`~/...` 或 `<external>/basename`。 |
| 210 | 不输出用户名、完整外部路径、环境变量值、Header 值、token、URL query。 |
| 211 | MCP 仅列出 env/header 的 **key**。可能携带 HTTP 响应体或 MCP stderr 的 |
| 212 | 错误文本会先经过全局密钥脱敏器（Authorization、Bearer/JWT/厂商 token、 |
| 213 | `KEY=value` 与 JSON `"key":"value"` 凭据形态、Cookie/Set-Cookie 值）， |
| 214 | 再截断到 400 字符。向 issue / 聊天贴报告时，优先复制诊断 JSON， |
| 215 | 不要贴原始配置文件。 |
| 216 | |
| 217 | ## 不在本诊断范围内的事项 |
| 218 | |
| 219 | | 需求 | 改用 | |
| 220 | | --- | --- | |
| 221 | | Provider 密钥、代理、沙箱 OS 支持 | `reasonix doctor` | |
| 222 | | 给支持用的完整会话包 | `reasonix doctor session <id>` | |
| 223 | | 单个插件包 | `reasonix plugin doctor <name>` | |
| 224 | | 会话内 MCP 列表 | `/mcp` | |
| 225 | |
| 226 | ## 缓存影响 |
| 227 | |
| 228 | 内置 `reasonix-guide` 仅在 system prompt 的 Skill 索引中增加 **一行稳定索引**； |
| 229 | 正文按需加载。诊断本身不进入 provider 请求。 |
| 230 |