为什么消息数组 + loading 状态不够用？

因为 Agent 场景的真实状态包含：步骤进度、工具调用回执、重试与取消、断线重连的补事件，以及并发子任务的聚合。用几个 boolean 很快就会失控，导致 UI 状态与真实执行状态不一致。

Event Sourcing 会不会太重？

对“需要可重放调试”的聊天产品，事件流反而更轻：把复杂度从“到处同步状态”变成“只追加事件 + 用 reducer 计算状态”。你可以从最小事件集合做起，不必一开始做完整工作流引擎。

怎么处理事件重复到达？

每条事件都带 `runId + seq`（或 `eventId`），store 里做去重；渲染层永远从 store 的派生状态读，不直接根据流式回调改 DOM。

事件里要不要存完整工具参数？

不建议放在前端可见事件里。前端事件只存摘要与可展示信息；完整参数应在后端事件日志（脱敏）中保存，避免泄露与滥用。

前端架构状态管理Event SourcingAgent可观测

聊天式产品的前端状态管理：从消息到工具事件（Event Sourcing 思路）

聊天式 AI 产品的“状态”远不止消息列表：还有工具调用、步骤状态、重试、取消、断线重连与可重放调试。本文给出一套可落地的前端事件模型：把消息、工具与运行状态统一成事件流，用 reducer 构建可重放 store，解决重复事件、并发子任务与 UI 派生视图的复杂度。

2026年3月4日

Synthly 团队

预计阅读 14 分钟

📷 Photo by Jakub Zerdzicki via Pexels

你的 UI 之所以“越做越乱”，通常是因为状态模型错了

聊天式产品初期往往是：

一个消息数组
一个 isLoading
一个 currentResponseText

但一旦进入 Agent 阶段（工具调用 + 多步骤 + 可取消/可重试），你会发现：

同一条“回答”内部有多个阶段
同一条“工具”会开始/结束/失败/重试
同一任务可能断线重连，需要补流
你需要把过程展示给用户（但不能泄密）

这时如果继续堆局部状态（local state），会出现典型事故：

UI 显示“完成”，但后端还在跑
UI 显示“失败”，但其实已成功写入（重复执行风险）
重连后消息顺序错乱、重复渲染

解决思路：从“状态管理”升级为“事件管理”。

如果你正在做流式 UI，建议配合阅读：

流式输出 UI 设计：让用户看到“进展”，而不是泄露“思考过程”

一、把聊天跑一次任务：从“消息”变成“Run”

建议先引入一个关键概念：Run（一次任务运行）。

一次用户输入 → 对应一个 run
run 内部会产生多条事件：消息、步骤、工具、错误、完成

这样你就不会把“聊天消息”与“执行过程”混在一起。

最小数据结构：

threadId：会话
runId：一次运行
events[]：事件追加日志
derivedState：由 reducer 派生出的可渲染状态

二、事件模型：最小事件集合与字段规范

1）最小事件类型

USER_MESSAGE_CREATED
ASSISTANT_MESSAGE_DELTA
STEP_STATUS_CHANGED
TOOL_CALL_STARTED
TOOL_CALL_FINISHED
RUN_FAILED / RUN_SUCCEEDED

你可以先从这 7 种开始，后续再细化。

2）每条事件必须具备的“去重与排序字段”

eventId：全局唯一（或 runId + seq）
seq：单 run 单调递增
ts：时间戳

为什么 seq 必须有？因为：

网络会乱序
事件可能重放
你需要补流

3）事件载荷（payload）的安全原则

前端事件：只放可展示且不敏感的摘要
调试需要的敏感细节：放后端日志（脱敏后）

这点与“流式 UI 不泄密”是同一套红线。

三、Store 设计：用 reducer 让状态可重放

1）为什么 reducer 是关键

如果你把事件“直接驱动 UI”，你会得到不可重现的 bug：

某次乱序导致 UI 状态错了
重连补事件导致重复
并发子任务导致覆盖

而 reducer 的好处是：

事件顺序可控（按 seq 排序）
去重可控（按 eventId）
状态可重放（给一串事件就能算出同样的 UI）

2）一个可落地的 TypeScript 形态（伪代码）

type EventBase = {
  eventId: string;
  runId: string;
  seq: number;
  ts: number;
};

type ChatEvent =
  | (EventBase & { type: 'USER_MESSAGE_CREATED'; text: string })
  | (EventBase & { type: 'ASSISTANT_MESSAGE_DELTA'; delta: string })
  | (EventBase & {
      type: 'STEP_STATUS_CHANGED';
      stepId: string;
      status: 'queued' | 'running' | 'succeeded' | 'failed';
    })
  | (EventBase & { type: 'TOOL_CALL_STARTED'; toolCallId: string; tool: string; summary?: string })
  | (EventBase & {
      type: 'TOOL_CALL_FINISHED';
      toolCallId: string;
      ok: boolean;
      summary?: string;
      errorType?: string;
    })
  | (EventBase & { type: 'RUN_SUCCEEDED' })
  | (EventBase & { type: 'RUN_FAILED'; errorType: string; userMessage: string });

type DerivedRunState = {
  status: 'running' | 'succeeded' | 'failed';
  answerText: string;
  steps: Record<string, { status: string }>;
  tools: Array<{ tool: string; ok?: boolean; summary?: string; errorType?: string }>;
  lastSeq: number;
};

function reduceRun(prev: DerivedRunState, e: ChatEvent): DerivedRunState {
  if (e.seq <= prev.lastSeq) return prev; // 最小保护：seq 回退直接忽略
  const next = { ...prev, lastSeq: e.seq };

  switch (e.type) {
    case 'ASSISTANT_MESSAGE_DELTA':
      next.answerText += e.delta;
      return next;
    case 'STEP_STATUS_CHANGED':
      next.steps = { ...next.steps, [e.stepId]: { status: e.status } };
      return next;
    case 'TOOL_CALL_STARTED':
      next.tools = [...next.tools, { tool: e.tool, summary: e.summary }];
      return next;
    case 'TOOL_CALL_FINISHED':
      next.tools = next.tools.map((t) =>
        t.tool === e.tool ? { ...t, ok: e.ok, summary: e.summary, errorType: e.errorType } : t,
      );
      return next;
    case 'RUN_SUCCEEDED':
      next.status = 'succeeded';
      return next;
    case 'RUN_FAILED':
      next.status = 'failed';
      return next;
    default:
      return next;
  }
}