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.9finishAtomic——终局帧 + 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返回 409session_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, 直到定稿。 具体规则:
- 模型开始输出正文时,drive 调
BeginMessage:INSERT 一行kind='message'、final=0, 此刻它就拿到了真实的、已提交的 seq——没有预留号,号就是库的号; - 输出过程中,drive 按节流(100ms 或 2KB 增量,§5.9)调
UpdateMessage:UPDATE 同一行的 正文与updated时间戳。每次 UPDATE 提交后才唤醒订阅者——「先落库再推」从纪律变成结构; - 流结束时
FinalizeMessage:最后一次 UPDATE,final=1。定稿不是一次特殊写入,是普通更新的最后一笔; - 流出失败 / 半截被取代:
FinalizeMessage的 outcome 参数记drop/discard, 行保留(不留 seq 空洞),UI 据此渲染「输出中断」或隐藏。
约束(应用层强制,建表注释里也写明):final=0 只允许出现在 kind='message' 的行上; 只有 final=0 的行可以被 UPDATE;UPDATE 只许改正文、updated、final,不许改 seq。
这个例外买到的东西:
- v4 §9.2 的窗口现在关闭,不是等阶段二——崩在输出中途,已落库的正文一个字不少,
Reconcile把遗留的final=0行定稿为interrupted(§5.3),读者看到的是「写到哪儿是哪儿」; - 重连的读者立刻看到当前已生成的文本(读库即得),而不是像 v4 那样在 seal 之前什么都看不到;
- 订阅不再需要内存事件缓冲(§5.2),多副本下任何副本都能服务任何订阅(§13.5);
ErrSealConflict、dropPartialTail、预留号、防忙等——整套机制不存在了。
付出的代价(照实登记,§9 还会算一次):run_log 的写规则不再是纯粹的「只追加」。 这是一个有界的例外(一类行、有限字段、单次生命周期内),换来上面四条。判断依据是: 追加式纯净的价值在于「写下的历史不可篡改」,而生成中的行还不是历史——它是进行中的现在, 对它 UPDATE 不篡改任何已定稿的事实。
1.2 为什么 inbox 与 session_log 是两张表 —— 本节作废(修订⑨)
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)。 三条理由(懒创建下仍然全部成立):
session_log的重放起点不变,且更硬了。 「从 0 开始重放」的起点是登记表里那一行; 懒创建下每个登记的会话第一帧必是message_queued(seq 从 1 起)——创建事实与第一条事实 同生同死,「刚建(空日志)」与「查无此会话」的歧义被结构性消除, 也无需为「创建」单开一种除创建者自己重放以外没有消费者的帧类型。- 目标是多副本部署(§13.5)。会话身份要在副本之间可路由、可归属; 配额、回收、会话列表、账号级订阅全都以登记行为前提。不变。
重启续答(§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 推论:哪些东西不能互相重建
- 不能从
run_log重建模型上下文——压缩是有意的信息销毁。 - 不能从
session_log重建 run 内容——它只记「发生了什么」,不记「产出了什么」。 - 不能从
run_archive重建历史——它会被压缩破坏性覆盖。
三张辅助表不算「持久状态」: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 | |
| 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
谁持有谁:
Server持有单例Engine(Engine 引用全部存储组件的同一份实例)Engine持有Registry/SessionLog/RunLog/Archive/Approvals/Feedagent/runner+ 一张纯本地的runCtxs map[runID]context.CancelFunc(即时取消的加速路径,不是真源、不是闸,§5.9)
RunLog/SessionLog持有存储连接 + 订阅唤醒表(map[id]chan struct{}一族, 只承载「醒来」信号,不承载内容——内容一律读库,§5.2)Archive持有存储连接 + 按会话键控的模型消息缓存- run 期间的全部临时状态(cancel、stopped、压缩暂存、对账用的 messageIDs、正文 flush 缓冲) 在
runState里,由 drive goroutine 持有,run 结束即消亡
命名修正(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」这个拓扑:
- 订阅竞态:runID 可见早于可订阅 → 404(v4 失效场景 E),靠不变量 9 治;
- 前端编排:
run_started到达 → 新挂一条流 → 终局帧到达 → 关流。每个客户端一套挂载状态机; - 续传起点不对称:run 级从 0、会话级从 lastSeq,两套规则,v4 用了两处篇幅解释为什么不是 bug;
- 连接坑位:每会话 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}
要点:
- 同一
rseq的重复帧 = 原位更新(生成中的正文)。final:false→ 前端原位替换气泡内容;final:true→ 定稿。这与 v4 的 Partial 帧线上形状几乎一样,但每一帧背后都是库里真实的一行, 不是内存预留号。 - run 级游标的重放含游标行本身——当且仅当它是 message 行。 message 行是唯一可变的行 (§1.1:只有
final=0的 message 行允许 UPDATE):断线前看到的final:false,可能在断开期间 被续写、被定稿(final:true),或被 Reconcile 定稿为interrupted。只回放rseq > runFrom就会恰好丢掉这次定稿(用例 5 正是这个场景)。重发游标行让前端按既有的「同 rseq 原位替换」 处理,行没变则重发无害,客户端零新分支。非 message 行写入即定稿、永不改变, 客户端见过的就是库里的,无需重发。 - SSE
id:字段承载双游标,格式<sessionSeq>:<runId>:<rseq>:每帧都带上 「此刻两个命名空间各走到哪」。浏览器 EventSource 断线自动重连时会带上Last-Event-ID, 服务端据此续传——客户端一行重连代码都不用写(§6.1)。 - heartbeat:
id: <sessionSeq>::+data: {"kind":"heartbeat","seq":<sessionSeq>},15 秒一拍。 不入库,只是线上的帧。作用有二:防止代理掐死静默连接;让客户端区分「服务端卡住」与「在等 LLM」, 并顺手刷新游标。 - 游标优先级:
Last-Event-ID优先于显式参数。 显式参数from=/runFrom=只在请求 没有携带Last-Event-ID时生效(curl 手打、整页刷新后的首次挂载)。反过来写是错的: 浏览器自动重连会重新请求同一个 URL——from=还是页面加载时刻的旧值——同时自动带上Last-Event-ID;若参数优先,旧游标覆盖新游标,页面加载以来的帧全部重播(§6.1 的承诺随之破产)。
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 的全部复杂度在这里,四条——前三条是追赶,第四条是实时):
- 先补游标 run:
lastRunID非空 → 同步回放该 run 已落库的内容(rseq > runFrom, 游标行按 §4.3 的规则随附——它是 message 行则重发)——即使它此刻已结束 (已结束则回放含终局帧)。它的run_started在from之前,规则 2 的遍历永远不会遇到它; 不单独补这一步,用例 5/11 里「断线期间的剩余内容」就无声丢失。 回放完若它仍是 live,挂好它的订阅,作为规则 4 的 run 订阅。 - 追赶会话帧:取
sessionLog.Since(from),按序遍历:普通会话帧直接发; 遇到run_started(r)→ 发出它,然后同步回放 r 已落库的内容帧 (从 0——能在这一步遇到 r 的run_started,说明客户端没见过 r 的任何帧; r 已结束则回放含终局帧);遇到run_terminal(r)→ 若 r 的内容刚回放完(规则 1 或本规则)则直接发。 - live run 兜底:切实时之前查
LiveRunID:存在且本连接还没回放过它的内容 (典型:整页刷新,lastRunID为空、from=lastSeq,它的run_started在from之前) → 从 0 回放它已落库的内容(含生成中行的当前文本),挂好订阅。这是 §7.7 刷新场景的支点。 - 实时阶段与唯一的排序规则:同时持有会话订阅与当前 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 完全相同,此处只列契约要点:
ModelMessages/AddRun/InvalidateCache:按 sessionID 键控的模型消息缓存, 冷热路径、LRU 逐出不变;Stage/RevertStage/CommitPatch+CompactState:压缩补偿事务,暂存态住runState, 寿命 = 一场 run,库只在finishAtomic事务里写补丁(§5.9);BindMemory:per-run 的compact.Memory适配器;Notify(写 compact 帧)/WriteRAG/SearchRAG。
已登记的洞(不变):跨副本的缓存失效。单副本下闸的串行化保证正确; 多副本下副本 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(两种形态都带)
}服务端失败只有两种,都是整体回滚(修订⑨ 后更对称了):
- 409
session_busy:闸检查(或并发撞唯一索引)——事务什么都没写,消息没进库。 客户端本地排队,run_terminal后带同一个messageId补投,安全; - 500:存储故障——整体回滚,客户端带同一个
messageId重发,干净地重新开跑; - 提交成功但响应丢失 → 客户端重发:若还在忙(run 在跑)→ 撞 409
session_busy, 客户端按约束 4 回放追平后撤销重发;若已落幕 → 作为新消息再答一次(同一句话被回答两次)。 修订⑨:没有 inbox 主键仲裁兜底,唯一防线是前端约束 4(先回放追平、再决定重发,§6.3), 窗口从「inbox 存活期」扩成整场 run,§9.5 照实登记。
两种失败都不产生不一致。原 v4/v5 的「Append 失败不回滚 inbox」中间态、 「beginRunAtomic 失败消息搁浅」(§11 问题 2)——机制整体不存在,问题连根删掉。
frame 必然比 202 先到:run_started 帧、start 帧与所有库行在同一个事务里提交, drive goroutine 在 Commit 之后启动——它们的广播只会发生在 202 响应到达浏览器之前。 前端按 messageId 对齐(§6.3 约束 2),不依赖顺序。
—— 已删除(修订⑨):调度回路随 inbox 一起拆除。 「入队但不调度」的状态不存在了:Enqueue 提交 = 开跑;run 之间没有「纳秒级调度窗口」, 下一条消息由客户端在 trySchedule 与 beginRunAtomicrun_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 必须遵守的约束(修订⑨ 后四条)
- 发送按钮永远可用。 不存在「busy」——忙时 POST 返回 409
session_busy, 进本地队列、run_terminal后自动补投。停止键按liveRunId显隐,与发送键无关。 - 服务端回显,不要本地回显。 用户气泡由
message_queued帧画出(帧带全文)。 POST 失败把输入框内容还回去(409session_busy除外——它进本地队列)。 换来的是「帧与视图永远一致」:本端任何时刻的视图都能从流回放重建, 代价是一个 RTT 的延迟感。 - 前端不保存任何服务端不知道的状态——本地队列除外(修订⑨,它是服务端明确 让渡给客户端的职责)。本地只存
sessionId/ 队列。 重连靠 Last-Event-ID(自动重连必带它,服务端以它为准——URL 里的from=只在首次挂载生效,§4.3), 整页刷新靠 Snapshot +from=lastSeq。 还没有 sessionId 时(未发首条消息)不挂流、不取快照——空会话没有可对齐的世界(§1.3 懒创建)。 - 重发必须先回放、且复用同一个
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)
sessionLog.AppendInTx(run_terminal),同事务提交(v5 原文里 run_terminal 由编排层事后补, 崩溃在两者之间同样缺帧;现在要么没判死、要么帧与状态同生)。②——随 inbox 删除。 除启动外,运行期每 15s 周期 Reconcile(§11 问题 17)——多副本下执行者死亡不能等某个副本重启才发现; 判定幂等(条件 UPDATE 只赢一次),多副本并发扫也安全。sessionLog.Reconcile找非空 inbox → ③ 逐个trySchedule
多副本语义: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 新增的四个代价
run_log的追加纯净性有一个例外(§1.1)。生成中的 message 行允许原位 UPDATE。 这是为关闭崩溃窗口付的语义税:写规则从「只追加」变成「追加 + 一类行的有限更新」。 有界(一类行、三个字段、定稿即止),但审计与回放工具必须知道这个例外存在。- 每次 flush 是一次 DB UPDATE(100ms / 2KB 节流)。一场 run 几十秒正文输出 ≈ 几百次 UPDATE, SQLite 与 Postgres 都无压力;但它意味着「输出速率」与「写库速率」挂钩, 节流参数(§11 问题 16)选得激进会放大写量,选得保守会放大崩溃尾巴。
- Feed 有一条排序规则要维护(run_terminal 压到对应订阅排空后)。 这是「一条流」的代价集中点:v4 里这个顺序由「两条连接各自的时序」自然形成 (且不被保证),v5 把它变成显式规则 + 显式测试(§7.10 第七行)。
- 执行租约的写量与调参面(修订新增,§5.3)。每场活跃 run 每 5s 一次续租 UPDATE、 每副本每 15s 一次过期扫描——量级可忽略;但 TTL / 续租间隔 / 扫描间隔成为新的调参面 (§11 问题 17),且「判死延迟」有了下限:执行者死亡最快也要 TTL 之后才被发现。
9.3 照旧登记的取舍(与 v4 相同,压缩为一屏)
- 线上推全文快照,不推增量(同一 rseq 重推整句,O(n²) 字节)。消息量级 KB,可忽略。 若要 O(n):库里就是累积全文,差分可算,
runFrame加个append字段即可——列为增强,不设阶段(§10)。 - 服务端回显的一个 RTT 延迟感(§6.3 约束 2)。拿即时感换「帧与视图永远一致」: 气泡由服务端帧画出,本端任何时刻的视图都能从流回放重建。 若实测明显,可加 pending 气泡(客户端 messageId 先画、帧按同 ID 对齐)——§11 问题 9。
停止后系统自己开跑新一轮(修订⑨ 改:客户端行为)——run_terminal后本地队列 自动补投,UI 须明示队列非空,给一键清空(清本地队列)。- 重发跳过回放会让同一句话被回答两次(§6.3 约束 4)。修订⑨ 后这是唯一的仲裁: 没有 inbox 主键兜底,窗口 = 整场 run 时长。永久映射表(Stripe 式)成本收益不成比例,先不做。
(修订⑨:机制不存在,§11 问题 2 销账)。beginRunAtomic失败的消息靠重试策略捞起- Archive 跨副本缓存失效的洞(§5.4,随多副本部署修)。
9.5 修订⑨ 的代价:inbox 删除与投递语义反转(照实登记五条)
换来的是:一张表、两个端点、三条竞态测试、整个调度回路(trySchedule/beginRunAtomic/ 不变量 8/§11 问题 2)消失,Enqueue 与建 run 合一事务。代价:
- 队列逻辑每个客户端各自实现一遍。 忙时各 409、各排各的、互不知道对方—— 跨端同步整体后置(修订⑩),「B 端看到 A 端排队中」届时随方案一并回来。 「发送键永远可用」的 UX 由前端本地队列保住,但它是前端组件,不是服务端事实。 后置增强:队列想要服务端可见/跨端一致时,inbox 以某种形态复活(届时合并语义一并重估)。
- 合并语义删除:一轮 run 只消费一条 message。run 期间连发三条 = 三轮 run 逐条回答。 以后要合并:客户端聚合文本(队首 messageId)或 API 收 batch,二选一,现在不做。
- 幂等兜底收窄:同
messageId重发,忙时撞 409(消息没落库,安全);但「已提交而 客户端没收到响应」的重复回答窗口从「inbox 存活期」扩成整场 run 时长, 唯一防线是前端约束 4(先回放追平、再决定重发)。 - 队列随客户端生死:浏览器关闭/刷新,没发出去的排队消息即丢;服务端重启也没有 待办可捞(原 §7.8 的 inbox 续答分支删除)。已 202 的不受影响(不变量 2)。
- 服务端失去背压:
maxQueueDepth422 删除,客户端队列无界。 现阶段可接受;真出现「排到几十条」的使用方式时再以服务端可见队列的形式回来。
9.4 v4 有、v5 没有的代价(销账记录)
进程崩在 seal 之前丢整条助手正文→ §1.1,正文从生成起落库;每会话 2 条 SSE,多标签页撞浏览器连接上限→ §4,一条流;Partial 预留号 / AppendSealed / ErrSealConflict / dropPartialTail / 防忙等→ 机制不存在;「两条流续传起点不对称」的前端规则→ 一条流一对游标;Enqueue 里「消息已入收件箱但没广播」的中间态→ 一个事务;事件缓冲是多副本仅剩的进程内断点→ 订阅读库 + 轮询兜底,任何副本可服务任何订阅(§13.5);inbox 表 / Cancel / ClearInbox / Drain / 合并窗口 / maxQueueDepth→ 修订⑨ 全删,客户端本地队列 + 409session_busy(§9.5);trySchedule / beginRunAtomic / 不变量 8 的搁浅竞态 / §11 问题 2→ 修订⑨:Enqueue 与建 run 合一事务,竞态失去发生位置。
10. 实施顺序
v5 不分「阶段一 / 阶段二」。 v4 分阶段的全部理由是「Partial 机制先顶着、增量协议以后重写」; v5 里那个「以后」的主要内容已经消失(§9.4),剩下的都是独立增强,各有启动条件,不构成阶段。
实施方式是重写,不是重构。顺序原则不变:先 API 契约、再存储、最后前端; 执行按 tmp/v5-plan/todos.md 的用例 loop 排(契约 → 数据需求 → 存储 → 实现)。
- 模块骨架 + 搬能力包:
go.mod、cmd/yktako/、internal/tools、guard、compact、mediaoffload、msgtext、adkrun、config。门槛:go build ./...与搬入包单测全绿。 - 领域类型与接口先行:
Event/StoredEvent/MsgOutcome/Classify/Subscription、SessionEvent一族、StreamFrame/Stream/Feed、五个存储接口、DTO 与错误体。 门槛:build 过;Classify单测穷举。 - API 契约落地(内存假实现):路由表(§5.12)、
errorMapper、sse.go的Stream()(含id:双游标与 heartbeat)、各 handler。门槛:curl 手打用例 1、9,逐字节对。 - RunLog 的 SQLite 实现:建表(含
owner/lease_until与外键)、BeginRunInTx、Append、BeginMessage/UpdateMessage/FinalizeMessage、FinishInTx、ListExpiredRunning/FailInTx(条件 UPDATE 判死 + 补终局帧 + 定稿孤行)、Subscribe/Since、LiveRunID、HistoryPage。 门槛:生成中行「更新 → 定稿 → 再写拒」单测;final=0约束单测; FailInTx 孤行定稿与幂等(重复判死只赢一次)单测;fencing(判死后写全拒)单测。 - Archive:与 v4 相同。门槛:stage → revert 逐条相同。
- Registry + SessionLog(修订⑨:无 Inbox):两张表 +
session_seq;SessionFeed三方法;Registry.CreateInTx(仅 Enqueue 内部调用,§1.3 懒创建)。 门槛:seq 不跳号不重号。 - Engine 真实现:
Enqueue单事务(§5.9,修订⑨:含闸检查 + 建 run—— 准入/懒创建 →LiveRunID查闸(忙 → 409session_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)可行。 - Feed 扇入器:追赶(游标 run 补齐 + 会话帧遍历 + live 兜底)+ 实时 + 排序规则(§4.4 四条)。 门槛:§7.10 第七、八行两条竞态测试; Last-Event-ID 续传测试(断开 → 期间产帧 → 带旧游标重连 → 不重不漏, 含游标行是 message 行时的重发、游标 run 已结束时的补齐、刷新态 live 兜底三条分支); 游标优先级测试(同时带旧
from=参数与新Last-Event-ID,必须以头为准)。 - 用例全绿 + 竞态表逐条(用例清单以修订后的 7.9 文件为准)。阶段总验收。
- 冒烟前端(go:embed 单页):§6.1 启动编排 + §6.2 状态机(含本地队列: 409
session_busy进队、run_terminal补投、一键清空)。 - 文档同步:
doc/按本文校正;§11 决议销账。 - inject 模式(用例 13,后置):失败可整块不做。
每一步 -race 全绿再走下一步。
独立增强(无阶段,各带启动条件):
- 增量 append 帧(O(n) 线上流量)——启动条件:实测正文推送流量成为问题。 库里已是累积全文,只加帧字段,不动存储。
- 实体树协议(message → block,富内容块、chat.name 类元数据)——启动条件: 出现「一帧放不下的富内容」需求。
- 跨客户端状态同步(账号级;WS 是候选之一,方案届时讨论)——后置安排,不删除(修订⑩)。 范围:会话列表同步(A 建会话、B 可见)、session 创建/删除广播等跨会话事实。 启动条件:账号体系出现;届时先讨论定方案(候选与关键代价登记在 §11 问题 15)。
SessionFeed分层(§5.8)与传输无关的帧信封已就位,任一候选落地都不改领域代码。 - MQ 投递 / IM / cron 入口——启动条件:多副本上线且有非浏览器投递方。
- 服务端队列(inbox 复活)/ 合并语义(修订⑨ 登记,§9.5 第 1、2 条)——启动条件: 队列需要跨端可见,或实测「逐条回答连发消息」体验不可接受。届时合并语义一并重估。
adk.TurnLoop换底座评估——启动条件:上述全部稳定后。
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 已删。inbox.seq 与 session_log.seq 同源
2. —— 已决(修订⑨:机制不存在,销账)。 原选项 (a) 回滚留 inbox / (b) 重试 / (c) 兜底轮询 全部作废:Enqueue 与建 run 同一事务, 没有「入队后调度失败」的状态。残余的并发面(两个 Enqueue 争闸)由唯一索引仲裁 → 一 202 一 409,见 §7.10 第一条。beginRunAtomic 失败后消息怎么办
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 (修订⑨:该错误随 inbox 删除)。懒创建修订再追加:message_id_taken 的 detail 也带 seqsessionId 进响应体, 两种形态都回带——创建时是新铸的 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 趋势递增可直接当游标)。
已从当前方案撤出的跨端设计(讨论的输入材料,届时一并重估、设计回来):
clientId(原 §6.4,设备标识,帧上的跨端归属字段);- 多端订阅的设计保证与验收(原 7.9 用例 4:多标签页/多设备同步);
- 原 §8 场景 C「另一端不知道有新一轮开始」的保证与测试;
- 原 §4.1 3/4/5 行跨端场景的保证表述。
传输方案候选与关键代价(讨论素材,现在不定): (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 的立场:承认是产物的机制就不该建。同一个判断用到三个别处(修订⑨ 加一个):
- 「run 级流要先知道 runID」也是拓扑产物——v5 不建那条流;
- 「Enqueue 两段写的事故容忍」是「没把共享计数器看出来」的产物——v5 一个事务;
- 「忙时投递要落库排队」是「inbox 值得一张表」的产物(修订⑨)——用户裁定不建: 队列职责移交客户端,服务端只留一个诚实的 409。代价照实登记(§9.5), 这比假装「服务端队列没有成本」诚实。
一条可迁移的检视方法:当文档里出现「这是临时形态,阶段 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) |
| 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 验收为准。
窗口仍然是「未上线」:能重写入口的真正理由是没有生产流量。这不是持久优势, 是一个正在关闭的窗口。