围绕 DeepSeek 开源的 Agent Harness（代号 dsh），我写了八篇源码解读和十三课配套课程。但想真正搞懂这个项目，光读文章不够——这一页是路线图，说清楚每份材料管什么、按什么顺序读。
两份材料的分工
文章和课程写自同一份源码快照，差别在组织方式：文章按主题一篇讲透一个机制，课程按顺序带你学。
| 材料 | 角色 | 什么时候用 |
|---|---|---|
| 本系列文章（本站） | 主题式源码解读，一篇讲透一个机制 | 想深入理解某个设计，或离开终端阅读 |
| 13 课课程 | 循序渐进的教学路径：目标→走读→动手→自检 | 第一次系统学、边学边练 |
文章回答「机制是什么、为什么这样设计」，课程回答「按什么顺序学、怎么确认学会了」。另有一份按条目组织的源码剖析维基（带文件与行号锚点），未在本站发布；课程中引用处用《》标注。
系列文章目录
- 一、一切皆插件：读 DeepSeek Harness 的架构——Cordis 框架、Profile/Bundle 分层，和几条明文规则。
- 二、模型看到的必须在日志里：dsh 的 Turn 执行流——两个事件平面、waterfall 拦截，和一条核心不变量。
- 三、Capability Seam：让 shell、文件系统和沙箱都可替换——三角色接缝、三层沙箱和 fail-closed 的审批。
- 四、逐文件 100% 覆盖：dsh 的质量门禁长什么样——44 个 verify 脚本、无 key 录制回放和决策记录。
- 五、压缩也是日志：dsh 的 Compaction 设计——压缩动作自己进日志，日志锁让崩溃可检测。
- 六、崩溃的 turn 要关闭，不是截断：dsh 的会话持久化——双后端、合成的关闭事件，和从日志派生的一切。
- 七、状态就是日志：plan、todo、goal 在 dsh 里怎么存——日志化状态的三种深度。
- 八、声明即授权：dsh Web 客户端的 slot 体系——浏览器侧的渲染授权与模块图。
十三课课程与配套文章
课程已按课序发布在本站，共 13 课、四个阶段：骨架（01–03）→ 主干（04–07）→ 扩展（08–10）→ 专题与收束（11–13）。每课与本站文章的对应关系如下：
| 课 | 主题 | 配套文章 |
|---|---|---|
| 01 | 三种运行形态与观察窗口 | 一（各运行形态一节） |
| 02 | 一切皆插件：Cordis 骨架 | 一（Cordis 一节） |
| 03 | 五种事件分发模式 | 一列了五种模式 · 二深讲 waterfall |
| 04 | 一次 Turn 的完整旅程 | 二 |
| 05 | 会话日志与「模型可见 ⟺ 已记录」 | 二 · 五 |
| 06 | 持久层与日志化状态 | 六 · 七 |
| 07 | Profile 与 Bundle 组合 | 一（Profile + Bundle 一节） |
| 08 | 能力接缝三角色 | 三 |
| 09 | 工具管线与安全三旋钮 | 三讲了沙箱与审批；管线专文待补 |
| 10 | 毕业项目：第一个插件 | 暂无（动手项目） |
| 11 | 自扩展：skill 与 extensions | 暂无 |
| 12 | Web 客户端：Slots 与模块图 | 八 |
| 13 | 工程文化与门禁 | 四 |
注：第五篇是第 05 课那条不变量的延伸案例——压缩改写可见内容，自己也被记录。第 09 课的管线专文、第 10 和 11 课的文章还在补；标「暂无」的课以课程为主材料。
两条学习路线
- 只读不练：按一到八的顺序读文章，不需要仓库和环境，拿到设计层面的全景。
- 边学边练：克隆
deepseek-harness/，从第 01 课按课程顺序走，每课对照上表的配套文章深读。没有 API key 也能学完全部 13 课——快照回放、--dump-config、单元测试和源码走读都不需要。
文章与课程的撰写基线都是 deepseek-harness/ 仓库的 2026-08-28 快照。项目处于 developer preview，迭代很快；描述与当前源码对不上时，以代码为准。