Preface

DeepSeek Harness (DSH) adopts an “everything is a plugin” architecture. Since the host version iterates rapidly, plugin authors often have to verify whether engines.dsh or @deepseek-ai/dsh* peers match on only one specific locally installed DSH version. If systematic comparison is not performed before upgrading, plugins may fail to load directly on the new host; installation failures on Windows/WSL may also leave behind half-finished directories and lock files. The community plugin directory is scattered across independent sites with no official affiliation to DeepSeek / High-Flyer. The host’s built-in Discover requires an official standard-compliant format-1 index JSON, rather than arbitrary web links.

Below is an introduction to dsh-plugin-health (GitHub: EasonMWS/dsh-plugin-health, Category: Workflow) released by maintainer EasonMWS. Aimed at plugin authors and developers using DSH daily, it supplements three capabilities: a static compatibility matrix for multiple host versions, construction of format-1 market indexes verified by official validators, and Windows/WSL installation diagnostics (read-only by default). When installed as a DSH bundle, it also provides a “Plugin Health” interface in the web configuration, turning discovery items into executable next steps.

What is this

dsh-plugin-health is a toolkit that provides a CLI, a reusable GitHub Action, and a DSH bundle simultaneously. The README states that it is built according to the official DSH 0.2.1-rc.2 compatibility rules and the published @deepseek-ai/dsh-plugin-market-index validator; the current version of the npm package is 0.3.2 (see the repository’s package.json), requiring Node.js 20+, with engines.dsh set to >=0.1.0-rc.6 <0.3.0-0.

It does not replace DSH’s built-in plugin manager, nor does it provide an official app store; instead, it helps you perform checks and produce artifacts using host-consistent semantics when upgrading the host, maintaining plugin repositories, or building your own “Discover” index source.

Core Features

Multi-host Compatibility Matrix

The matrix subcommand determines whether a plugin should load on multiple @deepseek-ai/dsh versions or dist-tags (latest, next, alpha, etc.) based on the plugin manifest (prioritizing engines.dsh, otherwise checking @deepseek-ai/dsh / @deepseek-ai/dsh-* peers, including prerelease and workspace: mappings). The README explicitly states: the matrix is a static evaluation and has not yet performed real startup mounting for each host; Git source plugins can use local directory paths as specs for checking.

Output includes matrix.json, matrix.md, and SVGs under badges/; --fail-on any|none|<host> can be used for CI gating.

Official Format-1 Market Index

The index subcommand converts the community catalog (currently primarily focusing on published npm entries) into an index.json (format 1) acceptable by DSH Plugins → Custom Plugin Market → Discover → Add Index Source, and validates it using @deepseek-ai/dsh-plugin-market-index. An example hosted by the maintainer on GitHub Pages is index.json (the README notes approximately 300 plugins, rebuilt daily). The index can include fields such as compatibility matrix-based health scores, categories, and multilingual title/description (see README for details).

Windows/WSL Installation Diagnostics

The tool provides a read-only default with an optional repair path: handling isolation, residual cordis.patch.yml, proxies/registries, profile drift, and installed plugins mismatched with the current running host version (presented via the plugin_health agent tool and settings UI in bundle mode).

“Plugin Health” Settings UI within DSH

After installing as a bundle into a profile, Settings → Plugin Health appears in the DSH web interface: no badge or sidebar entry is added if there are no issues; if issues exist, “Plugins have N issues” is displayed above the account menu with a jump link. The host side only provides a loopback read-only snapshot; the plugin does not modify your profile. Discovery items display a dry-run plan before providing one-click repair.

Reusable GitHub Action

The repository provides matrix-review.yml. After adding the workflow to a plugin repository, it can comment compatibility matrices on each Pull Request, generate job summaries, and upload artifacts (see examples/dsh-compat.yml in the README for an example).

Installation and Enablement

Global CLI (choose one):

npm install -g dsh-plugin-health

Install the bundle in a DSH web profile (enabling both the settings UI and diagnostic capabilities):

dsh plugin --profile web add dsh-plugin-health

The README also provides a method to run node bin/dsh-plugin-health.js --help after npm ci from a repository checkout; Node.js 20+ is required.

Typical Usage

Batch checking multiple host versions before upgrading

The README suggests running the matrix before upgrading to DSH 0.2.1; its scan example of the top 120 plugins in the ecosystem shows that 3 would fail to load on 0.2.1-rc.2 due to exact pinning of @deepseek-ai/* peers (see docs/upgrade-0.2.1.md in the repository for full details).

dsh-plugin-health matrix \
  --plugins examples/plugins.txt \
  --versions latest,next,alpha,0.1.7-rc.2 \
  --out dsh-health-out/matrix \
  --fail-on any

--plugins can be a file with one spec per line (supports # comments), a comma-separated list, or repeated flags; specs are name, name@version, or local plugin directories.

Automatically posting compatibility matrices on plugin PRs

Copy the example from the README as .github/workflows/dsh-compat.yml, and adjust plugins and versions as needed:

name: dsh plugin compatibility
on: pull_request
permissions:
  contents: read
  pull-requests: write
jobs:
  matrix:
    uses: EasonMWS/dsh-plugin-health/.github/workflows/matrix-review.yml@v0.1.5
    with:
      plugins: '.'
      versions: 'latest,next,alpha'
      comment: true

Generating an index importable into DSH from a catalog

dsh-plugin-health index \
  --catalog https://awesome-dsh-plugin.com/plugins.json \
  --host 0.2.1-rc.2 \
  --index-url https://easonmws.github.io/dsh-plugin-health/index.json \
  --matrix dsh-health-out/matrix/matrix.json \
  --limit 300 --out site

Host the site directory on a static site (no redirects), and fill the URL of index.json into the index source on the DSH Discover page.

Use Cases and Notes

Suitable for: teams maintaining DSH plugins in npm or local directories that need pre-release checks on multiple host versions or dist-tags; community maintainers wishing to build their own format-1 index for Discover; users troubleshooting installation residue on Windows/WSL; repositories wanting to fix compatibility matrix gating in the PR workflow.

Please note:

  1. The compatibility matrix is based on manifests and official rules and cannot replace real startup smoke tests (the README lists this as a roadmap item).
  2. index currently mainly processes npm entries in the catalog; GitHub/tarball-only entries will be skipped and noted in the report.
  3. DSH plugins run with the current dsh process permissions. Before installing any third-party bundle, you should review the source code, license (this repository is MIT), and maintainer information yourself to ensure compliance with your security and compliance requirements.

Conclusion

dsh-plugin-health converges three things—“can it load on this DSH version,” “can it generate a discovery index recognized by the host,” and “is the local installation clean”—into a single CLI, bundle UI, and GitHub Action, reducing the cost of trial and error relying solely on a single local version.