源码研读指南 ChenYu1991ppak/deepseek-harness-anatomy

DeepSeek Harness (dsh) 源码研读教程

语言： | English

17 章。一次讲透一个机制。每一章都可运行。 拆解 DeepSeek Harness 的工程骨架——从“一条消息进、一条回复出”的最小 agent 循环，一路走到多 agent 委派、上下文压缩、人类协作与跨进程 RPC。

一套渐进式的源码研读文档：用 17 章，把 dsh 从“一条消息如何变成一条回复”的最小闭环，逐章搭建成“多 agent 委派 + 上下文压缩 + 人类协作 + 跨进程 RPC”的完整端到端形态。

快速开始（3 分钟）

git clone https://github.com/ChenYu1991ppak/deepseek-harness-anatomy.git
cd deepseek-harness-anatomy
python3 ch02/code/main.py

无需依赖、无需 API key——只用 Python 3 标准库。你会看到完整的一轮“一个问题进、一条回复出”：

ch02 运行演示

然后打开第 2 章，沿着路线图逐章把循环加厚：

章节路线图

适合谁读

- 你正在构建自己的 agent 框架，想参考 DeepSeek 的设计决策——接缝三重角色、事件流持久化、Cordis 插件容器，都按机制逐一讲清
- 你读过 dsh 源码但抓不住头绪——本教程提供一张 17 章的渐进式地图，并配有 file:line 源码引用
- 你是 Python 开发者，不想读 TypeScript 源码——每一章都有可运行的 Python 教学代码（仅用标准库）
- 你要讲授或撰写 agent 架构相关内容——每一章都是自包含模块，配有可运行 demo，可直接引用或改编

本教程是什么

DeepSeek Harness（命令 dsh）是 DeepSeek AI 开源的一个 agent harness——即模型之外的全部工程骨架：会话日志、工具执行、上下文压缩、子 agent 委派、权限守卫、持久化……它的核心理念是“一切皆插件”，底层由内置的 Cordis 框架驱动。

直接硬读这种规模的源码很难抓住头绪，所以本教程把它拆成一组渐进式章节：

- 17 个严格递进的章节：每一章都只在前一章基础上增加一个机制；每章结尾都会预告下一章，跨章依赖会明确标注“见第 X 章”；
- 每一章都配有可运行的 Python 教学代码：chNN/code/ 自包含且仅使用标准库；直接运行 python3 chNN/code/main.py——先复现输出，再读机制拆解；
- 机制层面的叙述，而非 API 使用层面：它解释“为什么要这样设计”；每一处教学简化都标记为 [teaching simplification]；每章末尾都有一张到真实源码的 file:line 映射表。

整个教程由源码拆解专家组（一个多角色 AI 协作框架）产出：架构师绘制地图，探索者逐章阅读源码产出素材，写作者撰写，审阅者逐章挑刺并修订。

阅读本教程你能获得什么

- agent harness 的完整心智模型：从“一条消息如何变成一条回复”的最小闭环出发，逐章加厚，最终形成多 agent 委派、上下文压缩、人类协作与跨进程 RPC 的端到端全景；
- 设计决策背后的“为什么”：机制层面的叙述——为什么“一切皆插件”，为什么接缝拆成三种角色，为什么持久化通过事件流完成；看到一流框架的设计思考，而不只是功能清单；
- 从概念到实现的落点：每个机制都配有可运行的教学代码（先复现输出，再阅读拆解）以及章末的 file:line 源码映射表；你随时可以回去对照真实源码验证；
- 统一的概念词汇表：术语命名表与每章的速查表统一了 seam、scope、compaction 等概念的命名，此后无论是读源码、查资料还是与人讨论，都不会再卡在术语上。

除了阅读，它还有什么用

1. 直接当作模板使用：每章的教学代码都是一个自包含、仅依赖标准库的最小 agent 框架——从 ch02 的最小闭环到 ch17 的端到端形态，拿去改造成你自己的玩具 agent 或内部工具骨架，无需从零搭建；
2. 构建你自己的 harness 时的设计参考：接缝三角色（定义/实现/消费）、事件流 + 持久化投影、scope、guard 流水线等模式，都可以直接借鉴到自己的项目中；
3. 概念速查手册：ch00/outline_en.md 中的术语命名表 + 每章附录的速查表 + 章末源码映射表，可以当作 agent 领域概念的词典，随时查阅。

dsh 概览
用一句话说：agent = model + harness。模型只产生"下一步"，harness 负责编排与副作用——会话日志、工具执行、作用域、持久化、守卫；一个运行中的 dsh 就是启动时逐层装配出来的 Cordis 插件树——模型适配器、工具注册表、会话日志、agent 循环本身都是插件，都可以通过配置替换。

最宏观的分层视图：

flowchart TB
ENTRY["入口层 · CLI / Web UI / SDK"]
COMPOSE["组装层 · bundle / preset / boot（按配置装配插件树）"]
CORE["核心骨架 · session 事件日志 / agent-loop / tools pipeline / system-prompt / scope"]
SEAMS["能力缝 · llm / subprocess / shell / fs / sandbox / subagent / skill / compaction …（换 provider，换行为）"]
KERNEL["Cordis 内核 · ctx / inject / effect / emit（一切皆插件，无特权内核）"]
ENTRY --> COMPOSE --> CORE --> SEAMS --> KERNEL

四条核心设计哲学贯穿全书：一切皆插件，无特权内核；agent = model + harness；注册即 effect（安装可逆、可回滚）；缝的三重角色（换一个 provider，换整套行为）。

章节导航

| 章节 | 主题 | 关键概念 |
| 0 | 全书渐进式大纲 | 术语命名表 |
| 1 | Cordis 容器内核 | 一切皆插件 |
| 2 | 最小 agent-loop 闭环 | 一条消息进，一条回复出 |
| 3 | 会话持久化 | 事件流、持久化投影 |
| 4 | tools 执行管线 | tools 注册、守卫执行 |
| 5 | 能力缝 | 定义/实现/消费三重角色 |
| 6 | 执行世界 | subprocess / shell / fs / sandbox |
| 7 | LLM 适配 | 适配器缝、流式输出 |
| 8 | system-prompt 与上下文 | 提示词装配、上下文注入 |
| 9 | scope 作用域注册 | 铸造/谱系/遮蔽/派发 |
| 10 | 上下文压缩 | compaction、token 压力 |
| 11 | subagent 委派 | 多种传输 provider |
| 12 | skill 加载 | 等级阶梯、分层遮蔽 |
| 13 | web 与 lsp 能力 | Web 检索、lsp 代码语义 |
| 14 | 交互与治理 | interaction / permission / goal / plan |
| 15 | 配置组合 | preset / bundle / profile |
| 16 | 跨进程 RPC | typert / api / sdk |
| 17 | 工作流与端到端 | workflow / Ralph loop、端到端链路 |

第 1–2 章由原 s01 拆分而来（原 s01 同时承载“容器内核”与“agent-loop 闭环”两个机制簇）；第 3–17 章对应旧第 2–16 章，章号整体后移一位；旧稿已清理，按 ch00/outline_en.md 逐章重写。

推荐阅读顺序

1. 先读地图：ch00/outline_en.md 给出 17 章的递进弧线与术语命名表——建立全局心智模型。
2. 按序逐章阅读：ch01 → ch17，严格递进——每章开篇承接上一章新增的机制，结尾预告下一章；跨章依赖均标注“见第 X 章”。不建议跳章。
3. 边读边跑：每章教学代码位于 chNN/code/（ch02–ch17 经 main.py 进入；ch01 经 hello.py 进入），python3 chNN/code/main.py 可直接运行；先复现章末“完整运行输出”，再读机制拆解。

配套文件

| 文件 | 用途 |
| ch00/ | 大纲目录：outline_en.md 为 17 章递进大纲（主题 / 新增机制 / 源码模块 / 前置章节）+ 术语命名表；outline_zh.md 为对应中文版 |
| ch01/ … ch17/ | 每章一个目录：chNN-_en.md 为该章最终正文（题记 / 本章回答的问题 / 正文 / 完整运行输出 / 源码映射 / 小结与预告 / 附录速查表），chNN-_zh.md 为对应中文版，code/ 为该章可运行的 Python 教学代码（按章增量累积） |

架构对比

dsh 与其他 agent 框架的对比

| 维度 | DeepSeek Harness (dsh) | LangChain | CrewAI | AutoGen |
| 理念 | 一切皆插件 | 链式组合 | 角色化 agent | 多 agent 对话 |
| 核心容器 | Cordis（插件内核） | 无内核 | 无内核 | 无内核 |
| 接缝/可替换性 | 三重角色（def/provider/consumer） | 组件 | 有限 | 有限 |
| Agent 循环 | 内置 react loop | 自定义链 | 内置 | 内置 |
| 上下文压缩 | 内置（阈值触发） | 外部 | 外部 | 外部 |
| 会话持久化 | 仅追加事件日志 + 投影 | 手动 | 有限 | 有限 |
| Token 计量 | 真实 provider 返回 usage | 估算 | 估算 | 估算 |
| 插件隔离 | 作用域分层（按 agent） | 无 | 无 | 无 |
| 跨进程 RPC | 内置（Ralph/ACP） | 否 | 否 | 否 |
| 学习曲线 | 陡峭（功能全面） | 高（抽象众多） | 中等 | 中等 |
| 最适合 | 生产级智能体系统 | 快速原型开发 | 基于角色的任务 | 研究实验 |

为什么本教程聚焦于 dsh

dsh 在智能体框架中独树一帜，因为它拥有一个真正的插件内核（Cordis），而非一组组件库。这意味着每一项能力——模型调用、工具执行、会话日志、压缩——都是一个插件，可以替换、组合和限定作用域。理解这一架构能为你提供一个超越 dsh 的思维模型：它与 VS Code、Kubernetes 控制器和 webpack 使用的是同一种模式。

本教程是唯一一份逐机制解构 dsh 的资源，从最小智能体循环到完整的端到端系统。配套的 pydsh 项目提供了同一架构的可运行 Python 实现。