西瓜书插件开发指南 BuilderX-Club/dsh-watermelon-book

DSH 西瓜书 · 平民插件开发指南 🍉

DeepSeek Harness 插件开发，从零到能自己造工具。

一本写给 BuilderX 社区朋友的插件开发教程 —— 不要求你会 TypeScript、不要求你懂框架原理，只需要你有一个想让它帮你干活的想法。

这本书是什么

2026 年 8 月 13 日，DeepSeek 开源了 agent 框架 DeepSeek Harness（dsh）。
它的口号是 "Everything is a Plugin" —— 一切皆插件：工具是插件、模型适配是插件、文件访问是插件、连 agent 主循环本身都是插件。

这意味着什么？意味着 这个框架是"长"出来的，不是"写"出来的。
而"长"的权力，官方已经交到了每个人手里 —— 包括你。

这本书教你怎么用这份权力。

这本书不是什么

- ❌ 不是官方文档的翻译。官方文档很全，但它是给"已经会的人"查的。
- ❌ 不是源码解析。源码解析留给更专业的系列（比如 Jackywine 的 DSH 源码解析）。
- ✅ 是一本 从开机到造出第一个插件 的平民指南：每段代码都跑过、每个命令都验证过、每个坑都替你踩过。

目录

第一部分 · 零基础上手（约 30 分钟）

| 章节 | 内容 | 你会得到 |
| 第 1 章 · 先跑起来 | 装 Node、跑起 DSH Web UI | 一个能聊天的本地 agent |
| 第 2 章 · 第一个插件 | 插件是什么、怎么写 | 你的第一个插件（5 行代码） |
| 第 3 章 · 第一个工具 | 用 defineTool 造一个真工具 | 能让 AI 调用的 greet 工具 |

第二部分 · 深入机制（按需阅读）

| 章节 | 内容 |
| 第 4 章 · 配置与生命周期 | 插件如何接收配置、如何被卸载清理 |
| 第 5 章 · 服务与依赖 | inject 依赖注入、Service 是什么 |
| 第 6 章 · 事件系统 | 插件间怎么通信 |
| 第 7 章 · 解剖一个真实工具 | tool-fs / tool-bash 源码导读 |

第三部分 · 发布与生态

| 章节 | 内容 |
| 第 8 章 · 打包与发布 | bundle、profile、npm 发布、GitHub 安装 |
| 第 9 章 · 加入插件生态 | dsh-plugin topic、社区、下一步 |

附录

- 附录 A · 命令速查
- 附录 B · 术语对照表
- 附录 C · 踩坑记录

配套代码

每一章的代码都在 examples/ 里，可以直接抄、直接跑：

examples/
├── hello-plugin/ # 第 2 章：最小插件 └── greet-tool/ # 第 3 章：greet 工具插件

🤖 对 AI 友好：让 AI 帮你写插件

这本书不仅给人读，也给 AI 读。社区粉丝可以把下面这些直接丢给 AI，让它开发插件：

| 资源 | 给 AI 干什么 | 位置 |
| AGENTS.md | 给 AI 的插件开发指引：铁律 + 骨架 + 验证步骤 | agents/AGENTS.md |
| Prompt 模板 | 把需求填进去，AI 直接产出完整插件 | agents/prompts/plugin-dev-prompt.md |
| 规范速查 + 自检清单 | AI 写完插件后逐项自检 | agents/prompts/plugin-checklist.md |
| 脚手架模板 | clone 后让 AI 改造，5 分钟出插件 | agents/templates/dsh-plugin-template/ |

💡 用法：把需求 + Prompt 模板 丢给任意 AI，让它生成插件源码；然后让它按自检清单检查；最后启动验证。全程不需要你手写代码。

实测承诺

本书所有命令、代码、预期输出，均在以下环境实测通过：

- Node.js v22.22.1 / pnpm 11.7.0
- deepseek-harness @ 0.1.0-rc.6（2026-08-13 发布，对应 master @ 2026-08-14）
- 平台：Ubuntu Linux（本仓库审查时另在 macOS + Node 26 实测通过）

⚠️ DSH 目前是 developer preview，官方明确说会频繁破坏兼容。
本书的代码对应上述版本；如果未来 API 变了，以你本机 dsh 的实际行为为准。

许可

本书内容采用 CC BY 4.0 协议 —— 可以自由分享、改编，保留署名即可。

BuilderX 造物挑战 · 立足中国 · 面向全球的 AI Builder 社区