线上流式 FAQ"首尾截断"根因剖析与架构重构实践

智能 FAQ 的 DB 检索链路在服务端会以 SSE 长连接持续推送 message 事件。业务契约中，每个事件携带当前时序下的全量累积快照（而非纯增量 delta），前端需在打字机节奏下将其合并为可展示的 HTML 内容。

两类异常在压测与生产环境复现率随并发与轮次递增而上升：现象 A 破坏首屏信任感，现象 B 使多轮对话出现"幽灵半成品气泡"。二者共同特征是——抓包可见完整，肉眼看见残缺。

旧版解析器在每一帧 message 事件的打字机副作用末尾，存在致命边界处理：

// 位于每一帧 message 事件解析的打字机副作用末尾
data.event = 'message_end';
resetStreamingState();
isFinishedReplying.value = true;

物理机制：SSE 基于 HTTP Chunked Transfer Encoding 的单向长连接。服务端在一个持续 Connection 中会高频推送多个 message 事件，每个事件携带全量累积快照。

逻辑漏洞：旧逻辑将单个 message 帧内打字机循环的结束，等价为了整个会话流的终结（message_end），从而执行 resetStreamingState()。当后续真正的权威终态信号到达时，上下文已被清空，后续分片被无视——直接触发现象 B。

前端通过 async/await 结合 setTimeout 封装打字机渲染器，并发模型存在严重缺陷：

// 简化的旧版并发模型
async function onmessage(event) {
  const data = JSON.parse(event.data);
  for (let i = 0; i < data.content.length; i++) {
    await sleep(30); // 引入宏任务延迟
    sharedBuffer.value += data.content[i]; // 共享变量写入
  }
}

onmessage 同步触发，但内部 await 将后续执行挂入微/宏任务队列。当网络帧间隔 小于 打字机单帧间隔（如 30ms）时，前后两个 onmessage 产生的打字机循环并发运行，同时向同一响应式累加器写入。缺乏互斥或取消机制，时序交错导致覆盖与重叠——贡献现象 A 与 B。

处理 content（展示快照）与 answer（累积权威值）双字段合并时，旧版采用：

if (content.length > answerVisible.length) {
  replace();
}

大模型流式输出中，网络抖动或反向代理缓存可能使 content 丢弃前缀（如吐出断头文本 ustomers...）。尽管物理长度大于当前 answerVisible.length，却是非法快照。简单长度覆盖直接导致现象 A，破坏状态机最终一致性收敛。

message_end 到达后触发连接终止：controller.abort() → onclose() → cleanupRequest()。cleanupRequest 将 isFinishedReplying 置为 true，UI 输入框解锁。若用户立即发起下一轮，新请求的 resetStreamingState() 会强制中断上一轮尚未执行完毕的打字机宏任务，导致前一条消息视觉上永远缺失末尾片段。

为彻底根治上述问题，我们废弃 UI 层堆叠补丁，转向架构分层解耦、目标驱动状态机及代际隔离的闭环重构。

将耦合在 3900 行 index.vue 中的流式处理算法完全剥离，封装为独立 Composable（src/composables/useChatStreamMessage.js），实施单一职责原则（SRP）。

为避免 Composable 初始化时页面依赖尚未声明，设计延迟依赖注入（DIP）：通过 getDeps() 闭包在运行时动态获取 messages、addAIMessage、scrollToBottom，实现状态管理与视图层完全解耦。

// useChatStreamMessage.js 核心设计
export function useChatStreamMessage(getDeps) {
  // 运行期通过 getDeps() 动态获取组件层的 messages, addAIMessage, scrollToBottom
  // 实现状态管理与 UI 视图层的完全解耦
}

改变"每来一个网络帧就强行重置并重建 DOM"的陈旧设计，引入目标驱动（Target-Driven）动画引擎：

引入隐式分布式锁——代际号机制，彻底阻断多重异步宏任务对共享变量的竞态写入：

const dbTypingState = reactive({
  generation: 0,
  targetContent: ''
});

async function startTypingLoop() {
  dbTypingState.generation += 1;
  const currentGeneration = dbTypingState.generation;

  for (let i = 0; i < dbTypingState.targetContent.length; i++) {
    if (currentGeneration !== dbTypingState.generation) {
      console.warn('[Stream] 侦测到新一代异步流，当前过时循环强制退出');
      break;
    }
    await sleep(20);
  }
}

当新 message_id 到达或执行重置时，generation 递增；旧异步循环在下一帧唤醒时命中边界条件并安全自销毁。

双字段覆盖策略从无序长度对比升级为偏序关系的包含性校验：

const canUseContentSnapshot =
  normalizedContent.length > answerVisible.length &&
  (!answerVisible || normalizedContent.includes(answerVisible));

只有满足单调递增且不破坏前缀基底的快照才被允许采纳，拒绝"更长但断头"的非法帧。

4.1 沉淀的工程设计原则

4.2 体系待提升项

流式 FAQ 的"首尾截断"不是 CSS 问题，也不是某一行 += 的笔误，而是把传输帧、动画帧和终态帧当成同一件事时必然发生的系统性故障。分层、目标驱动与代际隔离，是让长连接 UI 真正可收敛的三根支柱。