2.2 Agent 生命周期与轮次流程

本章概览：DSH 内核的心脏——agent loop 如何把"一条消息"变成"若干步骤的反复执行"直至安静。本章定义 step/turn、inbox 机制、四个关键 waterfall 与错误恢复瀑布。

术语：步骤与轮次

一个步骤是一次模型请求加上它调用的工具。一个轮次包含零个或多个步骤：它在领取首条输入之前打开，并在不再欠下任何工作时关闭。

出处：docs/architecture.md（deepseek-harness-src/docs/architecture.md）

• step（步骤）：step/start → 模型请求 → 工具调用 → step/end；
• turn（轮次）：turn/start …（0..n 个 step）… turn/end。工具还欠请求、或有新输入到达时继续下一步；否则轮次关闭。

官方轮次流程

turn/start
  claim next-step input plus one queued message
  assemble prompt sections + tool schemas
  -> agent/pre-step                   reject | enter(messages)
     reject, or a first enter rewritten empty -> close the turn with no step
     step/start
     append entered messages as user/message
     derive model history from the log
     agent/request -> llm/stream -> assistant/chunk* -> assistant/message
     tool/call* -> tools/pre-execute -> tools/execute -> tools/post-execute -> tool/result*
     step/end
     tools owe another request, or next-step input arrived -> claim -> next step
  -> agent/turn-stopping
turn/end

出处：docs/architecture.md（deepseek-harness-src/docs/architecture.md）；可视化时序见 docs/agent-lifecycle.md

关键观察：

1. 持久 vs 实时分离：turn/*、step/*、user/message、assistant/*、tool/* 是持久会话事件；agent/* 与 tools/* 是实时扩展点；
2. agent/pre-step 决定模型看到什么：监听器可改写已领取消息或拒绝；首次领取被拒绝或被改写为空时，仍会关闭一个不含步骤的持久轮次，因此日志会记录这次尝试；
3. 每个步骤重新组装提示词片段与工具 schema（system-prompt/assemble）；
4. agent/turn-stopping 是 serial 事件，在轮次正常完成前运行，作为终止检查点。

Inbox：输入如何唤醒驱动器

所有输入（用户消息、steer、注入的上下文、follow-up）通过同一个 inbox 到达驱动器：

• 某些消息立即唤醒驱动器（agent/status → running）；
• 注入的上下文留在 inbox 中，直到另一条消息唤醒它——这是 agent.inject() 的语义基础（"落到下一次获准的请求中"）；
• inbox 的持久投影是 agent/inbox/spliced；实时通知是逐消息的 agent/inbox/inserted / claimed / discarded。

出处：packages/core/agent/README.md（deepseek-harness-src/packages/core/agent/README.md）

Agent 接口与注册表

dsh-agent 定义 Agent 接口与 ctx.agents 注册表，零 loop 依赖（loop 可替换）。核心能力：

• agent.followup(content)：交付下一条 FIFO 轮次输入；
• agent.inject()：注入上下文到下一次获准请求；
• agent.cancel(cause, { keepInbox })：显式取消当前轮次；
• agent.steer()：提交一条普通用户消息（plan 命令用它）；
• 作用域：Agent.ctx 是该 agent 的作用域上下文（dsh-scope，key = agent），通过它注册工具/片段/变量/监听器只对该 agent 生效，dispose 时全部撤销。

创建/恢复走 AgentFactory 契约（由 dsh-agent-loop 实现并 setFactory 注册）：ctx.agents.create(...) / ctx.agents.resume(...) 返回 AgentHandle，其 dispose() 是唯一的消费侧拆除能力。

出处：packages/core/agent/README.md 与 packages/core/agent-loop/README.md

请求失败恢复瀑布

agent/request-error 是失败的模型请求恢复 waterfall：监听器收到请求坐标、规范化失败事实、服务注册的重试策略（若有）与 signal；返回 { kind: 'retry' } 而不调用 next() 即拥有恢复权。官方实现中 dsh-compaction-basic 用它处理"规范性上下文溢出"（canonical context overflow）：恢复发生在"已关闭的失败 step"与"失败的 turn 关闭"之间，只有修剪/总结推进了 surface 替换代次时才开新的重试轮次。

出处：docs/agent-lifecycle.md 与 packages/compaction/compaction-basic/README.md

显式取消与协作式中止

取消是协作式的：每次类型化调用都提供调用者拥有的 AbortSignal。agent/request-error 的监听器可以配合 signal，但不得把它当作"对另一个轮次"的权威。取消语义详见 tool-cancellation Agent Note 与 explicit-turn-cancellation Agent Note。

静默（quiescence）与终止

"等待安静"是 headless 运行器、jobs、follow-up 等所有"等结果"机制的共同语义：loop 在不再欠下任何工作（无待处理输入、无进行中工具、无未决请求）时进入 idle。agent/status 的 running/idle 是区间状态，不是某条消息的结果——自动化调用方若要定义"一次运行"，必须显式界定区间（从消息的持久 inbox 回执到下一个整 agent idle）。

出处：docs/defensive-patterns.md（deepseek-harness-src/docs/defensive-patterns.md）

小结

轮次流程回答了"agent 怎么跑"：输入进 inbox → pre-step 把关 → 步骤循环（请求→工具）→ turn-stopping → 轮次关闭，全程把持久事实写进会话日志、把实时控制留给 agent/* 事件。下一章 2.3 工具执行流水线 深入每个工具调用内部。

参考资料

• docs/architecture.md — Turn flow（deepseek-harness-src/docs/architecture.md）
• docs/agent-lifecycle.md — 轮次/步骤时序图（curated）（deepseek-harness-src/docs/agent-lifecycle.md）
• packages/core/agent/README.md — Agent 接口与事件词汇
• packages/core/agent-loop/README.md — 具体 loop 驱动器
• docs/defensive-patterns.md — "Async state is not synchronous state"