[!info] related notes

• 所属 MOC: LLM Streaming MOC
• 对比: Delta Stream, Full State Stream
• 综合对比: Delta Stream vs Append Stream
• 输出模型: LLM 输出四层模型
• 前端消费: 前端 SSE 消费

Append Event Stream

一句话定义

Append Event Stream 是 LLM 流式的增强语义模式——每次追加一个新的结构化事件（文本、工具调用、状态变化、结构化数据），前端通过 events.push(event) 或 reducer 分发消费。适合 Agent / workflow / function calling 场景。

核心机制

数据模型

每个事件是一个独立的结构化记录，可能有不同的类型和语义：

{ "type": "message.append", "role": "assistant", "content": "你好" }
{ "type": "tool_call", "name": "symptom_extract", "args": {...} }
{ "type": "extracted_info", "data": { "symptom": "头痛" } }
{ "type": "message.append", "content": "根据你的描述，可能需要进一步确认。" }

前端操作

// 方式一：直接追加到事件列表
events.push(event)

// 方式二：按类型分发到不同状态
switch (event.type) {
  case "message.append":
    messages.push(event.content)
    break
  case "tool_call":
    toolCalls.push(event)
    break
  case "extracted_info":
    extractedInfo = event.data
    break
}

核心模型是：整个 AI 流程不断产生新的结构化事件。事件流 = AI 任务执行过程的日志。

协议示例

{ "type": "message.started", "id": "m1", "role": "assistant" }
{ "type": "message.append", "message_id": "m1", "content": "我先帮你分析一下症状。" }
{ "type": "tool_call.started", "id": "t1", "name": "symptom_extract" }
{ "type": "tool_call.completed", "id": "t1", "result": {...} }
{ "type": "extraction.updated", "data": { "symptoms": ["头痛", "发热"] } }
{ "type": "message.append", "message_id": "m1", "content": "根据你的描述..." }
{ "type": "message.completed", "id": "m1" }

最小场景

Agent 系统的多步骤 UI：

function onEvent(event: StreamEvent) {
  switch (event.type) {
    case "message.append":
      addMessage(event.content)
      break
    case "tool_call":
      showToolCallStatus(event.name, "running")
      break
    case "extracted_info":
      updateInfoPanel(event.data)
      break
    case "status":
      updateWorkflowStep(event.step)
      break
  }
}

适用场景

场景	说明
LangChain callbacks	Agent 执行过程的事件流
Dify workflow	工作流节点执行状态
Agent 编排 UI	多步骤 AI 流程展示
Function calling	工具调用与结果返回
结构化信息提取	症状提取、实体识别等

优势

• 天然支持 message list：每个 append 事件就是一个消息项
• 更适合 multi-turn UI：事件流本身就是对话历史
• 可扩展：轻松添加 tool_call、metadata、citation、error 等事件类型
• 接近 event log：方便日志记录、回放、调试

局限

• UI 拼接复杂：前端需要 reducer 分发，不是简单的 buffer 追加
• 不适合 token 级打字机效果：粒度比 Delta 粗，逐字动画需要额外处理
• 没有统一事件规范时容易混乱：事件类型、数据结构需要团队约定

边界与易混淆点

• Append 和 Delta 可以组合：外层用 Append 管理流程事件，内层用 Delta 管理文本生成。
• Append 不等于”每次追加整条消息”：append 的是一个事件片段，不是完整消息。
• 适合 Agent 但不是只有 Agent 能用：任何需要表达”AI 流程中产生了什么”的场景都适合。