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 needed

Why 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 exist

Finding your dsh

dshp locates dsh automatically, in order:

1. DSHP_DSH_BIN — full custom command, e.g. node --import tsx/esm <repo>/apps/cli/src/bin.ts
2. DSHP_DSH_ROOT — a deepseek-harness source checkout (run from source, no build needed)
3. A sibling deepseek-harness/ directory next to dshp
4. A globally installed dsh on PATH

Publish your plugin

Templates default to the prebuilt npm route — users install compiled output and never touch build-script allowlists:

pnpm build && npm publish

Users then install into any profile:

dsh plugin --profile my add your-plugin
dsh --profile my --dump-config   # see the layer land

Requirements

• 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