变更同步用事件通道:事件只通知,状态永远重拉
模块:运行引擎 · 变更同步与前端(doc/46)|状态:已落地(2026-10-23,Loop A + Loop B;2026-10-28 追加
skills_changed)|证据:doc/46-变更同步与事件通道.md、internal/runengine/events.go、web/src/mutation.ts
1. 场景与病灶
tako 的所有同步都是「拉」:会话列表是一次性 GET /api/sessions,项目页靠手动刷新,对话页在打开那一刻 reconcile 一次。系统里没有任何「谁改了什么」的通知。client(浏览器 tab)越多,每个 tab 手里的快照就越可能是假的。
这个病已经咬过三口,都是真实发生:
症状一(已修):项目页展开过面板后,另一个 tab 在项目里新建了会话;原 tab 点「删除项目」时,级联文案和「连带清空当前对话」的判断用的是旧快照——服务端删的是 3 场,前端以为只有 2 场。
症状二(已修):项目页对同一场会话双击「打开」,两次 reconcile 交错,历史整体重复渲染。
症状三(本方案治本):tab A 记住的「新对话落点项目」在 tab B 被删;tab A 发新对话时带着死项目 id,吃 404 114001,页面只能弹错,不会自愈回默认项目。
三个症状的共同点:变更发生的那一刻,其它 client 没有任何途径知道。
2. 候选与代价
| 候选 | 做法 | 好处 | 代价 |
|---|---|---|---|
| A 每个 tab 定时全量重拉 | 轮询列表接口 | 零新概念 | 绝大多数请求白跑;实时性差;删除类变更仍有窗口期 |
| B WebSocket | 双向长连接 | 客户端也能推 | 客户端只收不发(发言走 POST),WS 的重连/协议成本换不到东西 |
| C 事件流 + 状态重拉(选定) | 服务端推「谁改了什么 id」,client 收到就作废本地状态并重拉 | 覆盖跨机跨端;事件不带状态,流丢了也不分叉 | 需要新端点 + 新 Redis 键 + 横切写口契约 |
| D 事件携带完整状态 | 事件里带会话标题、项目名、技能内容,client 直接用 | 省一次重拉 | 事件一丢(MAXLEN 挤出、Redis 重启)各端状态永久分叉——恰好是这套设施要消灭的病,以另一种形式回来 |
选 C。关键纪律(继承 doc/31):事件只通知,状态永远重拉。真源永远是 PG,client 的任何展示状态都必须能通过一次重拉重建。
3. 两步走:BroadcastChannel 半步,SSE 一步
| Loop A · BroadcastChannel | Loop B · 账号级 SSE | |
|---|---|---|
| 覆盖范围 | 同机同 origin 的 tab | 跨机、跨端、将来 IM/cron 入口 |
| 通知源 | 删东西的那个 tab 自己广播 | 服务端 XADD tk:events:<tid> |
| 后端改动 | 零 | 新端点 + 新 Redis 键 + 三个写口 |
| 工期 | 半天 | 一个正经 loop |
| 两者关系 | 同一个 handleMutation 失效函数,两个通知源都喂它 |
同左 |
为什么先做半步:Loop A 半天内埋掉症状三、并把失效逻辑做成形;Loop B 换源即可,不会把失效逻辑重写第二遍(否则两个源的语义会悄悄分叉)。
为什么半步不是白做:BroadcastChannel 在同机是快路径;SSE 断线时兜底的正是它——两者喂同一个函数,语义天然一致。所以 B3 之后 BroadcastChannel 代码保留。
4. 失效处理函数只做三件事
| 事件 | 动作 | 不做的后果 |
|---|---|---|
workspace_deleted |
清落点记忆(若落点 == id);项目页开着就重拉列表 | 症状三原样复发 |
session_deleted |
若正是当前打开的会话 → 气泡区换「已被删除」提示条并断 reconcile;项目页开着则移除该行 | 对着尸体发言,发出去吃 404 |
workspace_renamed |
项目页开着就重拉列表(落点只存 id 不受影响) | 名不对版,刷新才好 |
失效之后永远跟一次重拉,本地不留事件的任何副本。
5. Loop B 的契约要点
端点 GET /api/events(SSE、authn、按 token 里的租户过滤)。连接即挂读 Redis Stream,无事件时挂起。Last-Event-ID 续传 = 从某 entry id 之后读。
事件字节(SSE 不进信封):
data: {"seq":"1729628000000-0","type":"session_deleted","id":"s_01M…","at":"2026-10-23T02:13:20Z"}
| 细节 | 裁定 | 为什么 |
|---|---|---|
| 承载 | Redis Stream tk:events:<tid>,MAXLEN ~ 1000 有界截断,易失 |
事件丢了 client 下次全量拉就追回真相。这是第三个临时键,作为契约变更显式登记进 doc/16 §2c |
| 为什么落 Redis 不落进程内 channel | 写口所在副本 XADD,任何副本的 SSE 连接都能 XREAD |
进程内状态上线即失效;多副本天然安全,无「事件必须经过哪个进程」的调度问题 |
| created 类事件 | 不发 | 新会话/新项目主要与创建者自己有关,列表页重拉即可覆盖;created 事件是噪音 |
skills_changed(2026-10-28 追加) |
发;id 是技能名不是行 id |
技能是跨 run 生效的租户级状态:一个窗口装了/删了技能,改的是「下一场 run 的目录」。use_skill/read_skill 只读,不发(每场 run 几十次,会冲成噪音) |
| 写口横切契约 | 自本方案起,新增「删除/改名/不可忽略的状态翻转」类端点必须同时接事件写口,或显式登记不发的原因 | 「契约」与「一个端点」的区别:不接写口,流就是空的,端点成摆设 |
| SSE 鉴权 | GET /api/events?access_token=<jwt>(EventSource 不能自定义头) |
gin 日志只记 Path,不长期留存 token |
| 事件落 PG | 不做 | 易失设施不背持久化;要对账用审计表,那是另一条线 |
| 离线推送(APNs/邮件/Webhook) | 不做 | 等 IM 入口(doc/16 #8b)再议 |
| 协同编辑/状态同步 | 不做(doc/42 已拍) | 本方案只管删除/改名这类离散变更 |
6. 落地后复审发现:SSE 重连死循环(2026-10-23,已修)
这是落地之后的复审发现,不在原方案里——原方案把「断线重连」当成网络抖动的小事,没料到它跟短效 access token 撞在一起会变成刷屏死循环。
病灶链条,三个条件同时成立才现形:token 过期 + 连接断开 + 页面静止 → onerror 关掉 → 3 秒后拿过期的 token 重建 → 服务端一律 401 → 再 onerror → 永远停不下来。
为什么难发现:日常点几下页面,token 早被 authFetch 顺手续上,连接也不断。出问题时的症状是「日志很吵」而不是「功能报错」,很容易被当成网络抖动放过。
修法:onerror 里重建之前自己先刷一次 token;刷到就用新 token 重建,刷不到(refresh token 也失效)就不重建、等用户重新登录。
对照实验(TAKO_ACCESS_TTL=20s 的隔离引擎,页面静止到 token 过期再重启引擎):
/api/auth/refresh |
/api/events |
|
|---|---|---|
| 修之前 | 0 次 | 401 × 7(每 3 秒)、200 × 0 —— 事件流实际是死的 |
| 修之后 | 1 次(200) | 401 × 0、200 × 1 —— 一次刷新后自愈 |
回归网:scripts/acceptance/sse_reconnect.sh(未修复时判红)。
7. 证据
方案:doc/46-变更同步与事件通道.md §0(三个症状)§1(名词准入)§2(现状锚点)§3.1(共同哲学)§3.2(Loop A)§3.3(Loop B)§4(契约与契约变更登记)§5(六拍)§6(不做)§7(开放问题)§7.5(重连死循环)§7.6(skills_changed)。
台账:tmp/46-变更同步与事件通道/(本地,不入库)。
代码符号:
| 位置 | 是什么 |
|---|---|
internal/runengine/events.go:41 |
eventsMaxLen = 1000:流容量 |
internal/runengine/events.go:44 |
keyEvents:tk:events:<tid> |
internal/runengine/events.go:48 |
Server.publishEvent:写口(XADD) |
internal/runengine/events.go:54 |
Store.PublishEvent |
internal/runengine/events.go:97 |
Server.getEvents:SSE handler |
internal/runengine/server.go |
GET /api/events 路由注册 |
internal/runengine/auth.go |
?access_token= query 兜底鉴权 |
internal/runengine/product_api.go |
删除/改名写口接事件 |
internal/runengine/contract_test.go |
TestContractStreamEventBytes 钉事件字节 |
web/src/mutation.ts |
handleMutation 唯一失效入口 + ensureEventStream |
web/src/api.ts、chat.ts、App.vue、ProjectsView.vue |
三个源(BroadcastChannel / EventSource / 自愈重试)接线 |
scripts/acceptance/events_live.sh |
活体判红 |
scripts/acceptance/sse_reconnect.sh |
重连死循环回归网 |
复核命令:
cd yk-tako-eino
grep -n "tk:events\|XADD\|/api/events" internal/runengine/events.go internal/runengine/server.go
grep -n "handleMutation\|ensureEventStream\|BroadcastChannel\|EventSource" web/src/mutation.ts
grep -n "skills_changed" internal/runengine/*.go | grep -v _test
bash ../scripts/acceptance/events_live.sh # 需隔离引擎活体验收(2026-10-23):
- Loop A:iframe harness(同机双 tab 的等效物)5/5 + 3/3 全过;A2 投递自愈——落点项目被删后
114001自动清落点回落默认项目重试一次。 - Loop B:活体 7/7(挂读 / 续传不回放 / 新连接静默 / query token / 双副本互证);前端 EventSource 与 BroadcastChannel 并存、同喂一个 dispatch,真后端事件 harness 3/3。
- 契约:
TestContractStreamEventBytes钉字节;用例 9 登记进expected.json的declared_not_asserted+ 契约散文;events_live.sh判红。 - 2026-10-28
skills_changed:隔离引擎 8943 上curl -N /api/events挂着,另一终端DELETE /api/skills/<name>→ 收到{"type":"skills_changed","id":"<name>"};重装再收一条。
8. 现状
- 仍有效:事件只通知、状态重拉;BroadcastChannel + SSE 双源同喂一个失效函数;Redis Stream 易失且有界;写口横切契约;query token。
- 已修:SSE 重连死循环(§6)。
- 明确不做:WebSocket、事件携带状态、created 类事件、离线推送、事件落 PG、协同编辑。
- 同族问题:SSE 运输哲学与帧面 → 前端拉帧还是切流;落点记忆与多 tab 症状 → 前端可用性欠账;临时键纪律 → 崩溃后这场 run 算什么状态;技能变更写口 → 技能谁读谁执行。