LearnHarness SSE事件通道重构实录:从轮询地狱到notify-fetch推送模型的完整方案
LearnHarness SSE事件通道重构实录:从轮询地狱到notify-fetch推送模型的完整方案
LearnHarness 是一款把 AI 教师 Agent、练习系统与持久化知识图谱装进本地桌面应用的开源学习工具。为了让界面"实时"反映服务器端的变化,它经历了一次教科书级的通信层重构:拆掉遍布各处的轮询定时器,换成一条基于 SSE(Server-Sent Events)的 notify-fetch 事件通道。本文完整复盘这次重构的动机、分层设计与落地细节,是理解"推送式前端同步"的一个绝佳范本。
为什么必须重构:轮询网格的三个代价
重构前的 LearnHarness 客户端,靠一张"轮询网格"感知服务端变化:
| 轮询点 | 间隔 |
|---|---|
| 侧边栏会话列表 | 2.5s |
| 活动 dock(后台任务) | 自适应 2.5s / 10s |
| 任务(jobs)状态 | 1s / 4s |
| 知识图谱状态 | 2s |
| 练习(practice)状态 | 2s |
| 回合结束后的附加观察 | 若干 |
这套方案有三个无法回避的代价:
- 延迟与空转并存:最坏情况下用户要等一个完整周期才能看到变化,而 99% 的请求拿回来的是"什么都没变"。
- 盲点无法覆盖:一次真实的事故暴露了它——探测(probe)→ 教学(teach)交接时,会话里没有任何后台任务,轮询的触发条件不成立,一个由服务器自发开启的新回合对已打开的视图完全不可见,界面直接"冻结"。
- 心智负担分散:每个界面各自维护定时器、各自的防抖与竞态处理,加一个新功能就要再补一张轮询。
问题的根源一句话就能说清:客户端在"猜"服务器何时变了,而它本可以让服务器"告诉"它。
新模型的核心思想:notify → fetch
2026-10-02,项目做出了一条干脆的裁决:直接去终局(go directly to the endgame)——不留过渡期的混合方案,一步到位推送到拉数据(notify → fetch)模型:
- 事件只携带"事实",不携带数据(push the poke, pull the data)。一帧事件只说"真相动了",外加
chatId这类过滤键,payload 极小、无 schema、天然幂等。 - 消费者收到事件后,自己去常规端点 fetch 最新数据(
/api/chats/:id、/api/jobs、/api/activity……)。于是无需 payload 版本管理、无需重放协议——断线重连后,每个消费者重新 fetch 一次即完成自愈。
有人会问:SSE 长连接在云端场景里成本不低,值得吗?这里有一个关键背景:LearnHarness 是运行在 localhost 上的桌面应用,服务器与渲染器同机。1~3 条 SSE 连接各自只占一对 socket,空闲时零流量——轮询在云端的那套经济账,在回环网络上根本不成立。这也是架构文档 docs/architecture.md 中明确写下的判断。
事件通道四层结构逐层拆解
整条通道被拆成职责清晰的四层,每层一个"文件就能看懂"的规模,这也是该项目"可追溯性优先"架构原则的直接体现。
第一层:进程内事件总线(src/core/events.ts)
events.ts 是全应用的唯一总线:服务器回合生命周期、store 适配器、Agent 层后台注册表都向它 emit,SSE 路由把每次发射变成一帧。事件词汇表从第一天就冻结,共 7 种:
| 事件 | payload | 何时发射 |
|---|---|---|
turn-started |
{chatId} |
回合开始(beginTurn 写注册表之后) |
turn-settled |
{chatId} |
回合持久化完成之后(endTurn) |
jobs-changed |
{chatId?} |
任务记录任何写操作 |
activity-changed |
{} |
抽取/练习运行阶段变化 |
chats-changed |
{} |
会话列表形态变化(建/删/改名) |
record-changed |
{chatId} |
无回合的静默记录写入 |
compaction-changed |
{chatId, running} |
压缩开始/结束(running 兼作发送门) |
总线有一个容易被忽略的实现细节:监听器集合挂在 globalThis 上,而不是模块级单例。原因是 Next.js dev 模式下每条路由被编译为独立模块入口,模块级单例在页面渲染、事件路由、各发射方手里会是三个互不相通的实例,事件根本传不出去。这条纪律与同项目的回合存活注册表同源,文件头部注释把前因后果写得清清楚楚(见 events.ts#L13-L19)。
总线本身还内置了两条健壮性规则:emit 时先对监听器集合快照再遍历(遍途中退订不会改坏迭代);单个监听器抛错被 try/catch 隔离并记录,绝不打断其余监听者与发射方。
第二层:SSE 传输(src/server/events-stream.ts)
GET /api/events 的响应逻辑收敛在 events-stream.ts 一个 seam 里,框架路由 app/api/events/route.ts 只剩三行薄封装。核心设计点:
- 生命周期归客户端:与"回合流"不同,这条流不因业务结束而
[DONE],唯一的终结方式是客户端离开触发的cancel()——且cancel只摘除本窗口的监听器与定时器,总线和其余窗口不受影响。 - 心跳与防缓冲:每 25 秒发一帧
: ping注释,防止中间层空闲断连;响应头no-cache, no-transform+X-Accel-Buffering: no关闭一切缓存与缓冲。 - 先订阅后发帧:监听器在
start中同步挂载,单线程保证构造与订阅之间不会漏事件。
第三层:客户端 Hub(components/server-events.tsx)
server-events.tsx 是全应用中唯一知道 EventSource 存在的文件,被挂载在根布局 app/layout.tsx 的最外层。每个打开的窗口持有自己的一条 EventSource("/api/events"),通过一个按类型分发的 Hub(createNotifyHub)扇出给组件。三个关键机制:
- resync 自愈:利用
EventSource原生的自动重连——每次(重新)打开都触发所有消费者的 resync 回调,各 fetch 一次。开发服务器重启、网络抖动,界面都能自行恢复。 - latest-ref 回调:钩子
useServerEvent把回调存入 ref,永远执行最新渲染闭包,规避"事件落在两次渲染之间"的陈旧闭包陷阱。 - 错误隔离 + 解析守门:单个 handler 抛错不影响同类型其他订阅者;解析失败的帧被大声丢弃——通道 payload 约定是极小无 schema 的,坏帧绝不"半触发"。
第四层:消费者接线(chat 视图为例)
components/chat.tsx 展示了消费侧的完整纪律:
- 409 竞态守卫:收到
turn-started时,若localStreamRef.current已被本窗口持有(这是我自己刚发起的回合,流归我所有),直接忽略;否则挂接到正在运行的回合流。 - ~250ms 尾随去抖:突发的事件流合并为每窗口一次 fetch,侧边栏、dock、jobs、图谱全部共享这一形状。
- 不中途同步已挂接的流:挂接期间由流的终结帧负责收敛,避免
turn-settled触发的全量拉取覆盖掉流式续写的状态。
发射方纪律:什么该发、何时发、什么必须沉默
通道能否可靠,一半取决于发射方的自律。项目在架构文档中固化了四条"发射定律"(docs/architecture.md#L491-L497):
- 写后通知(notify-after-write):
turn-settled在persistTurn之后才发射,保证事件触发的 fetch 读到的是已落盘的持久真相。回合的开始/结束发射点见 turn-liveness.ts#L44-L59。 - 在场条目门控(present-entry gating):没有实际改变状态的写(更新不存在的 id、删除空行)不发射任何事件——任务 store 中的
if (removed > 0) emit(...)就是这条定律的落笔(jobs.ts#L108)。 - 沉默定律(silence law):内容写者(
saveMessages、appendTurnUsage等)刻意静默——否则会每个回合刷爆事件,而它们对列表可见的影响已由turn-started/turn-settled覆盖。 - 读永不发射:纯读操作零副作用。
发射方分布在各层:会话 store(chats.ts)、任务 store(jobs.ts)、抽取流水线(extraction.ts 在阶段切换时发 activity-changed)、压缩服务与静默归档服务(发 record-changed / compaction-changed)。
验证与收尾:测试 seam 与"留下的轮询"
测试不依赖 React,也不依赖服务器。 tests/server-events.test.tsx 用一个手工驱动的假 NotifySource 直接驱动真实的 Hub 接线代码:按名分发、open 触发 resync(首次与重连都算)、抛错 handler 不打断邻居、close 即停发——四条纪律逐一钉死。因为 wireSource 被特意抽成纯函数,React 只是它外面的一层适配器。
重构后并非"零轮询",项目诚实地保留了少数有界的轮询并写明理由(docs/architecture.md#L508-L513):409 重试的 500ms→5s 指数退避(竞态客户端的有界等待)、dock 上的 1s 时钟跳动(纯本地渲染)、挂载时的快速路径。它们要么是"对竞争"而非"对服务器",要么根本不产生网络请求。
总结:这套方案可复用的三个要点
- 推送事实,拉取数据:事件通道只传"变了"这个信号,数据仍走常规端点。没有版本管理、没有重放协议,重连=重新 fetch,自愈是免费的。
- 词汇表先行:事件类型在第一天冻结、集中定义(events.ts#L26-L51),客户端按名注册,通道能力边界一目了然。
- 纪律比代码难写:写后通知、在场门控、沉默定律、读不发射、错误隔离——这些"什么不发"的规则,才是通道长期可靠的真正来源。
想在自己的 Next.js 项目里复刻这条通道,起点非常小:一个 globalThis 总线 + 一个 SSE 路由 + 一个 EventSource Provider,三个文件即成骨架。完整的分文件讲解可参考项目文档 docs/architecture.md(第 10 节专讲推送模型)与开发指南 docs/development.md。


