Cherry Studio Execution Overlay 深度解析渲染进程流式覆盖层的分流、种子与生命周期设计【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio导读在 Cherry Studio 中主进程Main负责 AI 流式回复的完整生命周期、持久化与多播分发而渲染进程Renderer只做一件事把 chunk 流实时画到聊天界面上。本文解析的Execution Overlay正是渲染进程侧的流式覆盖层——它以TopicStreamSubscription做 IPC 挂载与按 execution/anchor 的分流以useExecutionOverlayExecutionStreamOverlayService驱动逐条消息的流式叠加渲染。读完本文你将理解为什么主进程与渲染进程必须共用同一个 chunk 组装函数、如何用executionId anchorMessageId双重键做到多模型并行与同模型 steer 续写互不串扰、如何用每轮一次性 reader 当前 DB 种子从结构上杜绝跨轮状态污染以及覆盖层如何在流式叠加与SQLite 权威数据之间安全交接。一、背景渲染进程侧的pipeStreamLoop对应物Execution Overlay 是主进程pipeStreamLoop的渲染进程侧对应物。主进程通过tee()将 AI SDK 产生的UIMessageChunk流一分为二详见 Stream ManagerMain: pipeStreamLoop(stream) tee() ├─ branch A → broadcast to listeners → WebContentsListener → IPC chunks └─ branch B → readUIMessageStream → exec.finalMessage (writes to DB) ▲ │ (DB write) │ Renderer: TopicStreamSubscription ┌──── readUIMessageStream → snapshot │ │ │ ▲ │ ▼ │ │ │ routes chunks by │ fed by branch stream │ executionId anchor │ │ into stream branches ───────┘ ▼ branch ReadableStream → useExecutionOverlay (per execution)两侧使用的是同一个纯组装器——AI SDK 的readUIMessageStream——把 chunk 流还原成一个完整的CherryUIMessage。主进程把组装结果写入磁盘exec.finalMessage落库渲染进程则把它作为覆盖层叠加在 SWR 支撑的历史消息之上。最终持久化的内容与用户看到的流式内容在结构上严格一致。二、为什么两端必须共用同一个 merge 函数UIMessageChunk的组装绝不是简单的字符串拼接文本增量按id合并text-start/text-delta/text-endreasoning 块有独立的 start / delta / end 生命周期工具调用要经历tool-input-start→tool-input-delta→tool-input-available→tool-output-available的完整状态机动态 data part 按 key 合并多步骤multi-step回合携带 step 边界。如果在渲染进程上重新实现这套组装逻辑就等于制造了第二个真相源second source of truth——它必须时刻追着 AI SDK 上游跑而且两处对部分状态partial state的理解随时可能不一致。因此 Cherry Studio 的设计是在同一份UIMessageChunk流上各跑一次readUIMessageStream——主进程跑一份用于落库渲染进程跑一份用于驱动覆盖层。这样两端在结构上天然一致没有分叉的机会。三、TopicStreamSubscription传输层的分流中枢源码位于 TopicStreamSubscription.ts。这是一个渲染进程类每个保留中的 topic 持有一个实例负责把 IPC 传来的 chunk 流按执行身份路由到各条ReadableStreamUIMessageChunk分支上。它同时也是一个有状态多播器任何执行中的订阅者都能从register()拿到一条专属分支。3.1 每个 topic 只挂载一次 IPCattach 是引用计数的attachai.stream.attachIPC由引用计数保护每次执行调用register(executionId, anchorMessageId)都会使计数 1最后一个unregister才触发detachdetach还会延迟一个微任务queueMicrotask避免activeExecutions的瞬时抖动导致先 detach 再 reattach从而短暂丢失主进程的最后一个监听器。unregister(executionId, anchorMessageId, attemptId) { // ... if (this.#branches.size 0 this.#attached !this.#disposed !this.#topicOpen) { // Defer one tick: a transient activeExecutions flicker would otherwise // detach→reattach and momentarily drop Mains last listener. queueMicrotask(() { if (this.#branches.size 0 this.#attached !this.#disposed !this.#topicOpen) this.#detach() }) } }值得注意的是#ensureAttached()的实现顺序先注册 IPC 监听器再发起 attach 请求。这样主进程在其 listener 注册的瞬间发出的实时 chunk 也不会漏掉attach 返回的bufferedChunks重连回放也会在挂载完成后立即回放。3.2 执行 anchor 双重分流register(executionId, anchorMessageId)的返回值是一条只属于该模型写入该 assistant 行的ReadableStreamUIMessageChunk多模型并行回复不同模型按executionId分到不同分支同模型 steer 续写按anchorMessageId分到不同分支。分支身份键在源码中是三者合一function branchKey(executionId: UniqueModelId, anchorMessageId?: string, attemptId?: number): string { // One model execution can roll into another assistant row during steer continuation. // The branch identity must include the row anchor, not only the model id. return JSON.stringify([executionId, anchorMessageId ?? null, attemptId ?? null]) }3.3 anchor 是流身份的一部分executionId命名的是模型而不是 assistant 行。在 steer 续写过程中主进程可能先关闭 A1a、紧接着用同一个模型 id 打开 A2——此时 A2 的 chunk 可能先于 React 注册 A2 的 reader 到达。若只按模型 id 路由这些 chunk 会被错误地送进已关闭的 A1a 分支。因此传输层必须把 chunk 缓存在executionId anchorMessageId键下。3.4 同步创建 controller迟到读者不丢块分支的ReadableStreamDefaultController在new ReadableStream({ start })调用期间同步创建。这意味着从register返回流、到 reader 首次read()之间到达的 chunk 已经被缓冲进流的内部队列——迟到的读者永远不会错过回放的 chunk。3.5 终结terminal分流ai.stream.done/ai.stream.error会关闭匹配的分支并向监听者广播一个ExecutionTerminal{ isAbort, isError }若 payload 携带isTopicDone或没有executionId则所有分支一起终结显式的isTopicDonefalse会让 topic 附件跨过下一个分支产出第一个 chunk 之前的空档存活避免在续写间隙误 detach。在源码中终结还带一个topicAttemptWatermark机制当某轮终结携带水位线时所有attemptId watermark的旧分支会被统一退役retire从而把跨轮的僵尸分支一次清理干净。3.6 取消分层不要把两者混为一谈层次所有者动作渲染进程本地订阅TopicStreamSubscription.unregister/dispose关闭分支 reader、释放监听器引用计数主进程继续生成生成中止主进程useChatWithHistory.stop→ai.stream.abort真正停止 LLMTopicStreamSubscription绝不 abort LLM。关闭全部分支在渲染进程侧等价于streamDetach——主进程继续流式生成其他窗口继续观察。3.7 防御性路由一个没有executionId的 chunk 是意外情况主进程总是会给聊天 chunk 打上执行身份标记。作为防御性兜底若恰好只有一条分支已注册则将该 chunk 路由过去否则丢弃并打一条警告日志源码中#routeChunk对缺少executionId/attemptId的 payload 记录chunk without execution identity dropped。四、useExecutionOverlayReact 绑定层源码位于 useExecutionOverlay.ts。这是每个执行execution的覆盖层入口构建在ExecutionStreamOverlayServiceTopicStreamSubscription之上const { overlay, liveAssistants, disposeOverlay, reset, clear } useExecutionOverlay( topicId, activeExecutions, // ActiveExecution[] from useTopicStreamStatus uiMessages, // current DB snapshot { onFinish } )4.1 薄绑定 useSyncExternalStore这个 hook 只是窗口级ExecutionStreamOverlayService的薄 React 绑定acquire/release 一个引用计数的视图通过useSyncExternalStore订阅服务端视图卸载路由/标签页/会话切换不会拆除流重新挂载时同步恢复实时覆盖层。overlay是messageId - 最新流式 partsmessageId 即 anchorMessageId或临时 topic 无预分配行时用 start-chunk 的 idliveAssistants是按插入顺序排列的最新 assistant 快照。4.2 每轮一个 reader零跨轮状态每个 execution 每轮使用一次性readUIMessageStreamreader而不是有状态的 AI SDKChat对象Chat会跨轮携带state.messages复用它会令新一轮从上一轮已完成的 assistant 处续写上轮答案 新流造成污染每轮全新 reader 在结构上不可能跨轮污染。4.3 seed 规则continue-safefunction pickSeed(uiMessages, anchorMessageId): CherryUIMessage | undefined { if (!anchorMessageId) return undefined const found uiMessages.find((m) m.id anchorMessageId) if (!found) return { id: anchorMessageId, role: assistant, parts: [] } // readUIMessageStream mutates message.parts in place, and found is the live // SWR-derived row — clone the parts so the reader only ever writes to a throwaway. return { ...found, parts: structuredClone(found.parts ?? []) } }reader 以anchorMessageId对应的消息为种子且该消息取自reader 启动时刻的当前 DB 真相uiMessagesRef.current。有两种典型情形全新占位行SQLite 行 parts 为空种子实际上为空reader 从零构建消息工具审批 / 继续会话行里已经带有上一轮的 assistant parts包括尚未解决的tool-inputpart。流式tool-outputchunk 随后可以干净地合并到与之同toolCallId的tool-input上。种子在每次 reader 启动时都从 DB 重新派生绝不跨轮携带且其parts被structuredClone克隆readUIMessageStream的就地修改永远不会触碰 SWR 缓存行。结合每轮全新 reader这是结构性的反污染保证——不是强制清空 parts或与上一帧做 diff这类权宜之计。五、窗口级服务ExecutionStreamOverlayService源码位于 ExecutionStreamOverlayService.ts。该服务是窗口级的流式覆盖状态所有者按topicId键控被 chat 与 agent-session 两类消费者共享其生命周期以传输层的topicId路由作用域为准而不是某个组件实例。5.1 生命周期轻缓存DB 才是真相源覆盖层只是在途流式内容的临时暂存区SQLite 是权威数据源。丢失暂存区最多代价是下次挂载时多一次 DB 刷新——这正是它不值得背负太多机制的边界所在。activeExecutions变化与当前 reader 表做 diff——取消并注销已不在活跃列表中的 execution对新增活跃 execution 注册分支、清掉保留的旧快照、启动新 reader。终结分支由TopicStreamSubscription关闭reader 的for await正常退出onFinish(executionId, event)携带最终快照 { isAbort, isError }触发。卸载 / 切换标签页视图被释放引用计数 -1但运行中的 reader 继续在服务里组装。销毁策略情形处理方式流仍在运行无论 mount 与否条目都保留流结束、视图已挂载终结状态边沿触发refresh()DB →reset()丢弃已定局的快照流结束、无视图该 execution 的覆盖层立即丢弃持久化的 DB 行接管条目在最后一个 reader 结束且主进程确认 topic 完成后才移除。isTopicDonefalse只保留跨续写空档的 topic 附件排队中的续写 chunk 会把它钉住直到被读取或其所在轮次终结泄漏兜底MAX_ENTRIES32的 LRU 驱逐只驱逐refCount 0的条目且先取消 reader 再丢弃源码中的驱逐逻辑#evictIfNeeded特别注释了顺序原因先handle.cancel()再#dropEntry否则仍在运行的 reader 会把被截断的流当作成功 finish报告给onFinish消费者。5.2 四道守卫无轮次身份机制下的竞态安全reset()/disposeOverlay()绝不触碰 reader 仍存活的 execution。已结束轮次的延迟 DB 交接不得冻结同一 topic 上正在流式的新轮次——reader 仍在运行检查就是全部的身份测试。破坏性的整体清空是独立的clear()quick-assistant 用。失败的ai.stream.attach会以错误终结其分支让 reader 正常结束而不是永远挂起下次挂载通过全新订阅重新 attach。isTopicDonefalse跨续写空档保留 topic 附件。一个 execution 的终结并不等于 detach 许可——只要主进程显式保持 topic 存活、且尚未调度下一个分支。已结束的 execution 键被墓碑化settledKeys。重新挂载时Activity 保留的消费者状态若仍列出该 execution也不能把它重启成僵尸 reader。墓碑只让位于新鲜的传输证据——一个已经排队着新一轮 chunk 的开放分支——此时重启的 reader 可以无损回放。5.3 覆盖层拆除是单调的disposeOverlay(messageId)只丢弃一条快照条目。聊天外壳把调用时机接线为DB 刷新 promise resolve 之后才释放覆盖层见useChatRuntimeState中handleExecutionFinish的refresh()→.finally(() disposeOverlay(message.id))顺序。这个次序消除了流式覆盖层与持久化 parts之间的可见闪烁——SWR 缓存先持有权威行覆盖层再消失。渲染进程从不把流式 parts 写进 SWR——那样做会与 DB 权威的刷新竞态导致闪烁。5.4 为什么终态后仍保留快照服务会把最终快照留在snapshots中直到满足以下任一条件同一 execution 重新启动下一轮清掉它调用方调用disposeOverlay(messageId)持久化后的交接调用方调用reset()整轮持久化后的交接或clear()破坏性清空quick-assistant条目被丢弃最后一个 reader 在 refCount 0 下结束或 LRU 驱逐。这种保留让消费者在流结束 → DB 刷新完成的短暂窗口内不必经过 SWR 就能读到最终帧。5.5 提交节奏按负载自适应的 interval 批处理源码中没有用固定的 rAF/定时器节拍而是按待提交快照的总文本量自适应提交间隔const MIN_COMMIT_INTERVAL_MS 100 const MAX_COMMIT_INTERVAL_MS 3000 const COMMIT_CHARS_PER_MS 2000 function commitIntervalMs(pending): number { let chars 0 for (const item of pending) for (const part of item.snapshot.parts ?? []) { const text (part as { text?: unknown }).text if (typeof text string) chars text.length } return Math.min(MAX_COMMIT_INTERVAL_MS, Math.max(MIN_COMMIT_INTERVAL_MS, chars / COMMIT_CHARS_PER_MS)) }每次 commit 都要重跑 O(消息大小) 的渲染工作内容变换 markdown 重新词法分析所以间隔随快照大小线性放大把每秒的渲染工作量限制在界内——固定节奏会在消息增长时压垮渲染进程。间隔范围 100ms3000ms按chars / 2000计算。5.6 已定局 parts 的引用共享readUIMessageStream对每个 chunk 都克隆完整消息。为了不让渲染成本随累积的完整记录线性增长服务实现了shareSettledPartReferences对协议上已定局的 part非 streaming 的 text / reasoning、已到output-available且非preliminary的 tool part、file/source-url/source-document/step-start等追加型 part复用上一帧的对象引用使渲染工作量只与活跃前沿成正比。data part 被刻意排除——带 id 的 data part 可能被后续 chunk 原地更新。六、覆盖层的消费方6.1 聊天页useChatRuntimeStateuseChatRuntimeState.ts 是文档 code map 中标注的消费者接线方式与本文第四、五节完全对应调用useExecutionOverlay(topic.id, branchActiveExecutions, messages, { onFinish })handleExecutionFinish中先refresh()使 DB 权威消息失效刷新再disposeOverlay(message.id)并清理分支级实时消息快照结束前把分支 live 消息从列表中移除实现覆盖层 → 持久化行的平滑交接。6.2 Agent 会话useAgentChatRuntimeStateuseAgentChatRuntimeState.ts 同样消费该覆盖层useExecutionOverlay(sessionTopicId, activeExecutions, uiMessages)随后通过useMessageStreamingLayers({ messages, overlay, executions, ... })把覆盖层 parts 叠加进消息流式层渲染。这印证了服务按topicId键控的设计动机——chat 与 agent-session 两类页面共享同一套窗口级覆盖机制。6.3 测试验证useExecutionOverlay.test.ts 覆盖了本文讨论的关键不变量包括N1锚点覆盖层隔离——每个 execution 只落在自己的 anchor 上N2/N2b无跨轮污染——同一模型新 anchor 下一轮干净起步同一模型直接切换 anchor 会启动全新 readerN3工具审批续写——从当前 DB 锚点非空播种流式续写追加在既有内容之后而非替换种子克隆——SWR 派生行永不因 reader 就地修改而损坏终端快照立即冲刷而非等待下一次提交节奏React 往返卸载后继续组装、重挂载同步渲染卸载前后的全部内容破坏性 clear 后取消的 commit 不能恢复快照。七、代码地图src/renderer/services/aiTransport/TopicStreamSubscription.ts ← IPC attach branch demux (one per retained topic) src/renderer/services/aiTransport/ExecutionStreamOverlayService.ts ← window-level readers/snapshots/interval batching, keyed by topicId src/renderer/hooks/useExecutionOverlay.ts ← React binding (refcounted view lease) src/renderer/pages/home/useChatRuntimeState.ts ← consumer dispose-after-refresh src/renderer/pages/agents/useAgentChatRuntimeState.ts ← agent-session consumer (same window-level service)八、审查者应核对的不变量两端必须使用同一个 merge 函数。任何在渲染进程上重新实现 chunk→消息组装而不是喂给readUIMessageStream的代码都是错误的——那是主进程与渲染进程最先分叉的地方。每个分支身份一个 reader。在executionId或anchorMessageId变化的activeExecutions过渡中复用 reader 是禁止的。复用正是 v1Chat的 bug只按模型 id 键控会把同样的问题带回同模型 steer 续写场景。种子取自当前 DB。pickSeed在 reader 启动时读取uiMessagesRef.current。把种子缓存在首次挂载并跨轮复用会破坏继续会话continue-conversation场景。覆盖层必须在 DB 刷新后拆除。任何在 DB 重新验证 promise resolve之前执行的disposeOverlay(messageId)都是闪烁 bug。TopicStreamSubscription永不 abort。它只 detach。该层任何调用ai.stream.abort的代码都放错了位置——abort 属于useChatWithHistory.stop。attach 引用计数。已有 execution 注册同一 topic 时不得再发起新的 attach仍有任何 execution 持有分支时不得发起新的 detach。九、延伸阅读主进程侧累计器与 tee 分流Stream Manager —pipeStreamLoopIPC 信封与 attach/detach 语义IPC Transporttopic 状态与审批锚点的上层呈现Tool Approval组装器上游语义readUIMessageStreamAI SDK UI 参考文档【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Cherry Studio Execution Overlay 深度解析：渲染进程流式覆盖层的分流、种子与生命周期设计
Cherry Studio Execution Overlay 深度解析渲染进程流式覆盖层的分流、种子与生命周期设计【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio导读在 Cherry Studio 中主进程Main负责 AI 流式回复的完整生命周期、持久化与多播分发而渲染进程Renderer只做一件事把 chunk 流实时画到聊天界面上。本文解析的Execution Overlay正是渲染进程侧的流式覆盖层——它以TopicStreamSubscription做 IPC 挂载与按 execution/anchor 的分流以useExecutionOverlayExecutionStreamOverlayService驱动逐条消息的流式叠加渲染。读完本文你将理解为什么主进程与渲染进程必须共用同一个 chunk 组装函数、如何用executionId anchorMessageId双重键做到多模型并行与同模型 steer 续写互不串扰、如何用每轮一次性 reader 当前 DB 种子从结构上杜绝跨轮状态污染以及覆盖层如何在流式叠加与SQLite 权威数据之间安全交接。一、背景渲染进程侧的pipeStreamLoop对应物Execution Overlay 是主进程pipeStreamLoop的渲染进程侧对应物。主进程通过tee()将 AI SDK 产生的UIMessageChunk流一分为二详见 Stream ManagerMain: pipeStreamLoop(stream) tee() ├─ branch A → broadcast to listeners → WebContentsListener → IPC chunks └─ branch B → readUIMessageStream → exec.finalMessage (writes to DB) ▲ │ (DB write) │ Renderer: TopicStreamSubscription ┌──── readUIMessageStream → snapshot │ │ │ ▲ │ ▼ │ │ │ routes chunks by │ fed by branch stream │ executionId anchor │ │ into stream branches ───────┘ ▼ branch ReadableStream → useExecutionOverlay (per execution)两侧使用的是同一个纯组装器——AI SDK 的readUIMessageStream——把 chunk 流还原成一个完整的CherryUIMessage。主进程把组装结果写入磁盘exec.finalMessage落库渲染进程则把它作为覆盖层叠加在 SWR 支撑的历史消息之上。最终持久化的内容与用户看到的流式内容在结构上严格一致。二、为什么两端必须共用同一个 merge 函数UIMessageChunk的组装绝不是简单的字符串拼接文本增量按id合并text-start/text-delta/text-endreasoning 块有独立的 start / delta / end 生命周期工具调用要经历tool-input-start→tool-input-delta→tool-input-available→tool-output-available的完整状态机动态 data part 按 key 合并多步骤multi-step回合携带 step 边界。如果在渲染进程上重新实现这套组装逻辑就等于制造了第二个真相源second source of truth——它必须时刻追着 AI SDK 上游跑而且两处对部分状态partial state的理解随时可能不一致。因此 Cherry Studio 的设计是在同一份UIMessageChunk流上各跑一次readUIMessageStream——主进程跑一份用于落库渲染进程跑一份用于驱动覆盖层。这样两端在结构上天然一致没有分叉的机会。三、TopicStreamSubscription传输层的分流中枢源码位于 TopicStreamSubscription.ts。这是一个渲染进程类每个保留中的 topic 持有一个实例负责把 IPC 传来的 chunk 流按执行身份路由到各条ReadableStreamUIMessageChunk分支上。它同时也是一个有状态多播器任何执行中的订阅者都能从register()拿到一条专属分支。3.1 每个 topic 只挂载一次 IPCattach 是引用计数的attachai.stream.attachIPC由引用计数保护每次执行调用register(executionId, anchorMessageId)都会使计数 1最后一个unregister才触发detachdetach还会延迟一个微任务queueMicrotask避免activeExecutions的瞬时抖动导致先 detach 再 reattach从而短暂丢失主进程的最后一个监听器。unregister(executionId, anchorMessageId, attemptId) { // ... if (this.#branches.size 0 this.#attached !this.#disposed !this.#topicOpen) { // Defer one tick: a transient activeExecutions flicker would otherwise // detach→reattach and momentarily drop Mains last listener. queueMicrotask(() { if (this.#branches.size 0 this.#attached !this.#disposed !this.#topicOpen) this.#detach() }) } }值得注意的是#ensureAttached()的实现顺序先注册 IPC 监听器再发起 attach 请求。这样主进程在其 listener 注册的瞬间发出的实时 chunk 也不会漏掉attach 返回的bufferedChunks重连回放也会在挂载完成后立即回放。3.2 执行 anchor 双重分流register(executionId, anchorMessageId)的返回值是一条只属于该模型写入该 assistant 行的ReadableStreamUIMessageChunk多模型并行回复不同模型按executionId分到不同分支同模型 steer 续写按anchorMessageId分到不同分支。分支身份键在源码中是三者合一function branchKey(executionId: UniqueModelId, anchorMessageId?: string, attemptId?: number): string { // One model execution can roll into another assistant row during steer continuation. // The branch identity must include the row anchor, not only the model id. return JSON.stringify([executionId, anchorMessageId ?? null, attemptId ?? null]) }3.3 anchor 是流身份的一部分executionId命名的是模型而不是 assistant 行。在 steer 续写过程中主进程可能先关闭 A1a、紧接着用同一个模型 id 打开 A2——此时 A2 的 chunk 可能先于 React 注册 A2 的 reader 到达。若只按模型 id 路由这些 chunk 会被错误地送进已关闭的 A1a 分支。因此传输层必须把 chunk 缓存在executionId anchorMessageId键下。3.4 同步创建 controller迟到读者不丢块分支的ReadableStreamDefaultController在new ReadableStream({ start })调用期间同步创建。这意味着从register返回流、到 reader 首次read()之间到达的 chunk 已经被缓冲进流的内部队列——迟到的读者永远不会错过回放的 chunk。3.5 终结terminal分流ai.stream.done/ai.stream.error会关闭匹配的分支并向监听者广播一个ExecutionTerminal{ isAbort, isError }若 payload 携带isTopicDone或没有executionId则所有分支一起终结显式的isTopicDonefalse会让 topic 附件跨过下一个分支产出第一个 chunk 之前的空档存活避免在续写间隙误 detach。在源码中终结还带一个topicAttemptWatermark机制当某轮终结携带水位线时所有attemptId watermark的旧分支会被统一退役retire从而把跨轮的僵尸分支一次清理干净。3.6 取消分层不要把两者混为一谈层次所有者动作渲染进程本地订阅TopicStreamSubscription.unregister/dispose关闭分支 reader、释放监听器引用计数主进程继续生成生成中止主进程useChatWithHistory.stop→ai.stream.abort真正停止 LLMTopicStreamSubscription绝不 abort LLM。关闭全部分支在渲染进程侧等价于streamDetach——主进程继续流式生成其他窗口继续观察。3.7 防御性路由一个没有executionId的 chunk 是意外情况主进程总是会给聊天 chunk 打上执行身份标记。作为防御性兜底若恰好只有一条分支已注册则将该 chunk 路由过去否则丢弃并打一条警告日志源码中#routeChunk对缺少executionId/attemptId的 payload 记录chunk without execution identity dropped。四、useExecutionOverlayReact 绑定层源码位于 useExecutionOverlay.ts。这是每个执行execution的覆盖层入口构建在ExecutionStreamOverlayServiceTopicStreamSubscription之上const { overlay, liveAssistants, disposeOverlay, reset, clear } useExecutionOverlay( topicId, activeExecutions, // ActiveExecution[] from useTopicStreamStatus uiMessages, // current DB snapshot { onFinish } )4.1 薄绑定 useSyncExternalStore这个 hook 只是窗口级ExecutionStreamOverlayService的薄 React 绑定acquire/release 一个引用计数的视图通过useSyncExternalStore订阅服务端视图卸载路由/标签页/会话切换不会拆除流重新挂载时同步恢复实时覆盖层。overlay是messageId - 最新流式 partsmessageId 即 anchorMessageId或临时 topic 无预分配行时用 start-chunk 的 idliveAssistants是按插入顺序排列的最新 assistant 快照。4.2 每轮一个 reader零跨轮状态每个 execution 每轮使用一次性readUIMessageStreamreader而不是有状态的 AI SDKChat对象Chat会跨轮携带state.messages复用它会令新一轮从上一轮已完成的 assistant 处续写上轮答案 新流造成污染每轮全新 reader 在结构上不可能跨轮污染。4.3 seed 规则continue-safefunction pickSeed(uiMessages, anchorMessageId): CherryUIMessage | undefined { if (!anchorMessageId) return undefined const found uiMessages.find((m) m.id anchorMessageId) if (!found) return { id: anchorMessageId, role: assistant, parts: [] } // readUIMessageStream mutates message.parts in place, and found is the live // SWR-derived row — clone the parts so the reader only ever writes to a throwaway. return { ...found, parts: structuredClone(found.parts ?? []) } }reader 以anchorMessageId对应的消息为种子且该消息取自reader 启动时刻的当前 DB 真相uiMessagesRef.current。有两种典型情形全新占位行SQLite 行 parts 为空种子实际上为空reader 从零构建消息工具审批 / 继续会话行里已经带有上一轮的 assistant parts包括尚未解决的tool-inputpart。流式tool-outputchunk 随后可以干净地合并到与之同toolCallId的tool-input上。种子在每次 reader 启动时都从 DB 重新派生绝不跨轮携带且其parts被structuredClone克隆readUIMessageStream的就地修改永远不会触碰 SWR 缓存行。结合每轮全新 reader这是结构性的反污染保证——不是强制清空 parts或与上一帧做 diff这类权宜之计。五、窗口级服务ExecutionStreamOverlayService源码位于 ExecutionStreamOverlayService.ts。该服务是窗口级的流式覆盖状态所有者按topicId键控被 chat 与 agent-session 两类消费者共享其生命周期以传输层的topicId路由作用域为准而不是某个组件实例。5.1 生命周期轻缓存DB 才是真相源覆盖层只是在途流式内容的临时暂存区SQLite 是权威数据源。丢失暂存区最多代价是下次挂载时多一次 DB 刷新——这正是它不值得背负太多机制的边界所在。activeExecutions变化与当前 reader 表做 diff——取消并注销已不在活跃列表中的 execution对新增活跃 execution 注册分支、清掉保留的旧快照、启动新 reader。终结分支由TopicStreamSubscription关闭reader 的for await正常退出onFinish(executionId, event)携带最终快照 { isAbort, isError }触发。卸载 / 切换标签页视图被释放引用计数 -1但运行中的 reader 继续在服务里组装。销毁策略情形处理方式流仍在运行无论 mount 与否条目都保留流结束、视图已挂载终结状态边沿触发refresh()DB →reset()丢弃已定局的快照流结束、无视图该 execution 的覆盖层立即丢弃持久化的 DB 行接管条目在最后一个 reader 结束且主进程确认 topic 完成后才移除。isTopicDonefalse只保留跨续写空档的 topic 附件排队中的续写 chunk 会把它钉住直到被读取或其所在轮次终结泄漏兜底MAX_ENTRIES32的 LRU 驱逐只驱逐refCount 0的条目且先取消 reader 再丢弃源码中的驱逐逻辑#evictIfNeeded特别注释了顺序原因先handle.cancel()再#dropEntry否则仍在运行的 reader 会把被截断的流当作成功 finish报告给onFinish消费者。5.2 四道守卫无轮次身份机制下的竞态安全reset()/disposeOverlay()绝不触碰 reader 仍存活的 execution。已结束轮次的延迟 DB 交接不得冻结同一 topic 上正在流式的新轮次——reader 仍在运行检查就是全部的身份测试。破坏性的整体清空是独立的clear()quick-assistant 用。失败的ai.stream.attach会以错误终结其分支让 reader 正常结束而不是永远挂起下次挂载通过全新订阅重新 attach。isTopicDonefalse跨续写空档保留 topic 附件。一个 execution 的终结并不等于 detach 许可——只要主进程显式保持 topic 存活、且尚未调度下一个分支。已结束的 execution 键被墓碑化settledKeys。重新挂载时Activity 保留的消费者状态若仍列出该 execution也不能把它重启成僵尸 reader。墓碑只让位于新鲜的传输证据——一个已经排队着新一轮 chunk 的开放分支——此时重启的 reader 可以无损回放。5.3 覆盖层拆除是单调的disposeOverlay(messageId)只丢弃一条快照条目。聊天外壳把调用时机接线为DB 刷新 promise resolve 之后才释放覆盖层见useChatRuntimeState中handleExecutionFinish的refresh()→.finally(() disposeOverlay(message.id))顺序。这个次序消除了流式覆盖层与持久化 parts之间的可见闪烁——SWR 缓存先持有权威行覆盖层再消失。渲染进程从不把流式 parts 写进 SWR——那样做会与 DB 权威的刷新竞态导致闪烁。5.4 为什么终态后仍保留快照服务会把最终快照留在snapshots中直到满足以下任一条件同一 execution 重新启动下一轮清掉它调用方调用disposeOverlay(messageId)持久化后的交接调用方调用reset()整轮持久化后的交接或clear()破坏性清空quick-assistant条目被丢弃最后一个 reader 在 refCount 0 下结束或 LRU 驱逐。这种保留让消费者在流结束 → DB 刷新完成的短暂窗口内不必经过 SWR 就能读到最终帧。5.5 提交节奏按负载自适应的 interval 批处理源码中没有用固定的 rAF/定时器节拍而是按待提交快照的总文本量自适应提交间隔const MIN_COMMIT_INTERVAL_MS 100 const MAX_COMMIT_INTERVAL_MS 3000 const COMMIT_CHARS_PER_MS 2000 function commitIntervalMs(pending): number { let chars 0 for (const item of pending) for (const part of item.snapshot.parts ?? []) { const text (part as { text?: unknown }).text if (typeof text string) chars text.length } return Math.min(MAX_COMMIT_INTERVAL_MS, Math.max(MIN_COMMIT_INTERVAL_MS, chars / COMMIT_CHARS_PER_MS)) }每次 commit 都要重跑 O(消息大小) 的渲染工作内容变换 markdown 重新词法分析所以间隔随快照大小线性放大把每秒的渲染工作量限制在界内——固定节奏会在消息增长时压垮渲染进程。间隔范围 100ms3000ms按chars / 2000计算。5.6 已定局 parts 的引用共享readUIMessageStream对每个 chunk 都克隆完整消息。为了不让渲染成本随累积的完整记录线性增长服务实现了shareSettledPartReferences对协议上已定局的 part非 streaming 的 text / reasoning、已到output-available且非preliminary的 tool part、file/source-url/source-document/step-start等追加型 part复用上一帧的对象引用使渲染工作量只与活跃前沿成正比。data part 被刻意排除——带 id 的 data part 可能被后续 chunk 原地更新。六、覆盖层的消费方6.1 聊天页useChatRuntimeStateuseChatRuntimeState.ts 是文档 code map 中标注的消费者接线方式与本文第四、五节完全对应调用useExecutionOverlay(topic.id, branchActiveExecutions, messages, { onFinish })handleExecutionFinish中先refresh()使 DB 权威消息失效刷新再disposeOverlay(message.id)并清理分支级实时消息快照结束前把分支 live 消息从列表中移除实现覆盖层 → 持久化行的平滑交接。6.2 Agent 会话useAgentChatRuntimeStateuseAgentChatRuntimeState.ts 同样消费该覆盖层useExecutionOverlay(sessionTopicId, activeExecutions, uiMessages)随后通过useMessageStreamingLayers({ messages, overlay, executions, ... })把覆盖层 parts 叠加进消息流式层渲染。这印证了服务按topicId键控的设计动机——chat 与 agent-session 两类页面共享同一套窗口级覆盖机制。6.3 测试验证useExecutionOverlay.test.ts 覆盖了本文讨论的关键不变量包括N1锚点覆盖层隔离——每个 execution 只落在自己的 anchor 上N2/N2b无跨轮污染——同一模型新 anchor 下一轮干净起步同一模型直接切换 anchor 会启动全新 readerN3工具审批续写——从当前 DB 锚点非空播种流式续写追加在既有内容之后而非替换种子克隆——SWR 派生行永不因 reader 就地修改而损坏终端快照立即冲刷而非等待下一次提交节奏React 往返卸载后继续组装、重挂载同步渲染卸载前后的全部内容破坏性 clear 后取消的 commit 不能恢复快照。七、代码地图src/renderer/services/aiTransport/TopicStreamSubscription.ts ← IPC attach branch demux (one per retained topic) src/renderer/services/aiTransport/ExecutionStreamOverlayService.ts ← window-level readers/snapshots/interval batching, keyed by topicId src/renderer/hooks/useExecutionOverlay.ts ← React binding (refcounted view lease) src/renderer/pages/home/useChatRuntimeState.ts ← consumer dispose-after-refresh src/renderer/pages/agents/useAgentChatRuntimeState.ts ← agent-session consumer (same window-level service)八、审查者应核对的不变量两端必须使用同一个 merge 函数。任何在渲染进程上重新实现 chunk→消息组装而不是喂给readUIMessageStream的代码都是错误的——那是主进程与渲染进程最先分叉的地方。每个分支身份一个 reader。在executionId或anchorMessageId变化的activeExecutions过渡中复用 reader 是禁止的。复用正是 v1Chat的 bug只按模型 id 键控会把同样的问题带回同模型 steer 续写场景。种子取自当前 DB。pickSeed在 reader 启动时读取uiMessagesRef.current。把种子缓存在首次挂载并跨轮复用会破坏继续会话continue-conversation场景。覆盖层必须在 DB 刷新后拆除。任何在 DB 重新验证 promise resolve之前执行的disposeOverlay(messageId)都是闪烁 bug。TopicStreamSubscription永不 abort。它只 detach。该层任何调用ai.stream.abort的代码都放错了位置——abort 属于useChatWithHistory.stop。attach 引用计数。已有 execution 注册同一 topic 时不得再发起新的 attach仍有任何 execution 持有分支时不得发起新的 detach。九、延伸阅读主进程侧累计器与 tee 分流Stream Manager —pipeStreamLoopIPC 信封与 attach/detach 语义IPC Transporttopic 状态与审批锚点的上层呈现Tool Approval组装器上游语义readUIMessageStreamAI SDK UI 参考文档【免费下载链接】cherry-studio Cherry Studio 是一款支持多个 LLM 提供商的桌面客户端项目地址: https://gitcode.com/CherryHQ/cherry-studio创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考