Reasonix 能力诊断快速清单：6 大能力的加载顺序与一分钟排障

Reasonix 能力诊断快速清单：6 大能力的加载顺序与一分钟排障

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

Reasonix 内置一套完整的能力诊断：一条只读命令，就能拿到覆盖技能、斜杠命令、Hooks、MCP 服务器、插件包、指令文档六大体系的报告。掌握本篇的排障路径，你可以独立定位技能被遮蔽、MCP 连不上这类问题，不再靠猜。

⚡ 快速上手：先跑这条诊断命令

诊断入口只有一条命令，默认就是纯静态报告：不发网络请求、不启动任何子进程，磁盘零写入。

reasonix doctor capabilities --json

实时探测是另一回事：--live会真正拉起第三方 MCP 服务器，可能联网并透传配置好的 env/header，必须显式声明、确认允许才用。

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

对比项	静态（默认）	--live实时
触发方式	追加--json	追加--live --timeout 5s
副作用	零：只读、无网络请求、无 MCP 子进程	会拉起第三方 MCP 服务器，可能联网

输出一份稳定的 JSON Schema：顶层有summary总览，skills、commands、hooks、plugins、mcp、instructions各自成块，外加一个扁平的issues数组。每条 issue 结构统一：稳定错误码（固定不变、机器可读的编码）+ 严重级别 + 来源 + remediation 修复建议，带settings_tab的还能在桌面端一键跳到对应设置页。排障时直接照报告读错误码、来源和修复项，别自创方案。采集逻辑见 internal/capdiag/。

一图看懂"遮蔽与合并"

所有"能力消失"类问题都指向同一个根源：遮蔽（shadowing）——高优先级文件与它同名，低优先级那份仍在磁盘上，但永远不会被加载。就像同一目录放了两个同名文件，你只能看见最上面那个。

技能按名字定唯一胜者，共四层作用域（scope，决定同名文件谁胜出的层级），从高到低：

1. project—<workspace>/{.reasonix,.agents,.agent,.claude}/skills/
2. custom—[skills].paths（含插件包内的技能根目录）
3. global—<Reasonix home>/skills与主目录约定目录
4. builtin— 产品内置

名字一旦进了[skills].disabled_skills，则整体隐藏，从列表和读取中彻底消失。作用域枚举的定义在 internal/skill/。

斜杠命令走另一套规则：三级命令目录按"主目录约定 → Reasonix 主目录 → 项目约定"依次扫描，后扫描的覆盖先扫描的；约定目录内部.reasonix优先级最高，所以同名git/commit.md最终由项目的.reasonix说了算。

这两种情形分别对应报告里的skill.shadowed与command.shadowed，胜者的 Path 和来源都直接列出，照着去低优先级根目录找就行。

逐项体检：6 个组件的 1 分钟验证法

Reasonix 排障卡住时，先按组件各跑一遍一分钟检查。每个组件固定三步：从哪加载、怎么确认活着、最易踩的坑。

Reasonix skill 被遮蔽？1 分钟查清加载来源

技能没显示，八成是遮蔽、禁用、缺 frontmatter 三选一。

从哪加载：上文四层作用域目录；两种布局——目录式<name>/SKILL.md与扁平式<name>.md（.claude下的扁平文件必须带 skill frontmatter 才被识别）。

确认活着：跑reasonix doctor capabilities看 Skills 区块；或桌面端 Settings → Skills。

最易踩的坑：

• 技能从索引消失 → 名字进了disabled_skills或被更高作用域遮蔽 → 对照skill.shadowed与禁用列表。
• .claude扁平文件被忽略 → 缺 skill frontmatter → 补description:/runAs:，或改SKILL.md目录式。
• 正文从不自动加载 → 属正常：正文按需加载 → 用/name或run_skill调起。

斜杠命令正文是否被覆盖

命令"能跑但正文不对"，基本是覆盖问题，不是 bug。

从哪加载：上文三级扫描顺序；命令名由路径推导，斜杠转冒号，git/commit.md变成/git:commit。

确认活着：Diagnostics → Commands 区块；或在聊天里直接敲/name，看返回的是不是你要的那份正文。

最易踩的坑：

• 正文不是自己的 → 被后扫描目录覆盖 → 查command.shadowed的胜者。
• 文件在但解析失败 → 权限或编码问题 → 修到可读，对应command.read_failed。
• 命令根本不出现 → 目录或扩展名放错 → 把*.md放进被扫描的commands/根下。

Reasonix hook 不触发？先看这 2 个阻塞型事件

11 个 Hook 事件里只有 2 个能拦下主循环，排障从这里入手。

从哪加载：三处——项目<workspace>/.reasonix/settings.json（保存即自动加载，但需重启 Reasonix 生效）、已启用的插件包、全局<Reasonix home>/settings.json（始终加载）。

确认活着：/hooks命令；或 Settings → Hooks。

关键事实：仅PreToolUse与UserPromptSubmit是阻塞型事件（blocking，退出码 2 可拦截主循环）；阻塞事件默认超时 5 秒，其余默认 30 秒；match字段是锚定正则；超时单位是毫秒。超时定义见 internal/hook/。

最易踩的坑：

• 项目 Hook 静默失效 → settings.json 保存了但没重启 → 重启 Reasonix。
• 匹配器永不触发 → 误以为match非锚定：裸file打不中read_file→ 写成.*file或*，对应hook.invalid_matcher。
• settings.json 非法 → 不加载任何 Hook，但不会崩溃 → 修好 JSON。

Reasonix MCP 连不上先查这三处

MCP 连不上，十有八九是没启用、启动失败、合并顺序没看懂三选一。

从哪加载：三级合并——用户/项目 TOML 的[[plugins]]→ 项目.mcp.json（同名跳过）→ 已启用插件包的 MCP（同名跳过）；同名时先定义者胜出。auto_start设为 false 的服务器启动时直接跳过；Tier 设为eager时握手会阻塞启动，空或background则后台连接、不挡聊天。传输支持stdio（默认）、http、sse。

确认活着：静态 doctor 只校验配置合法性、命令路径/URL 形态与启动意图，不拉子进程；要真连就用--live；桌面端可直接看活动标签页的当前连接状态。

最易踩的坑：

• 服务器始终没连上 →auto_start=false或启动失败 → 启用或修命令/URL，对应mcp.command_not_found、mcp.start_failed。
• 连上了却没有工具 → tools/list 返回空 → 查服务器配置与权限，对应mcp.no_tools。
• 传输类型无效 →type不是 stdio/http/sse → 改对取值，对应mcp.invalid_transport。

报告只列 env/header 的键名、绝不输出值——这两处常放密钥。

用 Reasonix plugin doctor 隔离单个包

插件包出问题，单包隔离最快，别查整个体系。

从哪加载：三种 manifest——原生reasonix-plugin.json、Codex 的.codex-plugin/plugin.json、Claude 的.claude-plugin/plugin.json；安装状态存于<Reasonix home>/plugin-packages.json。关键规则：包一旦被禁用，它带来的技能、Hooks、MCP 全部不生效。

确认活着：跑单包隔离命令；或 Settings → Plugins、Diagnostics → Plugins。

reasonix plugin doctor <name>

最易踩的坑：

• 包被报缺失 → 根路径错误 → 重装或修根路径，对应plugin.missing_root。
• Manifest 解析失败 → JSON/manifest 非法 → 修文件，对应plugin.invalid_manifest。
• 包内技能不见 → 包被禁用 → 启用它。

指令文档是否折进了系统提示词

指令文档不生效，先查文件名和位置对不对。

从哪加载：特异性递增的四级顺序——用户全局文档 → 祖先目录链 → 项目文档 → 项目本地文档（*.local.md）；可识别文件名是REASONIX.md、AGENTS.md、CLAUDE.md及其*.local.md变体。

确认活着：Diagnostics → Instructions 区块；或直接读磁盘文件。

最易踩的坑：

• 指令被忽略 → 文件名不被识别或文件为空 → 在正确目录下用可识别文件名。
• 错了层级的内容胜出 → 本地文件覆盖所致 → 看报告里的加载顺序。

注意区分机制：这些文档在会话启动时折进系统提示词，构成缓存稳定的前缀；Hooks 则是按各自配置位置加载的运行时事件处理器。两者互不影响，排查时别混。

桌面端 Diagnostics 页：报告页还能做什么

桌面 Diagnostics 页是个只读面，和 CLI 复用同一套静态采集：

• 打开即静态报告，Refresh 重新执行一次静态采集。
• 可复制脱敏（剔除敏感取值）后的 JSON，直接贴进工单。
• 可选合并会话运行时信息：仅读取活动标签页 Host 的 connected/failed/deferred/disabled 状态，不启动 MCP。
• issue 带settings_tab时，一键跳到它指向的设置页；页面自身不改任何配置、不跑 Hook、不自动重连。

🛡️ 安全红线：报告里绝不出现什么

报告的设计原则是"敏感零泄漏"，以下内容不会出现在其中：

• 优先静态诊断；--live可能执行第三方代码并联网，获允许才用。
• token、header/env 取值、URL 查询串、用户名、机器绝对路径一律不输出。
• env/header 只给键名（env_keys、header_keys），值永远不露面。
• 路径统一以<workspace>/…、~/…、<external>/…脱敏形式呈现。
• 全程严格只读：不改既有配置，不产生新文件。

排障永远先取证、后修复：让报告里的稳定错误码和 remediation 说话，别凭手感动手。

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