streamed markdown playback：完成事件不再抢跑展示动画

buffin-ai/buffin · 14dcbfe...58aca59 · 2026-07-17 · 自包含，读完即弃

写法说明：本文按「逐跳走读」展开——每个机制都给真实代码片段（取自分支、经裁剪，青色斜体注释为解读所加，灰色斜体是源码原注释的保留或意译），每段代码标注所在文件。每条旅程结尾有一张「排查路标」：将来出问题时，症状对应去哪个文件看哪个函数。

1TL;DR

这次修复把流式 Markdown 的事实到达速度和屏幕播放速度拆开。Incremark 不再同时负责解析与打字节拍；新的 usePlaybackBuffer 持有展示游标，以固定 cadence 释放权威文本。

message.completed 只封口输入。只要当前文本曾经处于 revealing，缓冲区就继续 draining，直到展示游标追上完整文本，adapter 才调用 finalize()。

视觉层只给本帧最新释放的 AST 尾部添加一个 fade chunk，避免多个半透明 suffix 同时留在 DOM 里形成拖影；历史回放与 reduced-motion 路径仍然静态显示。

2一条文本的播放旅程

从 provider 文本抵达 renderer 开始，顺着展示游标、Incremark parser 和 fade span 走一遍，就能看到这次改动真正移动的职责边界。

2.1播放缓冲区接管展示时钟

以前 adapter 把权威文本立即 append 给 Incremark，再用 Incremark typewriter 控制显示。完成态一旦触发 static 或 finished，调用方会发出 skip，尚未播放的尾部直接跳到最终文本。

缓冲区的参数共同定义感知速度：首帧先放 2 个字符，此后每 72ms 前进一步。积压越长，每步越大，但被限制在 2 到 12 个字符之间。

const TICK_MS = 72
const INITIAL_CHARS = 2
const MIN_CHARS_PER_TICK = 2
const MAX_CHARS_PER_TICK = 12
const TARGET_DRAIN_TICKS = 16

function nextRevealLength(current: number, target: number): number {
  const remaining = target - current
  const step = Math.min(
    MAX_CHARS_PER_TICK,
    Math.max(MIN_CHARS_PER_TICK, Math.ceil(remaining / TARGET_DRAIN_TICKS)),
  )
  return Math.min(target, current + step)
}

finished 与 playback 不再被压成一个布尔开关。完成事件只在“此前确实正在 revealing”时开启内部 draining；因此 live part 会继续前进，静态历史则从一开始就完整显示。

function beginsDrain(
  finished: boolean,
  previousFinished: boolean,
  previousPlayback: ThreadPlaybackMode,
): boolean {
  return finished && !previousFinished && previousPlayback === 'revealing'
}

if (beganDrain) drainingRef.current = true
const reveal = shouldReveal(playback, drainingRef.current)

if (!reveal) {
  displayedLengthRef.current = text.length
  setFrame((current) => settledFrame(current, text))
}

非前缀 replacement 走另一条路径：它代表权威内容改写，而不是 suffix 到达。此时缓冲区立即停表并落到完整文本，避免把旧文本的游标套到新内容上。

2.2Adapter 只消费展示帧

adapter 仍然拥有 Incremark parser 的生命周期，但输入已经从 text 换成 displayedText。每次游标前进只 append 新释放的 suffix；只有展示文本等于权威文本时，完成态才真正 finalize parser。

const frame = usePlaybackBuffer(text, playback, finished)
const displayedText = frame.text
const displayFinished = finished && displayedText === text

if (displayedText.length === 0) {
  im.reset()
} else if (initialContent || displayedText.startsWith(previous)) {
  im.append(displayedText.slice(previous?.length ?? 0))
} else {
  im.reset()
  im.append(displayedText)
}

if (displayFinished && !finalizedRef.current) {
  im.finalize()
  finalizedRef.current = true
}

这使 parser 与用户看到的文本保持同一步幅。完成事件可以早到，但 parser 的 finalize 不会越过展示游标。

2.3最新尾部单独淡入

每帧返回 fadeChars 与单调递增的 revision。adapter 从最后一个 AST block 向前切，只给本帧新增的尾部创建 chunk；旧字符直接成为 stable text。

const animatedChars = Math.min(blockChars, remaining)
const node = sliceAst(block.node, blockChars, {
  stableChars: blockChars - animatedChars,
  chunks: [{ text: ' '.repeat(animatedChars), createdAt: revision }],
})

if (node) result[index] = { ...block, node }
remaining -= animatedChars

CSS 动画只改变 opacity，从 0.2 到 1。64ms 动画短于 72ms 释放节拍，因此新 suffix 出现前，上一段已经完成淡入；reduced-motion 下直接关闭。

.markdown-part .incremark-fade-in {
  animation: buffin-stream-text-enter 64ms cubic-bezier(0.2, 0.6, 0.3, 1) both;
}

@keyframes buffin-stream-text-enter {
  from { opacity: 0.2; }
  to { opacity: 1; }
}

@media (prefers-reduced-motion: reduce) {
  .markdown-part .incremark-fade-in { animation: none; }
}

3心智模型补丁

4新词表

5测试与风险地图

覆盖声明：本报告全量精读 commit 58aca59 的 5 个文件与完整 diff；before 侧的 adapter 与旧测试直接读取自父提交 14dcbfe。没有抽样，没有使用 subagent，也没有把工作区其他历史 commit 纳入本报告。

buffin-ai/buffin · main · 58aca59 · 5 files · +344 / −88 · 本报告为一次性理解辅助，不维护、不作为真相源。