跪拜 Guibai
← All articles
Frontend

DSH Plugin Development in Five Shapes: Runnable Code for Tools, Events, Config, and Services

By 再吃一根胡萝卜 ·
Read original on juejin.cn ↗ Google Translate ↗ Alt translation

The five plugin shapes give DSH developers a concrete start for extending the harness with model-callable tools, lifecycle-aware event handlers, user-configurable behavior, and cross-plugin services. The runnable code closes the gap between reading plugin API docs and having a working plugin, so the main remaining effort is deciding which shape fits the task.

Summary

DeepSeek Harness (DSH) plugin development is laid out in five concrete shapes, each with full TypeScript code that runs inside a `scratch-plugin` directory. All five share a common overlay-based launch: create `scratch-plugin/src/`, write a `cordis.yml` patch that points at the absolute path of the plugin file, and start with `pnpm dsh web --patch`. The minimal plugin only needs `name` and an `apply` that logs; the tool plugin uses `inject: ['tools']` and `defineTool` to let the model call a function; the event plugin shows `ctx.effect` for automatic cleanup of timers and other resources; the config plugin declares a `Config` type and Schema to let users override defaults; and the service plugin uses a class extending `Service` to expose a named instance that other plugins can inject.

The packaging section lists the required `package.json` fields: `main`, `type: module`, `files`, and `dsh.bundle.patch`, plus the need for a `cordis.patch.yml` in the plugin directory. A FAQ covers which example to run first, directory layout for local debugging versus distribution, how to combine tool and config examples, and when a class-based service plugin is necessary. The central warnings are the absolute path requirement in the overlay patch and the resource leak that occurs when event listeners skip `ctx.effect`.

Takeaways
— A minimal DSH plugin requires only a `name` export and an `apply` function that logs; this verifies the environment and load chain.
— Tool plugins register callable functions via `ctx.tools.register(defineTool({...}))` after declaring `inject: ['tools']`.
— Event listeners should be inside `ctx.effect`; returning a cleanup function from the effect stops timers when the plugin unloads, avoiding resource leaks.
— Config plugins export a `Config` interface and a Schema object; `apply` receives a config object as the second argument, with missing fields filled with defaults.
— Service plugins use `export default class ... extends Service` and register the service name via `super(ctx, 'metrics')`; other plugins consume it with `export const inject = ['metrics']`.
— All five examples run with the same three-step flow: create `scratch-plugin/src/`, write `cordis.yml` with the plugin file's absolute path, and start with `pnpm dsh web --patch`.
— Packaging a distributable plugin requires `package.json` fields `main`, `type: module`, `files`, and `dsh.bundle.patch`, plus a `cordis.patch.yml` in the project directory.
— The FAQ recommends running the minimal plugin first to verify the environment before trying the rest.
Conclusions

The framework's `ctx.effect` pattern mirrors React's useEffect cleanup, signaling a deliberate lifecycle model where plugins must explicitly relinquish resources.

The distinction between function-form and class-form plugins is a design choice that keeps simple plugins lightweight while reserving class semantics for when a plugin exposes a service instance to peers.

Requiring absolute paths in the overlay patch adds friction for multi-machine development; the article gives no workaround, so portability is a real limitation.

The packaging section stops at listing required fields and doesn't walk through the actual publish flow, leaving the distribution process to another guide or documentation.

Concepts & terms
Overlay patch (cordis.yml)
A configuration file that injects plugin entries into an existing DSH setup without modifying the core source; it points to plugin files by absolute path and is applied at startup with `--patch`.
ctx.effect
A lifecycle hook in Cordis that ties a resource's cleanup to plugin unload; the function passed to `ctx.effect` can return a cleanup callback, ensuring timers, listeners, and other resources are released.
defineTool
A helper from `@deepseek-ai/dsh-tools` that defines a model-callable function with name, description, parameters schema, output schema, and an async execute implementation.
Service
A Cordis class that other plugins can consume via dependency injection; a plugin extends `Service` and registers a service name, allowing `inject` to expose the instance.
From the discussion
Featured comments
组合搭配函数

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.

See top comments, translated →
Source: juejin.cn ↗ Google Translate ↗ Backup ↗