Practicing DSH plugins without Harness: a no-key lab
There is a specific way to lose a day: you want to understand how plugins work, but you get stuck installing Harness, finding a key, and choosing a profile. The repository ships a practice environment that starts with one command and needs no key. This is that route: how to set it up, what each chapter teaches, and how to move the code back.
Who should practice DSH plugin basics here first
The DSH plugin lab pays off for three readers: no Harness yet, a messy environment, or a framework gap.
Three situations where the lab pays off immediately.
You have not installed Harness yet. You want to know whether the plugin model fits your work before committing, and installing first is a more expensive way to find out. Harness is installed but the environment is messy. Multiple dsh copies, unpredictable profiles, a config change that takes an hour to diagnose — experiments in a temporary directory touch none of it.
You can write tools but not explain the framework. You know a tool plugin when you see one, but Fiber, inject, and effect are still separate words. Seven chapters connect them. Who should skip it: anyone who just wants the model to do their work. The lab produces understanding, not a usable interface.
Three steps to a running DSH plugin lab
A DSH plugin lab needs three steps: clone, create a scratch directory, and write one cordis.yml.
The official prerequisites are three commands:
- Clone and install:
git clone https://github.com/deepseek-ai/deepseek-harness.git, thencd deepseek-harness && pnpm install; - Create a scratch directory:
mkdir -p tmp/cordis-tutorial && cd tmp/cordis-tutorial; - Put a
cordis.ymlin it pointing at your plugin, then runnode --import tsx ../../vendor/cordis/bin.js.
The launcher always does the same thing: create the root Context, mount the Loader plugin, and let the Loader read ./cordis.yml from the current directory. Which plugins exist and how they are configured all come from that YAML. --import tsx removes the build step. Node runs TypeScript directly, so save a change and run again to see the result.
tmp/ is git-ignored. Nothing you write there enters version control, which makes it safe to break. A minimal cordis.yml is one line:
- name: './hello.ts'
hello.ts exports name and apply; running the launcher prints whatever apply logs. Save and re-run — no cache clearing needed.
Three TypeScript notes save a lot of searching: type annotations describe values without changing runtime; import type disappears after compilation and only constrains types; declare module performs declaration merging that types ctx or events but produces no runtime wiring.
What the seven DSH plugin chapters cover
Working through all seven chapters is what makes DSH plugin services, events, and config compose correctly.
The route builds on itself, and every chapter uses the previous one's output:
| Chapter | What you write | What you verify |
|---|---|---|
| 1 | A plugin exporting apply | The Loader mounts it and runs it |
| 2 | A plugin using ctx.effect | Resources are cleaned up on unload |
| 3 | One service and two consumers | inject waits for readiness, ctx resolves |
| 4 | One event and several listeners | Broadcast, ordering, waterfall short-circuit |
| 5 | A plugin with Config | Validation and defaults |
| 6 | A multi-layer cordis.yml | Composition and hot reload |
| 7 | A real tool registration | The plugin reaches Harness's registry |
Do not skip chapters. Service dependencies from three, event dispatch from four, and config validation from five all appear together in chapter six; if earlier chapters were not run, a later failure is unattributable.
Every chapter should leave an observable result. Chapter one prints output, two prints cleanup logs, three shows the waiting state when a service is absent, four shows listener order, five shows an invalid-config error. Without observing the result, you did not do the chapter.
Four differences from a real DeepSeek Harness
The DSH plugin lab differs from a real DeepSeek Harness in entry, interface, model, and DSH_HOME.
The lab is useful precisely because it is small, but it is not Harness. Four differences matter:
Loading entry. Here cordis.yml points directly at source files; in Harness the CLI starts a profile whose manifest lists bundles. No interface. There is no Web UI, so tool registration is confirmed from logs or a self-check; Harness shows the tool list and call cards directly.
No model. Without a key you cannot verify that a model picks your tool at the right moment, only that the tool registers.
No DSH_HOME. Sessions and config here never touch ~/.dsh, so a broken experiment leaves the real environment alone — and conversely, you cannot inspect real history here.
Keep those four in mind and you will not use lab results to explain production failures. "The tool registered but the model never calls it" simply cannot reproduce here.
Moving DSH plugin code into Harness
Moving DSH plugin code into Harness keeps the logic and drops the directory layout.
Move the logic, not the directory layout:
- Extract each chapter's
applyand helpers into one entry file, keepingnameandinject; - Build a minimal bundle:
package.jsondeclaresdsh.bundle, andcordis.patch.ymlreferences the entry by package name; - Load it once through
--patchand confirm behavior matches the lab; - Install with
dsh plugin --profile <name> addand verify it still loads; - Only then consider publishing or submitting to a market.
Do not skip step three. Going from "Loader reads a local file" to "profile resolves a package name" changes the resolution path entirely; verifying first tells you immediately whether a failure is packaging or logic.
Resist renaming services and events during the move. Once something in the real environment injects them, the names are public contracts; keeping them unchanged avoids a round of PENDING debugging.
When to leave the DSH plugin lab
Leave the DSH plugin lab once you need a real model, real profiles, or real user data.
The lab builds a mental model, not a development environment. Switch when any of these appear:
- You need to verify that a model selects a tool, or how a tool card renders;
- You need to test several plugins composing in one profile;
- You need to test host-version compatibility, such as an
engines.dshrange; - You need to reproduce a user report, which requires real data and a real profile.
The lab answers "what is a plugin"; the real environment answers "does this plugin work". Answer both and you can actually write one.
For the conceptual version of Context and inject, read Cordis primer; for hot reload and composition, read plugin hot reload; to start with real project structure, read building a plugin from zero.
FAQ
Yes, DSH plugin exercises need neither a model nor a key. The Cordis tutorial in the repository uses a single-file launcher that loads a local cordis.yml, and none of its examples need a key. You practice assembly, lifecycle, services, and events rather than model calls.
The plugin model is the same: a module exporting apply and name. The host differs. The tutorial's launcher reads a local cordis.yml, while Harness starts a profile through the CLI and loads plugins in the Web UI.
Keep the apply logic and switch the DSH plugin to a bundle layout: a package.json declaring dsh.bundle and a cordis.patch.yml referencing the entry by package name. Load it with --patch first, then install it into a profile.
You can verify DSH plugin assembly but not whether the model picks your tool. The checks are that the plugin loads and the tool appears in the registry. Confirming model behavior still requires a configured provider and key.
Related Terms
- Cordis
- Cordis is the plugin framework underneath DeepSeek Harness, providing context, lifecycle, services, and events on which every Harness capability is mounted.— DeepSeek Harness docs
- cordis.yml
- cordis.yml is the configuration describing the plugin tree, telling the launcher which plugins to load, in what order, and with what config.— DeepSeek Harness docs
- Loader
- The Loader reads cordis.yml, resolves plugin rows, and mounts plugins; it is itself mounted on the root context as a plugin.— DeepSeek Harness docs
- profile
- A profile is a named assembly environment under $DSH_HOME/profiles/<name>, a different concept from the tutorial's temporary directory.— DeepSeek Harness docs
Sources
- DeepSeek Harness docs: Cordis tutorial· deepseek-harness
- DeepSeek Harness docs: your first plugin· deepseek-harness
- deepseek-harness repository· deepseek-ai