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，可直接引用或改编

flowchart LR
subgraph S1["基础"]
direction LR
C01["1 · Cordis 内核"] --> C02["2 · 最小 agent-loop"] --> C03["3 · 会话持久化"]
end
subgraph S2["能力构建"]
direction LR
C04["4 · 工具流水线"] --> C05["5 · 能力接缝"] --> C06["6 · 执行世界"] --> C07["7 · LLM 适配"] --> C08["8 · system-prompt"]
end
subgraph S3["进阶机制"]
direction LR
C09["9 · scope"] --> C10["10 · 压缩"] --> C11["11 · subagent"] --> C12["12 · skill"]
end
subgraph S4["治理与组合"]
direction LR
C13["13 · web & lsp"] --> C14["14 · 交互与权限"] --> C15["15 · preset / bundle"]
end
subgraph S5["端到端"]
direction LR
C16["16 · 跨进程 RPC"] --> C17["17 · 工作流 e2e"]
end
S1 --> S2 --> S3 --> S4 --> S5

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

直接阅读这种规模的源代码很难抓住头绪，因此本教程将其拆解为一组渐进式章节：

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

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

阅读本教程你能获得什么

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

除了阅读之外，它还有哪些用途
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 event log / 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 注册、guard 执行 |
| 5 | 能力接缝 | 定义/实现/消费三重角色 |
| 6 | 执行世界 | subprocess / shell / fs / sandbox |
| 7 | LLM 适配 | Adapter 接缝、流式输出 |
| 8 | system-prompt 与上下文 | Prompt 组装、上下文注入 |
| 9 | scope 作用域注册 | Minting/lineage/shadowing/dispatch |
| 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 循环、端到端链路 |

第 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 |
|---|---|---|---|---|
| 理念 | 一切皆插件 | 链式组合 | 基于角色的智能体 | 多智能体对话 |
| 核心容器 | Cordis（插件内核） | 无内核 | 无内核 | 无内核 |
| 接缝/可替换性 | 三重角色（定义/提供/消费） | 组件 | 有限 | 有限 |
| 智能体循环 | 内置 react 循环 | 自定义链 | 内置 | 内置 |
| 上下文压缩 | 内置（阈值触发） | 外部 | 外部 | 外部 |
| 会话持久化 | 仅追加事件日志 + 投影 | 手动 | 有限 | 有限 |
| Token 计量 | 真实提供商返回的用量 | 估算 | 估算 | 估算 |
| 插件隔离 | 作用域分层（按智能体） | 无 | 无 | 无 |
| 跨进程 RPC | 内置（Ralph/ACP） | 无 | 无 | 无 |
| 学习曲线 | 陡峭（功能完备） | 高（抽象众多） | 中等 | 中等 |
| 最适合 | 生产级智能体系统 | 快速原型开发 | 基于角色的任务 | 研究实验 |

为什么本教程聚焦于 dsh

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

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