claude-mem 旋转 Logo 问题深度解析：SSE 状态推送链路的三种失效模式与分阶段修复方案

本文基于 claude-mem 仓库中的排障 playbook TRIAGE-02-Spinning-Logo-Fix.md，完整还原 Viewer 界面"处理中"旋转 Logo 卡死/抽搐问题的根因分析：事件驱动状态推送缺乏心跳、SSE 广播不处理写错误、前端图标动画依赖帧计数这三个独立失效模式，并给出可落地的分阶段修复方案与验证清单。读完本文，你可以掌握 SSE 长连接状态同步类系统的通用排查方法：如何定位"状态不一致"类 UI 问题，以及如何用心跳、写错误处理与时间戳驱动动画系统性加固整条推送链路。

问题背景：一条"处理中"状态是怎么到达浏览器的

claude-mem 的本地 Worker 服务负责观察 Agent 会话并压缩记忆，Viewer 是一个浏览器端界面，需要实时反映 Worker 是否正在处理任务。状态同步链路是：

1. Worker 内部的会话/消息状态发生变化（收到 prompt、消息入队、会话完成等）；
2. worker-service.ts 中的 broadcastProcessingStatus() 被触发，计算 isProcessing 与 queueDepth 并通过 SSE 广播给所有客户端；
3. SSEBroadcaster 把事件以 data: {json}\n\n 的 SSE 帧格式写给每个连接的 Response 对象；
4. Viewer 前端通过 EventSource 接收 processing_status 事件，驱动 Header 的旋转动效与标签页 favicon 动画。

broadcastProcessingStatus() 的当前实现可以直接在仓库中确认，worker-service.ts#L843-L861 中它从 SessionManager.getTotalActiveWork() 取队列深度，queueDepth > 0 即视为 isProcessing，随后调用 sseBroadcaster.broadcast({ type: 'processing_status', isProcessing, queueDepth })。它的触发方式则是"纯事件驱动"的：worker-service.ts#L266 将 setOnPendingMutate(() => this.broadcastProcessingStatus()) 挂到 SessionManager 的待处理消息变更回调上——有事件才有广播，没有事件就什么都没有。这正是下述失效模式的源头。

根因分析：三种相互独立的失效模式

playbook 给出的结论是，旋转 Logo 的"诡异行为"并非单一 bug，而是三个彼此独立的失效模式叠加造成的。下面逐一展开，并结合当前仓库源码给出印证。

失效模式 1：幻影旋转——没有事件就没有状态纠正

根因：broadcastProcessingStatus() 只响应会话事件（收到 prompt、observation 入队、会话完成），不存在周期性心跳。若最后一次广播时消息恰好短暂处于 processing 状态（计算出 isProcessing: true），而消息在下次广播之前就完成了，UI 将永远收不到 isProcessing: false 的更新——旋转 Logo 就此"幻影式"地停不下来。

加剧因素：playbook 指出，负责清理卡死消息的 hasAnyPendingWork()（其内部对滞留超过 5 分钟的消息执行重置副作用）只在 broadcastProcessingStatus() 运行时才会被间接触发，而后者本身又依赖事件触发。没有事件 = 没有自愈检查，形成死锁式的状态悬挂。

佐证：文档记录了当时的证据——陈旧会话回收器（stale session reaper）每 2 分钟运行一次，但回收完成后不调用 broadcastProcessingStatus()，即使后台已经清理干净，UI 也收不到任何通知。

修复思路（Phase 1）：给状态推送加心跳。 核心动作有二：

• 在 Worker 服务中新增一个 30 秒间隔的心跳定时器，周期性调用 broadcastProcessingStatus()，让卡住的 isProcessing: true 最多 30 秒后就能被下一次计算纠正；
• 在陈旧会话回收器回调内、回收完成后追加一次 broadcastProcessingStatus()，让"后台清理完成"这一时刻立即反映到 UI。

实现上文档给出了明确的代码模式指引：照抄同文件中 2 分钟回收器的 setInterval 写法，并在 shutdown() 中保存并清理定时器句柄。验证标准是：触发处理 → 中途杀掉 Agent 进程 → 旋转 Logo 应在 30 秒内（而非 5 分钟）自动停止。

失效模式 2：SSE 连接悄悄死亡——广播不处理写错误

根因：客户端的 TCP 连接可能因网络切换、笔记本休眠等原因静默断开。此时 Response 对象仍留在客户端集合中，而广播时的写入既不检查返回值、也没有 try/catch，死连接永远收不到后续状态。这一点在当前源码中仍然可以清晰看到，SSEBroadcaster.ts#L36-L38：

for (const client of this.sseClients) {
  client.write(data);
}

broadcast() 遍历 sseClients 集合直接 write，没有任何错误处理分支。同时，SSEBroadcaster.ts#L13-L15 的 'close' 事件监听只在客户端显式关闭连接时触发，网络掉线不会触发它。

加剧因素：应用层没有任何心跳/ping。HTTP 层只依赖 Connection: keep-alive 背后的 TCP keepalive，而操作系统级的 keepalive 超时往往长达 2 小时以上（macOS 尤其如此），远不能及时发现死连接。

修复思路（Phase 2）：双管齐下加固广播器。

1. 写错误处理：在 broadcast() 中为每个 client.write(data) 包上 try/catch，捕获写错误后立即调用 removeClient(client) 把死连接从集合中清掉；日志级别用 debug 而非 warn——客户端断开是正常现象，不应污染告警。
2. 应用层心跳：每隔 30 秒向客户端发送 SSE 注释帧 :ping\n\n。SSE 注释会被 EventSource 忽略，但能持续维持 TCP 连接活性、让死连接尽快暴露。实现上可以按客户端各存一个定时器并在 removeClient() 中清除，也可以用一个共享定时器统一 ping 所有客户端（文档认为后者更简单）。

验证标准：打开 Viewer 停留 60 秒以上，浏览器 Network 面板中 SSE 流不中断；杀掉 Worker 后 Viewer 应在 3 秒内重连（保持 EventSource 现有的重连行为）。

失效模式 3：后台标签页中 favicon 动画卡顿——帧计数假设了 60fps

根因：驱动标签页图标旋转的 Hook useSpinningFavicon.ts 使用固定帧增量旋转。当前源码 useSpinningFavicon.ts#L51 中：

rotationRef.current += (2 * Math.PI) / 90;

每一帧 requestAnimationFrame 回调都让角度增加 4°，这是按 60fps（即 240°/秒）设计的。但浏览器对后台标签页会把 rAF 节流到约 1fps，于是 favicon 实际只有 4°/秒，视觉上表现为冻结或抽搐。

非问题项：Header 中 logomark 上的 CSS .spinning 动画不受影响——CSS 动画在后台标签页中仍按正常速度执行，这是文档特意澄清的边界。

修复思路（Phase 3）：改为时间戳驱动。 用 performance.now() 记录起始时间，每一帧根据"经过的时间"而非"经过的帧数"计算角度，使动画与帧率解耦：

const elapsed = performance.now() - startTime;
const rotation = (elapsed / 1500) * 2 * Math.PI; // 1.5 秒转一圈

这样无论 rAF 被节流到多低，回到前台时角度都对应真实流逝的时间，动画表现平滑一致。验证标准：触发处理 → 切到其他标签页 10 秒 → 切回 → favicon 应处于"按正确速度旋转"的角度，而不是冻结在原角度。

失效模式 4（附赠）：类型定义缺口

playbook 的 Phase 4 指出了一个顺带问题：queueDepth 字段已经在 SSE 事件消费侧被使用，但 Viewer 侧的 StreamEvent 接口类型定义中没有声明它，属于类型与实现脱节。修复动作是在该接口中补上 queueDepth?: number，并以 npx tsc --noEmit 无相关报错作为验证标准。

关键 API 与代码坐标速查表

playbook 在 Phase 0 做了一轮"API 发现"，把修复涉及的每个关键方法定位到了文件与行号（下表行号为文档撰写时 feat/factory-ai 分支的坐标，仓库后续演进后行号有漂移，使用时请以方法名为准在当前代码中定位）：

方法	文档记录位置	用途
broadcastProcessingStatus()	worker-service.ts:872	计算并广播 isProcessing + queueDepth
isAnySessionProcessing()	SessionManager.ts:431	委托给待处理消息存储的查询
hasAnyPendingWork()	PendingMessageStore.ts:404	SQL 检查 + 5 分钟卡死消息重置副作用
resetStaleProcessingMessages()	PendingMessageStore.ts:160	重置卡死消息（阈值可配置）
claimNextMessage()	PendingMessageStore.ts:93	对单会话卡死消息有 60 秒自愈
SSEBroadcaster.broadcast()	SSEBroadcaster.ts:45	向所有客户端写数据（当时无错误处理）
SSEBroadcaster.addClient()	SSEBroadcaster.ts:21	注册客户端并监听 close 事件
useSpinningFavicon()	useSpinningFavicon.ts:7	Canvas rAF 动画，按帧计数旋转
useSSE()	useSSE.ts:8	EventSource，出错时 3 秒重连
Stale session reaper	worker-service.ts:476	2 分钟间隔，但不广播状态

当前仓库中可直接核对到的坐标：broadcastProcessingStatus() 位于 worker-service.ts#L843，SSE 写入循环位于 SSEBroadcaster.ts#L36-L38，帧增量旋转位于 useSpinningFavicon.ts#L51。从源码结构看，SessionManager 当前通过 getTotalActiveWork() 提供队列深度，其待处理工作集合与文档描述的 hasAnyPendingWork() 一脉相承，但中间存储层的实现文件在仓库演进中已有所调整，深入排查时应以方法语义而非旧行号为锚点。

文档明确列出的反模式（Anti-Patterns）

playbook 特意给出三条"不要做"，体现了该项目的工程约束，值得随修复方案一起继承：

• 初始开发阶段不要加防御性 try/catch——项目奉行 fail-fast 原则（唯一例外正是 Phase 2 中 SSE 写路径：写错误属于可预期的外部故障，需要隔离处理并清理死连接）；
• 不要在 UI 端引入轮询——SSE 推送才是正确的状态同步模式，轮询只会把问题 1 的"错过更新"换成"延迟更新"；
• 不要用 WebSocket 替换 EventSource——SSE 在单向状态推送场景下更简单且足够。

分阶段验证清单

playbook 的 Phase 5 给出了五个端到端验收项，全部可人工复现：

1. 基本循环：打开 Viewer → 触发处理 → 观察旋转开始 → 处理完成 → 旋转应在 2 秒内停止；
2. 卡死消息自愈：开始处理 → 中途杀掉 Worker → 重启 Worker → 旋转状态应在 30 秒内自愈；
3. 后台标签页：触发处理 → 切换标签页 → 切回 → favicon 平滑旋转（验证 Phase 3）；
4. 连接韧性：断开网络片刻 → 恢复 → 旋转状态正确（验证 Phase 2 心跳与 EventSource 重连）；
5. 回归：npm test 全量通过。

配合文档给出的快速定位命令——grep -n 'broadcastProcessingStatus' src/services/worker-service.ts——可以在改动后一眼确认新的心跳定时器是否就位。

小结：从一次 UI Bug 看 SSE 状态同步系统的三条加固原则

这份 playbook 的价值不仅在于修好了一个旋转 Logo，更在于它示范了对"事件驱动状态推送系统"做鲁棒性设计的完整思路：

• 事件驱动不等于状态收敛：只要存在"最后一次事件恰好携带中间状态"的窗口期，就必须用周期性心跳兜底自校正（30 秒心跳 + 关键后台任务完成时立即广播）；
• 长连接的写入必须有归宿：无错误的写 + 只在显式关闭时清理客户端，必然积累僵尸连接；写错误清理 + 应用层 :ping 心跳是把连接活性从操作系统层拉回应用层的标准做法；
• 前端动画要与帧率解耦：凡是用 rAF 做动画，都应按时间戳计算而非按帧计数，否则后台标签页节流会直接暴露假设。

以上方案均可在当前仓库中按文件路径追溯原始实现：TRIAGE-02 文档、SSEBroadcaster.ts、useSpinningFavicon.ts 与 worker-service.ts，可作为同类 SSE 状态推送架构排查时的参照模板。