DeepSeek Harness 学习手册 11 章 单页全本 架构图 分析报告 GitHub
Learning Notes · 2026

DeepSeek Harness 学习手册
没有内核的 harness

dsh 的架构文档第一句话就把自己讲完了:没有可打补丁的特权核心。 模型适配器、工具注册表、会话日志、连 agent 循环本身都是插件——一个运行中的 dsh, 只是启动时按顺序组合出来的一棵插件树。 这份手册把官方文档与仓库源码交叉对齐,回答一个问题: 「万物皆插件」到底换来了什么,又要付什么账。

repo deepseek-ai/deepseek-harness commit 22ddee3 license MIT packages 363 + 5 apps TS/TSX ~111 万行(含测试) 架构图 + 时序图 已校验

前置提醒:README 第 13 行写着 "THERE WILL BE COMPATIBILITY-BREAKING CHANGES", 第 15 行要求你先读 SAFETY.md。这不是免责声明套话,是理解它设计取舍的前提(见 第 07 章)。

00

十一章:从插件树到第一个插件

推荐顺序从 01 开始——后面的章节会反复用到「插件树」「三个事件域」「seam」这几个概念。 每章页脚有上一章 / 下一章,左侧有本章目录。

01
心智模型:没有特权核心
先换掉「有一个主程序」的直觉:插件的最小形态只有两个导出,注册是可逆副作用。
6 min · 三个事件域的分诊口诀
02
设计哲学:可替换,而不是删减
Cordis 的五个想法、五种派发模式、waterfall 语义,以及「范式税」由谁付。
10 min · 与 pi 的路线对照
03
架构图:14 个零件,16 条连接
可交互运行时架构图,配读图指南、四个画图判断与组件证据表。
12 min · 内嵌图 + 可全屏
04
一次提问:turn 与 step 的契约
文档原文的 20 行流程逐字引用,以及五个与直觉不同的地方。
10 min · 时序图 + 权威流程
05
五个机制
事件域三分、waterfall(含仓库真实代码)、seam 三角色、工具管线、共享执行世界。
15 min · 6 个 seam 证据表
06
会话与持久化:日志即真相
「Model-visible means logged」、投影 seam、代际迁移链的五条规则、中断的尾巴。
12 min · 格式代际表
07
刻意不做:四条「不承诺」
不承诺稳定、不承诺安全隔离、不定义「官方界面」、不替你选配置——每条都配原文。
8 min · SAFETY.md 原文
08
扩展与集成:三层组合 + 20 个扩展点
profile / bundle / patch 的层序,完整译出的 20 行「目标 → 机制」表,以及三条外部通道。
12 min · 20 行清单
09
与 pi 的对照,以及一个不对称事实
规模差 2.3–2.7×、内核差 5.7–7.1×(两种口径);以及 dsh 把 pi 的模型层当成自己的一个适配器在用。
8 min · 代码级证据
10
动手:从跑起来到写第一个插件
三种启动方式、读懂 --dump-config、写 hello 插件并 patch 进去、六条自检清单。
20–40 min · 命令可复制
11
延伸阅读:按问题读
六条最短路径、按角色的四条路线、百科式入口、外部链接。
3 min · 全部链接
◈

三条路线,看你有多少时间

路线 A · 30 分钟
01 心智模型 → 03 架构图 → 07 刻意不做。
目标:能说清「没有特权核心」意味着什么,以及它明确不承诺什么。
路线 B · 60 分钟
02 设计哲学 → 04 一次提问 → 05 五个机制 → 06 会话。
目标:理解一个 turn 的全链路,以及为什么「日志先于请求」。
路线 C · 半天
全部十一章 + 10 动手练习。
目标:能新建一个 profile、用 patch 覆盖任意一行、写出一个带 inject 的插件。
◇

这份材料的几个入口

同一份内容有不同形态,按场合选:

分章阅读(本页)——每章一页,左侧章节导航 + 本章目录,适合逐步学习。

深入理解 dsh · 机制层 6 章——这一本往下挖一层,只讲一件件事在代码里到底怎么发生:一个 turn 穿过哪几层派发、压缩先做什么后做什么、崩溃后补出来的那几个事件长什么样。同样每条带源码行号。

单页全本——全部内容在一页里,适合 ⌘F 全局搜索、打印或整页分享(仍是单文件,无外部依赖)。

两张图——运行时架构图(14 组件 / 16 连接 / 5 卡片)与 单轮时序图(8 参与者 / 14 消息 / 4 片段),由 Archify v3.2 生成, validate 与 finalize --browser-check 全部通过。

读书指南——把开源书《深入理解 AI Agent》的 Harness 五要素与五个设计模式,落成 pi 与 dsh 的体检表(每条判断都带源码证据)。

分析报告——图之外的结构性结论、规模事实、复现方法,以及本轮没做的事。

事实基准:仓库 commit 22ddee3(2026-10-23)。 所有源码断言都给出 GitHub blob 永久链接(带行号),行号在写入前逐条核对。 与 pi 的对比数据(第 09 章)来自两侧同一口径的实测,不是估算。