dsh-plugin-engineering

---
name: dsh-plugin-engineering
description: Build, modify, debug and ship DeepSeek Harness (DSH) plugins: Cordis plugins, tools, services, events, config, LLM adapters, client UI and skins. Use for any task mentioning DSH, DeepSeek Harness, Cordis, cordis.yml, `dsh plugin add`, `ctx.tools`, `defineTool` or a new model provider; and when the user says "add a tool to my agent", "write a plugin for this harness" or "my plugin won't load". Read before answering DSH plugin API questions: the surface is versioned and npm `latest` is stale.
license: MIT
compatibility: Any agent with shell access and a local DSH installation. Targets third-party plugins installed into a DSH profile; DSH monorepo internals are out of scope.
---

# DSH Plugin Engineering

A DSH plugin is a Cordis plugin plus a manifest. Everything the harness does — the tool registry, the model adapters, even the agent loop — is a plugin, so extending DSH means registering through `ctx` and letting the framework own lifecycle.

The hard part is not writing `apply()`. It is that **the API surface moves fast, moves under names you already learned, and npm will hand you a version from months ago without complaining.** This skill exists to make you verify before you write.

## Scope

**In scope:** a plugin you author, publish, and install into a DSH profile — tool plugins, services, event listeners, config schemas, LLM adapters, client-side UI and settings panels, and the bundle/profile layer that delivers them.

**Out of scope, say so instead of improvising:** in-session dynamic plugins (`cordis_define` / `cordis_run` streams), agent-preset composition editing, and patches to a monorepo checkout of DSH itself (that has its own `packages/<group>/<pkg>` conventions, build gates and test tiers that do not apply to your project).

## Non-negotiables

These are the rules you cannot derive by reading example code. Everything else lives in the references.

1. **Anchor the version before the first line of code.** Read the installed version, then resolve the matching package version from npm dist-tags. `npm install @deepseek-ai/dsh-base` resolves the `latest` tag, which today points at a months-old preview build, not the version the user runs. Writing code against those types produces a plugin that silently fails to load. See `references/api-verification.md`.

2. **No invented API.** Every service key, method, event name and config field you use must trace to a `.d.ts` in the resolved package or to a grep hit in its compiled output. Service keys do get renamed between releases — `bash`→`shell` and `tasks`→`jobs` both happened — so a name from a blog post, an older skill, or your own memory is not evidence. When you cannot verify something, say which part is unverified rather than filling the gap.

3. **Every registration is an effect.** `ctx.tools.register`, `ctx.on`, `ctx.connection.rpc.handle`, `ctx.effect` all return disposers owned by the plugin's fiber and run on unload. Do not create module-scope timers, listeners or connections that outlive the plugin. When teardown order matters, put the related cleanup in one `ctx.effect()` — disposers across separate effects may not run in the order you assumed.

4. **Tools return a canonical JSON value; `render()` makes it readable.** `output.schema` is mandatory and is enforced against the returned value. Never return prose the caller then has to parse for ids, counts or paths.

5. **A waterfall listener must call `next()`.** Omitting it is a deliberate veto of everything downstream, including built-in behaviour. That is correct for a gate and a bug everywhere else.

6. **Config is a standard schema, and it fails loud.** Export `Config` as a Schemastery schema (it satisfies `StandardSchemaV1`, which is what the loader validates). Put defaults in the schema. Anything a deployment might change belongs there, not in a constant.

7. **A patch row replaces the whole `config` value; it is not a deep merge.** When overriding a row you did not write, restate every key you still want. See `references/config-and-packaging.md`.

8. **Verify the world, not your own report.** Do not assert that a tool worked because `execute` returned. Re-read the file, re-run the command, boot the profile and look at the log. This applies to your verification of the plugin and to the tests you write.

## Workflow

Run the stages in order. Each has a completion gate — do not report progress past a gate you have not actually cleared.

**1 · Anchor.** Detect the running DSH version and resolve the type source at that exact version. Record it, e.g. `DSH 0.2.1-rc.5 → @deepseek-ai/dsh-tools@0.2.1-rc.5`. → `references/api-verification.md`

**2 · Choose the mechanism.** Decide what the plugin contributes before deciding how to write it; a request that maps to no extension point needs a different conversation, not a cleverer plugin. → `references/plugin-anatomy.md` for the decision table.

**3 · Verify the surface you will touch.** Read the relevant `.d.ts` for the handful of APIs this plugin uses. Not the whole package — the members you call and the events you subscribe to.

**4 · Build.** One file or a small package: `export const name`, `export const inject` (only the services you actually read), `export function apply(ctx, config)`. Add `Config` when anything is configurable. Register optimistically and let `inject` gate loading.

**5 · Self-check against the non-negotiables.** Read your own diff looking for the eight failure modes above — invented keys, module-scope state, missing `next()`, missing disposers. This catches more real defects than any test.

**6 · Prove it loads and works.** Boot a throwaway profile with the plugin mounted and read the startup log before claiming success. Then pick test tiers from the change surface. → `references/testing-and-debugging.md`

**7 · Ship.** Declare `dsh.bundle` in `package.json` when the package contributes composition rows, install with `dsh plugin --profile <name> add <spec>`, confirm with `--dump-config`. → `references/config-and-packaging.md`

## Routing

Read the reference for the *thing you are about to write*, not all of them.

| When you are about to… | Read |
| --- | --- |
| detect a version, pick a package version, check whether an API exists, decide if a claim is trustworthy | `references/api-verification.md` |
| write `apply()`, pick a plugin form, reason about load order, disposal or `inject` | `references/plugin-anatomy.md` |
| add a model-facing tool, change `output.render`, gate or rewrite tool calls, run work in the background | `references/tools.md` |
| expose a capability to other plugins, listen to an event, choose a dispatch mode | `references/services-and-events.md` |
| add a model provider or wrap an existing one | `references/llm-adapters.md` |
| render in the browser half, add a settings panel, call a host method from the client | `references/client-ui.md` |
| make something configurable, package it, publish it, install it, read a patch layer | `references/config-and-packaging.md` |
| decide what to test, a plugin won't load, `ctx.x` is undefined, it works from source but not after install | `references/testing-and-debugging.md` |

## Done means

A plugin is done when all of these are true — otherwise say which one isn't:

- The profile boots with the plugin mounted, and the startup log shows it loaded (not merely "no error").
- Unloading the plugin leaves no timer, listener, connection, tool registration or background job behind.
- Every API name used traces to the verified type source, and you can name that source and version.
- Tool outputs validate against their declared `output.schema`, and `render()` produces the text a human reads.
- Configuration errors surface at load time with a message naming the bad field.
- Install path is proven at least once: `dsh plugin add` in a throwaway profile, then `--dump-config` shows the row.

If the user asked only for a design or a review, deliver that and label the design decisions as recommendations rather than verified API facts.

• .gitignore 1 KB
• LICENSE 1 KB
• README.md 7 KB
• README.zh-CN.md 6 KB
• SKILL.md 8 KB
• THIRD-PARTY-NOTICES.md 2 KB