DSH plugin manifest and dshTarget compatibility

DeepSeek Harness is in developer preview, which means the runtime changes and plugins have to say what they were built against. The community’s way of saying it is a compatibility declaration in the manifest, and getting it right is the difference between a plugin that installs everywhere and one that breaks silently.

What a manifest contains

A plugin manifest is the metadata that describes the package to the harness and to directories. In practice it lives in package.json plus a small harness-specific block. The fields that matter:

Anything a directory cannot read from these fields it will either infer badly or leave blank, which is why the manifest is worth treating as user-facing content rather than build metadata.

How the compatibility declaration works

The declaration names the harness releases your plugin was built and tested against, for example >=0.1.0-rc.6 <0.2.0 or 0.1.2-rc.1 || 0.1.5-alpha.1. It is a contract, not a guess. Users compare it against their installed harness before installing, and directories record it verbatim — on this site it is the dshTarget field shown on every plugin page.

Two honest facts about the mechanism, because authors deserve to know what they are writing into:

1. The harness does not enforce it. As of 0.1.5-rc.1 nothing in the runtime reads dsh.compatibility; a plugin with a mismatched declaration still installs and loads. The declaration is for people and directories, not for the loader — which makes accuracy more important, not less, because nothing will catch a wrong one for you.
2. Use real release tags. The published line is ordinary semver with preview tags: 0.1.0-rc.2 through 0.1.0-rc.8, 0.1.1-rc.*, 0.1.2-alpha.*, 0.1.2-rc.1, 0.1.3-alpha.*, 0.1.5-alpha.*, 0.1.5-rc.*, 0.1.6-alpha.1, with 0.1.5-rc.1 the current latest. A directory cannot map shorthand it has never seen onto that list — declare tags from it, not abbreviations.

Three rules keep the declaration useful:

1. Declare the versions you actually tested. A plugin tested on 0.1.2-rc.1 and never run on the 0.1.5 line should say so, even though the older tag looks worse in a listing.
2. Update it in the same commit that adopts a new runtime capability, not in a separate release people forget.
3. Never declare a wider range than you verified. Plugins that claim a hypothetical future version keep working users away for no benefit, and the claim survives no scrutiny.

Declaring it

The shape the ecosystem has settled on is a compatibility object inside the dsh block:

{
  "name": "dsh-my-plugin",
  "version": "0.3.0",
  "type": "module",
  "keywords": ["dsh-plugin", "deepseek-harness", "web-search"],
  "license": "MIT",
  "repository": "https://github.com/you/dsh-my-plugin",
  "dsh": {
    "bundle": { "patch": "./cordis.patch.yml" },
    "compatibility": {
      "dsh": ">=0.1.0-rc.6 <0.2.0",
      "profiles": ["web"],
      "dshReleases": {
        "0.1.5-alpha.1": "compatible",
        "0.1.5-rc.1": "compatible"
      }
    }
  }
}

dsh is the range; dshReleases lets you mark individual releases compatible or unknown when a blanket range would overclaim; profiles says which harness surfaces you support.

In the README, state it in plain language as well, because humans read the README first:

Tested against DSH 0.1.5-rc.1. On the 0.1.2 line the tool registers but the
streaming status field is unavailable.

Describing the failure mode, not just the version, is what turns a compatibility note into something a user can act on.

What happens when a plugin is incompatible

The failure is usually legible: the runtime reports a load error for the plugin while the rest of the session continues. What you want to avoid is a plugin that loads and then misbehaves, because that looks like a harness bug to the user and produces confusing reports.

If your plugin touches a surface you know changes often, such as interface rendering or an event payload shape, add a runtime check at load time and refuse to activate with a clear message. Declining to load is a better user experience than loading badly — and the declaration cannot do this for you, because nothing enforces it.

Compatibility as a listing signal

Directories display compatibility because it answers the question users ask before installing: will this work on my harness. On this site the declaration appears verbatim on every plugin page alongside the verification level and the last update date, so you can judge both whether it runs and whether anyone is still maintaining it. The verification level L3 requires exactly this: a resolvable install command and a declared target. A plugin with a resolvable install but no declaration sits at L2 and appears in no group on the compatibility matrix — which is the honest reflection of what its author committed to.

FAQ

Does the compatibility declaration replace peer dependency declarations?

No. It communicates harness compatibility to users and directories. Peer dependency ranges still govern which @deepseek-ai/* packages the install actually resolves, and the two serve different purposes: a peer range is an install requirement, a compatibility declaration is a support statement.

How often should I bump it?

Whenever you adopt a new runtime capability or complete a compatibility pass. Not on every release.

Can one plugin support two harness versions?

Yes — that is what a range or an explicit dshReleases map is for. Declare 0.1.2-rc.1 || 0.1.5-alpha.1 and mark the releases in between unknown if you have not tested them, rather than claiming a blanket range.

What if I do not declare it at all?

The plugin still installs and loads — the harness does not check. Directories will record compatibility as undeclared: on this site the listing shows no target, sits at verification L2, and appears in no group on the compatibility matrix. Users cannot tell whether it fits, which measurably reduces installs.

Next steps

Read the Cordis lifecycle guide for the runtime behaviour behind these fields, then publish your plugin.