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

Agent 框架源码

第 1 节:一棵树不是一座山,循环只占 0.2%

核对 2026-11-05 更新 1 次 引用 0 个来源

1056431 行按「谁离不开谁」摊开是极度不平衡的结构:骨架约 1.1 万行,循环 2127 行,剩下的全是按能力挂上去的枝叶。小循环换来多实例、可替换、可热重载,代价是装配与策略分散在 370 个包里。

关键事实 · 5 条口径随行标注
全仓行数
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 要跑在多环境、多租户、需要审计,它的收益立刻兑现。

变更记录

日期类型改了什么范围
新建 按「树干/枝叶」拆体量,给出小循环的三笔账单 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型