Agent 框架源码
第 1 节:一棵树不是一座山,循环只占 0.2%
1056431 行按「谁离不开谁」摊开是极度不平衡的结构:骨架约 1.1 万行,循环 2127 行,剩下的全是按能力挂上去的枝叶。小循环换来多实例、可替换、可热重载,代价是装配与策略分散在 370 个包里。
- 全仓行数
- 1056431 行packages 下 4890 个 TypeScript 文件,含注释与空行
- 包数量
- 370 个packages 下带 package.json 的包目录
- 循环体量
- 2127 行core/agent-loop/src 六个文件
- 子 agent 体量
- 4944 行subagent 包,是主循环的两倍多
- 启动装配体量
- 5408 行boot/app-boot,是主循环的 2.5 倍
一棵树,不是一座要通读的山
第一次打开 deepseek-harness 的仓库,最容易被两个数字劝退:370 个包、1056431 行。但把文件按「谁离不开谁」摊开,会发现它是一个极度不平衡的结构:
packages/ 1056431 行 · 370 个包
│
├─ core/ 骨架,约 1.1 万行
│ ├─ agent-loop 2127 行 ← 真正驱动 agent 的循环
│ ├─ session 3354 行 仅追加日志
│ ├─ tools 3710 行 注册表 + 执行流水线
│ ├─ agent 1789 行 接口与注册表
│ ├─ system-prompt 698 行 提示词组装
│ └─ scope 471 行 作用域原语
│
├─ llm/ fs/ shell/ sandbox/ … seam 与提供方,一层层往外
│
└─ 外围功能包 35 个工具、69 个子系统、UI、渠道、任务
subagent 4944 行
boot/app-boot 5408 行
看最后两行。「派发子 agent」这一段比主循环大两倍多,「启动装配」这一段是主循环的 2.5 倍。这不是头重脚轻,是这套架构的必然:任何一项能力都被拆成「接口 + 提供方 + 消费方」三件套独立成包,包与包之间只通过 ctx 上的服务键见面。
所以正确的心智模型是:树干 2127 行,枝叶按能力挂上去,随时可摘。要判断一个改动该放哪,只需问「它属于树干还是枝叶」。放错了,要么把稳定内核改脏,要么在外围重复实现已有能力。
为什么循环必须这么小:三个无法回避的理由
「循环要小」听起来像风格偏好,但在 dsh 的用法里它是硬约束。三个场景直接决定循环不能大:
| 场景 | 对循环的要求 | 循环变大后的后果 |
|---|---|---|
| 多个 Worker 并行 | 能被同时实例化,各自状态隔离 | 内部隐含全局状态,第二个实例就串味 |
| 整层替换驱动器 | 只依赖接口,不依赖实现 | 官方现在就做不到同时供 web / sdk / acp 三种模式 |
| 热重载插件 | 注册全部可撤销,循环不持有裸状态 | 改一次配置得重启进程 |
第一条最硬。Super-agent 那套 Router/Worker 结构要求同时跑多个独立上下文的 Worker;如果循环里塞了「当前会话」「当前工具集」这类单例状态,多开一个就互相踩。
所以 Agent 是一个接口而不是一个类,具体实例由 ctx.agents 注册表管理;循环只认接口,实例要什么能力就挂什么注册。这也是 scope 那个只有 471 行的包存在的理由——给每个 agent 划一块自己的注册域。
反过来看那些被塞进循环的东西,全都能外挂:预算、重试、审批、压缩、观测。它们各自是一个监听 agent/* 或 tools/* 事件的插件,装不装、装哪几个,看部署需要。
小循环的账单:复杂度没消失,只是换了位置
把复杂度从核心移到外围,不是消灭它,是换一种支付方式。这张账单值得在动手前看清:
| 省下来 | 欠下来 |
|---|---|
| 核心可读、可替换、可多实例 | 装配复杂度转移到配置层:四层 patch 叠加,得会读 --dump-config |
| 策略与工具解耦,一份工具多套规矩 | 策略散落在多个监听器,出问题要跨包追一条事件链 |
| 每个能力可独立装卸 | 370 个包意味着 370 个版本约束,依赖治理成本真实存在 |
| 日志即真源,可回放可审计 | 写放大,且「删一条消息」是追加撤销事件,不是真删 |
最关键的一行是第二行的后半句。策略外挂的代价是「行为不可从单点读出」——你打开 tool-bash 的源码,看不到它在生产环境会被拦;得去翻 patch 文件、审批策略、sandbox 提供方三处才能拼出全貌。
dsh 用两个手段缓这个问题:一是事件命名带域(tools/*、agent/*、fs/*),追链路时有明确入口;二是配置可导出(--dump-config),装配结果能静态看到。但本质上,这是一套需要「会读整棵树」的架构。
给一个判断标准:如果你的团队只有一个人维护、且只跑一种部署,这套结构的收益要打折;如果你的 agent 要跑在多环境、多租户、需要审计,它的收益立刻兑现。
变更记录
| 日期 | 类型 | 改了什么 | 范围 |
|---|---|---|---|
| 新建 | 按「树干/枝叶」拆体量,给出小循环的三笔账单 | 全页 |