esengine--deepseek-reasonix/docs/CAPABILITY_DIAGNOSTICS.md

Capability diagnostics

简体中文  ·  Guide  ·  Plugin packages

Reasonix ships a read-only capability diagnostics model shared by the CLI and desktop Settings → Diagnostics. It reports Skills, Commands, Hooks, plugin packages, MCP servers, and instruction docs (AGENTS.md / REASONIX.md / CLAUDE.md).

Write policy

Mode	Config files	MCP stats / schema cache	Network / MCP processes
Static (default) + desktop	Never written (LoadForRootReadOnly)	Never written	None
CLI --live	Never written	Not written (SkipPersistence)	Starts automatic MCP in an isolated Host

How to use (quick start)

Goal	What to run
Check this workspace’s skills / hooks / MCP / plugins	reasonix doctor capabilities
Machine-readable report (CI / support)	reasonix doctor capabilities --json
Another project root	reasonix doctor capabilities --root /path/to/project
Probe MCP startup for real (starts third-party servers)	reasonix doctor capabilities --live --timeout 5s
Ask the agent to walk through config / fix guidance	/reasonix-guide in chat, or ask naturally
GUI health view	Desktop Settings → Diagnostics

Default is static and safe: no network, no MCP child processes. Use --live only when you explicitly want to start automatic MCP servers.

Related (unchanged) doctor commands:

reasonix doctor                  # env / providers / sandbox snapshot
reasonix doctor session <id>     # support session bundle
reasonix doctor redact-sessions  # redact secrets in session files

Everyday workflows

1. “Skill / command is missing or wrong”

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

Look for:

• skill.shadowed / command.shadowed — a higher-priority path won
• skill.disabled — name is in [skills].disabled_skills
• skill.missing_description — skill loads but index quality is weak
• command.read_failed — unreadable or broken markdown

Then open Settings → Skills (or fix the file under .reasonix/skills / .reasonix/commands).

2. “Project hooks never fire”

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

If you see hook.untrusted_project, trust the workspace in Settings → Hooks (or the CLI trust flow). Matchers are anchored regexes: file does not match read_file.

3. “MCP tools don’t show up”

1. Static first (no side effects):

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

2. Only if you accept starting third-party servers:

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

Common codes: mcp.command_not_found, mcp.invalid_transport, mcp.start_failed, mcp.no_tools. On desktop, prefer Settings → Diagnostics with “Include current session runtime” to read the active tab Host without starting a second Host.

4. Ask the agent (reasonix-guide)

In an interactive session:

/reasonix-guide

or:

My MCP server X is configured but the model never sees its tools — diagnose.

The built-in skill is inline (runAs: inline). It tells the model to prefer:

reasonix doctor capabilities --json

and to use --live only after you explicitly allow external MCP. Project or global skills named reasonix-guide override the builtin; you can also hide it with [skills].disabled_skills = ["reasonix-guide"].

CLI reference

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

Flag	Meaning
--root	Workspace root (default: current directory). Uses config.LoadForRoot.
--json	Write one JSON object to stdout only (warnings go to stderr).
--live	Start automatic MCP servers in an isolated Host (may network).
--timeout	Per-server live timeout, 1s–60s, default 5s. Requires --live.

Modes

Mode	Behavior
Static (default)	No network; no stdio / HTTP / SSE MCP child processes.
Live (--live)	Stderr risk banner; only servers with automatic start intent; auto_start=false → skipped; concurrency 4; Host always closed.

Desktop “include current session runtime” is not CLI --live: the desktop only reads the active tab Host and never starts MCP.

Exit codes

Code	Meaning
0	No error-severity issues (warnings/info are allowed)
1	One or more error issues, or live MCP start failures
2	Bad flags / usage

Examples:

# Human-readable, current directory
reasonix doctor capabilities

# Fail CI only on hard errors
reasonix doctor capabilities --json
# shell: exit code 1 if summary.errors > 0

# Live probe with a longer timeout
reasonix doctor capabilities --live --timeout 15s --json 2>live-warn.txt

Existing reasonix doctor, doctor session, and doctor redact-sessions commands keep their own JSON schemas — capability fields are not mixed into those reports.

Desktop

Open Settings → Diagnostics:

Control	Behavior
Open page	Loads a static report for the active workspace root
Refresh	Re-runs collection with the current runtime toggle
Copy redacted JSON	Clipboard paste-safe report (paths already redacted)
Include current session runtime	Merge connected / failed / deferred / disabled from the active tab Host only
Open settings (on an issue)	Jumps to MCP / Skills / Plugins / Hooks when settings_tab is set

The page never auto-edits config, auto-trusts projects, auto-enables packages, or reconnects MCP. Opening Diagnostics does not rebuild the controller or snapshot the session.

JSON schema (version 1)

Top-level fields:

• schema_version (always 1)
• root (display path)
• live (bool)
• summary — error/warning/info counts and resource counts
• instructions, skills, commands, hooks, plugins, mcp
• issues[] — ordered list of findings

Issue shape:

{
  "severity": "error|warning|info",
  "code": "skill.shadowed",
  "subsystem": "skills",
  "name": "demo",
  "source": "<workspace>/.reasonix/skills/demo/SKILL.md",
  "message": "...",
  "remediation": "...",
  "settings_tab": "skills"
}

Stable codes include:

• 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

Array and issue order is deterministic for scripting and tests.

Severity

Severity	Meaning	CLI exit
error	Broken config or failed live start	1
warning	Actionable but non-fatal (e.g. untrusted project hooks)	0
info	Shadowing, disabled assets, runtime unavailable	0

Path and secret safety

Reports rewrite paths as:

• <workspace>/... under the diagnosis root
• ~/... under the user home
• <external>/basename for other absolute paths (no full external path)

They never intentionally emit usernames, full external paths, environment variable values, header values, tokens, or URL query strings. MCP entries list env/header keys only. Error text that may carry raw HTTP response bodies or MCP stderr passes through the product-wide secret redactor (Authorization schemes, Bearer/JWT/vendor tokens, KEY=value and JSON "key":"value" credential forms, Cookie/Set-Cookie values) and is truncated to 400 characters. Prefer copying report JSON into issues or chat over pasting raw config files.

What is not diagnosed here

Need	Use instead
Provider keys, proxy, sandbox OS support	reasonix doctor
Full session transcript for support	reasonix doctor session <id>
One plugin package only	reasonix plugin doctor <name>
Interactive MCP list in a chat session	/mcp

Cache impact

Adding the built-in reasonix-guide skill appends one stable index line to the system-prompt skills index after upgrade. The skill body is loaded only on invocation. Diagnostics itself is not part of the provider prompt.