ChatGPTClaudeGrok / X / CursorGemini

DSH plugin capability roles: three packages or one?

Plugin DevelopmentPublished 2026-11-05Author: DeepSeek Plugin Market
DSH plugincapability layeringService DefinitionProviderConsumer
One capability: one package or three? The Bash example shows how Definition, Provider, and Consumer relate, and when splitting is not worth its cost.

The tool works, but something feels off. The model calls run_command, and your machine executes it. The day you want container execution or a remote runner, does the tool code have to change too?

The answer decides whether you write one package or three.

What each DSH plugin capability role owns

A DSH plugin capability has three roles, each with a distinct output: definition, provider, and consumer. Before creating directories, align the roles. The official model splits a general capability into three, each with its own output:

RoleOutputExample
Service DefinitionThe service plus request/result typesdsh-shell
Service ProviderOne concrete implementationdsh-bash-local
ConsumerExposes the capability to models or usersdsh-tool-bash

A definition is an executable contract, not documentation. It exports an abstract class extending Service, registers the service name with super(ctx, 'shell'), and exports the request and result types. A provider subclasses it, a consumer injects shell and reads ctx.shell — which is why a tool plugin contains no command-string assembly. That belongs to the provider.

DSH plugin dependency direction: three edges, no fourth

What matters is not the number of packages but that dependencies only point one way. The rules fit in three lines:

  1. The provider depends on the definition;
  2. The consumer depends on the definition;
  3. The provider and consumer do not depend on each other.

Why forbid a fourth edge? If a consumer imports a provider's internals, swapping providers becomes editing the consumer. If a provider imports a consumer's tool definitions, the provider can no longer run without the model layer. Either one turns "replaceable" into a slogan. The definition should also expose explicit default handling such as resolve(request): Spec; hiding ?? default inside run() makes defaults invisible to callers.

When splitting a DSH plugin is justified

The threshold is whether a role must evolve independently, not whether the code is long. Ask three questions:

  1. Will a second implementation exist? If yes, definition and provider must separate;
  2. Will the provider evolve separately from the tool? If yes, separate them;
  3. Will another consumer use this capability? If yes, the definition needs its own package.

Three "no" answers mean do not split; one package may legitimately hold all three roles, and the official guidance discourages preventative splitting. The signals of over-splitting are concrete: each package is a few dozen lines, versions always ship together, one change touches three package.json files, or the dependency graph grows a cycle. That is splitting directories, not boundaries.

A minimal three-package DSH plugin walkthrough

A minimal DSH plugin splits into definition, provider, and consumer, composed in cordis.yml. Write them in role order, trimmed from the official example.

Definition first. It only registers the service name and declares the capability:

ts
export abstract class MyCapService extends Service {
  constructor(ctx: Context) { super(ctx, 'myCap') }
  abstract execute(request: MyCapRequest): Promise<MyCapResult>
}
export interface MyCapRequest { input: string }
export interface MyCapResult { output: string }

Provider next. It subclasses, implements, and mounts itself:

ts
class MyCapLocal extends MyCapService {
  async execute(request: MyCapRequest) {
    return { output: request.input.toUpperCase() }
  }
}
export const name = 'my-cap-local'
export function apply(ctx: Context) { ctx.plugin(MyCapLocal) }

Consumer last. It knows only the service name and wraps the capability as a tool:

ts
export const name = 'tool-my-cap'
export const inject = ['tools', 'myCap']
export function apply(ctx: Context) {
  ctx.tools.register(defineTool({
    name: 'my_cap',
    parameters: { input: { type: 'string', required: true } },
    output: {
      schema: { type: 'string' },
      render: (_args, value) => [{ type: 'text', text: value }],
    },
    async execute(args) {
      const result = await ctx.myCap.execute({ input: args.input })
      return result.output
    },
  }))
}

Composition happens in cordis.yml, provider first, consumer second:

yaml
- name: '@deepseek-ai/dsh-my-cap-local'
- name: '@deepseek-ai/dsh-tool-my-cap'

Verify the swap through configuration, not code: replace the first row with another package implementing the same MyCapService, restart, and confirm the tool still works with the consumer untouched.

Three ways to get a DSH plugin wrong

A definition with a default implementation. Someone adds a default execute so providers can skip it, and the default becomes the de facto standard, quietly killing replaceability. A consumer that constructs a provider. The tool imports MyCapLocal and instantiates it; configuration can no longer choose an implementation, and swapping the cordis.yml row does nothing.

Calling the tool the capability. Only dsh-tool-my-cap exists, with no definition and no provider. It works until the execution method changes, at which point the tool must be edited and the second person to need the capability copies the code.

A quick self-check: ask how many packages must change if the execution method changes. The answer should be zero — one configuration line only.

Splitting buys replaceability and independent evolution, and costs maintenance. Do that arithmetic before touching the directory layout. For runtime behavior of services and inject, read service isolation; for where a capability should attach, read which extension point.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Must a DSH plugin capability be split into Definition, Provider, and Consumer packages?

No, not always: split only when a DSH plugin role must evolve or be replaced independently. If the roles always change together, one package holding several roles is simpler, and the official guidance warns against preventative splitting.

Why should a DSH plugin Service Provider and Consumer never depend on each other?

Because a DSH plugin provider and consumer should know only the Service Definition. The provider depends on the definition to implement it, the consumer depends on it to call it, and swapping providers then requires no consumer change.

If I replace the Bash execution backend, does the tool plugin need changes?

No, not necessarily: swap the DSH plugin provider row in cordis.yml for another package implementing the same service, and the definition and consumer stay untouched. That config-level swap is the main payoff of the three-package shape.

What goes wrong if a DSH plugin has three packages for one implementation?

A DSH plugin split three ways for one implementation takes on two extra packages of versioning, release, and dependency maintenance for almost no benefit. Keep the interface, implementation, and tool in one package until a second implementation or independent evolution actually appears.

Related Terms

Service Definition
A Service Definition is the package that declares a capability: the Cordis service plus request and result types, shared by providers and consumers.— DeepSeek Harness docs
Service Provider
A Service Provider is a package that implements the capability by extending the definition's service and mounting itself with ctx.plugin.— DeepSeek Harness docs
Consumer
A Consumer is a package that uses the capability, usually exposing it as a model-callable tool, and depends only on the definition.— DeepSeek Harness docs
seam
A seam is the architectural joint of one complete capability, formed by its definition, provider, and consumer together; no single role is a seam.— DeepSeek Harness docs

Sources