前言

一个改不动的需求

去年我给团队搭内部 agent 平台，接的是 Claude Code。第一个需求很小：每次 agent 改完文件，把 diff 发到群里。

做法是写一个 PostToolUse hook。配一段 JSON，启一个子进程，从 stdin 读一坨数据，解析，判断，发出去。跑通了，但从那天起我一直在跟同一件事较劲——我想改的是「工具执行完之后」这个环节，可我碰不到它，只能在它旁边挂一个进程。

后面的需求一个比一个难：换掉默认的上下文压缩策略，让工具执行走公司的隔离沙箱，在对话界面里插一张自己的卡片，把审批接到内部的审批系统。这些都不是挂个 hook 能办的。它们要动主路径，而主路径是产品的内部实现，不对外。

我在 OpenClaw、Codex、几个开源 harness 之间来回选型，结论都差不多：你能扩展的，是人家预留给你的那几个洞。

2026 年 8 月 13 日，DeepSeek 开源了 DeepSeek Harness。它的 slogan 只有三个词：Everything is a Plugin。

我装上跑了一个任务，然后执行了一条命令：

dsh --profile web --dump-config

它打印出这台机器上将要启动的整棵插件树，490 行。模型适配器是一行，会话日志是一行，agent 是一行。往下翻，主循环——agent-loop——也是一行。

任意一行，都能被我自己的一行 YAML 顶掉。

这本书就是从这条命令开始的。

这本书写给谁

第一优先：在公司里搭 agent 平台的人。 你要做的不是「用好一个 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 篇中文，比任何翻译都准）；对软件架构本身不感兴趣、只想拿现成配置抄的人。

这本书讲什么，不讲什么

讲四件事，都是官方文档不做的：

1. 设计取舍与代价。 DeepSeek 选了「没有内核」，放弃了什么？「日志是唯一真相源」这条规矩，开发时谁在为它付账？第 3 章逐条摊开六个取舍，每条都写清楚得到什么、放弃什么、怎么补偿、这条会不会变。
2. 横向对比与选型判断。 dsh 和 Claude Code、Codex、OpenClaw 的分野在哪，和 LangGraph 这类编排框架压根不在一个抽象层上。官方永远不会写这部分。
3. 源码走读加亲手重建。 全书带你用 TypeScript 写一个能跑的迷你实现 mini-dsh，约 3500 行。它不是产品，是理解工具——只有亲手写过 fiber 的激活顺序和 disposer 的回滚，第 3 章那六个取舍才会从道理变成体感。
4. 方法论提炼成能搬走的清单。 dsh 是一个人和 agent 共同维护的 50 万行代码库，它的工程约束体系是目前能找到的最完整的公开样本。第 19 到 21 章负责把它拆开、判断哪些能抄、按团队规模给出裁剪方案。

不讲：

• 不做 API 手册。配置字段、事件签名、工具参数一律指向官方生成的 catalog，书里只写不会变的那一层。
• 不讲怎么用 dsh 提高编码效率。这是一本讲它怎么造的书，不是使用手册。
• 不讲模型训练、推理优化、prompt 技巧。

怎么读

只做选型（半天）：第 1 章 → 第 3 章 → 第 4 章。读完能开选型会，能回答「我们该不该上、上了要写多少代码、锁定风险多大」。

系统学架构（跟着写 mini-dsh）：全书顺读，第 5 到 11 章跟着敲代码。配套仓库每章有 chNN-start 和 chNN-done 两个 tag，任何一章都能直接 checkout 开工，不需要前面全部自己写对；每章挖好 TODO 骨架，跑 pnpm verify:chNN 自检。哪怕 mini-dsh 你一行不写，第 12、14、18、19、20、21 章仍然完整可用。

只要工程方法：第 1 章 → 第 19 章 → 第 20 章 → 第 21 章。这四章不依赖前面的任何机制细节。

想搭内部平台：第 1、3、4 章打底，然后直接跳第 13、14、18 章。

你需要准备什么

Node.js 22.19+ 或 24+，一个能跑 npm install 的环境。dsh 依赖 node-pty，要编译，老发行版可能撞到编译器版本问题——第 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 章会标清楚哪些实验在你的系统上跑得起来。

关于时效，把话说在前面

这本书写的是一个 0.1.0-rc 阶段的项目。官方 README 里那句话是全大写的：THERE WILL BE COMPATIBILITY-BREAKING CHANGES. 仓库的 AGENTS.md 里还有一节写着「首个正式 release 时删掉本节：目前没有外部消费者，宁可重命名、重打包也不加兼容垫片」。

所以：

• 全书锁定 commit 47f94385（2026-08-13，声明版本 0.1.0-rc.5）。所有源码行号引用以它为准。
• 运行结果基于 npm 上的 0.1.0-rc.6。rc.5 从未发布到 npm，你装到的比你能读到的源码新约一小时。
• 有些包在 npm 上掉队了。subagent-claude-code、subagent-codex、tool-cordis 这几个发布的版本停在 0.0.1-rc.1，和当前内核 peer 冲突、装不上（第 4 章 4.4、第 16 章 16.2 有实测）。你在源码里读到的能力，不等于你在 npm 上能装到的能力——这是 rc 阶段的典型症状，也是本书反复强调”自己先跑一遍”的原因。
• 每章 frontmatter 带 verified_against，标明该章内容核对于哪个版本、哪一天。
• 易腐内容集中在第四部分（第 15 到 17 章）。那三章讲的是实现细节最具体、最可能被重做的子系统。第一到三部分和第五部分写的是不变量层——事件模型、接缝模型、日志即真相、配置合成规则、工程方法，这些不会跟着 rc 版本号变。
• 勘误维护在仓库的 ERRATA.md。

还有一条自我约束，写在这里供你监督——后面几章会直接管它叫取证纪律：这本书里每一个数字，都附有产生它的那条命令（汇总在附录 A）；每一条「dsh 会 / 必须 / 强制 X」的断言，取证都落到代码或门禁脚本，落不到的一律写成「文档如此描述」。凡是让 dsh 显得更强的论断，取证标准比让它显得更弱的高一档。

这条规矩是有来历的。我做第一轮调研时统计过五个数字——Agent Notes 的篇数、文档篇数、内核本地修改条数、约束规则条数、生成器的校验能力——五个全错，而且错的方向完全一致：都往「更宏大、更自动化、更严格」偏。 根因是我在「读文档 + 数文件」，而 dsh 的文档质量高到会让人放松警惕，于是它的自我描述被我当成一手事实转述了。

配套资源

• 配套仓库：https://github.com/diguike/book-deepseek-harness
  • mini-dsh/ 手写的迷你实现，每章双 tag
  • examples/ 各章可独立运行的片段，含 mock-llm-server
  • extensions/ 第 14 章那个真发布到 npm 的插件
  • assets/ 各章原始实测产物：dump 全文、会话日志、请求录制
• 参考源码：https://github.com/deepseek-ai/deepseek-harness @ 47f94385
• 官方文档：仓库 docs/ 目录，含 7 课时的 Cordis 教程和 9 篇中文开发者教程。这本书和它们的分工写在每个部分的开头。
• 勘误与反馈：配套仓库 Issues。

一句话

如果你正卡在「我想改的那个环节碰不到」这件事上，这本书讲的是另一种可能：把每一个环节都做成一行配置，包括主循环本身。

代价是什么，第 3 章会算清楚。

本书前言来自《一切皆插件》开源版 · 作者「递归客」
在线阅读完整书系：inferloop.dev
源码仓库：github.com/diguike/book-deepseek-harness