Reasonix 能力诊断完全指南：用 1 个命令定位 Skills、Hooks 与 MCP 配置问题-二趣网

Reasonix 能力诊断完全指南：用 1 个命令定位 Skills、Hooks 与 MCP 配置问题

【免费下载链接】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

某个技能突然从列表里消失，斜杠命令的内容和预期对不上，或者 MCP 服务器怎么也连不上——先别靠猜。Reasonix 能力诊断提供一条命令把所有疑点摊开：reasonix doctor capabilities。它会把 Skills、Commands、Hooks、MCP 服务器、插件包以及 AGENTS.md 指令文档的现状汇总成一份结构化报告。下面先教你怎么拿到并读懂这份报告，再按最常见的四类故障逐个给出修复路径。

如何获取能力诊断报告：先静态，后实时

最常用的姿势是加--json输出结构化结果：

reasonix doctor capabilities --json

这个模式是严格只读的：采集逻辑（internal/capdiag/collect.go 中的Collect）通过只读方式加载配置，不发网络请求、不启动任何 MCP 子进程，也不碰 config、cache、state 或日志文件。你完全可以随时跑，零副作用。

需要确认 MCP 到底能不能起来时，才用实时探测，而且要显式声明：

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

--live会在隔离的 Host 中真正启动那些标记为自动启动的 MCP 服务器，可能联网并透传你配置的 env 与 header，所以务必在信任环境里执行。--timeout限定单服务器探测时间，范围 1s~60s，缺省 5s；探测并发上限为 4，结束后必然 Close。

报告顶层按稳定 Schema（SchemaVersion，定义见 internal/capdiag/types.go）组织：summary给计数，instructions/skills/commands/hooks/plugins/mcp各占一块，最下面是一条扁平的issues数组。每条 issue 都带稳定错误码、严重级别、来源、消息和修复建议（remediation），部分还带settings_tab方便桌面端跳页。排障时直接照抄报告里的错误码与建议即可，不必自己脑补原因。桌面端 Settings → Diagnostics 复用同一套采集，其中"包含当前会话运行时"开关只是读取活动标签页 Host 的 connected / failed / deferred / disabled 状态，同样不会启动 MCP。

技能消失时：先搞清楚谁遮蔽了谁

报告里找不到某个技能，最常见的原因是同名冲突或被禁用。Reasonix 按名字给技能定唯一胜者，优先级从高到低是四级：

project— 工作区下的.reasonix、.agents、.agent、.claude里的skills/
custom—[skills].paths指定路径及插件包内的技能目录
global— Reasonix home 的skills与主目录约定目录
builtin— 随产品内置的技能

这就像"项目规则盖过全局规则"：同名时高优先级作用域胜出，低优先级那份在报告里标记为 shadowed。四级定义与 internal/skill/skill.go 的Scope枚举一一对应。另有两条独立规则：

名字进了[skills].disabled_skills的技能会被整体隐藏，List / Read 都看不到（错误码skill.disabled）
缺少description:的 skill 仍能加载，但索引质量下降（skill.missing_description），补一行描述即可

发现目录有约定：.reasonix是原生目录，另外三个是为了让你直接复用为其他 Agent 工具写的技能资产。布局支持两种——目录式<name>/SKILL.md和扁平式<name>.md；注意.claude下的扁平文件必须带技能 frontmatter（如description:/runAs:）才会被识别，否则换个目录式布局最稳妥。

还有一条"消失"其实是正常现象：技能的正文默认不加载，只把名字和描述放进索引，通过/name或run_skill调用时才按需展开。排查完改动后，记得重开会话或刷新 Skills再验证。对应错误码是skill.shadowed，消息里会直接写出胜者路径，照着改低优先级那份就行。

命令正文不对：后扫描的目录会覆盖先扫描的

斜杠命令（.md模板文件）的目录由 internal/config/paths.go 的CommandDirsForRoot解析，扫描顺序是：主目录约定命令目录 → Reasonix 主目录命令目录 → 项目约定命令目录，而后扫描的同名命令覆盖先扫描的。每个层级内部还按.claude→.agent→.agents→.reasonix升序排列，所以最终最高优先级落在项目的.reasonix/commands/。

命令名从路径推导：git/commit.md会变成/git:commit，斜杠转成冒号。症状对应的处理很直接：

正文内容不是你写的那份 → 被后扫描目录覆盖，看command.shadowed指向的胜者路径，删掉或改名多余的一份
命令整个缺失 → 检查文件是不是*.md、是否真的落在受扫描的commands/根目录下
解析失败 → 文件读不了，修权限或编码，错误码是command.read_failed

在聊天里直接敲/name试一下，是验证覆盖结果最快的方式。

Hook 不触发：匹配器是锚定的，而且改了要重启

Reasonix 的 Hook 一共支持 11 个事件：PreToolUse、PostToolUse、PermissionRequest、UserPromptSubmit、Stop、PostLLMCall、SessionStart、SessionEnd、SubagentStop、Notification、PreCompact。其中只有PreToolUse和UserPromptSubmit是阻塞型：它们以退出码 2 结束时能真正拦下主循环（gating）；其余事件只产生告警或往上下文里加内容。

超时默认值定义在 internal/hook/hook.go：阻塞事件默认5 秒，其他事件默认30 秒，而配置里写的timeout单位是毫秒——写 5000 而不是 5，差一个数量级。

Hook 有三个来源：

项目：<workspace>/.reasonix/settings.json，保存后自动加载，但需要重启 Reasonix 才生效（这是"静默失效"的头号原因）
插件包：已安装且已启用的包
全局：<Reasonix home>/settings.json，始终加载

最容易踩的坑是match字段：它是锚定的正则，file不会匹配read_file，想模糊匹配得写.*file或直接用*。报告给出的对应错误码包括hook.invalid_matcher（匹配器不合法）、hook.missing_command（条目既没 command 也没 contextFile）、hook.missing_context_file（context 文件缺失或不可读）、hook.unknown_event（事件名不在 11 个之内）、hook.malformed_settings（settings.json 的 JSON 非法）。注意最后一条的语义：文件坏了就一个 Hook 都不加载，但进程本身不会崩——所以"所有 Hook 集体失灵"多半就是 JSON 损坏，而不是配置逻辑问题。入口是/hooks、Settings → Hooks 和 Diagnostics → Hooks。

MCP 连不上：三个来源按序合并，再选对检查模式

MCP 配置按固定顺序合并，先定义的名字胜出：

用户/项目 TOML 的[[plugins]]
项目.mcp.json中尚未出现过的服务器
已启用插件包贡献的 MCP（名字已定义则跳过）

传输方式支持stdio（默认）、http（streamable-http）和sse。两个行为开关值得记住：auto_start=false表示启动时跳过该服务器；tier 为eager会阻塞启动握手，空值或background则后台连接、不卡聊天。

检查分三种模式，选错模式会得出错误结论：

静态 doctor（默认）：只校验配置合法性、命令路径 / URL 形态与启动意图，不启动子进程
CLI--live：在隔离 Host 中真正拉起服务器，只探测 auto-start 的那部分，并发 4，结束后 Close
桌面端运行时：仅读取活动标签页 Host 的状态，绝不新启动

安全上有个设计细节：env 和 header 的值可能是密钥，报告只列出键名（env_keys、header_keys），绝不输出值。常见错误码速查：连不上看mcp.command_not_found或mcp.start_failed；连上了但mcp.no_tools说明服务器没暴露工具，查它的配置或鉴权；被别的来源遮蔽就核对报告里的 Source / 包所有者；type写错则是mcp.invalid_transport。

插件包与指令文档：两个常被忽略的来源

插件包有三种 manifest 形态：原生的reasonix-plugin.json、Codex 的.codex-plugin/plugin.json、Claude 的.claude-plugin/plugin.json（含有限的 Claude 兼容路径）。安装状态记在<Reasonix home>/plugin-packages.json。关键规则是：被禁用的包不贡献任何 Skills / Hooks / MCP。Reasonix 不会虚构能力，未映射的 Claude 专属特性只以兼容性警告出现（plugin.compatibility）。根路径丢失是plugin.missing_root，manifest 解析失败是plugin.invalid_manifest；包级诊断有专门命令：

reasonix plugin doctor <name>

指令文档（AGENTS.md / REASONIX.md 体系）是另一类来源。加载顺序按特异性递增：用户全局文档 → 祖先目录链 → 项目文档 → 项目本地文档（*.local.md变体）。可识别的文件名是REASONIX.md、AGENTS.md、CLAUDE.md及其*.local.md变体；同一目录可加载多个文件，符号链接指向同一身份时会去重。要分清机制：这些指令在会话启动时折叠进系统提示词，构成缓存稳定的前缀；而 Hooks 是按各自配置位置加载的运行时事件处理器。"指令没生效"先去 Diagnostics → Instructions 看加载顺序，多半是文件名不对或文件为空；"本地规则盖了项目规则"则是本地文件覆盖，属于预期行为。

桌面端 Diagnostics 与脱敏边界

桌面端的用法和 CLI 同源：打开即展示静态报告，Refresh 重新执行静态采集，可以复制脱敏后的 JSON，也可勾选合并会话运行时信息（只读 Host）。当某条 issue 带settings_tab时，页面能直接跳到 MCP / Skills / Plugins / Hooks 的设置页。该页面从不自动修改配置、执行 Hook 或自动重连——所有修复动作都留给你。

脱敏规则值得单独记一下：报告不输出 token、header 值、env 值、URL 查询串、用户名或机器上的绝对外部路径，路径一律以<workspace>/…、~/…、<external>/…形式呈现。反过来，这也意味着把报告直接贴给同事或支持渠道是安全的——但前提是你没加--live之外的手动粘贴操作。

排查心法：先只读取证，再动手修复

到这里，整套流程可以浓缩成一条心法：让只读报告先开口，再改配置。行动清单可以直接带走：

出问题时第一条命令永远是reasonix doctor capabilities --json，看summary的 errors/warnings 计数，再逐条读issues的错误码
技能 / 命令类问题，先核对胜者路径（winner_path）与遮蔽计数，确认冲突来自哪一层
Hook 问题先查 JSON 合法性与match锚定写法，改完项目 settings 后重启 Reasonix
MCP 问题先分清是静态配置错（transport / command / url）还是运行时失败（mcp.start_failed），后者再考虑--live深入
插件包用reasonix plugin doctor <name>单独定位，别被全局报告带偏
修复后重开会话再跑一遍报告，直到 errors 清零

报告是只读的、错误码是稳定的、修复建议写在每条 issue 里——照着证据走，比翻配置快得多。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析