DSH plugin capability roles: three packages or one?
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:
| Role | Output | Example |
|---|---|---|
| Service Definition | The service plus request/result types | dsh-shell |
| Service Provider | One concrete implementation | dsh-bash-local |
| Consumer | Exposes the capability to models or users | dsh-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:
- The provider depends on the definition;
- The consumer depends on the definition;
- 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:
- Will a second implementation exist? If yes, definition and provider must separate;
- Will the provider evolve separately from the tool? If yes, separate them;
- 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:
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:
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:
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:
- 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.
FAQ
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.
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.
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.
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
- DeepSeek Harness docs: three capability roles· deepseek-harness
- DeepSeek Harness docs: services and dependencies· deepseek-harness
- deepseek-harness repository· deepseek-ai