dsh-plugin-health
Compatibility matrix, official format-1 index builder, and Windows/WSL install doctor for
DeepSeek Harness (dsh) plugins.
Status: 0.1.6. Built against the official DSH 0.2.1-rc.2 compatibility rules and the
published @deepseek-ai/dsh-plugin-market-index validator.
Live official format-1 index: https://easonmws.github.io/dsh-plugin-health/index.json
(300 plugins, rebuilt nightly) · npm: npm install -g dsh-plugin-health ·
repo: https://github.com/EasonMWS/dsh-plugin-health
Upgrading to DSH 0.2.1? Run the check first.
In a scan of the top 120 ecosystem plugins, 3 would stop loading on 0.2.1-rc.2 because
they pin exact @deepseek-ai/* peer versions. Full report:
docs/upgrade-0.2.1.md.
dsh-plugin-health matrix --plugins plugins.txt --versions 0.2.0-rc.2,0.2.1-rc.2
Why
DSH ships no official plugin market index, publishes a prerelease roughly every two days with
breaking changes, and its plugin manager has no version picker or upgrade action. Today an author
can only check a plugin against the one DSH version installed on the machine, and Windows/WSL
install failures leave partial directories and stale locks behind.
This tool covers the three gaps that the existing doctor/market tools do not:
- Multi-host compatibility matrix — will a plugin load on
0.1.7-rc.2, 0.2.0-rc.2,
0.2.1-alpha.4, 0.2.1-rc.2, ...? Evaluated with the exact official semantics
(engines.dsh first, otherwise @deepseek-ai/dsh* peers, prereleases included,
workspace: ranges mapped to the host version).
- Official format-1 market index — turn a community catalog into a JSON index that the
built-in DSH Discover tab accepts, validated by the same parser the DSH Host uses.
- Windows/WSL install doctor — read-only by default; repairs quarantine, never delete, and
patch edits keep the user's comments.
Install
npm install -g dsh-plugin-health
# or run the checkout:
git clone https://github.com/EasonMWS/dsh-plugin-health.git && cd dsh-plugin-health && npm ci
node bin/dsh-plugin-health.js --help
Requires Node.js 20+.
Install inside DSH (bundle mode)
The package is also an installable DSH bundle. Installing it into a profile adds a read-only
plugin_health agent tool that reports missing third-party bundles, broken package directories,
cordis.patch.yml residue, proxy/registry configuration, profile drift, and installed plugins
incompatible with the running DSH version.
dsh plugin --profile web add dsh-plugin-health
The bundle declares engines.dsh, adds no UI, and changes nothing by itself.
1. Compatibility matrix
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 accepts a file (one spec per line, # comments allowed), a comma list, or repeated
flags. A spec is name, name@version, or a local plugin directory.--versions accepts exact SemVer versions or npm dist-tags of @deepseek-ai/dsh
(latest, next, alpha, ...).- Output:
matrix.json, matrix.md, and static SVG badges (badges/).
--fail-on any|none|<host> makes the command usable as a CI gate.
The evaluation mirrors packages/boot/app-boot/src/plugin-compatibility.ts:
| Manifest declares | Check |
|---|
engines.dsh | that range alone; peers are ignored |
no engines.dsh, has peers | every @deepseek-ai/dsh / @deepseek-ai/dsh-* peer range |
peer range workspace:^ / ~ / * | the running host version |
| prerelease host versions | participate in ranges (includePrerelease: true) |
Limitations: the matrix is static (manifests + official requirements). It does not yet boot
each host and mount the plugin; that runtime smoke test is on the roadmap. Git-only plugins can be
checked from a local clone with a directory spec.
Example run (2026-10-17, 7 plugins × 4 hosts)
dsh 0.1.7-rc.2: 6/7 compatible, 1 incompatible
dsh 0.2.0-rc.2: 5/7 compatible, 2 incompatible
dsh 0.2.1-alpha.4: 5/7 compatible, 2 incompatible
dsh 0.2.1-rc.2: 5/7 compatible, 2 incompatible
✗ dsh-win32@0.17.14: incompatible on all four (narrow @deepseek-ai/dsh-subprocess-local peers)
✗ dsh-find-plugin@0.4.0: incompatible from 0.2.0-rc.2 (@deepseek-ai/dsh-tools peer)
The first result reproduces the real failure tracked in dsh-win32 issue #89 (a peer upper bound
that is too narrow for later host lines) without installing anything.
GitHub Action: matrix on every pull request
The repository ships a reusable workflow. Add
examples/dsh-compat.yml to a plugin repository (as
.github/workflows/dsh-compat.yml) and every pull request gets a compatibility matrix comment plus
a job summary, with the matrix artifact uploaded:
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
2. Format-1 market index
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
The command writes site/index.json (format 1) plus site/build-report.md, then validates the
document with @deepseek-ai/dsh-plugin-market-index — the official reader used by the DSH Host.
Host the directory on any static origin (GitHub Pages is fine; no redirects) and paste the
index.json URL into Plugins → 自定义插件市场 → 发现 → 添加索引源.
Index facts:
- market title/description and every plugin title/description are localised (
en required, zh kept);
- categories come from the catalog, plus labels (
npm, compatible, incompatible,
unchecked, capability risk) and sort keys (downloads, stars, health score);
- the health score is deterministic: popularity (log downloads 55, log stars 25) ± compatibility
and capability-risk adjustments, 0–100;
- versions listed per plugin default to the dist-tag latest first, then the highest versions
(
--max-versions, default 3), with the npm publish timestamp and engines.dsh.
Current scope: npm-published catalog entries only (2,607 of 5,704 in the October 2026 snapshot).
GitHub/tarball-only entries are skipped and reported; git source support (commit-pinned) is on the
roadmap.
3. Windows/WSL doctor and repair
dsh-plugin-health doctor --home C:\Users\me\.dsh --profile desktop --runtime 0.2.1-rc.2
dsh-plugin-health repair --home C:\Users\me\.dsh --profile desktop --apply --yes
Checks: declared third-party bundles that are not installed (bundles shipped by the DSH
installation are treated as provided), unreadable/partial package directories, missing profile
dependencies, broken or empty cordis.patch.yml entries, .bak-* / .lock / .lock.takeover-*
residue, large plugin-manager logs, proxy configured without NODE_USE_ENV_PROXY=1, WSL and long
Windows paths, installed-plugin incompatibility against --runtime, and plugin-set drift between
profiles.
Repairs are opt-in (--apply), default to a dry run, and never delete:
- files/directories move to
<home>/.plugin-health/quarantine/<timestamp>/ (a repair-log.json
records every action);
cordis.patch.yml is edited textually (top-level - [] entries only) after a backup, so comments
and formatting survive.
Roadmap
- runtime smoke: install and mount the plugin in an isolated profile per host version;
- git/tarball catalog entries with commit-pinned sources;
- matrix over the whole catalog, published nightly next to the index;
- a DSH plugin panel that renders the matrix and doctor results in-app;
- a reusable GitHub Action and a public compatibility dashboard.
Development
npm ci
npm test
23 unit tests cover the official compatibility semantics, the format-1 builder (validated with the
official parser), and the doctor/repair flow on fixture homes. No network is needed for tests.
Disclaimer
DSH plugins run with the user's full permission. A health score, a compatibility label, or a
catalog listing is not a security review. Third-party indexes are unsigned; only add sources you
trust.
License
MIT
