ChatGPTClaudeGrok / X / CursorGemini

Practicing DSH plugins without Harness: a no-key lab

Plugin DevelopmentPublished 2026-11-05Author: DeepSeek Plugin Market
DSH pluginCordisplugin tutoriallocal labDeepSeek Harness
No Harness install, no API key, no profile cleanup. Use the repository's Cordis launcher to practice plugins, services, events, and config in seven chapters.

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:

  1. Clone and install: git clone https://github.com/deepseek-ai/deepseek-harness.git, then cd deepseek-harness && pnpm install;
  2. Create a scratch directory: mkdir -p tmp/cordis-tutorial && cd tmp/cordis-tutorial;
  3. Put a cordis.yml in it pointing at your plugin, then run node --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:

yaml
- 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:

ChapterWhat you writeWhat you verify
1A plugin exporting applyThe Loader mounts it and runs it
2A plugin using ctx.effectResources are cleaned up on unload
3One service and two consumersinject waits for readiness, ctx resolves
4One event and several listenersBroadcast, ordering, waterfall short-circuit
5A plugin with ConfigValidation and defaults
6A multi-layer cordis.ymlComposition and hot reload
7A real tool registrationThe 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:

  1. Extract each chapter's apply and helpers into one entry file, keeping name and inject;
  2. Build a minimal bundle: package.json declares dsh.bundle, and cordis.patch.yml references the entry by package name;
  3. Load it once through --patch and confirm behavior matches the lab;
  4. Install with dsh plugin --profile <name> add and verify it still loads;
  5. 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:

  1. You need to verify that a model selects a tool, or how a tool card renders;
  2. You need to test several plugins composing in one profile;
  3. You need to test host-version compatibility, such as an engines.dsh range;
  4. 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.

ChatGPTClaudeGrok / X / CursorGemini

FAQ

Can I learn DSH plugin development without configuring a model or an API key?

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.

Are plugins in the Cordis tutorial written the same way as plugins running inside Harness?

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.

How do I move DSH plugin code from the lab into a real Harness project?

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.

Without an API key, can I still do chapter seven, connecting to the harness?

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