Reasonix 能力诊断完整指南技能、命令、Hook 与 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-ReasonixReasonix 是一款面向终端的 AI 编码代理它的行为由 Skills技能、Commands斜杠命令、Hooks钩子、MCP 服务器和插件包五类扩展能力驱动。当你发现某个能力配了却没反应时问题往往出在加载来源和覆盖规则上。这篇 Reasonix 能力诊断指南教你用一条只读命令拿到全局状态再按错误码逐项修复不需要翻源码。为什么能力会看起来存在实际不生效Reasonix 的能力都来自多个目录项目工作区、你的主目录、Reasonix 自己的主目录、以及已安装的插件包。同一名字的能力可能在多处同时存在此时只有一份会被加载另一份被遮蔽——也就是被更高优先级的来源挡住对外表现是这个技能/命令消失了。常见的四种根因同名能力被更高优先级来源遮蔽文件放错了目录或布局不符合约定比如缺少SKILL.md配置项显式禁用了它或整个插件包处于禁用状态MCP 服务器启动失败但它连不上时只报错误码不会中断聊天这些状态你无法靠肉眼翻目录确认因为遮蔽发生在加载逻辑内部。所以第一步永远不是改配置而是取证。先用静态检查定位全局状态核心命令只有一条它不联网、不启动任何子进程、不写任何文件是纯只读采集reasonix doctor capabilities --json输出是一份固定 Schema 的 JSON 报告顶层包含summary、instructions、skills、commands、hooks、plugins、mcp七个区块和扁平的issues数组。每条 issue 都有稳定错误码code、严重级别、来源、消息和remediation修复建议桌面端还能借settings_tab直接跳到对应设置页。采集逻辑在 internal/capdiag/collect.go报告结构定义在 internal/capdiag/types.go。阅读顺序建议先看summary里errors是否大于 0再按子系统逐个扫issues。错误码是稳定的比如skill.shadowed表示技能被遮蔽、mcp.start_failed表示启动失败照着它们搜文档或问人即可不要凭消息文字猜。只有当你明确需要验证 MCP 真实连通性时才用实时模式——它会真的启动第三方服务器并透传其环境变量和 header可能执行第三方代码reasonix doctor capabilities --live --timeout 5s --json桌面端 Diagnostics 页面默认走静态报告打开include current session runtime开关也只是读取当前会话中已连接/失败/延迟的服务器状态同样不会替你启动任何东西。配置从哪里来项目、全局、插件包的边界五类能力各有各的发现根目录理解边界比记住路径更重要。Skills项目级看工作区下的.reasonix/skills/同时兼容.agents、.agent、.claude三个目录复用其他 Agent 工具写好的技能不用挪文件自定义路径来自[skills].paths全局级是 Reasonix 主目录与主目录约定目录最后是随产品内置的技能。每个技能支持两种布局名字/SKILL.md的目录式或扁平的名字.md.claude下的扁平文件必须带 skill frontmatter 才会被识别。作用域定义见 internal/skill/skill.go。Commands由CommandDirsForRoot解析出主目录约定命令目录、Reasonix 主目录命令目录、项目约定命令目录三类来源见 internal/config/paths.go。命令名从相对路径推导git/commit.md会变成/git:commit。Hooks项目级在工作区/.reasonix/settings.json全局级在 Reasonix 主目录的settings.json插件包里也可以携带。MCP按用户/项目 TOML 的[[plugins]]→ 项目.mcp.json→ 已启用插件包的顺序合并名字先到先得。插件包安装状态记录在 Reasonix 主目录的plugin-packages.json被禁用的包不贡献任何 Skills、Hooks 或 MCP。指令文档REASONIX.md、AGENTS.md、CLAUDE.md及*.local.md变体按用户全局 → 祖先目录 → 项目 → 项目本地的递增特异性顺序加载会话启动时折叠进系统提示词Hooks 则是运行时事件处理器两者机制不同排查时要分开看。同名配置为什么会覆盖或隐藏另一个配置各系统的胜出规则不完全一样这是最容易混淆的地方Skills固定四级优先级project custom global builtin。高优先级作用域的同名技能胜出低优先级的被记为skill.shadowed。另外[skills].disabled_skills里列出的名字会从列表和调用中彻底消失skill.disabled。Commands扫描顺序相反——先主目录、再 Reasonix 主目录、最后项目目录后扫描的覆盖先扫描的所以项目里的.reasonix命令优先级最高。被覆盖的命令在报告里标为command.shadowed胜者是最后加载的那份。MCP合并时名字先到先得TOML 里先定义的服务器不会被.mcp.json或插件包的同名条目替换。判断哪份生效的方法只有一个看报告。Skills/Commands 区块会列出胜者winners与被遮蔽项shadowed的路径和作用域不需要自己推算。分场景排障技能、命令、Hook、MCP、插件包以下错误码均来自诊断报告每条附对应的最小修复动作。技能不出现或内容不对skill.shadowed确认胜者的 Path 与 Scope若低优先级那份才是你想要的改它的名字或删掉高优先级那份skill.missing_description技能仍会加载但索引占位弱补一行description:frontmatterskill.disabled把名字从[skills].disabled_skills移除正文不自动加载是预期行为技能正文只在通过/名字或run_skill调用时才注入命令正文错误或命令缺失command.shadowed打开报告确认哪份胜出通常是你在别的机器上带过来的同名命令覆盖了项目版本command.read_failed文件不可读修权限或编码命令整个不出现确认.md文件放在被扫描的commands/目录下而不是 skills 或其他位置Hook 不触发项目 Hook 保存后需要重启 Reasonix 才生效这是最常见原因hook.invalid_matchermatch是锚定正则写file不会匹配read_file需要.*file或用*hook.missing_command/hook.missing_context_filesettings 条目不完整补齐 command 或 context 文件hook.malformed_settingssettings.json 非法时整个文件的 Hook 都不加载但不崩溃修复 JSON 即可记住超时单位是毫秒且阻塞型事件PreToolUse、UserPromptSubmit退出码 2 可拦截主循环默认 5 秒、其余事件默认 30 秒定义见 internal/hook/hook.go钩子脚本里 sleep 太久会被直接杀掉MCP 未连接或无工具auto_startfalse的服务器启动时被跳过这是没连上的最常见原因mcp.command_not_found/mcp.missing_commandstdio 命令不在 PATH 或没写 command静态检查会先暴露命令路径问题mcp.start_failed命令能跑但进程启动失败用--live模式复现并看输出mcp.no_tools已连接但 tools 列表为空多半是服务器端权限或配置问题mcp.invalid_transporttype只支持stdio默认、http、sseTier 为eager的服务器会阻塞启动握手background/空值则后台连接、不卡聊天插件包异常单包可以用专门的命令体检reasonix plugin doctor nameplugin.missing_root包根路径不对重装或修正路径plugin.invalid_manifestmanifest 解析失败支持的格式有reasonix-plugin.json、.codex-plugin/plugin.json、.claude-plugin/plugin.jsonplugin.compatibility未映射的 Claude 专属特性只出警告Reasonix 不会虚构这些能力更完整的错误码表和报告字段说明可查官方文档 docs/CAPABILITY_DIAGNOSTICS.zh-CN.md。安全与脱敏诊断时不要做的事默认只用静态模式。--live会执行第三方 MCP 代码并可能联网没确认服务器可信前不要开报告已做脱敏env/header 只列键名env_keys、header_keys不输出值路径统一显示为workspace/…、~/…、external/…你转述报告给别人时同样不要补全 token、URL 查询串、机器绝对路径诊断命令全程只读不会替你改配置、执行 Hook 或自动重连——修复动作必须由你自己确认后再做收尾可复制的排查清单跑reasonix doctor capabilities --json先看summary.errors按issues里的稳定错误码定位不要按消息文字猜能力消失先查shadowed/disabled确认胜者的路径和作用域Hook 不触发先重启一次再检查match是否需要.*MCP 问题先确认auto_start与type需要真实连通验证时再上--live改完配置后重开会话或刷新再跑一次静态报告确认归零【免费下载链接】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），仅供参考