tako 文档 GitHub

变更同步用事件通道:事件只通知,状态永远重拉

模块:运行引擎 · 变更同步与前端(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):

8. 现状