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。报告顶层按稳定 SchemaSchemaVersion定义见 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_filecontext 文件缺失或不可读、hook.unknown_event事件名不在 11 个之内、hook.malformed_settingssettings.json 的 JSON 非法。注意最后一条的语义文件坏了就一个 Hook 都不加载但进程本身不会崩——所以所有 Hook 集体失灵多半就是 JSON 损坏而不是配置逻辑问题。入口是/hooks、Settings → Hooks 和 Diagnostics → Hooks。MCP 连不上三个来源按序合并再选对检查模式MCP 配置按固定顺序合并先定义的名字胜出用户/项目 TOML 的[[plugins]]项目.mcp.json中尚未出现过的服务器已启用插件包贡献的 MCP名字已定义则跳过传输方式支持stdio默认、httpstreamable-http和sse。两个行为开关值得记住auto_startfalse表示启动时跳过该服务器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_rootmanifest 解析失败是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 后重启 ReasonixMCP 问题先分清是静态配置错transport / command / url还是运行时失败mcp.start_failed后者再考虑--live深入插件包用reasonix plugin doctor name单独定位别被全局报告带偏修复后重开会话再跑一遍报告直到 errors 清零报告是只读的、错误码是稳定的、修复建议写在每条 issue 里——照着证据走比翻配置快得多。【免费下载链接】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），仅供参考