tako 文档 GitHub

46 · 变更同步与事件通道

性质:已落地(2026-10-23)。Loop A(BroadcastChannel 同机失效)+ Loop B(账号级 SSE 事件流)全部施工并验收。 状态:✅ A1–A2、B1–B4 六拍 + P3 收口全部完成。 验收结论(2026-10-23):


0. 为什么写这份方案

背景:tako 的所有同步都是「拉」——会话列表是一次性 GET /api/sessions,项目页靠手动「刷新」,对话页在打开那一刻 reconcile 一次。系统里没有任何「谁改了什么」的通知。client(浏览器 tab)越多,每个 tab 手里的快照就越可能是假的。

这个病已经咬过三口,都是真实发生、不是假想:

症状一(已修):项目页展开过面板后,另一个 tab 在项目里新建了会话;原 tab 点「删除项目」时,级联文案和「连带清空当前对话」的判断用的是旧快照——服务端删的是 3 场,前端以为只有 2 场(2026-10-23 修:删除前无条件重拉)。

症状二(已修):项目页对同一场会话双击「打开」,两次 reconcile 交错,历史整体重复渲染——第一次重拉在清屏之后继续补行(2026-10-23 修:reconcile 全程令牌校验)。

症状三(开着,即 doc/44 遗留 nit):tab A 记住的「新对话落点项目」在 tab B 被删;tab A 发新对话时带着死项目 id,吃 404 114001,页面只能弹错,不会自愈回默认项目。

三个症状的共同点:变更发生的那一刻,其它 client 没有任何途径知道。Kimi 那类多端产品的标准件正是补这个的:一条长连接把「谁删了什么」推到所有在线 client(灵感来源见头注,内部实现未核实,不作依据)。本方案把这个模式落到 tako 的栈上,分两步走。

端到端链路(机制在链路中的位置见 §3):

client A(tab A)          服务端                      client B(tab B / 将来 IM)
    │  DELETE /api/sessions/:id                        │
    │ ─────────────────────→ │ 删行(PG 真源)           │
    │                        │ ── Loop A:A 自己广播 ──→│ BroadcastChannel:
    │                        │   (同机才有这条路)       │   「session X 没了」→ 失效
    │                        │ ── Loop B:XADD 事件流 ─→│ SSE /api/events:
    │                        │   (跨机跨端的路)         │   「session X 没了」→ 失效
    │                        │                          │ 失效 = 清落点 / 刷列表 /
    │                        │                          │   被删会话提示并退出
    │ ←── 下次任何拉取:真相都是新的(拉是正确性,流只是让它早点知道)

1. 名词准入(操作定义,后文不重复解释)

2. 现状锚点(方案就建立在这些事实上)

  1. 拉的清单(2026-10-23 实读):GET /api/sessions(server.go:772,一次性)、项目页手动「刷新」、对话页 reconcile 只在打开/恢复时跑一次(chat.ts:525)。没有任何变更推送。
  2. SSE 已有先例(doc/31):GET /api/runs/:id/stream 把 run 帧面推给 client,纪律是「拉是正确性、流是优化」。事件流复用这条纪律与这套运输认知,不新造哲学。
  3. Redis 已在栈里(tk:runlive:* / tk:runepoch:* 两个临时键 + asynq)。多副本纪律:进程内的 channel/缓存上线即失效,事件流必须落在共享的 Redis 上(根 AGENTS.md「部署形态」)。
  4. 临时键契约 currently 是两个(doc/16 §2c、doc/38):事件流键 tk:events:<tid> 会是第三个。这不是偷偷加键——§4 把它作为契约变更显式登记:事件流是「易失通知设施」,不是「run 存活态」,生命周期与真源划分和前两键不同。
  5. 多 tab 症状的病根已确认(doc/44 落地当天):症状一、二已修(都是「用前重拉/令牌」的治标法),症状三(落点失效)开着——治本的失效通知通道就是本方案。
  6. #8b 预留口(doc/30 §12):IM/cron 入口没有常驻页面可拉,「run 被删/被改」只能靠推。事件流是它们的共同前置——现在做一半的 BroadcastChannel 解决不了 IM 入口。
  7. 落点记忆的存法(doc/44、api.ts):localStorage['tako.workspaceId.<tid>']——失效逻辑要清的就是这个键;会话存储是 localStorage['tako.sessionId.<tid>'](同源同机,BroadcastChannel 够得着)。

3. 总设计

3.1 共同哲学:事件只通知,状态永远重拉

事件流是优化,不是真源。真源永远是 PG,client 的任何展示状态都必须能通过一次重拉重建——这条直接继承 doc/31。没这条纪律会怎样: tempted 在事件里带状态(标题、名字),client 开始省掉重拉,事件流一丢数据(MAXLEN 挤出、Redis 重启)各端状态就永久分叉——恰好是这套设施要消灭的病,以另一种形式回来。

3.2 Loop A · BroadcastChannel 半步(先行,半天)

做什么:变更端点成功后(当前只有三个写口:DELETE /api/sessions/:id、DELETE /api/workspaces/:id、PATCH /api/workspaces/:id 改名),前端在拿到成功响应后向同 origin 广播一条变更事件;每个 tab 启动时挂监听,收到事件交给统一的失效处理函数 handleMutation(evt)。

失效处理函数起步只做三件事(每步四问):

事件 做什么 输入 输出 不做的后果
workspace_deleted 清落点记忆(若落点 == id);项目页开着就重拉列表;侧栏树重拉(doc/50 A5) localStorage 键 + 当前视图 干净的落点/列表/侧栏 症状三原样复发;侧栏躺着一个点进去 404 的死项目
session_deleted 若正是当前打开的会话 → 气泡区换「已被删除」提示条并断 reconcile;项目页开着则移除该行 当前 sessionId 不显示已死会话 对着尸体发言,发出去吃 404
workspace_renamed 项目页开着就重拉列表;侧栏树重拉(落点只存 id 不受影响,doc/50 A5) 当前视图 新名字 名不对版,刷新才好的小刺

关键设计:这个 handleMutation 就是 Loop B 的前端部分。Loop A 的通知源是 BroadcastChannel,Loop B 换成 EventSource——失效逻辑一份,两个源都喂它。没这个设计会怎样:Loop B 落地时把失效逻辑重写第二遍,两个源的语义悄悄分叉。

盲区明说:BroadcastChannel 只到同机同 origin 的 tab。多设备、IM 入口不在它的覆盖里——那是 Loop B 存在的理由。

3.3 Loop B · 账号级 SSE 变更事件流

端点:GET /api/events(SSE,authn,按 token 里的租户过滤)。连接即挂读 Redis Stream;无事件时挂起(XREAD BLOCK 或等价轮询),有事件按 SSE data: 帧吐出。cursor 语义:Last-Event-ID 续传 = 从某个 entry id 之后读——断线重连不丢窗口内事件。

写口(落地后即成横切契约):每个「变更类端点」在删改成功之后 XADD tk:events:<tid> 一条事件。起步只接三个写口(同 Loop A);POST 创建类不发——新会话/新项目主要与创建者自己有关,列表页重拉即可覆盖,created 事件会把它变成噪音(登记为后话,见 §6)。没写口会怎样:流是空的,SSE 端点成了摆设——这正是「契约」和「一个端点」的区别:契约要求每个新变更端点落地时自觉地发事件。doc/52 C3 追加的写口:技能的安装(含 HITL 确认后的 skill_install)、更新、删除都发 skills_changed——它跨进程改变「下一场 run 的目录」,别的端不重拉就会拿旧目录办事(§7.6)。

事件字节(SSE 不进信封,同 doc/40 §6 对帧面的裁决):

data: {"seq":"1729628000000-0","type":"session_deleted","id":"s_01M…","at":"2026-10-23T02:13:20Z"}

前端接线:登录后挂 EventSource('/api/events'),收到帧 → 同一个 handleMutation。断线:EventSource 原生重连;重连后从 Last-Event-ID 续。Redis 挂了/流被清空:事件窗口内的事件丢失——client 无感,因为下次任何拉取都拿回真相(§3.1)。

多副本:写口所在副本 XADD 到共享 Redis,任何副本的 SSE 连接都能 XREAD 到——没有「事件必须经过哪个进程」的调度问题。这是事件流落 Redis 而不落进程内 channel 的直接理由(根 AGENTS.md:进程内状态上线即失效)。

4. 契约与契约变更登记

  1. 新端点:GET /api/events(SSE、authn、按租户隔离、Last-Event-ID 续传)。成功响应是 SSE 流,不进 {code,message,data} 信封(doc/40 §6 的既有裁决:SSE 帧面不进信封);鉴权失败按既有 401。
  2. 新 Redis 键(第三个,契约变更显式登记):tk:events:<tid> = Stream,MAXLEN ~ 1000 有界截断,易失。doc/16 §2c「临时键形态」契约随施工拍扩一行:前两键(runlive/runepoch)是「run 存活态」,本键是「租户级易失通知」,真源仍是 PG、丢了全量拉追回。这正是 doc/16 §2c 那三行表的既有写法——「是什么(人话)」里说清生命周期差异。
  3. 变更端点横切契约:自本方案落地起,新增「删除/改名/不可忽略的状态翻转」类端点时,必须同时接事件写口(XADD)或显式登记不发的原因。登记进 doc/16 §2c。
  4. 前端:handleMutation 是唯一失效入口,两个源(BroadcastChannel / EventSource)都喂它;失效必跟重拉。

5. Loop 拆分(点头后逐拍施工;每拍先交 todos.md)

顺序 A → B:A 半天埋掉症状三并把失效逻辑做成形;B 把通知源换成服务端通道,天然成为 #8b 前置。

Loop A · BroadcastChannel 半步

拍 改什么 怎么验收(第一行是 curl/两个窗口) 回答什么
A1 handleMutation 失效函数 + BroadcastChannel 监听/广播,接三个写口(删会话/删项目/改名) 两个窗口:A 窗口删会话 → B 窗口当场换提示条;A 删项目 → B 的落点记忆被清(再发新对话落在默认项目,不再 404);A 改名 → B 项目页名字当场变。npm run typecheck && build 绿 同机多 tab 的三个症状当场失效
A2 nit 4 顺手埋掉:投递吃 404 114001 且 id == 当前落点 → 清落点、回落默认项目重试一次 curl 造不出(要页面状态),验收走单测/手验:删落点项目后发新对话无感落到默认项目 报错路径变成自愈路径

Loop B · 账号级 SSE 事件流

拍 改什么 怎么验收(第一行是 curl) 回答什么
B1 events.go:XADD 写口封装(三个写口接入)+ tk:events:<tid> 流初始化;dev 探针或直连 redis-cli 可读 curl -N $TAKO/api/events -H "Authorization: Bearer $TOK" 挂住;另一个终端 curl -X DELETE $TAKO/api/sessions/:id → SSE 收到 data: {"type":"session_deleted",…} 一字不差 写口到流的链路通、字节钉死
B2 GET /api/events 端点(XREAD 挂读、Last-Event-ID 续传、authn、租户隔离) 同 B1 但走真端点;断线重连带 Last-Event-ID 能追回窗口内事件;跨两个引擎副本(起 8943 第二个实例连同一 Redis):A 副本删、B 副本的连接收到——多副本成立 服务端通道跨副本、跨进程
B3 前端 EventSource 接线:挂 /api/events,帧喂同一个 handleMutation;断线静默重连 两个窗口,其中一个换成隐私窗口(无 BroadcastChannel 通道的另一 profile 不行——同机同 origin 广播会漏给它;改用:杀掉另一窗口改用纯 SSE 验证:断开源码里的广播即可);实操:浏览器 + curl 当第二个 client——curl 删会话,浏览器页面当场失效 浏览器吃服务端事件走同一失效逻辑
B4 契约收口:contract_test.go 登记事件字节;expected.json 登记 B1/B2 用例;doc/16 §2c 两行(新键形态 + 变更端点契约)同批落;跑 check-master-plan.sh go test + assert_contract.py + check-expected.sh 全绿 两台机器 + 横切契约都钉住

脚手架与转正:无临时脚手架(B1 的 redis-cli 直读就是探针本身)。BroadcastChannel 代码在 B3 之后保留——它是同机失效的快路径,SSE 断线时兜底的正是它(两者喂同一函数,语义天然一致)。

6. 明确不做(本期)

7. 开放问题(点头时一起拍)

  1. 顺序 A→B(荐):A 半天埋症状三、把失效逻辑做成形;B 是 #8b 前置,等主线上需要多入口时再施工也来得及。
  2. 起步事件词表(荐):session_deleted / workspace_deleted / workspace_renamed 三个;created 不发。
  3. 流容量:MAXLEN ~ 1000 拍脑袋值,够覆盖「断线几分钟重连」的窗口;有异议施工拍再调。
  4. B3 的纯 SSE 验证姿势:BroadcastChannel 在同机存在会让「浏览器只靠 SSE 失效」不好单独验;方案里的姿势是 curl 当第二个 client。若有更干净的想法欢迎拍。
  5. SSE 鉴权姿势(实现拍,荐 query token):EventSource API 不能自定义头,而 token 存在 sessionStorage。荐 GET /api/events?access_token=<jwt>(仅本端点特例、token 短效);施工拍同时确认引擎 access log 不因此长期留存 token(会记则该端点摘出 query 日志),结论写进 §4。备选:前端 fetch + ReadableStream 手动读流(无自动重连,代码更多)。

7.5 2026-10-23 复审:SSE 重连死循环(已修)

这是本篇落地之后的复审发现,不在原方案里——原方案把「断线重连」当成网络抖动的小事,没料到它跟短效 access token 撞在一起会变成一个刷屏的死循环。

病灶

web/src/mutation.ts 的 ensureEventStream 里,事件流用 EventSource 连 GET /api/events?access_token=<jwt>。 onerror 的原处置是「关掉、3 秒后取最新 token 重建」。看着像能自愈,其实取不到新 token:

后果:引擎日志被 /api/events 的 401 刷满;事件流(跨端变更通知)实际是死的——别的端删了会话,这边收不到。

为什么难发现

它要三个条件同时成立才会现形:token 过期 + 连接断开 + 页面静止。 日常点几下页面,token 早就被 authFetch 顺手续上了,连接也不断——所以平时看不出问题。 一旦出问题,症状是「日志很吵」而不是「功能报错了」,很容易被当成网络抖动放过。

修法

onerror 里重建之前自己先刷一次 token:

onerror → 关掉 → 3 秒后 → refreshAccessToken() → 刷到了就用新 token 重建;刷不到(refresh token 也失效,clearAuth 已清)→ 就不重建,等用户重新登录

验收(对照实验,2026-10-23)

对着一个 access token 只有 20 秒的隔离引擎(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(把上面这套对照实验固化成可重跑的活体验收;未修复时判红退出)。 它自带一个短 TTL 的隔离引擎 + 一个指向它的 vite,不需要手工准备任何东西。

注意:起隔离引擎必须在 yk-tako-eino/ 目录下——引擎从 cwd 找 .env(模型密钥),找不到就「没有可用的模型厂商」直接退出。

7.6 2026-10-28 追加:skills_changed(doc/52 C3)

技能是跨 run 生效的状态:一个窗口里装了/删了一个技能,改的是「这个租户下一场 run 的目录」;别的窗口/别的机器如果只拿着旧列表,用户会看到「我刚装的怎么不见了」,管理员会对着已经删掉的技能点开关。这正是本方案 §3.1 那条纪律要覆盖的第四类变更,所以按 §4-3 的横切契约接了写口,而不是新造通道。

7.7 2026-11-10 追加:任务编排两类事件 + 心跳与续读(doc/70 §10.3)

持久 Task 让「用户不在场的后台工作」有了自己的状态机:任务页若只靠轮询,一行 Task 从执行到完成最长要等一个刷新周期;若靠浏览器自己 XREAD,又把通道复制了一份。所以按 §4-3 横切契约接两个写口,任务页收事件重拉——事件仍只通知,状态永远重拉(§3.1)。

8. 所以这解决了什么

三个多 tab 症状里,重拉和令牌只治了两个的标;本方案把第三个(落点失效)埋掉的同时,给系统装上「变更通知」这个一直缺的零件——先以 BroadcastChannel 的便宜形态在同机生效,再以 SSE 事件流成为跨端与 IM/cron 入口(doc/16 #8b)的共同前置。事件只通知、状态永远重拉,流的易失性因此不是缺陷而是设计。点头后从 A1 开工。