01Two concepts: bundle and profile

Packaging involves two concepts. Both are package.json files — they simply carry different manifests under the dsh key:

• BUNDLE: an npm package that ships a configuration layer. Its manifest declares dsh.bundle and answers “what does this package contribute?” — usually a patch file that inserts or overrides plugin rows;
• PROFILE: a directory under $DSH_HOME/profiles/ (named after the profile) describing one runnable composition. Its manifest declares dsh.profile and answers “which bundles compose this setup, and in what order?”.

Nothing is both: a package either contributes layers or composes them.

02Bundle layout and manifest

Using hello-plugin as the example, a bundle package looks like this:

hello-plugin/
├── package.json
├── cordis.patch.yml
└── index.js

Alongside the usual npm fields, package.json declares this as a bundle with dsh.bundle:

{
  "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" } }
}

Three things matter: files must include cordis.patch.yml, or the layer is missing after install; dsh.bundle.patch points at the layer file; main points at the plugin entry.

The plugin module itself is no different from a regular plugin — index.js exports name and apply:

export const name = 'hello'

export function apply(ctx) {
  console.log('[hello] loaded from dsh-hello-plugin')
}

03Writing cordis.patch.yml

cordis.patch.yml is the heart of a bundle: it declares which plugin rows the package inserts into (or overrides in) the configuration.

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

Note that name holds the package name dsh-hello-plugin, not a relative path. Once the bundle is installed into a profile, its files live inside the profile’s node_modules, and only the package name lets Node resolution find the installed code; a relative path would break after installation.

Conversely, a package lacking dsh.bundle still installs, but only as a plain dependency — dsh plugin warns and activates no layer. Libraries a plugin package imports follow this path: imported by plugins, but contributing no config themselves.

04Install into a profile and verify

Run this from the directory that contains hello-plugin:

dsh plugin --profile demo add ./hello-plugin

The first time you use the demo profile, three things happen: the profile is initialized with @deepseek-ai/dsh-base as its first bundle; pnpm links your local checkout; and dsh appends the bundle to the profile’s dsh.profile.bundles list. Afterwards, the profile’s package.json looks roughly like this:

{
  "dsh": {
    "profile": {
      "bundles": [
        "@deepseek-ai/dsh-base",
        "dsh-hello-plugin"
      ]
    }
  }
}

dsh --profile demo --dump-config

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

dsh --profile demo

dsh plugin --profile demo remove dsh-hello-plugin

05Layer composition and loading order

When a profile boots, configuration is layered in a fixed order, and later layers win per row:

1. each bundle patch in the dsh.profile.bundles list, in list order (@deepseek-ai/dsh-base first, then each installed bundle in add order);
2. the profile’s own cordis.patch.yml;
3. the machine-level $DSH_HOME/cordis.patch.yml, shared across profiles;
4. each --patch overlay passed on the command line, in argv order.

The key semantic: a patch replaces a row whole rather than deep-merging keys. Your patch can override an earlier row by id, but it must restate every key the row needs — omitted keys are not kept from the old value.

06Four install sources

dsh plugin add supports four sources — pick by distribution scenario:

dsh plugin --profile demo add ./hello-plugin

dsh plugin --profile demo add github:you/hello-plugin

dsh plugin add your-package

dsh plugin add ./hello-plugin-0.1.0.tgz

07Installing from GitHub and build permission

Git fetches sources, not built artifacts, so two conditions apply. First, the package needs a prepare script that builds from source. Second, the profile’s pnpm-workspace.yaml needs an allowBuilds entry — pnpm 10 and newer refuse to run a git dependency’s prepare script until allowed:

allowBuilds:
  dsh-hello-plugin: true

Pin a commit at the same time so you don’t fetch different code on every install:

dsh plugin --profile demo add github:you/hello-plugin#<sha>

08Running from a source checkout

If you run dsh from a source checkout instead of an installed dsh (the common case for contributors), keep the plugin at the repository root and prefix every command with pnpm:

# from the root of the deepseek-harness source repository
pnpm dsh plugin --profile dev add ./hello-plugin
pnpm dsh --profile dev --dump-config
pnpm dsh --profile dev

Everything else stays identical: the bundle layout, the patch format, and the layer composition rules do not change.