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

## 插件树之后的主循环

上一篇「[Profile 与 Bundle 如何装配运行时](https://mp.weixin.qq.com/s/TWIl3xtB7R-3jaf4jJX21g)」停在插件树挂载完成的位置：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。

```Plain
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 会按照下面的顺序推进，其中部分事件只会在特定条件下写入：

```Plain
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 在这两条队列之上提供了一个基础的入队接口：

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

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

```Plain
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 中，核心介入位置集中在五处：

|   |   |   |   |
|---|---|---|---|
|位置|事件|模式|作用|
|Step 入口|agent/pre-step|waterfall|拒绝 Step，或替换进入它的消息|
|请求组装|agent/request|waterfall|修改模型调用配置|
|请求失败|agent/request-error|waterfall|重试请求，或结束失败处理|
|Turn 收尾|agent/turn-stopping|serial|Turn 关闭前决定是否追加工作|
|工具执行|tools/pre-execute → tools/execute → tools/post-execute → tools/result|waterfall ×3 + emit|放行、包裹、改写结果和观察执行|

这些派发模式来自 Cordis：

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

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

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

```Plain
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 的整体执行结构：

![1.png](https://developer.qcloudimg.com/http-save/yehe-12464096/de337d44d6f697ef6f064150159e8d3d.png)

## Turn 如何继续与结束

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

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

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

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

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

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

```Plain
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()` 只会按照原始调用顺序，连续提交已经完成的工具结果：

```Plain
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`

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

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

一次执行如何被拆成 Turn 与 Step，插件又能在哪些位置介入。

人工智能

开发工具

后端

dsh Agent Loop 采用Turn与Step双层循环架构，通过Inbox队列管理输入，利用pre-step、request-error等扩展点实现插件化干预。工具调度支持并发执行与顺序提交，失败处理区分模型错误与执行异常。该机制为Agent运行时提供灵活可扩展的执行框架，支持会话恢复与状态追踪。

代码解释

中间件

路由

Cordis

Agent

文章

问答

视频

教程

学习中心

腾讯云实验室

直播

竞赛

腾讯云代码分析专区

腾讯iOA零信任安全管理系统专区

腾讯云架构师技术同盟交流圈

腾讯云数据库专区

腾讯云智能顾问专区

腾讯云原生专区

腾讯混元专区

腾讯云TCE专区

腾讯云Lighthouse专区

腾讯云HAI专区

腾讯云Edgeone专区

腾讯云存储专区

腾讯云智能专区

腾讯轻联专区 

腾讯云开发专区

TAPD专区

腾讯轻量云游戏服专区

EdgeOne AI 安全实战专区

腾讯云最具价值专家

腾讯云架构师技术同盟

腾讯云创作之星

腾讯云开发者先锋

腾讯云代码助手

云原生构建

TAPD 敏捷项目管理

Cloud Studio

SDK中心

API中心

命令行工具

涵盖代码开发、场景应用、自动测试全流程，助你从零构建专属AI助手

一站式MCP教程库，解锁AI应用新玩法

聚焦“写作效率、视觉美观与运行性能”三方面进行全面升级，为您提供更高效、稳定的创作环境

社区富文本&Markdown编辑器全新改版上线，欢迎大家体验!

诚挚邀请您参与本次调研，分享您的真实使用感受与建议。您的反馈至关重要，感谢您的支持与参与！

社区新版编辑器体验调研

拆解 dsh：Turn 与 Step 如何组织 Agent 主循环-腾讯云开发者社区-腾讯云

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

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

社区

活动

圈层

关于

腾讯云开发者

热门产品

热门推荐

更多推荐