Reasonix Capability Diagnostics 能力诊断完全指南：从 `doctor capabilities` 到桌面 Diagnostics 的排障实践

Reasonix Capability Diagnostics 能力诊断完全指南：从doctor capabilities到桌面 Diagnostics 的排障实践

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix

Reasonix 内置了一套只读的能力诊断（capability diagnostics）模型，CLI 与桌面端Settings → Diagnostics共享同一套报告逻辑，用于体检当前工作区的 Skills、Commands、Hooks、插件包、MCP 服务器以及AGENTS.md/REASONIX.md/CLAUDE.md指令文档。读完本文，你将掌握reasonix doctor capabilities的静态/实时两种模式与全部参数，理解 JSON v1 报告结构与稳定问题码，并能在「技能丢失、钩子不触发、MCP 工具不出现」等典型场景下快速定位根因——同时了解诊断功能在路径改写与密钥脱敏上如何保证安全。

诊断什么：五类能力 + 指令文档

能力诊断围绕以下六类内容生成清单与问题列表：

核心入口是 internal/capdiag/collect.go 中的Collect函数：它依次收集指令文档、Skills、Commands、Hooks、插件包与 MCP 配置，再把所有子系统产生的问题汇总、按「severity → code → name → source」稳定排序后输出。数组与问题顺序是确定性的，这为脚本与测试消费报告提供了保障。

写策略：默认静态安全，live 需显式开启

诊断严格遵守只读与无副作用原则，不同模式的差异如下：

源码层面的两个关键证据：

• collect.go 使用config.LoadForRootReadOnly(root)加载配置，注释明确说明「只读加载：绝不重写磁盘上的 legacy tier 行或其他配置」；加载失败时回退到config.Default()，并把config.load_failed作为error问题上报。
• live.go 的probeLiveMCP注释强调：SkipPersistence: true使--live在 Reasonix home 下不产生任何缓存/状态副作用；同时defer host.Close()保证探测结束后 Host（含 stdio 子进程）一定被关闭。

因此结论非常清晰：默认的静态诊断不发起任何网络请求、不启动任何 MCP 子进程，只有当你明确希望真实拉起自动 MCP 服务器时才使用--live。

快速上手

相关医生（doctor）命令：

reasonix doctor # env / providers / sandbox 快照 reasonix doctor session <id> # 支持用的会话包 reasonix doctor redact-sessions # 对会话文件中的密钥做脱敏

CLI 实现见 internal/cli/doctor_capabilities.go：--root缺省取当前目录并转绝对路径；--timeout必须配合--live使用，且被限制在 1s–60s 之间，否则返回退出码 2（见下文退出码表）。--live启动前会向stderr打印风险横幅（LiveWarningMessage，见 live.go），提示第三方 MCP 可能访问网络并接收配置的 env/headers。

Skill 工具引用检查：识别而非授权

doctor与doctor capabilities都会基于同一套配置路径、排除项、禁用名单与来源优先级，对生效 skill 的allowed-tools做引用检查。工具清单由编译期内置工具与宿主管理的工具标识合并而成——例如use_capability即使在没有 MCP 服务器时也是已知宿主工具，因此无需禁用或覆盖内置的审查类 skill。

需要强调：「识别」只代表引用名称匹配了一个已知工具，不代表该工具在每次会话中已注册、已授权或已就绪。通过代理可调用的隐藏工具也计入清单；而 MCP 依赖配置是否完整属于另一项独立检查。当既有运行时 Host 或显式--live探测提供了 MCP 工具时，诊断会使用这份实测清单来解析可移植别名（alias）：插件 skill 可以使用其所属包内的别名，普通本地 skill 则需要具体的可调用名称或能力 ID；诊断保留适配器的原始名称与可见名称（含配置的前缀剥离）。

相关能力问题码：

未验证（unverified）引用在能力诊断中仅作信息提示；普通doctor保留其警告列表格式并显式标注这些引用未经验证。两种结果都不会授予工具访问权，也不代表服务器一定损坏。静态检查不会启动 MCP 服务器或调用模型供应商。

日常排障工作流

1. “Skill / Command 缺失或行为不对”

reasonix doctor capabilities --json | jq '.skills.entries, .commands.entries, .issues'

重点查看：

• skill.shadowed/command.shadowed— 更高优先级路径胜出，当前项被遮蔽
• skill.disabled— 名称在[skills].disabled_skills中
• skill.missing_description— skill 能加载但索引质量弱（缺少description:前导字段）
• command.read_failed— Markdown 不可读或解析失败

随后打开Settings → Skills（或直接修复.reasonix/skills/.reasonix/commands下的文件）。源码中collectSkills（collect.go）会逐个候选输出 Root 列表与条目（name / description / scope / path / status / runAs / winnerPath），并依据skill.CandidateShadowed、skill.CandidateDisabled等状态生成对应问题。

关于 skill 优先级，内置 reasonix-guide skill 给出了明确的胜出顺序：

1. project—<workspace>/{.reasonix,.agents,.agent,.claude}/skills/
2. custom—[skills].paths（以及插件包 skill 根）
3. global—<Reasonix home>/skills及 home 约定目录
4. builtin— 出厂内置 skill（含本文提到的 guide 本身）

同名时高作用域胜出、低作用域被遮蔽；[skills].disabled_skills会将该名称从 List/Read 中彻底隐藏。

2. “项目钩子从不触发”

reasonix doctor capabilities | sed -n '/Hooks/,/Plugins/p'

项目钩子从.reasonix/settings.json自动加载。若不触发，先确认当前工作区是否正确，保存后在重启 Reasonix再看。注意 matcher 是锚定（anchored）正则：file不会匹配read_file，需要写.*file或*。

源码中collectHooks（collect.go）对每个钩子条目做了四类校验：空 command 且空 contextFile →hook.missing_command（error）；contextFile 不存在/不可读 →hook.missing_context_file（error）；使用工具类 matcher 的事件校验正则 →hook.invalid_matcher（error，提示「使用锚定正则（或空/*）」）；事件名不在 11 个受支持事件内 →hook.unknown_event（warning）。settings JSON 整体解析失败则产生hook.malformed_settings（error），此时钩子整体不加载但不会导致崩溃。

3. “MCP 工具不出现”

分两步排查：

1. 先做静态检查（无副作用）：

   reasonix doctor capabilities --json | jq '.mcp.servers, .issues[] | select(.subsystem=="mcp")'

2. 只有当你接受启动第三方服务器时：

   reasonix doctor capabilities --live --timeout 10s --json

常见问题码：mcp.command_not_found、mcp.invalid_transport、mcp.start_failed、mcp.no_tools。桌面端优先使用Settings → Diagnostics并勾选 “Include current session runtime”，直接读取当前活动标签页的 Host，而不会启动第二个 Host。

每个 MCP 条目都会通过source、source_path、effective标识最终生效的配置来源（TOML /.mcp.json/ 插件包，见 collect.go 中collectMCP的guessMCPSource与PackageOwner判定）。启动失败还会上报：

• startup_stage：launch、authorization、initialize或tools/list
• startup_elapsed_ms：启动耗时
• 一段有界、经密钥脱敏的stderr尾部

这套信息能区分「重复/遮蔽注册」与「真正缓慢或损坏的握手」，同时不会暴露完整进程输出。静态检查中mcp.command_not_found只是warning而非 error——因为静态LookPath无法复现 GUI/登录 shell 在运行时补充的 PATH（源码注释见 collect.go），命令在真实会话环境下仍可能启动成功。

4. 让 Agent 帮你诊断（reasonix-guide）

在交互会话中：

/reasonix-guide

或直接提问：

My MCP server X is configured but the model never sees its tools — diagnose.

内置 skill 是**内联（runAs: inline）**执行的，完整内容见 internal/skill/builtincontent/reasonix-guide/SKILL.md。它指示模型：

• 首选静态报告reasonix doctor capabilities --json（无网络、无 MCP 子进程）；
• 仅在用户明确允许启动第三方 MCP（可能联网并传递已配置的 env/headers）时使用--live --timeout 5s --json；
• 桌面端“include current session runtime”只读取活动标签页 Host，不启动 MCP；
• 不臆造自动修复，而是报告稳定的问题码、来源与修复建议。

项目或全局存在同名reasonix-guideskill 时会覆盖内置版本；也可以用[skills].disabled_skills = ["reasonix-guide"]将其隐藏。内置 guide 还内置了 Skills / Commands / Hooks / MCP / 插件包 / 指令文档六个模块的「症状 → 原因 → 修复」速查表，是本工作流的最佳搭档。

CLI 参考

reasonix doctor capabilities [--root PATH] [--json] [--live] [--timeout 5s]

模式对比

桌面端 “include current session runtime”不等于CLI--live：桌面只读取活动标签页 Host，从不启动 MCP。Live 探测的并发上限与SkipPersistence在 live.go 中直接可见（Concurrency: 4、AbortOnError: false、SkipPersistence: true）。

退出码

退出码判定在 doctor_capabilities.go 中实现：capdiag.HasErrorSeverity(report)为真即返回 1（见 live.go）；--timeout未配合--live、时长越界或存在多余位置参数时返回 2。

示例：

# 人类可读，当前目录 reasonix doctor capabilities # CI 只在硬错误时失败 reasonix doctor capabilities --json # shell: summary.errors > 0 时退出码为 1 # 带更长超时的 live 探测，警告写入文件 reasonix doctor capabilities --live --timeout 15s --json 2>live-warn.txt

既有reasonix doctor、doctor session、doctor redact-sessions命令保留各自独立的 JSON schema——能力字段不会混入这些报告。

桌面 Diagnostics 页面

打开Settings → Diagnostics：

页面绝不编辑配置、执行钩子、自动启用插件包或重连 MCP。打开 Diagnostics 不会重建控制器，也不会对会话做快照。运行时合并（mergeRuntimeHost，见 collect.go）只读取host.Servers()、host.Failures()与host.ConnectingServers()；若请求了会话运行时但没有可用 Host，则追加一条mcp.runtime_unavailable（info，见CollectWithRuntimeUnavailable，collect.go）。

JSON schema（版本 1）

顶层字段：

• schema_version（恒为1）
• root（展示路径）
• live（bool）
• summary— error / warning / info 计数与资源计数（Skills 胜出数、Commands 胜出数、Hooks 数、Plugins 数、MCP 服务器数，见 collect.go）
• instructions、skills、commands、hooks、plugins、mcp
• issues[]— 有序问题列表

插件包条目针对Manifest v2做了向后兼容的增量：每个包额外上报prompts与themes计数，并在声明代码运行时上报runtime标志（详见 docs/PLUGIN_PACKAGES.md）。旧版读取方可以忽略这些字段；schema_version仍保持1。

Issue 结构：

{ "severity": "error|warning|info", "code": "skill.shadowed", "subsystem": "skills", "name": "demo", "source": "<workspace>/.reasonix/skills/demo/SKILL.md", "message": "...", "remediation": "...", "settings_tab": "skills" }

稳定问题码包括：

• skill.shadowed、skill.missing_description、skill.disabled
• command.shadowed、command.read_failed
• hook.invalid_matcher、hook.missing_command、hook.malformed_settings
• plugin.missing_root、plugin.invalid_manifest、plugin.compatibility
• mcp.invalid_transport、mcp.command_not_found、mcp.missing_command、mcp.missing_url
• mcp.start_failed、mcp.no_tools、mcp.runtime_unavailable

数组与 issue 顺序对脚本与测试是确定性的（排序键依次为 severity → code → name → source，见 collect.go 的sortIssues）。

严重级别

路径与密钥安全

报告按以下规则改写路径：

• 诊断根内路径改写为<workspace>/...
• 用户 home 下改写为~/...
• 其他绝对路径改写为<external>/basename（不暴露完整外部路径）

报告绝不有意输出用户名、完整外部路径、环境变量值、header值、令牌或 URL 查询字符串。MCP 条目只列出 env/header 的键名（EnvKeys/HeaderKeys，见 collect.go）。可能携带原始 HTTP 响应体或 MCP stderr 的错误文本会经过产品级密钥脱敏器（secrets.Redact，覆盖 Authorization 方案、Bearer/JWT/厂商令牌、KEY=value与 JSON"key":"value"凭据形式、Cookie/Set-Cookie 值），并截断到 400 字符。诊断还会额外收紧 Bearer 令牌的最小长度、改写PATH=键值，并对错误文本中出现的 POSIX / Windows 绝对路径做同样的展示路径改写（完整流程见 collect.go 的sanitizeErrTextWithPaths）。

建议：把报告 JSON 复制进 issue 或聊天中，优先于直接粘贴原始配置文件。

这里不诊断什么

缓存影响与架构要点

新增内置reasonix-guideskill 只会向下一次变更的session-contextSkills 目录追加一行；skill 正文仅在真正被调用时才加载。能力诊断本身不属于provider 提示词的一部分。

从架构上看，这套诊断的价值在于「一个模型、两处入口」：CLI 与桌面共享 internal/capdiag 的实现，默认静态无副作用、路径与密钥双重安全、问题码稳定可脚本化，同时通过可选的--live探针与桌面只读运行时合并，把「配置怎么看」和「运行时到底行不行」两个维度统一进同一份报告。配合内置的/reasonix-guide内联 skill，绝大多数能力类问题都能在几秒内定位到确切的配置文件与修复建议。

进一步阅读：docs/GUIDE.md（使用指南）、docs/PLUGIN_PACKAGES.md（插件包与 Manifest v2 说明）、docs/CAPABILITY_DIAGNOSTICS.zh-CN.md（本文简体中文版）。

【免费下载链接】DeepSeek-ReasonixDeepSeek-native AI coding agent for your terminal. Engineered around prefix-cache stability — leave it running.项目地址: https://gitcode.com/GitHub_Trending/de/DeepSeek-Reasonix