Reasonix 能力诊断完整指南五大扩展体系配置与快速排障一次讲清【免费下载链接】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 是一个面向终端的 DeepSeek 原生 AI 编码智能体。技能消失了、MCP 连不上、Hook 不触发用内置的reasonix doctor capabilities体检命令把 Skills / Commands / Hooks / MCP / 插件包五大体系与 AGENTS.md 指令文档的配置来源、优先级裁决、排障路径一次理清楚。一、谁说了算同名冲突的裁决规则五大体系加指令文档最容易让人懵的问题是同一个名字配了两份到底执行哪份先讲透裁决规则后面排障全是顺藤摸瓜。Skills作用域四层越贴近项目越强裁决按作用域硬排座次project custom global builtin定义见 技能作用域定义。同名时高作用域胜出输家被标记为 shadowed遮蔽不再是两份都在而是只剩一份。Commands扫描有先后后扫的覆盖先扫的命令目录按优先级从低到高依次扫描插件包命令目录 → 主目录约定命令目录 → Reasonix 主目录命令目录 → 项目约定命令目录。语义很简单——后扫描的目录在同名冲突时覆盖先扫描的同一组约定目录里.reasonix排最后扫描也就是最高优先级扫描顺序见 约定目录与命令解析。命令名从路径推导git/commit.md就是/git:commit斜杠变冒号。Hooks没有遮蔽但一坏就全坏Hooks 不存在同名竞争三个来源共存生效项目workspace/.reasonix/settings.json、已启用的插件包、全局Reasonix home/settings.json始终加载。但注意某个 settings.json 若是坏 JSON该文件里的 Hook 一条都不会加载——整个来源静默下线程序本身不崩。MCP先定义的名字赢配置按固定顺序合并① 用户/项目 TOML 的[[plugins]]TOML 里先定义的名字胜出→ ② 项目.mcp.json只补 TOML 里没有的服务器→ ③ 已启用的插件包名字已定义则跳过。所以一台服务器只有一个归属来源报告里的Source字段会告诉你它是toml、mcp_json还是plugin_package。指令文档不是决出胜者而是一条链REASONIX.md、AGENTS.md、CLAUDE.md及*.local.md变体按用户全局 → 祖先目录链 → 项目 → 项目本地特异性递增地全部加载没有谁把谁踢掉。关键区别这些指令在会话启动时折叠进系统提示词构成缓存稳定的前缀改完要新开会话才生效Hooks 则一直是运行时事件处理器两者机制完全不同排障时别混为一谈。能力项裁决顺序左强右弱输家怎么被处理Skillsproject custom global builtin标记skill.shadowed从索引中隐身Commands项目约定目录 Reasonix 主目录 主目录约定目录 插件包组内.reasonix最强标记command.shadowed被后扫描版本整体替换Hooks无命名竞争三来源并存settings.json 坏 JSON → 该来源条目全部失效MCPTOML先定义者胜.mcp.json 插件包同名条目直接跳过只保留首个定义指令文档项目本地*.local.md 项目 祖先 用户全局不淘汰全部按序拼进系统提示词二、怎么开体检静态与--live的边界静态报告默认零副作用reasonix doctor capabilities reasonix doctor capabilities --json为什么默认只读采集逻辑以只读模式加载配置不发任何网络请求、不启动任何 MCP 子进程、不写任何文件这一点在 报告采集逻辑 与 internal/capdiag/collect.go 中写得很直白。报告里一旦出现 error 级 issue命令退出码为 1方便接进脚本做门禁。--live唯一会动真格的模式reasonix doctor capabilities --live --timeout 5s只有加--live才会启动第三方 MCP 服务器——它可能在隔离 Host 里拉起真实进程、联网并透传你配置的那台服务器的 env 与 header。--timeout控制单服务器探测超时1s~60s默认 5s。拿不准时先跑静态live 留给静态看不出问题的疑难。JSON 报告怎么读顶层就几个大块schemaVersion、summary各能力计数 error/warning/info 汇总、instructions/skills/commands/hooks/plugins/mcp六个区块以及一个扁平的issues数组。每条 issue 带稳定错误码code、严重级别、来源、消息和修复建议remediation部分还带settings_tab——桌面端能凭它直接跳到对应设置页。排障时直接引用报告里的错误码别自己脑补修复方案。桌面端 Diagnostics 页面怎么用打开即展示静态报告Refresh 重新执行静态采集JSON 可一键复制且已脱敏include current session runtime 开关是只读的只合并活动标签页 Host 的 connected / failed / deferred / disabled 状态不启动任何东西issue 带settings_tab时可直跳 MCP / Skills / Plugins / Hooks 设置页该页面从不自动改配置、从不执行 Hook、从不自动重连三、五大能力逐个过3.1 静态资产线Skills技能被遮蔽了怎么办定位技能是命名的提示词包——只有名字和描述常驻系统提示词索引正文按需加载/name或run_skill调用时才读。放哪里projectworkspace/{.reasonix,.agents,.agent,.claude}/skills/custom[skills].paths追加的路径 插件包内技能目录globalReasonix home/skills与主目录下四个约定目录builtin随产品内置约定目录里.reasonix是原生位后三个.agents/.agent/.claude是为了让你复用给其他 Agent 工具写的技能文件不用挪。布局支持两种name/SKILL.md目录式和name.md扁平式.claude下的扁平文件必须带技能 frontmatter 才认。怎么验证reasonix doctor capabilities的 Skills 区块桌面 Settings → Skills会话内/skill列表。最易踩的三个坑问技能从索引里消失了答先查名字是否在disabled_skills禁用是彻底消失再查 shadowed 状态。问.claude下放了扁平文件没被识别答缺 frontmatter——补description:等字段或改成SKILL.md目录式。问description 为什么重要答进索引的只有名字 描述正文懒加载。描述写得糊模型就看不见这个技能。Commands斜杠模板配好却没生效定位命令是用户手敲的斜杠模板和技能的模型调用是两个入口。放哪里各约定目录下的commands/。扫描覆盖顺序前面讲过插件包 → 主目录约定目录 → Reasonix 主目录 → 项目约定目录后扫覆盖先扫。怎么验证Diagnostics → Commands 区块看胜者聊天里直接敲/name试。最易踩的三个坑问命令正文不是我写的那份答被后扫描目录覆盖了顺着command.shadowed找胜者路径。问命令压根不存在答检查文件是否在受扫描的commands/根下、扩展名是不是.md。问报command.read_failed答文件读不出来——修权限或编码。指令文档AGENTS.md 加载顺序与生效时机定位指令文档是折叠进系统提示词的项目手册不是事件处理器。加载顺序特异性递增用户全局文档 → 祖先目录链 → 项目文档 → 项目本地*.local.md。同一目录可并存多个可识别文件符号链接指向同一身份会去重。怎么验证Diagnostics → Instructions 区块能看到加载顺序与深度最朴素的办法是直接看磁盘文件。最易踩的三个坑问指令像没生效答文件名必须是可识别的几个REASONIX.md/AGENTS.md/CLAUDE.md及.local变体空文件等于没写。问改完文档行为没变答指令在会话启动时折叠重开会话再说。问两份文件说法矛盾答没有胜者全部生效、本地更具体——看报告里的加载顺序确认链子。3.2 运行时线Hooks11 个事件两个能叫停定位Hook 是主循环各节点上的运行时事件处理器共 11 个事件PreToolUse、PostToolUse、PermissionRequest、UserPromptSubmit、Stop、PostLLMCall、SessionStart、SessionEnd、SubagentStop、Notification、PreCompact。其中PreToolUse与UserPromptSubmit是阻塞型——返回退出码 2 能拦截主循环gating见 Hook 阻塞事件与默认超时其余事件只产出告警或贡献上下文。放哪里项目.reasonix/settings.json保存后自动加载需重启 Reasonix 生效、已启用的插件包、全局Reasonix home/settings.json始终加载。怎么验证会话内/hooksSettings → HooksDiagnostics → Hooks。最易踩的三个坑问项目 Hook 静默失效答两个嫌疑——工作区指错了或保存后忘了重启。问匹配器永不触发答match是锚定正则file匹配不到read_file得写.*file或用*对应hook.invalid_matcher。问超时怎么配答单位是毫秒阻塞事件默认 5 秒其他默认 30 秒。MCPMCP 连不上怎么查定位MCP 是 Reasonix 外接工具服务器的通道。传输方式三种stdio默认起本地进程、httpstreamable-http、sse。放哪里TOML[[plugins]]、项目.mcp.json、插件包——合并顺序见第一节。两个开关值得记auto_startfalse表示会话启动时跳过Tier 为eager会阻塞启动握手空或background则后台连接、不挡聊天。怎么验证三种模式别混模式行为静态 doctor只校验配置合法性、命令路径 / URL 形态、启动意图不启动进程CLI--live在隔离 Host 中启动 auto-start 服务器探完即关桌面端运行时只读活动标签页 Host 的连接状态MCP 连不上怎么查问状态是未连接答先看auto_startfalse是不是自己关的再看mcp.command_not_found/mcp.start_failed——把命令换成绝对路径或给 env 里设 PATH。问连上了但一个工具都没有答mcp.no_tools查服务器配置与鉴权/权限。问我的服务器配置像消失了答多半被更高优先级来源遮蔽看报告Source字段确认归属。插件包插件包不生效的三种原因定位插件包是技能 命令 Hooks MCP的捆绑发行单元。Manifest 认三种形态原生reasonix-plugin.json、Codex.codex-plugin/plugin.json、Claude.claude-plugin/plugin.jsonClaude 专属特性只给兼容性警告不会假装支持。放哪里安装状态记录在Reasonix home/plugin-packages.json。被禁用的包不贡献任何 Skills / Hooks / MCP——零贡献不是半贡献。怎么验证reasonix plugin doctor nameSettings → PluginsDiagnostics → Plugins。不生效的三种原因根目录被挪走 / 删除 →plugin.missing_root重装或修根路径Manifest 解析失败 →plugin.invalid_manifest修 JSON包被禁用 → 在设置页重新启用四、卡住了先问三件事排障别撒网按顺序过这三关大多数问题第二关就现形是不是被禁用了disabled_skills、禁用的插件包、auto_startfalse、坏掉的 settings.json——都属于电源自己被人拔了报告里都有对应 issue。是不是被高优先级来源遮蔽了报告里找skill.shadowed/command.shadowed看胜者的 Path 是不是你预期的那份MCP 则看Source确认归属来源。文件名、路径、格式对不对SKILL.md布局、.md扩展名、可识别的指令文件名、锚定正则的match——静默失效九成死在这一关。高频错误码速查错误码在说什么先做哪一步skill.shadowed同名技能被更高作用域压住看胜者 Path改名或删掉低优先级那份skill.missing_description缺描述索引占位弱补一行description:frontmatterskill.disabled名字进了disabled_skills从禁用列表移除command.shadowed命令被后扫描目录覆盖核对胜者确认覆盖是否有意command.read_failed命令文件读不出修权限 / 编码hook.invalid_matchermatch 不是合法锚定正则改成.*xxx或*hook.malformed_settingssettings.json 是坏 JSON修 JSON该文件 Hook 全部未加载mcp.start_failed服务器启动 / 握手失败查日志、命令/URL、鉴权mcp.no_tools已连接但 tools/list 为空查服务器配置与权限mcp.command_not_foundstdio 命令静态 PATH 找不到用绝对路径或在 env 里设 PATHplugin.invalid_manifestManifest 解析失败修三种形态之一的 JSONplugin.missing_root包根目录不存在重装或修根路径五、安全红线静态优先静态报告完全只读能跑静态就别跑 live。--live的副作用要想清楚它会执行第三方 MCP 代码并可能联网且透传对应服务器配置的 env / header。跑之前确认你知道哪些服务器会被拉起、密钥会流向哪里。脱敏规则报告只列env_keys/header_keys键名绝不输出值token、URL 查询串、用户名、机器绝对外部路径一律不出现——路径统一以workspace/…、~/…、external/…形式呈现。顺带提醒reasonix doctor session打包的会话 bundle不做脱敏只发给可信的支持渠道。六、动手之前先取证别急着改配置。先跑一遍reasonix doctor capabilities --json把错误码、来源、修复建议都读一遍——绝大多数消失的能力其实安静地躺在报告里等你认领。先取证后动手改哪一处都心里有数。【免费下载链接】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），仅供参考