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-ReasonixReasonix 内置了一套只读的能力诊断capability diagnostics模型CLI 与桌面端Settings → Diagnostics共享同一套报告逻辑用于体检当前工作区的 Skills、Commands、Hooks、插件包、MCP 服务器以及AGENTS.md/REASONIX.md/CLAUDE.md指令文档。读完本文你将掌握reasonix doctor capabilities的静态/实时两种模式与全部参数理解 JSON v1 报告结构与稳定问题码并能在「技能丢失、钩子不触发、MCP 工具不出现」等典型场景下快速定位根因——同时了解诊断功能在路径改写与密钥脱敏上如何保证安全。诊断什么五类能力 指令文档能力诊断围绕以下六类内容生成清单与问题列表类别检查要点Skills各作用域的加载根、同名覆盖shadowing、disabled_skills禁用、缺少description前导字段Commands斜杠命令模板的目录扫描、优先级覆盖、可读性/解析错误Hooks项目钩子.reasonix/settings.json、全局钩子、事件名、matcher 正则合法性、命令与 contextFile 存在性Plugin packages包根目录、Manifest原生 / Codex / Claude、兼容性警告、能力计数MCP servers传输类型、命令/URL 形状、自动启动意图、启动阶段与失败信息InstructionsAGENTS.md/REASONIX.md/CLAUDE.md及其*.local.md变体的加载路径与作用域顺序核心入口是 internal/capdiag/collect.go 中的Collect函数它依次收集指令文档、Skills、Commands、Hooks、插件包与 MCP 配置再把所有子系统产生的问题汇总、按「severity → code → name → source」稳定排序后输出。数组与问题顺序是确定性的这为脚本与测试消费报告提供了保障。写策略默认静态安全live 需显式开启诊断严格遵守只读与无副作用原则不同模式的差异如下模式配置文件MCP 统计 / schema 缓存网络 / MCP 进程静态默认 桌面永不写入LoadForRootReadOnly永不写入无CLI--live永不写入不写入SkipPersistence在隔离 Host 中启动自动 MCP源码层面的两个关键证据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。快速上手目标执行的命令检查当前工作区的 skills / hooks / MCP / pluginsreasonix doctor capabilities输出机器可读报告CI / 支持场景reasonix doctor capabilities --json指定其他项目根目录reasonix doctor capabilities --root /path/to/project真实探测 MCP 启动会启动第三方服务器reasonix doctor capabilities --live --timeout 5s让 Agent 讲解配置 / 修复建议在会话中发送/reasonix-guide或直接自然语言提问GUI 健康视图桌面端Settings → Diagnostics相关医生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诊断保留适配器的原始名称与可见名称含配置的前缀剥离。相关能力问题码问题码含义skill.tool_reference_unknown普通名称不在已知清单中检查拼写skill.tool_reference_invalidglob 语法非法或 MCP 引用不完整skill.tool_reference_ambiguous提供的 MCP 绑定把某个字面量解析到多个工具skill.tool_reference_unverified动态引用或未匹配的模式无法在离线状态下验证skill.mcp_dependency_missingauto-use 必需 skill 依赖未配置的 MCP 服务器skill.mcp_dependency_failed必需服务器存在已观测到的宿主启动失败未验证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下的文件。源码中collectSkillscollect.go会逐个候选输出 Root 列表与条目name / description / scope / path / status / runAs / winnerPath并依据skill.CandidateShadowed、skill.CandidateDisabled等状态生成对应问题。关于 skill 优先级内置 reasonix-guide skill 给出了明确的胜出顺序project—workspace/{.reasonix,.agents,.agent,.claude}/skills/custom—[skills].paths以及插件包 skill 根global—Reasonix home/skills及 home 约定目录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或*。源码中collectHookscollect.go对每个钩子条目做了四类校验空 command 且空 contextFile →hook.missing_commanderrorcontextFile 不存在/不可读 →hook.missing_context_fileerror使用工具类 matcher 的事件校验正则 →hook.invalid_matchererror提示「使用锚定正则或空/*」事件名不在 11 个受支持事件内 →hook.unknown_eventwarning。settings JSON 整体解析失败则产生hook.malformed_settingserror此时钩子整体不加载但不会导致崩溃。3. “MCP 工具不出现”分两步排查先做静态检查无副作用reasonix doctor capabilities --json | jq .mcp.servers, .issues[] | select(.subsystemmcp)只有当你接受启动第三方服务器时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_stagelaunch、authorization、initialize或tools/liststartup_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]Flag含义--root工作区根目录默认当前目录。使用config.LoadForRoot。--json仅向stdout输出一个 JSON 对象警告信息走 stderr。--live在隔离 Host 中启动自动启动的 MCP 服务器可能联网。--timeout每个服务器的 live 超时1s–60s默认5s。必须配合--live。模式对比模式行为静态默认无网络无 stdio / HTTP / SSE MCP 子进程。Live--livestderr 打印风险横幅仅启动具备自动启动意图的服务器auto_startfalse→skipped并发 4Host 探测后必定关闭。桌面端 “include current session runtime”不等于CLI--live桌面只读取活动标签页 Host从不启动 MCP。Live 探测的并发上限与SkipPersistence在 live.go 中直接可见Concurrency: 4、AbortOnError: false、SkipPersistence: true。退出码退出码含义0无error级问题允许 warning / info1存在一个或多个error问题或 live MCP 启动失败2参数/用法错误退出码判定在 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 2live-warn.txt既有reasonix doctor、doctor session、doctor redact-sessions命令保留各自独立的 JSON schema——能力字段不会混入这些报告。桌面 Diagnostics 页面打开Settings → Diagnostics控件行为打开页面为活动工作区根加载静态报告Refresh按当前 runtime 开关重新执行采集Copy redacted JSON复制剪贴板安全报告路径已脱敏Include current session runtime仅合并活动标签页 Host的 connected / failed / deferred / disabled 状态Open settings针对某条 issue当settings_tab存在时跳转到 MCP / Skills / Plugins / Hooks 设置页面绝不编辑配置、执行钩子、自动启用插件包或重连 MCP。打开 Diagnostics 不会重建控制器也不会对会话做快照。运行时合并mergeRuntimeHost见 collect.go只读取host.Servers()、host.Failures()与host.ConnectingServers()若请求了会话运行时但没有可用 Host则追加一条mcp.runtime_unavailableinfo见CollectWithRuntimeUnavailablecollect.go。JSON schema版本 1顶层字段schema_version恒为1root展示路径liveboolsummary— error / warning / info 计数与资源计数Skills 胜出数、Commands 胜出数、Hooks 数、Plugins 数、MCP 服务器数见 collect.goinstructions、skills、commands、hooks、plugins、mcpissues[]— 有序问题列表插件包条目针对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.disabledcommand.shadowed、command.read_failedhook.invalid_matcher、hook.missing_command、hook.malformed_settingsplugin.missing_root、plugin.invalid_manifest、plugin.compatibilitymcp.invalid_transport、mcp.command_not_found、mcp.missing_command、mcp.missing_urlmcp.start_failed、mcp.no_tools、mcp.runtime_unavailable数组与 issue 顺序对脚本与测试是确定性的排序键依次为 severity → code → name → source见 collect.go 的sortIssues。严重级别Severity含义CLI 退出码error配置损坏或 live 启动失败1warning可处理但非致命如钩子命令缺失0info遮蔽、禁用资产、运行时不可用0路径与密钥安全报告按以下规则改写路径诊断根内路径改写为workspace/...用户 home 下改写为~/...其他绝对路径改写为external/basename不暴露完整外部路径报告绝不有意输出用户名、完整外部路径、环境变量值、header值、令牌或 URL 查询字符串。MCP 条目只列出 env/header 的键名EnvKeys/HeaderKeys见 collect.go。可能携带原始 HTTP 响应体或 MCP stderr 的错误文本会经过产品级密钥脱敏器secrets.Redact覆盖 Authorization 方案、Bearer/JWT/厂商令牌、KEYvalue与 JSONkey:value凭据形式、Cookie/Set-Cookie 值并截断到 400 字符。诊断还会额外收紧 Bearer 令牌的最小长度、改写PATH键值并对错误文本中出现的 POSIX / Windows 绝对路径做同样的展示路径改写完整流程见 collect.go 的sanitizeErrTextWithPaths。建议把报告 JSON 复制进 issue 或聊天中优先于直接粘贴原始配置文件。这里不诊断什么需求请改用Provider 密钥、代理、sandbox OS 支持reasonix doctor供支持用的完整会话转录reasonix doctor session id仅诊断单个插件包reasonix plugin doctor name会话内交互式 MCP 列表/mcp缓存影响与架构要点新增内置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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考