DSH Plugin Development

An architecture-first field guide and Agent Skill for building plugins for DeepSeek Harness and its Cordis runtime.

This project is independent community work. It is not affiliated with or endorsed by DeepSeek.

The core idea

A DSH plugin is not merely a JavaScript module that registers a Tool. It is five systems at once:

flowchart LR
  A["Cordis capability graph"] --> B["Tool contract"]
  B --> C["Model / Code / UI projections"]
  C --> D["Durable session replay"]
  D --> E["Product interaction"]
  A --> F["Profile and package closure"]
  F --> E

Most difficult failures happen when one of these boundaries is mistaken for another:

• a canonical Tool value is confused with model-facing rendered content;
• a live card is assumed to be replayable;
• a React component is tested without its real owner/selection/slot chain;
• atomic list Tools turn the model into a pagination engine;
• a monorepo makes undeclared runtime dependencies look installed;
• config order is mistaken for Cordis activation.

The SKILL.md teaches a reusable way to reason about those boundaries. The failure atlas maps common symptoms to the incorrect mental model behind them.

What this repository contains

• SKILL.md — the installable Agent Skill;
• references/failure-atlas.md — symptom → failed boundary → correct diagnosis;
• scripts/check-plugin-closure.mjs — a read-only package/build/peer-dependency checker for out-of-tree DSH plugins;
• evals/evals.json — realistic prompts for evaluating whether an Agent learned the architecture rather than memorizing a checklist.

Install as an Agent Skill

Clone the repository into a skill directory recognized by your Agent runtime:

git clone https://github.com/JerryChaox/dsh-plugin-development.git \
  ~/.agents/skills/dsh-plugin-development

For a project-local installation, place it under:

<project>/.agents/skills/dsh-plugin-development/

The Skill should trigger for DSH/Cordis plugin work, Tools, Code Mode, client slots, replay bugs, profile packaging, blank details panels, and plugins that work in a source checkout but fail after installation.

Check a plugin's installation closure

Build the target plugin first, then run:

node scripts/check-plugin-closure.mjs /path/to/plugin

The checker verifies declared and built host/client entrypoints, bundle patches, client injections, and whether every peer dependency resolves from the plugin's own installation location.

It deliberately does not prove that the plugin is active. Inspect the actual DSH profile separately:

dsh --profile <profile> --dump-config

Design thesis

The Agent should choose business intent and constraints. A high-level Tool should execute the data plan. The UI should help a person inspect the resulting decision.

That separation is more robust than asking the model to manually page through large datasets, copy intermediate JSON into context, and explain internal Tool fields to the user.

License

MIT