DeepSeek Harness plugin: bundle, patch, and profile install

Packaging a DeepSeek Harness plugin means turning the plugin you wrote into an npm package that ships a configuration layer (a bundle): package.json points dsh.bundle.patch at a cordis.patch.yml whose rows reference the module by package name, and after a user runs dsh plugin --profile <name> add, that layer is appended to the profile's dsh.profile.bundles. Every DSH plugin bundle obeys the same set of constraints.

DSH plugin bundle and profile: two concepts, two manifests

Authors produce bundles, users boot profiles, and the two never merge. The official definitions are precise (source):

"Nothing is both." A bundle is what you author and distribute; a profile is what a user boots with dsh --profile <name>. Never hand-write a profile — dsh plugin creates and maintains it.

The three files of a minimal DSH plugin bundle

An installable bundle is only three files. The official layout:

hello-plugin/
├── package.json       # declares dsh.bundle
├── cordis.patch.yml   # the layer applied when a profile lists this bundle
└── index.js           # plugin modules the patch rows reference

{
  "name": "dsh-hello-plugin",
  "version": "0.1.0",
  "type": "module",
  "main": "index.js",
  "files": ["index.js", "cordis.patch.yml"],
  "dsh": { "bundle": { "patch": "./cordis.patch.yml" } }
}

export const name = 'hello-plugin'
export function apply() {
  console.log('[hello-plugin] plugin loaded!')
}

files must include cordis.patch.yml, or the installer never receives the config layer — the plugin installs but is never mounted, the most common packaging omission.

A package without dsh.bundle still installs, but only as a plain dependency and activates no layer, with dsh plugin printing a warning. That shape is for a library imported by plugin packages, not for a plugin users enable.

Writing a DSH plugin's cordis.patch.yml

A packaged patch references the module by package name, not by source path. The official minimal form:

- insert:
    - id: hello
      name: dsh-hello-plugin

The only difference from local debugging: an overlay writes an absolute path (because the loader resolves module paths from the profile directory), while a bundle writes a package name and lets Node module resolution find the installed code. See local debugging.

Installing a DSH plugin into a profile and verifying

dsh plugin --profile <name> <args...> forwards arguments to pnpm in the profile directory, so every pnpm verb works. From the directory containing hello-plugin (source):

1. Install into the profile: dsh plugin --profile demo add ./hello-plugin. The first use initializes the profile (with @deepseek-ai/dsh-base as its first bundle), links the checkout, and appends your package to dsh.profile.bundles.
2. Check the layer without booting: dsh --profile demo --dump-config, which you should expect to show a # == dsh-hello-plugin layer.
3. Then boot: dsh --profile demo, which you should expect to show the plugin's load log and working behavior.

Removing uses the same channel: dsh plugin --profile demo remove dsh-hello-plugin, which removes both the dependency and the layer. The full layer-precedence rules are in local debugging.

DSH plugin layer order and the whole-row replacement trap

Understanding two things prevents most "installed but not in effect" and "my config vanished after an override" cases.

1. Layer order: bundle patches (in dsh.profile.bundles order) → the profile's own cordis.patch.yml → the home-level $DSH_HOME/cordis.patch.yml → --patch overlays; later layers win.
2. Whole-row replacement, no deep merge: when a patch overrides a row's config, it must restate every key that row needs; writing only the changed key drops the rest.

Two packaging takeaways: ① your patch can override earlier rows by id (the official dsh-web-app bundle overrides dsh-base rows this way), but it must be complete; ② users can override your rows from their own profile without touching your package, so prefer defaults users are likely to keep and let the schema carry the rest.

Giving a DSH plugin bundle its own command line (advanced)

When you need custom startup flags, mount a provider plugin — the launcher needs no change. Have the plugin inject = ['cmdlineArgs'], parse its own commander program with parseCmdline from @deepseek-ai/dsh-cmdline, and provide its app-owned service from the action; rows that need those values inject that service and read them with !!js:

- id: my-app
  name: '@example/my-app'
  inject: [myAppStartup]
  config:
    port: !!js ctx.myAppStartup.port ?? 8080

On --help the provider publishes no service, so those rows never activate — which is exactly how help output avoids triggering business rows.

Once it installs locally, the next step is picking a distribution channel: publishing to npm is covered in publishing to npm, and submitting for directory listing in publishing to the plugin hub. After installing, check the installed list and config in DSH Plugin Hub. For the code-level hard checks, see the development spec.