DeepSeek Harness plugin development guide: forms, debug

This DeepSeek Harness (DSH) plugin development guide is about choosing a route: which of the three plugin forms to use, whether a capability belongs in tools, a service, or an event, and whether to debug with a --patch overlay or a profile install. Settle those three lines first and you will avoid rework when you start coding.

DSH plugin development: three lines to decide

A DSH plugin goes from idea to running by answering three questions in order. They map to three parts of the official docs (source):

1. Form — is this plugin a function that only registers capabilities, an object that also carries dependencies and config, or a class that provides a service to other plugins?
2. Capability placement — is the capability for the model (a tool), for other plugins (a service), or just a hook at some moment (an event)?
3. Debugging mode — use a --patch overlay while editing source, or package and install into a profile to verify?

The next three sections follow that order, and each gives decision criteria instead of an API dump.

Choosing a DeepSeek Harness plugin form: function, object, class

Function form covers the vast majority of plugins; class form is only for providing a service. The official wording is "Function form is sufficient in most cases," pointing to services as the reason to use class form (source).

Here is the minimal class form — the constructor performs synchronous initialization, and the service name (myService here) is what other plugins use in inject:

import { Service, type Context } from '@deepseek-ai/cordis'

export default class MyService extends Service {
  static inject = ['tools']

  constructor(ctx: Context) {
    super(ctx, 'myService')
    // Perform synchronous initialization in the constructor.
  }
}

Named exports and default exports must not be mixed: function form uses a named export, while object and class form use a default export. That is how the loader identifies the plugin form. See the development spec for the full checklist.

Where a DeepSeek Harness plugin capability belongs: tools, service, events

Placement follows the caller, not your preference. A DSH plugin capability has three kinds of consumer, matching three registration styles (source):

• Model calls it → register a tool with ctx.tools.register, after inject: ['tools'].
• Other plugins call it → register a service, using class form so consumers reach it through inject.
• Framework moment → register an event listener with ctx.on to hook plugin load and unload.

Events themselves have several trigger modes, and picking the wrong one means your logic never runs or runs out of order: emit broadcasts, bail short-circuits on the first result, serial runs in order, and waterfall is a pipeline that only continues if you call next(). Confirm the mode before writing a listener.

Declare the tool's parameters and output with defineTool so the model knows how to call it and the framework knows how to render the result:

import { defineTool } from '@deepseek-ai/dsh-tools'

export const inject = ['tools']

export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_cap',
    description: 'Execute my capability.',
    parameters: {
      input: { type: 'string', required: true },
    },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      return args.input.toUpperCase()
    },
  }))
}

When a DeepSeek Harness plugin provider must be replaceable: the three-role design

Split packages only when the capability must swap implementations without touching callers — never preemptively. The official design separates three roles and uses Bash execution as the example: dsh-shell (Service Definition) owns the contract, dsh-bash-local (Service Provider) implements local execution, and dsh-tool-bash (Consumer) exposes it as a model-callable tool (source).

The three dependency rules are the heart of it:

• The Service Provider depends on the Service Definition;
• the Consumer depends on the Service Definition;
• the Provider and Consumer do not depend on each other.

Swapping a provider is then a one-line change in cordis.yml, with the Definition and tool untouched:

# Local execution
- name: '@deepseek-ai/dsh-bash-local'
# Replace this row with another package that provides the same service.

The official design points are worth copying into a review checklist: do not split preemptively (a simple tool plugin does not); Request/Result types belong to the Service Definition; explicit over implicit — resolve defaults in an explicit resolve(request) step rather than hiding ?? default inside run().

Debugging a DSH plugin: --patch overlay versus install verification

Use a --patch overlay while editing source and a profile install to verify the artifact — they verify different things. The official tutorial mounts a local plugin into the Web UI with an overlay in three steps (source):

1. Get the absolute path — run pwd in the plugin repository root. Expect: the absolute repo root, which the name field below needs.
2. Write the overlay config — create a cordis.yml that inserts the local plugin into the config tree:

- insert:
    - id: hello
      name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'

3. Start with the patch — run the command below. Expect: the Web UI starts with the plugin mounted, and later source edits take effect on restart:

pnpm dsh web --patch ./scratch-plugin/cordis.yml

Two hard rules: the plugin path must be absolute, and a patch file contributes configuration but does not change the profile directory the loader resolves module paths from. So "it is in the patch but never loads" is usually a path-resolution problem, not a syntax problem.

To verify the packaged artifact, switch to a profile install: dsh plugin --profile <name> add <package>, then check the config layer with dsh --profile demo --dump-config before starting. For the trade-offs and more techniques, see local debugging.

From DSH plugin development guide to release

Once the guide settles the route, proceed through tutorial → spec → release. A suggested order:

1. Run the six steps of the development tutorial to get a first installable plugin;
2. run the development spec checklist over exports, dependencies, cleanup, and config;
3. package and distribute via packaging into a bundle and publishing to the plugin hub;
4. confirm the plugin shows up in the installed list of DSH Plugin Hub, with config rendering correctly.

If the plugin loads but behaves wrong (no effect, or a service registration error), start with plugin not activating and service already registered. Most cases come down to a wrong form or a missing inject.