第7章 SSE 流式协议：meta / chunk / step_break / done

从后端事件到前端气泡——一次流式对话的完整旅程

7.1 本章导读

前面几章都在后端打转。本章我们把视角拉到浏览器：模型逐字输出的文字、工具调用的卡片、最终的完整消息——它们如何通过 SSE（Server-Sent Events）从 ReactLoopAgent 一路流到你的眼前？这个协议看似简单，但本项目在"多步工具调用"场景下踩过三个连环 Bug（文本乱码、工具卡不更新、气泡覆盖），本章会完整复盘。

7.2 为什么是 SSE 而不是 WebSocket

Agent 对话是典型的"用户发一次、服务端推一串"——单向推送，SSE 是最小可用方案。Spring 端用 SseEmitter，前端用原生 EventSource 或 fetch 流。

7.3 八种事件的完整序列

POST /api/agent/stream 返回的事件流：

7.4 step_break：为什么必须是独立事件

这是本协议最关键的设计决策，来自真实踩坑。最初的想法是"在 chunk 文本里混入特殊字符串标记工具边界"，结果在多步工具调用时出了乱码。

修复方案是协议化：把"工具边界"从文本流中抽出来，变成独立的 SSE 事件。完整链路：

7.5 done 事件：全量消息的必要性

为什么流式推送了 chunk，最后还要在 done 里带全量 messages？因为流式过程只覆盖"文本增量"，工具卡片的最终状态（成功/失败、完整结果）需要从事件日志重建：

// done 事件携带的 messages 结构（简化）
{
  "messages": [
    { "role": "user", "content": "列出目录文件" },
    { "role": "assistant", "content": "我先查看一下目录。" },
    { "role": "tool", "callId": "call_1", "name": "shell_execute",
      "status": "success", "result": "..." },      // ← 流式阶段只有 status=running
    { "role": "assistant", "content": "目录下有 3 个文件..." }
  ]
}

前端收到 done 后用这份全量消息替换本地状态——这就是第6章说的 AgentCollectNode 必须投影 ToolCall/ToolResult 的原因：没有它们，done 里就没有 tool 角色消息，前端会把 step_break 阶段创建的工具卡片清掉，卡片永远停在 running。

7.6 后端事件到 SSE 的映射总览

7.7 小结与下一章预告