Blog · Guide

What makes a good DeepSeek Harness plugin

August 17, 2026 · dshbase

We run dshbase, a community directory for DeepSeek Harness. To date we've installed and boot-tested 1,700+ plugins on dsh 0.1.0-rc.6, and marked roughly 1,400+ as verified. That means we've seen the same mistakes break plugins again and again — and the same habits make a plugin "just work." This is the checklist, for authors who want their plugin to be in the first group.

1. Ship a bundle manifest — or you never load

The single most common silent failure: a plugin installs fine but the agent never activates it. The cause is almost always a missing bundle manifest. A DSH plugin isn't just an npm package — it needs cordis.patch.yml (or cordis.yml) plus a dsh.bundle entry so the Cordis loader knows to mount it. Without it, dsh plugin add treats your plugin as a plain dependency and quietly ignores it.

Test it yourself: dsh plugin add <your-plugin>, then dsh --profile <name> --dump-config. If your plugin's entry doesn't appear in the tree, the manifest is wrong.

2. Ship ESM, not CommonJS

Core packages like @deepseek-ai/dsh-tools are ESM-only. A plugin compiled to CommonJS that imports them dies with ERR_REQUIRE_ESM. Set "type": "module" in your package.json and build to ESM. This is one of the most frequent hard failures we see in the directory.

3. Mind your version pins (the dist-tag trap)

Nearly every package under @deepseek-ai/* has a latest dist-tag pointing at a broken 0.0.1-rc.x, while the working 0.1.0-rc.6 lives on the next tag. If your plugin declares a release range like >=0.1.0, the prerelease 0.1.0-rc.6 does not satisfy it, and pnpm reports "No matching version found." Declare your peer deps against the actual published version, and test against 0.1.0-rc.6 explicitly.

4. Declare your Cordis contract

Cordis is strict about dependencies. Every service your plugin reads must be declared:

inject: [...] — reading a service without declaring it throws cannot get property "X" without inject.
using / inject the services you need — otherwise the loader leaves your entry waiting for service: X and it never starts.
Don't collide on loader entry IDs — code-runtime is owned by the bundles; registering it again causes a "duplicate loader entry id" error.

5. Be honest about your runtime surface

DSH has two sibling surfaces over the same base: headless (one-shot CLI, dsh --profile x "task") and web (a full GUI server with webServer, storage, workspace). If your plugin is a GUI plugin that needs those services, say so — a headless-only test will show it as waiting for service: webServer and a naive tester will call it broken. The same goes for plugins that need an external account (an xAI login, GitHub Packages auth, a paid API). State it in the README, up front.

6. Make install deterministic

Don't depend on workspace: references that only exist in your monorepo.
Don't ship a prepare build script that fails in a clean environment.
If you use native deps (node-pty, koffi, protobufjs), declare them so pnpm's allowBuilds can compile them.

7. The bar for "great" — not just "works"

Everything above gets you to "installs and activates." A great plugin goes further:

One clear job. A plugin that does one thing well beats a grab-bag of twenty half-finished tools.
A README with the exact install command and a sentence on what changes after install.
A demo. If it's a UI plugin, one screenshot is worth a thousand words — and it's also the fastest verification evidence.
A license and the dsh-plugin GitHub topic, so your plugin is discoverable.
A test story. How do you know it works? Write that down; it becomes our verification signal too.

How to earn the Verified badge

In the directory, we verify what we can: a fresh-profile install plus a boot test. But some plugins legitimately need a full web runtime, an external account, or a special build environment — those we mark Unverified rather than guess wrong.

If your plugin is one of those, you can close the gap yourself. On your plugin's page (or directly here), open an issue with the "Submit verification evidence" template, attach a screenshot or log of your plugin actually running in dsh, and we'll review and flip it to Verified. The badge is there for the taking — we just need something real to point to.

All articles →