拆解 dsh：Turn 与 Step 如何组织 Agent 主循环

本文基于 @deepseek-ai/dsh 0.1.1-rc.2（npm latest 标签），对应仓库标签 dsh-v0.1.1-rc.2，commit b150a551b8。dsh 仍处于 developer preview，API 还会变化。

插件树之后的主循环

上一篇「Profile 与 Bundle 如何装配运行时」停在插件树挂载完成的位置：Bundle 提供配置层，Profile 决定组合顺序，Cordis 把最终配置树变成一棵运行中的插件树。

插件树挂载完成后，Agent Loop 开始工作。用户的输入进入系统后，模型会开始生成回复；如果中途调用工具，工具结果会回到下一次模型请求中，循环继续推进，直到当前 Turn 结束。dsh 将这部分也做成了插件：@deepseek-ai/dsh-agent-loop。

目前，dsh 的大多数包要么提供的是抽象 service，要么作为插件挂在扩展点上。这个包的 README 指出，它是整个 Harness 中唯一包含具体循环逻辑的包，循环本体位于 src/agent.ts 中的 ReactLoopAgent 类。

这套循环分成两个层级：Turn 与 Step。

• Turn 是一次由输入唤醒的完整执行过程，从 turn/start 开始，到 turn/end 结束，中间可以包含一次或多次模型调用。

• Step 是一次模型调用，以及这次调用产生的工具执行，由 step/start 和 step/end 包住。

一个 Turn 中包含多少个 Step 并不固定。如果模型给出回答但没有调用工具，那么这个 Turn 就只有一个 Step；如果模型调用工具，工具结果返回后再次请求模型，就会进入下一个 Step。

Turn

    Step 1
        模型请求
        工具执行

    Step 2
        模型请求
        工具执行

    ...

Turn 可以不包含任何 Step。例如，agent/pre-step 上的插件拒绝这次 Step，Turn 会以 blocked 结束；被唤醒的消息在中途被清除，或者插件把进入 Step 的消息改写为空，也可能让 Turn 在没有模型调用的情况下关闭。

Turn 编号会跨进程延续。持久化会话恢复后，驱动器从日志中找到最后一个 turn/start，新的 Turn 从原有编号继续递增；Step 编号则在每个 Turn 中重新从 1 开始。

Turn 并没有覆盖运行时里的所有工作。dsh 还提供 maintenance 相位，用于执行不需要开启 Turn 的维护任务，例如手动压缩。维护期间到达的唤醒输入会先留在 Inbox，等任务结束后再交给主循环处理。这划出了一条明确的边界：Turn 描述一次 Agent 执行，运行时自身的维护任务可以独立运行。

Turn、Step 与 Inbox

Agent Loop 运行过程中，会持续记录各类执行事件。一个完整的 Turn 会按照下面的顺序推进，其中部分事件只会在特定条件下写入：

turn/start          { turn }
  ├─ (pre-step 决策，不落事件)
  step/start        { turn, step }
  ├─ user/message   × N        进入这一步的消息
  ├─ request/header             请求配置变化时写入
  ├─ request/context            路由或容量变化时写入
  ├─ assistant/chunk × N        流式原始分片
  ├─ assistant/message          组装后的完整回复
  ├─ tool/call      × N
  ├─ tool/result    × N
  step/end          { turn, step }
  ├─ (还有工具结果或 steering，进入下一个 step)
turn/end            { turn, reason }

这条序列同时反映了循环执行和日志写入的过程。为什么模型请求的配置也要写进日志，以及这些事件如何重新构造模型看到的 messages，会放到下一篇讨论。

输入进入循环之前，会先进入 Inbox。Inbox 内部维护 next-turn 和 next-step 两条队列，Agent 在这两条队列之上提供了一个基础的入队接口：

send(
  message: UserMessage,
  target: InboxTarget,
  wakeup: boolean
): void

target 决定消息进入哪条队列，wakeup 决定是否唤醒驱动器。两个参数可以形成四种组合，dsh 为其中三种提供了固定别名：

followup()   next-turn  + 唤醒
steer()      next-step  + 唤醒
inject()     next-step  + 不唤醒

第四种 next-turn + 不唤醒 没有对应别名。

• followup() 表示一条新的用户输入，会进入 next-turn，等待开启自己的 Turn；

• steer() 会把消息放入 next-step，让它进入当前 Turn 的下一个 Step，同时唤醒驱动器；

• inject() 同样写入 next-step，但不会唤醒驱动器。

一个典型场景是插件在 agent/session-start 时注入上下文。如果此时还没有 Turn，这些消息会先留在队列中，直到后续的 followup() 或 steer() 唤醒驱动器。

Turn 和 Step 在开始时，会从 Inbox 中取出不同类型的消息。Turn 开始时，驱动器会一次性取走全部的 next-step 内容，再取一条排队的 prompt；两个 Step 之间，则只读取 next-step。每条被取出的消息都会产生一次 agent/inbox/claimed。如果消息取出后被 pre-step 拒绝，它不会重新放回 Inbox，也不会进入当前 Step，而是随这个被拒绝的 Turn 一起结束。

Inbox 的变化同样会写入日志。每次队列发生变化时，系统会先记录 agent/inbox/spliced，再更新内存列表；重新构造驱动器时，Agent 会根据会话日志中记录的 Inbox 变化重新还原队列状态。如果这些日志被持久保存，进程重启后，之前还没处理的输入也能恢复。

主循环的扩展点

Turn 与 Step 定义了主循环的基本结构，插件则通过几组扩展事件介入执行过程。rc.2 中，核心介入位置集中在五处：

这些派发模式来自 Cordis：

emit        注册顺序     无返回值
waterfall   注册顺序     有返回值
parallel    并行         无返回值
serial      注册顺序     有返回值

waterfall 类似一条环绕式中间件链。监听器收到 (...args, next) 后，可以调用 next() 把处理结果交给下一个监听器，也可以停止向后传递并自行返回结果。因此，同一个扩展点可以挂载多个插件，既能逐层处理，也允许某个插件提前结束这条处理链。Agent Loop 会等这条处理链执行完成后，再继续后面的流程。

这些扩展点的使用密度差异很明显。在 rc.2 仓库中统计相关事件的监听包数量，排除测试代码和仅负责作用域转发的部分后，可以看到：

agent/pre-step        14
agent/request-error    2
agent/turn-stopping    2
agent/request          0

其中，agent/pre-step 使用最密集，共有 14 个包监听它，覆盖上下文压缩、Agent Instructions、时间与 tmux 上下文、Skill、Plan Mode、重复工具调用提醒、Subagent、Hook 和持久化检查点等能力。功能虽然不同，它们需要的介入位置却相同：在模型请求发出之前，对当前 Step 的消息和状态进行处理。

pre-step 还参与动态运行时上下文的组装和去重。RuntimeContextProjection 会保存上一份上下文快照，内容没有变化时不重复生成消息；如果运行时上下文从有内容变为空，系统会写入一条清空标记，说明之前保存的快照已经失效。如果这份快照后来被压缩等操作替换，系统会在需要时重新生成新的快照。

agent/request 的独立监听包数量虽然是 0，但这个事件仍有实际使用者。model-selection.ts 中的 installModelSelection() 会在 Agent 作用域监听 agent/request，取得当前调用配置后，再根据运行时选中的 provider 和 model 更新模型配置。由于这段逻辑由运行时入口安装，因此不会表现为一个独立插件包。

到这里，Turn、Step、Inbox 和几个主要扩展点的关系也基本清楚了。把它们放在一起，可以看到 dsh Agent Loop 的整体执行结构：

Turn 如何继续与结束

另一个关键扩展点是 agent/turn-stopping。它发生在 Turn 准备结束的位置：模型当前没有待回复内容，Inbox 中也没有新的 steering 输入。

turn-stopping 本身不通过返回值决定 Turn 是否继续。如果监听器还有工作需要处理，会通过 agent.steer(...) 向 next-step 写入新的输入。所有监听器执行完后，驱动器重新检查 Inbox：

有新输入 → 再执行一个 Step
没有输入 → 关闭 Turn

因此，Turn 是否继续最终由队列状态决定。如果多个插件都希望延长当前 Turn，并各自写入 steering 消息，这些消息会一起进入下一个 Step。

工具结果也可以携带 concludesTurn 标记，表示工具希望当前 Turn 在这个 Step 后结束。不过，如果同一个 Step 又产生了 additionalContexts，或者运行过程中出现新的 steering，驱动器仍会先处理这些内容，等队列排空后再关闭 Turn。

Turn 结束时，turn/end 会记录对应的结束状态：

completed     正常结束
aborted       取消请求打断 Turn，并携带 AgentCancelCause
blocked       pre-step 拒绝 Step
error         结构化失败
max-tokens    至少一个 Step 达到输出 token 上限
interrupted   持久化后端恢复崩溃遗留的 Turn

一个 Turn 中，只要任一 Step 达到输出 token 上限，max-tokens 状态就会保留到 Turn 结束。即使后续 Step 正常完成，最终状态仍会记录为 max-tokens，不会恢复为 completed。interrupted 状态比较特殊。Agent Loop 本身不会写入这个结束状态，它只会在持久化恢复时，用来标记因崩溃而未正常结束的 Turn。这个状态会在下一篇日志机制中再展开。

Step 内的工具调度

模型在一个 Step 中返回多个工具调用后，会交给 tool-calls.ts 中的调度器处理。调度器先按照执行模式对调用进行分类：exclusive 调用形成执行屏障，一次只运行一个；parallel-safe 调用进入有界滚动池，池大小由 maxParallelToolCalls 控制，默认值为 10，设为 1 时则按串行方式执行。

这里的并发只发生在工具派发和工具执行阶段。Policy 检查、工具结果写入日志，以及结果附带的上下文，仍然按照模型给出的调用顺序处理。commitReady() 只会按照原始调用顺序，连续提交已经完成的工具结果：

Call 1  完成
Call 2  未完成
Call 3  完成

此时即使 Call 3 先完成，也要等待 Call 2，最终仍按 1 → 2 → 3 的顺序提交结果。滚动池继续填充时，还会重新检查后续调用的执行模式。如果前面的调用提交后，工具注册表发生变化，例如某个插件把后续工具改成 exclusive，尚未启动的调用会按照新的执行模式形成屏障。

收到取消信号后，已启动的调用会继续执行，并按原顺序提交结果；尚未派发的调用则会补写一对 tool/call和 tool/result 事件，其中结果标记为 TOOL_ABORTED_BEFORE_DISPATCH。这样可以保证每个 tool/call 都有对应的 tool/result，避免日志回放时留下未配对的工具调用。

模型流式输出中途被取消时也有类似处理。如果已有内容呈现给用户，循环会保留一条带 interrupted 标记的 assistant/message，让日志中的会话历史与用户实际看到的内容保持一致。

如果调度器自身出错，系统会停止派发新的调用，等待已启动的调用结束，再把第一个错误交给 Turn 的错误边界；尚未执行的调用不会补写结果。

失败、取消与重新唤醒

Agent Loop 对失败分成两条处理路径。第一类是模型请求失败：模型调用从 ctx.llm 返回 terminal error 或 aborted finish 后，会进入 agent/request-error。监听器可以返回 { kind: 'retry' } 接管恢复，也可以把错误交给后续监听器；如果最终没有监听器处理，本次请求就以失败结束。

dsh-llm-retry 就挂在这个扩展点上。它会记录本次重试，等待退避时间结束后返回 { kind: 'retry' }，再由 Agent Loop 重新发起模型请求。如果退避期间收到取消信号，这次重试也会随之结束。

第二类失败来自中间件、结果处理、工具执行以及其他扩展逻辑，这些异常不会进入 agent/request-error，而是结束当前 Turn。Turn 结束后，Agent Loop 的驱动器仍会回到空闲状态，等待下一次输入唤醒。

除了失败，主循环还要处理主动取消。cancel(cause, options) 会清空 Inbox，除非设置了 keepInbox，随后中止当前的 AbortSignal；如果驱动器本身处于空闲状态，调用 cancel() 不会产生额外动作。

这里还要注意一种情况：取消信号触发后，当前活动可能还没有完全结束。如果这时有新的唤醒输入到达，dsh 会先通过 wakeRequested 记录这次唤醒，等当前执行收敛后再处理。对于这类输入，如果当前 AbortSignal 处于 aborted 状态，消息会被放入 next-turn，避免继续进入正在取消的执行；inject() 这类不会唤醒驱动器的输入仍保留在 next-step。如果这次取消来自运行时销毁（disposed），新的唤醒请求则不会再被保留。

小结

到这里，dsh Agent Loop 的主要结构就串起来了。Turn 管理一次完整执行的生命周期，Step 划分模型请求与工具执行，Inbox 决定新输入进入当前 Turn 还是下一轮，pre-step、request、turn-stopping 和工具事件则把循环中的关键位置开放给插件。

从工程结构上看，这套设计形成了比较清晰的分层：生命周期由 Turn 管理，模型与工具执行由 Step 划分，输入通过 Inbox 驱动循环，插件围绕关键阶段添加能力。

下一篇继续看这条循环写下来的日志：为什么每次请求的 messages 都从日志推导，48 种事件中只有 3 种会进入模型可见部分，以及这套日志结构如何支撑会话恢复、压缩和回放。

参考源码

以下路径以 dsh-v0.1.1-rc.2 为基线：

• packages/core/agent-loop/src/agent.ts

• packages/core/agent-loop/src/tool-calls.ts

• packages/core/agent-loop/src/runtime-context.ts

• packages/core/agent-loop/README.md

• packages/core/agent/src/inbox.ts

• packages/core/agent/src/runtime-types.ts

• packages/core/agent/src/model-selection.ts

• docs/subsystems/core.md

• docs/subsystems/tools.md

• docs/cordis-primer.md