DSH Plugin Development in Five Shapes: Runnable Code for Tools, Events, Config, and Services
DSH plugin development examples: complete code compilation for five plugin forms
Author: 再吃一根胡萝卜 Tags: 前端
This article is compiled from the Alibaba Cloud Developer Community article "DSH plugin development examples: complete code examples of minimal plugin, tool plugin, event plugin, configured plugin and service plugin" (2026-09-27), the original content is reposted from the DSH Plugin Hub plugin market. Suitable for direct backup to a personal blog.
1. Overview
DeepSeek Harness (DSH) plugin development examples are easier to get started with than the specification. The five examples cover the common forms of plugin development, each of which can be directly copied into scratch-plugin/src/ and run with a --patch overlay. Whether you call it a DSH plugin or a DeepSeek plugin, the running steps are exactly the same.
| Example | Purpose | Key API |
|---|---|---|
| Example 1: Minimal plugin | Verify the environment and loading chain | apply + name |
| Example 2: Model tool | Let the model call your capability | inject: ['tools'] + defineTool |
| Example 3: Event listener | Insert logic at framework timing and auto-clean up | ctx.effect |
| Example 4: With configuration | Let users change plugin behavior | Config type + Schema |
| Example 5: Provide service | Let other plugins call you | Service class form + inject |
2. Common skeleton (run in three steps)
The five examples share the same directory and running method; the difference is only in what is registered in the source code.
Step 1: Create the directory
Create scratch-plugin/src/ at the checkout root:
deepseek-harness/ # Checkout root (already run-from-source)
└── scratch-plugin/
├── src/my-plugin.ts # All five examples are written here
└── cordis.yml # Overlay configuration
Step 2: Write the overlay configuration
Create scratch-plugin/cordis.yml, and fill name with the absolute path of the plugin source:
# scratch-plugin/cordis.yml
- insert:
- id: demo
name: '/absolute/path/to/deepseek-harness/scratch-plugin/src/my-plugin.ts'
Step 3: Start
pnpm dsh web --patch ./scratch-plugin/cordis.yml
Expected: The Web UI starts and mounts my-plugin.ts into the plugin tree.
⚠️ Note: The path must be an absolute path. The patch only contributes configuration and does not change the loader's profile directory for resolving module paths. If the environment is not set up, check "Development Environment Setup" first.
3. Example 1: Minimal plugin
Purpose: Verify the environment and loading chain. Only an apply that logs is needed.
import type { Context } from '@deepseek-ai/cordis'
export const name = 'hello-plugin'
export function apply(ctx: Context) {
console.log('[hello-plugin] plugin loaded!')
}
Expected result: On startup, the terminal prints [hello-plugin] plugin loaded!. If you don't see this line, don't go further; first troubleshoot the path and build.
4. Example 2: Model tool
Purpose: Let the model call your capability. Note the inject and defineTool trio.
import type { Context } from '@deepseek-ai/cordis'
import { defineTool } from '@deepseek-ai/dsh-tools'
export const name = 'greet-tool'
export const inject = ['tools']
export function apply(ctx: Context) {
ctx.tools.register(defineTool({
name: 'greet',
description: 'Greet someone by name.',
parameters: {
name: { type: 'string', required: true, description: 'The name to greet' },
},
output: {
schema: { type: 'string' },
render: (_args, value) => [{ type: 'text', text: value }],
},
async execute(args) {
return `Hello, ${args.name}!`
},
}))
}
Expected result: Input "Use the greet tool to greet Ada." to the model; the model calls greet and gets Hello, Ada!. The complete rules for the execute contract and card rendering are found in "How to Write a Tool Plugin".
5. Example 3: Event listener and automatic cleanup
Purpose: Insert logic at framework timing and correctly release manual resources. Register listeners via ctx.on and hand over disposal via ctx.effect.
import type { Context } from '@deepseek-ai/cordis'
export const name = 'heartbeat-plugin'
export function apply(ctx: Context) {
ctx.effect(() => {
const timer = setInterval(() => console.log('heartbeat'), 5000)
// The returned function is executed when the plugin is unloaded.
return () => clearInterval(timer)
})
}
Expected result: After the plugin runs, it prints heartbeat every 5 seconds; after unloading the plugin, the timer stops.
⚠️ Common pitfall: If you write the timer directly in
applywithout wrapping it inctx.effect, it will still run after the plugin is unloaded, which is the most common source of resource leaks.
6. Example 4: Plugin with configuration
Purpose: Let users change your behavior. Declare a Config type and a Schema with the same name; apply receives a second argument.
import type { Context } from '@deepseek-ai/cordis'
import Schema from '@deepseek-ai/schemastery'
export interface Config {
greeting: string
maxRetries: number
}
export const Config: Schema<Config> = Schema.object({
greeting: Schema.string().default('Hello'),
maxRetries: Schema.number().default(3),
})
export const name = 'configured-plugin'
export function apply(ctx: Context, config: Config) {
console.log(`${config.greeting} (retries: ${config.maxRetries})`)
}
Expected result: Without configuration, it prints the default values Hello (retries: 3); with partial configuration, missing fields are filled with defaults. The display of configuration in the interface is covered in "How to Use Plugin Configuration".
7. Example 5: Provide a service
Purpose: Let other plugins call you. This is when the class form is needed: register the service name in the constructor, and consumers declare it via inject.
import { Service, type Context } from '@deepseek-ai/cordis'
export default class MetricsService extends Service {
static inject = ['tools']
constructor(ctx: Context) {
super(ctx, 'metrics')
// Do synchronous initialization here.
}
count(name: string) {
console.log(`[metrics] ${name}`)
}
}
Expected result: After the plugin loads, other plugins can get ctx.metrics in apply using export const inject = ['metrics'].
💡 Only use the class form when providing services externally; for ordinary plugins, the function form is simpler.
8. From example to installable package
Examples only run in the checkout; they are not yet distributable. To become an installable package, three things need to be added:
- Declare in package.json:
main(pointing to the entry)type: modulefiles(including the entry andcordis.patch.yml)dsh.bundle.patch(pointing to that patch file)
- Put it into a project directory with a
cordis.patch.yml.
Publishing path: First follow "Packaging as a bundle" to generate an installable artifact, then use "Publish to Plugin Hub" to submit for inclusion; after installation, you can verify the plugin and its configuration items in the installed list of DSH Plugin Hub. The hard self-check items when writing code are in "Development Standards".
9. FAQ
Q1: Which example is best to run first?
Run the minimal plugin first: it only has name and an apply that logs. Mount it to the Web UI with the --patch overlay. Seeing the log means the environment and loading chain are working. The official tutorial also places the minimal plugin first because all subsequent examples merely add registration code to this skeleton.
Q2: How should the directory structure be arranged?
In two phases: for local debugging, the official approach creates scratch-plugin/src/ from the repository root and mounts it with an absolute path; when preparing for distribution, separate the project and include package.json (main, type: module, files, dsh.bundle.patch) and cordis.patch.yml. These are not mutually exclusive: first debug in the checkout, then extract it into an installable package.
Q3: Is there an example that shows both tools and configuration?
Stack the tool example and the configuration example: first declare inject = ['tools'] and the Config schema, then in apply(ctx, config) use values from config to construct the description or behavior of defineTool. Note that the second argument of apply comes from the framework's config object completed according to the schema and can be used directly.
Q4: What is the difference between the class form in the service example and an ordinary plugin?
The service example uses the class form: export default class ... extends Service, registering the service name into the context via super(ctx, 'myService') in the constructor; other plugins consume it via inject: ['myService']. An ordinary plugin ends after registering capabilities, while a service plugin also exposes an instance externally. So only use the class form when "another plugin needs to call you".
Copyright notice: This article is reposted from the DSH Plugin Hub plugin market, and the copyright belongs to the DSH Plugin Hub plugin market. The original was published on the Alibaba Cloud Developer Community.
Top 1 from juejin.cn, machine-translated. The original thread is authoritative.
That pitfall in example three deserves to be called out on its own: the timer written directly in apply without wrapping ctx.effect keeps running after unload — in both plugins and browser extensions this is the most common source of leaks, and not using the cleanup hooks the framework gives you is treating unload as a decoration. I also agree with the line "only use the class form when providing external services" — the function form is enough for an ordinary plugin, no need to wrap everything in a Service from the start. One more question, though: if an error is thrown inside defineTool's execute, does the model side receive the original error text or is it wrapped by the framework? That directly decides whether, when the tool fails, the model will retry on its own or just give up.