wehub/esengine--deepseek-reasonix

Fork 0

Files

T

wehub-resource-sync 6345505628 chore: import upstream snapshot with attribution

2026-07-13 13:00:08 +08:00

7.7 KiB

Raw Permalink Blame History

能力诊断

English · 使用指南 · 插件包

Reasonix 提供 CLI 与桌面端 设置 → 诊断 共用的只读能力诊断模型，覆盖 Skills、 Commands、Hooks、插件包、MCP 服务器，以及指令文件（AGENTS.md / REASONIX.md / CLAUDE.md）。

写入策略

模式	配置文件	MCP stats / schema cache	网络 / MCP 进程
静态（默认）+ 桌面端	永不写入（`LoadForRootReadOnly`）	永不写入	无
CLI `--live`	永不写入	不写入（`SkipPersistence`）	在隔离 Host 中启动 automatic MCP

怎么用（快速上手）

目标	命令 / 入口
检查当前工作区的 skills / hooks / MCP / 插件	`reasonix doctor capabilities`
机器可读报告（CI / 报障）	`reasonix doctor capabilities --json`
指定项目根目录	`reasonix doctor capabilities --root /path/to/project`
真实探测 MCP 启动（会启动第三方服务器）	`reasonix doctor capabilities --live --timeout 5s`
让 Agent 按手册排障	会话中 `/reasonix-guide`，或自然语言描述症状
GUI 健康视图	桌面端设置 → 诊断

默认是静态且安全的：无网络、不启动 MCP 子进程。只有你明确需要启动 automatic MCP 时才用 --live。

其它既有 doctor 命令（行为不变）：

reasonix doctor                  # 环境 / provider / 沙箱快照
reasonix doctor session <id>     # 支持用会话包
reasonix doctor redact-sessions  # 脱敏会话中的密钥

日常工作流

1. 「Skill / 命令找不到或内容不对」

reasonix doctor capabilities --json | jq '.skills.entries, .commands.entries, .issues'

关注：

skill.shadowed / command.shadowed — 更高优先级路径覆盖了它
skill.disabled — 名字在 [skills].disabled_skills 里
skill.missing_description — 能加载但索引描述很弱
command.read_failed — 文件读失败或解析失败

然后到 设置 → 技能，或直接改 .reasonix/skills / .reasonix/commands 下的文件。

2. 「项目 Hooks 不触发」

reasonix doctor capabilities | sed -n '/Hooks/,/Plugins/p'

若出现 hook.untrusted_project，在 设置 → Hooks（或 CLI trust 流程）信任该工作区。match 是锚定正则：file 不会匹配 read_file。

3. 「配置了 MCP 但模型看不到工具」

先做静态检查（无副作用）：

reasonix doctor capabilities --json | jq '.mcp.servers, .issues[] | select(.subsystem=="mcp")'

仅在接受启动第三方服务器时：

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

常见 code：mcp.command_not_found、mcp.invalid_transport、 mcp.start_failed、mcp.no_tools。桌面端更推荐 设置 → 诊断 打开「包含当前会话运行状态」——只读取活动标签 Host，不会再起第二个 Host。

4. 让 Agent 按手册排查（`reasonix-guide`）

交互式会话中：

/reasonix-guide

或：

我配置了 MCP 服务器 X，但模型始终看不到它的工具，请排查。

该内置 Skill 是 inline（runAs: inline）。它会优先要求模型运行：

reasonix doctor capabilities --json

只有你明确允许启动外部 MCP 时才建议 --live。项目或全局同名 reasonix-guide 会覆盖内置版；也可用 [skills].disabled_skills = ["reasonix-guide"] 隐藏。

CLI 参考

reasonix doctor capabilities [--root PATH] [--json] [--live] [--timeout 5s]

参数	含义
`--root`	工作区根目录（默认当前目录），走 `config.LoadForRoot`
`--json`	仅向 stdout 输出一个 JSON 对象（提示写 stderr）
`--live`	在隔离 Host 中启动 automatic MCP（可能联网）
`--timeout`	单服务器 live 超时，1s–60s，默认 `5s`，必须配合 `--live`

模式

模式	行为
静态（默认）	无网络；不启动 stdio / HTTP / SSE MCP 子进程
Live（`--live`）	stderr 风险提示；只探测 automatic 启动意图；`auto_start=false` → `skipped`；并发 4；始终关闭 Host

桌面端「包含当前会话运行状态」不等于 CLI --live：桌面只读取活动标签 Host，不启动 MCP。

退出码

码	含义
`0`	无 `error` 级问题（warning/info 允许）
`1`	存在 `error` 或 live MCP 启动失败
`2`	参数错误

示例：

# 当前目录、人类可读
reasonix doctor capabilities

# CI：仅有 error 时非零退出
reasonix doctor capabilities --json

# live 探测，超时 15 秒
reasonix doctor capabilities --live --timeout 15s --json 2>live-warn.txt

既有 reasonix doctor / doctor session / doctor redact-sessions 的 JSON schema 不会混入新字段。

桌面端

打开 设置 → 诊断：

控件	行为
打开页面	对活动工作区根加载静态报告
刷新	按当前「会话运行状态」开关重新收集
复制脱敏 JSON	可安全粘贴的报告（路径已脱敏）
包含当前会话运行状态	仅合并活动标签 Host 的 connected / failed / deferred / disabled
前往设置（Issue 上）	当 `settings_tab` 有值时跳到 MCP / Skills / Plugins / Hooks

页面不提供自动编辑、自动 trust、自动启用或自动重连。打开诊断页不会 rebuild controller，也不会 snapshot 会话。

JSON schema（version 1）

顶层字段：schema_version、root、live、summary、 instructions / skills / commands / hooks / plugins / mcp、issues。

Issue 含稳定 code、severity、subsystem、source、message、remediation、可选 settings_tab。数组与 Issue 顺序确定，便于脚本与测试。

常见 code：

skill.shadowed、skill.missing_description、skill.disabled
command.shadowed、command.read_failed
hook.untrusted_project、hook.invalid_matcher、hook.missing_command、hook.malformed_settings
plugin.missing_root、plugin.invalid_manifest、plugin.compatibility
mcp.invalid_transport、mcp.command_not_found、mcp.missing_command、mcp.missing_url
mcp.start_failed、mcp.no_tools、mcp.runtime_unavailable

严重度

严重度	含义	CLI
`error`	配置损坏或 live 启动失败	退出 `1`
`warning`	需处理但非致命	退出 `0`
`info`	遮蔽、禁用、无运行时等	退出 `0`

路径与密钥安全

路径显示为 <workspace>/...、~/... 或 <external>/basename。不输出用户名、完整外部路径、环境变量值、Header 值、token、URL query。 MCP 仅列出 env/header 的 key。可能携带 HTTP 响应体或 MCP stderr 的错误文本会先经过全局密钥脱敏器（Authorization、Bearer/JWT/厂商 token、 KEY=value 与 JSON "key":"value" 凭据形态、Cookie/Set-Cookie 值），再截断到 400 字符。向 issue / 聊天贴报告时，优先复制诊断 JSON，不要贴原始配置文件。

不在本诊断范围内的事项

需求	改用
Provider 密钥、代理、沙箱 OS 支持	`reasonix doctor`
给支持用的完整会话包	`reasonix doctor session <id>`
单个插件包	`reasonix plugin doctor <name>`
会话内 MCP 列表	`/mcp`

缓存影响

内置 reasonix-guide 仅在 system prompt 的 Skill 索引中增加 一行稳定索引；正文按需加载。诊断本身不进入 provider 请求。

7.7 KiB Raw Permalink Blame History Unescape Escape