Reasonix 能力诊断完全指南五大能力体系配置优先级与排障清单的 10 分钟上手【免费下载链接】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-native 的 AI coding agent。本文围绕它的五大能力体系Skills / Commands / Hooks / MCP 服务器 / 插件包外加 AGENTS.md 指令文档讲清楚配置从哪来、同名冲突时谁胜出、出了问题怎么查。读完后你能用reasonix doctor capabilities生成并读懂静态能力报告解释skill.shadowed、mcp.start_failed这类稳定错误码并按清单定位技能消失、命令被覆盖、Hook 不触发、MCP 连不上等典型故障。从一个真实故障切入技能怎么突然不见了昨天会话里还能调的技能今天找不到了——这是最常见的抱怨。原因往往不是文件丢了而是同名规则起了作用技能、命令、MCP 服务器都按名字解析出唯一胜者你在高优先级目录里的某个同名文件把当前用的那个遮蔽了。所以在改任何配置之前先取证再动手。先取证生成并读懂静态能力报告静态报告是排查的第一步零副作用Collectinternal/capdiag/collect.go通过config.LoadForRootReadOnly只读加载配置全程不写 config、cache、state、日志也不启动任何 MCP 子进程CLI 侧由doctorCapabilitiesCommand分发internal/cli/doctor.go。reasonix doctor capabilities --json报告顶层结构固定SchemaVersion 1见 internal/capdiag/types.gosummary各区块计数、instructions、skills、commands、hooks、plugins、mcp以及扁平的issues数组。每条 issue 都带severityerror/warning/info、code稳定错误码、subsystem、source来源、message以及remediation修复建议部分还带settings_tab桌面端可据此跳到 MCP / Skills / Plugins / Hooks 设置页。排查方法很简单按code定位区块照remediation执行。报告不会给出源码之外的修复——比如skill.shadowedinfo的 remediation 是若胜者不是故意的重命名、删除或禁用低优先级那份mcp.start_failederror的 remediation 是检查服务器日志、命令/URL 与鉴权。报告没写的原因就以报告输出为准不要凭空补。五大能力体系的来源与优先级总表能力来源低 → 高同名冲突规则Skillsbuiltin → globalReasonix home 与主目录约定目录→ custom[skills].paths与插件包技能根→ projectworkspace/{.reasonix,.agents,.agent,.claude}/skills/project custom global builtin高者胜、低者被遮蔽internal/skill/skill.go的Scope枚举Commands主目录约定 commands 目录 → Reasonix 主目录 commands → 项目约定 commands 目录同级内.claude先扫、.reasonix后扫后扫描的目录覆盖先扫描的.reasonix优先级最高internal/config/paths.goHooks插件包、全局Reasonix home/settings.json、项目.reasonix/settings.json不互相覆盖项目 Hook 先于全局触发MCP 服务器已启用插件包 → 项目.mcp.json→ TOML[[plugins]]先定义的名字胜出后序来源同名跳过internal/config/load.go插件包Reasonix home/plugin-packages.json只有 enabled 的包才贡献能力指令文档用户全局 → 祖先目录链 → 项目 → 项目本地*.local.md特异性递增地叠加加载不存在胜者技能同名冲突时谁胜出约定目录来自ConventionDirsinternal/config/paths.go.reasonix、.agents、.agent、.claude后三个是为了让你直接复用为其他 Agent 工具写的资产。两种布局都认name/SKILL.md目录式以及name.md扁平式——注意.claude下的扁平文件必须带技能 frontmatter 才会被识别。写进[skills].disabled_skills的名字会被整体隐藏从 List/Read 里彻底消失错误码skill.disabled。一个容易误解的假故障技能的正文不会常驻加载只有名字和 description 进入系统提示词索引正文在/name或run_skill调用时才按需读入。没看到正文是预期行为。坑点绕法技能从索引消失依次核对是否在disabled_skillsskill.disabled、是否被同名遮蔽skill.shadowed报告里winner_path指向胜者、是否缺description:skill.missing_description能加载但索引质量弱有意覆盖内置技能后想撤销删除或重命名用户侧同名技能即可不需要动内置侧.claude扁平文件不认补 frontmatter或改成SKILL.md目录式布局改完配置不生效重开会话或刷新 Skills 再验证检查入口CLI 看 Skills 区块桌面端 Settings → Skills 或 Settings → DiagnosticsAgent 内可用/skill列表。桌面端的技能面板长这样斜杠命令的覆盖方向与缺失排查命令的优先级方向和技能相反command.Load让后扫描的目录胜出。扫描顺序为主目录约定命令目录 → Reasonix 主目录命令目录 → 项目约定命令目录同级内部.claude先扫、.reasonix最后扫所以项目里的.reasonix/commands是最高优先级已启用的插件包也会贡献 commands 目录。命令名从路径推导git/commit.md变成/git:commit斜杠转冒号internal/command/command.go。排查三问正文不对 → 查command.shadowed看胜者在哪个目录文件报command.read_failed→ 修权限或编码或移除坏文件完全找不到 → 确认*.md放在被扫描的commands/根下且扩展名正确。聊天里直接输/name是最快的验证手段。Hook 不触发的自查清单11 个受支持事件中只有PreToolUse和UserPromptSubmit是阻塞型gating退出码 2 可拦截主循环其余事件只产生告警或贡献上下文。超时默认值internal/hook/hook.goPreToolUse/PermissionRequest/UserPromptSubmit为 5 秒其余 30 秒settings 里的timeout_ms单位是毫秒。来源有三项目.reasonix/settings.json保存后自动加载需重启 Reasonix 生效、全局Reasonix home/settings.json始终加载、已启用的插件包。match字段是锚定正则file匹配不到read_file要写.*file留空或*匹配全部工具。Hook 不触发时按序自查报告hooks.sources里有没有目标 settings 文件带hook.malformed_settings说明 JSON 坏了——此时该来源一条 Hook 都不加载但程序不会崩。事件名是否拼错11 个之外会报hook.unknown_eventcommand和contextFile是否至少填了一个hook.missing_commandcontext 文件存在且可读吗hook.missing_context_filematch是否按锚定语义写了hook.invalid_matcher的 remediation 会明确提示 matchers are fully anchoredWindows 上 shell 是否可用hook.shell_unavailableremediation 指向 Git Bash 或[tools.shell]配置项目 Hook 的话工作区是否选对了保存后是否重启过MCP 连不上的四个原因合并逻辑internal/config/load.goTOML[[plugins]]先定义项目.mcp.json中同名服务器跳过已启用插件包的 MCP 最后合并、名字已定义则跳过。传输方式支持stdio默认、httpstreamable-http、ssetype写错报mcp.invalid_transport。auto_startfalse时启动意图为 offtier 为eager的服务器会阻塞启动握手空或background则后台连接、不挡聊天。连不上通常落在四种情况之一根本没打算启动报告里start_intent为off这是配置意图而非故障把auto_start设为 true 或显式激活即可。命令找不到mcp.command_not_found是 warning——静态 PATH 查不到不代表运行时真起不来GUI/登录 shell 的 PATH 更丰富remediation 建议用绝对路径、在服务器 env 里设 PATH或用会话运行时 /--live验证。command 直接为空则是mcp.missing_commanderror。URL 缺失非 stdio 服务器 url 为空报mcp.missing_url填 http(s) 地址。启动了但失败mcp.start_failed会附带 error、stderr 与启动阶段信息连上了却mcp.no_tools则按 remediation 检查服务器配置与鉴权。另外注意来源错误类问题报告每个服务器带sourceuser_config / project_config / project_mcp_json / plugin_package与package_owner字段先确认这个服务器到底归谁定义再改对文件。插件包的状态检查与兼容警告三种 Manifest 都认原生reasonix-plugin.json、Codex 的.codex-plugin/plugin.json、Claude 的.claude-plugin/plugin.json含有限的兼容路径。安装状态记录在Reasonix home/plugin-packages.json。被禁用的包不贡献任何 Skills / Hooks / MCP——包里的技能消失时先查enabled。Reasonix 不会虚构能力映射不了的 Claude/Codex 专属特性会以plugin.compatibility警告出现报告中的warnings字段可直接读。包级状态取值ok/missing_root根路径没了plugin.missing_root/invalid_manifestplugin.invalid_manifest/disabled。单包排查命令reasonix plugin doctor nameAGENTS.md 加载顺序为什么改了指令不生效可识别的文件名是REASONIX.md、AGENTS.md、CLAUDE.md及各自的*.local.md变体加载顺序按特异性递增用户全局文档 → 祖先目录链 → 项目文档 → 项目本地文档。同一目录可以加载多个文件符号链接指向同一身份会去重。排查时区分两种机制指令文档在会话启动时折叠进系统提示词构成缓存稳定的前缀所以改完要开新会话才生效Hooks 是运行时事件处理器按各自配置位置加载保存后按来源规则重新加载。文件识别错了、或者放在了不在祖先链上的目录症状都是指令被忽略——Diagnostics → Instructions 会按order列出实际加载序列照着对一遍即可。实时探测 --live何时用、注意什么静态报告只读--live会在隔离 Host 中真实启动第三方 MCP 子进程可能联网并透传配置的 env/header等于执行第三方代码只在明确需要时开启reasonix doctor capabilities --live --timeout 5s --json约束只启动 auto-start 服务器并发 4探测结束总是 Closetimeout 被限制在 1~60 秒之间缺省 5 秒。桌面端 Diagnostics 默认走只读路径仅读活动标签页 Host 的 connected/failed/deferred/disabled 状态从不自动改配置、执行 Hook 或重连。脱敏规则值得知道env_keys、header_keys只列键名不列值URL 只保留 host查询串被剥掉绝对路径改写成workspace/…、~/…、external/…Bearer 令牌、PATH 值等在报错文本里统一替换为redacted。排查顺序与常用命令速查建议的固定顺序先跑静态报告不动任何配置issues按 error → warning → info 读逐条照remediation执行静态定位不到、怀疑是启动问题时才用--live验证承担联网风险修完重跑报告复核指令类改动记得开新会话。用途命令 / 入口静态能力报告首选reasonix doctor capabilities --json实时 MCP 探测会联网reasonix doctor capabilities --live --timeout 5s --json单插件包诊断reasonix plugin doctor name技能 / 命令 / Hook / MCP 入口桌面端 Settings → Skills / Hooks / Plugins / MCP或 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-Reasonix创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考