Agent Loop：DeepSeek Harness 的智能体循环怎么转

agent 包拥有公开约定：Agent 接口、活跃注册表、agent/* 实时事件词汇和 ctx.agents 服务。agent-loop 只是这套约定的默认实现（ctx.agentLoop）。官方规定：扩展插件只依赖 agent 包，绝不直接依赖 agent-loop——所以整个驱动器是可以替换的。这呼应了架构总览里的"不存在特权内核"。

• 步骤（step）：一次模型请求，加上它调用的工具。
• 轮次（turn）：零个或多个步骤。轮次在领取首条输入前打开，在"不再欠任何工作"时关闭。

注意"零个步骤"是真实存在的：输入在 pre-step（步骤前决策）阶段被拒绝或改写为空，循环也会关闭一个不含步骤的持久轮次——这次尝试会留在日志里，不会静默消失。所以"轮次"不等于"一轮一问一答"。

以官方 docs/architecture.zh.md 的 turn-flow 伪代码和 docs/agent-lifecycle.zh.md 时序图为准，一个轮次依次经历：

1. turn/start：轮次打开；
2. 认领输入；
3. agent/pre-step：步骤前决策（waterfall 模式，监听器可以拒绝或改写消息）——它决定模型最终看到什么；
4. step/start：步骤开始，把用户消息追加进日志；
5. 从会话日志派生模型历史（不是单独存的历史，见会话页）；
6. agent/request → llm/stream：向模型发请求并流式接收；
7. 模型回复以 assistant/chunk → assistant/message 落日志；
8. 模型要调工具时：tool/call → tools/pre-execute（审批把关）→ tools/execute → tools/post-execute → tool/result 落日志；
9. step/end：步骤结束。如果还欠工具结果或来了新输入，进入下一步；
10. agent/turn-stopping → turn/end：轮次收尾关闭。

示意图点击放大

其中 agent/pre-step、agent/request、llm/stream、tools/* 都是 waterfall（瀑布）模式——监听器必须调 next() 才能委托下游（规则见 Cordis 框架页）；agent/turn-stopping 是 serial（串行）模式，没有 next()。

所有输入都经过统一 inbox（收件箱）到达，inbox 里有两条有序列表：next-turn（排下一轮）和 next-step（插入当前轮）。对外是同一个发送函数 send(message, target, wakeup)，三个常用叫法是它的预设别名：

• followup：排队到下一轮，并唤醒 agent；
• steer：中途引导，在最近的步骤边界被消费——你在 Agent 干活中途插话走的就是这条；
• inject：注入模型可见上下文，但不唤醒 agent。

示意图点击放大

从可观测状态看，Agent 只有 idle（空闲）和 running（运行中）两个值；running 覆盖整个驱动器排空区间，可以跨连续多个轮次。dispose（销毁）不是第三个状态。实操中怎么用中途引导，见教程《Agent 模式》。

• 请求失败：步骤失败后、轮次结束前，会运行 agent/request-error（waterfall）。监听器返回 { kind: 'retry' } 就触发重试；默认返回 undefined，保持终态不重试。
• 上下文太长：compaction（上下文压缩）通过两个钩子工作——用 agent/pre-step 处理日常的上下文压力，用 agent/request-error 处理"请求直接超出上下文"的溢出错误。

想深入工具执行那段流水线，见工具系统页。

轮次流程里你会看到两类事件名字混在一起，性质完全不同：

• turn/*、step/*、user/message、assistant/*、tool/* 是持久会话事件：落盘的事实，可回放；
• agent/* 是实时协调接口：运行中的信号，不构成历史。

SDK 或外部系统要回放完整交互记录，应该消费 session/event 广播，而不是去订阅实时事件。