DSH Plugin Development in Five Shapes: Runnable Code for Tools, Events, Config, and Services
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.
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`.
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.
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.