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

Agent 框架源码

第 4 节:两个队列两个层级,turn 与 step 的边界

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

待处理输入是两个持久队列 next-turn 与 next-step,所有增删都是落盘的 splice。step 是一次请求加工具调用,turn 从领取首条输入到不欠工作。重试不重跑 pre-step,取消保留已交付文本。

关键事实 · 3 条口径随行标注
输入队列
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 边界,标出重试与取消的正确语义 全页
赞助推荐 一键部署 AI 大模型
赞助推荐 一键部署 AI 大模型