tako 文档 GitHub

19 · 运行引擎架构 v5

这是文档版本,不是软件版本。 本文取代 v4(doc/19-运行引擎架构-v4.md), 自包含,不依赖任何先前版本的方案文档,也不以旧实现的代码为依据。

性质:设计方案,尚未实施。实施方式是重写,不是重构——新 module 从零起步, 与运行引擎无关的能力包(工具集、guard、压缩、媒体落盘、eino 封装)作为既有资产搬入。

术语:message 指用户投递的一条输入;run 指一次执行;一场 run 消费一条 message (合并语义已删,§9.5)。会话(session) 是服务端登记过的资源,有身份、有创建事实。

评审后修订(七处勘误 + 修订⑨⑩;架构方向与 §0 四个改动不变): ① §4.3 游标优先级反转——Last-Event-ID 优先于显式参数,否则浏览器自动重连会拿 URL 里的旧游标重播全部帧; ② §4.3/§4.4 游标行重放规则——message 行可在断线期间被更新或定稿,重放必须含游标行本身; ③ §4.4 Feed 编排补两条——游标 run 单独补齐、live run 兜底;原文的三条规则产生不了用例 3/5/11(修订⑨ 前编号 3/6/14)演出来的回放; ④ §5.3 Reconcile 租约化(owner + lease_until + 条件更新 fencing)——「启动即判死所有 running」在多副本下会误杀其他副本正在执行的 run; ⑤ §5.9 finishAtomic——终局帧 + status + run_terminal 同事务,关掉收尾崩溃的永久缺帧窗口(Reconcile 判死路径同); ⑥ §5.9 会话行锁 + §5.14 外键——Delete 与投递交错不再可能留孤儿行; ⑦ §5.9/§9.3 幂等措辞收窄到 inbox 存活期。 ⑧ §1.3 会话懒创建——POST /api/session 删除;不带 sessionId 的投递在 Enqueue 事务内含铸会话 (202 回带 id,空会话不存在)。首消息重试幂等缺口照实登记(§11 问题 18)。 ⑨ inbox 删除,投递语义反转(用户裁定,2026-10-02)——inbox 表与整套队列机制不建; 会话忙时 POST /api/message 返回 409 session_busy,没发出去的消息由客户端本地排队, run_terminal 后自动补投。合并语义随之删除(一轮 run 只消费一条 message)。 红利:Enqueue 与建 run 合成一笔事务(闸检查 + message_queued 帧 + 档案行 + start 帧 + run_started 帧同生同灭),不变量 8、§11 问题 2、搁浅竞态整体消失。 代价照实登记在 §9.5。

⑩ 跨客户端状态同步(账号级)显式后置、不删除;当前方案同步撤出跨端设计(用户裁定,2026-10-02)—— 当前不做跨 client 同步;在 §10 与 §11 问题 15 登记为「后置安排 + 届时讨论定方案」。 定位记录:其载体(WS 账号级多路复用)是跨客户端、跨会话的状态同步通道 (A 建会话、B 的列表冒出来),不只是省连接;但它连带依赖账号体系、会话列表枚举、 账号级事件源三块前置,现在都不存在——讨论素材登记在 §11 问题 15。 当前方案内的跨端设计一并撤出:凡为跨端同步而设、单客户端用不到的组件与保证 不保留「顺便兼容」——clientId 整体删除(原 §6.4)、§4.1 与 §8 的多端场景与跨端断言、 7.9 用例 4。它们不是被否定,是随跨端同步一并后置:届时作为讨论输入(§11 问题 15), 方案落地时一并设计回来。会话级流仍可被多端订阅是存储结构的物理事实—— 当前方案不阻止,但不为它做设计保证、不写验收。

0. v5 相对 v4 的四个改动

v4 的存储划分(减去 inbox)、调度模型、审批设计大部分保留;投递语义反转(改动 5)。v5 改五处, 每一处的动机都是「拆除一个自己承认是临时形态/拓扑后果的机制」:

# 改动 拆除的东西 动机
1 流式正文从生成起就落库:run_log 允许「生成中的 message 行」原位 UPDATE,定稿是同一行的最后一次 UPDATE Partial 预留号、AppendSealed、ErrSealConflict、dropPartialTail、游标不前移、防忙等——整套机制 v4 §12.3 自己承认这是「建模产物」;v4 §9.2 承认它敞开一个不可恢复的正文丢失窗口。v5 不把它当阶段二再拆,现在就不建
2 一条 SSE 承载一个会话的全部帧:会话级通知与 run 级内容共用一条连接,帧上用不同字段名区分命名空间(seq / run+rseq) GET /api/chat/stream 端点、「先拿 runID 再订阅」的竞态(v4 失效场景 E)、前端「挂第二条流」的步骤、每会话 2 条连接的浏览器坑位占用 run 级流需要预先知道 runID 是拓扑选择的后果,不是问题的性质。不变量 9 的事务保证保留,但它要治的传输层竞态不再发生
3 Enqueue 与建 run 合一事务:message_queued 帧 + 闸检查 + run 档案行 + start 帧 + run_started 帧同事务 inbox 表、beginRunAtomic/trySchedule 调度回路、放闸与查队列的原子性要求(原不变量 8)、搁浅竞态、§11 问题 2 inbox 没了之后,「入队但不调度」的状态不存在,Enqueue 要么整笔成功(消息开跑)要么整笔回滚(409 session_busy)。临界区从三处减到两处
4 订阅不再依赖内存事件缓冲:Subscription.Next 直接读库,内存里只有「醒来」信号(notify 通道 + 低频轮询兜底) runBuffer.events / sessionBuffer.events 的无界内存增长;多副本审计里仅剩的那处进程内断点(v4 §13.5 第三行) 改动 1 让生成中的文本也在库里,于是「读库」天然等价于「读内存缓冲」,缓冲失去存在理由。任何副本都能服务任何订阅
5 inbox 删除,队列职责移交客户端:会话忙时投递返回 409 session_busy,没发出去的消息客户端本地排队,run_terminal 后自动补投 inbox 表(重复计数,归改动 3)、Cancel/ClearInbox 端点、撤回/清空两条竞态、maxQueueDepth 背压、合并语义(messageIds 多 id + mergedText)、重启续答的 inbox 分支 用户裁定(2026-10-02):队列逻辑服务端实现一次 vs 每个客户端各自实现,换砍掉一张表、两个端点、三条竞态测试和整个调度回路。代价照实登记在 §9.5

连带的命名修正:Engine 不再自称「无状态」。它不持有任何 per-session 常驻对象, 但持有进程内运行时状态(取消句柄表、订阅唤醒表、审批等待者)。这些全部是加速路径, 真源都在库里——多副本下失去它们只变慢,不变错(§13.5)。

没改的:三真源划分(run_log / run_archive / session_log)、session 登记表与准入检查、 闸是 DB 部分唯一索引、finishAtomic 单事务、审批决策行落库、Archive 与压缩补偿事务。 改了的:投递语义(忙时 409,客户端排队,改动 5)与合并语义(删除)—— v4 §7.9 用例中凡涉及收件箱的(排队、撤回、清空、合并开跑)语义都改了,其余不变。


1. 存储:三真源 + 一张登记表

四份持久状态(inbox 已删,修订⑨)。它们的写规则、读者、生命周期都不同,不是冗余,是四种不同的东西。

run_log run_archive session_log session
角色 真源:run 级事实 真源:模型视图 真源:会话级事实 登记表:会话身份
粒度 run run 会话 会话
回答的问题 这场 run 发生过什么 下一轮该给模型看什么 这个会话发生过什么 这个会话存不存在、何时建的
写规则 追加;一类行允许原位更新(§1.1) 可改写(压缩是破坏性覆盖) 只追加,永不改 只插入 / 只删除,不改
读者 人 / UI / 回放 / 对账 LLM UI / 回放对账 所有写操作的准入检查
seq 命名空间 per-run — per-session —
生命 永久 永久 永久 永久(显式删除为止)

「还有哪些话没被回答」这个问题不再由服务端回答——没发出去的消息在客户端本地队列里 (修订⑨,§9.5)。服务端的世界里,一条 message 被接受的那一刻就已经开跑。

1.1 run_log 的更新特例:生成中的 message 行

v4 的 run_log 是「只追加,永不改」,代价是流式正文不敢落库(落了就没法改), 只能在内存里玩预留号,流结束时一次性 seal——整套 Partial 机制由此展开, 并留下「进程崩在 seal 之前,正文彻底丢失」的窗口。

v5 把写规则改成:追加为主;唯一例外是「生成中的 message 行」可以被原位 UPDATE, 直到定稿。 具体规则:

约束(应用层强制,建表注释里也写明):final=0 只允许出现在 kind='message' 的行上; 只有 final=0 的行可以被 UPDATE;UPDATE 只许改正文、updated、final,不许改 seq。

这个例外买到的东西:

  1. v4 §9.2 的窗口现在关闭,不是等阶段二——崩在输出中途,已落库的正文一个字不少, Reconcile 把遗留的 final=0 行定稿为 interrupted(§5.3),读者看到的是「写到哪儿是哪儿」;
  2. 重连的读者立刻看到当前已生成的文本(读库即得),而不是像 v4 那样在 seal 之前什么都看不到;
  3. 订阅不再需要内存事件缓冲(§5.2),多副本下任何副本都能服务任何订阅(§13.5);
  4. ErrSealConflict、dropPartialTail、预留号、防忙等——整套机制不存在了。

付出的代价(照实登记,§9 还会算一次):run_log 的写规则不再是纯粹的「只追加」。 这是一个有界的例外(一类行、有限字段、单次生命周期内),换来上面四条。判断依据是: 追加式纯净的价值在于「写下的历史不可篡改」,而生成中的行还不是历史——它是进行中的现在, 对它 UPDATE 不篡改任何已定稿的事实。

1.2 为什么 inbox 与 session_log 是两张表 —— 本节作废(修订⑨)

inbox 已删:「还有哪些话没被回答」不再由服务端存储回答,没发出去的消息在客户端本地队列。 原论证(事实表与状态表写规则相反,必须分两张)随之失去对象;其精神保留在 session_log(事实,只追加)与 session(登记,只插入/只删除)的划分里。

消息被接受后,「m_1 曾投递过」这个事实不会丢:它在 session_log 里有 message_queued 帧, 在 run_started 帧里也有一份。断线重连的客户端能完整重建时间线。

1.3 为什么需要 session 登记表

会话身份由服务端铸造,不由客户端生成——铸造点是首条消息: POST /api/session 不存在;POST /api/message 不带 sessionId 时, session 行在 Enqueue 事务里与 message_queued 帧、run 档案行同时出生(§5.9)。 空会话不存在:没有消息就没有 session 行,「新对话」是纯客户端动作(清本地 id)。 三条理由(懒创建下仍然全部成立):

  1. session_log 的重放起点不变,且更硬了。 「从 0 开始重放」的起点是登记表里那一行; 懒创建下每个登记的会话第一帧必是 message_queued(seq 从 1 起)——创建事实与第一条事实 同生同死,「刚建(空日志)」与「查无此会话」的歧义被结构性消除, 也无需为「创建」单开一种除创建者自己重放以外没有消费者的帧类型。
  2. 目标是多副本部署(§13.5)。会话身份要在副本之间可路由、可归属; 配额、回收、会话列表、账号级订阅全都以登记行为前提。不变。
  3. 重启续答(§7.8)依赖它(修订⑨删除:inbox 没了,重启后没有待办队列要捞; 重启恢复只剩 run 租约判定一条路,§7.8)。登记表本身的价值由第 1、2 条独立支撑,不变。

准入规则(不变):任何带 sessionId 的写操作,先查登记表;未登记一律 404,不隐式创建。 唯一合法的创建入口是「不带 sessionId 的投递」——首条消息。

已知缺口,照实登记:首条消息超时重发可能铸两个会话、跑两条同样的消息—— 首条消息发生时客户端手里还没有 sessionId,服务端没有任何已建行可撞 (修订⑨:inbox 主键没了,连会话内幂等键都没了;重发仲裁只剩客户端约束 4)。 去重闸(客户端一次性 requestId + registry 唯一索引,重发带同一 nonce 命中已建行)是后置补强,登记在 §11 问题 18。

messageId 由客户端生成(clientId 随修订⑩ 删除——它是纯跨端同步组件)。会话 id 是资源身份(服务端必须存在这个对象); messageId 是绑草稿的回放对齐键,客户端必须在发出请求之前就知道它, 超时重发同一句用同一个 id(修订⑨:不再有 inbox 主键仲裁,它只对齐回放,约束 4)。 它不承担可读性:排序一律走 seq / rseq,messageId 从不参与排序。

1.4 推论:哪些东西不能互相重建

三张辅助表不算「持久状态」:session_seq(会话级 seq 计数器,§5.9)、 compact_rag(被压缩换掉的原文,只写只检索,§5.4)、approval(审批决策行,§5.11—— 决策事实在 run_log 的 approval_result 帧里也有,行只是让它成为可查询的当前态)。 建表汇总(§5.14):7 张表 = 4 份持久状态 + 3 张辅助表(inbox 已删,修订⑨)。


2. 不变量

九条(修订⑨:第 7 条语义反转、第 8 条作废——编号不动,作废留档)。每条都是承重的: 违反它会得到一个具体的、可复现的错误行为。

# 不变量
1 会话是服务端登记的资源。 未登记的 sessionId 一律 404,不隐式创建(§1.3);会话由首条消息在投递事务内登记——空会话不存在。
2 run 的命不属于任何连接。 runCtx 是进程 ctx 的子 ctx;浏览器关掉、刷新、断网,run 照跑、帧照落库。只有 Stop 与 Delete 能取消它。
3 库操作一律用进程 ctx,绝不用请求 ctx。
4 先落库,再推浏览器,再回 2xx。 v5 起这条对流式正文的每一次 flush 同样成立——UpdateMessage 提交后才唤醒订阅者,而订阅者本来就只读库(§5.2),「推了库里没有的东西」在结构上不可能。
5 续传坐标是一对游标:(sessionSeq) 管会话级事实,(runId, rseq) 管 run 级内容。两个命名空间各自单调,互不换算,共用一条流(§4)。
6 终局唯一。 Finish 在一个事务里写终局帧 + 改 status + 会话级 run_terminal(finishAtomic,§5.9),之后 Append / BeginMessage 直接拒绝。
7 忙时投递诚实拒绝(修订⑨,语义反转)。 会话有 running run 时 POST /api/message 返回 409 session_busy,什么都不写;没发出去的消息由客户端本地排队,run_terminal 后自动补投。Enqueue 只可能因「忙」(409)或存储故障(500)失败,不存在 422。
8 放闸与调度必须原子。 作废(修订⑨):原治「收尾放闸与查 inbox 之间消息搁浅」的竞态。inbox 删除后调度回路不存在——Enqueue 在一笔事务里完成闸检查 + 建 run,要么整笔成功要么整体回滚,没有「入队后等调度」的中间态,竞态失去发生的位置。留档见 §2.1。
9 run 的档案行、start 帧、run_started 帧在同一个事务里写入。 runID 在事务提交前对任何读者不可见。

2.1 不变量 8 为什么是硬要求 —— 作废留档(修订⑨)

原论证:放闸和查收件箱之间有窗口,落在窗口里的消息会永久搁浅——入队时看到闸 occupied (没触发调度),收尾查收件箱又发生在它入队之前。这是「signal lost between unlock and wait」竞态, 只能靠原子性解决(原 beginRunAtomic)。

作废理由:这个竞态的两端都被拆了。收件箱没了(消息不会在库里等待调度); 「闸检查 + 建 run」移进 Enqueue 的同一笔事务(修订⑨),事务提交即消息开跑, 不存在「signal 发出后还有人要等」的双方。原子的临界区从三处减到两处(Enqueue、finishAtomic)。

2.2 不变量 9 在 v5 里的位置变了

v4 里不变量 9 要治一个传输层竞态:客户端从某处拿到 runID 去订阅 run 级流, 而档案行还没提交 → 404(v4 失效场景 E)。v5 没有这个端点了——run 内容走会话流, run_started 与内容帧在同一条有序流上,扇入器保证 run_started 先于该 run 的任何内容帧发出 (§4.4),「拿到 ID 却订阅不到」在结构上不发生。

不变量 9 保留,但它守的不再是订阅竞态,而是快照一致性: GET /api/session(Snapshot)与 GET /api/session/history 读到的世界, 必须不存在「liveRunId 有值但 run 无档案行」或「run_started 已入日志但 run 查不到」的中间态。 同事务写入依然是最便宜的保证方式。

2.3 关于「POST 返回流」的澄清(沿用 v4)

不是「因为不返回流所以不用判状态」,而是「因为没有状态冲突可判,所以不必返回流」。 返回流本身无罪。有罪的是「流的寿命绑死在一个 runID 上」与「POST 的含义是开 run 而非投递」。 v5 把这两点都改掉了,且比 v4 更彻底:连 run 级订阅端点都没有了。


3. 组件关系

 浏览器 / APP / IM / cron
    │
    │  ① POST /api/message ──────────▶ 投递(无 sessionId 时事务内含铸会话,202 回带 id)
    │  ② GET  /api/session/stream ───▶ 唯一的一条流:会话级通知 + run 级内容(常驻)
    ▼
 ┌──────────────────────────────────────────────┐
 │  internal/webui/  (只有 transport,无业务)    │
 │   ├─ server.go          装配 + 路由           │
 │   ├─ middleware.go      中间件链(含错误映射) │
 │   ├─ handler_session.go 快照 / 删除              │
 │   ├─ handler_msg.go     投递(忙时 409)        │
 │   ├─ handler_stream.go  统一 SSE              │
 │   ├─ dto.go             请求/响应 DTO         │
 │   └─ sse.go             Stream()(帧写出 + id 游标 + 心跳) │
 └──────────────────┬───────────────────────────┘
                    │ 函数调用(webui → run,反向不依赖)
                    ▼
 ┌──────────────────────────────────────────────────────────┐
 │  internal/run/                                           │
 │                                                          │
 │   Engine(单例,无 per-session 常驻对象,方法显式收 sessionID)│
 │     ├── Registry     会话登记表(准入检查)                │
 │     ├── SessionLog   会话级事实真源(+ Since/Subscribe)   │
 │     ├── RunLog       run 级事实真源(含生成中行的原位更新) │
 │     ├── Archive      模型视图真源(共享实例,按会话键控缓存)│
 │     ├── Approvals    审批:决策行落库 + 等待/通知          │
 │     └── Feed         扇入器:把 SessionLog 与 RunLog       │
 │                      合成一条有序的统一订阅(§4.4)        │
 │                                                          │
 │   没有独立调度器(修订⑨):闸检查 + 建 run 就在 Enqueue     │
 │   的那一笔事务里,投出去 = 开跑;run 期间的临时状态在        │
 │   runState 里,由 drive goroutine 持有、随 run 结束消亡      │
 │                                                          │
 │   领域类型:Event / StoredEvent / Subscription             │
 │             SessionEvent / SessionSubscription             │
 │             StreamFrame / Stream(统一流的帧与订阅)        │
 │             Approval / Checkpoint                          │
 └──────────────────┬───────────────────────────────────────┘
                    │ eino adk.Agent / adk.Runner(出站,不经 webui)
                    ▼
                   LLM

谁持有谁:

命名修正(v5 起):Engine 不叫「无状态」。准确表述是: Engine 不持有任何 per-session 常驻对象;它持有的进程内状态全部是加速路径,真源都在库里。 进程内状态清单(每一项的多副本行为见 §13.5):

进程内状态 真源 失去它的后果
Engine.runCtxs(runID → cancel) run_archive.stop_requested 列 Stop 从「即时」降为「drive 下个轮询点收敛」
RunLog / SessionLog 的唤醒表 表本身 订阅者从「被唤醒」降为「轮询间隔(≤1s)才发现」
Approvals.waiters approval 行 同上
Archive 的会话缓存 run_archive 冷路径重读库;跨副本失效是已登记的洞(§5.4)

依赖方向:webui → run → eino / compact。run 不依赖 webui,也不依赖 guard。

Engine 的对外方法(全部显式收 sessionID,修订⑨ 后 5 个): Enqueue / Stop / Approve / Snapshot / Delete。 session 行只由 Engine.Enqueue 在首条消息事务内铸造(Registry.CreateInTx);transport 无开会话端点。


4. 一条流:统一订阅通道

4.1 从「谁需要知道什么」出发(结论与 v4 相同)

# 场景 谁需要知道 需要知道什么
1 发了一句,等模型逐字回答 本端 这一场的正文、工具调用、看板
2 刷新了页面,run 还在跑 本端 从断点续上这场 run
3 消息投出,等「已接收」确认来驱动气泡(§6.3 约束 2:服务端回显) 本端 「m_1 被接受了」(message_queued)
4 r_17 跑完,本地队列的 m_2 自动补投,开了 r_18 本端 「r_17 落幕」(补投触发信号)、「r_18 开始,runID 是这个」
6 A 在 APP 上开了新会话,网页列表要冒新条目 网页 「多了一个会话」(账号级跨端同步,后置安排、不删除,届时讨论定方案,§11 问题 15 / 修订⑩)

(原 3/4/5 行的跨端版本——B 同步看到 A 的投递、A 知道 B 删了会话——不再是当前方案的 设计保证:跨端同步整体后置。编号留空是有意的,见下行说明。)

修订⑩ 的边界:会话级流可被多端订阅是存储结构的物理事实,当前方案不阻止; 但不为跨端同步做设计保证、不写验收——多端行为届时随方案讨论一并定义(§11 问题 15)。

结论不变:逻辑上需要两个通道——会话级(发生了什么)与 run 级(这一场的具体内容)。 v4 据此开了两条物理连接。v4 错把逻辑划分当成了物理划分的理由。

4.2 逻辑两个通道 ≠ 物理两条连接

v4 的两条 SSE 带来了四笔账,每一笔都追溯到「run 级流需要预先知道 runID」这个拓扑:

  1. 订阅竞态:runID 可见早于可订阅 → 404(v4 失效场景 E),靠不变量 9 治;
  2. 前端编排:run_started 到达 → 新挂一条流 → 终局帧到达 → 关流。每个客户端一套挂载状态机;
  3. 续传起点不对称:run 级从 0、会话级从 lastSeq,两套规则,v4 用了两处篇幅解释为什么不是 bug;
  4. 连接坑位:每会话 2 条 SSE,浏览器 HTTP/1.1 同 host 上限 6,多标签页直接撞墙(v4 §9.1)。

而「同一时刻最多一场 run 在跑」是闸保证的——「摄像头画面」任何时候只有一路, 门磁和摄像头共走一条线没有带宽问题。于是 v5:

③ GET /api/session/stream?id=&from=   ← 唯一的一条流,常驻
     承载:会话级帧(message_queued / run_started / run_terminal)
           + run 级帧(start / message / tool_call / tool_result / board / approval / … / 终局)
           + heartbeat

竞态在结构上消失:扇入器(§4.4)保证 run_started(r) 先于 r 的任何内容帧发出—— 它们在同一条有序流上,客户端知道 runID 的时刻不晚于第一帧内容到达的时刻,也不需要拿 ID 去「订阅」什么。 (这条保证管新 run;追赶阶段回放旧 run 的内容帧时,runID 的来历是 Last-Event-ID 或 Snapshot, 见 §4.4 规则 1/3 的注。)

4.3 线格式与游标

两个 seq 命名空间共用一条流,字段名必须可区分:会话级帧用 seq,run 级帧用 run + rseq。

id: 2::
data: {"seq":2,"ts":"T0","kind":"run_started","runId":"r_17","messageId":"m_1","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","agent":"tako","role":"assistant","text":"好的,我来读一下 doc/19。","final":true}

要点:

4.4 Feed:扇入器

统一流背后是两个数据源(SessionLog、RunLog)。把它们合成一条有序流是服务端的职责, 新组件 Feed(internal/run/feed.go):

// StreamFrame 是统一流上的一帧:两类二选一。
type StreamFrame struct {
    Session *StoredSessionEvent // 会话级帧(seq 命名空间)
    Run     *StoredEvent        // run 级帧(run+rseq 命名空间)
}

type Stream interface {
    Next(ctx context.Context) (StreamFrame, bool)
    Close()
}

type Feed interface {
    // Attach 挂上会话的统一流。
    // from:会话级游标(seq > from 的帧要补齐)。
    // lastRunID / runFrom:断线前正在看的 run 及其 rseq 游标(来自 Last-Event-ID——
    //   它优先于显式参数,§4.3);该 run 的内容按规则 1 补齐,不论它是否已结束;
    //   空串表示「我没有在看的 run」(整页刷新——live run 由规则 3 兜底)。
    // replay:补帧策略——all(默认,断开期间开始过的 run 内容全补)/ live(只补当前 live run)/ none(只补会话级帧)。
    Attach(sessionID string, from int64, lastRunID string, runFrom int64, replay ReplayMode) (Stream, error)
}

编排规则(Feed 的全部复杂度在这里,四条——前三条是追赶,第四条是实时):

  1. 先补游标 run:lastRunID 非空 → 同步回放该 run 已落库的内容(rseq > runFrom, 游标行按 §4.3 的规则随附——它是 message 行则重发)——即使它此刻已结束 (已结束则回放含终局帧)。它的 run_started 在 from 之前,规则 2 的遍历永远不会遇到它; 不单独补这一步,用例 5/11 里「断线期间的剩余内容」就无声丢失。 回放完若它仍是 live,挂好它的订阅,作为规则 4 的 run 订阅。
  2. 追赶会话帧:取 sessionLog.Since(from),按序遍历:普通会话帧直接发; 遇到 run_started(r) → 发出它,然后同步回放 r 已落库的内容帧 (从 0——能在这一步遇到 r 的 run_started,说明客户端没见过 r 的任何帧; r 已结束则回放含终局帧);遇到 run_terminal(r) → 若 r 的内容刚回放完(规则 1 或本规则)则直接发。
  3. live run 兜底:切实时之前查 LiveRunID:存在且本连接还没回放过它的内容 (典型:整页刷新,lastRunID 为空、from=lastSeq,它的 run_started 在 from 之前) → 从 0 回放它已落库的内容(含生成中行的当前文本),挂好订阅。这是 §7.7 刷新场景的支点。
  4. 实时阶段与唯一的排序规则:同时持有会话订阅与当前 run 的订阅,先到先发。 新的 run_started(r) 到达 → 挂上 r 的订阅(从 0 开始,新 run 的内容本来就没发过)。 收到 run_terminal(r) 时,压到 r 的订阅排空(见到终局帧)之后再发—— run_terminal 与 r 的终局帧在同一个 finishAtomic 事务里提交(§5.9), r 的内容此刻必已齐全,排空必然完成——不会死等。

第四条是 Feed 里唯一需要小心的地方,也是「run_terminal 永远在内容之后」这个客户端假设的唯一支点。 规则 1/3 发出的内容帧,其 run_started 客户端在本连接上未必(重)收——runID 的来历是 Last-Event-ID 或 Snapshot(§6.1),前端按 runId 键控建 run 视图,不依赖本连接先见 run_started; 「run_started 先于内容」管的是新 run(规则 2 的回放与规则 4 的实时)。 Feed 约 150 行,其中一半是追赶阶段的游标去重(追赶期间新到的帧按游标跳过)。

replay 参数为什么存在:断开很久的客户端(比如一周,50 场 run)全量补内容太重。 UI 做了虚拟滚动的话,用 replay=live 或 none,历史内容走 GET /api/session/history 按需拉。 默认 all 让 curl 验收与简单客户端零分支。


5. 组件详细设计

5.1 Event(run 级领域帧)

文件:internal/run/event.go

v5 的 Event 上没有 Partial 字段。 「生成中 / 定稿」是存储行的属性(final 列), 不是事件的属性——事件描述「要写什么」,写到哪个阶段由 RunLog 的方法区分 (BeginMessage / UpdateMessage / FinalizeMessage,§5.3)。

type EventKind string

// 十一种帧,按「谁写」分两组:
// Classify 只可能产出前四种,后七种由 RunLog / drive 的 ask 闭包直接构造。
const (
    // ── Classify 产出(来自模型的一条 *schema.Message)──
    EventMessage    EventKind = "message"
    EventToolCall   EventKind = "tool_call"
    EventToolResult EventKind = "tool_result"
    EventBoard      EventKind = "board"

    // ── 由存储层 / 引擎直接写(不经过 Classify)──
    EventStart           EventKind = "start"
    EventApproval        EventKind = "approval"
    EventApprovalResult  EventKind = "approval_result"
    EventCompact         EventKind = "compact"
    EventComplete        EventKind = "complete"
    EventError           EventKind = "error"
    EventStop            EventKind = "stop"
)

func (k EventKind) IsTerminal() bool {
    return k == EventComplete || k == EventError || k == EventStop
}

// MsgOutcome 是一条 message 行定稿时的结局。
type MsgOutcome string
const (
    MsgOK       MsgOutcome = ""          // 正常定稿
    MsgDrop     MsgOutcome = "drop"      // 模型流出失败:行保留,UI 渲染「输出中断」
    MsgDiscard  MsgOutcome = "discard"   // 半截被最终结果取代(如变成工具调用):行保留,UI 隐藏
)

type Approval struct {
    ID       string
    Tool     string
    Args     string
    Message  string
    Decision string // 只在 approval_result 帧上非空
}

type ToolCall struct {
    Name string
    Args string
}

type Event struct {
    Kind      EventKind
    Agent     string
    Role      schema.RoleType
    Text      string
    ToolName  string
    ToolCalls []ToolCall
    Approval  *Approval // 仅 approval / approval_result 两帧非 nil
}

// StoredEvent 是已被 RunLog 分配身份的帧。
type StoredEvent struct {
    Run     string
    Seq     int64     // 库内序号(线上叫 rseq)
    Ts      int64     // 创建时刻,unix 毫秒
    Updated int64     // 最近一次更新时刻;final 行恒等于 Ts
    Final   bool      // false = 生成中(仅 kind=message 允许)
    Outcome MsgOutcome // 定稿结局,Final=false 时为空
    Event
}

对比 v4 删掉的字段:Partial(→ Final 列 + 三个写方法)、Drop / Discard (→ 定稿时的 Outcome,行保留不留空洞,连 v4 的「作废预留号」动作都省了)。

纯函数 Classify 不变:

func Classify(agentName string, mv *adk.MessageVariant, msg *schema.Message) (Event, bool)

5.2 Subscription(读库式订阅)

文件:internal/run/event.go

v4 的 Subscription.Next 是全篇第二难写的东西:内存缓冲 + Partial 同号重推 + 防忙等。 v5 里生成中的行就在库里,于是订阅退化成「读库 + 等信号」:

type Subscription interface {
    // Next 阻塞到下一帧可用。
    // 冷启动时先把库里符合条件的行读完,再切实时。
    // run 不存在 → Subscribe 时已返回 ErrRunNotFound;ctx 取消 / 流已关 / run 终局且读尽 → false。
    Next(ctx context.Context) (StoredEvent, bool)
    Close()
}

订阅者状态只有三个数:lastFinal(已发出的最大定稿 seq)、genSeq + genUpdated (正在跟踪的生成中行及其上次发出的 updated;0 表示没有)。

func (s *subscription) Next(ctx) (StoredEvent, bool) {
    for {
        rows := s.log.sinceRun(s.runID, s.lastFinal)   // SELECT … WHERE run_id=? AND seq>? ORDER BY seq
        for _, row := range rows {
            if row.Final {
                emit(row)                  // 含「生成中行定稿」:genSeq 清零
                s.lastFinal, s.genSeq = row.Seq, 0
                return row, true
            }
            // 生成中行:updated 变过才重发(同 rseq 原位更新),游标不前移
            if row.Updated > s.genUpdated {
                s.genSeq, s.genUpdated = row.Seq, row.Updated
                return row, true
            }
        }
        if s.log.runFinished(s.runID) && s.genSeq == 0 { return StoredEvent{}, false } // 流完即止
        wait(s.log.notify(s.runID), 500ms tick, ctx.Done())  // 唤醒是加速,轮询是正确性兜底
    }
}

对比 v4 的 Next:没有内存缓冲、没有 gen 计数、没有 goto wait、没有 Partial 分支。 正确性不依赖任何进程内状态——唤醒通道丢了、副本换了,下一轮轮询照样读到。

约束:一场 run 同一时刻最多一行 final=0。 由 drive 的顺序写保证 (定稿一条 message 才写下一帧),单写者天然满足。

双通道等待是普遍原则,不是特例:唤醒通道(本进程,快)+ 轮询(≤1s,跨副本与丢信号兜底), 与 Approvals.Wait(§5.11)是同一副药。多副本下别的副本写的帧, 本副本的订阅者最坏 1 秒后读到——v4 §13.5 的第三处断点就此消除。

内存占用:订阅的内存是 O(活跃订阅者),不再是 O(历史帧数)。 长会话、多订阅者都不会让缓冲无界增长(v4 的一个未登记的洞,v5 顺手关上)。

5.3 RunLog(run 级事实真源)

文件:internal/run/runlog.go(接口)+ internal/run/sqlite/runlog.go(实现)

type RunLog interface {
    // ── 写(一律用进程 ctx,不变量 3)──

    // ListExpiredRunning 列出「status='running' 且租约已过期」的 run——多副本下
    // 它们只属于死掉的执行者;租约未过期的 running run 是别的副本正在健康执行的,绝不动。
    // Engine.Reconcile 对每场这样的 run 开一个事务:FailInTx + sessionLog.AppendInTx(run_terminal)
    // ——同事务提交,不留「run 已终局但会话级缺帧」的窗口(§7.8)。启动时与周期都调它,幂等。
    ListExpiredRunning(ctx context.Context) ([]RunningRun, error)

    // FailInTx 在调用方事务里把一场 run 判死:条件 UPDATE(WHERE status='running'——
    // 撞了说明已被判过,跳过,这是周期与多副本并发 Reconcile 的幂等点);
    // 补一帧 kind:"error" 终局帧(没有它,重连的客户端永远等不到终局);
    // ★ 并把该 run 所有 final=0 的行定稿为 outcome="interrupted"——
    //   生成中的正文是真实数据,崩溃后它必须以定稿形态留在日志里。
    FailInTx(ctx context.Context, tx *sql.Tx, runID string) (FailedRun, error)

    // BeginRunInTx 在调用方的事务里开一轮 run(调用方是 Engine.Enqueue,§5.9):
    // 插入 run_archive 行(owner=本副本、lease_until=now+租约TTL,
    // 见本节「执行租约与 fencing」)+ 写 rseq=1 的 start 帧。
    // 撞 one_live_run_per_session 唯一索引 = 闸忙 → 调用方回滚整个事务 → 409 session_busy。
    BeginRunInTx(ctx context.Context, tx *sql.Tx, runID, sessionID, userMessage, agentName string) (StoredEvent, error)

    // Append 追加一帧非 message 帧(tool_call / tool_result / board / approval / …)。
    // final=1,seq = 库内 max+1。run 已非 running → 拒绝(不变量 6)。
    Append(ctx context.Context, runID string, ev Event) (StoredEvent, error)

    // BeginMessage 开始一条流式正文:INSERT kind='message', final=0。
    // 返回的 seq 是真实的、已提交的——没有预留号。
    BeginMessage(ctx context.Context, runID string, ev Event) (StoredEvent, error)

    // UpdateMessage 原位更新生成中行的正文(与 updated 时间戳)。
    // 调用方(drive)负责节流:100ms 或累计 2KB 一次,§5.9。
    // 行不存在或已定稿 → 错误(说明 drive 的状态与库分叉,按 persistErr 处理)。
    UpdateMessage(ctx context.Context, runID string, seq int64, text string) error

    // FinalizeMessage 定稿:UPDATE final=1 + outcome。生成中行定稿;
    // outcome=drop/discard 时行保留(不留 seq 空洞),UI 据此渲染或隐藏。
    FinalizeMessage(ctx context.Context, runID string, seq int64, text string, outcome MsgOutcome) error

    // FinishInTx 在调用方的事务里写终局帧 + 改 run_archive 状态(不变量 6)。
    // 调用方是 Engine.finishAtomic:本写与 sessionLog.AppendInTx(run_terminal) 同事务提交(§5.9)——
    // 终局唯一且终局不缺帧:要么整场 run 仍在 running(崩溃后由 Reconcile 收拾),
    // 要么终局帧、status、run_terminal 三者同生同灭。
    // kind 只接受 "complete" / "error" / "stop"。只有 complete 写 producedJSON。
    // patch 非 nil 时同事务改 user_message 和清被换掉的行。
    // status 改写是条件 UPDATE(WHERE status='running'):僵尸执行者的迟到 Finish 影响 0 行(fencing)。
    FinishInTx(ctx context.Context, tx *sql.Tx, runID, kind, text string, producedJSON []byte, patch *ArchivePatch) (StoredEvent, error)

    // ── 读 ──

    Subscribe(runID string, from int64) (Subscription, error)
    Since(ctx context.Context, runID string, from int64, limit int) ([]StoredEvent, error)

    // LiveRunID 查会话当前 running 的 run。在 Enqueue 的事务里用(§5.9)。
    LiveRunID(ctx context.Context, tx *sql.Tx, sessionID string) (string, error)

    // HistoryPage 返回会话里已结束的 run(档案 + 事件),按 created_at 降序分页。
    HistoryPage(ctx context.Context, sessionID, cursor string, limit int) (HistoryPage, error)

    Close() error
}

执行租约与 fencing(多副本恢复判定):run_archive 带 owner(执行者副本 id, 进程启动时铸造 n_<ULID>,只用于租约归属,不参与路由)与 lease_until 两列。 drive 在 run 期间周期续租(条件 UPDATE:WHERE run_id=? AND status='running')—— 续租是独立 ticker,不搭 flush 的车:审批挂起可能几分钟没有任何帧写出,租约照样得活着。 起步参数:TTL 15s、每 5s 续一次、周期 Reconcile 每 15s 扫一次(§11 问题 17)。

fencing 不需要单独一列:run 级的所有写(Append / BeginMessage / UpdateMessage / FinalizeMessage / FinishInTx)本来就「run 非 running 即拒绝」(不变量 6),落实为以 status='running' 为条件的条件更新后,被 Reconcile 判死的 run,其僵尸执行者的迟到写入 全部被拒;迟到的 Finish 撞条件 UPDATE 影响 0 行。判死后闸位即释——客户端的补投 开新 run 合法占闸,这是正确行为,不是双跑。进程被 SIGSTOP / 长 GC 暂停超过 TTL 再复活, 等价于僵尸,同一条路径收敛。 单副本语义不变:进程死了无人能续租,重启耗时远超 TTL,启动 Reconcile 看到的就是「租约已过期」。

没有 AppendSealed、没有 ErrSealConflict、没有补发接口。 v4 里「补发」的三条否决理由(前提不成立 / 客户端不存内容 / 窗口将消失)在 v5 里全部落地: 窗口已经消失,连「将来会消失」都不用等。

内部结构(实现细节):

type runLog struct {
    mu     sync.Mutex
    db     *sql.DB
    notify map[string]*wakeSet // runID → 唤醒通道集。只承载信号,不承载内容
}

每个写方法在事务提交后 bump 对应的 wakeSet。Subscribe 不再 readAll 建缓冲—— 直接返回一个 §5.2 的读库订阅。

5.4 Archive(模型视图真源)

文件:internal/run/archive.go(接口)+ internal/run/sqlite/archive.go(实现)

与 v4 完全相同,此处只列契约要点:

已登记的洞(不变):跨副本的缓存失效。单副本下闸的串行化保证正确; 多副本下副本 B 的旧缓存看不到副本 A 跑完的新轮次。修法(失效广播或每场 run 冷装) 随多副本部署做,§11 问题 12。

5.5 SessionEvent / SessionSubscription(会话级领域类型)

文件:internal/run/session_event.go

修订⑨ 后三类帧(message_cancelled 随 Cancel 端点一起删除):

const (
    SessMessageQueued SessionEventKind = "message_queued"
    SessRunStarted    SessionEventKind = "run_started"
    SessRunTerminal   SessionEventKind = "run_terminal"
)

SessionEvent 仍是并集结构体(MessageID / Text;RunID / Resumed; TerminalKind)。修订⑩:ClientID 字段删除(原 clientId 是纯跨端同步组件,随跨端同步一并后置,§11 问题 15)。护栏:帧种类涨到 6 种以上就拆成每类一个结构体—— 目前是 3 种,并集的代价(字段可空性靠约定)小于收益(一套存储一套订阅)。

SessionSubscription 与 §5.2 同构,更简单:没有生成中行,游标永远单调前移。 同样读库 + 唤醒 + 轮询兜底。会话级流永不自然结束(会话没有终局),只有 ctx 取消返回 false。

5.6 Registry(会话登记表)

Create(事务内,仅 Engine.Enqueue 调用——transport 没有开会话端点)/ Get / Delete。 id 服务端铸造,s_<ULID> 格式(多副本安全、趋势递增、带前缀)。 所有带 sessionId 的写操作先 Get 准入(不变量 1);不带 sessionId 的投递走 Create(§1.3 懒创建)。

5.7 Inbox(收件箱) —— 本节作废(修订⑨)

inbox 不建。internal/run/inbox.go 不存在;inbox 表不存在(§5.14)。 「还有哪些话没被回答」由客户端本地队列回答:忙时 409 session_busy, run_terminal 后自动补投。随之删除的:Cancel / ClearInbox 端点、 message_cancelled 帧、maxQueueDepth 背压、Drain、会话内 messageId 主键仲裁。 作废前本节定义的 Inbox 接口、ErrMessageIDTaken、幂等措辞见修订留档(§9.5、§11 问题 3)。

5.8 SessionLog(会话级事实真源)

文件:internal/run/sessionlog.go(接口)+ internal/run/sqlite/sessionlog.go(实现)

与 v4 相同,删去 Reconcile(修订⑨:没有 inbox 要捞了,重启恢复只剩 run 租约判定,§7.8): NextSeq / Append / AppendInTx / Subscribe / Since / CloseSession / Close。

SessionFeed 分层保留(Since + Subscribe + Notify),但 v5 里它的主要消费者 不再是 SSE handler,而是 Feed 扇入器(§4.4)。 (修订⑩:原「将来换 WS 多路复用(账号级)时 Attach 签名不变」的前瞻说明已删除—— 账号级传输整体后置、届时讨论,见 §11 问题 15;Feed 的类型抽象是既成事实,不是预留设计。)

5.9 Engine:Enqueue(投递+建 run)/ drive / finishAtomic / Stop / Delete

文件:internal/run/engine.go

// Engine 是单例:不持有任何 per-session 常驻对象,所有方法显式收 sessionID。
// 它持有的进程内状态全部是加速路径(§3 的清单),真源都在库里。
// 修订⑨:没有 Inbox 字段,没有调度器——闸检查 + 建 run 就在 Enqueue 的事务里。
type Engine struct {
    ctx        context.Context // 进程 ctx(不变量 3)
    db         *sql.DB         // 各原子事务的事务域(Enqueue / finishAtomic / Reconcile)
    registry   Registry
    runLog     RunLog
    sessionLog SessionLog
    archive    Archive
    approvals  *Approvals
    feed       Feed
    agent      adk.Agent
    runner     *adk.Runner

    mu      sync.Mutex
    runCtxs map[string]context.CancelFunc // runID → cancel,纯本地加速路径
}

// runState 是一场 run 的全部进程内状态。由 drive goroutine 独占持有,run 结束即消亡。
type runState struct {
    id            string
    sessionID     string
    cancel        context.CancelFunc
    stopped       bool
    messageIDs    []string
    userText      string
    compact       *CompactState
    // ── 流式正文的 flush 暂存(v5 新增,替代 v4 的 Partial 协议)──
    openMsgSeq    int64  // 当前生成中行的 rseq;0 = 没有
    msgText       strings.Builder // 已收到的全文(flush 的源)
    msgDirty      bool   // 自上次 flush 以来有新文本
    lastFlush     time.Time
}

闸只有一种形态:DB 部分唯一索引(与 v4 相同):

CREATE UNIQUE INDEX one_live_run_per_session ON run_archive(session_id) WHERE status='running';

「判断闸空」与「开 run 并占闸」在 Enqueue 的同一个事务里完成(修订⑨,不再有独立的 beginRunAtomic):事务内先 LiveRunID 查闸(给出干净的 409 session_busy), 再 INSERT run 档案行——并发投递撞唯一索引 = 闸忙 = 事务回滚、同样 409。 一次事务两种判忙路径,多副本下唯一索引是仲裁者(§13.5)。

会话级串行化点:session 行锁。 任何以 sessionID 为键的写事务 (Enqueue / finishAtomic / Delete / Stop / Approve,修订⑨ 后就这五个), 第一条语句是 SELECT session_id FROM session WHERE session_id=? FOR UPDATE—— 准入检查与行锁是同一条 SELECT:行不存在 → 404(不变量 1);行存在 → 持锁到事务结束。 锁顺序唯一(session 行 → 其他行,无第二顺序),且所有操作都是单会话的,不会死锁。 它治的竞态:Delete 与 Enqueue 交错时,无锁则两个事务可以都提交、留下没有 session 的 孤儿 run/session_log 行;有锁则要么 Delete 先赢(Enqueue 拿锁后重查准入 → 404), 要么 Enqueue 先赢(Delete 把它新开的 run 随五表一起删掉)——竞态表「删会话 vs 投递」的保证由此成立。 外键(§5.14)是 DB 层的第二道。注意:行锁与 FOR UPDATE 是 PostgreSQL 语义; SQLite 替身下退化为库级写锁,只验逻辑、不验并发——并发正确性以目标库为准(§13.5)。

Enqueue(修订⑨:投递 + 建 run,一笔事务):

func (e *Engine) Enqueue(ctx, sessionID, messageID, expectedRunID, text string) (string, int64, error) {
    tx, err := e.db.BeginTx(e.ctx, nil)          // 进程 ctx(不变量 3)
    if err != nil { return "", 0, err }
    defer tx.Rollback()

    // 懒创建(§1.3):无 sessionID → 事务内铸新行(s_<ULID>,服务端铸造),
    // 与 message_queued 帧、run 档案行同生同死;空会话不存在。
    // 有 sessionID → 准入 + session 行锁合一(FOR UPDATE,见上节)。未登记 → 404。
    // 此后本事务与 Delete / finishAtomic / Stop 等所有会话级写串行。
    if sessionID == "" {
        sessionID = registry.MintID()
        if err := e.registry.CreateInTx(e.ctx, tx, sessionID); err != nil { return "", 0, err }
    } else {
        if err := lockSession(e.ctx, tx, sessionID); err != nil { return "", 0, err }
    }

    // ── 闸检查(先查后插,给干净的 409;唯一索引兜并发,见上节)──
    live, _ := e.runLog.LiveRunID(e.ctx, tx, sessionID)
    if expectedRunID != "" && expectedRunID != live {
        // 新建会话 live="":首条消息带 expectedRunId 必 409——首条消息本来就不该带。
        return "", 0, &StaleViewError{LiveRunID: live}      // → 409 stale_view
    }
    if live != "" {
        return "", 0, ErrSessionBusy                        // → 409 session_busy,什么都不写
    }

    seq, err := e.sessionLog.NextSeq(e.ctx, tx, sessionID)
    if err != nil { return "", 0, err }
    if _, err := e.sessionLog.AppendInTx(e.ctx, tx, sessionID, SessionEvent{
        Kind: SessMessageQueued, MessageID: messageID, Text: text,
    }); err != nil { return "", 0, err }

    // ★ 同一笔事务:建 run 并占闸。撞唯一索引 = 并发投递赢了一半 = 回滚 → 409 session_busy。
    runID := runlog.MintID()                 // r_<ULID>,服务端铸造
    if _, err := e.runLog.BeginRunInTx(e.ctx, tx, runID, sessionID, text); err != nil {
        if isUniqueViolation(err) { return "", 0, ErrSessionBusy }
        return "", 0, err
    }
    if _, err := e.sessionLog.AppendInTx(e.ctx, tx, sessionID, SessionEvent{
        Kind: SessRunStarted, RunID: runID, MessageID: messageID, Resumed: false,
    }); err != nil { return "", 0, err }

    if err := tx.Commit(); err != nil { return "", 0, err }  // → 500;客户端带同一 messageId 重发
                                                             // (重发仲裁只剩客户端约束 4,见下;
                                                             //   首条消息的重发缺口见 §1.3 / §11 问题 18)
    e.sessionLog.bump(sessionID)
    e.runLog.bump(runID)
    st := e.newRunState(runID, sessionID, messageID, text)
    go e.drive(st)                               // run 的命不属于连接(不变量 2)
    return sessionID, seq, nil                   // handler 回带 sessionId(两种形态都带)
}

服务端失败只有两种,都是整体回滚(修订⑨ 后更对称了):

两种失败都不产生不一致。原 v4/v5 的「Append 失败不回滚 inbox」中间态、 「beginRunAtomic 失败消息搁浅」(§11 问题 2)——机制整体不存在,问题连根删掉。

frame 必然比 202 先到:run_started 帧、start 帧与所有库行在同一个事务里提交, drive goroutine 在 Commit 之后启动——它们的广播只会发生在 202 响应到达浏览器之前。 前端按 messageId 对齐(§6.3 约束 2),不依赖顺序。

trySchedule 与 beginRunAtomic —— 已删除(修订⑨):调度回路随 inbox 一起拆除。 「入队但不调度」的状态不存在了:Enqueue 提交 = 开跑;run 之间没有「纳秒级调度窗口」, 下一条消息由客户端在 run_terminal 后补投(一轮 run 的启动点从三个调用点收束成一个:Enqueue)。

drive 的流式循环(v5 重写:flush 循环替代 Partial 协议):

// 模型每吐一条 *schema.Message:
switch Classify(agent, mv, msg) {
case message 帧(正文增量):
    st.msgText.WriteString(delta)
    st.msgDirty = true
    if st.openMsgSeq == 0 {
        se := runLog.BeginMessage(ctx, st.id, ev)   // INSERT final=0,拿到真实 rseq
        st.openMsgSeq = se.Seq
    }
    // 节流 flush:距上次 ≥100ms 或增量 ≥2KB
    if st.msgDirty && (time.Since(st.lastFlush) >= 100*ms || pendingBytes >= 2*KB) {
        runLog.UpdateMessage(ctx, st.id, st.openMsgSeq, st.msgText.String())  // UPDATE → 提交后才 bump
        st.msgDirty, st.lastFlush = false, now
    }
case 其他帧:
    if st.openMsgSeq != 0 { flush + FinalizeMessage(..., MsgOK); st.openMsgSeq = 0 }
    runLog.Append(ctx, st.id, ev)
}
// 流结束(无论成败):若 openMsgSeq 非 0 → flush + FinalizeMessage(MsgOK / MsgDrop / MsgDiscard)

flush 的顺序即不变量 4:UpdateMessage 内部是「UPDATE → commit → bump」, 订阅者被唤醒后读库——它们只能读到已提交的内容。「推了库里没有的东西」没有对应的代码路径。

节流的崩溃账:进程崩在两次 flush 之间,最多丢 100ms 未落库的文本尾巴—— 这截尾巴 Connected 客户端也没见过(没见过 = 没推过),所以它不是「用户看到的东西丢了」, 是「还没来得及给任何人看的东西没存」。与 v4 §9.2 的「几十秒已显示正文彻底丢失」是两个量级。

drive 收尾(v5 修订:finishAtomic 一个事务):terminalOf 定终局 (persistErr > complete > stop > error)→ 压缩补丁只有 complete 才随 FinishInTx 提交、其余 RevertStage → finishAtomic:一个事务里 FinishInTx(终局帧 + status + 补丁)+ sessionLog.AppendInTx(run_terminal), 先锁 session 行 → AddRun(内存缓存,事务提交后)。 放闸 = 该事务提交;之后没有任何调度动作(修订⑨:没有收件箱要查,下一条消息由客户端 在 run_terminal 后补投)。同事务的动机:v5 原文里 run_terminal 是 Finish 之后的独立 Append, 进程死在两者之间会留下「run 已终局、会话级永不落幕」的窗口——Reconcile 只扫 running, 扫不到它,客户端的气泡永远停在 answering。同事务后这个窗口不存在: 要么事务没提交(run 仍 running,租约到期后由 Reconcile 连 run_terminal 一起补,§7.8), 要么三者同生。

Stop / Delete / Approve / Snapshot:与 v4 相同。 要点复述:Stop 写 stop_requested 列(真源)+ 本地 cancel(加速)—— 不取消任何东西之外的消息,客户端队列归客户端(修订⑨); Delete 三步(查 running 行取消 live → 同事务删五表 → 关订阅与缓存), 以 sessionID 为键、不依赖客户端知道 runID;删除事务先锁 session 行(与所有并发写串行, 见本节「会话级串行化点」),子表先删、session 行最后删(外键顺序,§5.14); Snapshot 的 LiveRunID / LastSeq 必须同源读取(一个事务)。

5.10 run_archive 的 message_ids

user_message 就是这条 message 的原文(合并已删,修订⑨,恒为单句), message_ids 仍是 JSON 数组但恒为单元素——列不动,留给将来「一轮消费多条」的可能复活点; 真到那天再改写法,现在不为它优化。

5.11 Approval 与 Checkpoint

与 v4 相同:决策行落库(真源)+ 本地 waiters(加速)+ 低频轮询(跨副本兜底)。 Create 先于审批帧落行;Decide 是条件 UPDATE;Wait 双通道阻塞。 Checkpoint 是进程内存的 adk.CheckPointStore,重启即丢。

5.12 Transport

文件:internal/webui/

路由表(修订⑨ 后 8 条:撤回与清空随 inbox 删除):

路由 handler 做什么
GET / handleIndex 静态冒烟页(阶段一)
GET /api/session?id= handleSession 准入检查 + engine.Snapshot() → {liveRunId, lastSeq}
★ GET /api/session/stream?id=&from=&runFrom=&replay= handleStream 准入检查 + 解析游标(Last-Event-ID 优先于显式参数,§4.3)+ feed.Attach() → 统一 SSE(常驻,无自然终止)
★ POST /api/message handleMessage engine.Enqueue() → 202 + {"sessionId","seq","messageId"};无 sessionId 时事务内含铸会话(§1.3);忙 → 409 session_busy(什么都不写)
★ DELETE /api/session/:id handleDelete engine.Delete() → 204(级联见 §5.9)
GET /api/session/history?id=&cursor=&limit= handleHistory runLog.HistoryPage()
POST /api/approval handleApproval engine.Approve()
POST /api/stop handleStop engine.Stop()

删掉的路由:GET /api/chat/stream(v4 的 run 级订阅,功能被统一流的 runFrom 游标与 Feed 回放完全覆盖);DELETE /api/message/:id(撤回)与 DELETE /api/session/:id/inbox(清空)——队列在客户端,撤回/清空是本地操作(修订⑨)。 一个客户端对一个会话,永远只有一条流。

没有的路由(与 v4 相同):POST /api/chat、任何补发/恢复端点。

handler 仍 ≤ 15 行。handleMessage 与 v4 相同(六行 + 响应回带 sessionId 一行), 只是 Enqueue 内部从事故容忍变成了事务,并多了懒创建分支(§1.3)。

DTO:

type messageRequest struct {
    SessionID     string `json:"sessionId"`            // 可空:首条消息不带,事务内含铸会话(§1.3)
    MessageID     string `json:"messageId"     binding:"required"`
    ExpectedRunID string `json:"expectedRunId"`        // 首条消息不得携带(新会话 live="",带了必 409)
    Text          string `json:"text"          binding:"required"`
}
type messageResponse struct {
    SessionID string `json:"sessionId"`  // 两种形态都回带:创建时是新铸的 id,否则原样回显
    Seq       int64  `json:"seq"`
    MessageID string `json:"messageId"`
}

// 统一流上的帧:两种形状,靠有没有 "run" 字段区分。
// 会话级帧:
type sessionFrame struct {
    Seq          int64  `json:"seq"`
    Ts           string `json:"ts"`
    Kind         string `json:"kind"`
    MessageID    string `json:"messageId,omitempty"`
    Text         string `json:"text,omitempty"`
    RunID        string `json:"runId,omitempty"`
    Resumed      bool   `json:"resumed,omitempty"`
    TerminalKind string `json:"terminalKind,omitempty"`
}
// run 级帧(注意:序号字段叫 rseq,与会话级 seq 区分):
type runFrame struct {
    Run       string     `json:"run"`
    Rseq      int64      `json:"rseq"`
    Ts        string     `json:"ts"`
    Kind      string     `json:"kind"`
    Final     *bool      `json:"final,omitempty"`     // 仅 kind=message:false=生成中,true=定稿
    Outcome   string     `json:"outcome,omitempty"`   // 定稿结局:drop / discard / interrupted
    Agent     string     `json:"agent,omitempty"`
    Role      string     `json:"role,omitempty"`
    Text      string     `json:"text,omitempty"`
    ToolName  string     `json:"toolName,omitempty"`
    ToolCalls []ToolCall `json:"toolCalls,omitempty"`
    Approval  *Approval  `json:"approval,omitempty"`
}
// 心跳:{"kind":"heartbeat","seq":<当前会话级 seq>},id 带双游标。

SSE 线格式:id: <sessionSeq>:<runId>:<rseq>\ndata: <JSON>\n\n,每帧 Flush。 会话级帧的 id 里 runId/rseq 段填最近一次 run 帧的值(游标是全局的,不是每帧各自的); 心跳同理。sse.go 只有一个 Stream():从 Feed.Attach 拿 Stream,逐帧写, 同时按上面的规则拼 id:。没有终止条件——会话删除时由 CloseSession 断开。

5.13 错误体与错误映射中间件

与 v4 相同的三段式 {"error":{"code","message","detail"}} 与 errorMapper 中间件。 映射表(修订⑨ 重写):

领域错误 状态码 code 说明
ErrSessionBusy 409 session_busy 会话有 running run。事务整体回滚、什么都没写;客户端本地排队,run_terminal 后带同一 messageId 补投,安全重试。这是唯一的「状态冲突」错误(不变量 7 反转)

其余:bad_request 400 / session_not_found 404 / run_not_found 404(保留给 history 等场景)/ stale_view 409(detail.liveRunId,expectedRunId fencing)/ internal 500。 已删(随 inbox):message_id_taken 409(无 inbox 主键可撞)、message_not_found 404、 queue_full 422(无服务端背压,§9.5)。

5.14 建表汇总

-- 会话身份(§5.6)
CREATE TABLE session (
    session_id TEXT    PRIMARY KEY,
    created_at INTEGER NOT NULL
);

-- run 级事实(§5.3)。★ v5:final / updated 两列是新的
CREATE TABLE run_log (
    run_id  TEXT    NOT NULL REFERENCES run_archive(run_id),
    seq     INTEGER NOT NULL,
    ts      INTEGER NOT NULL,
    updated INTEGER NOT NULL,     -- 最近一次更新;final=1 的行恒等于 ts
    kind    TEXT    NOT NULL,
    final   INTEGER NOT NULL,     -- 1 = 定稿;0 = 生成中。★ 仅 kind='message' 允许 0
    payload TEXT    NOT NULL,     -- Event 的 JSON;定稿结局(drop/discard/interrupted)在其中
    PRIMARY KEY (run_id, seq)
);
-- 应用层约束:final=0 仅见于 kind='message';只有 final=0 的行允许 UPDATE;
-- UPDATE 只许改 payload、updated、final。

-- 模型视图(§5.4)。★ 修订:owner / lease_until 两列是新的(执行租约,§5.3)
CREATE TABLE run_archive (
    run_id        TEXT PRIMARY KEY,
    session_id    TEXT NOT NULL REFERENCES session(session_id),
    created_at    INTEGER NOT NULL,
    status        TEXT NOT NULL,      -- running / complete / error / stop / failed
    stop_requested INTEGER NOT NULL DEFAULT 0,
    owner         TEXT NOT NULL,      -- 执行者副本 id(n_<ULID>),只用于租约归属
    lease_until   INTEGER NOT NULL,   -- 租约到期时刻(unix 毫秒);drive 周期续租
    user_message  TEXT NOT NULL,
    message_ids   TEXT NOT NULL,      -- JSON 数组
    produced_json BLOB
);
CREATE INDEX idx_archive_session ON run_archive(session_id, created_at DESC);
CREATE UNIQUE INDEX one_live_run_per_session ON run_archive(session_id) WHERE status='running';
CREATE INDEX idx_archive_lease ON run_archive(lease_until) WHERE status='running';  -- 周期 Reconcile 扫描用

-- 会话级事实(§5.8)
CREATE TABLE session_log (
    session_id TEXT    NOT NULL REFERENCES session(session_id),
    seq        INTEGER NOT NULL,
    ts         INTEGER NOT NULL,
    kind       TEXT    NOT NULL,
    payload    TEXT    NOT NULL,
    PRIMARY KEY (session_id, seq)
);

-- 会话级 seq 计数器(Enqueue 事务内 NextSeq,§5.9)
CREATE TABLE session_seq (
    session_id TEXT PRIMARY KEY REFERENCES session(session_id),
    seq        INTEGER NOT NULL
);

-- 压缩换掉的原文(§5.4)
CREATE TABLE compact_rag (
    session_id TEXT NOT NULL REFERENCES session(session_id),
    run_id     TEXT NOT NULL,
    body       TEXT NOT NULL,
    created_at INTEGER NOT NULL
);

-- 审批决策行(§5.11)
CREATE TABLE approval (
    session_id  TEXT NOT NULL REFERENCES session(session_id),
    run_id      TEXT NOT NULL,
    approval_id TEXT NOT NULL,
    decision    TEXT,
    created_at  INTEGER NOT NULL,
    decided_at  INTEGER,
    PRIMARY KEY (session_id, approval_id)
);

7 张表 = 4 份持久状态 + 3 张辅助表(inbox 已删,修订⑨)。列变化:run_log 加 final / updated; run_archive 加 owner / lease_until(执行租约,§5.3)。 外键是修订新增:五张子表引用 session(run_log 引用 run_archive)——孤儿行在 DB 层不可能, 是 session 行锁(§5.9)之外的第二道。Delete 在同一事务里先删子表、最后删 session 行。 SQLite 替身需 PRAGMA foreign_keys=ON;外键与行锁的并发语义以 PostgreSQL 为准(§13.5)。


6. 前端契约

产品前端是 Vue,属于独立 loop。 本节只定契约。阶段一不写产品前端,验收全程用 curl(§7.9)。

6.1 启动编排(v5:一条流,没有挂载状态机)

页面加载
  │
  ├─ ⓪ 有 sessionId 吗?(本地存的)
  │     有 → GET /api/session?id= 验一下:200 用它;404 → 清掉本地 id,走「无」
  │     无 → 不调任何服务器接口:不挂流、不取快照,呈现一个空会话的输入框
  │        第一条消息发出(POST /api/message 不带 sessionId)→ 202 回带 {"sessionId",…},存下来
  │        → 拿到 id 后才 ② 挂流(from=0,库里有几帧重放几帧)
  │        ★ 不要自己 mint 一个 UUID 当 sessionId(§1.3)——等服务器铸
  │
  ├─ ① GET /api/session?id= → {liveRunId, lastSeq}
  │     用途:首屏对齐。liveRunId 非空则画一个「正在回答」的占位
  │     (仅「有 id」分支;空会话没有可对齐的世界,也不需要)
  │
  └─ ② new EventSource(`/api/session/stream?id=${id}&from=${lastSeq}&runFrom=0`)
        from=:「有 id」分支取 ① 的 lastSeq;「无」分支(首条消息之后才挂)固定 0
        ★ 唯一的一条流,常驻,页面活着就开着
        ★ from=/runFrom= 只在这次首次挂载生效;此后自动重连必带 Last-Event-ID,
          服务端以它为准(§4.3)——URL 里的旧值不会把游标拉回去
        on message_queued    → 画用户气泡(带全文,由帧画出)
        on run_started       → messageId 对应气泡标 answering;开一块 run 视图(按 runId 键控)
        on run 帧(有 run 字段) → 按 (run, rseq) 路由到对应 run 视图:
              final:false → 原位替换气泡文本;final:true → 定稿
        on 终局帧(complete/error/stop) → run 视图收尾(流**不关**,它管整个会话)
        on run_terminal      → answering 气泡 → answered;本地队列非空 → 自动补投队首;
                               更新状态文案
        on heartbeat         → 更新存活指示;不需要别的

断线重连是免费的:EventSource 自动重连并带 Last-Event-ID(id: 里编码的双游标), 服务端的 Feed 追赶逻辑(§4.4)补齐漏掉的会话帧与 run 内容。客户端不需要任何重连代码, 也不需要每帧手动记游标——v4 §9.3 第 1 条那个「sessionSeq 必须每帧更新、报大了丢帧兜不住」 的前端陷阱,由 SSE 协议的 id: 字段接管了。

对比 v4 删掉的东西:「收到 run_started 后新挂第二条流」「终局帧到达关流」 「两条流续传起点不对称(一个 from=0 一个 from=lastSeq)」——全部不存在了。 整页刷新与 SSE 单独断线(v4 用例 3 与用例 14 的区别)在 v5 里是同一条路径, 差别只剩 from/runFrom 从哪来(Snapshot 还是 Last-Event-ID)。

6.2 消息气泡的状态机(修订⑨:两态,更简单了)

            POST /api/message
                  │
 ┌────────────────┼─────────────────────┐
 │ 409 session_busy│                202 {seq,messageId}
 ▼                ▼                     ▼
[进本地队列]   [其他失败]        ┌───────────────┐
  │      [输入框内容还回]        │  sent          │ ← message_queued 帧画出
  │ run_terminal                └───┬───────┬───┘
  │ 自动补投            run_started│       │
  └────────────────►[气泡消失]    ▼       ▼
                            ┌───────────────┐
                            │  answering     │
                            └───────┬───────┘
                                    │ run_terminal
                                    ▼
                            ┌───────────────┐
                            │  answered      │
                            └───────────────┘

本地队列是唯一的新前端组件(修订⑨):收到 409 session_busy 进队, run_terminal 后出队补投(带原 messageId);刷新/关页即丢弃——队列随客户端生死,§9.5。

6.3 必须遵守的约束(修订⑨ 后四条)

  1. 发送按钮永远可用。 不存在「busy」——忙时 POST 返回 409 session_busy, 进本地队列、run_terminal 后自动补投。停止键按 liveRunId 显隐,与发送键无关。
  2. 服务端回显,不要本地回显。 用户气泡由 message_queued 帧画出(帧带全文)。 POST 失败把输入框内容还回去(409 session_busy 除外——它进本地队列)。 换来的是「帧与视图永远一致」:本端任何时刻的视图都能从流回放重建, 代价是一个 RTT 的延迟感。
  3. 前端不保存任何服务端不知道的状态——本地队列除外(修订⑨,它是服务端明确 让渡给客户端的职责)。本地只存 sessionId / 队列。 重连靠 Last-Event-ID(自动重连必带它,服务端以它为准——URL 里的 from= 只在首次挂载生效,§4.3), 整页刷新靠 Snapshot + from=lastSeq。 还没有 sessionId 时(未发首条消息)不挂流、不取快照——空会话没有可对齐的世界(§1.3 懒创建)。
  4. 重发必须先回放、且复用同一个 messageId。 没收到响应时,先让流追平 (EventSource 自动重连即可):回放里出现同一个 messageId 说明已落地,撤销重发; 没出现才重发,且必须带同一个 id。修订⑨ 后这是唯一的重发仲裁(没有 inbox 主键兜底): 跳过回放直接重发,可能在 run 落幕后把同一句话再答一次。

7. 完整链路:八幕

沿用 v4 的贯穿例子(修订⑨ 改版):会话 s_1 已有 r_15、r_16 两轮;m_1 开跑 r_17; r_17 期间用户发 m_2 → 409 session_busy、进本地队列;r_17 落幕后补投 m_2、 开 r_18;r_18 期间压缩换掉 r_15;中途刷新一次、进程重启一次。

会话级 seq 仍是唯一对账锚:

seq=1 message_queued(m_1)        seq=2 run_started(r_17, m_1)
seq=3 run_terminal(r_17)         seq=4 message_queued(m_2)        seq=5 run_started(r_18, m_2)

(m_2 的 message_queued 在 seq=4:它发生于 r_17 落幕后。忙时的 409 不产生任何帧—— 服务端的世界里什么都没发生,这与「客户端本地排了一条」是两回事。)

7.1 第一幕:投递

POST /api/message {sessionId:"s_1", messageId:"m_1", text:"读一下 doc/19"}
  │
  ├─ engine.Enqueue(...)
  │     └─ 一个事务(§5.9,修订⑨:投递 + 建 run 合一):
  │          准入 + session 行锁(未登记 → 404,不变量 1)
  │          → LiveRunID 查闸(非空 → 409 session_busy)
  │          → NextSeq=1 → AppendInTx(message_queued{m_1}, seq=1)
  │          → BeginRunInTx(r_17, userMessage="读一下 doc/19")  -- 档案行 + start 帧,占闸
  │          → AppendInTx(run_started{r_17, m_1}, seq=2)
  │        commit → bump → 建 runState{r_17} + ModelMessages() + go drive(runCtx, st)
  └─ 202 {"sessionId":"s_1","seq":1,"messageId":"m_1"}

客户端从统一流上依次收到 message_queued(m_1)、run_started(r_17)、start 帧—— 不需要挂第二条流,帧自己会来。帧必然比 202 先到(同一事务提交后才起 drive), 按 messageId 对齐。

数据变化(修订⑨):session_log +2 帧;run_archive +r_17 行;run_log +start 帧。 没有第五张表要记。

7.2 第二幕:忙时投递

修订⑨ 新增的画面,替代原「排队」一幕:m_2 的 POST 在 r_17 期间到达 → 闸检查非空 → 事务整体回滚 → 409 session_busy,库里什么都没有。 A 的前端把 m_2 放进本地队列并画出提示;B 的前端(同一 sessionId)若此刻也发消息, 同样 409、同样进 B 自己的队列——两端各排各的,互不知道对方(§9.5 第 1 条代价)。

7.3 第三幕:模型开口(v5:正文随时在库里)

模型吐 *schema.Message
  ├─ Classify → (Event, ok);ok=false 跳过
  ├─ A 路(给模型的):root agent 的消息攒进 list,落幕时成 produced_json —— 不变
  └─ B 路(给人的):
       message 帧 → drive 的 flush 循环(§5.9):
           BeginMessage(INSERT final=0,拿真实 rseq)→ 节流 UpdateMessage(UPDATE)
           → 流结束 FinalizeMessage(final=1)
       其他帧 → runLog.Append(INSERT final=1)

与 v4 的差别落在两处:① 订阅者(包括刷新后刚挂上流的)在输出进行中就能读到当前文本 (读库即得),v4 里他们要等 seal;② 每一帧推出去之前,它的内容已经在库里(不变量 4 从纪律变结构)。

7.4 第四幕:中途停顿,等人拍板

与 v4 相同:ask 五步(Create 落行 → emit approval 帧 → Wait 挂起 → Approve 写库唤醒 → emit approval_result)。挂起占闸:审批期间投递一律 409 session_busy,客户端照常本地排队。

7.5 第五幕:压缩在暗处进行

与 v4 相同:Stage 全程不碰库,补丁随 finishAtomic 事务写(§5.9);compact 帧只追加。

7.6 第六幕:落幕

事务边界修订:terminalOf → finishAtomic 一个事务(FinishInTx 含 CommitPatch + sessionLog.AppendInTx(run_terminal),§5.9)→ AddRun。 闸的释放 = 该事务提交;之后没有任何服务端动作(修订⑨)—— A 的前端收到 run_terminal 后把本地队列队首(m_2)补投出去,走一遍 7.1 的事务,开 r_18。 「停止后自动开跑」(用例 7)就是这条客户端行为的产物:Stop → run_terminal → 补投。

7.7 第七幕:刷新(v5 大幅简化)

A 刷新(本地存着 s_1)
  ├─ GET /api/session?id=s_1 → {"liveRunId":"r_18","lastSeq":5}
  └─ new EventSource(/api/session/stream?id=s_1&from=5&runFrom=0)
       → Feed 追赶:游标 run 为空(lastRunID 空串)→ 会话级 seq>5 无帧
       → live 兜底(§4.4 规则 3):live run r_18 从 rseq=0 回放已落库内容 → 切实时

v4 里这一幕的难点全部消失:没有「两条流起点不对称」(只有一条流); 快照只剩 LiveRunID / LastSeq 两个字段(修订⑨:没有队列可对齐), 且二者同源读取仍是要求——流从 lastSeq 起、内容回放只在 run 命名空间里, 两个命名空间互不干扰。刷新后本地队列丢了(它只在内存/localStorage 里): 正在排的消息要用户重发——§9.5 第 4 条代价,UI 不为此做恢复。

(修订⑩:原「多端的含义不变:A 和 B 收到同一行 session_log / run_log 的两次投递」 已删除——跨端同步后置。同一客户端内,帧来自库行回放的唯一副本,不存在对齐问题。)

7.8 第八幕:进程重启

启动顺序(修订⑨ 后只剩一步,仍不可换):Engine.Reconcile——对每场租约已过期的 running run 开一个事务:FailInTx(标 failed + 补 error 终局帧 + 把遗留 final=0 行定稿为 interrupted,§5.3)

多副本语义:Reconcile 只判「租约过期」的 run(§5.3)。副本 B 重启不会动副本 A 正在执行的 run——A 在续租,租约未过期。v5 原文的「启动时把遗留 running 标 failed」是单实例语义, 直接搬进多副本会把健康副本的 run 误判死;租约化之后两者是同一条规则: 单副本下进程死了没人续租,重启时租约必已过期。

客户端侧的恢复比 v4 更强:浏览器 EventSource 自动重连,Last-Event-ID 还带着断开前的 双游标(服务端以它为准,§4.3);服务端进程虽然换了一个,但游标指向的是库里的行, Feed 追赶照常补齐——包括被定稿为 interrupted 的半截正文(它一行不少)。整页都不需要刷新。

阶段一(v4 意义上)的已知损失已关闭:唯一会丢的是两次 flush 之间的 ≤100ms 文本尾巴, 且那截尾巴从未被推给任何客户端(§5.9 的崩溃账)。

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

本章节已移至 7.9-业务用例链路.md。

(含 13 个用例的线上真实字节、帧样例与 curl 验收命令;修订⑨ 前为 16 个。)


7.10 竞态对照表

测试必须逐条覆盖——全是「不崩但结果错」的类型。

竞态 谁和谁 正确结果 靠什么保证 测法
★ 并发投递(修订⑨ 新增) 两个 POST /api/message 同时到达空闸 一 202 一 409 session_busy;只开一场 run session 行锁串行化 + one_live_run_per_session 唯一索引仲裁(§5.9) 两 goroutine 并发投递,断言恰好一场 running run、两响应各归各
投递 vs 落幕 POST /api/message 与 finishAtomic 纳秒级交错 run_terminal 先提交 → 409;Enqueue 事务先提交 → 202 开新 run;不会「落幕后又开一场同消息的 run」,也不会搁浅 两个事务争 session 行锁,唯一索引 + 行锁仲裁(§5.9) 并发驱动收尾与投递,断言两种结局之一且库里无半成品
停止 vs 正常完成 POST /api/stop 与自然返回 只写一条终局帧;产出已拿到则记 complete terminalOf 判断顺序 最后一帧前触发 stop
删会话 vs 投递 DELETE /api/session/s_1 与 POST /api/message 202 或 404 都可,不留孤儿行 session 行锁串行化(§5.9)+ Delete 同事务先子后父删五表 + 外键兜底(§5.14) 删后查五表行数 = 0,等 10 秒再查
重连 vs 修剪 续传与 session_log/run_log 修剪(未决,§11 问题 10) from 早于已修剪处不能静默丢帧 待定 决议后补
★ 终局 vs 落幕通知(v5 新增) run 的终局帧与会话级 run_terminal 在 Feed 里扇入 客户端永远先收完 r 的内容(含终局帧),再收 run_terminal(r) Feed 规则 4:run_terminal 压到对应订阅排空后发(§4.4) 并发驱动 run 收尾与订阅,断言流上顺序
★ flush vs 落幕(v5 新增) UpdateMessage 在途与 finishAtomic 提交 终局帧落库时,生成中行已定稿(没有 run 结束了还有 final=0 行) drive 顺序:Finalize 在 finishAtomic 之前;Reconcile 兜底定稿孤行 断言任意时刻 status!='running' 的 run 无 final=0 行
★ 收尾崩溃(修订新增) 进程死在 finishAtomic 之前或之中 事务未提交 → run 仍 running → 租约到期由 Reconcile 连 run_terminal 一起补;「终局帧已落库、run_terminal 永缺」的状态不存在 finishAtomic 同事务(§5.9)+ Engine.Reconcile 逐场单事务(§7.8) 故障注入收尾各点,重放断言终局帧与 run_terminal 同有或同无
★ 僵尸执行者(修订新增) 租约过期被判死后,原执行者复活并迟到写入 Append / FinishInTx 全部被拒;闸位由后来合法的 Enqueue 占用 run 级写全部以 status='running' 为条件更新(fencing,§5.3) 判死后从旧 drive 发写,断言全拒且新 run 不受影响

前四条覆盖投递/停止/删除主线,中间一条待修剪决议,后四条是 v5 新机制与修订的对应测试。 全部随对应 action 一起写,不留到最后补。 (修订⑨ 删除的三条:「撤回 vs 开跑」「清空 vs 开跑」「重发 vs Drain」——端点与 inbox 不存在, 竞态失去双方当事人。)


8. 必须覆盖的失效场景

验收清单。每条:场景 → 根因 → 本方案靠哪条设计覆盖 → 怎么验。 v4 的六条里,D 和 E 在 v5 里被结构消除,C 随跨端同步整体后置删除(修订⑩), 其余三条(A/B/F)保留——B 收窄为本端语义,跨端断言随之后置(§11 问题 15)。

场景 A:「新会话」时旧 run 在后台续跑(不变)

场景:按下发送,模型还在思考(客户端还不知道 runID),用户点了「新会话」。 根因:任何「前端记住 runID、切会话前发 stop」的做法都漏掉这段窗口。 覆盖:DELETE /api/session/:id 第 1 步以 sessionID 为键取消 live run(§5.9), 随后同事务删五张表。被取消的 run 写帧撞已删除的行 → persistErr → 退出。 怎么验:发送后立刻 DELETE,查五张表行数为 0,等 10 秒再查仍为 0。

场景 B:投递被拒之后看不到新内容(修订⑨ 改语义;修订⑩ 收窄为本端)

覆盖:① 忙时投递不拒绝在服务端落库——它根本什么都不写;本端收到 409 后自己排队, 并在 run_terminal 后自己补投——气泡出现的前提是它排了队; ② 会话级流常驻——投递若成功,message_queued 主动送达,气泡由帧画出(约束 2)。 怎么验:一轮 run 进行中投递 → 断言 409 session_busy 且库里无任何新行; run_terminal 后补投 → 202、新一轮 run 只含这一条 message。 (原跨端断言「B 收到逐字节相同的 message_queued」随修订⑩ 删除,见 §11 问题 15。)

场景 D:进程重启后客户端永远挂着等终局 —— v5 结构性消除

v4 的病灶:run 级流以「读到终局帧」为关闭条件,Reconcile 只改 status 不补帧 → 永远等。 v4 的治法:Reconcile 补帧(保留,§5.3)。 v5 里这个场景连形态都不存在:没有 per-run 的流可挂;统一流没有「等某条流闭合」的概念, 追赶阶段自然播到 Reconcile 补的终局帧就继续往下走(§7.9 用例 5)。 补帧仍然必要——但为的是日志完整(重放者、history、对账),不再是「救一条悬空的连接」。 怎么验:开一轮 run,kill -9,重启;客户端(不重挂任何东西,EventSource 自动重连) 必须收到 outcome:"interrupted" 的定稿帧 + error 终局帧 + 会话级 run_terminal; 修订⑨:r_18 不会自己开跑——等客户端补投(§7.9 用例 5)。

场景 E:拿到 runID 就订阅,却 404 —— v5 结构性消除

v4 的病灶:runID 的可见时刻早于可订阅时刻。 v5 里没有「拿 runID 去订阅」这个动作——唯一的流按会话挂,runID 由流上的 run_started 帧告知,内容帧紧随其后(Feed 规则保证顺序,§4.4)。 不变量 9 保留,但守的是快照一致性(§2.2),不是订阅竞态。 怎么验:此场景无对应测试——它不可表达。回归测试是 §7.10 的「终局 vs 落幕通知」。

场景 F:run 在跑的时候用户打不了字(修订⑨ 改覆盖方式)

覆盖:发送键永远可用是客户端行为——忙时 409 session_busy 进本地队列、 run_terminal 后自动补投;服务端只保证 409 诚实(什么都不写)与 run_terminal 必达。 怎么验:一轮 run 进行中投递 → 断言 409 session_busy 且库里无任何新行; run_terminal 后补投 → 202、新一轮 run 只含这一条 message(合并已删,§9.5 第 2 条)。


9. 取舍与代价

诚实列出。v5 相对 v4:删掉两个已知代价(Partial 崩溃窗口、双倍连接占用), 新增四个(§9.2)+ 修订⑨ 新增五个(§9.5),其余照旧。

9.1 复杂度(修订⑨ 更新)

项 量 为什么非它不可
表 7(4 份持久状态 + 3 张辅助表) 每份回答一个不同的问题,两两不可互推(§1.4)
流 每会话 1 条 SSE 两个逻辑通道(§4.1)扇入一条物理连接(§4.4)
客户端游标 1 对(sessionSeq + runId/rseq) 由 SSE id: 字段携带,浏览器自动管理(§4.3)
Engine 单例,导出方法 5 个 每个对应一个真实用户动作
并发临界区 两处单事务:Enqueue(准入 + 闸检查 + message_queued + 建 run + run_started)、finishAtomic(终局帧 + status + run_terminal);均先锁 session 行 不变量 6、7、9(不变量 8 已作废)
前端组件 本地队列(修订⑨ 新增):进队 / run_terminal 补投 / 丢弃 服务端不做 inbox 的镜像代价,§9.5
新组件 Feed 扇入器(约 150 行) 两个数据源合成一条有序流必须有个地方做(§4.4)

9.2 v5 新增的四个代价

  1. run_log 的追加纯净性有一个例外(§1.1)。生成中的 message 行允许原位 UPDATE。 这是为关闭崩溃窗口付的语义税:写规则从「只追加」变成「追加 + 一类行的有限更新」。 有界(一类行、三个字段、定稿即止),但审计与回放工具必须知道这个例外存在。
  2. 每次 flush 是一次 DB UPDATE(100ms / 2KB 节流)。一场 run 几十秒正文输出 ≈ 几百次 UPDATE, SQLite 与 Postgres 都无压力;但它意味着「输出速率」与「写库速率」挂钩, 节流参数(§11 问题 16)选得激进会放大写量,选得保守会放大崩溃尾巴。
  3. Feed 有一条排序规则要维护(run_terminal 压到对应订阅排空后)。 这是「一条流」的代价集中点:v4 里这个顺序由「两条连接各自的时序」自然形成 (且不被保证),v5 把它变成显式规则 + 显式测试(§7.10 第七行)。
  4. 执行租约的写量与调参面(修订新增,§5.3)。每场活跃 run 每 5s 一次续租 UPDATE、 每副本每 15s 一次过期扫描——量级可忽略;但 TTL / 续租间隔 / 扫描间隔成为新的调参面 (§11 问题 17),且「判死延迟」有了下限:执行者死亡最快也要 TTL 之后才被发现。

9.3 照旧登记的取舍(与 v4 相同,压缩为一屏)

9.5 修订⑨ 的代价:inbox 删除与投递语义反转(照实登记五条)

换来的是:一张表、两个端点、三条竞态测试、整个调度回路(trySchedule/beginRunAtomic/ 不变量 8/§11 问题 2)消失,Enqueue 与建 run 合一事务。代价:

  1. 队列逻辑每个客户端各自实现一遍。 忙时各 409、各排各的、互不知道对方—— 跨端同步整体后置(修订⑩),「B 端看到 A 端排队中」届时随方案一并回来。 「发送键永远可用」的 UX 由前端本地队列保住,但它是前端组件,不是服务端事实。 后置增强:队列想要服务端可见/跨端一致时,inbox 以某种形态复活(届时合并语义一并重估)。
  2. 合并语义删除:一轮 run 只消费一条 message。run 期间连发三条 = 三轮 run 逐条回答。 以后要合并:客户端聚合文本(队首 messageId)或 API 收 batch,二选一,现在不做。
  3. 幂等兜底收窄:同 messageId 重发,忙时撞 409(消息没落库,安全);但「已提交而 客户端没收到响应」的重复回答窗口从「inbox 存活期」扩成整场 run 时长, 唯一防线是前端约束 4(先回放追平、再决定重发)。
  4. 队列随客户端生死:浏览器关闭/刷新,没发出去的排队消息即丢;服务端重启也没有 待办可捞(原 §7.8 的 inbox 续答分支删除)。已 202 的不受影响(不变量 2)。
  5. 服务端失去背压:maxQueueDepth 422 删除,客户端队列无界。 现阶段可接受;真出现「排到几十条」的使用方式时再以服务端可见队列的形式回来。

9.4 v4 有、v5 没有的代价(销账记录)


10. 实施顺序

v5 不分「阶段一 / 阶段二」。 v4 分阶段的全部理由是「Partial 机制先顶着、增量协议以后重写」; v5 里那个「以后」的主要内容已经消失(§9.4),剩下的都是独立增强,各有启动条件,不构成阶段。

实施方式是重写,不是重构。顺序原则不变:先 API 契约、再存储、最后前端; 执行按 tmp/v5-plan/todos.md 的用例 loop 排(契约 → 数据需求 → 存储 → 实现)。

  1. 模块骨架 + 搬能力包:go.mod、cmd/yktako/、internal/tools、guard、compact、 mediaoffload、msgtext、adkrun、config。门槛:go build ./... 与搬入包单测全绿。
  2. 领域类型与接口先行:Event / StoredEvent / MsgOutcome / Classify / Subscription、 SessionEvent 一族、StreamFrame / Stream / Feed、五个存储接口、DTO 与错误体。 门槛:build 过;Classify 单测穷举。
  3. API 契约落地(内存假实现):路由表(§5.12)、errorMapper、sse.go 的 Stream() (含 id: 双游标与 heartbeat)、各 handler。门槛:curl 手打用例 1、9,逐字节对。
  4. RunLog 的 SQLite 实现:建表(含 owner / lease_until 与外键)、BeginRunInTx、Append、 BeginMessage / UpdateMessage / FinalizeMessage、FinishInTx、 ListExpiredRunning / FailInTx(条件 UPDATE 判死 + 补终局帧 + 定稿孤行)、 Subscribe / Since、LiveRunID、HistoryPage。 门槛:生成中行「更新 → 定稿 → 再写拒」单测;final=0 约束单测; FailInTx 孤行定稿与幂等(重复判死只赢一次)单测;fencing(判死后写全拒)单测。
  5. Archive:与 v4 相同。门槛:stage → revert 逐条相同。
  6. Registry + SessionLog(修订⑨:无 Inbox):两张表 + session_seq;SessionFeed 三方法; Registry.CreateInTx(仅 Enqueue 内部调用,§1.3 懒创建)。 门槛:seq 不跳号不重号。
  7. Engine 真实现:Enqueue 单事务(§5.9,修订⑨:含闸检查 + 建 run—— 准入/懒创建 → LiveRunID 查闸(忙 → 409 session_busy)→ message_queued → BeginRunInTx → run_started,一笔事务)/ Stop / Approve / Snapshot / Delete、drive 的 flush 循环、 finishAtomic(终局帧 + status + run_terminal 同事务)、Engine.Reconcile (启动 + 周期,逐场单事务含 run_terminal)、session 行锁(所有会话级写事务的第一条语句)。 门槛:★ 压测并发投递(两个 Enqueue 争空闸:一 202 一 409,只开一场)与 投递 vs 收尾纳秒级并发(不双跑、不搁浅、无半成品行); ★ Enqueue 故障注入(事务中每一步失败都整体回滚、重发行为符合 §5.9 三种失败路径); ★ 收尾故障注入(§7.10:终局帧与 run_terminal 同有或同无);-race 全绿; ★ eino 验证项:per-run 绑定(BindMemory、checkpoint key)可行。
  8. Feed 扇入器:追赶(游标 run 补齐 + 会话帧遍历 + live 兜底)+ 实时 + 排序规则(§4.4 四条)。 门槛:§7.10 第七、八行两条竞态测试; Last-Event-ID 续传测试(断开 → 期间产帧 → 带旧游标重连 → 不重不漏, 含游标行是 message 行时的重发、游标 run 已结束时的补齐、刷新态 live 兜底三条分支); 游标优先级测试(同时带旧 from= 参数与新 Last-Event-ID,必须以头为准)。
  9. 用例全绿 + 竞态表逐条(用例清单以修订后的 7.9 文件为准)。阶段总验收。
  10. 冒烟前端(go:embed 单页):§6.1 启动编排 + §6.2 状态机(含本地队列: 409 session_busy 进队、run_terminal 补投、一键清空)。
  11. 文档同步:doc/ 按本文校正;§11 决议销账。
  12. inject 模式(用例 13,后置):失败可整块不做。

每一步 -race 全绿再走下一步。

独立增强(无阶段,各带启动条件):


11. 待定问题

编号沿用 v4(1/2/3 不重排)。状态按 v5 更新。

1. seq 关系 —— 已决(v5 加强;修订⑨ 更新):run 级 per-run、会话级 per-session 两个命名空间; message_queued 帧的 seq 与 run_started 帧的 seq 是 Enqueue 一个事务里相邻的两个数 (前者 NextSeq,后者再 NextSeq,§5.9)。inbox.seq 与 session_log.seq 同源——inbox 已删。

2. beginRunAtomic 失败后消息怎么办 —— 已决(修订⑨:机制不存在,销账)。 原选项 (a) 回滚留 inbox / (b) 重试 / (c) 兜底轮询 全部作废:Enqueue 与建 run 同一事务, 没有「入队后调度失败」的状态。残余的并发面(两个 Enqueue 争闸)由唯一索引仲裁 → 一 202 一 409,见 §7.10 第一条。

3. 队列上限 —— 作废(修订⑨)。 随 inbox 删除:队列在客户端、无界,背压问题登记为 §9.5 第 5 条。

4. Stop 不清收件箱 + 批量清空接口 —— 改判(修订⑨)。 收件箱不存在; 语义变为客户端行为:run_terminal(含 stop 终局)后本地队列自动补投, UI 须明示队列非空并给一键清空(清本地队列)。

5. Reconcile 补终局帧 —— 已决:补,且判死与 run_terminal 同事务(修订加强)。 v5 追加: 同时定稿遗留 final=0 行(outcome:"interrupted")——生成中的正文是真实数据, 必须以定稿形态留在日志里(§5.3)。修订再追加:判定从「遗留 running」改为「租约过期」 (多副本语义,§5.3、§7.8),编排层补帧合并进判死事务(Engine.Reconcile 逐场单事务), 原「先判死、后补帧」两步之间的崩溃缺帧窗口关闭。

6. 202 带响应体 —— 已决:{"sessionId","seq","messageId"}。 v5 追加:409 message_id_taken 的 detail 也带 seq(修订⑨:该错误随 inbox 删除)。懒创建修订再追加:sessionId 进响应体, 两种形态都回带——创建时是新铸的 id(§1.3)。

7. 各种 id 由谁生成 —— 已决。 资源身份(sessionId/runId)服务端铸造 (修订:sessionId 的铸造点是首条消息的 Enqueue 事务,§1.3); 幂等键(messageId)客户端生成(设备标识 clientId 随修订⑩ 删除,见问题 15)。三角约束与 B/C 案排除理由同 v4。 残留风险(跳过回放直接重发)照实登记;修订⑨ 后由前端约束 4 独扛(不再有 inbox 主键兜底)。

8. 会话是服务端资源 —— 已决。

9. 服务端回显 vs 本地 pending 气泡 —— 未决,倾向先服务端回显。 第 10 步(冒烟前端)之前定。

10. 修剪 —— 未决。 倾向 (b) 修剪 + 「落后太多请重建」的显式信号;两张日志表一起定。 v5 注意点:修剪 run_log 时 final=0 行只可能属于 running 的 run,不会被修剪窗口碰到—— 但要把这条写进修剪规则的自检。

11. inject 的「已被消费」表达 —— 未决,倾向加 message_injected 会话级帧。 随第 12 步定。

12. 多副本的进程内机制 —— v5 全部有 DB 兜底路径(关闭;修订补上恢复判定)。 闸(DB 唯一索引)、审批(DB 行 + 轮询兜底)同 v4;事件缓冲在 v5 里不存在了 (订阅读库 + 唤醒 + ≤1s 轮询,§5.2)——任何副本都能服务任何订阅。 修订补上审计漏掉的一项:恢复判定——Reconcile 从「启动即判死所有 running」(单实例语义, 多副本会误杀他副本的 run)改为 owner + 租约 + 条件更新 fencing(§5.3), 启动与周期 Reconcile 只判租约过期者,幂等。 唯一照实登记的洞:Archive 的跨副本缓存失效(§5.4),随多副本部署修。

13. 连接拓扑 —— v5 已改:每会话一条 SSE。 账号级传输(WS 或其他形态)随修订⑩ 后置、届时讨论(问题 15)。

14. adk.TurnLoop 换底座 —— 未决。 它原生有收件箱 / 合并窗口 / 抢占 / checkpoint-resume, 本方案在明知故犯地重造;理由是风险预算。记录备查,不启动。

15. 账号级订阅 / 跨客户端状态同步 —— 已决:后置安排,届时讨论定方案(修订⑩,2026-10-02 用户裁定)。 现在不做,但不删除。定位:载体(WS 账号级多路复用)是跨客户端、跨会话的状态同步通道 (A 建会话、B 的列表冒出来),不是连接数优化。届时讨论的任务就是定方案。

连带前置(届时一并设计,现在都不存在): ① 账号/身份——现 session 完全匿名,服务器无法判定两个客户端同属一个账号; ② 会话列表枚举——现无任何列表端点,session 只能靠 id 直接访问(§1.3); ③ 账号级事件源——session_log 是 per-session 的,「session 被创建」这个事实 目前没有任何地方记录(形状候选:session 表加 account 维度 + 账号级 seq; created_at / ULID 趋势递增可直接当游标)。

已从当前方案撤出的跨端设计(讨论的输入材料,届时一并重估、设计回来):

传输方案候选与关键代价(讨论素材,现在不定): (a) 账号级 WS 单连接多路复用——连接复用 + 双向 attach/detach;代价是失去 SSE 的 Last-Event-ID 免费续传(游标管理变客户端代码)与 curl 逐字节验收路径(§7.9 的方法论代价); (b) 账号级 SSE(每账号一条常驻流)与会话级 SSE 并存——续传免费、curl 可验收; 代价是每会话仍占一条流,多会话同屏时浏览器 6 连接上限依旧(§4.2); (c) 混合:WS 只做控制面(session 创建/删除广播 + attach 管理),会话数据仍走 SSE。 Feed 的 StreamFrame / Stream 抽象(§4.4)使订阅与传输解耦——这是既成结构事实, 届时加传输不需要动领域代码,但当前方案不为其预留任何设计(§5.8 前瞻说明已删)。

16. flush 节流参数(v5 新增)—— 未决,倾向 100ms / 2KB 双阈值起步。 第 7 步用真实模型流实测后定。约束:它是「崩溃尾巴长度」与「写库频率」的兑换率(§9.2 第 2 条)。

17. 租约参数(修订新增)—— 未决,倾向 TTL 15s / 续租 5s / 周期 Reconcile 15s 起步。 随多副本部署实测定。约束:TTL 是「判死延迟下限」与「僵尸写入窗口」的兑换率(§9.2 第 4 条); 续租间隔要远小于 TTL;周期扫描间隔 ≤ TTL,否则判死延迟失控。单副本阶段取默认值即可—— 进程重启走启动 Reconcile,不经过周期路径。

18. 会话懒创建(修订新增)—— 已决:首条消息铸会话。 POST /api/session 删除; 不带 sessionId 的 POST /api/message 在 Enqueue 事务内含铸 session 行(§1.3), 202 回带 id。空会话不存在,「新对话」是纯客户端动作。 已知缺口照实登记:首条消息超时重发可能铸两个会话、排两条同样的消息—— messageId 幂等是会话内的,重发时客户端手里还没有 sessionId。 去重闸(客户端一次性 requestId + registry 唯一索引)是后置补强,现在不做; 启动条件:非浏览器投递方出现之前。


12. 与外部产品及 v4 的对照

12.1 拓扑对照

Kimi:  1 条常驻控制流(WS,per 账号,多路复用所有会话)
      + 1 条数据流(流式 POST,per 一次 Chat 调用)
v4:    1 次短 POST + 1 条常驻会话流(SSE)+ N 条 run 流(SSE,一场一条)
v5:    1 次短 POST + 1 条常驻统一流(SSE,per 会话)

v5 比 v4 更接近 Kimi 的形态:「拿到 ID 却订阅不到」在 Kimi 里不发生(流绑定一次调用而非 runID), 在 v5 里同样不发生(一条流);v4 需要不变量 9 在传输层治的病,两边都没有。 差异只剩:Kimi 的控制面是账号级(WS),v5 是会话级(SSE)——账号级是后置项(§11 问题 15)。

12.2 帧协议对照(Kimi 抓包 vs v5)

维度 Kimi 增量协议 v5
帧的含义 「某字段变成了这个值」(op:set/append + mask) 「发生了一件事」+ 生成中行同 rseq 重推
流式正文 append 增量,O(n) 快照重推,O(n²)(KB 级可忽略;增强项已留位)
「生成中」的存储 message 实体 GENERATING 起就在 final=0 行从生成起就在——同一判断
崩溃窗口 不存在 不存在(≤100ms 未推未存的尾巴,§5.9)
保活 heartbeat 带 offset heartbeat 带 seq(§4.3)
终止 done:{} 显式终止符 run 终局帧 + 会话级 run_terminal;流本身不终止(会话无终局)

v4 里「阶段二按增量协议重写数据面」的判断,其核心收益(崩溃窗口、Partial 拆除)已被 v5 提前兑现。 增量协议剩下的独有收益是 O(n) 流量与实体树的表达力,两者都降级为按需增强(§10)。

12.3 v4 的教训,逐条核销

v4 §12.3 说「Partial/sealed 是建模产物」——判断正确,但 v4 的选择是先建再拆。 v5 的立场:承认是产物的机制就不该建。同一个判断用到三个别处(修订⑨ 加一个):

一条可迁移的检视方法:当文档里出现「这是临时形态,阶段 N 会拆掉」时, 先问「现在不建的代价是什么」。v4 里这个问题的答案是「改动面小、最快跑通用例」—— 但拆开看,Partial 机制本身是 v4 数据面最贵的部分,「先顶着」顶住的恰是最贵的东西。


13. 附录:外部来源、错判纪律、多副本审计

13.1 借鉴纪律(沿用 v4 §13.3,一字不改)

在参考实现里 grep「挂在旧协议旁边的新端点」——它们是演进的足迹; 找到「遗留」后问「它因为什么约束不得不存在」;那个约束在你这里成立则是未来的债, 不成立则是纯粹的包袱——两种情况下「照学」都是错的。 (WeKnora 的 steer 端点与 20 行外的 409 逻辑语义矛盾,矛盾本身就是信号。)

这条纪律也适用于框架:adk.TurnLoop 原生就是收件箱 + 调度器, 本方案在重造它,且是明知故犯(§11 问题 14)——理由写在这里,比假装它不存在诚实。

13.2 承重论断的前提(沿用 v4 §13.4,一字不改)

承重论断的前提只能来自代码、配置、用户的原话——不能来自文档注释、记忆、印象; 已作废的实现连代码都不算。v5 的四个改动同样遵守:每一处都只引 v4 文档里 它自己登记的承认(§9.2 的窗口、§12.3 的建模产物、§13.5 的第三处断点),不引旧实现。

13.5 多副本审计(v5 更新)

目标栈:Go + Gin + PostgreSQL/pgvector + Redis(asynq) + Vue。SQLite 是测试替身。 逐项判定:

机制 v4 状态 v5 状态
闸 DB 部分唯一索引 ✅ 不变 ✅
审批 DB 行 + 本地通知 + 轮询兜底 ✅ 不变 ✅
事件缓冲 ❌ 仅剩的断点:订阅只在拥有 run 的副本上能拿实时帧 ✅ 消除:订阅读库 + 唤醒 + ≤1s 轮询,任何副本可服务任何订阅(§5.2)。唤醒表是纯加速路径
Archive 缓存 ⚠️ 跨副本失效的洞(已登记) 不变,仍登记(§5.4)。修法:失效广播或每场 run 冷装
Stop 的即时性 本地 cancel + stop_requested 轮询收敛 ✅ 不变 ✅
Enqueue 两段写(单副本下的事故容忍) ✅ 单事务(修订⑨ 加强):投递 + 闸检查 + 建 run 一笔事务;忙 = 整体回滚 409 session_busy,失败路径对称(§5.9);并发投递由唯一索引仲裁
会话创建 v4 是独立端点(POST /api/session) ✅ 懒创建:session 行在 Enqueue 事务内铸造,INSERT 新行与既有会话的行锁天然并行,多副本下无竞态(§1.3)
inbox 队列 DB 表 + 调度器 ✅ 修订⑨ 删除:客户端本地队列。多副本语义反而更简单——队列状态不存在副本间一致性问题;代价见 §9.5
统一流 / Feed —(v4 是两条 SSE + 内存缓冲) Feed 只读两张表 + 唤醒信号;无状态,哪个副本都能跑 Attach ✅
恢复判定(Reconcile) 启动时把所有 running 标 failed(与 v5 原文相同) ✅ 修订:owner + 租约——只判租约过期的 run,他副本健康执行的 run 不动;fencing = run 级写全部以 status='running' 为条件更新(§5.3);启动 + 周期 Reconcile,幂等
会话写串行化 靠单副本进程内时序 ✅ 修订:session 行锁(所有会话级写事务的第一条语句)+ 五张子表外键(§5.9、§5.14)。FOR UPDATE 是 PostgreSQL 语义;SQLite 替身只验逻辑、不验并发

审计纪律照实登记:本表在 v5 原文里没有「恢复判定」这一行——评审发现「启动即判死所有 running」与下文结论直接矛盾后才补上。审计表漏行本身就是教训:逐机制列表时, 「启动/恢复路径」要和「稳态路径」分开列,它不走稳态的不变量。

结论:v4 里「多副本不推翻本方案」是审计出来的;v5 里「任何副本能等价服务任何请求」 是设计的直接推论——所有跨副本可见性靠表,所有进程内状态只影响快慢不影响对错。 修订后这个结论覆盖恢复路径:执行者死亡由租约判定,与「哪个副本重启」无关。 上线 Postgres 时的必做项:唤醒/轮询兜底间隔与租约参数(§11 问题 17)按负载调参、 Archive 缓存的失效策略;行锁与外键的并发正确性在 SQLite 替身上不可证,以 Postgres 验收为准。

窗口仍然是「未上线」:能重写入口的真正理由是没有生产流量。这不是持久优势, 是一个正在关闭的窗口。