ClawX ACP 流式输出即时渲染改造:移除 Renderer 端 16ms 批处理队列,让 Streamdown 逐事件更新
ClawX ACP 流式输出即时渲染改造:移除 Renderer 端 16ms 批处理队列,让 Streamdown 逐事件更新
本文聚焦 ClawX 项目中一条运行时桥接(runtime-bridge)任务规范:
harness/specs/tasks/apply-acp-stream-updates-immediately.md。它规定 Renderer 侧对 ACP 实时宿主事件必须"来一件、收一件、渲染一件",不再经过 16ms 批处理定时器,从而让 Streamdown 流式 Markdown 渲染跟随每个事件即时推进。读完本文,你将理解这条任务的目标、范围、验收标准、对应源码实现(src/stores/acp-chat-session.ts 与 src/lib/acp/reducer.ts),以及如何用单元测试、E2E 测试和 comms 回归脚本验证"两连块产生两次有序 Store 通知"这一核心行为。
一、任务定位:一条只改"更新节奏"的运行时桥接任务
该任务规范归属于 gateway-backend-communication 场景,taskType 为 runtime-bridge(运行时桥接),其核心意图(intent)只有一句话:
移除 Renderer 侧的实时 ACP 分块批处理(live ACP chunk batching),使 Streamdown 在不经过 16 ms 队列的情况下收到每一个被接受的宿主事件。
任务规范用 Scope 一节明确划定了改造边界:
本任务只改变 Renderer Store 对实时 ACP 宿主事件的更新节奏(update cadence)。它不改变 ACP 传输、Main 进程路由、时间线归约(reduction)语义、Streamdown 配置,也不改变持久化历史的权威性。
也就是说,这不是一次协议改动、不是新增传输通道、不是重写渲染器,而是一次"节流/去批"式的渲染管线调整:同一个事件,从"攒一批再提交"变成"到达即提交"。
预期用户行为(expectedUserBehavior)
规范对最终用户体验提出两点硬性要求:
- 实时助手输出随每个 ACP 宿主事件的到达而推进,而不是等待 Renderer 侧的批处理定时器;
- 流式顺序、过期 generation 拒绝、权限处理、已完成提示(completed prompt)行为均保持不变。
换句话说:用户看到的打字机式输出更跟手,但事件顺序、会话代数(generation)过滤、权限卡片交互和提示结束后的一次性回放水合,都不能因为"去批"而产生任何回归。
二、改造前后:从"定时器攒批"到"逐事件同步提交"
任务规范的 acceptance 给出了四条可验证的验收标准,它们共同刻画了改造前后的行为差异:
| 验收标准 | 含义 |
|---|---|
| 每个被接受的实时 ACP 会话更新都通过既有的类型化宿主事件订阅同步应用 | 不新增传输、不换订阅通道 |
| 两个连续实时 ACP 分块产生两次有序的 Store 通知,而非一次定时器批处理通知 | 去批的直接证据 |
| 历史会话回放保留既有的 generation 作用域归约行为 | 回放路径不受影响 |
| Renderer 不得引入任何替代的队列、定时器、传输或回退路径 | 防止"换汤不换药"式重新引入批处理 |
对应到当前仓库实现,applyUpdateEnvelope 的正常路径确实是同步提交的。在 src/stores/acp-chat-session.ts 中,当事件属于当前激活会话且 generation 匹配时,处理链是:
const timeline = applyAcpSessionUpdate(state.timeline, event.notification, { historical: !!event.historical });
const pending = newPendingAttachments(state.timeline, timeline);
set({ timeline }); // 每事件一次 Store 提交
if (state.sending) { /* 同步镜像到 liveSessionSnapshots */ }
resolvePendingAttachments(event.sessionKey, event.generation, pending);
get().recordImageGenerationStart(event);
const evidence = extractImageGenerationCompletionFromAcpEnvelope(event);
if (evidence) void get().projectImageGenerationCompletion(evidence);
这里没有任何 setTimeout、requestAnimationFrame 或队列:每个事件完成归约后立即 set({ timeline }),触发一次 Zustand 状态通知。reducer 是纯函数 applyAcpSessionUpdate,它只负责把 agent_message_chunk、agent_thought_chunk、tool_call、plan 等更新记录增量地并入时间线快照,调用方是同步立即执行,还是攒批后执行,归约结果完全一致——这正是"只改节奏、不改语义"能成立的根本原因。
三、订阅与分发:既有类型化宿主事件通道
任务要求"通过既有的类型化宿主事件订阅"同步应用,这意味着通道本身不做任何新增。在 shared/host-events/contract.ts 中,宿主事件契约暴露了:
acpSessionUpdate: (payload: AcpSessionUpdateEnvelope) => void;
Renderer 侧在 src/stores/acp-chat-session.ts 的 ensureAcpChatSubscriptions() 中完成一次性订阅注册(幂等,重复调用只订阅一次),把事件直接接到 Store 的 applyUpdateEnvelope:
export function ensureAcpChatSubscriptions(): void {
if (acpChatSubscribed) return;
acpChatSubscribed = true;
hostEvents.onAcpSessionUpdate((event) => {
useAcpChatSessionStore.getState().applyUpdateEnvelope(event);
});
hostEvents.onAcpPermissionRequest((event) => {
useAcpChatSessionStore.getState().applyPermissionRequest(event);
});
// ... GatewayChatMessage / ChatRuntimeEvent 仅用于图像生成补全投影
}
可以看到:实时文本/思考/工具事件的入口是 onAcpSessionUpdate → applyUpdateEnvelope,每来一个事件立即调用一次,没有中间层做时间窗口聚合。
事件过滤依然严格
"去批"绝不等于"放松过滤"。applyUpdateEnvelope 在同步应用前仍有三道守卫(见 src/stores/acp-chat-session.ts):
- 加载进行中(
state.loading):匹配的事件进入pendingLoadUpdates(按 generation 分组的交接期缓冲); - 结算回放交接(
activeSettledReplayLoad):generation 与当前不同的事件进入activeSettledReplayLoad.updates缓冲; - 会话或 generation 不匹配:事件只能作用于
liveSessionSnapshots中同 generation 的存活快照(且仅用于图像生成补全的延迟投影),绝不污染当前时间线。
只有通过这三道守卫、真正属于"当前激活会话 + 当前 generation"的事件,才走同步提交路径。过期 generation 拒绝(stale-generation rejection)行为因此保持不变。
四、仍然存在的"缓冲":交接期事务缓冲,而非替代队列
接受标准特意强调"Renderer 不得引入替代队列、定时器、传输或回退路径",但规范与架构参考文档同时承认两种有明确生命周期的事务性缓冲是合法的,因为它们不是节流工具,而是保证原子性的握手机制:
session/load交接期:Main 在 load 返回时把回放通知作为"一个 generation 作用域的原始批次"返回,Renderer 用一个状态提交完成归约;期间从事件通道到达的同 generation 事件先临时挂起,随 load 结果合并后一起归约。tests/unit/acp-chat-store.test.ts 的用例merges matching event-channel updates that arrive during the load handoff专门覆盖了这一握手。- 结算回放交接(settled replay handoff):提示(prompt)成功结束后,Renderer 会做一次隐藏的
session/load水合,期间到达的异 generation 事件进入activeSettledReplayLoad.updates,与水合批次合并后一次性提交。
harness/reference/acp-chat.md 在 History Authority 一节给出了与任务规范完全一致的表述:
"These are in-flight transaction buffers only, not history caches; after load, each live update continues through the normal host-event route and is applied immediately without a Renderer batching timer."
对应的规则 harness/specs/rules/acp-chat-state-and-history.md 也写明了同样的边界:允许在 IPC 结果交接期临时缓冲匹配的宿主事件,而每条普通实时提示更新继续走宿主事件通道并在没有 Renderer 批处理定时器的情况下立即应用。
五、测试验证:两连块 = 两次有序通知
任务规范把"两个连续实时 ACP 分块产生两次有序 Store 通知,而非一次定时器批处理通知"列为验收标准,而单元测试直接给出了可执行的验证:
tests/unit/acp-chat-store.test.ts 中的用例 commits each live streamed update immediately:
it('commits each live streamed update immediately', async () => {
vi.stubEnv('MODE', 'production');
vi.useFakeTimers(); // 假定时器:若存在批处理定时器必须手动拨动才会生效
// ... loadSession 后订阅 Store
hostEventsMock.updateListener?.(liveUpdate('one'));
expect(onStoreChange).toHaveBeenCalledTimes(1); // 第一个 chunk → 第一次通知
expect(useAcpChatSessionStore.getState().timeline.itemsById['streamed-message:0'])
.toMatchObject({ parts: [{ kind: 'markdown', text: 'one' }] });
hostEventsMock.updateListener?.(liveUpdate(' two'));
expect(onStoreChange).toHaveBeenCalledTimes(2); // 第二个 chunk → 第二次通知
expect(useAcpChatSessionStore.getState().timeline.itemsById['streamed-message:0'])
.toMatchObject({ parts: [{ kind: 'markdown', text: 'one two' }] });
});
两个细节值得注意:
- 测试启用了假定时器(
vi.useFakeTimers())却从不推进时间——如果 Store 里还残留任何 16ms 批处理定时器,第二个断言(第二次通知立即出现)将无法通过。这从测试层面"钉死"了去批行为。 - 时间线从
'one'累积为'one two',证明逐事件应用保持了有序拼接(append 语义),即验收标准中的"有序"。
另一组用例反向验证"历史回放仍是一次性批提交":tests/unit/acp-chat-store.test.ts 的 commits a completed ACP load batch as one timeline snapshot 断言订阅者观察到的状态序列绝不会出现 { loading: false, itemCount: 1 } 这样的中间态,最终一次性落到 { loading: false, itemCount: 2 }——这正是"历史回放保留既有 generation 作用域归约行为"的体现:实时去批,回放不拆。
E2E 层:Streamdown 逐块渲染
用户可见的最终效果由 tests/e2e/chat-streamdown-rendering.spec.ts 验证。该用例通过 emitAcpSessionUpdates 逐条注入 agent_message_chunk,并断言每个块的效果在注入后立即可见:
- 第一块
Streaming **bold→strong元素立即渲染出bold,且首词带--sd-duration: 140ms动画标记(spec); - 第二块补充
** words with inlineCode()...→ 行内代码、URL 文本立即出现,且新词继续获得动画标记(spec); - 后续块注入
\``javascript ...与```→ 未闭合代码块(data-incomplete="true"`)即时出现并随后关闭(spec)。
如果事件仍被 16ms 定时器攒批,这些断言(每个块注入后立即检查 DOM)将出现竞态或超时,因此该 E2E 用例本身就是"逐事件渲染"的最强行为证据。
六、验证命令与回归检查
任务规范列出了开发完成后必须通过的验证命令,它们与仓库 package.json 中的脚本一一对应:
| 命令 | 验证内容 | 对应脚本 |
|---|---|---|
pnpm exec vitest run tests/unit/acp-chat-store.test.ts |
Store 层:逐事件提交、交接期合并、generation 过滤、回放批提交等 | — |
pnpm exec playwright test tests/e2e/chat-streamdown-rendering.spec.ts |
E2E:Streamdown 对每个 ACP chunk 的即时渲染与动画 | — |
pnpm run typecheck |
类型安全(node + web 双 tsconfig) | package.json |
pnpm run comms:replay |
通信层回放回归 | package.json → scripts/comms/replay.mjs |
pnpm run comms:compare |
通信层基线比对回归 | package.json → scripts/comms/compare.mjs |
其中 comms:replay 与 comms:compare 属于任务 requiredProfiles 中的 comms 画像:本次改造触及宿主事件到达 Renderer 的时序,通信层回归工具(配合 scripts/comms/baseline.mjs 与 scripts/comms/datasets 下的 JSONL 数据集)用于确认事件流回放与对比结果不劣化。requiredProfiles 中的 fast 画像则对应任务对"低延迟即时更新"的属性要求。
七、必须遵守的边界规则
任务规范声明依赖以下规则(requiredRules),它们共同划定了本次改造的合法范围:
- renderer-main-boundary:Renderer 只做语义归约与呈现,Main 拥有 ACP 进程/路由生命周期;"去批"只能在 Renderer Store 侧进行,不得扩散到 Main 路由。
- backend-communication-boundary:不改动 ACP 传输与 Main 进程路由,事件仍走既有宿主事件通道。
- host-events-fallback-policy:宿主事件订阅是既有通道,不得因去批而引入替代传输或回退路径。
- acp-chat-state-and-history:交接期临时缓冲被明确允许,但普通实时更新必须立即应用、无 Renderer 批处理定时器;历史回放保持 generation 作用域的一次性批提交。
- comms-regression:事件流通信行为不得回归,需通过 comms 回归脚本验证。
docs 字段为 required: false,即本任务不要求更新文档——规范本身(harness/specs/tasks/apply-acp-stream-updates-immediately.md)、架构参考(harness/reference/acp-chat.md)与状态规则(harness/specs/rules/acp-chat-state-and-history.md)中的既有表述已经与目标行为一致。
八、小结:一次"最小侵入"的渲染管线优化
综合来看,这条任务规范描述的是一次刻意保持小范围的运行时桥接改造:
- 改什么:Renderer Store 对实时 ACP 宿主事件的更新节奏——从定时器批处理改为逐事件同步提交;
- 不改什么:ACP 传输、Main 路由、归约语义、Streamdown 配置、历史权威;
- 怎么验证:单元测试证明"两连块两次通知、回放仍单次批提交",E2E 证明 Streamdown 每个块即时渲染,typecheck 与 comms 脚本兜底回归;
- 代码落点:同步提交在 src/stores/acp-chat-session.ts 的
applyUpdateEnvelope,纯归约在 src/lib/acp/reducer.ts,订阅接线在 src/stores/acp-chat-session.ts。
对开发者而言,这条任务的最佳启示是:流式体验的"跟手感"问题,往往不需要动协议和渲染引擎,只需审视事件到达与状态提交之间是否存在多余的"攒批"环节;而判断这类优化是否安全,靠的是"归约函数纯不纯"(同一事件序列无论立即执行还是攒批执行,结果一致)以及"交接期缓冲是否有明确生命周期"(只做握手,不做节流)。