---

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 / 目录

English

#	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 11 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	调试与验证工作流	Debugging and verification
5	分发与发布	Distribution and publishing
6	FAQ — 十一个最易踩的坑	FAQ — the 11 pitfalls
7	皮肤与个性化	Skins and Personalization
8	发布到目录	Publishing to the Catalog
9	预设与场景包	Presets and Scenario Packs

---

What's inside / 内容亮点

• 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. / 三类插件形态，最小且完整——工具、事件、双半面板，均来自可运行 spike。
• The 15 design principles — each with the rule, the one-sentence why, and the anti-pattern. / 15 条设计准则——每条含规则、一句话理由、反例。
• A key-free verification workflow — scaffold, build, dsh plugin add, --dump-config, headless. / 无 API key 的验证工作流——脚手架、构建、装载、--dump-config、headless。
• 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. / 分发与版本坑——bundle vs profile、cordis.patch.yml，以及为什么 dsh-tools 必须锁 next tag。

Screenshots live under assets/screenshots/ — real terminal frames (rendered dark-theme) and Playwright captures of a live dsh web server. / 截图在 assets/screenshots/——真实终端帧与真实 dsh web 的 Playwright 截屏。

---

Companion repo / 配套仓库

• dsh-suite — 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. / DSH 插件目录、create-dsh-plugin 脚手架与迁移指南。本书是配套内容资产，套件是代码。
• DeepSeek Harness — the upstream harness. / 上游 harness。
• Cordis — the plugin framework underneath. / 底层插件框架。

---

Star and contribute / 求 Star 与贡献

⭐ 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. / ⭐ 如果这本书帮你省下一小时插件调试时间，给个 Star——这是我们判断该继续扩充的依据。 欢迎 issue / PR 补充章节、更清晰的示例或新坑。

---

License / 许可

MIT © 2026 whyihaveyou