# dsh-plugin-development

> A universal dsh plugin development Skill — any agent tool loads it and can develop dsh plugins that conform to DeepSeek Harness

[![license](https://img.shields.io/badge/license-MIT-green)](LICENSE)
[![dsh](https://img.shields.io/badge/dsh-0.1.0--rc.6-blue)]()
[![skill](https://img.shields.io/badge/skill-AGENTS.md-orange)](SKILL.md)
[![中文](https://img.shields.io/badge/readme-中文-red)](README.md)
[![English](https://img.shields.io/badge/readme-English-blue)](README.en.md)

An **agent-tool-agnostic** Skill (`SKILL.md`): Claude Code, Codex, Hermes, OpenClaw, DeepSeek Harness' built-in agent — any agent that loads this Skill can develop, register, install, and debug dsh plugins (`dsh插件`) against the **real plugin contract** of DeepSeek Harness (DSH).

Every contract statement is verified against an installed **dsh 0.1.0-rc.6**: the `.d.ts` files inside `@deepseek-ai/*` packages, the `dsh web --dump-config` composed tree, and the `dsh` CLI source. It also builds on the proven [claude-parchment-theme](https://github.com/RayYeung1989/claude-parchment-theme) plugin (the parent of this repo's client template).

## Features

- ✅ **Agent-tool agnostic** — no dependency on DSH-internal tools; any agent can follow with plain file + shell tools
- ✅ **Ground truth first** — the Skill requires agents to read the installed version's `.d.ts` and composed tree, banning invented APIs and resisting version drift
- ✅ **All three plugin shapes** — host-only (server), browser-only (client theme/UI), and dual-half plugins
- ✅ **Runnable templates** — three scaffolds under `templates/`, all passing `node --check`
- ✅ **Tested end-to-end** — a fresh sub-agent loaded this Skill and correctly produced a dual-half plugin; its findings fixed a contract error in the Skill's first draft

## Layout

```
dsh-plugin-development/
  SKILL.md                       # Main Skill (agent entry: workflow / decision tables / failure table)
  README.md                      # Chinese readme
  README.en.md                   # This file
  LICENSE                        # MIT
  references/
    plugin-package.md            # Full contract: package layout / entry / manifest / patch / CLI / module resolution
    services-events.md           # Service & event surface + how to enumerate it at runtime
  templates/
    server-plugin/               # Host-only starter (Config + events + timer)
    client-plugin/               # Browser-only starter (theme token override + CSS, proven pattern)
    dual-half-plugin/            # Dual-half starter (host Service class + browser remote.$on)
```

## Installing into agent runtimes

Copy this folder into the runtime's skills directory, or keep one copy in `~/.agents/skills/` (the cross-runtime central repo that DSH reads directly) and symlink it into each agent tool's skills dir with your skill-distribution tool:

| Runtime | Directory |
| --- | --- |
| Codex / Copilot CLI / Gemini CLI / DSH itself | `~/.agents/skills/dsh-plugin-development/` |
| Claude Code | `~/.claude/skills/dsh-plugin-development/` |
| DeepSeek Harness (home-level) | `$DSH_HOME/skills/dsh-plugin-development/` |
| Hermes / OpenClaw / others | Any skills directory that tool scans for `SKILL.md` |

> DSH skill-root precedence (smaller number wins): project `.dsh/skills` (100) → project `.agents/skills` (200) → `customSkillDirs` (300) → `~/.dsh/skills` (400) → `~/.agents/skills` (500) → bundled. Drop a same-name Skill into a higher-precedence root to override it.

## Quick start

After loading the Skill, an agent follows the 8-step workflow:

1. Locate the local dsh install and target profile (`echo $DSH_HOME`, `dsh --version`)
2. Read the composed tree `dsh web --dump-config`; find the row id to add or override
3. Decide host vs browser side with the decision table
4. Scaffold from `templates/`; write code against the real `.d.ts`
5. Register in `cordis.patch.yml`: `- insert: - id: xxx name: '@dsh-local/xxx'`
6. Install: `dsh plugin --profile web add <path-or-github-spec>`
7. Verify: `dsh web --dump-config` shows the new row → restart `dsh web` → client plugins visible under Settings → Plugin management
8. Debug with the failure table

## Plugin contract at a glance (details in references/)

| Face | Contract |
| --- | --- |
| Host entry | ESM; `export { name, inject, Config, apply }` / default-export function / default-export `Service` subclass (`static Config`, schemastery `z.object`) |
| Browser half | `package.json` declares `dsh.client = { platform, inject, immediately }` + a `./client` export; `lib/client.js` registers via `window.__ModuleLoader__.load({ id, factory })`, plain JS without import/JSX |
| Events | `turn/start\|end` (`{turn, reason}`), `step/start\|end`, `user/message`, `assistant/message` (content is a blocks array), `tool/call\|result`, `assistant/chunk` |
| Services | Host: `sessions`, `llm`, `agents`, `skills`, `settings`, `subagents`, `goals`, `timer`; Browser: `theme`, `slots`, `modules`, `remote` |
| Registration | Patch rows are addressed by `id`, last write wins, `config` is replaced wholesale (no merging); `!!js` expressions can read env/ctx values |

## Version baseline

- dsh / `@deepseek-ai/*`: `0.1.0-rc.6`
- DSH is `0.1.0-rc.*` and moving; the Skill requires agents to trust the **installed version's** `.d.ts` over any table in this repo

## Related projects

- [deepseek-ai/deepseek-harness](https://github.com/deepseek-ai/deepseek-harness) — DeepSeek Harness itself
- [RayYeung1989/claude-parchment-theme](https://github.com/RayYeung1989/claude-parchment-theme) — a shipped dsh theme plugin (parent of this repo's client template)

## License

[MIT](LICENSE) © RayYeung1989