tako 文档 GitHub

前端拉帧还是切流:加一条流,但不把正确性交给它

模块:运行引擎 · API 面与前端(doc/31)|状态:端点已落地(2026-10-18 A1–A4);前端未切流(刻意)|证据:doc/31-sse流式端点.md、internal/runengine/server.go

1. 场景与病灶

一个外部消费方(curl 脚本、SDK、别的产品进程)想在终端里打字机式展示 tako 的回复。现在的四 API 是纯拉——没有任何一条路能让服务端把「有新帧了」主动送到一个还挂在连接上的消费方手里。

他必须自己写这个循环:

loop:
  sleep 300ms                                  ← 节奏他自己定
  GET /api/runs/r_1/frames?eventOffset=N       ← 他自己攒游标
  status==generating → 继续睡
  status==done      → 收口
  status==gone      → 转拉 log 对账            ← 三态语义他必须全懂

要正确跑通,他得先读完契约文档的全部字节规则(帧 kind 清单、nextOffset、单批上限 W、agent/model 字段、gone 转拉),再把这套样板抄进自己的语言。每个集成方重写一遍,抄错任何一处就是丢帧或死循环。

轮询本身还有一笔税:300ms 间隔意味着绝大多数请求返回空批——白来的 HTTP 往返;拉长间隔省往返,实时性就掉。服务端明明知道「第 7 号帧刚压进去」,却只能等下一次轮询才说得出口。

2. 候选与代价

候选 做法 好处 代价
A 什么都不加 消费方自己写轮询样板 零改动 每个集成方重写一遍;服务端知道也不说
B 加流并当唯一实时通道(2026-10-02 裁定的形态) stream 与 frames 两路状态源,客户端收流同时还要拉 frames 补漏 实时 两路合并的复杂度真实存在——这正是 10-02 删掉流的理由
C 流拉并存,流只是第二种运输方式(选定,2026-10-18 用户拍) 新增第五个端点;流交付的字节与 frames 逐字节同形状;断线恢复/新 tab/补历史/收口对账全部仍走拉 集成方一次 GET 读到 terminal;四 API 零改动;纯增量 多一个端点、多一条 tail 循环;线程/连接成本
D 加流并让前端切过去 web 也改吃 SSE 前端省轮询 前端拉路已验收,切流是优化不是需求;两套消费路径要同时维护

选 C。10-02 当初删流对在哪:那时 SSE 的定位是唯一实时通道,双路合并复杂度真实存在。现在为什么不对:流不再承担任何正确性职责——所谓「双路合并」不需要回来,因为消费逻辑本来就只有一份,无论字节从流来还是从拉来,都喂给同一套「delta 追加、按 runId 对 log 收口、gone 转拉」。

不变量一句话:拉是正确性,流是优化。

3. 端点契约要点

GET /api/runs/{runId}/stream,200 Content-Type: text/event-stream。帧真源就是 runlive Redis LIST,流 handler 循环调 ReadFrames——与 frames 端点同一个存储原语。流上没有新帧形状:kind 集合与 frames 契约同一份,字段逐一相同。

细节 裁定 为什么
id: 行 = 该帧的 eventOffset 重连带 Last-Event-ID: N 从 offset > N 继续——同一个游标的第二种读法,不是新游标
event: gone 连接建立时 runlive 键已不存在 → 推一条后关闭 与 frames 的 200 gone 同语义,含「从未存在」与「TTL 过期」,故意不区分
terminal 帧 推完服务端主动关连接 run 结束 = 流的自然终点(complete/error/stopped 同)
心跳 每 15 秒一行 : ping(无 data) 防 NAT/代理掐闲连接;10-02 删心跳是因为纯拉无连接可掐,流模式没有它会「无声断流」
单批上限 W 不适用 W 是拉路「防超长回复撑爆单次响应」的概念,流逐条推、无批
未知 runId 不回 404,200 + gone 同 frames
建流之后内部错误 直接断流 SSE 协议没有错误语义;消费方凭「断了且没 terminal」知道该重连
鉴权/压缩/重放 照多租户的缝走,不在本拍 —

4. tail 为什么用定时读,不用事件通知

handler 是 Gin 循环:读 Last-Event-ID → ReadFrames(ctx, runID, from, W) → 逐条写 + flush → 末帧 terminal 就关、键不存在推 gone → 否则 sleep 150ms 再来一轮。

不用进程内 chan / pubsub 通知,理由挂 AGENTS.md 的硬规矩:进程内等待者上线即失效。定时读 Redis 天然多副本安全——任何副本都能服务任何 run 的流,零粘性路由、零每连接状态(offset 就是游标本身)。

代价:每连接每 150ms 一次 LRANGE 空转,连接数上去后这笔账要实测。Redis pub/sub 唤醒登记为演进方向,本拍不做。

5. 同族小裁定

小问题 裁定 代价 / 备注
web 前端切不切流 不切 拉路已验收;流是优化不是需求。前端今天仍走 frames 轮询(web/src/chat.ts 无 SSE 消费)
会话级流 / 多 run 聚合流 / 历史流 不做 历史回放走 log 端点,流只管「生成中」这一段
tail 间隔 / 心跳间隔 常数(150ms / 15s),不开旗标 方案 §9 原留「旗标还是常数,施工拍定」→ 施工定为常数(server.go:1083-1084)
retry: 行 不加 重连间隔由消费方自己控;待拍项里判「小项,可随契约拍定」
event 名 只有 frame / gone 两个 够用
回压 Write 阻塞 → tail 停摆,不丢帧;断开重连从 Last-Event-ID 补 消费方读得慢不会把服务端拖垮
连接中途断 服务端 ctx 取消即退出,无清理义务 每连接零状态,所以没有「清理」这回事
子代理帧 原样推(带 agent/model) 消费方自决渲染与否
流能不能用来收口 能,但不是必须——收到 terminal 可以直接收口,也可以再拉一次 log 验一遍 流不承诺可靠送达;收口对账以拉路为准

6. 证据

方案:doc/31-sse流式端点.md §2(病灶戏)§3(与 10-02 b2 裁定的对质)§4(端点契约)§5(服务端机制)§6(边界情形)§7(不做清单)§8(五条 curl 验收)§9(待拍清单)§10(闭环)。翻案标注落在 19v6-01 §0 与新 §5、19v6-90 二次修订段、doc/16 能力表 7d 行。

台账:tmp/31-sse流式端点/(本地,不入库)。

代码符号:

位置 是什么
internal/runengine/server.go:116 路由注册 GET /api/runs/:runId/stream
internal/runengine/server.go:1083 sseTailInterval = 150ms
internal/runengine/server.go:1084 sseHeartbeatInterval = 15s
internal/runengine/server.go:1112 Server.getRunStream:建流 → 推存量 → 判终 → tail
internal/runengine/server.go:1136 心跳分支

复核命令:

cd yk-tako-eino
grep -n "getRunStream\|sseTailInterval\|sseHeartbeatInterval" internal/runengine/server.go
grep -rn "EventSource\|text/event-stream" web/src/ | head        # 应为空:前端未切流

# 金路径(先起隔离引擎)
curl -N http://127.0.0.1:<port>/api/runs/<rid>/stream
# 断线续传
curl -N -H "Last-Event-ID: <N>" http://127.0.0.1:<port>/api/runs/<rid>/stream

活体验收(2026-10-18,五场):金路径 start → delta… → terminal 后连接自动关闭;Ctrl-C 后带 Last-Event-ID: N 重连首帧 offset = N+1;已过期 runId 得到一条 event: gone 即关;error run 的 terminal status:"error" 后关闭;长工具执行挂 20s 至少一条 : ping。单测 4 件 + 全量 runengine 15.1s 绿 + vet 干净。

7. 现状