一条消息怎样变成一个步骤:dsh 的 turn/step 生命周期
核验于 2026-10-31dsh 0.2.1-rc.5版本说明
一次模型请求不是从 fetch 开始的,而是从一条消息被放进 inbox 开始的。ReactLoopAgent 把工作分成轮次和步骤:轮次打开之后,循环依次领取输入、跑 agent/pre-step、组装提示词、准备调用、把系统消息与用户消息写进 Session 日志、冻结请求、流式读取响应、调度工具,最后关闭步骤和轮次。
按调用顺序读下来,最容易混淆的一对概念是“持久事实”和“实时控制”。下面的图只画一条消息经过一个步骤的主流程;策略分支、工具内部的关卡留给下一篇。

源码坐标
agent.ts:298-399—turn():turn/start、pre-step、step 循环、turn-stopping、turn/endagent.ts:267-289—preStep():调用agent/pre-step,拿到 reject 或 enteragent.ts:400-441—step()前半:渲染提示词、提交系统消息、接纳用户消息agent.ts:564-615—prepareRequest():agent/request与llm.prepareCall()agent.ts:616-700—buildRequest():request/header、request/context、冻结请求inbox.ts:109-113—claim():next-step 与 next-turn 的领取规则system-prompt/src/index.ts:20-32—system-prompt/assemblewaterfalltool-calls.ts:60-113—executeToolCalls():屏障、滚动池、按模型顺序提交session/src/index.ts:984-1011—deriveMessages():从日志折叠模型历史llm/src/index.ts:956-964—prepareCall():绑定适配器与调用能力
先分清三个边界
| 概念 | 边界 | 记录在哪 |
|---|---|---|
| 轮次 turn | 从领取首条输入开始,到不再欠工作结束 | turn/start、turn/end |
| 步骤 step | 一次模型请求,加上它调用的工具 | step/start、step/end |
| 持久事实 | 模型见过什么、工具返回了什么 | session/event 里的 user/message、assistant/message、tool/result 等 |
| 实时控制 | 队列、状态、请求拦截、steering | agent/* 事件,不用于回放 |
一个 turn 可以有零个 step。agent/pre-step 如果交出空的 messages(把领取到的消息全部去掉,或者改写成空数组),turn() 在 phase.step === 0 && decision.messages.length === 0 时直接把 turn 以 completed 结束,不发起模型请求,也不写 step/start。agent/pre-step 如果交出 reject,turn 以 blocked 结束,同样不会有 step。
turn() 的主循环
turn() 从 agent.ts:298 开始,骨架是一个 while (true):
- 追加
turn/start。 - 计算下一个 step 号,调用
preStep(target, { turn, step })。 - 如果决策是
reject,把turnEnds设为blocked,不进入 step。 - 如果这是首轮且
messages为空,把turnEnds设为completed,不进入 step。 - 追加
step/start,调用step(decision)。 - 在
finally里追加step/end,即使step()抛错也要写。 - 如果自然停止且
nextStep为空,跑一次agent/turn-stopping串行检查点。 - 如果还有
nextStep输入,继续下一个 step。 - 在
finally里追加turn/end,带上turnEnds。
把上面的顺序写成伪代码是:
turn/start
loop:
pre-step → reject/enter
step/start
… 模型请求与工具 …
step/end
turn-stopping(自然停止时)
turn/end
turn/end 的 reason 由 turnEnds 决定:completed、blocked、max-tokens、aborted、error。max-tokens 是粘性的:某一步撞到上限之后,turnEnds 就停在 max-tokens,后面正常完成的步骤不能把 reason 改写成 completed。
inbox:两个队列,不是一个共用队列
Inbox 里有两个队列:next-step 和 next-turn。claim(target, turn) 的行为是:
- 取走整个
next-step数组; - 如果
target === 'next-turn',再取走一条next-turn消息; - 对取走的每条消息发一个
agent/inbox/claimed实时事件。
next-step 的消息会加入当前 turn 的下一个 step;next-turn 的消息只在当前 turn 结束之后开启新的 turn。区分两个队列解决了一个具体问题:你在模型回答途中补一句话,这句话应该影响下一个 step,而不是另起一轮;agent loop 空闲之后,排进 next-turn 的那条新任务才会开启下一个 turn。
Inbox 的变更会以 agent/inbox/spliced 事件写进 Session 日志。恢复 Session 时,pending 输入由这些 splice 事件重新折叠出来,所以“队列里有几条消息”不是只存在内存里的状态。注入的上下文(agent.inject())不会单独唤醒 loop;这些注入的上下文要等一条唤醒消息,再和这条唤醒消息一起进入下一次认领。
pre-step:准入闸门
preStep() 在 agent.ts:267,preStep() 把领取到的消息连同 { turn, step, signal } 交给 agent/pre-step waterfall。agent/pre-step 的监听器可以做两件事:
- 返回
reject:当前 turn 以blocked结束,不进入 step。 - 返回
enter:带上最终要接纳的messages,监听器可以改写或增删messages,也可以设置startsRequestSeries。
startsRequestSeries 是一个容易被包装监听器弄丢的字段。startsRequestSeries 传给 loop 的信息是:本次 enter 要开启一个新的请求序列,需要记录新的 request/header。如果包装监听器用 { ...decision, messages } 重建决策,重建的结果要包含 startsRequestSeries;否则新序列的标记会被静默丢掉。
压缩(compaction)也挂在 agent/pre-step 事件上。dsh-compaction-basic 在派生请求之前通过 agent/pre-step 处理上下文压力;恢复时仍在同一个打开的 step 内,只有剪枝或摘要推进了 surface replacement generation,压缩才会重试。压缩挂接 agent/pre-step 的完整说明在架构总览的轮次流程里。
组装提示词:一次,重试复用
进入 step 之后,step() 先调用 renderPrompt(assembly),把系统提示词、上下文和工具 schema 渲染成文本。assembly 来自 pre-step 之前的 system-prompt/assemble waterfall;system-prompt/assemble 的监听器可以修改共享的 assembly,但已注册的完整 section 会在 waterfall 之后被恢复,所以监听器无法替换整个系统提示词。
step() 的组装规则是“一次,重试复用”:renderedPrompt 在 step 开始时计算一次,后面的重试循环不会重新组装 assembly。重试只重新调用 prepareRequest,然后基于同一份 assembly 和同一份渲染结果重新提交必要的 system/message,不会重跑 agent/pre-step。
prepareCall:先绑定,再提交
prepareRequest() 在 agent.ts:564,做两件事:
- 跑
agent/requestwaterfall,得到这次调用的 provider/model 配置。 - 调用
llm.prepareCall(config, signal),让适配器提前绑定路由,拿到一个 prepared call。
prepareCall 的返回值(也就是 prepared call)不只是“能 stream 的函数”。prepared call 还带着 systemPromptUpdate、toolUpdate、retryPolicy 和 context 等能力声明,后面的提示词提交和重试策略都依赖这些能力声明。
顺序很重要:先 prepare,再提交系统提示词和用户消息。 如果 prepareRequest() 抛错,或者在 prepareRequest() 期间取消,系统提示词和用户消息都不会写进 Session 日志。这样就不会出现“日志里有一条用户消息,但模型从没收到请求”的半截状态。先后顺序在 step() 的代码里就能看出来:agent.ts:410 先拿到 prepareRequest() 的结果,agent.ts:423 和 agent.ts:430-439 才写 system/message 与 user/message,agent.ts:442 最后调用 buildRequest()。
写日志:模型可见即已记录
写入分两处。step() 提交模型可见的输入:agent.ts:423 写 system/message(系统提示词的提交,带 surface intent),agent.ts:430-439 写 user/message(本次接纳的用户消息,runtime-context 会延后到第一次需要上下文时再写进日志)。
buildRequest() 在 agent.ts:616,buildRequest() 按需追加请求边界的事件:
request/header:请求信封,reason是initial、resume、change或series;developer/message:工具增删时写给模型的提示,带headerSeq;request/context:provider、model、上下文窗口或提示词更新能力发生变化时写。
追加完这些事件之后,buildRequest() 调用 deriveMessages(),从 Session 日志里折叠出模型历史,逐条对消息执行 deepFreeze,再用 Object.freeze 冻结整个数组和请求对象。冻结之后,请求就是不可变的;任何插件都不能在请求发送途中修改消息。
这套顺序实现了“模型可见即已记录”:请求不是从局部变量拼出来的,而是从 Session 日志推导出来的。下一次恢复、fork 或重放读同一份 Session 日志,就能得到同一份历史。
system/message 的处理比单纯追加一条消息更复杂。提示词可能按版本替换、在缓存前缀之后追加更新,或者在不支持更新的路由上归并到首个系统节点。规则在架构总览的轮次流程和 packages/core/agent-loop/README.zh.md 里;用一句话概括:system/message 的提交发生在 buildRequest() 之前,Session 日志是唯一来源。
流式结算:message 还是 attempt
流式读取由 AssistantStreamAttempt 承载。AssistantStreamAttempt 把 chunk 推给实时事件 agent/assistant-stream,同时记录一份紧凑 stream,等结算时把这份紧凑 stream 写进持久事件。
结算分几种情况:
- 成功完成:写
assistant/message,把紧凑 stream 嵌入其中;如果内容为空(比如只返回 usage),派生历史会丢掉这条内容为空的assistant/message。 - 撞到
max-tokens:仍然写assistant/message,返回max-tokens,后续步骤不能把 turn 的结束原因改成completed。 - 失败、重试、取消或 stream error,且没有 surface 内容:写
assistant/attempt,这条记录只留在日志里,不添加模型历史。 - 取消时已经收到部分内容:写带
interrupted: true的assistant/message,把已到达的内容留在历史里。
失败结算之后,loop 会跑 agent/request-error waterfall。agent/request-error 的监听器可以返回重试动作;dsh-compaction-basic 遇到规范的上下文溢出时返回重试动作。如果没有重试动作,原始错误会继续抛给 turn,turn 最终以 error 结束。
实时 agent/assistant-stream 的 chunk 帧是瞬态数据。回放时读取的是 assistant/message 或 assistant/attempt;如果进程在结算完成前被硬中断,Session 日志里不会留下持久的 attempt stream。
工具调用:模型顺序提交
如果 assistant/message 里含有 tool-call 块,step() 会调用 executeToolCalls()。executeToolCalls() 的调度规则是:
- 独占调用形成屏障:屏障之前的调用必须全部结算,屏障之后的调用才能开始。
- 可并行的调用使用有界滚动池,并在每次启动前重新分类;注册表在运行中变化时,新的独占调用会形成新的屏障。
- 每个工具调用在 prepare/dispatch 之前先把
tool/call写进 Session 日志。 - 结果按模型发出的顺序提交
tool/result,即使实际执行是并发的。
工具返回的 additionalContexts 会通过回调 splice 到 next-step 队列里,作为活动批次的一部分,排在已记录的工具结果之后。工具在结果里附加一段文字,模型在下一个 step 看到这段文字;完成这段投递的是上面那条 splice 回调。
工具内部的审批、守卫和失败分层,是下一篇的主题。
日志怎样变成历史
deriveMessages() 在 session/src/index.ts:984。deriveMessages() 不复制日志,而是沿 surface 节点走一遍:
- 只有 message-producing 事件会进入派生历史:
system/message、user/message、assistant/message、tool/result,以及插件注册的消息投影。 - 没有 surface 标记的原始事件(chunk、turn 边界)不会进入历史。
- 压缩的
replace会删掉被遮蔽的节点,派生历史随之重建。 - 空内容的
assistant/message派生为null,不进入 transcript。 - 尾部追加是增量的;只有 replacement 或消息投影变化时,
deriveMessages()才整体重建派生历史。
deriveMessages() 返回的数组每次都是新快照,但数组里的 Message 对象是共享且深冻结的。消费方不能通过返回值修改 Session 日志。
自己验证
下面的检查不需要模型 Key。第一步是确认 agent loop 确实以“空启动列表”挂载:
dsh --profile web --dump-config | grep -A6 "id: agent-loop"
预期输出:
- id: agent-loop
name: '@deepseek-ai/dsh-agent-loop'
config:
agents: []
agents: [] 表示 base 不在启动时创建 agent;Web 是在客户端请求时创建 Session,再由 Session 驱动 agent loop。配置里这份空的 agent 列表,解释了为什么“启动后什么都没发生”是正常现象。
有模型 Key 时,可以进一步查看真实日志:
- 启动
dsh web,发一条会调用工具的消息。 - 找到
$DSH_HOME/sessions下的 Session 文件(可能是 JSONL 或压缩后的 JSONL)。 - 在日志里搜索
turn/start、step/start、tool/call、tool/result、turn/end。
这些步骤不要求解析日志的每一行:你要先确认上面列出的事件的出现顺序,再回到 turn() 和 step() 的源码逐条对照。如果 Session 日志是 .zstd 压缩的,先解压再读取,不要直接编辑原文件。
三个常见误解
“一个 turn 一定有一次模型请求。” 不一定。首轮的 agent/pre-step 返回 reject,或者把 messages 改写成空数组时,turn 会打开并关闭,但不进入 step,也不会发起模型请求。
“重试会重新跑 pre-step 和用户消息。” 不会。重试发生在仍打开的 step 内,复用同一份 assembly 和渲染结果,只重新 prepare 并重新提交必要的系统消息;用户消息由 firstAttempt 把关,不会重复写入日志。
“实时 stream 就是历史。” 不是。实时 chunk 是瞬态事件;历史来自持久结算。SDK 用户要 transcript,应该消费 session/event 里的持久事件;要队列和状态,才消费 agent/* 事件。
官方文档对应位置
- Agent 轮次与步骤生命周期:时序图、事件清单、压缩与重试
- 架构总览:轮次流程:turn、step、请求构建与系统提示词规则
- agent-loop README:实现顺序、取消与错误恢复
- session README:日志、派生历史与持久化
下一篇进入工具内部:一次工具调用要过哪些关卡。
常见问题
turn 和 step 有什么区别?
turn 是一次连续工作:从领取首条输入开始,到不再欠任何工作结束;一个 turn 可以包含零个或多个 step。step 是一次模型请求,加上这次请求调用工具的过程。
为什么重试不会重复写用户消息?
重试发生在仍打开的 step 内。step() 里的 firstAttempt 只在第一次尝试时接纳用户消息;后续重试复用同一份 assembly,不重新跑 agent/pre-step,也不重复写 user/message。
assistant/message 和 assistant/attempt 有什么区别?
assistant/message 是一次成功结算,会进入派生历史;assistant/attempt 记录失败、重试、取消或 stream error 的已到达结算,不添加模型历史。被中断但已有内容的流可以结算成带 interrupted 标记的 assistant/message。
回放 transcript 应该读哪一路事件?
读 session/event 里的持久事件。agent/assistant-stream 是进程本地的实时 chunk,不用于回放;持久结算在 assistant/message 或 assistant/attempt 里。