适用场景：大模型流式问答、AI Agent 工具调用、实时对话、智能体持续输出场景
核心目标：解决 AI 流式输出断流、卡死、重连失效、页面卡顿、滚动异常、消息乱序等线上常见问题
一、SSE 流式封装（单向流式首选）
1. 技术定位与适用场景
SSE（Server-Sent Events）基于 HTTP 长连接，单向服务端推流，是纯文本流式问答最优方案，主流 OpenAI、DeepSeek、通义千问流式接口默认采用 SSE 协议。
适配场景：AI 单次问答流式输出、日志实时推送、文本持续生成；不适用：双向交互、语音实时对话、频繁客户端上行指令场景。
2. 原生 SSE 痛点（必须封装解决）
-
原生
EventSource不支持主动中断请求，无法终止 AI 生成 -
默认自动重连无次数限制、无间隔控制，网络抖动会疯狂重试
-
无断流检测、无超时处理，容易出现页面假卡死、半截断文
-
不支持自定义请求头（Token 鉴权、自定义参数），原生无法适配业务鉴权
-
无错误分类处理（网络错误、服务端报错、限流、结束标识）
3. 封装核心能力详解
3.1 Abort 主动中断请求
基于 AbortController 实现手动终止流式请求，适配用户暂停生成、切换对话、关闭弹窗场景，避免后台持续推流、前端无效渲染、接口资源浪费。
核心逻辑：创建 SSE 实例时绑定控制器信号，触发中断时关闭连接、清空监听事件、终止请求。
3.2 智能断流处理
针对网络波动、服务端重启、接口超时、响应中断等场景做兜底处理：
-
超时检测：设置最大流式等待超时（默认30s），无数据推送自动判定断流
-
数据校验：校验流式分片合法性，过滤空数据、无效占位分片
-
结束标识识别：识别服务端
done结束字段，主动关闭连接，避免闲置长连接
3.6 可控自动重试
修复原生无限制重试缺陷，实现有限次数 + 递增间隔重试策略：
-
最大重试次数：默认3次，可配置
-
重试间隔：1s、2s、4s 指数递增，避免频繁请求压垮服务端
-
重试拦截：主动中断、接口报错、权限失效时，禁止重试
4. 核心封装 TS 能力清单
支持：自定义请求头、Token 鉴权、主动中断、超时断流、智能重试、事件回调统一管理、资源销毁
二、WebSocket 流式封装（双向 Agent 必备）
1. 技术定位与适用场景
WebSocket 是全双工双向长连接，支持文本/二进制传输，是复杂 AI Agent 核心方案，适配：中途暂停生成、实时追问、工具函数调用、语音双向流、文件实时交互、多轮持续对话场景。
2. 原生 WebSocket 痛点
-
无心跳保活，长时间闲置会被网关/防火墙断开连接
-
无断线重连，网络切换、页面休眠后连接失效
-
消息收发无序，高频推送会出现消息丢失、乱序、堆叠
-
不支持二进制解析，无法适配图片、语音、文件流式传输
-
无消息队列，断网期间发送的消息会直接丢失
3. 封装核心能力详解
3.1 心跳保活机制
解决长连接闲置断开问题，保障 Agent 长期在线：
-
心跳规则：客户端每 15s 发送心跳包，服务端返回心跳响应
-
超时判定：连续2次无响应，判定连接失效，触发重连
-
休眠优化：页面隐藏/最小化时暂停心跳，页面激活后恢复
3.2 智能断线重连
-
触发场景：网络断开、心跳超时、服务端主动断开、页面重连
-
重连策略：最大3次重试，指数递增间隔，重连期间禁止重复发起连接
-
状态恢复：重连成功后，自动补发队列消息、恢复对话流式状态
-
手动销毁：页面卸载、对话关闭时，彻底销毁连接，防止内存泄漏
3.3 消息队列机制
解决消息丢失、乱序、高频堆叠问题，适配 Agent 多工具并发调用场景：
-
发送队列：断网/重连中时，缓存待发送消息，连接恢复后依次补发
-
接收队列：对流式消息做序号排序，保证分片顺序绝对正确
-
队列节流：限制最大队列长度，防止内存溢出
3.4 二进制数据处理
适配多模态 Agent 场景：支持解析 Blob、ArrayBuffer 二进制流，实现语音流式传输、图片实时生成、文件分片推送，自动区分文本消息和二进制消息并分类解析。
三、AI 打字机流式渲染核心能力
1. 技术定位
承接 SSE/WebSocket 流式分片数据，实现逐字动态渲染，模拟真人打字效果，同时解决高频渲染导致的页面卡顿、滚动错位、文字重叠问题，是 AI 对话页面的核心交互体验。
2. 核心功能详细说明
2.1 分片逐字渲染
大模型流式返回为碎片化文本（单字/词语/短句分片），不直接拼接渲染，采用逐字渐进渲染：
-
拆分流式分片：将后端返回的 chunk 拆解为单字/字符
-
可控渲染速度：支持自定义打字速度，避免过快闪烁、过慢卡顿
-
特殊内容兼容：支持 Markdown、代码块、公式、标点符号正常渲染，不打乱格式
2.2 对话缓存管理
-
实时缓存：每渲染一个字符，同步缓存当前对话完整内容
-
断点续渲：断流、重连后，基于缓存继续渲染，不重复生成、不丢失内容
-
历史回溯：支持对话切换、页面刷新后，还原上次流式渲染结果
2.3 自动滚动到底部
解决流式渲染时滚动条错位、用户需要手动滑动的问题，适配长对话场景：
-
智能判定：仅当用户处于页面底部时，自动跟随滚动；用户主动上滑查看历史内容时，锁定滚动位置，不干扰浏览
-
平滑滚动：使用 requestAnimationFrame 实现流畅滚动，无卡顿闪烁
-
容器适配：兼容固定高度对话容器、自适应高度容器
2.4 渲染防抖与性能优化
高频流式分片（每秒10+分片）会触发大量 DOM 更新，导致页面卡顿、CPU 占用过高，通过防抖优化：
-
批量渲染防抖：短时间内多个分片合并渲染，减少 DOM 操作次数
-
异步渲染：基于微任务拆分渲染逻辑，阻塞主线程
-
结束兜底：流式结束后，统一校正最终文本，修复分片拼接错乱问题
-
终止清空：切换对话、中断生成时，立即终止当前渲染队列，避免残留渲染
3. 常见问题兜底方案
-
分片空白：自动过滤空字符、换行冗余，优化排版
-
渲染卡顿：限制最大单次渲染字符数，分片分批渲染
-
文字闪烁：关闭频繁 DOM 重置，采用增量更新模式
四、SSE vs WebSocket 流式场景最终选型规范
| 业务场景 | 推荐方案 | 核心原因 |
|---|---|---|
| 纯文本AI问答、文案生成、日志推送 | SSE | 轻量、自带重连、开发简单、资源开销低 |
| 可暂停/继续、实时追问、工具调用Agent | WebSocket | 双向通信，支持客户端上行指令 |
| 语音对话、图片生成、文件流式传输 | WebSocket | 支持二进制数据传输 |
| 长期在线、多轮连续交互智能体 | WebSocket | 心跳保活，连接稳定性更强 |
五、工程化落地总结
-
SSE 核心价值：极简单向流式，完美适配 80% 的普通 AI 问答场景，重点解决鉴权、中断、断流重试三大问题；
-
WebSocket 核心价值：支撑复杂双向 Agent 交互，心跳、重连、消息队列是生产环境必备兜底能力；
-
打字机渲染核心价值：统一流式交互体验，解决性能、滚动、渲染错乱问题，是 AI 产品体验的核心壁垒。