tako 文档 GitHub

7.9 业务用例链路:从用户视角看路由怎么串

每个用例给线上真实字节。验收就是把这些 curl 敲一遍、逐字节对。

样例约定:

用例索引(修订⑨ 后 13 个;★ = 帧路径在 v5 里变了):

# 场景 变化
1 ★ 首次打开 + 首次发消息 首条消息才铸会话(202 回带 id);流在其后挂载
2 ★ 发消息时已有 run 在跑 修订⑨:409 session_busy + 客户端本地队列 + run_terminal 后补投(取代原排队/合并)
3 ★ 刷新页面 与用例 11 合并成同一条路径;Snapshot 无 queued 字段
4 ★ 多标签页 / 多设备同步 删除(修订⑩):跨端同步后置,用例随之后置、编号保留不重排
5 ★ 进程重启 EventSource 自动重连 + Last-Event-ID;无 inbox 续答(修订⑨)
6 ★ 审批挂起期间投递 修订⑨:一律 409 session_busy(原「收件箱照收」)
7 ★ 停止 修订⑨:停止后自动开跑 = 客户端队列补投
8 删会话 流被断开的方式不变
9 未登记 / 已删 sessionId 不变
10 滚到顶翻历史 不变
11 ★ SSE 单独断线重连 Last-Event-ID 自动续传,不再依赖前端记游标
12 run 中途压缩 不变
13 inject 插话(后置能力) 不变

修订⑨ 删除的三个用例:撤回排队消息(原 4,端点不存在)、清空收件箱(原 9)、 队列上限 422(原 12,无服务端背压,§9.5 第 5 条)。队列相关语义全部收进用例 2。


用例 1:首次打开页面 + 首次发消息

⓪ (本地无 sessionId)→ 不请求服务器,呈现空会话
③ POST /api/message {messageId:"m_1", text:"读一下 doc/19"}(不带 sessionId)
   → 202 {"sessionId":"s_1","seq":1,"messageId":"m_1"},存下 s_1   ← 首条消息,事务内含铸会话(§1.3)
② GET /api/session/stream?id=s_1&from=0        ← 拿到 id 后才挂;唯一的一条流,常驻
   UI:不画任何气泡,等帧(§6.3 约束 2);from=0 自 message_queued 起重放补齐

数据样例(流上依次的帧):

id: 1::
data: {"seq":1,"ts":"T0","kind":"message_queued","messageId":"m_1","text":"读一下 doc/19"}

id: 2::
data: {"seq":2,"ts":"T0","kind":"run_started","runId":"r_17","messageId":"m_1","text":"读一下 doc/19"}
      ↑ UI:m_1 气泡 sent → answering。★ 没有「挂第二条流」这一步;一轮 run 只消费一条 message

id: 2:r_17:1
data: {"run":"r_17","rseq":1,"ts":"T0","kind":"start","text":"读一下 doc/19"}

id: 2:r_17:2
data: {"run":"r_17","rseq":2,"ts":"T1","kind":"message","agent":"tako","role":"assistant","text":"好","final":false}
id: 2:r_17:2
data: {"run":"r_17","rseq":2,"ts":"T2","kind":"message",…,"text":"好的,我来读一下 doc/19。","final":false}
      ↑ 同一 rseq 重复 = 原位更新,前端原位替换气泡(每一帧背后都是库里的一行,§1.1)
id: 2:r_17:2
data: {"run":"r_17","rseq":2,"ts":"T2","kind":"message",…,"text":"好的,我来读一下 doc/19。","final":true}
      ↑ final:true = 定稿。这就是 v4 的「sealed」,但它只是同一行的最后一次 UPDATE

id: 2:r_17:3
data: {"run":"r_17","rseq":3,"ts":"T2","kind":"complete"}
      ↑ run 视图收尾。★ 流不关——它管的是会话,不是这一场 run

id: 3::
data: {"seq":3,"ts":"T2","kind":"run_terminal","runId":"r_17","terminalKind":"complete"}
      ↑ m_1 answering → answered

终局仍是两帧:run 级 complete(rseq=3)+ 会话级 run_terminal(seq=3)。前者收尾内容视图, 后者让所有客户端(包括没展开看内容的)知道落幕。Feed 保证 run_terminal 在内容排空之后才发(§4.4 规则 4)。

③ 与第一帧的顺序不保证:帧必然在 202 之前到达(同一事务提交,§5.9),前端按 messageId 对齐。


用例 2:发消息时已有 run 在跑(修订⑨:忙时 409 + 客户端队列)

① POST /api/message {messageId:"m_2", expectedRunId:"r_17", text:"顺便看看 v1"}
   ← 409 {"error":{"code":"session_busy",…,"detail":{"liveRunId":"r_17"}}}
   服务端:闸检查非空 → 事务整体回滚 → 库里什么都没有(无帧、无行、不占 seq)
   前端:m_2 进本地队列,画「等待中」提示
② r_17 落幕 → run_terminal(r_17) → 前端出队补投:
   POST /api/message {messageId:"m_2", text:"顺便看看 v1"}(不带 expectedRunId——补投是新一轮)
   ← 202 {"seq":4,…} → 走一遍用例 1 的事务,开 r_18
③ r_18 终局帧 → run_terminal(r_18) → m_2 answered

数据样例(会话级 seq 承接用例 1;seq=4 是补投那一刻取的,不在 409 时):

(r_17 落幕)
id: 3::
data: {"seq":3,"ts":"T9","kind":"run_terminal","runId":"r_17","terminalKind":"complete"}
      ↑ 前端出队补投 m_2

id: 4::
data: {"seq":4,"ts":"T10","kind":"message_queued","messageId":"m_2",…,"text":"顺便看看 v1"}
id: 5::
data: {"seq":5,"ts":"T10","kind":"run_started","runId":"r_18","messageId":"m_2","text":"顺便看看 v1"}
id: 5:r_18:1
data: {"run":"r_18","rseq":1,"ts":"T10","kind":"start","text":"顺便看看 v1"}
…

另一种 409:stale_view(客户端自己的错,语义不变):

← 409 {"error":{"code":"stale_view",…,"detail":{"liveRunId":"r_17"}}}
   前端:刷新视图,把输入还回输入框让用户决定。不自动重试。
   (fencing 检查在事务内、闸检查之前,消息从未落库,重发复用同一 messageId 安全。)

重发的三种结局(修订⑨ 后唯一仲裁是客户端约束 4,§6.3):


用例 3:刷新页面,run 正在跑(v5:与用例 11 同一条路径)

① GET /api/session?id=s_1 → {"liveRunId":"r_17","lastSeq":3}
   UI:画 r_17 的「正在回答」占位(修订⑨:没有 queued 字段——队列在客户端,
   刷新后本地队列已丢,§9.5 第 4 条)
② new EventSource(/api/session/stream?id=s_1&from=3&runFrom=0)
   → Feed 追赶:游标 run 为空 → 会话级 seq>3 无帧 → live 兜底(§4.4 规则 3):
     回放 r_17 已落库内容(含生成中行的当前文本)→ 切实时
流(追赶阶段,r_17 仍在跑):
id: 3:r_17:1
data: {"run":"r_17","rseq":1,"kind":"start","text":"读一下 doc/19"}
id: 3:r_17:2
data: {"run":"r_17","rseq":2,"kind":"message",…,"text":"好的,我来读一下 doc/19。","final":true}
id: 3:r_17:3
data: {"run":"r_17","rseq":3,"kind":"tool_call",…,"toolCalls":[{"name":"read_file","args":"{\"path\":\"doc/19-…-v5.md\"}"}]}
id: 3:r_17:4
data: {"run":"r_17","rseq":4,"kind":"tool_result",…,"toolName":"read_file","text":"<文件原文>"}
id: 3:r_17:5
data: {"run":"r_17","rseq":5,"kind":"message",…,"text":"文件里第二节讲的是","final":false}
      ↑ ★ 生成中行也回放:v4 里刷新后要等 seal 才能看到这半截,v5 里立刻可见(§1.1)
(此后实时帧与重放帧同形状、同流、客户端无需区分)

用例 4:多标签页 / 多设备同步 —— 删除(修订⑩)

跨端同步整体后置(§11 问题 15),「多端看到一致内容」不再是当前方案的设计保证与验收对象。 原用例内容(每端一条流、帧逐字节相同、各端各排各的队列)未丢失——它是存储结构的物理事实, 届时讨论方案时作为输入材料。编号保留不重排。


用例 5:进程重启(修订⑨:无 inbox 续答)

崩溃前:session_log seq 1..3,r_17 在跑(run_log 里有一行 final=0 的正文)
—— 进程死掉。SSE 断开,浏览器 EventSource 进入自动重连 ——

重启后服务端只剩一步(§7.8):
  Engine.Reconcile     → r_17 租约已过期(进程死了没人续租)→ 一个事务:
                        status=failed + error 终局帧
                        + ★ r_17 的 final=0 行定稿为 outcome:"interrupted"(文本保留)
                        + seq=4 {run_terminal, r_17, "error"}
  (修订⑨:没有 sessionLog.Reconcile / trySchedule——没有收件箱要捞;
   r_18 不会自己开跑,等客户端补投)

客户端:EventSource 自动重连,带上 Last-Event-ID: 3:r_17:5
→ GET /api/session/stream?id=s_1    (Last-Event-ID 头携带双游标,优先于显式参数,§4.3)
流(Feed 追赶,§4.4 规则 1:游标 run 单独补齐):
id: 3:r_17:5
data: {"run":"r_17","rseq":5,"kind":"message",…,"text":"文件里第二节讲的是","final":true,"outcome":"interrupted"}
      ↑ 游标行是 message 行,随重放重发(§4.3)——它正是崩溃时被定稿的半截正文,
        用户刷新前看到的每个字都还在。前端按「同 rseq 原位替换」处理,零新分支
id: 3:r_17:6
data: {"run":"r_17","rseq":6,"kind":"error","text":"进程重启,本轮中断"}
id: 4::
data: {"seq":4,"kind":"run_terminal","runId":"r_17","terminalKind":"error"}
      ↑ 前端此刻出队补投本地队列队首(若有)——用例 2 的第 ② 步

v4 的失效场景 D(重挂旧流永远等不到终局)在 v5 里连场景都不存在: 没有「旧流」,只有一条流;Reconcile 补的终局帧照样落库,但客户端等它的方式 是「流的追赶阶段自然会播到它」,不是「一条悬空的订阅终于闭合」。

修订⑨ 的已知损失:崩溃前在客户端本地排队的消息随浏览器状态而定—— 刷新过就没了;服务端重启不丢任何东西,因为服务端本来就没有队列状态(§9.5 第 4 条)。


用例 6:审批挂起期间投递(修订⑨:一律 409)

流(r_17 进行中):
data: {"run":"r_17","rseq":5,"kind":"approval","approval":{"id":"s_1-a1","tool":"write_file","args":"…","message":"要写这个文件"}}
→ POST /api/message {messageId:"m_2",…} ← 409 session_busy(闸被占着——审批挂起也占闸)
   前端:进本地队列。原「收件箱照收」语义删除。
→ POST /api/approval {"sessionId":"s_1","requestId":"s_1-a1","decision":"approve"} ← 200
data: {"run":"r_17","rseq":6,"kind":"approval_result","approval":{"id":"s_1-a1","decision":"approve"}}
data: {"run":"r_17","rseq":7,"kind":"tool_result","toolName":"write_file","text":"已写入 doc/20.md"}
…
data: {"run":"r_17","rseq":9,"kind":"complete"}
data: {"seq":5,"kind":"run_terminal","runId":"r_17","terminalKind":"complete"}
      ↑ 前端补投 m_2 → 202 → run_started(r_18, m_2)

decision 只接受 approve / reject;reject 时 run 不结束,模型自己决定怎么办。


用例 7:停止(修订⑨:自动开跑 = 客户端补投)

→ POST /api/stop {"sessionId":"s_1","run":"r_17"} ← 200(run 对不上则 404)
data: {"run":"r_17","rseq":6,"kind":"stop"}
data: {"seq":4,"kind":"run_terminal","runId":"r_17","terminalKind":"stop"}
      ↑ 前端出队补投本地队列队首(若有):
        POST /api/message {messageId:"m_2",…} ← 202 → run_started(r_18, m_2)
        UI 必须事先明示队列非空(§6.3 约束 1),并给一键清空(清本地队列)

语义不变,担子换了边:停止的语义是「这一轮不对」,不是「我说的话不算」—— 原服务端 Drain 收件箱自动开跑,现由客户端在 run_terminal 后补投,效果同一条。


用例 8:删会话

→ DELETE /api/session/s_1 ← 204
   服务端 §5.9 三步(修订⑨):取消 live(以 sessionID 为键,不依赖客户端知道 runID)
   → 同事务删五张表 → CloseSession + InvalidateCache

所有客户端的流:连接被服务端关闭(不是收到一帧,是流断了)。
客户端 EventSource 自动重连 → GET 准入检查 404 → 前端清掉本地 id 回空会话态;
下一条消息将铸新会话(§6.1 ⓪)。本地队列随前端清会话一并丢弃。
被取消的 r_17 若在写帧:emit 撞已删除的行 → persistErr → 退出。没有行可写。

验收:删后查五张表 session_id='s_1' 行数为 0;等 10 秒再查,仍为 0。


用例 9:未登记 / 已删除的 sessionId(不变)

→ GET /api/session?id=s_9        ← 404 session_not_found → 前端清掉本地 id,回空会话态
→ GET /api/session/stream?id=s_9 ← 404(准入在挂流之前,不建连接)
→ POST /api/message {"sessionId":"s_9",…} ← 404(绝不隐式创建,不变量 1)
★ 唯一合法的创建入口是不带 sessionId 的首条消息(§1.3):它回 202,不回 404。

用例 10:滚到顶翻历史(不变)

→ GET /api/session/history?id=s_1&limit=20
← 200 {"runs":[{"runId":"r_16","createdAt":"…","status":"complete","events":[…]}, …],
       "nextCursor":"…|r_-3"}

HistoryPage 不含 running 的行。队列中的消息不进历史(它在客户端本地,服务端不知道)。


用例 11:SSE 断线重连(v5:与用例 3 同路径,且自动)

断开前最后一帧:id: 3:r_17:7   (一条 tool_result——非 message 行,写入即定稿、不可变)
—— 网络抖 3 秒。这期间本端又投了一条 m_2(若当时不忙则已 202;若忙则进本地队列)、
   r_17 落幕 ——
浏览器 EventSource 自动重连:GET /api/session/stream?id=s_1
  请求头 Last-Event-ID: 3:r_17:7        ← 浏览器自动带的,前端没写一行代码;
                                          服务端以它为准,忽略 URL 里可能存在的旧 from=(§4.3)
流(Feed 追赶,§4.4 规则 1:游标 run 单独补齐):
id: 3:r_17:8
data: {"run":"r_17","rseq":8,…}                ← r_17 剩余内容。游标行(rseq=7)非 message、
                                                 不可变,不重发;若它是 message 行则会先重发它(§4.3)
id: 3:r_17:9
data: {"run":"r_17","rseq":9,"kind":"complete"}
id: 4::
data: {"seq":4,"kind":"run_terminal","runId":"r_17","terminalKind":"complete"}
      ↑ 若本端有本地队列,此刻出队补投

v4 在这条用例里登记的前端陷阱(sessionSeq 必须每帧更新,报大了丢帧兜不住) 由 SSE 协议本身接管:游标跟着 id: 走,浏览器负责记住它,服务端负责解释它。 前端仍可在业务层维护游标做 UI 对账,但续传正确性不依赖它。


用例 12:run 中途压缩(不变)

data: {"run":"r_18","rseq":4,"kind":"compact","text":"上下文较长,正在压缩早期对话"}

轻提示,不产生会话级帧。压缩后翻历史:被压 run 的 run_log 帧原样可读(字还在), 被清的是 produced_json(下一轮模型看到什么)——两个真源的区分不变。


用例 13:inject 插话(后置能力,不变)

delivery:"inject" → 走 eino BeforeModelRewriteState 钩子 append 进 state.Messages。 帧协议表达力问题与 v4 相同(没有 run_started 跟随),§11 问题 11 倾向加 message_injected 帧。 启动条件不变:after 模式稳定且真的嫌等太久。