Foreword

In the DSH plugin ecosystem, there are many community plugins. When using them in practice, common issues are not just “finding the right plugin,” but also: Is this plugin a duplicate of a locally installed one? Does the aggregated bundle already provide a specific sub-plugin? Will batch installing multiple repositories conflict? Are there un-closed issues in the official repository? Is the local DSH behind the official release?

Directly manually searching, installing, and uninstalling relies heavily on temporary judgment and can easily lead to duplicate installations, missed sub-plugins, or skipped pre-checks. dsh-plugin-doctor is the tool designed to handle these types of plugin diagnostics and decision-making issues.

Below is an introduction to what it is suitable for, how to install it, typical usage, and the boundaries to be aware of when using it.

What is it

dsh-plugin-doctor is a diagnostic and decision-making tool for the DSH plugin ecosystem, maintained by white-sand-grand, licensed under MIT.

It targets DSH plugin community use cases, providing community plugin search, duplicate function checking, plugin relationship graphs, pre-installation checks for batch installation, aggregated bundle sub-plugin identification, local usage auditing, and official version sync checking.

This plugin requires Node.js >=22.19. It is read-only by default and will not install, uninstall, or start the Web UI on its own.

Core Capabilities

Community Plugin Search and Duplicate Detection

It can search for community plugins and return match scores, functional tags, stars, update times, and installation references.

When determining if a plugin is a duplicate, it compares the plugin description text, functional tags, and dependencies to provide suggestions on whether to keep, remove, or develop the functionality in-house.

Community search degrades in the following order:

  1. Live GitHub
  2. In-process cache
  3. Third-party registry
  4. Built-in static snapshot

The results will be annotated with the data source.

Plugin Relationships and Panoramic View

It can generate similarity relationship graphs for plugins, explaining the similarity between two plugins and the overlap in sources.

It can also generate a Mermaid plugin relationship panoramic view, classified by the following hierarchy:

  • core
  • active
  • idle
  • review

Such graphs are suitable for viewing functional relationships between installed plugins rather than relying solely on text descriptions.

Pre-installation Checks for Batch Installation

Before batch installation, it checks:

  • Package name
  • Tool name
  • Cordis patch lines
  • peer dependencies

If a check cannot be completed, plugin_install_guard will fail-closed. It will not allow installation if repository metadata cannot be read, or if GitHub returns 403/429 or an unknown status.

Check for Un-closed Issues in the Official Repository

Before installation, it asks whether to check for un-closed issues in the official repository and displays relevant links and risks.

This is a reminder process. If the Issue API is unavailable, it will only affect the reminder information and will not bypass the plugin_install_guard fail-closed rule.

Aggregated Bundle Sub-plugin Identification

It can expand the shape dependencies of plugins in aggregated bundles and mark the providedBy sub-plugins.

When a certain function is already provided by an aggregated bundle, it will mark the corresponding sub-plugin as providedBy to avoid duplicate installation and will not suggest uninstalling that sub-plugin individually.

Local Usage Audit

It scans locally persisted session logs and counts them by dsh.tools:

  • Number of calls
  • Number of sessions
  • Last used time

This audit only reads locally persisted session logs and does not upload content. Sessions that have not yet ended or been flushed to disk may not be counted, and this will be explicitly indicated in the results.

Official Version Sync Check

It compares the local DSH version with the latest official release.

If the local version is behind, it will report new changes in the official release and list items that may be duplicates or conflicting with locally installed plugins.

Installation and Enablement

Execute the following in the same environment where DSH is running:

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

After installation, start DSH Web in your own way. dsh-plugin-doctor will not start the Web for you, nor will it change other plugins in existing profiles.

Typical Usage

Ask about Official Issues Before Installing

You can ask like this:

I want to install a Web UI plugin, please help me check if there are un-fixed issues in the official repository.

The plugin will first ask if you want to check for un-closed issues in the official repository, then perform the pre-installation checks, and display relevant links and risks.

Search and Check for Duplicates

You can ask like this:

Help me find a memory plugin and check if it duplicates with plugins already in the web profile.

The results will list candidate plugins, the reason for the match, overlap with locally installed plugins, and suggestions on whether to keep or remove them.

Pre-installation Checks for Conflicts in Batch Installation

You can ask like this:

I want to install the following repositories at the same time, please check if they will conflict:
github:owner/plugin-a
github:owner/plugin-b
github:owner/plugin-c

If GitHub returns 403/429, or if repository metadata cannot be read, the result will be INSTALL BLOCKED.

View Relationships Between Installed Plugins

You can ask like this:

What is the connection between the previously installed plugins? Which features are similar?

It will return similarity relationships and explain the overlap in sources.

Identify Functions Provided by Aggregated Bundles

You can ask like this:

I want to install a task board, do I need to install a task-board plugin separately?

If the relevant function is already provided by an installed aggregated bundle, it will show the providedBy source and will not recommend installing it separately or uninstalling the sub-plugin individually.

Audit Plugins That Declared Tools But Never Used Them

You can ask like this:

List plugins in the web profile that declared tools but never used them.

The results are based solely on locally persisted session logs and do not upload content. Sessions that have not yet ended or been flushed to disk may not be counted.

Check if Local DSH is Behind the Official Version

You can ask like this:

How far behind is my DSH from the official version? Will upgrading affect installed plugins?

It will compare the local DSH version with the latest official release, report new changes, and list potentially duplicate or conflicting installed plugins.

Applicable Scenarios and Notes

It is suitable for DSH agent developers when adding, replacing, or reviewing plugins, especially in the following scenarios:

  • Want to find a community plugin but unsure if a local plugin already covers it
  • Preparing to batch install multiple plugin repositories and need to check for conflicts first
  • Want to view functional overlaps between installed plugins
  • Want to confirm if a certain function is already provided by an aggregated bundle
  • Want to know if the local DSH is behind the official version
  • Want to audit if local plugins are actually being used

Please note the following points:

  1. The plugin runs with the permissions of the current dsh process; you should check the source code and license before installation.
  2. dsh-plugin-doctor is read-only by default and will not install, uninstall, or start the Web UI on its own.
  3. allowExecuteActions defaults to false, meaning it only outputs commands by default; execution of add/remove is only allowed after explicit interactive confirmation.
  4. plugin_install_guard fails-closed when repository metadata cannot be read, GitHub returns 403/429, or an unknown status occurs.
  5. The official Issue check is a reminder process and cannot replace the pre-installation guard.
  6. Usage auditing only reads locally persisted session logs and does not upload content.
  7. Community search relies on Live GitHub, in-process cache, third-party registry, and built-in static snapshots, and will annotate the source.

Links

GitHub:

https://github.com/white-sand-grand/dsh-plugin-doctor

Plugin clues also contain the directory page URL, but it was not found in the scraped materials and is provided for reference only:

https://www.skillhub.cn/plugins/white-sand-grand/dsh-plugin-doctor