Agent 框架源码
第 4 节:两个队列两个层级,turn 与 step 的边界
待处理输入是两个持久队列 next-turn 与 next-step,所有增删都是落盘的 splice。step 是一次请求加工具调用,turn 从领取首条输入到不欠工作。重试不重跑 pre-step,取消保留已交付文本。
- 输入队列
- next-turn 与 next-step两个持久队列,所有变更以 agent/inbox/spliced 落盘
- 折叠校验
- 三重start 边界、removedCount 越界、两队列合并后 id 重复
- 工具续跑
- 还欠一次请求即进入下一 step工具可以主动让模型再想一次
输入不是「发消息」,是两个队列的 splice
大多数 agent 框架里,「用户发来一条消息」等于调用一次 run(prompt)。dsh 不是。它把待处理输入做成两个持久队列,所有增删改都是对队列的 splice 操作,并作为事件落盘:
Session 日志(仅追加)
│
├─ agent/inbox/spliced { target, start, removedCount, inserted }
│ │
│ └─→ projection 'inbox' 折叠所有 splice
│ ├─ next-turn : [消息…] ← 下一轮才处理
│ └─ next-step : [消息…] ← 当前轮下一步就插进去
│
└─ 每一次变更同时发一个语义通知:
agent/inbox/inserted { message }
agent/inbox/claimed { message } ← 领取:纯删除,不带 outcome
agent/inbox/discarded{ message } ← 丢弃:带 outcome: 'canceled'
为什么搞这么复杂?因为队列必须能在没有活跃 Agent 的时候被读取,也必须能在重启后重建。如果待处理消息只活在内存数组里,进程一挂,用户刚打的字就没了;如果只存最终队列快照,就分不清某条消息是「被领取执行了」还是「被取消了」。
折叠逻辑写得相当防守。apply() 里对 splice 做三重校验:start 必须是安全整数且在界内、removedCount 不能让区间越界、折叠后两个队列合起来不能出现重复的 message.id。任何一条不满足就抛错,并带上出错的 event.seq。
这段代码说明了一个设计取向:日志损坏要尽早炸,不能静默容错。一个被静默修正的 splice 会让后续所有折叠都建立在错误状态上,等到用户发现「模型说它没收到我的消息」时已经无法归因。
turn 与 step:边界定义决定了一切
两个术语必须先钉死,否则后面所有讨论都会错位:
| 概念 | 定义 | 边界事件 | 一个 turn 里有几个 |
|---|---|---|---|
| 步骤 step | 一次模型请求 + 它触发的工具调用 | step/start / step/end |
0 到多个 |
| 轮次 turn | 从领取首条输入,到不再欠任何工作 | turn/start / turn/end |
1 |
「零个步骤的 turn」是真实存在的:agent/pre-step 监听器拒绝领取,或首个 enter 决策被改写成空,循环就关掉一个不含步骤的持久轮次。这不是异常分支,是让拦截器能干净地说「这条消息不该触发模型」。
「不欠工作」的定义也值得抄下来。一个 step 结束后,只要满足任一条件就继续下一个 step:工具还欠一次请求(比如工具让模型再想想),或下一步的输入已经到达。都不满足,才进入 agent/turn-stopping 然后 turn/end。
这条规则带来一个重要性质:工具可以主动续跑。工具执行完返回「还欠一次请求」,模型就会在同一个 turn 里再被叫一次,而不需要用户再发一句话。异步任务、分步推理、需要中间确认的流程,都靠这个机制实现。
重试与取消:两个最容易写错的地方
循环里有两条容易搞混的路径,dsh 的处理方式可以直接抄。
重试不重复 pre-step。一个 step 内如果模型请求失败重试,它不会重新组装上下文、也不会再跑一遍 agent/pre-step。理由是:pre-step 是「这条输入该不该进这一轮」的判定,重试还是同一条输入,重复判定会让拦截器有机会对同一条消息给出不同答案。重试只做「重新发请求」,组装结果和准入决策都保留。
取消是协作式的,且保留已交付文本。取消不杀进程,是通过 AbortSignal 协作中止当前活动,并且已经流式交付给用户的文本会保留——不会因为取消就把用户屏幕上的字回滚掉。取消还有一档区别:keepInbox 未设置时会清空待处理工作,设置了就保留。
| 场景 | 正确行为 | 常见写错 |
|---|---|---|
| 步骤内请求失败重试 | 不重跑组装与 pre-step,只重发请求 | 整段重跑,拦截器被调用两次 |
| 用户取消 | 中止信号 + 保留已交付文本 | 直接丢弃整条 assistant 消息,用户看到的话消失 |
| 取消时队列 | 默认清空,keepInbox 可保留 |
一律清空,用户排队的后续指令被吞 |
| 失败步骤 | 记录「缺失的工具结果」 | 什么都不写,下一步模型看到半截调用 |
最后一行尤其关键。一个 step 失败了,日志里会补记「缺失的工具结果」——因为模型上一轮已经发出了 tool/call,如果结果位置空着,下一次请求的历史里就有一个悬空调用,模型会困惑于「我调了但没返回」。
下一节讲日志本身:为什么它是唯一真源,以及「模型看到什么」这件事是被投影出来的。
变更记录
| 日期 | 类型 | 改了什么 | 范围 |
|---|---|---|---|
| 新建 | 拆 inbox 投影与 turn/step 边界,标出重试与取消的正确语义 | 全页 |