main：Thread 流式播放不再靠“最后一条”猜测

buffin-ai/buffin · fc9cf3f...557014c · 2026-07-15 · 自包含，读完即弃

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

1TL;DR

Session Thread 的麻烦在于，历史重放、实时增量、后台 tab、审批暂停和多轮对话会挤在同一条消息流里。旧实现手上只有 isRunning 与 isHydrating，于是只能用“数组最后一条、group 最后一项”来猜动画该落在哪。

这 4 个提交没碰 daemon，也没改事件协议。改动全在前端：先把事件折叠成消息，接着算出 Session 当前处于运行、等待还是结束，再指定哪个 message、哪个 part 可以播放。Incremark 最后执行 static / revealing / frozen。

结果很具体。历史消息直接显示，后台完成的 Session 不会补播动画；多轮对话只动当前 run 的一段内容；遇到审批或输入请求，文字停在已经显示的位置；run 一结束，整条 Thread 归于静态。

边界也要先说清楚：这次只改了前端播放模型。重放结束仍靠 200ms quiet / 2s cap 猜测，设计稿里的 caught-up 标记和 activation barrier 都还没实现。提交材料没有说明为何收窄范围，这部分是 uncertain。（原始材料：完整比较、设计稿）

2变更地图

一共改了 1415 行，其中 847 行是测试。真正需要慢慢读的是 Session components 和 models。WorkBench 只负责把可见性传下去，runtime store 补上了 resync 后重新进入 hydration 的行为。

3架构一图流

这次把播放决策从组件内部挪了出来。过去，Thread 和 Markdown 组件各猜一遍；现在，事件投影负责整理事实，presentation 选播放对象，第三方渲染器照着策略执行。Markdown 库本身没有换。

4数据与状态先行

SessionState 是事件折叠后的结果。它按顺序保存 message/part，也记着 daemon run 是否还开着。这里没有动画状态。

export interface Message {
  id: string
  role: 'user' | 'assistant'
  parts: MessagePart[]
  status: 'complete' | 'running'
}

export interface SessionState {
  messages: Message[]
  isRunning: boolean
  usage: UsageInfo | null
}

SessionDomain 给这份数据一个统一解释：当前 run 正在工作、等人处理，还是已经结束；开放 run 又属于哪条 assistant message。Thread、tab badge 和 Activity 都从这里取状态。

export type SessionExecutionPhase =
  | 'idle'
  | 'running'
  | 'waiting-approval'
  | 'waiting-input'
  | 'settled'

export interface SessionDomain {
  execution: SessionExecutionPhase
  activeMessageId: string | null
}

ThreadPresentation 描述当前这个界面该怎么画。活动 message、活动 part、文字播放方式和 message 入场动画各占一个字段，互不冒充。

export type ThreadPlaybackMode = 'static' | 'revealing' | 'frozen'

export interface ThreadPresentation {
  execution: SessionExecutionPhase
  activeMessageId: string | null
  activePartIndex: number | null
  playback: ThreadPlaybackMode
  animateEntries: boolean
}

5旅程 A：一串事件如何成为 execution

先补一个背景。Session 不是 React 组件里的一段聊天数组；上游 dispatcher 把 snapshot 和订阅事件写进 TanStack Query 的 AgentTimeline，每个 Session 再用自己的 Zustand vanilla store 增量折叠这条时间线。（原始材料：dispatcher.ts）

A.1时间线只增量折叠，resync 才从头重建

processed 记着已经读到哪里。timeline 正常增长时，store 只处理后面的新 envelope。resync 会先清空 cache，这时数组变短，projection 才从头重建，UI 也重新进入 hydrating。

const ingest = () => {
  const timeline = queryClient.getQueryData<AgentTimeline>(queryKey) ?? emptyTimeline
  if (timeline.length < processed) {
    reduced = initialSessionState
    processed = 0
    store.setState({ ...reduced, isHydrating: true }) // resync 重新静态回放
    armCap()
  }
  while (processed < timeline.length) {
    const envelope = timeline[processed]
    if (!envelope) break
    const event = envelope.event as { type: string }
    if (isSessionEvent(event)) {
      reduced = sessionReducer(reduced, event, envelope.id)
    }
    processed++
  }
}

isHydrating 不是 daemon 发来的状态，是前端自己猜的。每来一个事件就重启 quiet timer；安静 200ms，或首次打开已经过了 2 秒，前端便认为这批历史数据收完了。做 MVP 够直接，但它不精确。

const HYDRATION_QUIET_MS = 200
const HYDRATION_CAP_MS = 2000

const armQuiet = () => {
  clearTimeout(quietTimer)
  quietTimer = setTimeout(settle, HYDRATION_QUIET_MS)
}
const armCap = () => {
  clearTimeout(capTimer)
  capTimer = setTimeout(settle, HYDRATION_CAP_MS)
}

A.2领域状态只看开放 run 与它自己的 pending interaction

判断很短。daemon run 已关闭时，空 transcript 叫 idle，有历史就叫 settled。run 还开着时，从后往前找最后一条 status === running 的 assistant message。

export function deriveSessionDomain(messages: Message[], isRunning: boolean): SessionDomain {
  if (!isRunning) {
    return {
      execution: messages.length === 0 ? 'idle' : 'settled',
      activeMessageId: null,
    }
  }

  const activeMessage = findLastRunningMessage(messages)
  const pending = activeMessage ? findLatestPendingInteraction(activeMessage.parts) : undefined
  return {
    execution:
      pending?.type === 'approval'
        ? 'waiting-approval'
        : pending?.type === 'ask-user'
          ? 'waiting-input'
          : 'running',
    activeMessageId: activeMessage?.id ?? null,
  }
}

pending interaction 只查 active message。旧 message 里即使残留一个 pending receipt，也不会把新 run 误判为 waiting。tab badge 和 Activity 也使用这份判断。

6旅程 B：多 Thread 中谁能播放

一个 Session 可以挂着、订阅着、还在跑，但用户此刻根本没看它。要不要播放动画，还得看宿主 tab、浏览器窗口、hydration 和 reduced motion。

B.1Tab keep-alive，但隐藏状态显式下传

ContentHost 没有卸载后台 tab。DOM 和相关状态都留着，只用 CSS 隐藏。这种 keep-alive 方式需要额外传入 visible，组件才能分清“还挂着”和“用户看得见”。

function TabContent({ tab, visible }: { tab: Tab; visible: boolean }) {
  return (
    <div
      className={cn('absolute inset-0 overflow-hidden',
        !visible && 'pointer-events-none invisible')}
      aria-hidden={!visible}
    >
      <ContentVisibilityProvider visible={visible}>
        <registration.Component target={tab.target} />
      </ContentVisibilityProvider>
    </div>
  )
}

useContentVisibility 还会检查 document.visibilityState。tab 和整个窗口都可见时，它才返回 true。

export function useContentVisibility(): boolean {
  const surfaceVisible = useContext(ContentSurfaceVisibilityContext)
  const windowVisible = useSyncExternalStore(
    subscribeWindowVisibility,
    getWindowVisibility,
    () => true,
  )
  return surfaceVisible && windowVisible
}

B.2先选唯一 message，再选唯一 narrative part

deriveSessionDomain 先选出最后一个 running assistant。presentation 接着从这条 message 的尾部找一段尚未 closed 的 text 或 reasoning。

正常 running 时，这段 narrative 必须正好在 parts 尾部。末尾如果是 tool，动画权就交给 tool，前面的文字停下。waiting 稍有不同：它会找到审批或输入卡之前的开放 narrative，把显示位置冻在那里。

function findActiveNarrativePartIndex(messages: Message[], domain: Domain): number | null {
  const message = messages.find((candidate) => candidate.id === domain.activeMessageId)
  if (!message) return null
  for (let index = message.parts.length - 1; index >= 0; index--) {
    const part = message.parts[index]
    if (!part || !isOpenNarrative(part)) continue
    if (domain.execution === 'running' && index !== message.parts.length - 1) return null
    return index
  }
  return null
}

function isOpenNarrative(part: MessagePart): boolean {
  return (part.type === 'text' || part.type === 'reasoning') && part.closed !== true
}

SessionThread 现在认 ID，不认数组位置。message 对不上 activeMessageId 就是 static；对得上的 message 里，也只有 partIndex === activePartIndex 的 group 能拿到 playback。

{messages.map((msg) => {
  const isActive = msg.id === presentation.activeMessageId
  return msg.role === 'user' ? (
    <UserMsg parts={msg.parts} />
  ) : (
    <AssistantMsg
      parts={msg.parts}
      playback={isActive ? presentation.playback : 'static'}
      activePartIndex={isActive ? presentation.activePartIndex : null}
      showRunningIndicator={
        isActive && msg.status === 'running' && presentation.execution === 'running'
      }
    />
  )
})}

B.3哪些情况会直接关掉动画

presentation 每次都用同一组输入重算。隐藏、hydrating 和 reduced-motion 会直接得到 static。界面可见且历史已经收稳后，等人处理用 frozen，普通 running 才用 revealing。

function derivePlaybackMode(input: ThreadPresentationInput, execution: SessionExecutionPhase) {
  if (!input.visible || input.isHydrating || input.reduceMotion) return 'static'
  if (execution === 'waiting-approval' || execution === 'waiting-input') return 'frozen'
  return execution === 'running' ? 'revealing' : 'static'
}

7旅程 C：playback 如何驱动 Incremark

MarkdownPart 瘦了很多。它收下完整 Markdown、播放模式和 finished，随即交给 IncremarkAdapter。原来的 useStreamingReveal 连同 timer 都删了。

C.1三个 playback 对应三组命令

命令映射很直白：revealing 开启并恢复 typewriter；frozen 只暂停，队列和当前位置都留下；static 关闭 typewriter，直接 skip 到当前完整内容。

useLayoutEffect(() => {
  const typewriter = imRef.current.typewriter
  if (playback === 'revealing') {
    typewriter.setEnabled(true)
    typewriter.resume()
  } else if (playback === 'frozen' && typewriter.enabled) {
    typewriter.pause()
  } else {
    typewriter.setEnabled(false)
    typewriter.skip()
  }
}, [playback])

打字速度交给 Incremark 的 typewriter：每 24ms 放出 1–3 个字符，效果是 fade-in，document hidden 时自动暂停。Buffin 只决定播还是不播，不再自己数时间和字符。

const typewriterOptions = {
  charsPerTick: [1, 3],
  tickInterval: 24,
  effect: 'fade-in',
  pauseOnHidden: true,
} satisfies TypewriterOptions

C.2前缀增长 append，权威替换 reset

普通 delta 总是在旧文本后面接内容，adapter 只需 append 新 suffix，parser 可以接着工作。message.completed.text 则可能变短、等长，或者改掉中间一段。这属于 权威替换，adapter 会 reset 后重建，并直接 skip 动画。

useEffect(() => {
  const im = imRef.current
  const previous = previousTextRef.current
  if (text === previous) return
  const initialContent = previous === undefined
  finalizedRef.current = false

  if (text.length === 0) {
    im.reset()
  } else if (initialContent || text.startsWith(previous)) {
    im.append(text.slice(previous?.length ?? 0)) // 只追加 suffix
  } else {
    im.reset()
    im.append(text)
    im.typewriter.setEnabled(false)
    im.typewriter.skip() // 权威替换静态落地
  }
  previousTextRef.current = text
}, [text])

这里还有一处针对 Incremark 1.0.2 的处理。completed block 会被缓存；短前缀先播完后，旧缓存可能截住同一段的后续文字。adapter 因此改用 parser 当前的 completed/pending block 来渲染同一个 id。

const sourceBlocks = new Map(
  [...im.completedBlocks, ...im.pendingBlocks].map((block) => [block.id, block]),
)
const renderedIncremark = {
  ...im,
  blocks: im.blocks.map((block) =>
    block.status === 'completed' ? (sourceBlocks.get(block.id) ?? block) : block,
  ),
}

C.3不能拿 unmount 当完成

keep-alive tab 和 React StrictMode 都可能触碰组件生命周期，unmount 不能代表内容真的结束。只有 part closed 或 message complete 时，adapter 才收到 finished，随后 finalize 一次并 skip 到完整内容。

useEffect(() => {
  if (!finished || finalizedRef.current) return
  const im = imRef.current
  im.finalize()
  im.typewriter.skip()
  finalizedRef.current = true
}, [finished])

SessionThread 用 group.closed || isComplete 计算 finished。live parser 不再随 effect cleanup finalize，所以 StrictMode 在开发期做一次 setup/cleanup rehearsal，也不会把后续 append 提前封死。

8计划 vs 实现的偏差

设计稿比这 4 个提交大得多，里面还包括 transport sync、共享事件契约和可替换 Markdown adapter。这次只做了前端播放这一段。代码能说明哪些东西做了、哪些没做，却没有交代为何收窄范围；原因统一记为 uncertain。（原始材料：session-event-projection-playback.md、handoff.md）

9读完要改掉的旧假设

10测试与风险地图

生产代码改了 568 行，测试改了 847 行。纯函数测试负责状态矩阵，组件测试检查策略有没有传对；另有一条跨层状态序列，以及两条直接运行真实 Incremark 的回归。

11验收提示与覆盖声明

验收时不要误判

• 隐藏 tab 仍保持挂载并更新 projection，这是原有的 keep-alive 设计。新增逻辑只关掉 presentation motion。
• isHydrating 继续存在。daemon 没有改，它仍负责估算 replay burst 的结束时间。
• 审批前的文字使用 frozen，这样光标停在原处；换成 static 会立即补出全文。
• running tool 位于 parts 尾部时，activePartIndex=null。此时 live output 由 tool renderer 展示。
• MarkdownPartDevReplay 只在 DEV 环境挂载，是本地回放工具，不参与状态机。

覆盖声明

报告读完了 fc9cf3f...557014c 的 27 个变更文件，共 1415 行增删，没有抽样。文中的代码片段来自 HEAD 原文件；旧管线则直接读取 base 版本的 SessionThread.tsx、MarkdownPart.tsx 和 use-streaming-reveal.ts。runtime、domain、presentation、visibility、真实 Incremark 测试、设计稿与 handoff 也都逐项核过。

这是一份代码走读，不是 code review。未落地的设计目标只记作范围差异，启发式边界也没有被写成必然故障。代码事实都能从 GitHub 完整 diff 回查。

buffin-ai/buffin · main · fc9cf3f...557014c · 4 commits / 27 files / +1142 −273 · 本报告为一次性理解辅助，不维护、不作为真相源。