插件架构白皮书 feicaiclub/deepseek-harness-whitepaper

DeepSeek Harness 白皮书

一切皆插件：从装上它，到看懂它，到自己扩展它

131 页 · 七部三十八章 · 全部结论回源码核对

这是什么

2026 年 8 月 13 日，DeepSeek 用 MIT 协议开源了自己的 agent harness —— dsh。

它和市面上的同类产品最本质的差别，不在功能多少，而在一个架构主张：整个产品没有特权核心，包括主循环在内的每一个部件，都是可以被替换或关掉的插件。

这份白皮书把它拆开讲清楚。131 页，从「harness 到底是什么」讲到「你自己写的插件怎么装进去」。

它不是官方文档的翻译，也不是 README 的扩写。 全书所有关于代码行为的判断，都以仓库源码为准；文档与代码冲突的地方，文中注明冲突并采信代码 —— 这样的地方我们找到了不止一处。

为什么值得你花时间

| 敢讲代价 | 每讲一个优点就算一次账。遥测默认端点硬编码指向哪台服务器、Web 服务端没有任何鉴权、插件与主程序同进程零隔离 —— 这些官方 README 里写了但没人翻译过来的东西，都在书里 |
| 数字全部实测 | 219 个包、26 条能力接缝、52 个内置工具、44 种会话事件、541 篇决策笔记 —— 每一个都能在仓库里复算，不转述二手资料 |
| 能照着做 | 装、配模型、用界面、接 CI、写第一个插件、打包发布 —— 命令和代码都是可执行的，不是示意 |
| 分层可读 | 正文写给不一定写代码的人；代码、文件路径、源码证据放在左侧页边栏。想深挖的顺着路径回仓库核对，不想看的整栏跳过 |

立即阅读

- 下载 PDF —— 131 页 A4，文字可搜可选，适合通读和打印
- 在线阅读网页版 —— 单文件、字体已内嵌，另存后断网也能看

想在本地起个服务：

git clone https://github.com/feicaiclub/deepseek-harness-whitepaper.git
cd deepseek-harness-whitepaper && python3 -m http.server 8000
打开 http://localhost:8000

怎么读

这本书按读者依次会产生的问题排，不按代码仓库的目录排。不必从头读到尾：

| 你是哪一种 | 只读这些就够 | 篇幅 |
| 只想用它 | 01 → 04 → 06–10 → 38 | 约 32 页 |
| 要写插件 | 03 → 04 → 11 → 13 → 26–35 | 约 36 页 |
| 要做选型 | 一页摘要 → 05 → 第五部代价页 → 36–38 | 约 23 页 |

时间只够读两部，就读第一部和第七部：一头告诉你它是什么，一头告诉你要不要碰。

里面有什么

| 部 | 这一部回答的问题 | 章 |
| 一 · 认识它 | 这东西到底是什么，值不值得我花时间 | 01–05 |
| 二 · 装上它，用起来 | 怎么在我自己的机器上跑起来、配上模型 | 06–10 |
| 三 · 它由什么组成 | 我看到的这两百多个包，是按什么分的 | 11–14 |
| 四 · 走完它的全程 | 我说一句话之后，里面究竟发生了什么 | 15–20 |
| 五 · 它的五个特点 | 它跟别的 harness 的差别落在哪几处 | 21–25 |
| 六 · 插件 | 我要自己扩展它，从哪一行开始写 | 26–35 |
| 七 · 判断 | 这一轮我到底该不该用它 | 36–38 |

外加四个附录：术语表、能力接缝清单、内置工具清单、研究方法与来源。

你会学到什么

- harness 到底是什么 —— 模型只会文字进文字出，是哪一层程序让它能读文件、跑命令、连着干活
- 怎么把它装上并跑起来 —— 两条安装路线、配模型、Web 界面、命令行、接 CI 的正确入口
- 「一切皆插件」是字面意义还是修辞 —— 判定标准是什么，官方自己是怎么关掉自带功能的
- 你说一句话之后里面发生了什么 —— 提示词怎么拼、模型怎么被调用、工具怎么执行、权限在哪一环、日志怎么记
- 一个插件长什么样 —— 完整可跑的代码，以及五种插件角色分别适合什么场景
- 第三方能挂进去的所有位置 —— 注册入口、事件拦截点、能力接缝，各自的门槛与代价
- 哪些坑会静默出错 —— 不报错、不打日志、只是结果不对的那一类
- 这东西现在该不该用 —— 分场景的建议，以及什么时候该重新评估

能照着做 · 完整可跑的插件，没有省略敢讲代价 · 官方 README 里写了、但没人翻过来的事

版本与免责

- 研究基线：deepseek-harness 0.1.0-rc.5（仓库源码版本；npm 上 latest 标签当时是 0.1.0-rc.6，两者不是一回事，书中凡涉及都说明了是哪一个）
- 快照时间：2026 年 8 月
- 这个项目正处在快速迭代中，官方 README 用全大写写着会有破坏性变更。这份文档会过时 —— 它记录的是这个时点的样子，以及为什么它长成这样。
- 本文档由废才俱乐部独立编写，非官方出品，与 DeepSeek 无隶属关系。

如果这份白皮书对你有用

废才俱乐部 · FEICAI CLUB

不说空话 / 只教你有用的东西

这份白皮书不是一次性的作品，是我们做内容的固定方式：读源码、数字实测、多轮核查、敢讲代价。

站里正在更新的方向，和这本书是同一条线 ——

#AGENT　#SKILL　#CLAUDE-CODE　#CODEX　#HARNESS#CONTEXT-ENGINEERING　#PROMPT-FRAMEWORK　#MCP-TOOLING　#RAG　#EVAL

除了 AI Agent 与 AI 编程，我们也做 AI 写作、AI 漫剧、AI 短剧、AI 设计生图、UI 设计，以及这些东西在具体行业里到底怎么落地。文章之外还有配套资源包、活动专区和付费社群。

→ www.feicaiclub.cn

订阅之后，这类深度内容会持续送到你面前

觉得这份白皮书有价值，给仓库点个 Star ⭐️ —— 也让更多人看见它

参与与反馈

发现错误、有补充、或者你也在做 dsh 插件 —— 欢迎开 issue 或 PR。

技术类文档最怕的是错了没人说。这本书里每一个数字都可以被复算，每一条判断都标了出处，就是为了让你能挑出我们的错。

协议

MIT © 废才俱乐部

文中引用的 DeepSeek Harness 源码与文档，版权归 DeepSeek AI 所有，其项目同样采用 MIT 协议。