Agent 框架源码
DeepSeek Harness 源码手册:105 万行里循环只占 2127 行
DeepSeek Harness 是 MIT 开源的 agent 框架,packages 下 370 个包、1056431 行代码,而驱动 agent 的循环只有 2127 行。它的全部设计意图就在这个比例里:把「什么是 agent」压到极小,把「能变成什么」交给插件树。这页是十节源码课的判据汇总。
- 仓库体量
- 1056431 行packages 下 4890 个 TypeScript 文件的物理行数,含注释与空行
- 包数量
- 370 个packages 下带 package.json 的包目录,另有 apps 5 个
- 循环体量
- 2127 行core/agent-loop/src 六个文件,占全仓 0.2%
- 持久会话事件
- 14 种SessionEventMap 的键集合,其余为不落盘的实时扩展点
- 内置工具
- 35 个docs/tool-catalog.zh.md 列出的面向模型工具条目数
这页是什么:一份可以拿来对照代码的判据表
DeepSeek Harness(下文缩写 dsh)在 2026 年 8 月以 MIT 协议开源,仓库名 deepseek-ai/deepseek-harness。我把 0.2.2-rc.1 这一版完整拉下来读过,packages 目录下 370 个包、4890 个 TypeScript 文件、1056431 行代码,而真正驱动 agent 的那个循环只有 2127 行。
这个比例不是巧合,是这份产品的全部设计意图:把「什么是 agent」压到极小,把「agent 能变成什么」交给插件树。所以读它不能从 README 往下读,得先看清哪 2000 行是骨架,剩下 105 万行是什么在围着骨架长。
这页是十节课程的判据汇总:数字、对照表、检查清单。每节展开一个问题,正文里的代码和推导留在各节。读法按你的目的分三种:
| 你的目的 | 先读哪几节 | 读完能做什么 |
|---|---|---|
| 判断要不要用 | 第 1 节 + 第 11 节(差别对照) | 说清它和 Claude Code、LangGraph 的取舍,不靠感觉 |
| 改它、扩它 | 第 2、3、6、9 节 | 写得出一个能跑的工具插件,知道注册为什么可撤销 |
| 抄它的架构 | 第 4、5、7、10 节 | 把「循环小、外围大」这套结构搬到自己的系统里 |
版本会动。dsh 官方明确说预览期会有破坏兼容的改动,所以本页所有数字都锚在 0.2.2-rc.1,每节标核对日期。升级后对不上的地方,以你本地 packages/ 的实际代码为准。
先看骨架:1056431 行是怎么分布的
把仓库按「谁离不开谁」摊开,结构立刻清楚。五个体量数字就够定位:
| 位置 | 行数 | 它是什么 |
|---|---|---|
packages/ 全部 TS |
1056431 | 产品本体的全部实现,4890 个文件 |
core/agent-loop |
2127 | agent 循环:发请求、跑工具、写日志,六个文件 |
core/tools |
3710 | 工具注册表与执行流水线 |
core/session |
3354 | 仅追加会话日志与内存存储 |
subagent |
4944 | 子 agent 派发,比主循环大两倍多 |
注意最后一行:子 agent 的代码量是主循环的两倍多。这不是失控,是这套架构的必然结果——任何一项能力都被拆成「接口 + 提供方 + 消费方」三件套单独成包,包与包之间只通过 ctx 上的服务键见面。功能越多,包越多,主循环一行不用改。
所以「1056431 行」这个数字容易误导。它不是一座要通读的山,是一棵树:树干 2000 行,枝叶按能力挂上去,随时可摘。
它想解决的问题:多任务上限不在模型,在人的注意力
dsh 团队在《Super-agent 设计探索》里给了一句判据:单任务的上限取决于模型能力,多任务的上限取决于人的注意力。一个人同时只能盯三到五个活跃会话,再多就要靠记性。
主流 agent 的形态是「一个会话一个循环」:会话 A 里得出的结论,会话 B 不知道;用户并行推三件事,就得自己当那个总线,记住每条上下文。想做常驻、事件驱动的助手,这个模型直接撞墙。
dsh 的解法不是把循环写得更聪明,而是把会话管理和上下文同步从人手里移到系统层:持续运行的 Router 收多渠道消息、分派任务,各自带独立上下文的 Worker 并行干活,人退到「定目标、验收结果」的位置。
这条判断决定了后面所有设计。为什么 agent loop 要小?因为要能被替换、被嵌套、被多个 Worker 同时实例化。为什么注册要可撤销?因为 Worker 会随时生灭。为什么日志要仅追加?因为上下文得从日志重建,而不是靠内存里一个会话对象。
一棵插件树:从 CLI 启动到 agent 跑起来
运行中的 dsh 不是「一个主程序 + 若干模块」,是一棵插件树。启动时按顺序叠几层配置,最终长出这棵树:
dsh --profile web
│
├─ profile「web」 Harness home 里的具名组装
│ └─ 有序组合包 bundle
│ ├─ dsh-base 模型适配器·工具·持久化·沙箱·审批·设置·凭据·遥测
│ └─ dsh-web-app 浏览器应用(HTTP + Web Client 插件)
│
├─ cordis.patch.yml 用户自己的覆盖层
├─ home patch 机器级覆盖层
└─ --patch overlay 命令行临时覆盖层
↓
空条目列表上逐层应用 patch → 插件树 → ctx 上挂满服务
↓
ctx.agents / ctx.sessions / ctx.tools / ctx.llm / ctx.systemPrompt …
↓
AgentLoop 按配置创建 agent,开始跑 turn
关键在最后那句「空条目列表上逐层应用」。没有任何一行是内建不可改的:dsh --profile web --dump-config 打印出来的每一条,都能被上面任意一层 patch 按 id 定位替换掉整个 config,或插入新条目。
这意味着「改行为」有三种粒度,成本递增:改配置(写 patch)→ 换提供方(注册同接口的实现)→ 改循环(换掉 ctx.agentLoop)。日常九成需求停在前两级。
五个核心包,各管一段,谁也不越界
骨架由五个包组成,每个包独占一个 ctx 服务键。它们之间的依赖是单向的:上层知道下层,下层不知道上层。
| 包 | 职责 | 服务键 | 不知道什么 |
|---|---|---|---|
core/session |
仅追加事件日志 + 内存存储 | ctx.sessions |
不知道有模型,也不知道有工具 |
core/system-prompt |
提示词片段与工具 schema 的组装 | ctx.systemPrompt |
不知道片段从哪来 |
core/tools |
作用域化注册表 + 带把关的执行流水线 | ctx.tools |
不知道调用方是模型还是脚本 |
core/agent |
Agent 接口、活跃注册表、agent/* 事件 |
ctx.agents |
不知道谁实现了这个接口 |
core/agent-loop |
上述接口的默认驱动器 | ctx.agentLoop |
不关心 UI、不关心渠道 |
这张表最值得看的是最后一列。ctx.sessions 完全不知道模型存在,所以你可以把会话存到 JSONL、Postgres 或远端对象存储,循环一行不改。ctx.agents 只是个接口注册表,所以官方能同时提供默认循环、SDK 模式和 ACP 模式三种驱动器。
第 4 节会拆开 agent-loop 那 2127 行,看它怎么用这五个键拼出一个能跑的 turn。
一次 turn 走完全程:十四个持久事件是它的脚印
术语先对齐:一个 步骤(step) 是一次模型请求加上它触发的工具调用;一个 轮次(turn) 包含零个或多个步骤,从领取第一条输入开始,到不再欠任何工作时结束。
turn/start ← 持久 ├ 取一条输入 + 一条排队消息 ├ 快照模型选择;组装提示词片段 + 本步准入的工具 schema ├ agent/pre-step waterfall,可 reject / 改写 │ └ reject 或首个 enter 被改写为空 → 本轮零步骤直接收尾 ├ step/start ← 持久 │ ├ agent/request waterfall(已弃用钩子) │ ├ prepareCall() 绑定适配器,提交系统提示词与用户消息 │ ├ 从日志派生并冻结模型历史 │ ├ llm/stream → agent/assistant-stream chunk* │ ├ assistant/message | assistant/attempt ← 持久 │ ├ tool/call* → tools/pre-execute → tools/execute → tools/post-execute → tool/result* │ └ step/end ← 持久 │ └ 还欠一次请求,或有新输入 → 回到 step/start ├ agent/turn-stopping serial,可停轮 └ turn/end ← 持久
十四种持久事件,全部写进仅追加日志:turn/start、step/start、system/message、user/message、assistant/message、assistant/attempt、tool/call、tool/result、request/header、request/context、step/end、turn/end、developer/message、session/end-seed。
其余全是活的事件扩展点,不落盘。这条边界很重要:需要一个事实在重启后还在,就做成会话事件;只是想在当下拦一刀,就用 agent/* 或 tools/* 事件。搞混了会得到两种后果——把瞬态判断写成持久事件,日志会膨胀;把必须留痕的事实只做成事件,重启就丢。
Cordis 管三件事:服务、类型化事件、可撤销注册
底层框架 Cordis 是 vendored 进来的,它不是又一个依赖注入容器。它只承诺三件事,而这三件事恰好是「一切皆插件」能成立的前提。
| 承诺 | 机制 | 不成立会怎样 |
|---|---|---|
| 按 key 取服务,不导入实现 | ctx.<key> + inject 声明依赖 |
换实现要改 import,编译期就绑死 |
| 事件有五种分发语义 | emit / waterfall / parallel / serial / bail |
拦截和观察混用,顺序不可控 |
| 注册是可逆副作用 | ctx.effect() / ctx.on() 自动回收 |
插件卸载后工具还在,热重载必泄漏 |
第三件事最容易被低估。工具的 schema、提示词片段、模型适配器、监听器,全部通过 ctx.effect() 或 ctx.on() 安装,返回 disposer 或由框架托管。插件 fiber 一 dispose,这些注册同时撤销。
这正是「fork 一个 Worker」便宜的原因:Worker 是一个独立 fiber,它的工具集、提示词、监听器全归它自己,销毁时一次收干净,不会污染主会话。
工具流水线:策略不写进工具,工具只负责干活
工具执行被拆成七道关,任何一道都能改调用、拦执行、改结果,而工具代码本身不知道这些策略存在:
模型吐出 tool-call ↓ tool/call 先落盘再执行(日志在动作之前) ↓ tools/pre-execute waterfall 钩子 / 权限 / 沙箱判定 ├ deny ──────────────────────→ 跳过工具体,结果标记失败 └ ask → ctx.approval 一次性询问 → 无人应答按拒绝处理 ↓ 单调守卫 guard deny 或弃权;后续监听器无法翻案 ↓ tools/execute waterfall 环绕分发:超时 / 重试 / 指标 ↓ 工具 execute() 本体 ↓ projectContent 把准备内容投影成模型可见文本与图片 ↓ tools/post-execute waterfall 接受 / 阻断 / 替换 / 追加上下文 ↓ finalizeContent 最后一道「只改内容」的不变式 ↓ tools/result 同步通知 结果已冻结,只许看,不许改 ↓ tool/result 落盘,模型看到唯一结果
三个 waterfall 都能改调用。区别在时机和权限等级:pre-execute 能拒、能问、能改参数;guard 是单调的,一旦 deny 谁也别想翻;post 只能动已经产生的结果。
这套划分解决一个很实际的问题:同一个工具在不同部署里要有不同规矩。开发机允许 rm,生产环境要审批,多租户环境要沙箱,但你不该为此维护三份 bash 工具。策略挂在事件上,工具保持一份。
seam:换一个提供方,整套执行环境跟着搬
seam(能力接缝)是一组三角色设计:声明接口的 Service Definition、实现它的 Service Provider、使用它的 Consumer。包可以同时扮演多个角色,但单一个角色本身不算 seam。
seam 真正的价值在组合效应。文件系统和进程提供方共享同一个「执行世界」,所以把它们指向远程沙箱,Bash、持久终端、LSP 会一起搬过去,不需要给每个工具写远程版本。
| seam | 换掉它 | 连带变化 |
|---|---|---|
ctx.fs |
本地 → 远程沙箱 | 读写、编辑、搜索、diff 卡片全部跟着走 |
ctx.subprocess |
本机 spawn → 容器 | Bash、PTY、LSP 的执行位置一起变 |
ctx.sandbox |
无 → 策略后端 | 进程启动前 argv 被包装,所有工具同时受约束 |
ctx.llm |
DeepSeek → 任意适配器 | 流式协议、工具调用格式、推理强度字段 |
ctx.sessions |
JSONL → 远端存储 | fork、恢复、导出全部复用同一套句柄 |
第 7 节用 fs 和 subprocess 两条链路验证这个说法:为什么把 ctx.fs 指向远端,bash 就自动在远端跑。
会话日志是唯一真源:模型看到什么,由它投影出来
dsh 有一条硬规矩,写在架构文档里加粗:模型可见即已记录。每个模型请求都必须能从日志重建。新增任何模型可见输入,都得先有对应的会话事件。
所以 deriveMessages() 不是「顺便存一份消息数组」,而是从仅追加日志里投影出模型历史。这条设计带来三个能力,都很难在「内存消息数组」的架构里做出来:
| 能力 | 依赖什么 | 内存数组做不到的原因 |
|---|---|---|
| 回放与审计 | 每次尝试的完整紧凑流都嵌在事件里 | 流在内存里是瞬态增量,结束了就没了 |
| fork 会话 | 按事件计数切开历史 | 没有可切分的稳定边界 |
| 格式迁移 | 相邻版本 vN → vN+1 链式解码 |
结构直接序列化,没有版本概念 |
代价也说清楚:日志只追加,不原地改,所以「删一条消息」实际是追加一条撤销事件;文件按 generation 排他发布,旧路径绝不覆盖。写放大是真的,换来的是任何一次事故都能完整复盘。
它和 LangGraph、Claude Code 到底差在哪
三者常被放在一起比,但比的不是同一层东西。按「谁决定下一步」和「谁拥有运行时」两个维度拆:
| 维度 | LangGraph 式编排 | Claude Code / Codex | DeepSeek Harness |
|---|---|---|---|
| 下一步谁定 | 图里的边,写代码时定死 | 模型,但只在单个会话内 | 模型,可跨会话由 Router 分派 |
| 运行时归属 | 你的进程 | 厂商托管,你只有 API | 你的机器,MIT 源码可改 |
| 扩展方式 | 加节点、改边 | 加 MCP server、加配置 | 挂插件,连循环都能换 |
| 状态在哪 | 图状态机 + 你自建持久化 | 厂商侧,你只能读界面 | 仅追加日志,本地可导 |
| 最贵的成本 | 图会越画越复杂 | 被托管,无法定制内核 | 粗糙,兼容性会破,得自己养 |
一句话概括这条谱系:LangGraph 把决策权交给编排代码,Claude Code 把决策权交给模型但运行时留在厂商,dsh 把两者都交出去——决策权给模型,运行时给你。
代价落在最后一列:官方自己在文档里写「预览期会频繁改动、会有破坏兼容的变更」,Super-agent 原型也明确标注「研究代码,非生产可用」。选它等于选了一份要自己维护的蓝图。
五个反直觉判断
这几条是我读完后和自己原有直觉冲突最大的地方,也是最容易在自建系统里做错的地方。
| 直觉 | 代码里的事实 |
|---|---|
| 核心循环是最复杂的部分 | 恰恰相反。循环 2127 行,是整棵树里最稳定的部分;复杂度全在 seam 和外围包 |
| 工具多代表能力强 | 内置面向模型的工具 35 个,但策略一律外挂。工具只管干活,不管规矩 |
| 子 agent 是主循环的简化版 | subagent 包 4944 行,是主循环的两倍多。派发、隔离、回收比循环本身难 |
| 拦截靠提示词就够了 | 提示词是建议,tools/pre-execute 和单调守卫才是约束。前者能被模型绕过,后者不能 |
| 日志是为了调试 | 日志是上下文来源本身。删掉日志,模型就不知道自己说过什么 |
动手之前:九条检查
如果你打算基于 dsh 做东西,或者照它的结构自建,这九条按顺序过一遍能省掉大部分返工。前四条定边界,后五条定实现——顺序错了,边界会跟着实现走,改起来就是重构。
还有一个隐性成本要提前认:新人上手没有「读一个文件就懂」的入口。文档再全,也得先把 370 个包的职责图装进脑子,才知道该改哪里。这份手册用十节搭的,正是这张图。
| # | 检查项 | 不通过的症状 |
|---|---|---|
| 1 | 版本锚点写死了吗 | 升级后数字全对不上,文章和代码两套真相 |
| 2 | 哪些行为必须落盘、哪些只需当下拦截 | 日志膨胀,或重启丢事实 |
| 3 | 策略是挂在事件上还是写进工具里 | 同一工具出现三份分支 |
| 4 | 注册是否都带 disposer | 热重载后旧工具还在,越跑越慢 |
| 5 | 取消是否协作式、是否保留已交付文本 | 用户看到的话被回滚,或取消后进程挂住 |
| 6 | 工具错误是否带可行动信息 | 模型反复重试同一个错,因为看不出为什么错 |
| 7 | 上下文压缩发生在哪一层 | 写进提示词当纪律,实际把事实删了 |
| 8 | 远程执行是换 seam 还是换工具 | 给每个工具写一份远程版,维护量翻倍 |
| 9 | 有没有一条能从日志重放的失败样本 | 出问题只能靠猜,不能归因 |
版本锚点与数据出处
本页与十节课的全部数字来自 2026-11-05 拉取的源码快照:主仓库 deepseek-ai/deepseek-harness 的 0.2.2-rc.1,以及 deepseek-ai/dsh-superagent-prototype。行数用 wc -l 统计 packages/*/*/src 下的 .ts 文件,含注释与空行;包数按带 package.json 的包目录计。
「内置工具 35 个」的口径是中文版 docs/tool-catalog.zh.md 列出的面向模型工具条目数,不含 UI 专用与内部调用。会话事件 14 种来自 SessionEventMap 的键集合。
官方文档本身很完整,本系列不重复翻译它,只做三件文档不做的事:把分散在 370 个包里的设计意图串成因果链、给出可核的体量与阈值、指出文档没写明的代价和边界。
依据:deepseek-harness 主仓库 · dsh-superagent-prototype · 仓库内 docs/architecture.zh.md、docs/cordis-primer.zh.md、docs/tool-execution-pipeline.zh.md。
变更记录
| 日期 | 类型 | 改了什么 | 范围 |
|---|---|---|---|
| 新建 | 把 0.2.2-rc.1 源码读成判据表,正文重写非文档翻译 | 全页 | |
| 口径 | 行数按 wc -l 统计 packages/*/*/src 下 .ts,含空行与注释 | 全页 | |
| 结构 | 建课程根页 + 10 节拆分,根页存判据、节存推导 | 全页 | |
| 待更 | 预览期版本会破兼容,升级后需回填体量数字与事件清单 | 全页 |