跳到主要内容
赞助推荐 搬瓦工怎么选:三网直连 CN2 GIA-E
核对于 2026-11-05
课程目录 · 11 节

Agent 框架源码

DeepSeek Harness 源码手册:105 万行里循环只占 2127 行

核对 2026-11-05 更新 4 次 引用 2 个来源

DeepSeek Harness 是 MIT 开源的 agent 框架,packages 下 370 个包、1056431 行代码,而驱动 agent 的循环只有 2127 行。它的全部设计意图就在这个比例里:把「什么是 agent」压到极小,把「能变成什么」交给插件树。这页是十节源码课的判据汇总。

关键事实 · 5 条口径随行标注
仓库体量
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 行是怎么分布的

把仓库按「谁离不开谁」摊开,结构立刻清楚。五个体量数字就够定位:

dsh 0.2.2-rc.1 实测体量(物理行数,含注释与空行)
位置 行数 它是什么
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 的提供方,会连带换掉哪些能力
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 原型也明确标注「研究代码,非生产可用」。选它等于选了一份要自己维护的蓝图。

五个反直觉判断

这几条是我读完后和自己原有直觉冲突最大的地方,也是最容易在自建系统里做错的地方。

直觉 vs 代码里的事实
直觉 代码里的事实
核心循环是最复杂的部分 恰恰相反。循环 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 节拆分,根页存判据、节存推导 全页
待更 预览期版本会破兼容,升级后需回填体量数字与事件清单 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型