By zoahdev · 2026-08-15 · All commands tested on Windows (Node 24, pnpm 11)
"The plugin loads" is not "the plugin works". Two real failure classes:
dsh.bundle, cordis.patch.yml, or prepare script explodes on someone else's machine;@deepseek-ai/dsh-tools RC into your plugin (verified: 0.1.0-rc.3 linked against ^0.1.0-rc.6 with only a generic warning).dsh-plugin-doctor turns both into "run it locally and know immediately".
git clone https://github.com/zoahdev/dsh-plugin-doctor.git
cd dsh-plugin-doctor
pnpm install
pnpm build
node lib/bin.js /path/to/my-plugin
Example output:
[PASS] manifest: my-plugin@1.0.0 bundle manifest ok
[PASS] patch: 1 plugin row(s): my-hello
[WARN] entry: entry lib/index.js not built yet (run pnpm install && pnpm run build)
[PASS] files: ships: lib, cordis.patch.yml
✅ ALL CHECKS PASSED
Exit code is 0 when everything passes, 1 otherwise.
| Check | Verifies | Default |
|---|---|---|
manifest |
package.json + dsh.bundle + dsh.bundle.patch + prepare + main |
✅ |
patch |
cordis.patch.yml parses and has an insert row with an id |
✅ |
entry |
the main target exists |
✅ |
files |
a files allowlist is declared |
✅ |
build |
pnpm run build actually runs |
--build |
pack+install |
pack → install into a fresh DSH profile → plugin id in --dump-config |
--full |
node lib/bin.js --full /path/to/my-plugin
This is the closest local simulation of "installed on someone else's machine":
[PASS] manifest: dsh-plugin-template@0.1.0 bundle manifest ok
[PASS] patch: 1 plugin row(s): template-hello
[PASS] entry: entry lib/index.js exists
[PASS] files: ships: lib, cordis.patch.yml, README.md, LICENSE
[PASS] pack: packed dsh-plugin-template-0.1.0.tgz
[PASS] install: plugin id(s) present in composed config: template-hello
✅ ALL CHECKS PASSED
Since v1.1.0, dsh-plugin-doctor also ships a plugin shell (dsh.bundle + cordis.patch.yml), so it can be installed straight into DSH:
dsh plugin --profile web add dsh-plugin-doctor
# or from a local tarball:
dsh plugin --profile web add ./dsh-plugin-doctor-1.1.0.tgz
Then tell the agent inside DSH:
Check whether this plugin is ready to publish — run the build first, then do a full verification.
The agent calls the plugin_check tool (dir plus optional build/full), returning PASS/WARN/FAIL per check and an overall ok — no need to leave DSH.
node lib/bin.js --json ./my-plugin
--json gives a machine-readable report plus the exit code, ready for GitHub Actions:
- run: node /path/to/dsh-plugin-doctor/lib/bin.js --build --json ./my-plugin
Q: entry warns? The plugin is not built yet: pnpm install && pnpm run build.
Q: manifest fails? Compare with the official publishing guide and add dsh.bundle + prepare.
Q: install fails? The plugin id is not in the composed config — check the id in cordis.patch.yml, or upgrade the host to 0.1.0-rc.6+ and retry.