dshp — DeepSeek Harness Plugin Toolkit
English | 中文
Scaffold, verify, and ship DeepSeek Harness plugins — without stepping on the platform's known landmines.
Writing a DSH plugin from scratch means learning the Cordis lifecycle, the bundle/profile manifest split, patch-layer composition, and — as we discovered while building this tool — several undocumented Windows and npm-tag traps. dshp encodes all of that into one command:
npm create dshp-cli@latest my-plugin # or: npx dshp-cli create my-plugin
cd my-plugin
npx dshp verify # ✓ boot-free, no API key neededWhy dshp?
| Pain (found the hard way) | What dshp does |
|---|---|
@deepseek-ai/dsh-tools latest tag is stale (0.0.1-rc.1 vs 0.1.0-rc.7); the two families' peers are mutually incompatible |
Pins the whole dependency family as one group (dsh-*, cordis, schemastery) per template; upgrade moves the group atomically |
Windows: a plain C:/... path in a patch file crashes the loader with ERR_UNSUPPORTED_ESM_URL_SCHEME |
Generates file:/// URLs (spaces auto-encoded) in every dev overlay |
Windows: dsh plugin add <path with spaces> breaks — the path gets split by the shell and pnpm tries to install "SOLO" |
Source-mode launcher spawns node directly (no shell), letting Node quote args; shell mode is refused loudly with a fix hint instead of failing silently |
pnpm ≥10 blocks esbuild install scripts → fresh pnpm install fails |
Templates ship a settings-only pnpm-workspace.yaml with the right allowlist |
| No way to check a plugin "would load" without booting the whole app (and an API key) | verify composes the real profile via dsh --dump-config and asserts your plugin's rows are in the tree — seconds, zero keys |
Commands
| Command | What it does |
|---|---|
dshp create <dir> |
Generates a plugin project: tool or service template, bundle manifest (dsh.bundle), cordis.patch.yml, dev overlay, tsconfig, pnpm settings, README |
dshp dev |
Boots dsh web with your dev overlay — TS source runs directly, edits hot-reload via HMR |
dshp verify |
Two layers: structural checks (L1) + real profile composition assertion via --dump-config (L2). --dev verifies the source-run overlay |
dshp upgrade |
Rewrites peer/dev deps to a newer family (reads live npm dist-tags). --check for CI |
dshp versions |
Shows built-in families vs. live npm dist-tags |
dshp create my-plugin --template tool --tag next
dshp create my-plugin --template service
dshp dev # http://127.0.0.1:3080 with your plugin live
dshp dev -- headless # no-UI run
dshp verify # after pnpm build (bundle form)
dshp verify --dev # source form, pre-build
dshp upgrade --check # CI: exit 1 when updates existFinding your dsh
dshp locates dsh automatically, in order:
DSHP_DSH_BIN— full custom command, e.g.node --import tsx/esm <repo>/apps/cli/src/bin.tsDSHP_DSH_ROOT— a deepseek-harness source checkout (run from source, no build needed)- A sibling
deepseek-harness/directory next todshp - A globally installed
dshon PATH
Publish your plugin
Templates default to the prebuilt npm route — users install compiled output and never touch build-script allowlists:
pnpm build && npm publishUsers then install into any profile:
dsh plugin --profile my add your-plugin
dsh --profile my --dump-config # see the layer landRequirements
- Node.js ≥ 20 (DSH itself wants ≥ 22.19)
- pnpm ≥ 10 (templates rely on its settings-file behavior)
- A
dsh— from source or npm
Roadmap
- [ ]
dshp test— harness-level test runner with mocked tool registry - [ ] Multi-file plugin templates (tool + UI card)
- [ ] Windows bug-fix PRs upstream to deepseek-harness (tracked in docs/windows-bugs.md)
License
MIT