前言
一个改不动的需求
去年我给团队搭内部 agent 平台，接的是 Claude Code。第一个需求很小：agent 每次改完文件，把 diff 发到群里。
做法是写一个 PostToolUse hook：配一段 JSON，启一个子进程，从 stdin 读一坨数据，解析、判断、发出去。功能跑通了，但我想改的是「工具执行完之后」这个环节本身，实际能做的只是在它旁边挂一个进程。
后面的需求一个比一个难：换掉默认的上下文压缩策略，让工具执行走公司的隔离沙箱，在对话界面里插一张自己的卡片，把审批接到内部的审批系统。这些都要动主路径，而主路径是产品的内部实现，不对外开放。我在 OpenClaw、Codex 和几个开源 harness 之间来回选型，情况都一样：能扩展的只有对方预留的那几个扩展点。
2026 年 8 月 13 日，DeepSeek 开源了 DeepSeek Harness（命令行叫 dsh），slogan 是 Everything is a Plugin。我装上跑了一个任务，然后执行：
dsh --profile web --dump-config它打印出这台机器上将要启动的整棵插件树，当时是 490 行。模型适配器是一行，会话日志是一行，往下翻，主循环 agent-loop 也是一行。其中任意一行，都可以用我自己写的几行 YAML 覆盖。
这本书讲的就是这棵树：它怎么拼起来，为什么这样设计，要付什么代价，以及怎么把同样的做法搬进自己的项目。
写给谁
主要写给三类读者。
在公司里搭 agent 平台的人。你要交付的是一个让一群工程师能扩展、能审计、能控成本的底座。第 4 章给出做采用决策要用到的事实，第 13、14、18 章的内容可以直接改写成设计文档和 PR。
已经在用 Claude Code 或 Codex、想给它加功能却只能挂 hook 的工程师。全书技术栈是 TypeScript / Node。
从传统后端转 AI 的工程师。第 2 章做概念对齐，附录 D 补 TypeScript 的语言特性，正文的类比尽量落在 Servlet Filter、Spring 容器、Kustomize、Git 这些你熟悉的东西上。入门铺垫都放在可以跳过的位置，主线不为它放慢。
不适合的读者：想找用 AI 写代码技巧的；想要中文 API 手册的（官方文档有 110 篇英文和 105 篇中文，比任何转述都准）；只想抄现成配置、对软件架构本身没兴趣的。
覆盖范围
正文做四件事，都是官方文档没有覆盖的。
- 设计取舍。DeepSeek 选了「没有内核」，放弃了什么？「日志是唯一真相源」这条规矩，开发时由谁付账？第 3 章逐条讲六个取舍：得到什么、放弃什么、怎么补偿、以后会不会变。
- 横向对比。dsh 和 Claude Code、Codex、OpenClaw 的差别在哪；它和 LangGraph 这类编排框架为什么不在同一个抽象层。
- 源码走读加手写重建。全书带你用 TypeScript 写一个能跑的迷你实现
mini-dsh，约 2,700 行（含测试），只用来帮助理解，不当产品用。亲手写过 fiber 的激活顺序和 disposer 的回滚，再回看第 3 章的取舍会具体得多。 - 工程方法。dsh 是一个由人和 agent 共同维护的 50 万行代码库，有一套成文的工程约束和门禁脚本。第 19 到 21 章把它拆开，判断哪些值得照搬，并按团队规模给出裁剪方案。
不覆盖的内容：
- API 手册。配置字段、事件签名、工具参数一律指向官方生成的 catalog，书里只写不随版本变的那一层。
- 用 dsh 提高编码效率的技巧。
- 模型训练、推理优化、prompt 技巧。
怎么读
- 只做选型（半天）：第 1、3、4 章。读完能回答「该不该上、上了要写多少代码、锁定风险多大」。
- 系统学架构：全书顺读，第 5 到 13 章跟着写 mini-dsh。配套仓库给第 5 到 10 章和第 12、13 章各打了两个 tag：
chNN-start是挖好 TODO 的骨架，chNN-done是完整实现。任何一章都能直接 checkout 开工，不必先把前面写对；第 5 到 8 章还能跑pnpm verify:chNN自检。mini-dsh 一行不写也没关系，第 12、14、18 到 21 章照样能读。 - 只要工程方法：第 1、19、20、21 章。这几章不依赖前面的机制细节。
- 想搭内部平台：第 1、3、4 章打底，然后跳到第 13、14、18 章。
准备什么
Node.js 22.19+ 或 24+，一个能跑 npm install 的环境。dsh 依赖 node-pty，安装时要编译，老发行版可能遇到编译器版本问题，解法在第 1 章 1.1 节。
模型 API key 不是必需的。第 1、11、15 章的核心数据来自 DeepSeek 官方端点：一次端到端任务的完整事件流、十个变量的前缀缓存实验、一次六轮调用的用量轨迹，缓存命中数字都是服务端真实返回的。
没有 key，可以用配套仓库里的 examples/mock-llm-server。它把本机的 claude CLI 包装成 OpenAI 兼容端点，写两条 patch 就能接上（第 1 章 1.5 节）。用它跑出的结果，正文都标了 via mock：模型行为不代表 DeepSeek，缓存数字不采信。
沙箱实验有平台限制：Landlock 和 bubblewrap 只在 Linux 上有，Seatbelt 只在 macOS 上有，Windows 走 ACL 受限令牌。第 13 章标明了每个实验能在哪些系统上跑。
版本与时效
dsh 仍处在 rc 阶段。官方 README 用全大写写着 THERE WILL BE COMPATIBILITY-BREAKING CHANGES；仓库的 AGENTS.md 有一节注明「首个正式 release 时删掉本节：目前没有外部消费者，宁可重命名、重打包也不加兼容垫片」。
本书正文写于 2026 年 8 月：
- 源码锁定 commit
47f94385（2026-08-13，声明版本0.1.0-rc.5），所有行号以它为准。 - 运行结果基于当时 npm 上的
0.1.0-rc.6。 - 每章 frontmatter 的
verified_against字段记录了该章核对的版本和日期。
到 2026 年 10 月 28 日，npm 上的 latest 已经是 0.2.1-rc.2。我按这个版本重跑了第 1 章：主循环是配置里的一行、模型可见的内容必须落进日志、patch 按 id 整体替换、bundle 逐层叠加，这些结论都没变；变的是数字和细节，插件行从 129 涨到 190，默认模型、遥测默认值、Web 端的登录方式都改了，第 1 章正文已经更新。其他章节还没有逐章复核，读的时候以各章的 verified_against 为准，新旧两版的对照数据见 assets/ch01/environment.md。
几条读这本书时要记住的事：
- 部分包在 npm 上掉队。
subagent-claude-code、subagent-codex、tool-cordis的latest标签到 10 月底仍停在0.0.1-rc.1，新版本只发在next和alpha标签上，默认的npm i装到的还是旧版（rc.6 时期的冲突实测见第 4 章 4.4 节、第 16 章 16.2 节；@next能否装上，本书没有重测）。源码里有的能力，npm 上不一定装得到，动手前先自己跑一遍。 - 最容易过时的是第四部分（第 15 到 17 章）。这三章讲的子系统实现最具体，也最可能被重做。第一到三部分和第五部分讲事件模型、接缝模型、日志即真相、配置合成规则和工程方法，变动的概率小得多。
- 勘误维护在仓库的
ERRATA.md。
取证纪律
本书的每个数字都附有产生它的命令，汇总在附录 A。每条「dsh 会 / 必须 / 强制 X」的断言都落到代码或门禁脚本上，落不到的写成「文档如此描述」。让 dsh 显得更强的论断，取证标准比让它显得更弱的高一档。后面几章说的「取证纪律」就是指这三条。
定这几条是因为吃过亏。第一轮调研时我统计了五个数字：Agent Notes 的篇数、文档篇数、内核本地修改条数、约束规则条数、生成器的校验能力。五个全错，而且都往「更宏大、更自动化、更严格」的方向偏。比如 Agent Notes 我数出 1,372 篇，实际是 688 篇：每篇都有中英两份文件，我把文件数当成了篇数。原因是我当时靠读文档和数文件取证，dsh 的文档写得好，我就把它的自我描述当成了一手事实。
配套资源
- 配套仓库：
https://github.com/diguike/book-deepseek-harnessmini-dsh/：手写的迷你实现，带各章 tagexamples/：各章可独立运行的片段，含mock-llm-serverextensions/：第 14 章插件的完整工程assets/：各章的原始实测产物，包括 dump 全文、会话日志、请求录制
- 参考源码：
https://github.com/deepseek-ai/deepseek-harness@47f94385 - 官方文档：仓库
docs/目录，含 7 课时的 Cordis 教程和 9 篇中文开发者教程。 - 勘误与反馈：配套仓库 Issues。
本书前言来自《一切皆插件》开源版 · 作者「递归客」
在线阅读完整书系：inferloop.dev
源码仓库：github.com/diguike/book-deepseek-harness