DeepSeek Harness 源码教程（dsh-tutorials）

面向「想真正搞懂并扩展 DeepSeek Harness（dsh）」的工程师与教学者的循序渐进课程。 撰写基线：deepseek-harness/ 仓库快照，2026-08-28。共 13 课，分四个阶段，每课包含：目标 → 问题引入 → 源码走读 → 动手环节 → 自检清单 → 延伸阅读。

三份材料的分工

材料	角色	什么时候用
本教程（deepseek-harness-tutorials/）	教学路径：按顺序学，先现象后机制，每课有练习和自检	第一次学习、给别人上课
源码剖析维基（deepseek-harness-wiki/）	机制参考：按主题组织的深度剖析（含文件:行号定位）	学到某课时深入展开、事后查阅
仓库内文档（deepseek-harness/docs/）	权威契约：architecture、glossary、cordis-tutorial、cookbook、postmortem	写代码时核对约定与操作步骤

维基回答「机制是什么、为什么这样设计」；本教程回答「按什么顺序学、每一步做什么、怎么确认学会了」。

受众与准备

• 前置能力：TypeScript 基础（interface / 泛型 / async 迭代器）、Node.js 命令行、pnpm 基本用法。
• 环境：Node ^22.19 || >=24、pnpm、克隆 deepseek-harness/ 仓库。
• API Key 说明：DEEPSEEK_API_KEY 只在少数环节需要（headless 跑真实任务、录制快照）。没有 key 也能学完全部 13 课——无 key 回放快照（test:snapshot）、--dump-config 检查组合树、单元测试与源码走读均不需要 key。
• 源码走读统一从 deepseek-harness/ 仓库根开始，行号引用（如 vendor/cordis/src/context.ts:71-84）来自维基，可能随代码演进漂移；若对不上，以当前代码为准并用符号名搜索。

学习路线图

 阶段一 上手与骨架          阶段二 核心主干             阶段三 扩展模型            阶段四 专题与收束
┌──────────────────┐  ┌──────────────────────┐  ┌────────────────────┐  ┌──────────────────────┐
│ 01 跑起来与观察    │  │ 04 一次 Turn 的旅程   │  │ 08 能力接缝三角色    │  │ 11 自扩展（skill/     │
│ 02 Cordis 20 分钟 │→ │ 05 会话日志与不变量    │→ │ 09 工具管线与安全    │→ │    extensions）       │
│ 03 五种事件分发    │  │ 06 持久层与日志化状态  │  │ 10 实战：第一个插件  │  │ 12 Web 客户端         │
│                  │  │ 07 Profile 与 Bundle  │  │    （毕业项目）      │  │ 13 工程文化与收束      │
└──────────────────┘  └──────────────────────┘  └────────────────────┘  └──────────────────────┘
   「它怎么跑起来」        「一个回合如何发生」        「如何替换与扩展它」         「它如何管住自己」

• 阶段一建立骨架心智：一切皆插件（Cordis）、五种事件分发。不碰业务包。
• 阶段二走通主干：一次 Turn 从输入到收尾的完整事件流、会话日志的三层不变量、部署组合方式。
• 阶段三进入扩展者视角：能力接缝三角色、工具执行四道关卡，最后亲手写一个完整插件（毕业项目）。
• 阶段四是选修与收束：自扩展、Web 客户端可以按需跳读；第 13 课建议所有人完成，它把全课程收束为「可机器执行的正确性」这一条主线。

课程表

课	文件	主题	产出（学完你能…）
01	01-run-and-observe.md	三种运行形态与观察窗口	不读一行源码，先看懂 dsh 在哪运行、在哪留下痕迹
02	02-cordis-in-twenty-minutes.md	一切皆插件：Cordis 骨架	写出带 inject 依赖的插件，解释 epoch 加载顺序
03	03-event-dispatch-modes.md	五种事件分发模式	为一个需求选对分发模式，写合规的 waterfall 监听器
04	04-turn-execution-flow.md	一次 Turn 的完整旅程	从快照日志反推一次 Turn 的事件序列与拦截点
05	05-session-event-log.md	会话日志与「模型可见 ⟺ 已记录」	解释三层强制，判断一个新输入需要什么事件
06	06-persistence-and-logged-state.md	持久层、投影与日志化状态	说明 plan/goal/todo 为何没有状态机
07	07-profile-and-bundle.md	Profile 与 Bundle 组合	手写一个自定义 profile 并读懂组合树来源
08	08-capability-seam.md	能力接缝：三角色与两种形态	对任意能力域填出三角色表，预测切换 Provider 的爆炸半径
09	09-tool-pipeline-and-safety.md	工具执行管线与安全三旋钮	画出工具调用从 pre-execute 到结果入日志的完整关卡图
10	10-capstone-first-plugin.md	毕业项目：写一个完整插件	拥有一个装进 profile、可验证、有决策记录的插件
11	11-self-extension.md	自扩展：skill 与 extensions	解释模型如何在运行时检视并挂载新插件，以及边界在哪
12	12-web-client.md	Web 客户端：Slots 与模块图	说明浏览器侧为什么是「另一个 Cordis 世界」
13	13-engineering-culture.md	工程文化与门禁	用维护者的视角解释「正确如何变成机器可执行」

如何用它教别人

• 节奏：每课 45–90 分钟。阶段一适合一次讲完（约半天）；阶段二每课独立，可拆多次；第 10 课毕业项目预留 2–3 小时。
• 顺序即依赖：除 11 / 12 可互换、可跳过外，其余课程按编号顺序学。每课「前置」栏标注了硬依赖。
• 先现象后机制：每课先完成「动手环节」里的观察类任务（看现象），再读源码，最后用「自检清单」验收。教人时把自检问题当随堂提问。
• 实物驱动：所有课程都能在无 key 环境完成观察类练习；讲到具体行为时优先展示快照回放（pnpm run test:snapshot）与 --dump-config，而不是口头描述。
• 纠偏材料：课程里标注「常见误解」的地方（如仓库没有组合入口型 cordis.yml、packages/core 实为 8 个包、循环依赖静默挂起是设计语义），来自维基对源码的核实，讲课时值得专门强调。

约定

• 路径与行号形如 packages/core/session/src/index.ts:424，均相对 deepseek-harness/ 仓库根。
• 指向维基的链接形如 ../deepseek-harness-wiki/concepts/xxx.md；指向仓库文档的形如 ../deepseek-harness/docs/xxx.md。
• 「伪代码」指维基根据真实源码简化的片段，用于讲解结构，不能直接运行。