dsh-plugin-developer

dsh plugin development (0.2.x)

Overview

"Adding new capabilities" in DeepSeek Harness (dsh) = writing a plugin mounted to the Cordis container,no need to fork the source code. dsh has no privileged kernel: model adapters, tool registries, the Agent loop, and the web UI are all plugins.

A plugin consists oftwo halves:Host half(Node process; registers tools/skills/system prompts, runs business logic and HTTP) + Client half(browser; registers pages/tabs/commands/Toolview). All workflows, templates, and reference materials are based on 0.2.x (official docs + hands-on experience from four published open-source plugins).

Workflow

Step 0: Diagnose the requirement + choose the type (first determine what capability is needed)

Check the requirement againstthe capability map（plugin-types.md has the full table):

What the user wants	What to use	Half
An extra action for the model	ctx.tools.register	Host
Teach the model to produce output per a spec	ctx.skills.registerProvider	Host
Teach the model when to use tools	ctx.systemPrompt.section	Host
Sidebar page/workbench	slots.inject('sidebar.panellist'+'main') + ctx.webServer.register	Client+Host
/commands, session tabs, right panel, settings card	inputTriggers / conversation.view / sidebarRightTabs / Config+configForms	Client
Local persistent data	$DSH_HOME/<插件名>/ + Host read/write	Host
Call external APIs / generate images	Tools + async job polling (http-client.md)	Host

Rule of thumb:What is registered for the model goes in the Host; what is registered for the user goes in Client slots; the legwork goes in the Host. 90% of requirements start with Tool + Skill (+ system prompt). To replace underlying mechanisms (swap the model gateway/add approval checkpoints/change the loop), see the four types in plugin-types.md.

Step 1: Environment setup

1. Node 22.19+ or 24+（node -v Verify; 20 will definitely crash).
2. Confirm dsh is available：dsh -v; the target host version determines the engines.dsh range in the skeleton (default >=0.2.1-rc.2 <0.3.0）。
3. Determine where you are developing：
   • In dsh's own conversation(Harness built-in agent): officially ships with the cordis-plugin-development skill + plugin_manager（install_bundle）/cordis_inspect_query(looks up the authoritative Service/Event/Config/Slots/Theme APIs of the installed host) tool —inside the host, everything is subject to the inspection results; to install plugins use install_bundle , do not manually edit the profile.
   • Outside dsh(terminal/editor/external AI): use this Skill's workflow; the following official docs can be WebFetched:

Topic	URL
First plugin	https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/
Tools	https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/tool
Configuration	https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/config
Packaging and installation	https://deepseek-harness.github.io/deepseek-harness/en/develop/basic/publish
Lifecycle/services/events	https://deepseek-harness.github.io/deepseek-harness/en/develop/framework/ （events、service）
Tool authoring reference (cookbook)	https://deepseek-harness.github.io/deepseek-harness/en/reference/cookbook/adding-a-tool

Another authoritative knowledge source: the official skills and templates bundled in the locally installed dsh package —<dsh 安装目录>/node_modules/@deepseek-ai/dsh-agent-preset/skills/cordis-plugin-development/(including references and the decoration/mcp templates); when unsure of the official stance, read it directly.

Step 2: Build the skeleton

python scripts/scaffold_plugin.py <项目目录> --name dsh-my-plugin
# 或手动复制 assets/plugin-skeleton/

The skeleton is afully runnableminimal plugin closed loop: tool (memo_add/memo_list, native registration + self-written validation + presentationMeta) + skill (with addendum) + system prompt + plugin page (gallery/ + webServer prefix routing + the auth trio + safeFile) + $DSH_HOME data persistence (atomic writes / mtime re-read across two processes) + Client half (sidebar + main slot + theme following + open new conversation only fills, does not send) + esbuild packaging self-check + node --test unit tests (no dsh dependency) + dev-sandbox isolated dev script. All 9 tests green, build self-check passed.

See the rename list in assets/plugin-skeleton/README.md; the role of each file and line-by-line explanation are in architecture.md。

Step 3: Implement capabilities (read the corresponding guide as needed)

• Tool → tool-plugin.md: defineTool vs native registration, exec context, output canonical value contract, presentationMeta, presentCall/presentResult cards, error handling.
• Skill → skill-plugin.md: two-level loading, Candidate fields, directory aggregation, snapshot vendor, rewrite+addendum, rank yielding.
• System prompt → system-prompt.md: anchor order, interpolate, prefix/suffix.
• Calling external APIs → http-client.md: async jobs + polling, injectable fetch, undici proxy, attachment-to-image generation, external CLI-type tools.
• Plugin page/HTTP/data → web-and-data.md + browser-side.md: prefix routing, the auth trio, safeFile, $DSH_HOME pattern; slot map, iframe communication, startSession, theme, i18n, Toolview.
• Deep integration → host-integration.md: the four event modes, calling the host model, background tasks, agent.inject notification.
• Security → security.md: go through the checklist item by item before publishing.
• Selection/replacement mechanism → plugin-types.md。

Step 4: Build

npm install && npm test && npm run build   # 骨架：JS 零构建 Host + esbuild 打包 client

Two mainstream forms in 0.2.x:JS zero-build(Host publishes source directly, only bundles client — the approach of the skeleton and guizang/media-desk) and TS dual-end tsdown(the approach of dsh-context/geochat). For the approach and the three major artifact self-checks, see build-test.md。

Step 5: Test (free-quota-first)

npm test                      # ① 纯函数/契约测试（node --test，不装 dsh）
scripts/dev-sandbox.sh 4311   # ② 隔离 DSH_HOME 跑网页版（Windows: scripts\dev-sandbox.ps1）
node scripts/mock-llm.mjs     # ③ mock 模型：不花额度跑全链路（模式见 build-test.md）
# ④ web 界面人工验收：http://127.0.0.1:3080，确认工具调用 + 页面渲染 + 深浅色

For the test pyramid and how to write each layer, see build-test.md; for error quick reference, see troubleshooting.md。

Step 6: Publish

Before publishing, go through the security.md checklist → npm pack(prepack auto build) → npm publish or Release tgz+SHA256 → for install paths and commands, desktop edition differences, engines.dsh compatibility declaration, marketplace metadata (icon/locale), see publish.md。

Reference index (read as needed, don't read everything at once)

File	Content	When to read
references/architecture.md	0.2.x dual-half model, package.json dsh.* fields, cordis.patch, profile, Config, version declaration	Setting up the skeleton/understanding the big picture
references/plugin-types.md	Capability surface map + four types (Provider/Interceptor/Tool/AgentLoop)	Step 0 selection
references/tool-plugin.md	Complete tool guide (two routes/exec/output/presenters)	Writing tools
references/skill-plugin.md	SkillProvider/snapshot aggregation/rewrite+addendum	Writing skills
references/system-prompt.md	System prompt injection and anchor order	Teaching the model to use tools
references/http-client.md	Async jobs + polling + proxy + attachments	Calling external APIs
references/browser-side.md	Slot map/page/theme/i18n/Toolview	Write browser-side
references/web-and-data.md	webServer routing/auth/safeFile/$DSH_HOME	Build pages and data
references/host-integration.md	Events/host model calls/background tasks/notifications	Deep integration
references/security.md	Security checklist (HTTP/path/SSRF/secrets/XSS)	Before release
references/build-test.md	Build two forms/three self-checks/dev-sandbox/mock-llm/test pyramid	Build/test
references/publish.md	Packaging/channels/installation/desktop differences/version compatibility	Release
references/troubleshooting.md	Error quick reference + thirteen documented pitfalls	Troubleshooting

Templates and scaffolding

• Plugin skeleton：assets/plugin-skeleton/ — Complete 0.2.x closed loop (recommended, runs directly).
• Scaffolding：scripts/scaffold_plugin.py <目录> --name dsh-my-plugin。

Hands-on cases

• assets/plugin-skeleton/: 0.2.x runnable skeleton (preferred blueprint).
• assets/examples/dsh-seedance-studio/：0.2.x hands-on case(made with this Skill). Demo: bundled skill snapshot + rich addendum (execution order/cost discipline), multi-action tool (action enum + credit cap + dryRun + out-of-bounds path rejection), external official CLI integration (dreamina-canvas login/canvas/generation/polling terminal state), webServer read-only interface, sidebar panel (2s polling progress, sharing the same validation set as the tool), offline self-check script. Corresponds to the "tool for calling external generation API/CLI" type of requirement.
• assets/examples/weather-plugin/: weather lookup + animated card (0.1.x historical case, build chain is outdated; the API ideas for tools/skills/system prompts/Toolview still apply).

Four open-source reference implementations already published (pattern comparison table at the end of architecture.md):dsh-context(dashboard/commands/settings cards/compatibility layer),dsh-guizang-design(skill package + pages + tools + data),dsh-media-desk(web app + security + mock testing),GeoChat DSH plugin(native tools + skills + canvas).