DeepSeek Harness Agent 生命周期详解

DeepSeek Harness Agent 生命周期是一套事件驱动循环：用户的 Follow-up 先进入 Inbox，Driver 启动 Turn，agent/pre-step 决定是否进入下一步，系统组装 Prompt 并接收模型的流式响应，工具调用又可能触发新的 Step。只有模型不再请求工具，或流程进入错误、Abort、Cancel 等终止分支，一个 Turn 才真正结束。

本文基于 DeepSeek Harness 官方 Agent 生命周期文档 二次创作，目标是帮助开发者排查 Agent 卡住、重复请求和工具未执行等问题，而非逐行翻译时序图。

先区分 Turn 与 Step

Turn 是由用户或系统输入触发的完整响应周期；Step 是一次模型请求及其关联工作。一个 Turn 可以包含多个 Step，因为模型可能先调用工具，再根据工具结果继续请求模型。

这也解释了常见疑问：为什么只发了一条消息，却看到多次 LLM 请求？分析用量、Provider 报错和工具循环时，应统计 Step；分析对话级输入与完成状态时，则应观察 Turn。

从 Agent Inbox 到 Turn Start

用户的 Follow-up 会先排入 Agent Inbox。Driver 被唤醒后，把 agent/status 更新为 running，并发出 turn/start。随后，它领取下一 Step 和一个排队中的 Prompt。

队列把“消息已经到达”与“Agent 开始执行”分开。消息可以先等待，界面也能通过实时状态告诉用户 Agent 当前处于什么阶段，而无需重写已经持久化的对话。

agent/pre-step 决策点

模型请求开始前，运行时以 Waterfall 方式触发 agent/pre-step。处理器可以拒绝当前 Step，也可以向其中加入消息。Step 获准进入后，系统发出 step/start，写入相关用户消息，并开始组装 Prompt。

这是策略和编排的重要接缝。处理器可以影响本次模型输入，但必须区分“修改持久历史”和“只改变当前请求”。关于 Session Event 与实时 agent/* Event 的界线，可参考 DeepSeek Harness 架构解析。

模型请求与流式回复

Prompt 组装完成后，Harness 向所选 LLM Provider 发起请求。Assistant Chunk 可以先以流式形式到达，之后才形成完整 Assistant Message。

界面可以立即展示 Chunk，而 Session 只应记录回放需要的持久消息事件。如果 UI 没有更新但 Provider 仍在响应，应检查流处理和 Client 边界；如果请求根本没有成功，则优先检查密钥、Endpoint 与 Request Error 分支。模型配置基础可查看 DeepSeek Harness 模型服务商配置。

工具调用如何调度

完整的 Assistant 响应可能包含 Tool Call。运行时会根据 Execution Mode 对工具分类，并按需要使用 Barrier 或 Rolling Pool。每个工具调用还会经历 Pre Execute、Execute 与 Post Execute 阶段。

执行模式决定并发和顺序。只读查询可能适合并行，修改状态的命令则可能需要屏障。工具作者要准确声明行为，使用者仍应检查操作目标与授权范围。

工具结果会进入当前上下文。如果 Agent 需要解释结果或继续决策，同一 Turn 会进入下一个 Step。可在 DeepSeek Harness 工具目录 中查看 Shell、文件、终端、Subagent 等工具类别。

请求重试、Abort 与 Cancel

模型请求失败时，agent/request-error 可以返回 Retry Action。重试策略应区分临时网络故障与无效密钥、错误参数、确定性工具失败。后几类问题不断重试，只会增加延迟和费用。

Abort 与 Cancel 属于终止控制路径，应停止等待中的工作、释放资源，并让 Agent 回到可解释状态。工具只有在真正观察传入 Signal 时才支持协作式取消；仅仅接收参数、却从不检查它，并不能中断长任务。

Session Event 与实时状态有什么不同

生命周期中有两条互补通道：

• session/event 保存回放、历史和审计所需的事实；
• agent/* 负责实时控制与运行状态。

用户消息、Assistant Message 和需要保留的 Tool Result 可以进入追加式会话历史；running 状态、流式进度与拦截决定通常属于实时状态。混用两者，可能造成回放内容重复，或重启后缺少关键事实。

Agent 卡住时如何排查

建议按事件顺序缩小范围：

1. 确认 Follow-up 是否进入 Inbox；
2. 查找 running 状态和 turn/start；
3. 查看 agent/pre-step 是否拒绝或修改了 Step；
4. 确认 Prompt 已组装并发往 Provider；
5. 区分流式 Chunk 与最终 Assistant Message；
6. 查看工具执行模式、Barrier 和完成事件；
7. 判断错误处理最终选择 Retry、Abort 还是 Cancel。

这套顺序能把“Agent 不动了”定位为某个具体边界。跨进程调用异常，则继续查看 API Gateway 指南。

官方原文

本文依据 DeepSeek Harness 官方 Agent 生命周期文档（中文） 独立整理，核对日期为 2026-08-20。当前事件顺序请以官方时序图为权威参考。