diguike
book-deepseek-harness
《一切皆插件》— DeepSeek Harness 源码精读、Mini 实现与插件开发实战。21 章 + 可运行的 mini-dsh + 真实插件案例，全部数据实测。
- Stars
- 0
- Language
- TypeScript
- Created
- Aug 17, 2026
- Updated
- Aug 17, 2026
Introduction
一切皆插件
DeepSeek Harness 源码精读、Mini 实现与插件开发实战
这本书讲 DeepSeek 官方开源的 agent harness dsh 本身是怎么设计的——不是怎么用它写代码，是它凭什么能让主循环、模型适配器、会话日志都变成配置里的一行。
dsh --profile web --dump-config 会打印出你这台机器上将要启动的整棵插件树。490 行 YAML、129 个插件行。模型适配器是一行，会话日志是一行，主循环 agent-loop 也是一行。任意一行都能被你自己的一行 YAML 顶掉。
为什么读这本书
如果你用过 Claude Code 或 Codex，想给它加点东西，最后发现只能挂一个 hook——那你已经碰到这本书要解决的问题了。你能扩展的，是人家预留给你的那几个洞。
dsh 给了另一个答案：没有内核，所以没有洞，因为没有墙。
这本书做四件官方文档不做的事：
- 把设计取舍和代价讲透。「没有内核」放弃了什么，「日志是唯一真相源」谁在付账
- 横向对比与选型判断。dsh 和 Claude Code / Codex / OpenClaw 的分野，以及为什么 LangGraph 压根不在同一个抽象层
- 源码走读 + 亲手重建。用 TypeScript 写一个能跑的迷你实现，约 3500 行
- 把工程方法提炼成能搬走的清单。dsh 是人和 agent 共同维护 50 万行代码的公开样本
写给谁
- 在公司搭 agent 平台的人（第一优先）——第 4、13、14、18 章能直接变成设计文档和 PR
- 已在用 CC / Codex、想扩展却碰壁的中高级工程师——技术栈 TypeScript / Node
- 从传统后端转 AI 的工程师——第 2 章做概念对齐，附录 D 补 TypeScript 缺口
不适合：想找「用 AI 写代码技巧」的人；想要中文 API 手册的人（官方文档更准）。
怎么读
| 目的 | 路线 | 时间 |
|---|---|---|
| 只做选型 | 1 → 3 → 4 | 半天 |
| 系统学架构 | 全书顺读，5–11 章跟着写 mini-dsh | — |
| 只要工程方法 | 1 → 19 → 20 → 21 | — |
| 搭内部平台 | 1、3、4 打底，跳 13、14、18 | — |
模型 API key 不是必需的，但有更好。 第 1、11、15 章的核心数据来自 DeepSeek 官方端点——端到端事件流、十变量的前缀缓存实验、六轮调用的真实用量轨迹，都带缓存命中数字。没有 key 也能跟着做：examples/mock-llm-server 把本机 claude CLI 包成 OpenAI 兼容端点，两条 patch 接上去。
目录
第一部分 它为什么长这样
第二部分 核心机制：亲手写一遍才懂
- 第 5 章 服务、注入与激活顺序
- 第 6 章 注册即可撤销
- 第 7 章 会话日志即真相
- 第 8 章 请求信封与流式协议
- 第 9 章 主循环：turn 与 step
- 第 10 章 三段瀑布、守卫与并发确定性
- 第 11 章 把 KV cache 写进架构契约
第三部分 组合与落地
第四部分 生产级子系统
第五部分 工程化与迁移
附录
配套代码
mini-dsh/ 手写的迷你实现，2,655 行 TS，65 个测试。零依赖，Node 22.6+ 直接跑
examples/ mock-llm-server：没有 API key 时把本机 claude CLI 包成 OpenAI 兼容端点
extensions/ 第 14 章那个真能装到 dsh 上的审计插件
assets/ 各章原始实测产物：dump 全文、会话日志、请求录制、实验数据、采集命令
跟着写 mini-dsh
八章各有两个 tag：
git checkout ch07-start # 起点：函数体挖空，签名、JSDoc、测试都在
cat mini-dsh/CHECKPOINT.md # 这一章要填哪几个函数
cd mini-dsh && node --test packages/session/tests/session.spec.ts # 绿了就是对了
git checkout ch07-done # 卡住了看参考答案
任何一章都能直接 checkout 开工，不需要前面的自己写对。可用 tag：ch05 ch06 ch07 ch08 ch09 ch10 ch12 ch13。
关于版本
本书写的是一个 0.1.0-rc 阶段的项目，官方 README 明写会有破坏性变更。
- 源码基准：
47f94385（2026-08-13，声明0.1.0-rc.5），所有行号引用以它为准 - 运行结果：npm 上的
0.1.0-rc.6。rc.5 从未发布，你装到的比能读到的源码新约一小时 - 每章 frontmatter 带
verified_against，标明核对版本与日期 - 易腐内容集中在第四部分；勘误见
ERRATA.md
取证纪律：书中每个数字都附有产生它的命令（汇总在附录 A）；每条「dsh 会 / 必须 / 强制 X」的断言都落到代码或门禁脚本，落不到的写成「文档如此描述」。凡是让 dsh 显得更强的论断，取证标准比让它显得更弱的高一档。
参考
- 源码：https://github.com/deepseek-ai/deepseek-harness
- 官方文档：仓库
docs/，含 7 课时 Cordis 教程与 9 篇中文开发者教程 - 反馈与勘误：本仓库 Issues
许可
正文 CC BY-NC-SA 4.0，代码 MIT。