white-sand-grand/dsh-plugin-doctor

Chinese version: README.md

dsh-plugin-doctor is a diagnostics and decision tool for the DSH plugin ecosystem. It searches community plugins, compares overlap, understands aggregate bundles, guards multi-plugin installs, audits real usage, renders a plugin landscape graph, and checks the local install against official releases. Inspired by Claude Code's /doctor command and repeated plugin conflicts and crashes caused by installing incompatible extensions.

Current version: 1.1.0. Requires Node.js >=22.19. The plugin is read-only by default: it does not start Web UI or mutate a profile on its own.

Install

Run this in the same environment that runs DSH:

dsh plugin --profile web add github:white-sand-grand/dsh-plugin-doctor

Start DSH Web yourself when needed:

dsh web

Open http://127.0.0.1:3080 and ask questions in natural language. The plugin does not start Web UI or change other profile plugins.

Update

Use this deterministic refresh sequence:

dsh plugin --profile web remove dsh-plugin-doctor
dsh plugin --profile web add github:white-sand-grand/dsh-plugin-doctor

Start Web yourself after updating if needed:

dsh web

Capabilities

Need	Behavior
Find a plugin	Searches GitHub dsh-plugin repositories and fallback sources; returns match, capabilities, stars, update time, and install reference
Check functional overlap	Compares description text, capability tags, and dependencies, then recommends dedupe or self-development
Ask how installs relate	Renders a similarity graph with Chinese function summaries and edge explanations
Check several repositories before installing	Inspects package names, tools, Cordis patch rows, and peer dependencies; conflicts or unknown metadata return INSTALL BLOCKED
Understand an aggregate bundle	Expands installed DSH-shaped dependencies; child plugins carry providedBy and are not recommended for independent removal
Audit actual usage	Scans finalized local session logs and attributes tool calls through dsh.tools
See the overall plugin landscape	Renders a Mermaid relation graph and core / active / idle / review tiers
Learn about known official issues before installing	Before search, recommendation, or supplied repository links lead to an install, asks whether to inspect open issues and shows relevant official links
Check how far behind the official release you are	Compares the local DSH version with the latest official release; when older, reports the release changes plus installed plugins that may be duplicated or conflicted

Tools

• plugin_community_search: community search and filters.
• plugin_similarity_analyze: similarity, redundancy groups, and irreplaceability.
• plugin_recommend: install, dedupe, or self-development decisions with aggregate-bundle awareness.
• plugin_install_guard: read-only preflight for multi-repository installs.
• plugin_usage_audit: local session usage audit.
• plugin_landscape: installed/community relation graph and usage tiers.
• plugin_official_sync: official release sync check; reports changes and duplicate/conflict findings when the local DSH is older.

The agent selects the appropriate tool automatically.

Official issue check before installation

When a user searches for an installable plugin, asks for a recommendation, or sends repository links to install, the plugin first asks whether to inspect open issues in the official repositories. It matches issue titles and bodies against the requested capability or symptom and shows official links, such as an unresolved report about recursive file watching causing Web UI stalls.

If the user explicitly chooses “do not check this session,” the prompt is suppressed for the rest of that session and returns in a new session. Dismissed prompts or unavailable interaction are reported as incomplete checks, never as proof that no known issue exists. An unavailable Issue API affects only the warning; it never bypasses the install guard's fail-closed behavior.

Examples

Ask about official issues before installing (real incident pattern)

I want to install a Web UI plugin. Check the official repository for unresolved issues first so we do not repeat history-load failures, unavailable model selection, or stuck file operations.

The plugin first asks whether to check official open issues. In the real incident pattern, an official repository contained an open issue closely matching “right-side file panel stalls and history loading fails”: the root cause was not the remote Web plugin, but a file-panel plugin whose recursive watcher consumed resources. The report uses a blurred plugin name such as @example-org/ui-panel-plugin and links to the official Issue #119 for verification. After an explicit refusal in the current session, later install requests do not repeat the prompt.

Search and check overlap

Find me a memory plugin and check whether it overlaps with plugins in my web profile.

The result lists candidates, match reasons, overlap scores against local plugins, and keep/remove commands. Spec generation and dedupe execution require confirmation.

Guard a multi-plugin install

I want to install these repositories together. Check for conflicts first:
github:owner/plugin-a
github:owner/plugin-b
github:owner/plugin-c

If GitHub returns 403/429, or repository metadata cannot be read, the result is INSTALL BLOCKED with token and rate-limit-reset guidance. Unknown metadata is never waved through.

View plugin relationships

How are the plugins I installed earlier related? Which ones are similar?

plugin_landscape returns a relation graph. Nodes include Chinese function summaries; edges explain whether similarity comes from descriptions, capabilities, or dependencies. With an intent, community candidates join as dashed nodes.

Understand an aggregate bundle

I need a task board. Does my installed UI bundle already provide one?

The recommendation path reads plugin-shaped dependencies of installed aggregate bundles. When a bundle already supplies the capability, the report shows its providedBy owner and avoids recommending an independent child removal or duplicate install.

Audit usage

List plugins in my web profile that declare tools but have never been used.

The result is based on local finalized session logs and never uploads their contents. An active or not-yet-flushed session may not be included and is called out.

Check official release sync

How far behind the official DSH am I? Will upgrading affect my installed plugins?

plugin_official_sync compares the local DSH version with the latest official release. Matching versions answer with a one-liner. When the local install is older, the report shows the release changes plus installed plugins that may be duplicated or conflicted: peer ranges excluding the new version, declared tool names appearing in the official notes, or capability keywords overlapping the changes. Findings are advisory only and never replace the install guard's verdict.

Direct DSH questions versus doctor

When you simply ask DSH to “find a plugin,” the model may offer a general suggestion from context, but it does not consistently search the community, read local package metadata, quantify overlap, or inspect Cordis registration conflicts. A multi-repository install can also proceed without a preflight.

With dsh-plugin-doctor, the same requests produce structured, reviewable evidence:

Direct DSH question	With dsh-plugin-doctor
Relies on model context or an ad-hoc search	Uses GitHub, cache, and registry fallbacks and identifies the source
Says plugins “look similar”	Returns text, capability, and dependency similarity plus redundancy groups
May miss children inside an aggregate bundle	Reads installed bundle dependencies and marks providedBy
Installs several repositories immediately	Checks package names, tools, patch rows, and peer dependencies first; unknown state fails closed
Gives no reliable usage history	Counts tool calls, sessions, and recency from local session logs
Describes relationships only in prose	Renders a Mermaid graph with pair-by-pair explanations

Safety and degradation

plugin_install_guard fails closed when repository metadata cannot be verified. GitHub 403 and 429 responses include token and rate-limit-reset guidance; unknown metadata is never treated as conflict-free.

Community search falls back in order: live GitHub, process cache, third-party registry pages, then a built-in snapshot. The response identifies the data source used.

The usage audit reads only session files already flushed to disk. An active or not-yet-flushed session may be absent and is called out in the report. Corrupt artifacts are skipped and counted; runtimes without zstd support skip compressed logs without preventing the other tools from loading.

The official release check reads the releases list with a process cache; when GitHub is unavailable it degrades to a stale cache or an explicit note. That degradation is advisory — it never affects plugin_install_guard's fail-closed verdict.

Optional configuration

Field	Default	Purpose
githubTokenEnv	DSH_PLUGIN_DOCTOR_GITHUB_TOKEN	Environment variable containing a GitHub token
githubToken	none	Literal token; prefer the environment variable
similarityThreshold	0.8	Similarity threshold for redundancy
cacheTtlMinutes	30	Community search cache lifetime
enableRegistryFallback	true	Enable registry and snapshot fallbacks
allowExecuteActions	false	Permit confirmed interactive add/remove actions; default is report-only

Prefer an environment variable and keep tokens out of repositories:

export DSH_PLUGIN_DOCTOR_GITHUB_TOKEN='your GitHub token'

Development

git clone https://github.com/white-sand-grand/dsh-plugin-doctor.git
cd dsh-plugin-doctor
pnpm install
pnpm test
pnpm run build
node verify-boot.mjs

Current verification baseline: 84 tests pass, TypeScript builds, and all seven tools register and pass the smoke invocation. See ARCHITECTURE.md for the algorithm and data flow, and CONTRIBUTING.md for contribution rules. Do not share one node_modules between Windows and WSL.

License

MIT.