LearnHarness SSE事件通道重构实录:从轮询地狱到notify-fetch推送模型的完整方案

原创2026-10-28 12:20:391,430 阅读

LearnHarness SSE事件通道重构实录:从轮询地狱到notify-fetch推送模型的完整方案

LearnHarness 是一款把 AI 教师 Agent、练习系统与持久化知识图谱装进本地桌面应用的开源学习工具。为了让界面"实时"反映服务器端的变化,它经历了一次教科书级的通信层重构:拆掉遍布各处的轮询定时器,换成一条基于 SSE(Server-Sent Events)的 notify-fetch 事件通道。本文完整复盘这次重构的动机、分层设计与落地细节,是理解"推送式前端同步"的一个绝佳范本。

LearnHarness AI学习应用主界面横幅:Agent驱动的教学会话与知识图谱

为什么必须重构:轮询网格的三个代价

重构前的 LearnHarness 客户端,靠一张"轮询网格"感知服务端变化:

轮询点 间隔
侧边栏会话列表 2.5s
活动 dock(后台任务) 自适应 2.5s / 10s
任务(jobs)状态 1s / 4s
知识图谱状态 2s
练习(practice)状态 2s
回合结束后的附加观察 若干

这套方案有三个无法回避的代价:

  • 延迟与空转并存:最坏情况下用户要等一个完整周期才能看到变化,而 99% 的请求拿回来的是"什么都没变"。
  • 盲点无法覆盖:一次真实的事故暴露了它——探测(probe)→ 教学(teach)交接时,会话里没有任何后台任务,轮询的触发条件不成立,一个由服务器自发开启的新回合对已打开的视图完全不可见,界面直接"冻结"。
  • 心智负担分散:每个界面各自维护定时器、各自的防抖与竞态处理,加一个新功能就要再补一张轮询。

问题的根源一句话就能说清:客户端在"猜"服务器何时变了,而它本可以让服务器"告诉"它。

LearnHarness AI教学会话截图:教师回合、后台任务与图谱更新都需要事件通道实时推送到客户端

新模型的核心思想:notify → fetch

2026-10-02,项目做出了一条干脆的裁决:直接去终局(go directly to the endgame)——不留过渡期的混合方案,一步到位推送到拉数据(notify → fetch)模型:

  1. 事件只携带"事实",不携带数据(push the poke, pull the data)。一帧事件只说"真相动了",外加 chatId 这类过滤键,payload 极小、无 schema、天然幂等。
  2. 消费者收到事件后,自己去常规端点 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)。

LearnHarness知识图谱视图:图谱节点的增删变化经由SSE事件通道实时推送,客户端按需拉取最新快照

验证与收尾:测试 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。

登录后查看全文
learnharness