# Chat 流式生成动画改造经验 本文记录 `src/components/chat` 里本次文字生成、图表生成、滚动稳定性的改造经验。重点不是复盘代码行数，而是总结后续继续调整时应遵守的工程边界和交互原则。 ## 目标 - 文本生成要有连续感，避免 token 直接到达导致忽快忽慢。 - 已生成内容必须稳定，不能反复淡入、重排或闪烁。 - 图表和工具调用插入时不能让“分析结果”边框剧烈抖动。 - 底部自动滚动要跟随，但不能每个 token 都强制贴底。 - 动画应辅助理解，不能比内容本身更抢眼。 ## 文本流式生成 ### 经验结论 不要把后端 token 到达节奏直接暴露给 UI。后端 token 通常不均匀，前端如果每个 token 都立即渲染，会出现文字跳动、滚动频繁、动画看不出来等问题。 更稳的做法是类似 Vercel AI SDK `smoothStream` 的思路： - token 先进入缓冲区。 - 前端按固定节奏释放 chunk。 - chunk 尽量按词、短语、标点边界切分。 - 当缓冲积压较大时，自适应加快 drain，避免显示落后真实输出太多。 当前实现采用： - `TOKEN_PLAYBACK_INTERVAL_MS = 16` - 小缓冲按较短 chunk 输出。 - 大缓冲最多每帧释放 `160` 字符。 - 中文优先使用 `Intl.Segmenter("zh", { granularity: "word" })`。 - 非 token 事件前强制 flush，保证工具调用、done、error 的顺序正确。 ### 踩坑 - 只做 `setTimeout(120ms)` 批量 flush 不够。它只是减少更新次数，并不能形成稳定播放节奏。 - interval 太小，例如 `8ms`，浏览器调度不一定更稳定，反而可能增加 React 更新压力。 - 中文按 `Intl.Segmenter` 的单个词输出会显得慢，必须结合缓冲长度动态放大 chunk。 - `done`、`error`、`tool_call` 前如果不 flush，会造成文本和结构事件顺序错乱。 ## Markdown 动画 ### 经验结论 Markdown 是流式文本动画里最容易出问题的部分。原因是 `ReactMarkdown` 每次都会重新解析完整内容，原始 Markdown 字符索引和最终 DOM 文本节点索引不一致。 典型例子： - `**加粗**` 的原始长度包含 `**`，但可见文本不包含。 - 列表符号、链接语法、代码块围栏都可能影响原始索引。 - 新增文本可能落在 `p`、`li`、`strong`、`code` 等不同节点里。 因此不要简单用原始 `text.length` 或 `fadeFrom` 去对应 Markdown 渲染后的 DOM 文本。 当前策略： - Markdown 仍完整解析，保证格式正确。 - 在 rehype 阶段处理 AST。 - 从 AST 尾部反向找最后的可见 text node。 - 只给最后一段尾部文本加动画。 - 每次最多动画最后 `48` 个字符，避免大 chunk 整段闪烁。 ### 踩坑 - 用 `text.length` 作为 React key 会导致整段 Markdown remount，所有文本都会重新淡入。 - CSS animation 和 Web Animations 同时作用在同一个 span 上，会出现闪烁或动画重启。 - 在 render 阶段读写 ref 会触发 React hooks lint 规则，也容易产生不可控渲染。 - 反向遍历 AST 时拆分 text node 要注意顺序。使用 `unshift` 时应先插入动画尾巴，再插入稳定文本，最终 DOM 才是“稳定文本在前，动画尾巴在后”。 ## 当前文字动画建议 推荐保留轻量动画： - 使用 Web Animations，在 `useLayoutEffect` 中启动，避免先完整显示一帧再裁切。 - 使用 `clip-path` 做左到右 reveal。 - 叠加轻微 opacity：当前约 `0.46 -> 1`。 - 时长控制在 `120ms - 260ms`。 不要做： - 外层整段 `motion.div` 淡入。 - 每次流式更新都改变 key。 - 对整个 Markdown AST 的新增范围大面积包 span。 - 在生成中对已有文本重复动画。 ## 滚动和边框稳定 ### 经验结论 滚动条在最底部时，内容增长会不断改变 `scrollTop`。如果每个 token 都执行 `scrollTop = scrollHeight` 或 `scrollIntoView`，最后一个 assistant turn 的边框会产生明显抖动。 当前策略： - 生成中不再每个 token 精确贴底。 - 底部保留生成缓冲区，当前约 `180px`。 - 只有缓冲被消耗到阈值后才恢复滚动。 - 用户离开底部附近后，不再强制自动跟随。 - 使用 `scrollbar-gutter: stable` 减少滚动条出现/消失造成的宽度变化。 ### 踩坑 - “锁最大高度”不是正确方向。问题不是高度无限增长，而是底部锚定过于频繁。 - 每 token 自动滚动会把视口不断向下推，视觉上就是边框抖动。 - 滚动判断阈值要和底部缓冲一致，否则缓冲刚出现就被判断为“离开底部”。 ## 图表生成 ### 经验结论 图表不能等数据到达后突然插入。图表生成应先占位，再 crossfade，再让图表内部动画接管。 当前策略： - 工具调用 pending 时使用固定尺寸 `ChartGenerationSkeleton`。 - 图表真实数据到达后，继续短暂保留 skeleton overlay。 - ECharts 在 skeleton 下方淡入。 - 容器尺寸保持一致，避免边框高度突变。 - ECharts 内部使用 enter/update 动画，而不是外层布局动画。 图表类型动画建议： - 折线图：平滑 enter，面积渐显。 - 柱状图：柱子从基线增长，并对数据点轻微 stagger。 - 饼图：使用 expansion/sweep 类进入动画。 - update 动画要短于 enter 动画。 ### 踩坑 - 只给外层图表卡片 fade in 不够，插入瞬间仍可能造成内容跳变。 - skeleton 和最终图表尺寸不一致，会导致边框先长再缩。 - 图表更新时不要重建组件，尽量让 ECharts diff 数据并执行内部 transition。 ## 状态提示 “正在生成”状态是有价值的，应该保留。它承担了部分动感和系统状态反馈，不需要让文本动画本身过于夸张。 推荐： - 状态放在“分析结果”标题行右侧。 - 使用小尺寸、低干扰的 pulsing dots。 - 不使用末尾光标，避免和业务文本混在一起。 ## 验证建议 每次调整流式动画后至少跑： ```bash npx eslint src/components/chat/AgentMarkdownBlock.tsx src/components/chat/AgentTurn.tsx src/components/chat/ChatInlineChart.tsx src/components/chat/AgentWorkspace.tsx src/components/chat/GlobalChatbox.tsx src/components/chat/hooks/useAgentChatSession.ts npx tsc --noEmit npm test -- src/components/chat/hooks/useAgentChatSession.lifecycle.test.tsx src/components/chat/hooks/useAgentChatSession.actions.test.tsx src/components/chat/AgentWorkspace.test.tsx src/components/chat/ChatInlineChart.test.ts --runInBand ``` 人工验证重点： - 长中文回答是否明显落后后端真实速度。 - Markdown 加粗、列表、代码块是否乱序。 - 底部自动滚动时“分析结果”边框是否抖动。 - 工具调用 pending 到图表出现时是否有高度跳变。 - 用户手动上滚后是否停止强制跟随。 ## 后续调整原则 1. 先调节 token playback，再调动画。 2. 动画只作用于新增内容，已有内容不能重播。 3. Markdown 动画优先保守，宁可弱一点，也不能破坏文本顺序。 4. 图表和工具调用先稳定布局，再考虑视觉效果。 5. 滚动跟随要有缓冲，不能逐 token 贴底。