dsh-plugin-template

English · 中文

A minimal, verified community starting point for DeepSeek Harness plugins. Fork it, rename it, and ship your own plugin with a CI that proves the plugin is actually callable — not just loadable.

Community template — not an official DeepSeek template, not a security audit, not a production-readiness certificate. Tested with: dsh 0.1.0-rc.6 · Node 24 · pnpm 11

What's inside

├── package.json              # dsh.bundle manifest + build scripts (prepare = git-install build)
├── cordis.patch.yml          # plugin row: id, package name, config
├── src/
│   ├── index.ts              # plugin entry: name / inject / Config / apply + one `hello` tool
│   └── version.ts            # dependency-free caret-range matcher used by the runtime guard
├── tests/
│   ├── index.spec.ts         # registration, behavior, cancellation (unit)
│   └── version.spec.ts       # prerelease range behavior matrix (unit)
├── scripts/
│   ├── integration-test.mjs  # installs the PACKED tarball, registers hello via apply(),
│   │                         # executes the real handler, asserts the result
│   └── dsh-smoke.sh          # fresh DSH profile install + config check + web boot (bounded retry)

└── README.md # bilingual


## Dependency strategy (read this)

- **Tested with**: `@deepseek-ai/dsh-tools` **0.1.0-rc.6** and `@deepseek-ai/cordis` **^4.0.1**.
- `peerDependencies` declares `"@deepseek-ai/dsh-tools": "^0.1.0-rc.6"`. This is a **caret range, not a pin**:
  - It currently matches `0.1.0-rc.6`, later RCs of `0.1.x` (`rc.7`, `rc.10`, ...), and `0.1.0` stable once published.
  - It does **not** match `0.1.0-rc.5`/older RCs, nor the `0.0.1-rc.*` train.
- `devDependencies` uses the same range; the committed `pnpm-lock.yaml` pins the exact tested version (`0.1.0-rc.6`) for development and CI.
- **Empirically verified with pnpm 11**: if the host already contains an older RC (e.g. `0.1.0-rc.3`), pnpm's default config links that older version into the plugin's peer slot with only a generic warning — **no error, no auto-upgrade**. npm fails loudly with `ERESOLVE` instead. Neither tool auto-upgrades the host.

Because silent linking is the dangerous case, the plugin itself **refuses to load** when the resolved `@deepseek-ai/dsh-tools` does not satisfy `^0.1.0-rc.6` (runtime guard in `apply()`, backed by `src/version.ts`). A silent mismatch becomes a clear, actionable error.

git clone https://github.com/zoahdev/dsh-plugin-template.git my-plugin
cd my-plugin
pnpm install
pnpm test
pnpm pack
dsh plugin --profile web add ./dsh-plugin-template-0.1.0.tgz
dsh web --port 4099

Then ask your agent: "Use the hello tool to greet Ada."

Rename checklist

package.json: name, description, keywords
cordis.patch.yml: plugin id and name
src/index.ts: export const name, tool name/description
README.md: title, links, author
Add the dsh-plugin topic to your GitHub repo

Check it with dsh-plugin-doctor

After renaming, run the community health checker locally (clone once, reuse everywhere):

git clone https://github.com/zoahdev/dsh-plugin-doctor.git
cd dsh-plugin-doctor && pnpm install && pnpm build
node lib/bin.js --full <your-plugin-directory>

It verifies the manifest, patch validity, entry points, build, pack, and a fresh-DSH-profile install — the same checks this template's CI runs. See zoahdev/dsh-plugin-doctor.

Or use the turnkey GitHub Action (no clone, no build):

- uses: zoahdev/dsh-plugin-doctor-action@v1
  with:
    path: .

Installation

README.md

dsh-plugin-template

What's inside

Rename checklist

Check it with dsh-plugin-doctor

Related tools