前端拉帧还是切流:加一条流,但不把正确性交给它
模块:运行引擎 · 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. 现状
- 仍有效:「拉是正确性,流是优化」;第五端点是纯增量;字节与 frames 同形状、游标同源;定时 tail;心跳;前端不切流。
- 演进方向(未做):Redis pub/sub 唤醒 tail(等空转成本实测);web 前端切流(独立拍,待拍项 1)。
- 同族问题:帧面与游标语义 → 崩溃后这场 run 算什么状态;前端怎么重建半截气泡 → 界面验收双轨;变更同步的通道 → 变更同步用事件通道。