插件开发指南 whyihaveyou/dsh-plugin-tutorial

📖 DSH 插件开发指南 DSH 插件开发指南

The hands-on, screenshot-rich book for building plugins on DeepSeek Harness (DSH) — from your first npm create dsh-plugin to tools, events, panels, and distribution. Bilingual EN / 中文.

一本动手的、全真实截图的 DeepSeek Harness (DSH) 插件开发实战书 —— 从第一条 npm create dsh-plugin 到工具、事件、面板与分发。中英双语。

GitHub stars
License: MIT
Language
Cordis

What is this book / 这本书是什么

DeepSeek Harness is the "everything is a plugin" agent harness. This book is the authoritative,
chapter-by-chapter guide to writing plugins for it, grounded in the two guarantees that make DSH's
plugin model safe at runtime — temporal composability (unload fully reverts a plugin's effects) and spatial composability (dependencies resolve reactively).

DeepSeek Harness 是一个「一切皆插件」的 agent harness。这本书是写 DSH 插件的权威章节化指南，扎根于让 DSH 插件模型在运行时安全的两个保证——时间可组合性（卸载完整撤销插件副作用）与空间可组合性（依赖响应式解析）。

Every code block comes from a verified, runnable spike and the
create-dsh-plugin scaffold — no fabricated API. Every screenshot is a real terminal run or a live dsh web session. The full formal theory behind the model lives in the companion paper notes.

每个代码块都来自已验证、可运行的 spike 与 create-dsh-plugin 脚手架——没有编造的 API。每张截图都是真实终端输出或真实 dsh web 会话。模型背后的完整形式化理论见配套论文笔记。

Table of Contents / 目录

| # | Chapter | 中文 |
| 0 | TL;DR | 摘要 |
| 1 | The plugin model | 插件模型 |
| 2 | The three plugin shapes | 三类插件形态 |
| 3 | The 15 design principles | 15 条设计准则 |
| 4 | Debugging and verification | 调试与验证 |
| 5 | Distribution and publishing | 分发与发布 |
| 6 | FAQ — the 14 pitfalls | FAQ 十四坑 |
| 7 | Skins and Personalization | 皮肤与个性化 |
| 8 | Publishing to the Catalog | 发布到目录 |
| 9 | Presets and Scenario Packs | 预设与场景包 |

| # | 章节 | English |
| 0 | 摘要 | TL;DR |
| 1 | 插件模型 | The plugin model |
| 2 | 三类插件形态 | The three plugin shapes |
| 3 | 15 条设计准则 | The 15 design principles |
| 4 | 调试与验证工作流 | 调试与验证 |
| 5 | 分发与发布 | 分发与发布 |
| 6 | FAQ — 十四个最易踩的坑 | FAQ — 十四个最易踩的坑 |
| 7 | 皮肤与个性化 | 皮肤与个性化 |
| 8 | 发布到目录 | 发布到目录 |
| 9 | 预设与场景包 | 预设与场景包 |

内容亮点 / What's inside

- 三类插件形态，最小且完整——一个 defineTool() 工具、一个 ctx.on/ctx.effect 事件插件，以及一个双半 Web UI 面板（ctx.slots.register + shell.overlay），全部提炼自一个可运行的 spike。/ Three plugin shapes, minimally and completely — a defineTool() tool, a ctx.on/ctx.effect event plugin, and a dual-half Web UI panel (ctx.slots.register + shell.overlay), all distilled from a runnable spike.
- 15 条设计准则——每条含规则、一句话理由、反例。/ The 15 design principles — each with the rule, the one-sentence why, and the anti-pattern.
- 无 API key 的验证工作流——脚手架、构建、dsh plugin add、--dump-config、headless。/ A key-free verification workflow — scaffold, build, dsh plugin add, --dump-config, headless.
- 分发与版本坑——dsh.bundle vs profile、cordis.patch.yml，以及为什么 @deepseek-ai/dsh-tools 必须锁 next tag。/ Distribution and the version trap — dsh.bundle vs profile, cordis.patch.yml, and why @deepseek-ai/dsh-tools must be pinned to the next tag.

截图在 assets/screenshots/——真实终端帧（暗色主题渲染）与真实 dsh web 服务器的 Playwright 截屏。/ Screenshots live under assets/screenshots/ — real terminal frames (rendered dark-theme) and Playwright captures of a live dsh web server.

配套仓库 / Companion repo

- dsh-suite——DSH 插件目录、 create-dsh-plugin 脚手架与迁移指南。本书是配套内容资产，套件是代码。/ the DSH plugin catalog, the create-dsh-plugin scaffolder, and the migration guide. This book is the companion content asset; the suite is the code.
- DeepSeek Harness — 上游 harness。/ the upstream harness.
- Cordis — 底层插件框架。/ the plugin framework underneath.

求 Star 与贡献 / Star and contribute

⭐ 如果这本书帮你省下一小时插件调试时间，给个 Star——这是我们判断该继续扩充的依据。
欢迎 issue / PR 补充章节、更清晰的示例或新坑。/ ⭐ If this book saves you an hour of plugin debugging, star the repo — it's how we know the guide is worth expanding. Issues and PRs for missing chapters, clearer examples, or new pitfalls are welcome.

许可 / License

MIT © 2026 whyihaveyou