19 · 运行引擎架构 v4
⚠️ 本文已被 v5 取代(
doc/19-运行引擎架构-v5.md),保留仅作演进记录。 v5 改四处:流式正文从生成起落库(Partial/sealed 不建了)、两条 SSE 并为一条统一流 (run 级端点删除,失效场景 D/E 结构性消除)、Enqueue 两段写合一事务、订阅改读库式 (内存事件缓冲取消)。改动清单与动机见 v5 §0。
这是文档版本,不是软件版本。 它描述一个完整的设计方案。§10 的「阶段」是方案内的实施顺序 (先做什么、后做什么),不是软件发布阶段。
本文自包含。 不依赖任何先前版本的方案文档,也不以旧实现的代码为依据。 旧实现(run 级协议、用 409 表示「会话忙」、单页前端)已作废;本文提到它时只作 「历史诊断」,不作为设计约束。§13 记录了设计的外部来源与一次错判的教训。
性质:设计方案,尚未实施。实施方式是重写,不是重构——新 module 从零起步, 与运行引擎无关的能力包(工具集、guard、压缩、媒体落盘、eino 封装)作为既有资产搬入。
术语:message 指用户投递的一条输入;run 指一次执行;一场 run 可能消费多条 message。 会话(session) 是服务端登记过的资源,有身份、有创建事实。
诊断依据:见《会话级并发:从 409 到收件箱》访谈稿(含外部产品实测与帧级抓包)。
1. 存储:三真源 + 一张登记表 + 一个待办队列
系统里有五份持久状态。它们的写规则、读者、生命周期都不同,不是冗余,是五种不同的东西。
run_log |
run_archive |
session_log |
session |
inbox |
|
|---|---|---|---|---|---|
| 角色 | 真源:run 级事实 | 真源:模型视图 | 真源:会话级事实 | 登记表:会话身份 | 待办队列 |
| 粒度 | run | run | 会话 | 会话 | 会话 |
| 回答的问题 | 这场 run 发生过什么 | 下一轮该给模型看什么 | 这个会话发生过什么 | 这个会话存不存在、何时建的 | 还有哪些话没被回答 |
| 写规则 | 只追加,永不改 | 可改写(压缩是破坏性覆盖) | 只追加,永不改 | 只插入 / 只删除,不改 | 可变:行会被消费或删除 |
| 读者 | 人 / UI / 回放 / 对账 | LLM | UI / 多客户端同步 | 所有写操作的准入检查 | 调度器 |
| seq 命名空间 | per-run | — | per-session | — | per-session(仅排序用) |
| 生命 | 永久 | 永久 | 永久 | 永久(显式删除为止) | 短暂:消费即删 |
1.1 为什么 inbox 与 session_log 是两张表
因为它们的写规则相反。session_log 是事实(只追加,回答「发生过什么」), inbox 是状态(可变,回答「现在还有什么没做」)。硬合成一张就得在事实表上做 UPDATE (标记 consumed),破坏追加式纯净性;或者用「追加一条 consumed 事件、读时做差集」, 把简单查询变成折叠计算。分成两张,各自的语义都干净——这与 run_log / run_archive 分开的理由是同一个。
inbox 被消费后,「m_1 曾排队过」这个事实不会丢:它在 session_log 里有 message_queued 帧, 在 run_started 帧的 messageIds 里也有一份。所以断线重连的客户端能完整重建时间线。
1.2 为什么需要 session 登记表
会话身份由服务端铸造(POST /api/session),不由客户端生成。理由是三条,都来自本方案自己的前提:
session_log的lastSeq:0必须有出处。 它是第三真源,「从 0 开始重放」这句话要有起点; 起点就是登记表里那一行(session_id+created_at)。若sessionId由客户端生成, 服务端面对一个空日志就分不清「会话刚建、还没有帧」和「查无此会话」——seq 0 只由客户端报的 一个字符串召唤出来,背后没有创建事实兜底。 创建事实不写成session_log的帧——那会多出一个除创建者自己重放以外没有任何消费者的帧类型。- 目标是多副本部署(§13.5)。会话身份要在副本之间可路由、可归属。客户端生成的 UUID 唯一性没问题,但没有创建事实——配额、回收、会话列表、账号级订阅全都无从下手。
- 重启续答(§7.9 用例 6)依赖它。 进程重启后要判断哪些
inbox行值得捞起来重跑, 前提是「这个会话是登记过的对象」,而不是任意字符串都能开一个收件箱。
准入规则:任何带 sessionId 的写操作,先查登记表;未登记一律 404,不隐式创建。 这条规则堵住的洞是「投递接口对一个不存在的服务端实体回 202」——那等于给一个不存在的收件箱开收据。
messageId与clientId仍然由客户端生成,这与上一条不矛盾,因为两者性质不同: 会话 id 是资源身份——服务端必须存在这么一个对象,所以有登记表和准入检查;messageId是绑草稿的幂等键,它绑的是「用户的这一句话」而不是「这一次 HTTP 请求」, 所以超时后重发同一句要用同一个 id,由 inbox 的主键仲裁(§5.7)。 它同时是回放对齐键:重连后session_log重放出message_queued(同 id), 客户端据此知道那句已经落地、不必重发(§6.3 约束 6)——这一层是永久的, 补上了 inbox 主键只在「消息还没被 Drain」期间有效的那个窗口。 把资源身份和幂等键混为一谈,就会同时失去准入检查和重发安全。它的形状是 UUID,不承担可读性。 要好看的场合(日志里「第几条」、UI 上的序号) 用
seq(inbox.seq/session_log.seq),排序也一律走seq,messageId从不参与排序。 曾考虑改由服务端铸造以换取漂亮形状,代价是客户端在发出请求前不知道 id、重发无法被认出; 三个候选的完整排除过程见 §11 问题 7。
1.3 推论:哪些东西不能互相重建
- 不能从
run_log重建模型上下文——压缩是有意的信息销毁。 - 不能从
session_log重建 run 内容——它只记「发生了什么」,不记「产出了什么」。 - 不能从
run_archive重建历史——它会被压缩破坏性覆盖。 - 不能从
inbox重建时间线——消费即删。
每一份都只有它能回答的那个问题。
另有三张辅助表不算「持久状态」,因为它们不回答任何新问题: session_seq(会话级 seq 的计数器,让 inbox.seq 与 session_log.seq 同源,§5.7、§11 问题 1)、 compact_rag(被压缩换掉的原文,只写只检索,是 run_archive 破坏性覆盖的副产物,§5.4) 与 approval(审批决策行,§5.11——决策事实在 run_log 的 approval_result 帧里也有, 行只是让它变成可查询的当前态,跨副本的等待方靠它收敛)。 建表汇总(§5.14)里一共 8 张表 = 5 份持久状态 + 3 张辅助表 (第三张辅助表是 approval:审批决策的行,§5.11。它也不是「新的持久状态」—— 决策这个事实在 run_log 的 approval_result 帧里同样有,行只是让等待方能跨副本读到它)。
2. 不变量
九条。每条都是承重的:违反它会得到一个具体的、可复现的错误行为,而不只是「不优雅」。
| # | 不变量 |
|---|---|
| 1 | 会话是服务端登记的资源。 未登记的 sessionId 一律 404,不隐式创建(§1.2)。 |
| 2 | run 的命不属于任何连接。 runCtx 是进程 ctx 的子 ctx;浏览器关掉、刷新、断网,run 照跑、帧照落库。只有 Stop 与 Delete 能取消它。 |
| 3 | 库操作一律用进程 ctx,绝不用请求 ctx。 请求 ctx 随连接断开而取消,用它写库等于「客户端一刷新就写一半」。 |
| 4 | 先落库,再推浏览器,再回 2xx。 用户打的字比输出帧更贵重——丢一帧输出可以从库补,丢一条用户输入无从恢复。 |
| 5 | seq 是唯一的续传坐标。 有两个独立的 seq 命名空间(run 级、会话级),各自续传,互不换算。 |
| 6 | 终局唯一。 Finish 在一个事务里写终局帧 + 改 status,之后 Append 直接拒绝。 |
| 7 | 投递永不因状态冲突失败。 Enqueue 只可能因存储故障(500)或输入本身需要被重新考虑(队列过深,422)而失败,绝不会因为「会话正忙」被拒。忙是调度器的内部事实,不是 API 层错误。 |
| 8 | 放闸与调度必须原子。 run 收尾时,「释放占用」与「检查 inbox 是否非空」必须在同一个临界区里完成。 |
| 9 | runID 只在事务提交后才对外可见。 发布 runID 的那一帧(run_started)与 run 的档案行、start 帧在同一个事务里写入。 |
2.1 不变量 8 为什么是硬要求
如果放闸和查收件箱之间有窗口,那么正好落在窗口里到达的消息会永久搁浅—— 它入队时看到闸是 occupied(所以没触发调度),而收尾时查收件箱又发生在它入队之前。 除非下一条消息到来,它永远不会被执行。这是经典的「signal lost between unlock and wait」竞态, 只能靠原子性解决。伪代码见 §5.9。
2.2 不变量 9 消灭了一个窄竞态
如果运行标记(「这个会话有一场 run 在跑」)在占闸那刻就对外可读,而档案行要等事务提交才写, 那么这个窗口内客户端拿到 runID 去订阅 run 级流会吃 404。本方案里客户端只可能从 run_started 帧得知 runID,而那一帧与档案行同事务提交,窗口不存在。
2.3 关于「POST 返回流」的澄清(一条被写错过的不变量)
早期设计里有一条不变量:「响应三态不得跨越:未提交 / 已提交 / 已结束」, 它的实际作用是要求「409 必须在写 SSE header 之前判完」。本方案没有这条不变量, 并且要说清因果方向:
不是「因为不返回流所以不用判状态」,而是「因为没有状态冲突可判,所以不必返回流」。
返回流本身无罪——外部产品的数据面恰恰就是流式 POST(§12.4)。有罪的是两件事: 流的寿命被绑死在一个 runID 上,以及 POST 的含义是「开一场 run」而非「投递」。 把这两点改掉,返回不返回流是自由选项。这条澄清留在正文里,是因为它是一次真实错判的产物(§13.4)。
3. 组件关系
浏览器 / APP / IM / cron
│
│ ① POST /api/session ──────────▶ 开会话(服务端铸造 id,201)
│ ② POST /api/message ──────────▶ 投递(永远 2xx,JSON)
│ ③ GET /api/session/stream ───▶ 会话级订阅(常驻长连接,只收通知)
│ ④ GET /api/chat/stream ──────▶ run 级订阅(收到 run_started 后才挂,收内容)
▼
┌──────────────────────────────────────────────┐
│ internal/webui/ (只有 transport,无业务) │
│ ├─ server.go 装配 + 路由 │
│ ├─ middleware.go 中间件链(含错误映射) │
│ ├─ handler_session.go 开会话 / 快照 / 删除 │
│ ├─ handler_msg.go 投递 / 撤回 │
│ ├─ handler_stream.go 两条 SSE │
│ ├─ dto.go 请求/响应 DTO │
│ └─ sse.go Stream() / StreamSession() │
└──────────────────┬───────────────────────────┘
│ 函数调用(webui → run,反向不依赖)
▼
┌──────────────────────────────────────────────────────────┐
│ internal/run/ │
│ │
│ Engine(无状态单例,方法一律显式收 sessionID) │
│ ├── Registry 会话登记表(准入检查) │
│ ├── Inbox 待办队列,可变状态 │
│ ├── SessionLog 会话级事实真源 │
│ │ └─ sqlite/sessionlog.go │
│ ├── RunLog run 级事实真源 │
│ │ ├─ sqlite/runlog.go │
│ │ └─ 内存 Subscription │
│ ├── Archive 模型视图真源(共享实例,按会话键控缓存)│
│ │ ├─ sqlite/archive.go │
│ │ └─ 实现 compact.Memory(per-run 绑定) │
│ └── Approvals 审批:决策行落库 + 等待/通知 │
│ │
│ 调度器不是独立组件,是 Engine 的 trySchedule 私有方法 │
│ run 期间的临时状态在 runState 里,由 drive goroutine │
│ 持有、随 run 结束消亡——Engine 自己不持有任何会话状态 │
│ │
│ 领域类型:Event / StoredEvent / Subscription │
│ SessionEvent / SessionSubscription │
│ Approval / Checkpoint │
└──────────────────┬───────────────────────────────────────┘
│ eino adk.Agent / adk.Runner(出站,不经 webui)
▼
LLM
谁持有谁:
Server持有单例Engine+ 共享的RunLog/SessionLog/Registry(后三者 Engine 也引用同一份)Engine持有Registry/Inbox/SessionLog/RunLog/Archive/Approvals的引用 +agent/runner- 一张纯本地的
runCtxs map[runID]context.CancelFunc(本进程正在跑的 run 的取消句柄, 只用于即时取消,不是真源、不是闸,§5.9)
- 一张纯本地的
Archive/Inbox/Registry/Approvals持有存储连接(或共享连接 + 独立事务域)SessionLog持有存储连接 + 每会话的内存事件缓冲(结构同runLog.runBuffer)- run 期间的全部临时状态(cancel、stopped、压缩暂存、对账用的 messageIDs)在
runState里(§5.9), 由 drive goroutine 持有,run 结束即消亡——没有任何「每会话常驻对象」
依赖方向:webui → run → eino / compact。run 不依赖 webui,也不依赖 guard。
Engine 的对外方法(每个方法对应一组路由,见 §5.12;全部显式收 sessionID): Enqueue / Cancel / ClearInbox / Stop / Approve / Snapshot / Delete。 开会话是 Registry.Create(transport 直接调),不经 Engine——Engine 无状态,没有「建/拆」这回事。
4. 三级订阅:先说使用场景,再说结构
4.1 一个语义陷阱
如果把投递接口(POST /api/message)的含义定义成「开一场 run」, 那么会话正忙时这个含义无法兑现,只能用状态码拒绝(409);而 POST 又要返回流、 状态码只能提交一次,于是 409 必须赶在写 header 之前判完——输入与执行就此绑死, 「你输入的时机不对」被迫表达成一个 HTTP 错误:
POST 的含义是「开一场 run」
→ 会话正忙时这个含义无法兑现
→ 只能用状态码拒绝(409)
→ 而 POST 又返回流,状态码只能提交一次
→ 409 必须赶在写 header 前
→ 投递入口必须同步完成占闸 + 开跑
→ 输入与执行绑死
根因不在实现,在语义。 把 POST 的含义从「开 run」改成「投递」,整条约束链自然消失: 投递永不失败,没有冲突需要表达,409 这个概念不存在(不变量 7)。
由此得到一条贯穿全文的判断:
当有了一条常开的控制面通道,单次请求就不再需要承载状态语义。 「正忙」「已排队」「已开始」从「HTTP 状态码」降级成「流内状态」——客户端本来就在监听。
4.2 谁需要知道什么
这条常开的控制面该推什么、推给谁?答案不在架构里,在谁需要知道什么里。先把场景摊开:
| # | 场景 | 谁需要知道 | 需要知道什么 | 这信息属于哪场 run |
|---|---|---|---|---|
| 1 | A 发了一句,等模型逐字回答 | A | 这一场的正文、工具调用、看板 | r_17 |
| 2 | A 刷新了页面,run 还在跑 | A | 从上次断点续上 r_17 | r_17 |
| 3 | B 打开着同一个会话,A 发了一句 | B | 「有人投递了 m_1」「r_17 开始了」 | 不属于任何 B 已知的 run |
| 4 | r_17 跑完了,调度器合并 m_2+m_3 开了 r_18 | A 和 B | 「r_17 落幕了」「r_18 开始了,runID 是这个」 | r_18 此刻还不存在于任何客户端 |
| 5 | B 删掉了这个会话 | A | 「这个会话没了,你正在看的 run 被停了」 | 属于账号,不属于会话 |
| 6 | A 在 APP 上开了新会话,网页端列表要冒出新条目 | 网页 | 「多了一个会话」 | 属于账号 |
第 3、4 行是决定性的。 这两条信息不属于任何客户端已经知道的 run, 所以它们在 run 级流里没有位置可放——run 级流的地址空间是 (runID, seq), 而「r_18 存在了」这句话本身是客户端获得 r_18 这个 ID 的前提。 用一个尚不存在的 runID 去订阅它自己的诞生通知,是循环依赖。
第 5、6 行再往上推一层:会话的增删本身也不是会话级事件,是账号级事件。
于是粒度天然是三级:
| 级别 | 订阅键 | 生命周期 | 推什么 | 本方案 | 外部产品(Kimi) |
|---|---|---|---|---|---|
| 账号级 | userID | 与登录态同寿 | 会话列表增删改、跨会话通知 | 不做(单用户,无账号体系) | WS topic |
| 会话级 | sessionID | 常驻,页面开着就在 | 投递、排队、撤回、run 开始/落幕 | GET /api/session/stream |
WS topic |
| run 级 | runID | 一场 run 的寿命 | 正文、工具调用、看板、审批 | GET /api/chat/stream |
流式 POST 的响应体 |
账号级为什么不做:它需要用户身份体系。会话登记表现在有了(§1.2), 所以「服务端有会话实体」这个前置已满足;缺的只剩「哪个会话属于谁」。 这被列为后置阶段(§10 阶段三),不是「不做」。
4.3 三条物理连接
① POST /api/session ───▶ 开会话,短请求,201 + 服务端铸造的 id
② POST /api/message ───▶ 投递,短请求,JSON 应答,永不因状态冲突失败
③ GET /api/session/stream ───▶ 会话级订阅,常驻,只收「发生了什么」的通知
④ GET /api/chat/stream ───▶ run 级订阅,收到 run_started 才挂,收内容
③④ 是两个逻辑通道。它们是否必须是两条物理连接,是另一个问题—— 浏览器对同一 host 的 HTTP/1.1 并发上限是 6,SSE 会长期占坑 (2 个标签页 × 2 条 SSE = 4 个坑),这个缺陷只在多标签页下暴露, 而多标签页正是本方案要修的场景。§12.4 记录了外部的替代拓扑(单条 WS 多路复用)。
阶段一接受两条 SSE 的代价,阶段三再评估是否合并(启动条件见 §10)。
4.4 两个通道的技术差异
这些差异是拆分的后果,不是拆分的原因:
| 会话级 | run 级 | |
|---|---|---|
| Partial 帧 | 无(通知是一次性的,不存在「半个通知」) | 有,且需要预留号 + 定稿机制 |
| 游标 | per-session seq | per-run seq |
| 寿命 | 不自然结束,页面关才断 | 终局帧后自然结束 |
| 重连代价 | 补几帧通知,很轻 | 可能要重放整场 run |
打个比方:会话级通道是门磁推送(「有人进屋了」),run 级通道是摄像头画面(点开才看)。 你不会为了知道「有人进屋」而 24 小时开着摄像头,也不会指望门磁告诉你屋里人在干什么。
5. 组件详细设计
5.1 Event(run 级领域帧)
文件:
internal/run/event.go
描述「发生过什么」的一条记录。不带 seq(落库时由 RunLog 分配)、不带 JSON tag (序列化是 transport 的事,领域类型不该知道线上格式)。
type EventKind string
// 十一种帧,按「谁写」分两组。这个区分是承重的:
// Classify 只可能产出前四种,后七种由 RunLog / drive 的 ask 闭包直接构造。
// 实现时若把 Kind 定成开放字符串而不列全,§7.9 的字节样例就没有可断言的枚举。
const (
// ── Classify 产出(来自模型的一条 *schema.Message)──
EventMessage EventKind = "message"
EventToolCall EventKind = "tool_call"
EventToolResult EventKind = "tool_result"
EventBoard EventKind = "board"
// ── 由存储层 / 引擎直接写(不经过 Classify)──
EventStart EventKind = "start" // BeginRun,run 级 seq 恒为 1
EventApproval EventKind = "approval" // drive 的 ask 闭包,挂起前
EventApprovalResult EventKind = "approval_result" // ask 被唤醒后
EventCompact EventKind = "compact" // Archive.Notify,压缩发生时
EventComplete EventKind = "complete" // Finish,终局
EventError EventKind = "error" // Finish / Reconcile,终局
EventStop EventKind = "stop" // Finish,终局
)
// 终局帧只有三种,且一个 run 恰好有一条(不变量 6)。
func (k EventKind) IsTerminal() bool {
return k == EventComplete || k == EventError || k == EventStop
}approval / approval_result 两帧带一个结构体而不是散字段——它要传 id、工具名、参数、 提示语、决策,散着放会让 Event 长出五个只有一种帧用到的字段:
type Approval struct {
ID string // 审批 id,POST /api/approval 用它回话
Tool string
Args string
Message string // 给模型/用户看的一句话说明
Decision string // 只在 approval_result 帧上非空:"approve" / "reject"
}Event 因此多一个字段 Approval *Approval(nil 表示这两帧之外的所有帧)。
type ToolCall struct {
Name string // 工具名
Args string // 模型给出的原始参数字符串,不截断不解析
}
type Event struct {
Kind EventKind
Agent string // 所属 agent 名(eino 盖的 AgentName)
Role schema.RoleType // 消息角色
Text string // 正文 / 工具回执 / 看板原文
ToolName string // 工具名(tool_result / board 用)
ToolCalls []ToolCall // 工具调用(tool_call 用)
Approval *Approval // 仅 approval / approval_result 两帧非 nil
Partial bool // 正文还在逐字流出,只进内存不落库
Drop bool // 模型流出失败,半截作废
Discard bool // 半截正文被最终结果取代,静默丢掉
}
// StoredEvent 是已被 RunLog 分配身份的帧。
// Event 描述「要写什么」,StoredEvent 描述「写下了什么」——
// 订阅(Subscription.Next)、写方法的返回值、DTO 转换只流转这个类型。
type StoredEvent struct {
Run string // 所属 run id
Seq int64 // 库内序号;Partial 帧是内存预留号(见 §5.3 Append)
Ts int64 // unix 毫秒;Partial 帧为进内存的时刻
Event
}数据长什么样(一轮典型 run 的事件序列,用户问「读一下 doc/19」):
| 时刻 | Event 内容 |
|---|---|
| 正文流出中 | {Kind:"message", Agent:"tako", Role:"assistant", Text:"好", Partial:true},下一帧 Text:"好的"——同一预留 seq 反复更新 |
| 正文定稿(sealed) | 同上但 Partial:false,Text 为最终全文,按预留号落库 |
| 模型请求调工具 | {Kind:"tool_call", Agent:"tako", Role:"assistant", ToolCalls:[{Name:"read_file", Args:"{\"path\":\"doc/19.md\"}"}]} |
| 工具回执 | {Kind:"tool_result", Agent:"tako", Role:"tool", ToolName:"read_file", Text:"<文件原文>"} |
| tasktracker 回执 | {Kind:"board", Agent:"tako", Role:"tool", ToolName:"TaskUpdate", Text:"<操作回执+当前看板+催更原文>"} |
落库时 RunLog 给每帧分配身份,变成 StoredEvent{Run:"r_17", Seq:5, Ts:1759200000123, Event:{...}}—— 写进 run_log 表和推给订阅者的都是 StoredEvent。
纯函数 Classify:
// Classify 把 eino 的一条消息分类成领域事件。ok=false 表示没有可呈现内容。
// 纯函数,不读任何状态,不写任何状态——所以它可以被单测穷举。
func Classify(agentName string, mv *adk.MessageVariant, msg *schema.Message) (Event, bool)
Partial/Drop/Discard三个字段与 sealed 机制是阶段一的形态。 阶段二会把「正在输出」从事件改成实体的状态字段,这三个字段与预留号协议整套退役(§12)。 它们不是设计目标,是「先不动数据面」这个路线选择的产物。
5.2 Subscription(run 级阻塞式订阅)
文件:
internal/run/event.go(与 Event 同文件)
type Subscription interface {
// Next 阻塞到下一帧可用。
// 冷启动时先把库里 seq > from 的帧按批吐完,再切到实时。
// run 不存在 / ctx 取消 / 流已关 → 返回 false。
// 「run 是否已结束」在 Subscribe 里一次判掉,不留给调用方轮询。
Next(ctx context.Context) (StoredEvent, bool)
// Close 释放订阅资源。幂等。
Close()
}Partial 帧照常从 Next 推出:带着内存预留的 seq 反复推同一号,只更新文本,读者游标不前移; sealed 那条沿用同一预留号落库后推出,游标才走到这个号。不变量 5 不受影响—— 重连的读者(from ≥ 预留号)只会收到 sealed 的那一条,不丢不重。
sealed(定稿):流式正文逐字产出期间只有 Partial 帧(不落库);流结束那一刻, 把最终全文作为一帧经 AppendSealed 按预留号落库、原位替换内存里的 Partial 帧——这个动作叫 sealed。
冷启动按批吐完的例子:run r_17 库里已有 seq 1..80,仍在跑。
读者 A:Subscribe("r_17", 50) ← 断线重连
├─ 追赶阶段:Next 不阻塞,把库里 51..80 按 seq 升序逐条立即返回
└─ 实时阶段:追平后 Next 开始阻塞,run 产出 81、82… 时才返回
读者 B:Subscribe("r_17", 0) ← 第一次打开页面
└─ 1..80 全部吐完,再切实时
读者 C:Subscribe("r_17", 80) ← 一直在看,没断过
└─ 无可追赶,直接阻塞等 81
三个读者调的是同一个 Next,签名不变;「按批」只是说追赶阶段不阻塞、连续返回, 不是返回一个切片。run 已结束时,追赶阶段吐完最后一帧后 Next 返回 false(流完即止)。
「同一预留号反复推」的例子:模型流式输出「早安」,库里已有 seq 1..4,缓冲预留号 = 5。
内存缓冲(库不动):[1..4 sealed] [5: Partial "早"]
读者收到:{seq:5, text:"早", partial:true} ← 读者游标停在 4,不前移
文本更新,原位改: [5: Partial "早安"] (bump)
读者收到:{seq:5, text:"早安", partial:true} ← 同一 seq 再推一次,前端原位替换半截气泡
流结束 AppendSealed:[5: sealed "早安,今天…"] ← 这时才 INSERT 进库
读者收到:{seq:5, text:"早安,今天…", partial:false} ← 游标这才走到 5
前端凭 partial:true + 相同 seq 判断「替换而非追加」;读者游标不前移意味着 断线重连(from=5)不会收到任何 Partial,只会收到 sealed 那条——不变量 5 的另一面。
Next 伪代码(难写点:一个方法里混着冷启动追赶、实时阻塞、Partial 同号替换三种状态, 还要不空转、不丢帧、run 结束即退出):
func (s *subscription) Next(ctx) (StoredEvent, bool) {
for {
s.log.mu.Lock()
buf := s.log.runs[s.runID] // Subscribe 时已保证存在且装满(内存没有则 readAll)
if ev, ok := buf.at(s.next); ok { // 缓冲里正好有 seq == s.next 的帧
if ev.Partial {
if buf.gen == s.seenGen { goto wait } // 文本没变过,不重推,防忙等
s.seenGen = buf.gen
s.log.mu.Unlock()
return ev, true // 游标不动:sealed 原位替换后 s.next 仍指这个号
}
s.next = ev.Seq + 1 // sealed / 持久帧:游标前移
s.seenGen = buf.gen
s.log.mu.Unlock()
return ev, true
}
// 走到这说明内存已追平(s.next 超过缓冲最大 seq)
if s.log.runFinished(s.runID) { // status 已不是 running
s.log.mu.Unlock()
return StoredEvent{}, false // 流完即止
}
wait:
ch := buf.notify // 持锁时拿下这一代通知通道
s.log.mu.Unlock()
select {
case <-ch: // 有 bump(新帧/文本更新),回顶部重扫
case <-ctx.Done():
return StoredEvent{}, false
}
}
}5.3 RunLog(run 级事实真源)
文件:
internal/run/runlog.go(接口)+internal/run/sqlite/runlog.go(实现)
追加式存储。分配 seq,保证终局唯一。内存缓冲让 Subscription 能阻塞式推送。
type RunLog interface {
// ── 写(一律用进程 ctx,不变量 3)──
// Reconcile 把上次进程没写上终局的 run 标成 failed,并给每个这样的 run
// **补一帧 kind:"error" 的终局帧**。启动时调一次。
// 补帧是必须的:存着旧 runID 的客户端重连后会一直等终局帧,
// 只改 status 不补帧,它就永远挂着(§8 失效场景 D)。
//
// 返回它刚刚标 failed 的那些 run,由调用方(Server 的启动流程)逐个
// sessionLog.Append(run_terminal) —— RunLog 不认识 session_log,
// 会话级的那一帧只能由外面补(编排顺序见 §7.8)。
Reconcile(ctx context.Context) (failed []FailedRun, err error)
// BeginRun 开一轮 run:插入 run_archive 行 + 写 seq=1 的 start 帧,同一事务。
BeginRun(ctx context.Context, runID, sessionID, userMessage, agentName string) (StoredEvent, error)
// Append 给仍在 running 的 run 追加一帧。seq 由库分配。
// ev.Partial 的帧例外:不写库,只在内存缓冲里预留下一个 seq 并返回
// (StoredEvent.Seq 即预留号);同一条流出正文反复调用沿用同一预留号,只更新文本。
// run 已经不是 running → 返回错误(不变量 6)。
Append(ctx context.Context, runID string, ev Event) (StoredEvent, error)
// AppendSealed 把流式正文的最终全文按预留号落库。
// seq 必须正好是库内 max+1,否则返回 ErrSealConflict——预留号只存在于内存,
// 若 seal 前被别的持久帧占了号,这里报错,由 drive 按 persistErr 走 error 终局。
AppendSealed(ctx context.Context, runID string, seq int64, ev Event) (StoredEvent, error)
// Finish 写终局帧 + 改 run_archive 状态,同一事务(不变量 6)。
// kind 只接受 "complete" / "error" / "stop"。
// 只有 complete 写入 producedJSON;失败和停止不把产出放进模型历史。
// patch 非 nil 时在同一事务里改 user_message 和清空被换掉的行。
Finish(ctx context.Context, runID, kind, text string, producedJSON []byte, patch *ArchivePatch) (StoredEvent, error)
// ── 读 ──
// Subscribe 返回阻塞式订阅。from=0 从头。
// run 不存在 → ErrRunNotFound(transport 回 404)。
// 内部判断 run 是否已结束:已结束则冷启动装库后流完即止。
Subscribe(runID string, from int64) (Subscription, error)
// HistoryPage 返回会话里已结束的 run(档案 + 事件),按 created_at 降序分页。
// cursor 格式 "<created_at>|<run_id>",空表示第一页。
// 不含 status='running' 的行——正在跑的 run 由 Snapshot 报告。
// 归 RunLog 而非 Archive:响应里带事件帧,且 run_archive 的
// status/produced_json 本来就由 BeginRun/Finish 的事务写,是同一块地盘。
HistoryPage(ctx context.Context, sessionID, cursor string, limit int) (HistoryPage, error)
// Close 关闭底层连接。
Close() error
}
type HistoryRun struct {
RunID string
CreatedAt string
Status string
Events []StoredEvent
}
type HistoryPage struct {
Runs []HistoryRun
NextCursor string
}
// FailedRun 是 Reconcile 的返回值:一个被强制标 failed 的 run 及其所属会话。
// 调用方拿它去补会话级的 run_terminal 帧(§7.8)。
type FailedRun struct {
SessionID string
RunID string
}这里没有补发接口。 早期设计里有一个「客户端把手里的全文补发回库」的方法, 用来兜「进程死在流结束与
AppendSealed之间」那个窗口。本方案不提供它,理由三条: ① 它的前提是浏览器手里有全文,而全文的唯一来源就是这条流本身——流断了才需要补发, 断了就说明客户端也没收全;② 它要求客户端长期保存对话内容,与会话身份在服务端的事实相悖; ③ 阶段二让正文从「生成中」起就落库,窗口结构性消失,补发无的放矢。 代价要在 §9.2 明说:阶段一这个窗口是敞开的,进程崩在 seal 之前会丢一条助手正文, 且不可恢复。这是 knowingly 接受的,不是漏掉的。
内部结构(实现细节,接口不暴露):
type runLog struct {
mu sync.Mutex
db *sql.DB
runs map[string]*runBuffer // 每 run 的内存缓冲,读者按 seq 读
}
type runBuffer struct {
events []StoredEvent // 按 seq 升序;Partial 帧带预留号在列,sealed 时原位替换
gen uint64 // 变化计数,通知读者
notify chan struct{} // 关闭表示有新事件
}Append / AppendSealed / Finish 在写库成功后调 runBuffer.bump() 通知所有订阅者。 Subscribe 如果 runs[runID] 不存在,先从库 readAll 装入并建 buffer,再返回 Subscription。
Append / AppendSealed 伪代码(难写点:Partial 预留号是纯内存协议, Drop/Discard 要作废预留号不留空洞,seal 要防「号被占」,且一律先写库再 bump——不变量 4):
func (l *runLog) Append(ctx, runID, ev) (StoredEvent, error) {
l.mu.Lock(); defer l.mu.Unlock()
buf := l.runs[runID]
if buf == nil || buf.status != running { return ErrRunFinished } // 不变量 6:终局后拒绝追加
if ev.Drop || ev.Discard {
buf.dropPartialTail() // 作废预留号:把内存尾部的 Partial 帧直接摘掉
buf.bump() // 库内 max 从没动过,下一条持久帧自然接上,不留空洞
return StoredEvent{}, nil
}
if ev.Partial {
if last := buf.tail(); last != nil && last.Partial {
last.Text, last.Ts = ev.Text, nowMillis() // 同一条流出正文:原位更新,沿用同一预留号
buf.bump()
return *last, nil
}
se := StoredEvent{Run: runID, Seq: buf.maxSeq() + 1, // 预留号 = 此刻若落库将得的号
Ts: nowMillis(), Event: ev}
buf.append(se) // 只进内存,不写库
buf.bump()
return se, nil
}
seq, err := l.insertEvent(ctx, runID, ev) // 写库:INSERT,seq 由库内 max+1 分配
if err != nil { return StoredEvent{}, err } // 写失败不进缓冲——读者永远看不到库里没有的帧
se := StoredEvent{Run: runID, Seq: seq, Ts: nowMillis(), Event: ev}
buf.append(se); buf.bump()
return se, nil
}
func (l *runLog) AppendSealed(ctx, runID, seq, ev) (StoredEvent, error) {
l.mu.Lock(); defer l.mu.Unlock()
buf := l.runs[runID]
tail := buf.tail()
if tail == nil || !tail.Partial || tail.Seq != seq || buf.maxSeq() != seq {
return ErrSealConflict // 预留号被别的持久帧占了 → drive 按 persistErr 走 error 终局
}
if err := l.insertEventAt(ctx, runID, seq, ev); err != nil { // INSERT 指定 seq
return err
}
buf.sealTail(ev) // 原位替换:Partial=false,Text=最终全文
buf.bump()
return *buf.tail(), nil
}5.4 Archive(模型视图真源)
文件:
internal/run/archive.go(接口)+internal/run/sqlite/archive.go(实现)
全局一个(不是每会话一个),内部按 sessionID 键控缓存。管理「下一轮该给模型看什么」。 冷热缓存、压缩的改写目标。压缩暂存不在这里——它是 run 期间的临时状态,住 runState(§5.9), Archive 只提供「对某个会话的缓存执行暂存/退回/出补丁」的无状态操作。 compact.Memory 的实现是一个 per-run 的小适配器(archiveMemory,见下)。
// ArchivePatch 是成功收尾时和 produced_json 同一笔写入的档案修改。
type ArchivePatch struct {
UserMessage string // 非空时覆盖 run_archive 的 user_message(压缩后的摘要)
DropRunIDs []string // 这些行的 produced_json 清成 NULL
}
type Archive interface {
// ── 模型消息缓存(按 sessionID 键控)──
// ModelMessages 返回下一轮要给模型的完整消息列表。
// 热路径直接返回缓存副本;冷路径从 run_archive 装入已完成 run 的产出。
// 调用方拿到的是副本,改不到缓存。
ModelMessages(ctx context.Context, sessionID string) ([]*schema.Message, error)
// AddRun 一轮成功收尾后,把这轮的产出接进该会话的缓存。
// userText 是这一轮的用户原话(或压缩后的摘要)。
// 该会话还没装过库(冷路径没走过)则不动,下次 ModelMessages 再读库。
AddRun(sessionID string, produced []*schema.Message, userText, runID string)
// InvalidateCache 丢掉该会话已装入的缓存,下次 ModelMessages 重读库。
// Delete 级联、以及冷会话被 LRU 逐出时用。
InvalidateCache(sessionID string)
// ── 压缩暂存(补偿模式;暂存态住 runState,§5.9)──
// Stage 对 st 里携带的缓存副本执行压缩改动,并把新的暂存态写回 st。
// 只改内存,不碰库。st.Snap 为空时留下快照(退回基准);
// 同一轮里再压,仍相对原始快照取舍。失败时 RevertStage 退回。
Stage(st *CompactState, c compact.Commit) error
// RevertStage 把 st 退回到本轮第一次压缩前。幂等。
RevertStage(st *CompactState)
// CommitPatch 返回成功收尾时要写入库的补丁。没 Stage 过则 ok=false。
CommitPatch(st *CompactState) (ArchivePatch, bool)
// BindMemory 返回这一场 run 的 compact.Memory 视图(per-run 适配器,见下)。
// drive 开跑时调一次,交给压缩 middleware。
BindMemory(sessionID, runID, userText string, st *CompactState) compact.Memory
// ── RAG ──
// Notify 追加一条 kind 为 compact 的事件到 run_log,不改已写下的帧。
// text 为空则不做。run 不在 running 时只记日志。
Notify(ctx context.Context, runID, text string)
// WriteRAG 把被换掉的原文追加进 compact_rag。
WriteRAG(ctx context.Context, sessionID, runID, body string) error
// SearchRAG 按词重叠检索这一会话的 compact_rag 原文。
SearchRAG(ctx context.Context, sessionID, query string) (string, error)
}
// CompactState 是压缩暂存态。由 drive 在开跑时创建、放进 runState,
// run 结束即丢弃——**它的寿命就是一场 run**,不是会话。
type CompactState struct {
Msgs []*schema.Message // 工作副本:本 run 视角的消息列表(含本轮已产消息)
Runs []RunRecord // 工作副本:与 Msgs 对应的已完成轮
SnapMsgs []*schema.Message // 第一次 Stage 前的快照(退回基准)
SnapRuns []RunRecord
Staged bool
PendingDrop []string // 被换掉的 runID,收尾时清它们的 produced_json
ModelText string // 压缩后的摘要整句(空 = 没压缩)
}内部结构(实现细节):
type archive struct {
mu sync.Mutex
caches map[string]*sessionCache // sessionID → 缓存;LRU 逐出冷会话(InvalidateCache)
runLog RunLog // Notify 写事件用
}
type sessionCache struct {
loaded bool // 冷路径是否走过
modelMsgs []*schema.Message // 缓存:下一轮给模型的完整列表
runs []RunRecord // 按完成顺序,与 modelMsgs 对应
}
type RunRecord struct {
RunID string
Msgs []*schema.Message
}缓存的正确性边界(照实登记):跨 run 的缓存一致性靠的是闸的串行化—— AddRun 只由持有 live run 的那个副本在 Finish 成功后调用,而「持有 live run」由 DB 唯一索引裁决。 单副本下这是充分的;多副本下它有一个已知的洞:副本 B 上留着的旧缓存, 在副本 A 跑完几轮之后不会自动失效。修法(跨副本失效广播,或干脆每场 run 开跑时冷装) 随 §11 问题 12 的事件缓冲一起解决,阶段一不处理。
archiveMemory:compact.Memory 的 per-run 适配器,drive 开跑时经 BindMemory 创建、 交给压缩 middleware,随 run 消亡:
type archiveMemory struct {
a Archive
sessionID string
runID string
userText string // 这一轮的用户原话(压缩前)
st *CompactState // 工作副本与暂存态都从这里读
}
// SessionID / OriginalUser / CurrentRunID 是常量字段;
// CompletedRunIDs() 从 st.Runs 取;Notify / WriteRAG / SearchRAG 转发给 Archive(带上 ctx 与 id)。Stage / CommitPatch / RevertStage 伪代码(难写点:这是一套「补偿式事务」—— 改动全部落在 CompactState(内存),库要等到收尾的 Finish 事务才写; 中间任何一步失败都必须能干净退回,否则模型视图和 run_archive 永久分叉,见 §7.6 补偿路径):
func (a *archive) Stage(st *CompactState, c compact.Commit) error {
if !st.Staged { // 本轮第一次压缩:留快照,作为回退基准
st.SnapMsgs = copy(st.Msgs) // 同一轮再压,仍相对这份原始快照取舍
st.SnapRuns = copy(st.Runs)
st.Staged = true
}
st.Runs = filter(st.Runs, r => c.KeptRunIDs.contains(r.RunID)) // 丢掉被换掉的轮
st.Msgs = rebuild(st.Runs) // 按保留集重装消息列表
st.PendingDrop = append(st.PendingDrop, c.DroppedRunIDs...)
st.ModelText = c.CombinedUser // 摘要接在本轮用户原话前的整句
return nil // 全程不碰库;被丢原文由 Handler 调 WriteRAG 写 compact_rag
}
func (a *archive) CommitPatch(st *CompactState) (ArchivePatch, bool) {
if !st.Staged { return ArchivePatch{}, false }
return ArchivePatch{UserMessage: st.ModelText, DropRunIDs: st.PendingDrop}, true
// 调用方(drive)把它交给 Finish,与终局帧同一事务写 run_archive
}
func (a *archive) RevertStage(st *CompactState) {
if !st.Staged { return } // 没 Stage 过,无事发生(幂等)
st.Msgs, st.Runs = st.SnapMsgs, st.SnapRuns
st.Staged = false
st.PendingDrop = nil
st.ModelText = ""
}CompactState 由 drive 持有(§5.9 的 runState.compact),所以暂存态与 run 同寿命—— 这正是「压缩改动只活在内存里」这句话的准确含义:活在 runState 里,不是活在 Archive 里。
5.5 SessionEvent / SessionSubscription(会话级领域类型)
文件:
internal/run/session_event.go
type SessionEventKind string
const (
SessMessageQueued SessionEventKind = "message_queued" // 一条消息进了收件箱
SessMessageCancelled SessionEventKind = "message_cancelled" // 用户撤回了一条排队消息
SessRunStarted SessionEventKind = "run_started" // 调度器开了一场 run
SessRunTerminal SessionEventKind = "run_terminal" // 一场 run 落幕
)
// SessionEvent 是会话级流的一帧。与 run 级 Event 完全平行,不共享类型。
// 四类帧各用自己的一部分字段——这是一个「并集结构体」,
// 代价是字段可空性靠约定;收益是四种帧共用一套存储与一套订阅机制。
type SessionEvent struct {
Kind SessionEventKind
// message_queued / message_cancelled 用:
MessageID string
ClientID string // 投递方的设备标识(客户端生成 UUID,存 localStorage)。
// 多客户端场景下 UI 据此区分「谁发的」——
// A 的桌面看到「B-phone: 再加个倒序版本」。
// 同一设备换浏览器/清缓存 → 新 clientId(变成「新设备」)。
// ★ 边界:同一浏览器的两个标签页读到的是同一个值,
// 所以它认设备、不认标签页(§7.9 用例 5)。
Text string // queued 帧带全文,重连的客户端不用再查一次就能画出排队气泡
// run_started 用:
RunID string
MessageIDs []string // 这场 run 消费了哪些消息(合并窗口的结果,UI 据此表达「这两句被一起回答了」)
MergedText string // 合并后交给模型的那句
Resumed bool // true = 进程重启后由 Reconcile 重新调度的(§7.8)
// run_terminal 用:
TerminalKind string // "complete" / "error" / "stop"
}
// StoredSessionEvent 是已被 SessionLog 分配身份的帧。
type StoredSessionEvent struct {
Session string
Seq int64 // 会话级 seq,与 run 级 seq 是两个独立命名空间(不变量 5)
Ts int64
SessionEvent
}
type SessionSubscription interface {
// Next 阻塞到下一帧可用。冷启动时先把库里 seq > from 的帧吐完,再切到实时。
// 与 run 级 Subscription 的关键区别:**会话级流永不自然结束**。
// run 级流见到终局帧即止;会话级流只在 ctx 取消时返回 false——它是常驻长连接。
Next(ctx context.Context) (StoredSessionEvent, bool)
Close()
}为什么不用 Partial 机制:会话级帧全是离散事实(入队、开跑、落幕),没有「逐字流出」的语义。 所以 SessionEvent 没有 Partial 字段,游标永远单调前移,重连逻辑比 run 级简单得多。
5.6 Registry(会话登记表)
文件:
internal/run/registry.go(接口)+internal/run/sqlite/registry.go(实现)
全局一个(不是每会话一个)。它只管身份,不管内容——内容在 session_log 与 run_log 里。
// Session 是登记表里的一行。
type Session struct {
ID string
CreatedAt int64 // unix 毫秒
}
type Registry interface {
// Create 铸造一个新会话 id 并落一行登记。
// 不写 session_log 帧、不开 run,也没有任何引擎对象要装配(Engine 是无状态单例,§5.9)。
Create(ctx context.Context) (Session, error)
// Get 查一个会话。不存在 → ErrSessionNotFound(transport 回 404)。
// ★ 所有带 sessionId 的写操作都要先过这一关(不变量 1)。
Get(ctx context.Context, sessionID string) (Session, error)
// Delete 删掉登记行。级联清理是 Engine.Delete 的职责,不是这里的(§5.9)。
Delete(ctx context.Context, sessionID string) error
}id 怎么铸造:服务端生成,格式 s_<时间有序 base32>(ULID 一类),runID 同理 r_<...>。 三个要求:
- 多副本安全——不能依赖单进程计数器或数据库自增序列(换 Postgres 后序列可用, 但 ULID 让「id 由谁发」这件事与存储解耦)。
- 趋势递增——会话列表将来要按创建时间排,id 本身可排就省一个索引。
- 带前缀——
s_/r_/m_让日志与 URL 里一眼看出这是哪种实体, 也避免「把 runID 当 sessionId 传」这类错误静默通过。
为什么没有什么要「建」:Engine 是无状态单例(§5.9),没有任何 per-session 对象需要装配; 会话的执行状态只存在于 runState,寿命不超过一场 run。 「开了一千个会话」的常驻成本因此只有表里的一千行登记,没有一千个引擎对象。 权威永远是登记表——它既管准入,也是重启后「哪些会话值得续答」的判据来源。
5.7 Inbox(收件箱)
文件:
internal/run/inbox.go(接口)+internal/run/sqlite/inbox.go(实现)
全局一个(DB 表的无状态句柄,方法一律收 sessionID)。表内容是可变状态,行会被消费或删除。
// QueuedMessage 是收件箱里的一条待发消息。
type QueuedMessage struct {
ID string
ClientID string
Text string
Seq int64 // 会话级排序坐标,决定合并时的先后
}
type Inbox interface {
// Put 投递一条消息,返回它拿到的会话级 seq(transport 把它放进 202 响应体,§5.12)。
// messageID **由客户端生成**,语义是「绑草稿的幂等键」(§1.2、§11 问题 7):
// 同一句话超时重发要带同一个 id,本会话内重复 → ErrMessageIDTaken
// (transport 回 409,前端视为幂等成功)。
// 除此之外只可能因存储故障失败——**没有「会话正忙」这种失败**(不变量 7)。
// 队列已达 maxQueueDepth → ErrQueueFull(transport 回 422 + 当前条数)。
Put(ctx context.Context, sessionID, messageID, clientID, text string) (seq int64, err error)
// Drain 取空收件箱,返回按 seq 升序的全部待发消息。
// **必须在与 BeginRun 同一个事务里调用**(见 §5.9 beginRunAtomic):
// 取空与开跑原子完成,才不会有消息在两步之间溜进来又被漏掉。
// 空收件箱 → 返回 nil, false。
Drain(ctx context.Context, tx *sql.Tx, sessionID string) ([]QueuedMessage, bool, error)
// Cancel 撤回一条尚未被消费的消息。
// 已被 run 消费(行已删)→ false(transport 回 404)。
// 因为消费与开跑同事务,**不存在「撤回了但模型已经看到」的中间态**。
Cancel(ctx context.Context, sessionID, messageID string) (bool, error)
// Clear 清空整个收件箱,返回被清掉的条数(transport 回 200 + 条数)。
// 用于「我改主意了,全不要了」——逐条撤回十次不如一次。
Clear(ctx context.Context, sessionID string) (int, error)
// Pending 返回当前待发消息,按 seq 升序。给 Snapshot 用。
Pending(ctx context.Context, sessionID string) ([]QueuedMessage, error)
// PendingCount 只返回条数。Put 用它做队列深度上限检查,不必拉出全部消息体。
PendingCount(ctx context.Context, sessionID string) (int, error)
}
// maxQueueDepth 是单个 run 期间可累积的排队上限。取值与理由见 §11 问题 3。
const maxQueueDepth = 10为什么队列过深是 422 而不是 202:不变量 7 说的是不因状态冲突失败 (会话忙不是错误,那是调度器的内部事实);而队列过深是用户的输入本身需要被重新考虑, 这是 4xx 的正当用途。参考实现给的理由更直白:超过这个深度说明「这场 run 显然没在听用户说话, 诚实的回答是拒绝,而不是静默排队」。
建表:
CREATE TABLE inbox (
session_id TEXT NOT NULL,
message_id TEXT NOT NULL,
client_id TEXT NOT NULL,
text TEXT NOT NULL,
seq INTEGER NOT NULL, -- 会话级递增,与 session_log.seq 同源分配
created_at INTEGER NOT NULL,
PRIMARY KEY (session_id, message_id) -- 幂等闸:同一草稿重发撞这里 → 409
);
CREATE INDEX idx_inbox_session ON inbox(session_id, seq);主键是 (session_id, message_id) 而不是 message_id 单列:messageId 是客户端 mint 的 UUID,唯一性由随机性保证,但范围只在本会话内承诺——A 会话用过的 id 不该让 B 会话吃 409。 单列主键会把「会话内唯一」偷偷升级成「全局唯一」,而方案里没有任何一处需要全局唯一 (Cancel / Drain / message_ids 全都带着 sessionId 一起用)。
seq 与 session_log.seq 同源分配(同一个会话级计数器),这样「消息 m_1 入队」这件事 在两张表里用的是同一个坐标,客户端对齐时间线时不需要换算。 同源不等于同一张表:计数器一次取号,inbox 与 session_log 各写各的行(§11 问题 1 讨论了这个取舍)。
5.8 SessionLog(会话级事实真源)
文件:
internal/run/sessionlog.go(接口)+internal/run/sqlite/sessionlog.go(实现)
结构与 RunLog 完全平行,只是粒度从 run 换成 session。
type SessionLog interface {
// Reconcile 启动时调一次:返回所有 inbox 非空的会话,由编排层逐个
// engine.trySchedule(ctx, sessionID)(§7.8)。
// (把没写完终局的 run 标 failed + 补终局帧是 RunLog.Reconcile 的事,§5.3。)
Reconcile(ctx context.Context) (pendingSessions []string, err error)
// NextSeq 取一个会话级 seq。inbox.Put 与 Append 共用这个计数器(§5.7)。
NextSeq(ctx context.Context, tx *sql.Tx, sessionID string) (int64, error)
// Append 追加一帧会话级事件。seq 由 NextSeq 分配。写成功后 bump 内存缓冲通知订阅者。
Append(ctx context.Context, sessionID string, ev SessionEvent) (StoredSessionEvent, error)
// AppendInTx 在调用方的事务里追加一帧,但**不 bump**。
// trySchedule 用它在同一事务里写 run_started(不变量 9),事务提交后再统一 bump。
AppendInTx(ctx context.Context, tx *sql.Tx, sessionID string, ev SessionEvent) (StoredSessionEvent, error)
// Subscribe 返回阻塞式会话级订阅。from=0 从头。
// 会话存在但还没有任何帧 → 返回一个空订阅,Next 阻塞等第一帧,不报错。
// ★ 「会话存不存在」不由这里判——那是 Registry 的职责(不变量 1),
// transport 先查 Registry 再订阅,未知会话直接 404。
// 与 run 级的区别:**不会因为「已结束」而流完即止**——会话没有终局。
Subscribe(sessionID string, from int64) SessionSubscription
// Since 非阻塞拉取 (from, from+limit] 的帧。见下面的 SessionFeed。
Since(ctx context.Context, sessionID string, from int64, limit int) ([]StoredSessionEvent, error)
// CloseSession 关掉这个会话的所有订阅并丢掉内存缓冲。Engine.Delete 用。
CloseSession(sessionID string)
Close() error
}存储与传输分离(重要):Subscribe 返回的是一个阻塞式迭代器, 它把「会话级事件增量怎么拿到」和「用哪种连接推给客户端」绑在了一起—— 一旦绑死,换成轮询或 WS 多路复用就得改接口。所以把它抽成一个独立能力:
// SessionFeed 是「拿到增量」的能力,与传输无关。SessionLog 实现它。
type SessionFeed interface {
// Since 非阻塞拉取。轮询模式直接用这个。
Since(ctx context.Context, sessionID string, from int64, limit int) ([]StoredSessionEvent, error)
// Subscribe 阻塞式推送。SSE / WS 用这个。
Subscribe(sessionID string, from int64) SessionSubscription
// Notify 注册一个「这个会话有新帧」的信号,不带内容。
// WS 多路复用用这个:一条连接上挂着 N 个会话,只需要知道谁变了,
// 再按需 Since 取内容——避免为每个会话各建一个 Subscription。
Notify(sessionID string) <-chan struct{}
}三种传输都建在同一份 session_log 上,可互换:
| 传输 | 用法 | 何时选它 |
|---|---|---|
| SSE | Subscribe + 逐帧写 |
阶段一的默认。最简单,浏览器自动重连 |
| 轮询 JSON | Since(?since=) |
降级路径;或客户端不便持有长连接时 |
| WS 多路复用 | Notify + Since |
多会话/多标签页,受浏览器 6 连接上限约束时(§4.3) |
阶段一只做 SSE,但接口按可互换来设计——因为「一条 WS 承载所有会话」是明确的演进方向 (§10 阶段三),不该等到要做时才发现接口绑死了。
建表:
CREATE TABLE session_log (
session_id TEXT NOT NULL,
seq INTEGER NOT NULL,
ts INTEGER NOT NULL,
kind TEXT NOT NULL,
payload TEXT NOT NULL, -- SessionEvent 的 JSON
PRIMARY KEY (session_id, seq)
);内存缓冲:map[sessionID]*sessionBuffer,字段与 runBuffer 同构 (events []StoredSessionEvent + gen uint64 + notify chan struct{}), 但不需要 Partial 分支,所以 Next 的伪代码比 §5.2 简单一半:
func (s *sessionSubscription) Next(ctx) (StoredSessionEvent, bool) {
for {
s.log.mu.Lock()
buf := s.log.sessions[s.sessionID]
if ev, ok := buf.at(s.next); ok {
s.next = ev.Seq + 1 // 游标永远前移,没有 Partial 的同号重推
s.seenGen = buf.gen
s.log.mu.Unlock()
return ev, true
}
ch := buf.notify // 会话级流不判「已结束」,直接等
s.log.mu.Unlock()
select {
case <-ch:
case <-ctx.Done():
return StoredSessionEvent{}, false
}
}
}5.9 Engine:Enqueue / Cancel / Stop / Delete / trySchedule / drive
文件:
internal/run/engine.go
// Engine 是无状态单例:全局一个,不持有任何会话状态,所有方法显式收 sessionID。
type Engine struct {
// ── 全部是构造时注入的共享依赖 ──
ctx context.Context // 进程 ctx(不变量 3)
registry Registry
runLog RunLog
sessionLog SessionLog
inbox Inbox
archive Archive
approvals *Approvals
agent adk.Agent
runner *adk.Runner
// ── 唯一的可变字段:纯本地的取消句柄表 ──
mu sync.Mutex
runCtxs map[string]context.CancelFunc // runID → cancel。只登记**本进程**正在跑的 run。
// 它是即时取消的优化,不是真源、不是闸:
// 「有没有 run 在跑」的唯一判据是
// run_archive 里 status='running' 的那一行(§5.14)。
// 多副本下 stop/delete 的跨副本语义见 Stop/Delete 的注释。
}
// runState 是一场 run 的全部进程内状态。由 drive goroutine 独占持有,run 结束即消亡。
// 它取代了早期设计的 per-session Engine 状态(live / pending / 压缩暂存)——
// 那些字段曾经是多副本审计里的三处断点(§13.5),现在两处(闸、审批)已不存在,
// 剩下的临时状态寿命都不超过一场 run。
type runState struct {
id string
sessionID string
cancel context.CancelFunc
stopped bool // Stop 命中过(drive 本地镜像;真源是库里的停止标记)
messageIDs []string // 这场 run 消费的消息 id,收尾时对账用
userText string // 合并后的整句(多条消息用 "\n\n" 连接)
modelUserText string // 压缩后的摘要(空 = 没压缩)
dropped []string
compact *CompactState // 压缩暂存(§5.4),寿命 = 一场 run
}闸只有一种形态:DB 部分唯一索引。
CREATE UNIQUE INDEX one_live_run_per_session ON run_archive(session_id) WHERE status='running';「判断闸空」「取空收件箱」「开 run 并占闸」三件事在 beginRunAtomic 的同一个事务里完成, 插入撞上唯一索引 = 闸忙 = 事务回滚、Drain 的消息自动回到 inbox。不变量 8、9 由事务本身兑现:
- 不需要进程内 mutex 当闸——并发开跑的仲裁者是数据库,两个并发
trySchedule(无论同进程还是跨副本)恰好一个能提交。 - 不需要「id 为空的哨兵」这个特例——早期设计用哨兵防止两个
trySchedule都判断闸空, 现在这个竞态由唯一索引吃掉;而「runID 不提前泄露」由不变量 9 保证 (runID 只在事务提交后、经run_started帧发布)。 - SQLite 也支持部分索引,第一阶段就能验,不必等 Postgres。
导出方法:
// Enqueue 投递一条用户消息。
//
// 语义:**永远成功**(除非存储故障、队列已满、或客户端自己搞错了)。
// 不判断会话忙不忙,不开 run,不返回 runID。
// 同步完成两件事:
// 1. inbox.Put() —— 落库(不变量 4:先落库再回 2xx)
// 2. sessionLog.Append(message_queued) —— 落库 + 推给所有会话级订阅者
// 然后调 trySchedule(sessionID):闸空就立刻开跑,闸忙就什么都不做(消息已在收件箱里等着)。
//
// 返回它拿到的会话级 seq —— transport 把它放进 202 响应体(§5.12)。
//
// 参数:
// messageID —— **由客户端生成**。让前端能立刻用自己的 ID 画 pending 气泡,
// 帧到达时按同一 ID 对齐;也让「消费事件早于 HTTP 响应到达」成为可能。
// 本会话内重复 → 409(**正当的 409**:表达「你重复投递了」,
// 不是「你来得不是时候」,与不变量 7 不冲突)
// clientID —— 投递方的设备标识(客户端生成 UUID,存 localStorage)
// expectedRunID —— 客户端**看到的那场 run**(fencing token,可为空)。
// 非空且与当前 live 不符 → 409 + 当前 liveRunID,
// 让客户端知道自己的视图过期了。比不变量 9 更强:
// 9 只保证「runID 提交后才可见」,这个还能检测「客户端停在旧视图」。
// 当前 live 从库里读(run_archive status='running' 的行),
// 不依赖任何进程内变量
// text —— 正文
func (e *Engine) Enqueue(ctx context.Context, sessionID, messageID, clientID, expectedRunID, text string) (seq int64, err error)
// Cancel 撤回一条排队中的消息。已被 run 消费 → false(transport 回 404)。
func (e *Engine) Cancel(ctx context.Context, sessionID, messageID string) (bool, error)
// ClearInbox 清空收件箱,返回被清掉的条数。「我改主意了,全不要了」。
// ★ 同样要为每条写一帧 message_cancelled——否则其他客户端的气泡不会消失。
func (e *Engine) ClearInbox(ctx context.Context, sessionID string) (int, error)
// Stop 取消一场正在跑的 run。幂等。run 不存在、不属于该会话、或不匹配 → false。
// 两步,顺序固定:
// 1. 库:查 run_archive 有 status='running' 且 run_id 匹配的行(没有 → false),
// 写停止标记(**stop_requested 列,真源**)
// 2. 本进程 runCtxs 命中 → 立刻 cancel;没命中(run 在别的副本上,多副本时)
// → 靠 drive 在帧边界轮询 stop_requested 收敛,行为一致、只是慢一拍
// **不清空收件箱**:停止的语义是「这一轮不对」,不是「我说的话不算」。
// 收尾时 trySchedule 会照常消费剩余消息(前端必须明示这一点,见 §6)。
func (e *Engine) Stop(ctx context.Context, sessionID, runID string) (bool, error)
// Delete 销毁整个会话。级联:停 live run + 清收件箱 + 删四张表的会话行 + 删登记 + 广播。幂等。
//
// ★ 语义必须是「以 sessionID 为键、无条件取消 live」,**不能依赖客户端知道 runID**。
// 理由是一个具体的失效场景(§8 场景 A):客户端只有在收到第一帧之后才知道 runID,
// 而「按下发送」到「第一帧到达」之间覆盖了模型首 token 之前的全部思考时间,通常好几秒。
// 这段窗口里如果「销毁会话」要靠客户端报 runID,它就报不出来,旧 run 会在后台跑到底,
// 帧继续写进一个用户以为已经不存在的会话。
//
// 顺序(每步都不可跳过):
// 1. 查该会话 status='running' 的行;本进程 runCtxs 命中 → cancel
// (多副本下别的副本持有的 run 由「行已删除」兜底——见第 3 步之后的说明)
// 2. 清 inbox(否则 trySchedule 会把已删会话的消息捞起来开新 run)
// 3. 同一事务删 run_log / run_archive / session_log / inbox 的会话行 + registry 登记行
// + approval 行(§5.11)
// 4. 关会话级订阅(SessionLog.CloseSession)+ archive.InvalidateCache(sessionID),
// 让所有客户端的常驻流断开、缓存不留孤儿
//
// 没有第五步。Engine 无状态,不存在「从 map 里摘掉这个会话的引擎」。
// 多副本下别的副本若正在 drive 这个会话:它的下一次写库(emit / Finish)撞到已删除的行
// → persistErr → 自行退出——「删表」比「发 stop」强,正是这个意思(§8 场景 A)。
func (e *Engine) Delete(ctx context.Context, sessionID string) error
// Approve 记录一条审批决策(写库 + 唤醒等待方)。见 §5.11——决策的真源在库里,
// 所以这个调用落到哪个副本都一样。
func (e *Engine) Approve(ctx context.Context, sessionID, approvalID, decision string) (bool, error)
// Snapshot 返回会话当前状态,给 GET /api/session 用。
// 是会话级流的「快照版」——客户端首屏用它对齐,之后靠流增量。
// ★ LiveRunID / Queued / LastSeq 必须**同源读取**(同一个事务),
// 否则会出现「快照说有 m_2,流又从更早的 seq 重放一遍 m_2」的重复气泡(§7.9 用例 3)。
func (e *Engine) Snapshot(ctx context.Context, sessionID string) (SessionSnapshot, error)
type SessionSnapshot struct {
LiveRunID string // run_archive 里 status='running' 的行;没有则空
Queued []QueuedMessage
LastSeq int64 // 会话级流的当前 seq,客户端据此决定 from
}trySchedule —— 全篇的核心,也是唯一的难写点:
// trySchedule 尝试为 sessionID 开一场 run。可以从任意 goroutine、任意副本调,幂等。
//
// 难写点:三件事必须原子——「判断闸空」「取空收件箱」「开 run 并占闸」。
// 少任何一步的原子性都会漏消息或开两场 run(不变量 8)。
// 本方案把三件事放进**同一个 DB 事务**,仲裁者是唯一索引,不是进程内的锁。
//
// 调用点有三个,缺一不可:
// - Enqueue 之后(消息到了,看看能不能立刻跑)
// - drive 收尾之后(闸空了,看看有没有排队的)
// - 进程重启 Reconcile 之后(inbox 里还有没答完的话,§7.8)
func (e *Engine) trySchedule(ctx context.Context, sessionID string) {
// 一个 DB 事务里完成全部临界区(不变量 8、9)
runID, merged, msgs, err := e.beginRunAtomic(ctx, sessionID)
// beginRunAtomic 内部:
// tx:
// msgs, ok := inbox.Drain(tx, sessionID) // 取空收件箱
// if !ok → 回滚,返回 ErrInboxEmpty
// merged := join(msgs, "\n\n")
// runLog.BeginRunInTx(tx, runID, sessionID, merged, agentName)
// // INSERT run_archive(status='running')
// // + run 级 seq=1 start 帧 + message_ids 列(§5.10)
// // ★ 撞 one_live_run_per_session 唯一索引
// // → ErrGateBusy → 回滚,Drain 自动还原
// sessionLog.AppendInTx(tx, sessionID, SessionEvent{
// Kind: SessRunStarted, RunID: runID,
// MessageIDs: ids(msgs), MergedText: merged,
// }) // 同一事务,runID 此刻才对外可见
// commit
// → bump sessionBuffer(推给会话级订阅者)
// → bump runBuffer(推给 run 级订阅者)
if errors.Is(err, ErrInboxEmpty) { return } // 没货可跑
if errors.Is(err, ErrGateBusy) { return } // 闸忙:并发 trySchedule 的输家,静默退出。
// 消息已被赢家的事务处理,或在 inbox 里等收尾
if err != nil {
// 开跑失败不是 HTTP 错误(没有 HTTP 请求在等)——
// 事务已回滚,消息还在收件箱,由下次重试,并写一帧会话级错误。决策见 §11 问题 2。
e.reportScheduleError(ctx, sessionID, err)
return
}
runCtx, cancel := context.WithCancel(e.ctx) // 不变量 2:进程 ctx 的子 ctx
st := &runState{
id: runID, sessionID: sessionID, cancel: cancel,
messageIDs: ids(msgs), userText: merged, compact: &CompactState{},
}
e.registerRun(runID, cancel) // 纯本地句柄表,只为 Stop/Delete 即时 cancel
messages, err := e.archive.ModelMessages(ctx, sessionID) // §5.4,冷热缓存
if err != nil { /* 走 error 终局,见 §7.6 */ }
messages = append(messages, schema.UserMessage(merged))
st.compact.Msgs, st.compact.Runs = messages, completedRuns(messages) // 工作副本
go e.drive(runCtx, st) // ← §7.3–7.6 的 drive
}哨兵去哪了:早期设计在事务开始前先占一个 id=="" 的进程内哨兵,防止两个 trySchedule 都判断闸空。现在「判断闸空」与「占闸」是同一个 INSERT——撞索引的一方整个事务回滚, 连 Drain 都自动还原,竞态被数据库吃掉了,特例也就没有存在的理由。 哨兵承担的另一半职责(「事务进行中不泄露 runID」)本来就不是它的——那是不变量 9 的事。
drive 的收尾:
func (e *Engine) drive(runCtx context.Context, st *runState) {
defer e.unregisterRun(st.id) // 本地句柄表除名
defer st.cancel()
// ... §7.3–7.6 的 stream 循环、A/B 两路、审批挂起 ...
// 收尾,最后三步:
// ① 放闸:Finish 一个事务里写终局帧 + status→complete/error/stop + ArchivePatch。
// status 离开 'running' 的那一瞬间,唯一索引行释放 = 闸开。
// ★ 放闸不是改一个内存变量,是这笔事务本身——所以「放闸」与「事实落库」不可能背离。
// ② 广播落幕(不变量 8:终局落库与再调度之间不留缝)
e.sessionLog.Append(e.ctx, st.sessionID, SessionEvent{
Kind: SessRunTerminal, RunID: st.id, TerminalKind: kind,
})
// ③ 闸空了,看看收件箱
e.trySchedule(e.ctx, st.sessionID)
}放闸与再调度之间为什么不会漏消息:Finish 的事务一提交, 「该会话没有 running 行」与「r_17 已终局」同时成为数据库事实。 此刻若有并发的 Enqueue:它 inbox.Put(落库)→ trySchedule → beginRunAtomic 要么赶在 ③ 之前提交(③ 随后撞索引,ErrGateBusy 静默退出),要么反之(③ 开跑,它撞索引)。 两边都调 trySchedule,数据库保证恰好一个赢——这正是 §7.10 竞态表前三行「靠什么保证」的内容。 消息不会搁浅,因为它先落库再触发调度(不变量 4 + 8 的合力)。
Enqueue 伪代码:
func (e *Engine) Enqueue(ctx context.Context, sessionID, messageID, clientID, expectedRunID, text string) (int64, error) {
if n, _ := e.inbox.PendingCount(e.ctx, sessionID); n >= maxQueueDepth {
return 0, ErrQueueFull // → 422 + 当前条数
}
live, _ := e.runLog.LiveRunID(e.ctx, sessionID) // SELECT run_archive WHERE status='running'
if expectedRunID != "" && expectedRunID != live {
return 0, &StaleViewError{LiveRunID: live} // → 409 + 当前 liveRunID(fencing)
}
seq, err := e.inbox.Put(e.ctx, sessionID, messageID, clientID, text) // ① 落库(进程 ctx,不变量 3)
if errors.Is(err, ErrMessageIDTaken) { return 0, err } // → 409,正当的重复投递
if err != nil { return 0, err } // → 500。唯一的意外失败路径
_, err = e.sessionLog.Append(e.ctx, sessionID, SessionEvent{ // ② 落库 + 广播
Kind: SessMessageQueued, MessageID: messageID, ClientID: clientID, Text: text,
})
if err != nil {
// 消息已入收件箱但没广播出去。**不回滚 inbox**——
// 用户的字比一帧通知重要(不变量 4 的优先级排序)。
// 客户端下次 Snapshot / 重连时会从 Pending() 看到它。
log.Printf("会话级帧落库失败: %v", err)
}
e.trySchedule(e.ctx, sessionID) // ③ 闸空就立刻开跑
return seq, nil
}messageID 由客户端给,Put 不返回它,这带来一个好处:message_queued 帧的 ID 与前端 pending 气泡的 ID 天然是同一个,对齐不需要映射表。 这一点在「帧比 202 先到」(§7.1)时是必需的而不是锦上添花:帧先到意味着客户端 只能从帧里认出自己那条,而认出的依据必须是它发出去之前就已经知道的东西。 若 id 由服务端铸造,帧里就得额外背一个客户端的不透明键才够对齐(§11 问题 7 的 B 案)。
5.10 run_archive 的 message_ids
一场 run 可能消费多条 message,所以档案要记两件事:
| 列 | 含义 |
|---|---|
user_message |
合并后的整句(多条用 "\n\n" 连接)。压缩仍可破坏性改写它,语义不变 |
message_ids |
JSON 数组,记录这场 run 消费了哪些 messageID |
message_ids 是给 UI 用的:前端据此把 N 个排队气泡归组到同一个回答下面, 表达「这两句被一起回答了」。模型侧不需要它——模型看到的是 user_message, 它本来就该是「用户连说了两句」的自然形态。
Archive.AddRun(produced, userText, runID) 的签名不变,userText 传合并后的整句 (或压缩后的 modelUserText)。Archive 完全不知道「多条消息」这件事的存在—— 合并发生在 Inbox 与 Engine 之间,Archive 看到的永远是一句 user 输入。 这是把复杂度挡在正确边界外的结果。
5.11 Approval 与 Checkpoint
文件:
internal/run/approval.go、internal/run/checkpoint.go
把 guard.ApprovalInfo 挡在引擎外面。引擎只知道 Approval,不知道 guard。
type Approval struct {
Tool string // 请求审批的工具名
Args string // 工具参数
Message string // 兜底文案(info 类型对不上时用)
}transport 层的 middleware 或 handler 负责把 guard.ApprovalInfo 转成 Approval。
决策通道第一版就是跨副本的:决策是一张 DB 行,不是进程内的 chan。 早期设计用 pending map[string]chan string(副本 A 阻塞等待、决策 POST 落到副本 B → 404 → 审批永久卡死,§13.5),V4 直接跳过它——Go channel 不跨进程,而目标栈是多副本。
// Approvals:决策行落库(真源)+ 本进程等待者通知(加速)。
type Approvals struct {
db *sql.DB
mu sync.Mutex
waiters map[string]chan struct{} // approvalID → 决策到达信号。纯本地优化,不是真源
}
// Create 在 ask emit 审批帧**之前**落一行 decision='pending'。
// 行先于帧存在,所以「读者看到卡片」时决策一定已可写入(不变量 4 的同款顺序)。
func (a *Approvals) Create(ctx context.Context, sessionID, runID, approvalID, tool, args, message string) error
// Wait 阻塞到决策可用 / ctx 取消 / 超时。
// 双通道:waiters 通知(快路径,同副本)+ 低频轮询该行(慢路径,兜跨副本与通知丢失)。
func (a *Approvals) Wait(ctx context.Context, approvalID string) (decision string, err error)
// Decide 写决策:UPDATE approval SET decision=? WHERE session_id=? AND approval_id=? AND decision='pending'。
// 行不存在或已决 → false(transport 回 404)。写成功后 bump 本地 waiters——
// **持有 run 的副本不在本进程时没人可 bump,那边的轮询会兜住**。
func (a *Approvals) Decide(ctx context.Context, sessionID, approvalID, decision string) (bool, error)ask 闭包的五步因此变成(对照 §7.4):① 生成审批 id + Create 落行;② emit 审批帧; ③ Wait 阻塞(挂起的只是 drive 这个 goroutine,闸——也就是 run_archive 的 running 行——照常占着); ④ 决策从 POST /api/approval 进来,Engine.Approve → Decide 写库 + 唤醒; ⑤ emit approval_result,decision 交还 runner。runCtx 取消(Stop / Delete / 断连)时 Wait 从 ctx 分支醒来,ask 走 §7.4 的停止结局,pending 行由级联清理删除 (Delete 第 3 步;run 终局后遗留的 pending 行无害——卡片所在的流已关闭,重启 Reconcile 顺手清)。
Checkpoint 实现 adk.CheckPointStore。全局一份,进程内存,重启即丢。
type Checkpoint struct {
mu sync.Mutex
m map[string][]byte
}
func NewCheckpoint() *Checkpoint
func (c *Checkpoint) Get(_ context.Context, key string) ([]byte, bool, error)
func (c *Checkpoint) Set(_ context.Context, key string, value []byte) error5.12 Transport
文件:
internal/webui/(server.go / middleware.go / handler_*.go / dto.go / sse.go)
路由表:
| 路由 | handler | 做什么 |
|---|---|---|
GET / |
handleIndex | 返回静态页面(阶段一只用于冒烟,不是产品前端,§6) |
★ POST /api/session |
handleCreateSession | registry.Create() → 201 + {"sessionId","lastSeq":0}。无请求体 |
GET /api/session?id= |
handleSession | 准入检查(未登记 → 404)+ engine.Snapshot() → {liveRunId, queued, lastSeq} |
★ GET /api/session/stream?id=&from= |
handleSessionStream | 准入检查 + sessionLog.Subscribe() → 会话级 SSE(常驻,不自然结束) |
★ POST /api/message |
handleMessage | engine.Enqueue() → 202 + {"seq","messageId"};队列超上限 → 422;重复 messageId / 视图过期 → 409。不返回流 |
★ DELETE /api/message/:id?sessionId= |
handleCancel | engine.Cancel() → 204 / 404 |
★ DELETE /api/session/:id/inbox |
handleClearInbox | engine.ClearInbox() → 200 + {"cleared":N} |
★ DELETE /api/session/:id |
handleDelete | engine.Delete() → 204。级联停 run + 清五张会话表(run_log / run_archive / session_log / inbox / approval)+ 删登记 + 断开该会话所有订阅(§5.9) |
GET /api/chat/stream?run=&from= |
handleStream | runLog.Subscribe() → run 级 SSE(见终局帧即关) |
GET /api/session/history?id=&cursor=&limit= |
handleHistory | runLog.HistoryPage() |
POST /api/approval |
handleApproval | engine.Approve()(请求体带 sessionId,决策写库,§5.11) |
POST /api/stop |
handleStop | engine.Stop()(请求体带 sessionId + run) |
没有的路由(明确不留,免得将来被当成「忘了实现」):
POST /api/chat——「开一轮 run」这个入口不存在了,语义被/api/message+/api/session/stream取代。- 任何补发/恢复端点——理由见 §5.3。
每个 handler ≤ 15 行,业务判断一律在 internal/run 里。handleMessage 长这样:
func (s *Server) handleMessage(c *gin.Context) {
var req messageRequest
if err := c.ShouldBindJSON(&req); err != nil { c.Error(errBadRequest(err)); return }
if _, err := s.registry.Get(s.ctx, req.SessionID); err != nil { c.Error(err); return } // 准入,不变量 1
seq, err := s.engine.Enqueue(s.ctx, req.SessionID, req.MessageID, req.ClientID, req.ExpectedRunID, req.Text)
if err != nil { c.Error(err); return }
c.JSON(http.StatusAccepted, messageResponse{Seq: seq, MessageID: req.MessageID})
}六行。没有一个状态码是「因为你来得不是时候」——这正是解耦的兑现。 Enqueue 仍会返回 409,但那两种 409 表达的是「你重复投递了」和「你的视图过期了」, 都是客户端自己的错误,不是时机问题。也没有 engineFor 这种「选一个每会话引擎」的步骤—— Engine 是无状态单例,准入检查直接打 Registry。
202 为什么带响应体:messageId 确实是客户端自己给的,不需要回传; 但 seq 只有服务端知道,而它是会话级流的续传游标。没有它, 「投递」与「流」之间就没有对账锚点——客户端重连时只能用自己记得的 lastSeq, 分不清「没收到 m_1 的帧是因为它没入队」还是「我的 from 起点太靠后」。 一个 int64 换掉这个歧义,值得。
注意这里不能回
{"queued":true}之类的状态字段:那要求Enqueue同步知道trySchedule的结果,把异步调度变成同步等待,与解耦的初衷相悖。 「排队还是已开跑」由会话级流的帧报告,不由这个响应报告。
DTO:
type messageRequest struct {
SessionID string `json:"sessionId" binding:"required"`
MessageID string `json:"messageId" binding:"required"` // 客户端生成
ClientID string `json:"clientId" binding:"required"` // 设备标识,客户端生成 UUID 存 localStorage
ExpectedRunID string `json:"expectedRunId"` // fencing token,可空
Text string `json:"text" binding:"required"`
}
type messageResponse struct {
Seq int64 `json:"seq"`
MessageID string `json:"messageId"`
}
type sessionResponse struct { // POST /api/session 的 201
SessionID string `json:"sessionId"`
LastSeq int64 `json:"lastSeq"`
}
// SessionSnapshot 与 QueuedMessage 的线上形状(全篇 camelCase):
// {"liveRunId":"r_17","queued":[{"id":"m_2","clientId":"A-desktop","text":"…","seq":4}],"lastSeq":4}
// run 级 SSE 帧。身份是 (run, seq),见终局帧即由 Stream 关闭连接。
// 字段全 omitempty:每类帧只带自己用得上的那几个(§7.9 的样例逐条对得上)。
type runFrame struct {
Run string `json:"run"`
Seq int64 `json:"seq"`
Ts string `json:"ts"` // RFC3339 UTC
Kind string `json:"kind"`
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"`
Partial bool `json:"partial,omitempty"` // 阶段一产物,阶段二随 sealed 一起退役(§12.3)
}
// 会话级 SSE 帧。与 run 级 frame 平行,不共用类型。
type sessionFrame struct {
Seq int64 `json:"seq"`
Ts string `json:"ts"`
Kind string `json:"kind"`
MessageID string `json:"messageId,omitempty"`
ClientID string `json:"clientId,omitempty"`
Text string `json:"text,omitempty"`
RunID string `json:"runId,omitempty"`
MessageIDs []string `json:"messageIds,omitempty"`
MergedText string `json:"mergedText,omitempty"`
Resumed bool `json:"resumed,omitempty"`
TerminalKind string `json:"terminalKind,omitempty"`
}SSE 线格式:data: <JSON>\n\n,每帧写完立即 Flush。 sse.go 提供 Stream(run 级,见终局帧即 return)与 StreamSession(会话级,没有终止条件)。
5.13 错误体与错误映射中间件
非 2xx 的响应体统一定形:
{"error":{"code":"queue_full","message":"排队已满(10 条),先停一下当前任务?","detail":{"queued":10,"limit":10}}}code 是机器读的(前端按它分支),message 是人读的(可直接展示),detail 可空。
为什么必须有一个中间件:gin 的 c.Error(err) 只把错误记进 c.Errors, 不改状态码——不注册中间件的话,所有错误都会变成 200 空体。所以:
// middleware.go
// errorMapper 把 handler 通过 c.Error() 记下的领域错误映射成状态码 + JSON 体。
// 挂在链尾。SSE handler 不适用(header 已发出),流内错误走帧。
func errorMapper() gin.HandlerFunc {
return func(c *gin.Context) {
c.Next()
if len(c.Errors) == 0 { return }
err := c.Errors.Last().Err
status, body := mapErr(err) // 领域错误 → (状态码, errorBody)
c.AbortWithStatusJSON(status, body)
}
}映射表(领域错误 → 状态码 → code):
| 领域错误 | 状态码 | code |
何时发生 |
|---|---|---|---|
请求体不合法 / 缺必填 / from 不是数字 |
400 | bad_request |
客户端写错了 |
ErrSessionNotFound |
404 | session_not_found |
未登记的 sessionId(不变量 1) |
ErrRunNotFound |
404 | run_not_found |
订阅一个不存在的 run |
ErrMessageNotFound(= Inbox.Cancel 返回 false,§5.7) |
404 | message_not_found |
撤回一条不在 inbox 里的消息(已被 Drain 走,或从未存在,§7.9 用例 4) |
ErrMessageIDTaken |
409 | message_id_taken |
同一草稿重发,且它仍在收件箱里(已被 Drain 就不会撞,那一层由回放兜,§6.3 约束 6)。前端视为幂等成功 |
StaleViewError |
409 | stale_view |
expectedRunId 与当前 live 不符(detail.liveRunId 带当前值) |
ErrQueueFull |
422 | queue_full |
队列达 maxQueueDepth(detail.queued / detail.limit) |
ErrSealConflict 等存储/内部错误 |
500 | internal |
服务端的问题,message 不含细节 |
两种 409 都不是「你来得不是时候」——它们表达的都是客户端自己的状态错误 (重复投递、视图过期),与不变量 7 不冲突。
5.14 建表汇总
-- 会话身份(§5.6)
CREATE TABLE session (
session_id TEXT PRIMARY KEY,
created_at INTEGER NOT NULL
);
-- run 级事实(§5.3)
CREATE TABLE run_log (
run_id TEXT NOT NULL,
seq INTEGER NOT NULL,
ts INTEGER NOT NULL,
kind TEXT NOT NULL,
payload TEXT NOT NULL,
PRIMARY KEY (run_id, seq)
);
-- 模型视图(§5.4)。message_ids 见 §5.10
CREATE TABLE run_archive (
run_id TEXT PRIMARY KEY,
session_id TEXT NOT NULL,
created_at INTEGER NOT NULL,
status TEXT NOT NULL, -- running / complete / error / stop / failed
stop_requested INTEGER NOT NULL DEFAULT 0, -- Stop 的停止标记(真源,§5.9);
-- 不能把 status 提前改成 stop——那等于提前放闸
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);
-- ★ 闸放数据库,**第一版就如此,没有进程内形态**(§5.9)。
-- 插入失败本身就是「会话已有一场 run 在跑」
CREATE UNIQUE INDEX one_live_run_per_session ON run_archive(session_id) WHERE status='running';
-- 会话级事实(§5.8)
CREATE TABLE session_log (
session_id TEXT NOT NULL,
seq INTEGER NOT NULL,
ts INTEGER NOT NULL,
kind TEXT NOT NULL,
payload TEXT NOT NULL,
PRIMARY KEY (session_id, seq)
);
-- 会话级 seq 计数器:inbox.seq 与 session_log.seq 同源(§5.7)
CREATE TABLE session_seq (
session_id TEXT PRIMARY KEY,
seq INTEGER NOT NULL
);
-- 待办队列(§5.7)
CREATE TABLE inbox (
session_id TEXT NOT NULL,
message_id TEXT NOT NULL,
client_id TEXT NOT NULL,
text TEXT NOT NULL,
seq INTEGER NOT NULL,
created_at INTEGER NOT NULL,
PRIMARY KEY (session_id, message_id)
);
CREATE INDEX idx_inbox_session ON inbox(session_id, seq);
-- 压缩换掉的原文(§5.4 WriteRAG / SearchRAG)
CREATE TABLE compact_rag (
session_id TEXT NOT NULL,
run_id TEXT NOT NULL,
body TEXT NOT NULL,
created_at INTEGER NOT NULL
);
-- 审批决策行(§5.11)。决策的真源,跨副本成立;已决/遗留行随 run 终局或 Delete 级联清理
CREATE TABLE approval (
session_id TEXT NOT NULL,
run_id TEXT NOT NULL,
approval_id TEXT NOT NULL,
decision TEXT, -- NULL = pending;'approve' / 'reject'
created_at INTEGER NOT NULL,
decided_at INTEGER,
PRIMARY KEY (session_id, approval_id)
);6. 前端契约
产品前端是 Vue,属于独立 loop(§10 阶段三之后)。 本节只定契约—— 前端要消费什么、必须实现哪个状态机、哪些做法是错的。阶段一不写产品前端, 验收全程用 curl(§7.9 的每个用例都给了可直接执行的命令与期望字节)。
6.1 启动编排
页面加载
│
├─ ⓪ 有 sessionId 吗?(本地存的)
│ 有 → GET /api/session?id= 验一下:200 用它,404 走下一行
│ 无 → POST /api/session → 201 {"sessionId","lastSeq":0},存下来
│ ★ 不要自己 mint 一个 UUID 当 sessionId(§1.2)
│
├─ ① GET /api/session?id= → {liveRunId, queued[], lastSeq}
│ 用途:首屏对齐。画出 queued 气泡;若 liveRunId 非空,立刻挂 run 级流
│
├─ ② GET /api/session/stream?id=&from=lastSeq ← 常驻,页面活着就一直开
│ on message_queued → 画一个排队气泡(带撤回按钮)
│ on message_cancelled → 撤掉那个气泡
│ on run_started → ③ 挂 GET /api/chat/stream?run=<runId>&from=0
│ 把 messageIds 对应的气泡标记为 consumed
│ on run_terminal → run 级流自己会结束;这里只更新状态文案
│
└─ ③ run 级流(同时最多一条——闸保证每会话最多一场 run)
①② 的续传起点不对称,这是设计:run 级流从 0 开始(这个客户端一份都没看过), 会话级流从 lastSeq 开始(它只是补齐断开期间漏掉的几帧)。
6.2 消息气泡的状态机(前端只需实现这一个)
所有转移都由流帧驱动:
POST /api/message
│
┌──────────────────┴───────────────────┐
│ 失败 │ 202 {seq,messageId}
▼ ▼
[输入框内容还回] ┌───────────────┐
│ queued │ ← message_queued 帧画出
│ (可撤回) │
└───┬───────┬───┘
DELETE /api/message│ │ run_started.messageIds 含它
▼ ▼
[气泡消失] ┌───────────────┐
│ consumed │ ← 撤回按钮消失
│ (正在被回答) │
└───────┬───────┘
│ run_terminal
▼
┌───────────────┐
│ answered │ ← 与助手回复配成一对
└───────────────┘
四个状态对应服务端的三处存储:queued = inbox 里有行;consumed = inbox 行已删、 run_started.messageIds 含它、run 仍 running;answered = run_terminal 已到。
6.3 六条必须遵守的约束
- 发送按钮永远可用。 不存在「busy」这个概念——用户随时能投递,投递永远成功。 停止键按
liveRunId是否非空显隐,与发送键无关。 - 服务端回显,不要本地回显。
send()只 POST,用户气泡由message_queued帧画出 (帧里带text全文,正是为此)。POST 失败就把输入框内容还回去。 代价是本地回显的那点即时感没了(多一个 RTT),换来的是 所有客户端画的用户消息来自同一个 seq 序列——同步是免费的。 本地先画一个气泡会让两端时序不同,撤回时更容易对不上。 - 前端不保存任何服务端不知道的状态。 刷新后靠
Snapshot+ 会话级流冷启动重建, 不需要本地存储兜底对话内容。本地只存两样:sessionId(资源句柄)与clientId(设备标识)。 - 撤回的语义边界要在 UI 上表达清楚:只有
queued且尚未出现在任何run_started.messageIds里的气泡能撤回。一旦被消费,撤回按钮消失 (服务端Cancel会返回 404,但前端不该让用户点到)。 - 停止后必须提示队列还在:
Stop不清收件箱(§5.9),所以按下停止后如果还有排队消息, 它们会立刻开跑。停止按钮旁边要明示「还有 N 条排队,会继续」并提供一键清空 (DELETE /api/session/:id/inbox),否则用户会觉得「我明明停了它怎么又跑了」。 - 重发必须在回放到位之后,且复用同一个
messageId。 一次投递没收到响应 (超时 / 断网 / 用户以为没发出去)时,不能立刻原样重发——它可能已经落地了。 正确顺序是先重连会话级流、把from=lastSeq回放完:回放里出现同一个messageId(message_queued帧)就说明那句已进队列或已被消费,撤销重发;没出现才重发, 且重发必须带同一个 id(id 绑草稿不绑请求,§1.2)——这样即使抢在回放之前撞上, inbox 主键也会给 409 而不是插成第二条。 这条约束是「服务端不加去重表」的代价,落点在前端而不是存储层(§11 问题 7 的残留风险)。
6.4 clientId 的语义边界(要写进 UI 文案)
clientId 存 localStorage,所以同一浏览器的两个标签页读到的是同一个值。 「谁发的」这个标记只在跨浏览器 / 跨设备时可辨;同浏览器多标签页里, B 看不出 m_1 是 A 那个标签页发的(帧里 clientId 与自己相同)。
要区分标签页得把它挪到 sessionStorage(每标签页一份),代价是「关掉再开」就变成新设备。 两种语义各有用处,本方案选 localStorage 版本:认设备,不认标签页。 这不是缺陷,是要写进 UI 文案的约定——「A-desktop」是设备名,不是标签页名。
7. 完整链路:八幕
前六节讲的是「每个组件是什么」,这一节讲「它们怎么串起来」。 一个贯穿全节的例子:
- 会话
s_1——由POST /api/session登记过,里面已有两轮完成的 run:r_15、r_16; - 用户发「读一下 doc/19」→
m_1,闸空,立刻开跑r_17; r_17在跑一个几十秒的工具,用户等不及又发了「顺便看看 v1」→m_2、 「对比一下差异」→m_3,两条排队;r_17落幕,调度器把m_2 + m_3合并成一句交给r_18;r_18期间上下文超阈值,压缩换掉r_15;- 中途用户刷新了一次页面、进程重启了一次。
会话级 session_log 的 seq 在全节连续增长,是唯一的对账锚:
seq=1 message_queued(m_1) seq=2 run_started(r_17, [m_1])
seq=3 message_queued(m_2) seq=4 message_queued(m_3)
seq=5 run_terminal(r_17) seq=6 run_started(r_18, [m_2,m_3])
每幕末尾给「数据变化」,列的是存储增量(谁多了一行、谁的哪个字段变了)。 查这类系统不能只看日志——所有争议最后都要落到「哪张表的哪一行」。
7.1 第一幕:投递
页面加载时前端已经做过两件事(§6.1):拿到 sessionId(本地存的先 GET /api/session?id= 验一次,404 就 POST /api/session 重新登记),挂上常驻的会话级流。第一幕从按下发送开始。
POST /api/message 到达 handler。这里没有任何「时机」判断——handler 只问两件事: 这个会话登记过吗?存储写进去了吗?
POST /api/message {sessionId:"s_1", messageId:"m_1", clientId:"A-desktop", text:"读一下 doc/19"}
│
├─ registry.Get("s_1") —— 准入检查
│ ├─ 命中 → 继续(Engine 是无状态单例,没有「装配」这一步,§5.9)
│ └─ ErrSessionNotFound → 404 {"error":{"code":"session_not_found",…}} ← 不变量 1
│ **绝不隐式创建**:客户端 mint 的 id 进不了库
│
├─ engine.Enqueue(s.ctx, "s_1", "m_1", "A-desktop", "", text)
│ │ ↑ 用 s.ctx 而不是 c.Request.Context()(不变量 3):POST 断了,落库不能跟着断
│ ├─ ⓪ 队列深度检查(≥10 → 422)+ expectedRunID fencing(空串跳过,§5.9)
│ ├─ ① inbox.Put() → m_1 落库,返回会话级 seq=1。**用户的字从此不会丢**(不变量 4)
│ ├─ ② sessionLog.Append(message_queued)
│ │ → 落库 + bump → 所有会话级订阅者立刻收到
│ │ → 另一个标签页 / 另一台设备上立刻出现这条消息的排队气泡
│ └─ ③ trySchedule(s_1)
│ ├─ beginRunAtomic:一个事务里
│ │ inbox.Drain → [m_1]
│ │ runLog.BeginRunInTx → INSERT r_17 档案行(status='running')
│ │ ← 唯一索引没撞上 = 闸空;撞上 = 闸忙,整个事务回滚(§5.9)
│ │ + run 级 seq=1 的 start 帧
│ │ sessionLog.AppendInTx(run_started{r_17, [m_1]}) → 会话级 seq=2
│ │ commit → bump 两个缓冲 ← 不变量 8、9:runID 此刻才对外可见
│ ├─ 建 runState{r_17}(drive 独占)+ archive.ModelMessages() + 用户这句
│ └─ go drive(runCtx, runState)
│
└─ 202 {"seq":1,"messageId":"m_1"} ← JSON,不是流
客户端此时已经通过会话级流收到了 message_queued(m_1) 和 run_started(r_17,[m_1]), 后者触发它去挂 GET /api/chat/stream?run=r_17&from=0。202 的响应体只是确认,不承载内容。
帧可能比 202 先到。 Enqueue 是同步的,②③ 在返回前就把帧推出去了; SSE 写浏览器比 HTTP 响应快是常事。所以前端不能依赖「先拿到 202 再收帧」的顺序, 必须用 messageId 把两边对上(§6.3 约束 2 说的「服务端回显」就是这个意思)。 seq 在响应体里的用途是对账,不是排序依据。
数据变化:
session 不变(r_17 之前 s_1 就已登记;这一幕只读它)
inbox + m_1 (seq=1) → 随即被 Drain 删除(净变化:空)
session_log + seq=1 {message_queued, m_1, clientId:"A-desktop", "读一下 doc/19"}
+ seq=2 {run_started, r_17, messageIds:[m_1], mergedText:"读一下 doc/19"}
session_seq s_1 的计数器 0 → 2
run_archive +行: r_17 | s_1 | user_message:"读一下 doc/19" | message_ids:["m_1"]
| status:"running" | produced_json:NULL | is_completed:0
run_log + r_17 seq=1 {kind:"start", text:"读一下 doc/19"}
Archive 内存 只读:ModelMessages() 返回 [r_15…, r_16…, user:"读一下 doc/19"]
runState (进程内)drive goroutine 诞生,持有 r_17 的全部临时状态;闸的真源是
run_archive 里那行 status='running',不在任何进程内变量里
7.2 第二幕:排队
r_17 在跑工具,耗时几十秒。用户等不及,又打了两句。
要求:这两句必须都能发出去,而且所有客户端都看得见它们在排队。 这不是体验优化,是不变量 7 的直接推论——投递不因状态冲突失败。 任何「因为正在跑所以拒绝」的设计都违反它,无论拒绝得多客气:灰掉的发送键、 409 run_in_progress、前端本地拦截,都算。
POST /api/message {messageId:"m_2", clientId:"A-desktop", expectedRunId:"r_17", text:"顺便看看 v1"}
├─ inbox.Put → m_2 落库(会话级 seq=3)
├─ sessionLog.Append(message_queued) → 所有客户端画出 m_2 的排队气泡
└─ trySchedule(s_1) → beginRunAtomic 撞上 one_live_run_per_session 唯一索引
(r_17 的 running 行还在)→ ErrGateBusy → 整个事务回滚,Drain 自动还原
→ **静默返回,零副作用**
POST /api/message {messageId:"m_3", …, expectedRunId:"r_17", text:"对比一下差异"}
└─ 同上 → m_3 排队(会话级 seq=4)
trySchedule 的早退不是丢弃——消息已经在 inbox 里落库了, r_17 收尾时会再调一次 trySchedule(第六幕)。这正是不变量 8 要保的事: 放闸与再调度之间不能有缝。有缝的话,这两条会一直躺到下一条消息进来才被捞起, 用户看到的就是「我停完之后它自己又跑了一轮旧的」。
expectedRunId:"r_17" 的作用:客户端是在「看见 r_17 在跑」的前提下发的这两句。 若实际上 r_17 已落幕、r_18 都开跑了,服务端回 409 stale_view—— 这不是拒绝投递,是告诉客户端「你的画面过期了,先对齐视图再发」。完整判断见 §5.9。
数据变化:
inbox + m_2 (seq=3) + m_3 (seq=4)
session_log + seq=3 {message_queued, m_2, clientId:"A-desktop", "顺便看看 v1"}
+ seq=4 {message_queued, m_3, clientId:"A-desktop", "对比一下差异"}
session_seq 2 → 4
run_archive 不变:r_17 仍 running——这一行就是闸本身(§5.9)
run_log r_17 继续追加它自己的帧(run 级 seq 2,3,4…)
Archive 内存 不变
所有客户端此刻看到的画面完全一致:一条正在跑的回答 + 两个可撤回的排队气泡。 一致性不是同步出来的,是「大家都读同一张 session_log」的自然结果(§4.2)。
7.3 第三幕:模型开口,一句话变成两件事
drive 把第一幕取好的 messages 交给 eino Runner,模型开始吐字。 吐出的每条 *schema.Message 在 drive 的 stream 循环里一变二:
- A 路(给模型的):只有 root agent 的消息被攒进一个 list,一轮结束时整体序列化成
produced_json——下一轮 Archive 的原料(第六幕用)。子代理的消息不进档案。 - B 路(给人的):
Classify把它翻译成领域 Event(§5.1),经emit写进 RunLog。 这是外界观察这轮 run 的唯一出口。
进图前先认识两个词:
- emit:drive 里「写一帧进库」的闭包。写失败会记下
persistErr并取消整轮 run—— 帧写不进库就不许推给读者(不变量 4:先落库,再推浏览器); - sealed(定稿):流式正文先以 Partial 帧在内存里反复更新(不碰库), 流结束时才把最终全文一次落库(定义与逐帧例子见 §5.1,伪代码见 §5.3)。 这是阶段一机制;阶段二的增量协议下「哪一帧才算数」这个问题不成立, sealed 连同整套 Partial 机制一起消失(§12.3)。阶段二第 14 步之后正文随 append 进库。
模型吐 *schema.Message(eino 包成 AgentEvent,流进 drive 的循环)
│
├─ Classify(agent, mv, msg) → (Event, ok) 纯函数;ok=false → 这条没有可呈现内容,跳过
│
├─ A 路:agentName == root → msgs = append(msgs, msg) 子代理不进档案
│
└─ B 路:emit(ev) → runLog.Append
├─ Partial → 只进内存,预留下一个 seq,库不动
├─ 定稿 → AppendSealed 按预留号落库(sealed),订阅者可见
├─ Drop → 模型流出失败,预留号作废,不落库
└─ Discard → 半截被最终结果取代(例如变成了工具调用),静默丢掉
作废不留空洞:库内 max 从没动过,下一条持久帧自然接上
数据变化(模型先回话,再调 read_file 读文件):
run_log + r_17 seq=2 {kind:"message", role:"assistant", text:"好的,我来读…"}
← Partial 帧在内存预留 seq=2 反复更新,sealed 时才落库(§5.1)
+ r_17 seq=3 {kind:"tool_call", tool_calls:[{name:"read_file", args:"{\"path\":\"doc/19-…-v4.md\"}"}]}
+ r_17 seq=4 {kind:"tool_result", tool_name:"read_file", text:"<文件原文>"}
drive 内存 produced(A 路)+= [assistant:"好的,我来读…", assistant:{tool_calls}, tool:"<文件原文>"]
run_archive 不变:r_17 仍 running,produced_json 仍 NULL ← A 路在落幕前不写任何库
Archive 内存 不变:本轮第一次调模型未超阈值,压缩没触发
读者从哪来?第一幕挂上 run 级流的那个 handler 是第一个,但 run 不要求有读者: 刷新页面走 GET /api/chat/stream?from=N 续传、第二个标签页、将来的 IM/cron 与 MQ 投递(§10 阶段三) 都只是又一个 Subscribe。一个读者都没有时,run 照跑、帧照落库(不变量 2:run 的命不属于任何连接)。 所以 B 路的终点是 RunLog 而不是 SSE——执行与观察彻底解耦,新读者类型接入时一行引擎代码都不用改。
7.4 第四幕:中途停顿,等人拍板
模型要调一个需要审批的工具,eino 把 run 中断。drive 里构造的 ask 闭包接住中断,做五件事:
- 生成审批 id,
approvals.Create先落一行 decision=NULL 的审批行(§5.11:行先于帧存在); emit一帧 approval——读者立刻看到审批卡片(走的就是第三幕的 B 路);- 挂起:
approvals.Wait阻塞在双通道上(本进程通知 + 低频轮询审批行),什么都不干; - 决策从
POST /api/approval进来,Engine.Approve→Decide写库 + 唤醒等待者 (决策的真源是审批行,所以这个 POST 落到哪个副本都一样;与 Stop / 断连的竞态处理见 §5.11); emit一帧 approval_result,把 decision 交还 runner,run 从原地继续(回到第三幕)。
要点:挂起的只是 drive 这个 goroutine——闸没放(本会话开不了第二轮)、 流没断(读者先看到卡片、再看到后续)。若用户等不及按了 Stop,runCtx 取消, ask 从 Done 分支醒来、清掉挂起表,run 直接进入第六幕的「停止」结局。
这里的交互设计值得单说一句:审批挂起期间闸不放,所以此时投递的消息一律排队。 用户看到的是「一张审批卡片 + 几个排队气泡」,而不是「输入框灰了、打字没反应」。 同一个机制(闸不放),换掉「投递会被拒绝」这一条,体验从「困惑」变成「我先把下一句说了」。 这也是不变量 7 与不变量 8 联手的结果:投递永远成功,成功之后由调度器决定何时跑。
数据变化(模型接着要调 bash,命中审批;用户点了允许):
approval + 行 {s_1, r_17, "s_1-a1", decision:NULL} ← ask 第 1 步(先于帧)
→ decision:"approve", decided_at:T ← POST /api/approval 送达后
run_log + r_17 seq=5 {kind:"approval", tool:"bash", args:"…"} ← ask 第 2 步,读者看到审批卡片
(drive 挂起在 Wait 上,期间持久状态只有审批行一处变化)
+ r_17 seq=6 {kind:"approval_result", text:"allow"}
+ r_17 seq=7 {kind:"tool_call", tool_calls:[{name:"bash", args:"…"}]} ← runner 恢复,回到第三幕
+ r_17 seq=8 {kind:"tool_result", tool_name:"bash", text:"<执行输出>"}
run_archive 不变:仍 running——挂起只冻结 goroutine,不冻结存储
Archive 内存 不变
7.5 第五幕:压缩在暗处进行
compact 不是独立的一幕,它藏在第一、三幕的 middleware 链里:每次要调模型前, 如果上下文超了阈值,它就地改写发给模型的消息,并调 archive.Stage() 把 「丢了哪些轮、摘要是什么」记进内存(§5.4 有伪代码)。
这一幕只需要记住一件事:Stage 全程不碰库。压缩改动在第一到五幕都只活在内存里, 直到第六幕落幕时,才和终局帧在同一个事务里写进 run_archive。 中途失败怎么办?这正是第六幕要回答的问题。
数据变化(bash 输出回来后,下一次调模型前上下文超阈值,compact 命中,换掉 r_15):
Archive 内存 staged: false→true;snapMsgs/snapRuns ← 压缩前快照(回退基准)
runs: [r_15, r_16] → [r_16]
modelMsgs: 重装为 [r_16 历史…, user:"<r_15 的摘要>读一下 doc/19", 本轮已产消息…]
liveModelText: "" → "<r_15 的摘要>读一下 doc/19" pendingDrop: ["r_15"]
run_log + r_17 seq=9 {kind:"compact", text:"压缩:r_15 被换掉…"} ← 只追加,不改任何旧帧(§2)
compact_rag + r_15 被换掉的原文(WriteRAG,从此只以可检索形式存在)
run_archive 不变——这正是本幕的全部要点:r_15 的 produced_json 原封不动,压缩只活在内存
7.6 第六幕:落幕与再调度
r_17 的 stream 循环结束。drive 自包含地收尾,依次回答三个问题:
问题一:这轮算什么结局? terminalOf 按四个输入定终局,判断顺序就是优先级:
| 判断(按序) | 终局 | 为什么 |
|---|---|---|
persistErr != nil |
error | 第三幕写库失败引发的 cancel,让流循环只看得到假象 context.Canceled;真因在 persistErr,必须优先 |
err == nil |
complete | 正常跑完,A 路攒的 list 成为 produced_json |
stopped == true |
stop | 用户按了 Stop |
| 其他 | error | 模型 / API 报错 |
问题二:第五幕 Stage 的压缩改动怎么办? 只有 complete 才配提交—— CommitPatch() 取出补丁,交给 Finish 与终局帧同一事务写库; 其余一切情况先 RevertStage() 退回内存。还有一个容易漏的补偿: complete 但 Finish 本身写库失败时,同样必须 RevertStage—— 库没提交,内存就不能留着压缩结果,否则放闸后下一轮 ModelMessages 会读到 数据库里从未发生的压缩,模型视图和 run_archive 永久分叉(§5.4)。
问题三:这一轮的产出怎么接进下一轮? complete 且落库成功后 archive.AddRun(sessionID, produced, userText, runID)——第三幕 A 路攒的 list 进缓存, 成为下一轮第一幕的档案原料。闸也在这笔 Finish 事务里放开:status 离开 'running' 的那一瞬间,唯一索引行释放——放闸就是这笔事务本身,会话可以接下一条消息了。
闸的释放在 Finish 事务内原子完成;紧随其后还有两步,中间不许留缝(不变量 8):广播落幕 + 再调度。
drive 收尾
│
├─ kind := terminalOf(persistErr, err, produced, stopped) // 判断顺序见上表
├─ Finish(+ CommitPatch) 同一事务 // §5.3 不变
│ status → 终局 = **放闸**:run_archive 的 running 行消失,唯一索引释放(§5.9)
├─ 成功且 complete → archive.AddRun(s_1, produced, userText, r_17) // §5.4 不变
│
├─ ★ sessionLog.Append(run_terminal{r_17, "complete"}) → 会话级 seq=5
│ → 所有客户端更新状态文案;没挂 run 级流的客户端也从这里知道落幕了
│
└─ ★ trySchedule(ctx, s_1)
├─ beginRunAtomic:一个事务里
│ inbox.Drain → [m_2, m_3] ← **合并窗口的兑现点**
│ merged = "顺便看看 v1\n\n对比一下差异"
│ runLog.BeginRunInTx → r_18 档案行 + run 级 start 帧
│ user_message: merged message_ids: ["m_2","m_3"]
│ (撞上唯一索引 = 有并发者已开跑 → 回滚退出,§5.9)
│ sessionLog.AppendInTx(run_started{r_18, [m_2,m_3], merged}) → 会话级 seq=6
│ commit → bump
└─ go drive(runCtx, runState{r_18}),消息 = […历史, user:merged]
合并的结果:模型看到的是一句 user 输入「顺便看看 v1\n\n对比一下差异」, 一次回答覆盖两句。而不是跑两场 run、第一场的回答看不到第二句。
客户端收到 run_started{r_18, messageIds:["m_2","m_3"]},把 m_2、m_3 两个气泡 从 queued 归到 consumed,然后挂 GET /api/chat/stream?run=r_18&from=0。
数据变化:
run_log + r_17 seq=10 {kind:"complete"} ← 终局帧
run_archive r_17: status→complete, is_completed→1, produced_json→<A 路产出>
+行: r_18 | s_1 | user_message:"顺便看看 v1\n\n对比一下差异"
| message_ids:["m_2","m_3"] | status:"running"
inbox m_2, m_3 被 Drain 删除 → 空
session_log + seq=5 {run_terminal, r_17, "complete"}
+ seq=6 {run_started, r_18, [m_2,m_3], merged}
session_seq 4 → 6
Archive 内存 AddRun(s_1, r_17 产出);随后为 r_18 调 ModelMessages()
runState r_17 的消亡;r_18 的诞生(drive goroutine 独占持有)
落幕之后:持久状态的终态对照
| 存储 | r_18 开跑后的内容 | 谁写的 |
|---|---|---|
run_log(run 级事实) |
r_17 seq 1..10 全 sealed;r_18 seq=1 start | Append / AppendSealed / Finish / BeginRun |
run_archive(模型视图) |
r_17 complete + produced_json;r_18 running + message_ids | Finish / BeginRun,同一事务 |
session_log(会话级事实) |
seq 1..6:queued(m_1) → started(r_17) → queued(m_2) → queued(m_3) → terminal(r_17) → started(r_18) | Append / AppendInTx |
session(身份登记) |
s_1 一行,自 POST /api/session 起就没动过 |
Registry.Create(只在登记时写) |
inbox(待办队列) |
空 | Put / Drain / Cancel / Clear |
compact_rag |
r_15 被换掉的原文(第六幕压缩发生后) | WriteRAG |
approval |
本会话已决的审批行(第四幕),随 run 终局 / Delete 级联清理 | Approvals.Create / Decide |
session_log 是这个会话的完整编年史:六帧讲清了「谁在什么时候说了什么、 系统什么时候开始回答、哪些话被合并回答了」。排队消息在这里有痕迹, 所以「用户说过但还没被回答的话」是可查的——inbox 只告诉你还没被消费的, session_log 告诉你全部。两者不可互相重建(§1.3)。
7.7 第七幕:刷新与多端
这一幕没有服务端动作,全是读。但它是最容易做错的一幕,因为两条流的续传起点不对称。
r_18 正在跑,用户在 A 设备按了刷新,同时 B 设备第一次打开这个会话:
A 刷新(本地存着 sessionId=s_1)
├─ GET /api/session?id=s_1
│ → 200 {"liveRunId":"r_18","queued":[],"lastSeq":6}
│ (若 s_1 已被删 / 从未登记 → 404 session_not_found → 前端走 POST /api/session 重来)
├─ 首屏:从 GET /api/session/history 拉 r_17 的完整帧、挂 r_18 的 run 级流 from=0
└─ 挂会话级流 GET /api/session/stream?id=s_1&from=6 ← ★ from=lastSeq,不是 0
B 首次打开(同一个 s_1,比如从链接进来)
└─ 完全相同的三步。差别只在 B 的 run 级流要从 0 开始重放 r_18 已产生的帧
为什么 run 级从 0、会话级从 lastSeq:
- run 级流是这个客户端对 r_18 的视图,它一帧都没看过,所以从 0 开始, Subscription 先重放库里的 1..N,再阻塞等 N+1(§5.2);
- 会话级流是会话的编年史,快照里已经把 1..6 的事实讲完了 (
liveRunId+queued就是 seq 1..6 的当前态投影),再从 0 重放一遍 会让 m_1/m_2/m_3 的排队气泡再画一次。
这也是 §5.9 强调 Snapshot 的 Queued 与 LastSeq 必须同源读取的原因: 若先读 queued(看到 m_2)再读 lastSeq(此时 m_2 的帧已推到 seq=7), 客户端会从 7 开始订阅、永远看不到 m_2 的帧,气泡就成了孤儿。
多端的真正含义:A 和 B 收到的是同一行 session_log 的两次投递, 不是两份各自维护的状态。所以「多端同步」不是一个功能,是存储结构的推论—— 不存在同步逻辑,也就不存在同步 bug。
数据变化:无。这一幕对五份持久状态零写入。
7.8 第八幕:进程重启
进程在 r_18 跑到一半时被杀(部署、OOM、panic)。重启后 Server 按固定顺序做三步—— 顺序是必须的:先补 run 级终局帧,再补会话级 run_terminal,最后才 trySchedule。 反过来做的话,客户端可能在 run_terminal(r_18) 到达前去挂 r_18 的 run 级流, 然后永远等不到那条终局帧。
启动
├─ ① failed, _ := runLog.Reconcile(ctx)
│ ├─ 遗留 running 的 run → run_archive.status = failed
│ ├─ ★ 给每个这样的 run **补一帧 kind:"error" 的 run 级终局帧**(§5.3)
│ │ 没有这帧,存着 r_18 的客户端重连后会一直挂在 run 级流上等终局,永远等不到
│ └─ 返回 []FailedRun{{s_1, r_18}}
│
├─ ② for _, f := range failed {
│ sessionLog.Append(ctx, f.SessionID, run_terminal{f.RunID, "error"})
│ }
│ ★ 这一步只能由 Server 做:RunLog 不认识 session_log,SessionLog 不认识 run_archive。
│ 两个真源各自只管自己那一层,跨层的补偿放在编排层(§3 的依赖方向)。
│
├─ ③ pending, _ := sessionLog.Reconcile(ctx) → 所有 inbox 非空的 sessionID
│
└─ ④ 对每个 pendingSession:engine.trySchedule(ctx, sessionID)
→ 重启前排队的消息**继续被回答**,不静默丢弃
→ run_started 帧带 resumed:true,UI 明示「这条是重启前排队的」
为什么自动继续而不是等用户确认:不变量 4 说用户的字比输出帧贵重。 既然它已经落库了,进程重启就不是丢弃它的理由——这与不变量 2 「run 的命不属于任何连接」是同一个精神:执行的生命周期独立于任何偶然事件。
r_18 自己不会被恢复。 它已经 failed,产出的半截回答留在 run_log 里可读, 但 produced_json 是 NULL——半截产出不进模型历史(§5.3 Finish 的约定)。 下一轮模型看到的是「用户说了 m_2+m_3」+「上一轮失败了」,而不是半截回答。 这是刻意的:半截内容进历史会让模型以为自己说过那些话。
阶段一的已知损失:如果进程崩在 Partial 帧 seal 之前,那条助手正文彻底没了 (它从没落过库)。这个窗口在阶段一是敞开的,阶段二靠「消息从 GENERATING 就持久化」 从结构上消掉它(§9.2、§12)。
数据变化:
run_archive r_18: status running → failed, is_completed 仍 0, produced_json 仍 NULL
run_log + r_18 seq=N {kind:"error", text:"进程重启,run 未完成"} ← 补的终局帧
session_log + seq=7 {run_terminal, r_18, "error"}
inbox 若重启时还有 m_4 → 仍在(这就是 pendingSession 的判据)
session 不变
Engine 无状态单例,重启后不需要任何装配——runState 随旧进程消亡,
Reconcile 补完事实后 trySchedule 直接可跑
7.9 业务用例链路:从用户视角看路由怎么串
§7.1–7.8 是技术链路(八幕),每幕末尾的「数据变化」列的是存储增量。 本节从用户操作出发,看路由、SSE 流、UI 状态怎么配合,每个用例给出线上真实字节—— 验收就是把这些 curl 敲一遍、逐字节对(§6 开头说的「验收全程用 curl」指的就是本节)。
样例约定(下面所有 JSON 都按这个写):
- 两条流都是
data: <JSON>\n\n,不带 event 名(§5.12)。 说「会话级流」=GET /api/session/stream?id=&from=,背后sessionLog.Subscribe(), 页面加载时挂一次、常驻不断开,一个会话一条; 说「run 级流」=GET /api/chat/stream?run=&from=,背后runLog.Subscribe(), 收到run_started才新挂,一个 run 一条、见终局帧即关。 两者生命周期不同,这是 §4 三级订阅的核心。 - run 级帧 =
runFrame,身份字段run+seq;会话级帧 =sessionFrame, 身份字段只有seq,指向 run 用runId。 两套 seq 是独立命名空间(§5.5)——看到seq:2得先问「哪条流」。 - 帧字段全是
omitempty,每类帧只带自己用得上的那几个(§5.12)。 ts是 RFC3339 UTC,样例里缩写成T0、T1… 省宽度;…表示省略与前一行相同的run/ts/agent字段,不是合法 JSON。- 会话
s_1、设备clientId:"A-desktop",沿用 §7 前八幕的示例数据(r_17 / m_1 / m_2)。 - seq 只在本用例内自洽:用例 1→2 是一条连续时间线(seq 接着长), 用例 3 之后各自从自己的前置状态起算,不要跨用例对齐数字。
- 错误体一律是 §5.13 的三段式
{"error":{"code","message","detail"}}; 样例里为了省宽度只写code与detail,message用…代替。 - 适用范围:单副本。 以下帧序列在多副本下不全部成立——审批的等待通道是 Go channel、闸是进程内 mutex(§5.9、§5.11 各有一条 ⚠️)。多副本要改的三处见 §13.5, 改完后本节用例的帧形状不变,变的是它们由谁写、由谁推。
用例索引(1–6 是主干,7–16 是打断路径与边界):
| # | 场景 | 主要涉及的路由 / 机制 |
|---|---|---|
| 1 | 首次打开页面 + 首次发消息 | POST /api/session、GET /api/session、两条流的挂载时机 |
| 2 | 已有 run 在跑时发消息 | 撞闸早退、合并窗口、两种 409 |
| 3 | 刷新页面 | GET /api/session、两条流续传起点不对称 |
| 4 | 撤回排队消息 | DELETE /api/message/:id、乐观更新与 404 |
| 5 | 多标签页 / 多设备同步 | 同一行 session_log 推给两条连接、clientId 的语义边界 |
| 6 | 进程重启 | 两个 Reconcile 的编排顺序、resumed:true |
| 7 | 审批挂起期间排队 | POST /api/approval、闸没放但收件箱能收 |
| 8 | 停止 | POST /api/stop、停止不清收件箱 → 排队消息立刻开跑 |
| 9 | 清空收件箱 | DELETE /api/session/:id/inbox、停止之后真正静下来 |
| 10 | 删会话(= 用户点「新会话」) | DELETE /api/session/:id、失效场景 A(§8) |
| 11 | 未登记 / 已删除的 sessionId | 404 session_not_found、不变量 1 |
| 12 | 队列上限 | 422 queue_full |
| 13 | 滚到顶翻历史 | GET /api/session/history 与流帧的接缝 |
| 14 | SSE 单独断线重连 | from=seq 续传(≠ 用例 3 的整页刷新) |
| 15 | run 中途压缩 | kind:"compact" 帧、压缩换掉旧 run 后历史读到什么 |
| 16 | inject 插话(后置能力) | delivery:"inject"、§11 |
用例 1:首次打开页面 + 首次发消息
用户动作:打开页面,输入「读一下 doc/19」,按回车
时序:
⓪ 本地没有 sessionId(第一次来)
→ POST /api/session → 201 {"sessionId":"s_1","lastSeq":0},存进 localStorage
★ 前端不 mint 这个 id(§1.2、§6.1)
① GET /api/session?id=s_1 → {"liveRunId":"","queued":[],"lastSeq":0}
随即挂上会话级流 GET /api/session/stream?id=s_1&from=0(★ 常驻,页面活着就一直开)
UI:空页面,无排队气泡,无 run 流
② POST /api/message {messageId:"m_1", …} → 202 {"seq":1,"messageId":"m_1"}
UI:**不画任何气泡**,等 ③ 的帧(§6.3 约束 2:服务端回显)
③ 会话级流推:message_queued(m_1, clientId:"A-desktop", text:"读一下 doc/19")
UI:画出 queued 气泡(带撤回按钮)
④ 会话级流推:run_started(r_17, messageIds:[m_1])
UI:**新挂一条** run 级流(GET /api/chat/stream?run=r_17&from=0,见终局帧即关)
queued 气泡 → consumed
⑤ run 级流推:message(role:"assistant", text:"好", partial:true) → text:"好的,我来…" → …
UI:助手气泡逐字更新(阶段一是快照全文,阶段二改成增量 append,§12)
⑥ run 级流推:终局帧 kind:"complete" → 这条流自己关闭
会话级流推:run_terminal(r_17, "complete")
UI:助手气泡定稿,consumed → answered
数据样例:
→ POST /api/session
← 201 {"sessionId":"s_1","lastSeq":0}
→ GET /api/session?id=s_1
← 200 {"liveRunId":"","queued":[],"lastSeq":0}
→ POST /api/message
{"sessionId":"s_1","messageId":"m_1","clientId":"A-desktop","text":"读一下 doc/19"}
← 202 {"seq":1,"messageId":"m_1"}
会话级流 GET /api/session/stream?id=s_1&from=0 ← 页面加载时常驻,一直开着
data: {"seq":1,"ts":"T0","kind":"message_queued","messageId":"m_1","clientId":"A-desktop","text":"读一下 doc/19"}
data: {"seq":2,"ts":"T0","kind":"run_started","runId":"r_17","messageIds":["m_1"],"mergedText":"读一下 doc/19"}
run 级流 GET /api/chat/stream?run=r_17&from=0 ← 由上面 seq=2 那帧触发挂载
data: {"run":"r_17","seq":1,"ts":"T0","kind":"start","text":"读一下 doc/19"}
data: {"run":"r_17","seq":2,"ts":"T1","kind":"message","agent":"tako","role":"assistant","text":"好","partial":true}
data: {"run":"r_17","seq":2,"ts":"T2","kind":"message",…,"text":"好的,我来读一下 doc/19。"}
↑ 同一 seq 再推一次 = 定稿(阶段一的 Partial 机制,阶段二整体退役,§12.3)
data: {"run":"r_17","seq":3,"ts":"T2","kind":"complete"}
会话级流
data: {"seq":3,"ts":"T2","kind":"run_terminal","runId":"r_17","terminalKind":"complete"}
终局是两帧不是一帧:run 级流自己以 kind:"complete" 收尾并关闭, 会话级流另推一帧 run_terminal,让没挂 run 级流的客户端也知道落幕了。二者不可互替。
②③ 的顺序不保证:Enqueue 是同步的,帧可能在 202 之前就到了浏览器。 前端按 messageId 对齐,不依赖「先拿响应再收帧」(§7.1)。
用例 2:发消息时已有 run 在跑
用户动作:r_17 正在跑,用户又发「顺便看看 v1」
时序:
① POST /api/message {messageId:"m_2", expectedRunId:"r_17", text:"顺便看看 v1"} → 202
② 会话级流推:message_queued(m_2) → UI 画 queued 气泡(排在 r_17 后面)
③ r_17 落幕 → run_terminal(r_17) → trySchedule 捞起 m_2 → run_started(r_18, [m_2])
UI:m_2 queued → consumed,挂 r_18 的 run 级流
④ r_18 落幕 → run_terminal(r_18) → UI:m_2 consumed → answered
数据样例(承接用例 1,会话级 seq 已到 3):
→ POST /api/message
{"sessionId":"s_1","messageId":"m_2","clientId":"A-desktop","expectedRunId":"r_17","text":"顺便看看 v1"}
← 202 {"seq":4,"messageId":"m_2"}
会话级流
data: {"seq":4,"ts":"T3","kind":"message_queued","messageId":"m_2","clientId":"A-desktop","text":"顺便看看 v1"}
↑ 后面没有 run_started——trySchedule 撞闸早退(§7.2)。
「排队」这件事只由这一帧表达,inbox 里的行是它的存储对应物。
(几十秒后 r_17 落幕,两帧先后到,前端不需要轮询)
data: {"seq":5,"ts":"T9","kind":"run_terminal","runId":"r_17","terminalKind":"complete"}
data: {"seq":6,"ts":"T9","kind":"run_started","runId":"r_18","messageIds":["m_2"],"mergedText":"顺便看看 v1"}
→ GET /api/chat/stream?run=r_18&from=0 ← 由 seq=6 触发
data: {"run":"r_18","seq":1,"ts":"T9","kind":"start","text":"顺便看看 v1"}
…
若合并窗口里排了两条(§7.2 的 m_2 + m_3),run_started 长这样—— messageIds 是 UI 表达「这两句被一起回答了」的唯一依据:
data: {"seq":6,"ts":"T9","kind":"run_started","runId":"r_18","messageIds":["m_2","m_3"],
"mergedText":"顺便看看 v1\n\n对比一下差异"}
只有两种 409,都是客户端自己的错,不是时机问题(§5.12、§5.13):
① expectedRunId 对不上(前端以为还是 r_16,其实 r_17 已开跑)
→ {"sessionId":"s_1","messageId":"m_9","clientId":"A-desktop","expectedRunId":"r_16","text":"…"}
← 409 {"error":{"code":"stale_view","message":"…","detail":{"liveRunId":"r_17"}}}
前端处理:刷新 Snapshot 与视图,把用户输入还回输入框让他重发。**不自动重试**——
自动重试等于替用户决定「这句话在新上下文下还是要说」,那是用户的判断。
(这次 fencing 检查在 `Put` 之前,消息**从未落库**,所以重发复用同一个 `messageId` 是安全的。)
② messageId 重复(重发 / 双击撞车),**且那条仍在收件箱里**
→ {"sessionId":"s_1","messageId":"m_2","clientId":"A-desktop","text":"…"}
← 409 {"error":{"code":"message_id_taken","message":"…","detail":{"messageId":"m_2"}}}
前端处理:视为幂等成功(这条已经在队列里),什么都不做。
**这个 409 只在消息还没被 Drain 时出现**:已被消费的 id 在 inbox 里没有行了,
重发会顺利插成新行、再被回答一次。挡住它的是 §6.3 约束 6——
先把会话级流回放到位,回放里出现同一个 `messageId` 就撤销重发(§11 问题 7 的残留风险)。
用例 3:刷新页面,run 正在跑
用户动作:r_17 跑到一半,用户刷新页面
时序:
① GET /api/session?id=s_1 → {"liveRunId":"r_17","queued":[m_2],"lastSeq":3}
UI:立刻画 m_2 的 queued 气泡(从 queued 取),并挂 r_17 的 run 级流(from=0,追赶已推的帧)
② run 级流:从 seq=0 重放已落库的帧 → 追上实时
③ 会话级流:from=3 挂上 → 只等新帧
数据样例(承接 §7 前八幕的编年史:seq 1=queued(m_1)、2=started(r_17)、3=queued(m_2)):
→ GET /api/session?id=s_1
← 200 {"liveRunId":"r_17",
"queued":[{"id":"m_2","clientId":"A-desktop","text":"顺便看看 v1","seq":3}],
"lastSeq":3}
→ GET /api/session/stream?id=s_1&from=3 ← 库里 seq>3 无帧,冷启动直接切实时,不重放
→ GET /api/chat/stream?run=r_17&from=0 ← 这条要追赶,重放已落库的 4 帧
data: {"run":"r_17","seq":1,"ts":"T0","kind":"start","text":"读一下 doc/19"}
data: {"run":"r_17","seq":2,"ts":"T2","kind":"message",…,"text":"好的,我来读一下 doc/19。"}
data: {"run":"r_17","seq":3,"ts":"T3","kind":"tool_call",…,"role":"assistant",
"toolCalls":[{"name":"read_file","args":"{\"path\":\"doc/19-运行引擎架构-v4.md\"}"}]}
data: {"run":"r_17","seq":4,"ts":"T4","kind":"tool_result",…,"role":"tool","toolName":"read_file","text":"<文件原文 41KB>"}
(此后是实时帧。前端分不出「重放」与「实时」——同一条流、同一套 seq、同一种帧)
两条流的续传起点不对称,这是设计而不是巧合(§7.7):run 级从 0(这个客户端一份都没看过), 会话级从 lastSeq(快照已经把 1..3 的当前态讲完了,重放会让 m_2 的气泡画两次)。 所以 Snapshot 的 Queued 与 LastSeq 必须同源读取,否则会出现 「快照说有 m_2,流又从 seq=2 重放一遍 m_2」的重复气泡(§5.9 那条 ★)。 前端按 messageId 幂等对齐可以兜住,但不该依赖它。
用例 4:撤回排队消息
用户动作:m_2 在排队(等 r_17),用户点撤回
时序:
① DELETE /api/message/m_2?sessionId=s_1 → 204,UI 立刻摘掉气泡
② 会话级流推:message_cancelled(m_2) → 所有客户端同步
数据样例:
→ DELETE /api/message/m_2?sessionId=s_1
← 204(无响应体)
会话级流(所有客户端都收到)
data: {"seq":4,"ts":"T5","kind":"message_cancelled","messageId":"m_2"}
↑ 只带 messageId:撤回不需要重述全文,气泡早就画在那了
已被消费的:
→ DELETE /api/message/m_1?sessionId=s_1 (m_1 已在 r_17 的 messageIds 里,inbox 里没这行)
← 404 {"error":{"code":"message_not_found","message":"…"}}
乐观更新与 404 的关系:前端点撤回时先本地摘掉气泡,再发 DELETE。 若回来 404(那条刚好被 trySchedule 抢走消费了,就是上面 m_1 那种情况), 本地状态与事实不符——纠正方式不是回滚那一次点击,而是等 run_started 帧到达: 它的 messageIds 含这条 messageId,前端据 §6.2 的状态机把气泡从 queued 直接推到 consumed。 流是唯一事实源,HTTP 响应只是操作回执,这条竞态因此不需要额外处理。
用例 5:多标签页 / 多设备同步
用户动作:同一会话在 tab A、tab B 都打开(或 A 在桌面、B 在手机),在 A 发消息
时序:
① A:POST /api/message → 202
② A 和 B 的会话级流都推:message_queued(m_1) → 两端同时画出 queued 气泡
③ 两端都收到 run_started(r_17,[m_1]) → 各自挂 r_17 的 run 级流,看到同样的回复
数据样例(两条会话级流是各自独立的 HTTP 连接,但读的是同一行 session_log):
tab A → POST /api/message {"sessionId":"s_1","messageId":"m_1","clientId":"A-desktop","text":"读一下 doc/19"}
← 202 {"seq":1,"messageId":"m_1"}
tab A 的流 data: {"seq":1,"ts":"T0","kind":"message_queued","messageId":"m_1","clientId":"A-desktop","text":"读一下 doc/19"}
tab B 的流 data: {"seq":1,"ts":"T0","kind":"message_queued","messageId":"m_1","clientId":"A-desktop","text":"读一下 doc/19"}
↑ 逐字节相同:seq、ts 都来自库里那一行,不是各自连接生成的。
所以两端对齐不需要时钟,按 seq 或 messageId 都能对上。
tab A 的流 data: {"seq":2,"ts":"T0","kind":"run_started","runId":"r_17","messageIds":["m_1"],"mergedText":"读一下 doc/19"}
tab B 的流 data: {"seq":2,…} ← 同一帧
→ 两端各自挂 GET /api/chat/stream?run=r_17&from=0,此后看到同样的回复流
这里没有任何「同步逻辑」:不存在把 A 的状态推给 B 的代码,只存在「A 和 B 都订阅了 同一张表的增量」。多端一致是存储结构的推论,不是功能(§4.2)。
clientId 的语义边界(详见 §6.4):它存 localStorage,所以同一浏览器的两个标签页 读到的是同一个值。「谁发的」只在跨浏览器 / 跨设备时可辨;同浏览器多标签页里, B 看不出 m_1 是 A 那个标签页发的(帧里 clientId 与自己相同)。 本方案选「认设备,不认标签页」,这要写进 UI 文案。
用例 6:进程重启,排队消息继续被回答
用户动作:m_2 在排队,r_17 在跑,进程崩溃重启
时序:
① 重启 → runLog.Reconcile 把 r_17 标 failed 并补一帧 kind:"error"
② Server 拿返回的 []FailedRun 给 s_1 补一帧会话级 run_terminal(r_17,"error")
③ sessionLog.Reconcile 发现 s_1 的 inbox 非空(m_2 还在)
④ trySchedule(s_1) → 捞起 m_2 → run_started(r_18,[m_2], resumed:true)
UI:气泡明示「这条是重启前排队的」
⑤ r_18 跑完 → run_terminal(r_18) → m_2 queued → answered
数据样例(崩溃前:session_log seq 1..3,inbox 有 m_2,r_17 档案行 status='running'):
—— 进程死掉。所有 SSE 连接随之断开,客户端进入重连 ——
重启后服务端做的四步(§7.8,顺序不可换):
runLog.Reconcile → r_17 status=failed;+ r_17 seq=N {kind:"error", text:"进程重启,本轮中断"}
sessionLog.Append → + 会话级 seq=4 {run_terminal, r_17, "error"}
sessionLog.Reconcile → 返回 ["s_1"]
trySchedule(s_1) → inbox.Drain=[m_2] → beginRunAtomic → r_18
客户端重连:
→ GET /api/session?id=s_1
← 200 {"liveRunId":"r_18","queued":[],"lastSeq":5}
会话级流 GET /api/session/stream?id=s_1&from=3 ← 补齐断开期间漏掉的帧
data: {"seq":4,"ts":"T6","kind":"run_terminal","runId":"r_17","terminalKind":"error"}
data: {"seq":5,"ts":"T6","kind":"run_started","runId":"r_18","messageIds":["m_2"],
"mergedText":"顺便看看 v1","resumed":true}
↑ resumed:true 只在 Reconcile 路径上为 true,是 UI 明示「重启前排队的」的钩子
run 级流 GET /api/chat/stream?run=r_18&from=0
data: {"run":"r_18","seq":1,"ts":"T6","kind":"start","text":"顺便看看 v1"}
…
会话级流
data: {"seq":6,"ts":"T8","kind":"run_terminal","runId":"r_18","terminalKind":"complete"}
一个执意重挂旧流的客户端也不会挂死:GET /api/chat/stream?run=r_17&from=5 (比如断线重连逻辑里存着上次的 runID)会拿到已落库的帧,然后拿到 ① 补的那帧 kind:"error",流正常关闭。没有那帧它就永远等下去——这是 §5.3 把「补帧」写进 Reconcile 契约的唯一理由,也是 §8 失效场景 D。
以下 7–16 是打断路径与边界。前六个用例都是「一件事按顺序发生」, 这十个里有一半是两件事同时发生——真正的复杂度在这里。
用例 7:审批挂起期间排队
场景:r_17 要调 write_file,卡在审批上等人拍板(§7.4)。用户等不及,又发一句。 要点是「连排队的入口都还在」:审批挂起占的是闸,不是收件箱。
run 级流(r_17 已挂着)
data: {"run":"r_17","seq":5,"ts":"T5","kind":"approval",
"approval":{"id":"s_1-a1","tool":"write_file","args":"{\"path\":\"doc/20.md\"}","message":"要写这个文件"}}
↑ ask 闭包产出。此刻:drive goroutine 阻塞、闸没放、两条流都没断
→ POST /api/message {"sessionId":"s_1","messageId":"m_2","clientId":"A-desktop","text":"顺便把 v1 也看看"}
← 202 {"seq":4,"messageId":"m_2"}
会话级流
data: {"seq":4,"ts":"T6","kind":"message_queued","messageId":"m_2",…,"text":"顺便把 v1 也看看"}
↑ 后面不会跟 run_started——闸被挂起的 r_17 占着。UI 该显示
「排队中,等 r_17 结束」,不是「马上开始」
→ POST /api/approval {"sessionId":"s_1","requestId":"s_1-a1","decision":"approve"}
← 200
run 级流(同一条 r_17 流,接着往下推)
data: {"run":"r_17","seq":6,"ts":"T7","kind":"approval_result","approval":{"id":"s_1-a1","decision":"approve"}}
data: {"run":"r_17","seq":7,"ts":"T8","kind":"tool_result","toolName":"write_file","text":"已写入 doc/20.md"}
…
data: {"run":"r_17","seq":9,"ts":"T9","kind":"complete"}
会话级流
data: {"seq":5,"ts":"T9","kind":"run_terminal","runId":"r_17","terminalKind":"complete"}
data: {"seq":6,"ts":"T9","kind":"run_started","runId":"r_18","messageIds":["m_2"],"mergedText":"顺便把 v1 也看看"}
↑ m_2 等到闸放了才开跑
decision 只接受 approve / reject;reject 时 run 不结束—— 模型收到拒绝后自己决定怎么办(换个做法、或收尾),所以后面仍可能是 complete。
用例 8:停止
场景:r_17 在跑,m_2、m_3 在排队。用户按停止。
→ POST /api/stop {"sessionId":"s_1","run":"r_17"}
← 200(run 对不上则 404 run_not_found)
run 级流
data: {"run":"r_17","seq":6,"ts":"T5","kind":"stop"} ← 终局帧,流关闭
会话级流
data: {"seq":4,"ts":"T5","kind":"run_terminal","runId":"r_17","terminalKind":"stop"}
data: {"seq":5,"ts":"T5","kind":"run_started","runId":"r_18","messageIds":["m_2","m_3"],
"mergedText":"顺便看看 v1\n\n对比一下差异"}
↑ ★ 立刻又开跑了。因为 Stop 不清收件箱
这是全套用例里最反直觉的一帧:用户按下「停止」,系统却开始了新一轮。 所以 §6.3 约束 5 要求停止按钮旁边明示「还有 2 条排队,会继续」并给一键清空(用例 9)。 不做这个提示,用户会觉得「我明明停了它怎么又跑了」。
而这恰恰是有意的产品决定:停止的语义是「这一轮不对」,不是「我说的话不算」。 用户可能是想打断一个跑歪了的回答,但他排队的那两句仍然成立。 要连排队的一起丢,是下一个用例的显式操作,不是停止的副作用。
用例 9:清空收件箱
场景:接用例 8。用户看到「还有 2 条排队,会继续」,点「全部丢弃」。
→ DELETE /api/session/s_1/inbox
← 200 {"cleared":2}
会话级流(每条被清掉的消息各推一帧 message_cancelled)
data: {"seq":6,"ts":"T6","kind":"message_cancelled","messageId":"m_2"}
data: {"seq":7,"ts":"T6","kind":"message_cancelled","messageId":"m_3"}
为什么必须有这个路由:DELETE /api/message/:id 是逐条撤回,但它有个抓不到的窗口—— 用例 8 里 m_2/m_3 已经在新 run 开跑的一瞬间被 Drain 走了,此时逐条撤回只会得到 404, 用户想「都别跑了」却做不到(只能 Stop 新的 r_18,然后 r_19 又起来了……)。 批量清空配合 Stop 才构成一个能真正静下来的操作序列。
它不保证静下来:清空只删 inbox 里当时还在的行,不碰 live run。 所以「停止 + 清空」要按这个顺序发,且清空后到下一条消息投递前,会话是安静的。 {"cleared":N} 里的 N 是给 UI 的确认文案(「已丢弃 2 条」),也是这个操作唯一的可观测结果—— 它不在任何 run 里留痕,因为被清掉的消息从未成为 run。
用例 10:删会话(= 用户点「新会话」)
场景:r_17 在跑,首帧还没到(模型还在思考)。用户点「新会话」。 这是 §8 失效场景 A 的现场:客户端此刻不知道 runID(runID 只在事务提交后经 run_started 发布,不变量 9),所以任何依赖「前端先 stop 再新建」的做法都会漏—— if (runID) stop() 的判断为假,stop 根本没发出去,旧 run 继续写进一个用户以为已不存在的会话。
方案是不让前端承担这个责任:删会话是服务端的一个原子操作,取消 run 是它的第 1 步。
→ DELETE /api/session/s_1
← 204
服务端按 §5.9 的 Delete 四步走:
① 查 run_archive 的 running 行取消 live runCtx(不依赖客户端知道 runID)
② 清 inbox
③ 一个事务删 run_log / run_archive / session_log / inbox / approval 的会话行 + registry 登记行
④ SessionLog.CloseSession 断开该会话所有订阅 + archive.InvalidateCache
——没有第五步:Engine 无状态,没有「会话引擎」可摘
所有客户端的会话级流:连接被服务端关闭(不是收到一帧,是流断了)
所有客户端的 run 级流(r_17):同样被关闭
被取消的 r_17 若已在写帧:emit 撞到已删除的行 → 写失败 → drive 记下 persistErr 退出。
**它写不进任何东西,因为没有行可写**——这是「删表」比「发 stop」强的地方。
「新会话」= DELETE 旧的 + POST /api/session 拿一个新的 + 重挂两条流。 不做 DELETE 只 POST,旧会话就变成孤儿(没人再看,但 run 还在写库、还在烧 token)。
验收方式:点「新会话」后立刻查六张表(run_log / run_archive / session_log / inbox / approval / session), session_id='s_1' 的行数必须是 0; 再等 10 秒查一次,仍必须是 0(证明旧 run 没有复活写入)。
用例 11:未登记 / 已删除的 sessionId
场景一:前端 localStorage 里存着一个上辈子删掉的 s_9。 场景二:有人拿 curl 手打一个自己编的 id。
→ GET /api/session?id=s_9
← 404 {"error":{"code":"session_not_found","message":"…"}}
前端处理:清掉本地 sessionId,走 POST /api/session 重新登记(§6.1 步骤 ⓪)
→ GET /api/session/stream?id=s_9&from=0
← 404(同上;准入检查在挂流之前,不会先建连接再断)
→ POST /api/message {"sessionId":"s_9","messageId":"m_1","clientId":"curl","text":"…"}
← 404(同上;★ 绝不隐式创建,不变量 1)
→ GET /api/chat/stream?run=r_999&from=0
← 404 {"error":{"code":"run_not_found","message":"…"}}
这是本方案与「前端 mint id」路线的分水岭:如果 POST /api/message 见到未知 sessionId 就顺手建一个会话,那么 ① 会话列表无法实现(不知道有哪些会话存在)、 ② 打错一个字符就静默开了一个新会话、用户的字进了一个再也找不到的地方、 ③ 孤儿会话无法回收(没有登记行,就没有「这个会话什么时候创建的、该不该清」的依据)。 准入检查是 Registry 存在的全部理由(§1.2)。
注意 messageId 和 clientId 仍是客户端生成的,这不矛盾:它们是幂等键与设备标识, 不是资源身份。messageId 重复会 409(且只在消息仍在收件箱期间,见 §6.3 约束 6), clientId 随便填都能用——它们不承担「这个资源存在吗」的问题。
用例 12:队列上限(422)
场景:r_17 跑得很久,用户已经排了 10 条。第 11 条投递。
→ POST /api/message {"sessionId":"s_1","messageId":"m_11","clientId":"A-desktop","text":"…"}
← 422 {"error":{"code":"queue_full","message":"…","detail":{"queued":10,"limit":10}}}
前端提示:「已经排了 10 条,先停一下当前任务?」
排到 10 条说明这场 run 已经久到用户在对着它自言自语,静默排队是不诚实的。 这与不变量 7 不冲突——不变量 7 说的是「不因状态冲突失败」, 队列过深是用户的输入本身需要被重新考虑,是 4xx 的正当用途(取值理由见 §11)。
注意它不写 inbox、不推帧、不占 seq:422 是唯一一个「投递没发生」的出口, 前端不该画任何气泡。会话级 seq 也不会因此跳号。
用例 13:滚到顶翻历史
场景:会话里有 40 个已结束的 run,页面首屏只画最近的。用户滚到顶。
→ GET /api/session/history?id=s_1&limit=20
← 200 {"runs":[{"runId":"r_16","createdAt":"…","status":"complete","events":[{…},{…}]},
{"runId":"r_15",…}, …],
"nextCursor":"2026-09-30T08:11:02Z|r_-3"}
→ GET /api/session/history?id=s_1&limit=20&cursor=2026-09-30T08:11:02Z|r_-3
← 200 更早的一页
接缝在哪里:HistoryPage 不返回 status='running' 的行(§5.3)—— 正在跑的 run 由 Snapshot.liveRunId 报告、由 run 级流呈现。所以「历史」与「实时」 天然不重叠:一个是已结束的 run 数组,一个是活的帧流。
但有一处新的接缝:排队中的消息既不在 history 里,也不在任何 run 的帧里 (它只在 inbox 和 session_log 的 message_queued 帧里)。刷新页面时它靠 Snapshot.queued 恢复(用例 3),而翻历史翻不到它——正确,因为它还没成为历史。 UI 要把排队气泡画在输入框上方那一区,不要混进历史流,否则翻页时会被重复插入。
用例 14:SSE 单独断线重连(≠ 用例 3 的整页刷新)
场景:网络抖了一下,会话级流断了 3 秒。这期间另一端投递了 m_2,r_17 也落幕了。 页面没刷新,JS 状态还在,本地记的 sessionSeq 停在 3。
断开前最后收到:data: {"seq":3,"kind":"run_started","runId":"r_17",…}
—— 连接断开 3 秒 ——
重连:GET /api/session/stream?id=s_1&from=3
data: {"seq":4,"ts":"T5","kind":"message_queued","messageId":"m_2",…,"text":"顺便看看 v1"}
data: {"seq":5,"ts":"T6","kind":"run_terminal","runId":"r_17","terminalKind":"complete"}
data: {"seq":6,"ts":"T6","kind":"run_started","runId":"r_18","messageIds":["m_2"],…}
↑ 补齐了漏掉的三帧,然后切实时
同时 run 级流 r_17 也断了:GET /api/chat/stream?run=r_17&from=7
data: {"run":"r_17","seq":8,…} data: {"run":"r_17","seq":9,"kind":"complete"}
↑ 它自己会收尾关闭
为什么这条用例必须单列:§9 会说会话级流的 from=seq 续传「不是可选优化」, session_log 持久化就是为它存在的。用例 3 走的是整页刷新(JS 状态归零,靠 Snapshot 重建), 没有验证「JS 状态还在、只补漏帧」这条路——而它才是日常最常见的那种断线。
前端实现上的关键:sessionSeq 必须每收一帧就更新,不能等批处理完; 否则重连时 from 报小了会重放(气泡重复),报大了会丢帧(气泡永久缺失)。 重放可以靠 messageId 幂等兜住,丢帧兜不住。
用例 15:run 中途压缩
场景:r_18 跑到一半上下文超阈值,压缩换掉了 r_15(§7.5)。
run 级流(r_18)
data: {"run":"r_18","seq":4,"ts":"T4","kind":"compact","text":"上下文较长,正在压缩早期对话"}
↑ compact 只表示「正在压缩」,text 是短句,不是摘要正文
…后续帧照常
用户看到什么:一句轻提示,不是新气泡、不是新 run。压缩是暗处的事(§7.5), 它不改 runID、不结束 run、不产生会话级帧——所以会话级流对压缩完全无感。 这是刻意的:压缩属于「模型视图真源」(Archive)的内部事务,不是会话级事实。
压缩之后翻历史会读到什么(接用例 13):r_15 的 produced_json 被清空、 原文挪进 compact_rag(§5.4)。但 GET /api/session/history 读的是 run_log 的帧, 不是 produced_json,所以 r_15 的对话在历史里照样能翻到、字还在。 被压掉的只是「下一轮模型看到什么」,不是「用户看到什么」。 这个区分是 §1 三真源的直接后果,也是最容易被实现搞反的地方。
用例 16:inject 插话(后置能力)
场景:r_17 正在读错的文件,用户想立刻纠正,不等它跑完。
→ POST /api/message {"sessionId":"s_1","messageId":"m_2","clientId":"A-desktop",
"delivery":"inject","text":"不对,看 doc/16"}
← 202 {"seq":4,"messageId":"m_2"}
会话级流
data: {"seq":4,"ts":"T3","kind":"message_queued","messageId":"m_2",…,"text":"不对,看 doc/16"}
↑ 注意:**没有 run_started**,但 m_2 也不会等到 r_17 结束
run 级流(r_17 继续,下一个 round boundary 处模型就吃到了这句)
data: {"run":"r_17","seq":6,"ts":"T4","kind":"message","role":"assistant","text":"好,我看 doc/16"}
机制上不需要新东西:eino 的 BeforeModelRewriteState 钩子在每次调模型前触发, 且改动会持久化进 agent state——在那里往 state.Messages 末尾 append 一条 user 消息即可。
与 after 模式的区别就在这一点:after 的 message_queued 后面必然跟着 (当前 run 落幕后的)run_started;inject 的后面什么都没有, 那句话直接进了正在跑的这一轮。前端因此不能用「有没有 run_started」判断消息是否被消费—— inject 消息的消费信号是它出现在 r_17 后续帧的语义里,没有专门的帧。
这是本用例集里唯一一个「帧协议不足以表达状态」的地方,所以 §11 把它列为可选阶段: 要么加一种 message_injected 会话级帧(干净,但多一种帧), 要么让 UI 对 inject 消息只显示「已插话」不再跟踪状态(够用,但状态机有例外)。倾向前者。
启动条件:after 模式稳定,且真的开始嫌「等它跑完」太久。没有它本方案仍然完整。
7.10 竞态对照表
§7.9 的用例里有六个是「两件事同时发生」(重发在用例 2、撤回 vs 开跑在用例 4,其余在用例 7–16)。把它们单独列出来,因为测试必须逐条覆盖—— 它们全都是「不崩但结果错」的类型,跑一百次正常、第一百零一次出错,靠冒烟测试抓不到。
| 竞态 | 谁和谁 | 正确结果 | 靠什么保证 | 测法 |
|---|---|---|---|---|
| 撤回 vs 开跑 | DELETE /api/message/m_2 与 trySchedule 的 Drain |
二者只有一个赢:要么 204 + message_cancelled,要么 404 + 该 id 出现在 run_started.messageIds。不可能既撤回成功又被回答 |
inbox 行的删除与 Drain 都是 DB 写,由事务仲裁行锁(§5.7) | 两个 goroutine 各打一次,断言恰好一帧、且两处的说法一致 |
| 清空 vs 开跑 | DELETE /api/session/:id/inbox 与 Drain |
被 Drain 走的那几条不在 cleared 计数里,也不会同时收到 message_cancelled |
同上(Clear 与 Drain 由事务仲裁) | 排 3 条,并发清空 + 落幕,断言 cleared + len(messageIds) == 3 |
| 停止 vs 正常完成 | POST /api/stop 与 drive 自然返回 |
只写一条终局帧。若产出已拿到,按 complete 记(产出仍算数) |
terminalOf 的判断顺序:err == nil 优先于 stopped(§7.6) |
在最后一帧前触发 stop,断言终局帧唯一 |
| 删会话 vs 投递 | DELETE /api/session/s_1 与另一端的 POST /api/message |
投递可能拿到 202,也可能 404;但它的帧和 inbox 行随会话一起消失,不留孤儿行 | Delete 的清 inbox 与删六张表在同一事务(§5.9) | 删完后查六张表行数必须为 0,再等 10 秒查一次 |
| 重连 vs 修剪 | from=3 续传与 session_log 修剪(§11,未决) |
若 from 早于已修剪的最小 seq,不能静默丢帧 |
待定:要么返回「你落后太多,请重新拉 Snapshot」的显式信号,要么不修剪 | 决议后补 |
| 重发 vs Drain | 同一 messageId 的重发与该消息被 Drain 消费 |
两种结果都可接受,但必须可区分:仍在收件箱 → 409 message_id_taken(幂等成功,不产生第二行);已被 Drain → 插成新行(§9.3 第 6 条的残留风险,由 §6.3 约束 6 在前端挡) |
inbox 主键 (session_id, message_id),且 Put 与 Drain 由事务仲裁(§5.7) |
排 1 条,并发「重发同 id」与「落幕触发 Drain」,断言:要么恰好一个 409 且 inbox 只有一行,要么多一行且 session_log 里出现两个 message_queued 帧 |
这六条都随对应的 action 一起写测试,不留到最后补。 竞态测试事后补的成本是当场写的三倍,而且事后补的往往只测「不崩」,测不出「恰好一帧」。
8. 必须覆盖的失效场景
这一节是验收清单,不是历史回顾。每条给:场景 → 用户看到什么 → 根因 → 本方案靠哪一条设计覆盖 → 怎么验。
选这六条的标准是:它们都不是「代码写错了」,而是「结构不对就一定会发生」。 换个写法、加个 try、多点耐心,都躲不掉——所以它们必须靠结构解决,也就能靠结构验证。
场景 A:「新会话」时旧 run 在后台续跑
场景:用户按下发送,模型还在思考(首 token 之前,通常好几秒),用户改主意点了「新会话」。
用户看到什么:页面清空了,新会话开始了。但后台那一轮还在跑, 还在调工具、还在烧 token、还在往一个用户以为已经不存在的会话里写帧。 如果那个工具是 write_file 或 bash,副作用是真实的——文件真的被改了。
根因:停止一轮 run 需要 runID,而 runID 在这个窗口里客户端不可能知道。 它是在 beginRunAtomic 的事务提交之后、经 run_started 帧才发布的(不变量 9)。 所以任何形如「前端记住当前 runID,切会话前发个 stop」的做法都必然漏掉这段窗口。 这个窗口不窄——它覆盖了模型首 token 之前的全部思考时间。
本方案怎么覆盖:把责任从客户端挪到服务端。DELETE /api/session/:id 的第 1 步 就是取消 live runCtx(§5.9)——以 sessionID 为键查 run_archive 的 running 行,无条件执行, 不依赖客户端知道任何 runID。 之后清 inbox、一个事务删六张表的会话行、断开该会话所有订阅。Engine 无状态,没有可摘的对象。 被取消的 run 若还在写帧,emit 会撞到已删除的行而失败——它写不进任何东西,因为没有行可写。 「删表」比「发 stop」强的地方就在这里:stop 是请求,删表是既成事实。
怎么验:发送后立刻(首帧到达前)DELETE /api/session/s_1, 然后查六张表 session_id='s_1' 的行数必须为 0;等 10 秒再查一次,仍必须为 0。
场景 B:投递被拒之后,那一端就再也看不到新内容了
场景:两台设备(或两个标签页)开着同一个会话。A 正在跑一轮,B 发了一句。
用户看到什么:B 上出现一个错误提示,然后B 就静了——A 那边的回答、 后来排队的消息、落幕,B 全都不知道。B 的用户只能刷新页面。而刷新之后 他刚才那句话有没有被记下来,也说不清。
根因:两件事叠加。① 投递因「已有 run 在跑」而失败,于是 B 的话没进任何存储, 连「说过」这个事实都没留下;② B 的订阅是 run 级的,它只知道自己在看的那一轮, 新一轮的 runID 它无从得知,所以也没有任何机制能把它唤醒。 一旦这条 HTTP 请求失败,B 就失去了唯一的信息来源。
本方案怎么覆盖:两处,缺一不可。 ① 投递永不因状态冲突失败(不变量 7):B 那句话落进 inbox、写进 session_log, message_queued 帧推给所有订阅者——B 的气泡同时出现在 A 和 B 上; ② 会话级流常驻(§4):B 一直开着 GET /api/session/stream, run_started 是主动送达的,B 不需要猜也不需要轮询就能挂上新一轮的 run 级流。 剩下的 409 只有两种,都是「客户端自己的状态错了」(重复 messageId、视图过期), 且都有明确的自愈动作(§7.9 用例 2)。
怎么验:A、B 两条 curl 各挂一个 GET /api/session/stream,从 A 投递, 断言 B 的流收到逐字节相同的 message_queued 帧(§7.9 用例 5)。
场景 C:另一端不知道有新一轮开始了
场景:A 在跑 r_17,B 刚打开这个会话(或 B 的页面一直开着但没在跑任何流)。
用户看到什么:B 的画面停在上一轮的结束状态。A 那边已经开始了新的一轮、 已经在输出,B 上什么都没有。B 的用户以为系统卡住了。
根因:与场景 B 同源,但更基础——「一轮 run 开始了」这个事实没有任何投递通道。 run 级流是「我已经知道 runID 才挂得上的」,而 runID 的产生与 B 的存在毫无关系。 一个只订阅 run 的系统,天然无法表达「有新 run 了」。
本方案怎么覆盖:这正是 session_log 存在的理由(§1.1)。 run_started 是一帧会话级事实,与 beginRunAtomic 在同一事务里写下(不变量 9), 事务一提交就 bump 给所有会话级订阅者。B 不需要问,帧会来找它。
怎么验:B 先挂流,A 再投递;断言 B 收到 run_started 且能据此挂上 run 级流, 期间 B 没有发过任何请求(§7.9 用例 5)。
场景 D:进程重启后,重挂旧流的客户端永远挂着
场景:r_17 跑到一半进程被杀。重启后,一个客户端按自己的重连逻辑 GET /api/chat/stream?run=r_17&from=5。
用户看到什么:已落库的几帧正常到达,然后流不结束。UI 停在「正在回答」, 转圈转到天荒地老。用户没有任何办法让它继续或结束,除了刷新页面。
根因:Reconcile 只把 run_archive.status 改成 failed,没有补终局帧。 而 run 级流的关闭条件是「读到终局帧」(§5.12)。状态字段在档案里,帧在 run_log 里, 只改前者,后者就永远缺一帧。订阅者的世界里这个 run 还没结束。
本方案怎么覆盖:Reconcile 的契约里明确写着补一帧 kind:"error" 的终局帧, 并返回它标 failed 的那些 run,由 Server 再给对应会话补一帧会话级 run_terminal(§5.3、§7.8)。 两步的顺序也不能换——先 run 级、后会话级,否则客户端可能在 run_terminal 到达前 去挂那条永远等不到终局的 run 级流。
怎么验:开一轮 run,kill -9 进程,重启, curl -N '…/api/chat/stream?run=<旧runID>&from=0' 必须在读完已落库帧后自己结束, 最后一帧是 kind:"error"。
场景 E:拿到 runID 就订阅,却 404
场景:客户端从某个接口读到了 live runID,立刻去挂 run 级流。
用户看到什么:404 run_not_found。或者更糟——挂上了,但流里缺了开头几帧, 回答看起来是从半截开始的。
根因:runID 的可见时刻早于它的可订阅时刻。 如果先发布 ID(比如写进一个内存变量、或先提交一部分事务),后写 run_log 的档案行与 start 帧, 中间就有一段窗口:ID 拿得到,帧查不到。窗口只有几毫秒,但在高并发或慢盘下必然被踩到。
本方案怎么覆盖:不变量 9——runID 只在 beginRunAtomic 的事务提交之后才对外可见, 且它的唯一发布渠道就是同一事务里写下的那帧 run_started。 档案行、run 级 start 帧、会话级 run_started 三者同生共死: 要么都看得见,要么都看不见。不存在「ID 有了、帧还没有」的中间态。 事务进行中之所以不泄露 ID,是因为 ID 的铸造与发布都在事务内部—— 闸与可见性都由数据库裁决,进程内没有任何「占位」状态可泄露(§5.9)。
怎么验:并发投递 + 并发订阅,断言任何一次「先拿到 runID 再订阅」都不会 404; 断言订阅到的第一条帧永远是 seq=1, kind:"start"。
场景 F:run 在跑的时候,用户打不了字
场景:一轮 run 要跑几十秒(读大文件、跑测试、等审批)。用户在此期间想到了别的。
用户看到什么:输入框灰着,或者发送键变成了停止键。用户想到的那句话, 没有任何地方可以放。他只能等,或者打断当前这一轮(而当前这一轮可能是对的)。
根因:把「会话正在忙」当成了投递的前置条件。这是一个同步模型的残留: 一次请求对应一次回答,所以第二次请求必须被拒。 但 agent 的一轮可以跑几分钟,用户不是请求-响应模型里的客户端。
本方案怎么覆盖:inbox 存在的全部理由(§1.1)。投递与执行解耦之后, 「正在忙」不再是拒绝投递的理由,只是推迟执行的理由。 发送键永远可用(§6.3 约束 1),排队的消息以气泡形式可见、可撤回, 落幕时被合并成一句交给下一轮(§7.6)。审批挂起期间同样可以排队(§7.4)—— 同一个机制,把「为什么打不了字」变成「我先把下一句说了」。
怎么验:一轮 run 进行中连投两条,断言两次都是 202、两条 message_queued 帧都到、 落幕后 run_started.messageIds 含这两个 id 且 mergedText 是两句拼接(§7.9 用例 2)。
9. 取舍与代价
诚实列出。这些是本方案真实变贵、变复杂、或者明知有洞的地方,不是可以忽略的脚注。
9.1 复杂度上升
| 项 | 量 | 为什么非它不可 |
|---|---|---|
| 表 | 8(5 份持久状态 + session_seq / compact_rag / approval 三张辅助表,§1.3、§5.14) |
每份持久状态回答一个不同的问题,两两不可互推(§1.3)。少任何一张,就有一个问题只能靠猜 |
| 流 | 2 种(run 级 + 会话级) | 「一轮 run 的内部过程」与「一个会话发生了什么」是两个不同的问题,受众与生命周期都不同(§4.2) |
| 客户端游标 | 1 + N(sessionSeq + 每 run 一个 seq) | 两套 seq 是独立命名空间(§5.5)。共用一套会让「run 内的帧序」与「会话内的事实序」互相污染 |
| Engine | 无状态单例,导出方法 7 个(Enqueue / Cancel / ClearInbox / Stop / Approve / Snapshot / Delete),全部显式收 sessionID | 每个方法对应用户的一个真实动作,没有一个可以合并(§7.9 的 16 个用例逐条对上)。无状态 = 没有任何 per-session 对象要装配、缓存、摘除(§5.9) |
| 并发临界区 | 占闸 + 取空收件箱 + 发布 runID,必须同事务 | 不变量 8、9。这是全篇唯一的难写点(§5.9 的 beginRunAtomic) |
| 浏览器连接占用 | 每个会话 2 条 SSE | 见下 |
连接占用是唯一一个「只在多标签页暴露」的代价,而多标签页正是本方案要修的场景, 所以它不能当脚注:浏览器对同一 host 的 HTTP/1.1 并发上限是 6,SSE 长期占坑, 2 个标签页 × 2 条 = 4 个坑,只剩 2 个给普通请求。 缓解手段是 §5.8 的 SessionFeed 分层(换成 WS 多路复用不动存储)与 §10 阶段三。
9.2 阶段一明知敞开的一个窗口
进程崩在 Partial 帧 seal 之前,那条助手正文彻底丢失,且不可恢复。
阶段一的流式正文只活在内存里(预留号协议,§5.3),流结束时才 AppendSealed 一次落库。 这中间可能有几十秒。崩在这个窗口里,用户看到过的那些字,库里一个字都没有。
不提供补救手段:早期设计里考虑过「让客户端把手里的全文补发回库」, 三条理由否掉了(§5.3 那段引用块)——前提不成立(全文的唯一来源就是那条流本身)、 要求客户端长期保存对话内容(与会话身份在服务端的事实相悖)、 且阶段二会让它无的放矢。
为什么可以先接受:阶段一要验的是入口与调度(投递、排队、合并、多端、重启续答), 数据面沿用既有机制不动,改动面小、能最快跑通那 16 个用例。 正文丢失是内容损失,不是状态不一致:run_archive 里没有半截产出(§5.3 的约定), 下一轮模型不会以为自己说过那些话,系统状态是自洽的。
它什么时候必须关掉:阶段二第 14 步(§10)。届时消息从 GENERATING 起就持久化, 「哪一帧才算数」这个问题不再成立,sealed 与整个 Partial 机制一起退役, 窗口结构性消失——不是被兜住,是不再存在。
9.3 新的失败模式
- 会话级长连接断开期间的事件会丢——所以会话级流必须支持
from=seq续传, 这不是可选优化。session_log持久化就是为它存在的(§7.9 用例 14)。 实现上最易错的一点:前端的sessionSeq必须每收一帧就更新, 报小了会重放(气泡重复,可靠messageId幂等兜住),报大了会丢帧(兜不住)。 beginRunAtomic事务失败时,消息何去何从? 它已从 inbox 被 Drain,事务回滚则恢复——回滚本身是安全的。 但需要一个重试策略,否则消息会躺在收件箱里直到下一次 Enqueue 才被捞起。 阶段一的处理:回滚 + 退回收件箱 + 写一帧会话级错误,由下次投递触发重试(§5.9、§11)。- 合并窗口让「我发的那句」与「回答」不再一对一。 UI 必须能表达归组关系,否则用户会困惑「我只问了一句,为什么回答里在讲两件事」。
message_ids(§5.10)就是为此存在的,run_started.messageIds是它的线上形式。 - 服务端回显引入一个 RTT 的延迟感(§6.3 约束 2)。 用户按下回车到气泡出现,从「立刻」变成「一个来回」。 这是拿即时感换多端一致性,是取舍不是纯收益。 阶段一先用服务端回显(简单、天然一致);若实测延迟感明显, 可用「客户端生成的
messageId先画一个 pending 气泡、帧到达时按同一 ID 对齐」补回即时感—— 这条已列为 §11 的待定项,采纳后 §6.2 的状态机要多一个 pending 态。 - 停止之后系统会自己开跑新一轮(§7.9 用例 8)。 这是产品决定而非 bug(停止的语义是「这一轮不对」,不是「我说的话不算」), 但它反直觉到必须在 UI 上明示,并配一个一键清空(用例 9)。 不做这两件事,用户会认为系统失控。
- 重发跳过回放,会让同一句话被回答两次(§6.3 约束 6、§11 问题 7)。
messageId的服务端去重只在消息仍在收件箱期间有效(主键撞 409); 一旦被 Drain 进某场 run,inbox 里就没有行了,重发会顺利插成新行。 挡住它的是前端约束:重连后先把from=lastSeq回放完,看见同一个messageId就撤销重发。 服务端不兜这一层——兜它需要一张永久的clientKey → messageId映射表, 成本与收益不成比例(§11 问题 7 的 B 案,已排除)。
9.4 阶段一不动什么
以下「不变」指阶段一。阶段二会动数据面(B 路的 emit、RunLog 的写方法、 Subscription、前端渲染),范围见 §10 第 13–17 步与 §12;Archive 与 A 路两个阶段都不动。
- Archive 的对外契约不变。合并发生在 Inbox 与 Engine 之间,Archive 看到的永远是一句 user 输入。
- drive 的 stream 循环、A/B 两路、审批挂起、compact 补偿事务全部照旧(§7.3–7.6)。
- RunLog 的 run 级语义不变,只增加
BeginRunInTx变体供事务内调用、 以及Reconcile的补帧与返回值(§5.3)。 - run 级 Subscription 不变:Partial 预留号、sealed、续传语义全部保留 (阶段一内;阶段二把这套机制整体退役,换成实体 + 字段补丁,§12)。
10. 实施顺序
本方案分三个阶段:阶段一只做入口与调度,数据面沿用 Partial/sealed; 阶段二按 §12 的增量协议重写数据面;阶段三是连接拓扑与新入口。 分阶段的理由在 §12.5——数据面重写的量级不小于阶段一本身,捆成一步会把两处的风险叠加。
但分阶段 ≠ 分版本:阶段二是本方案的一部分,不是「以后再说」。 它的启动条件写在下面,条件满足就做,不需要重新立项。
实施方式是重写,不是重构(见文首):新 module 从零起步, 与运行引擎无关的能力包作为既有资产搬入(第 1 步)。
阶段一:入口与调度(第 1–12 步)
顺序原则是 先 API 契约、再存储、最后前端: 第 3 步就把路由表与错误体钉死并用 curl 手打验证(此时存储是内存假实现), 这样存储层是在已知契约下写的,不会出现「表设计好了才发现接口要改」。 前端排到最后,且阶段一只做冒烟页——产品前端是 Vue,属于独立 loop(§6)。
- 模块骨架 + 搬能力包:
go.mod、cmd/yktako/、目录结构(§3); 把与运行引擎无关的既有资产搬入:internal/tools、guard、compact、mediaoffload、msgtext、adkrun、config(含provider-catalog.json)。 门槛:go build ./...与搬入包的既有单测全绿。 - 领域类型与接口先行,不写实现:
internal/run/event.go(十一种EventKind、Event、Approval、StoredEvent、Classify、Subscription)、 五个存储接口(RunLog/Archive/Registry/Inbox/SessionLog)、SessionFeed、Engine的导出方法签名、transport 的 DTO 与错误体。 门槛:go build ./...过,Classify的单测穷举四种输入(纯函数,此时就能测)。 - API 契约落地(存储用内存假实现顶着):Gin 路由表(§5.12)、
errorMapper(§5.13)、sse.go的Stream/StreamSession、各 handler。 门槛:curl 手打 §7.9 的用例 1、11、12,逐字节对响应体。 这一步不追求功能完整,追求「契约不再变」。 - RunLog 的 SQLite 实现:建表(§5.14)、
BeginRun(InTx)、Append(含 Partial 预留号)、AppendSealed、Finish(含 patch)、Reconcile(补终局帧 + 返回[]FailedRun)、Subscribe、HistoryPage。门槛:sealed / 预留号作废 /ErrSealConflict三类单测。 - Archive:
ModelMessages、AddRun、Stage/CommitPatch/RevertStage、Notify、WriteRAG。门槛:压缩后回退的单测(stage → revert → 视图必须与 stage 前逐条相同)。 - Registry + Inbox + SessionLog:三张表 +
session_seq同源计数器(§5.7)、SessionFeed的Since/Subscribe、CloseSession、两个Reconcile。 门槛:Put与Append拿到的 seq 严格同源、不跳号、不重号。 - Engine 真实现换掉假实现:
Enqueue、Cancel、ClearInbox、Stop、Approve(含 §5.11 的approval表与Approvals三方法)、Snapshot、trySchedule/beginRunAtomic(DB 闸:部分唯一索引第一版就是唯一形态,没有进程内版)、drive/runState。 门槛:★ 压测不变量 8——让Enqueue与drive收尾在纳秒级并发, 断言消息不会搁浅、不会开出两场 run;去掉全部进程内锁后测试仍全绿 (闸在库里,测试环境 SQLite 就能验);-race全绿。 ★ 附带一个 eino 验证项:adk.Agent/adk.Runner/ compact middleware 能以「drive goroutine 现场构造 per-run 绑定(BindMemory、checkpoint key)」的方式使用, 不依赖任何每会话常驻对象——本设计的唯一外部前提,第 7 步内必须证实或调整。 Engine.Delete+ 启动编排:DELETE /api/session/:id(场景 A);Reconcile的四步顺序(场景 D,§7.8)。 门槛:§7.10 竞态表里的「删会话 vs 投递」与「重挂旧流」两条。- §7.9 用例 1–9 全绿:curl + 两个
curl -N手打,逐字节对; §7.10 竞态表六条各有一个测试。这是阶段一的总验收。 - 冒烟前端(go:embed 单页):只为「不用 curl 也能手工点一遍」, 不是产品前端。实现 §6.1 的启动编排与 §6.2 的状态机即可,样式从简。
- 文档同步:
doc/下描述接口与存储的文档按本文校正;本文 §11 的决议销账。 - inject 模式(§7.9 用例 16,后置能力):
Enqueue加delivery参数、 inbox 表加一列、新增一个 middleware 走 eino 的BeforeModelRewriteState把 pending 消息 append 进state.Messages。 放在最后,因为它依赖第 6–7 步,且失败时可以整块不做——没有它本方案仍然完整。
阶段二:数据面增量协议(第 13–17 步)
启动条件:阶段一第 9 步全绿。第 7 步起「投递永不因状态冲突失败」就直接站在 DB 上 (闸的部分唯一索引从第一版就生效)。设计依据是 §12:帧从「发生了一件事」改成 「某实体的某字段变成了这个值」,流式正文只推增量,「流式中 → 定稿」退化为一次普通字段变更。 §12 给出的是形状与判断,不是可实施的规格——所以第 13 步是先把规格写死。
- 协议规格:实体树(message → block)、
op:set/append+mask字段路径、 跨实体全局单调 offset、带 offset 的heartbeat、显式done终止符。 落成文档:存储 schema、帧形状、续传语义 (重连from=offset时增量帧如何补齐——实体在库里,追赶者读实体当前态即可, 这是增量协议的续传比 Partial 简单的地方)。 - 存储层:message 实体在
status:GENERATING时创建即落库,正文 append 累积进库。 §9.2 那个窗口从这一刻起结构性消失。 - 订阅层:删
Subscription的 Partial 分支——预留号、AppendSealed、ErrSealConflict、dropPartialTail、游标不前移、防忙等全部退役; run 级续传统一为「按 offset 追赶 + 读实体当前态」; 「流式中 → 定稿」变成一次op:"set" mask:"message.status"。 - 前端:从「按
kind分派渲染」改成「维护实体树、按mask打补丁」;done终止符替换终局帧判定;heartbeat带 offset 让客户端能区分 「服务端卡住」与「在等 LLM」。 - 测试与文档:测事件形状的用例大部分改写;文档同步,§11 决议销账。
门槛:第 15 步删 Partial 分支之前,先用测试钉住 「重连读者在流式中途加入,能看到实体当前态且不重不漏」。
阶段三:连接拓扑与新入口(第 18 步起)
启动条件:阶段二完成,且出现了下面任一具体压力。逐条列,免得被当成「以后再说」的垃圾场:
- 一条 WS 多路复用替换两条 SSE——启动条件:多标签页场景下浏览器连接上限成为瓶颈 (HTTP/1.1 并发上限 6,2 标签页 × 2 条 SSE = 4 个坑,§9.1)。 §5.8 的
SessionFeed已做存储与传输分层,换 WS 不需要动存储层,只写一个 WS 实现。 - 账号级订阅——启动条件:出现「一个账号多个会话,要在一个页面看全部」的需求(§4.2)。 硬前置是
session表已存在(第 6 步),且要有账号概念。 - MQ 投递——启动条件:多副本部署真的上线,且出现了「非浏览器的投递方」。 MQ 不承担崩溃兜底:那个职责在阶段二第 14 步已经由存储层接管(§9.2)。 MQ 剩下的唯一价值是多副本之间的投递与解耦。
- IM / cron 入口——启动条件:有真实的 IM 接入或定时任务需求。 它们只是「又一个
Subscribe」与「又一个Enqueue」,引擎一行不改(§7.3 末)。 adk.TurnLoop换底座评估——启动条件:阶段二完成后再评估。TurnLoop原生就有收件箱、合并窗口、抢占与 checkpoint-resume,尤其诱人; 但换底座等于同时改语义层和执行层,而本方案的全部风险预算应该花在 语义层(阶段一)与数据面(阶段二)上。
两套顺序的关系
本节按依赖排(先铺基础设施,再往上接)。实际执行按 tmp/v4-plan/todos.md 的用例 loop 排 (先让最痛的场景消失,再为下一个用例引入下一个组件)。两套顺序不冲突,映射关系:
| 本节的步 | 兑现 §7.9 的用例 |
|---|---|
| 第 3 步(API 契约 + 假实现) | 1、11、12 的响应体形状 |
| 第 4–6 步(存储层) | 1–6 的存储面 |
| 第 7 步(Engine + DB 闸 + Approvals) | 1、2、8、9(闸的保证直接在 DB 上,无进程内形态) |
| 第 8 步(Delete + Reconcile) | 6、10 |
| 第 9 步(总验收) | 1–9 全部 + §7.10 竞态六条 |
| 第 10 步(冒烟前端) | 3、5、13、14 的手工验证 |
| 第 12 步(inject) | 16 |
| 审批相关 | 7(本节没有单独一步——approval 表与 Approvals 随第 7 步落地,ask 闭包随 drive) |
每一步 -race 全绿再走下一步。
11. 待定问题
编号是稳定的,正文里「§11 问题 N」的引用按这里的号。 每条标注 已决(记下结论与理由,免得被重新提出)或 未决(写清选项、倾向、启动条件)。 正文其他章节引用问题 1 / 2 / 3,不要重排这三条。
1. 会话级 seq 与 run 级 seq 的关系 —— 已决:独立命名空间,但 inbox.seq 与 session_log.seq 同源。
理由:两者都是会话粒度,共用一个计数器能让「消息入队」在两张表里用同一坐标, 客户端对齐时间线无需换算(§7.9 用例 3 的 queued[].seq 就是会话级 seq)。 run 级 seq 保持 per-run,因为它的续传语义(Partial 预留号)依赖「本 run 内 max+1」, 跨 run 共用会破坏不变量 5。
残留的实现取舍:同源计数器怎么落地。两个选项—— (a) 一张 session_seq 表,NextSeq(ctx, tx, sessionID) 在事务里 UPDATE … RETURNING; (b) SELECT max(seq)+1 FROM session_log。 §5.14 建了 (a) 的表。倾向 (a):(b) 在 inbox 里有一行还没写进 session_log 时会算重, 而「Put 之后、Append 之前」正是这两步之间的真实状态。(a) 的代价是每个会话多一行、每次投递多一次 UPDATE。
2. beginRunAtomic 事务失败后消息怎么办 —— 未决。
三个选项:
- (a) 事务回滚,消息留在 inbox,等下一次
Enqueue或trySchedule捞起——简单,但可能长时间搁浅(用户不再发消息就永远躺着); - (b) 回滚后立刻重试 N 次,仍失败则写一帧会话级
error通知客户端——用户可见,但要新增一种SessionEventKind; - (c) 起一个后台定时器周期性
trySchedule所有非空 inbox——兜底最稳,代价是多一个常驻 goroutine。
倾向 (a) + (c):正常路径靠 (a),(c) 作低频兜底(30 秒一次)。 (b) 的可见性收益不大,因为 (c) 会让它最终一定被执行。 §5.9 的注释目前写的是 (a)+(b)(退回收件箱 + 写一帧会话级错误),决议后要与 (c) 对齐。 启动条件:第 7 步(Engine + DB 闸落地)写完就得定,不能拖——它决定 trySchedule 的调用点是否要加第四个。
3. 合并窗口 / 队列上限取多少 —— 已决:上限 10,超出硬拒绝(422)。
参考实现取的是同一个值(WeKnora internal/handler/session/steer.go:52-57,maxSteerQueueDepth = 10), 它注释里给的理由比「太长会混乱」硬得多:
past that the run is clearly ignoring its user and the honest answer is to refuse instead of queueing silently
即:排到 10 条说明这场 run 已经久到用户在对着它自言自语,此时静默排队是不诚实的。 早期草稿倾向「软上限 5,超出的留给下一场 run」,那个方案是错的: 它把「拒绝」变成「悄悄延后」,用户看不到任何反馈。
与不变量 7 不冲突:不变量 7 说的是不因状态冲突失败(会话忙不是错误), 而队列过深是用户的输入本身需要被重新考虑,这是 4xx 的正当用途(§7.9 用例 12)。
4. Stop 要不要清空收件箱;清空用什么接口 —— 两条都已决。
不清(§5.9)。理由:停止的语义是「这一轮不对」,不是「我说的话不算」。 用户可能想打断一个跑歪了的回答,但他排队的那两句仍然成立。 代价是「停止后系统自己开跑新一轮」这个反直觉现象(§7.9 用例 8、§9.3 第 5 条), 所以 §6.3 约束 5 要求 UI 明示剩余条数并提供一键清空。这是产品决定,不是技术决定。
清空用 DELETE /api/session/:id/inbox(§5.12、§7.9 用例 9),不是前端循环调 DELETE /api/message/:id。理由:逐条撤回有 N 个请求、中间任何一条撞上 trySchedule 就 404, 前端得容忍「清了一半」;批量清空由服务端一个事务解决,并推 N 帧 message_cancelled。
5. Reconcile 标 failed 的 run 要不要补终局帧 —— 已决:补,且由编排层补会话级的那一帧。
选 (a) 补帧而不是 (b)「让 run 级流在档案非 running 且无更多帧时主动收尾」: (b) 不写库,但把「run 结束了吗」的判定从数据挪到了传输层,与不变量 6 的精神相悖。 终局是事实,事实就该落在事实真源里。
V4 相对早期设计多做了一步:Reconcile 返回 []FailedRun,由 Server 逐个 sessionLog.Append(run_terminal)(§5.3、§7.8)。这是两个真源互不认识(§3 的依赖方向) 的必然结果——RunLog 不能替 session_log 写帧。
6. POST /api/message 的 202 要不要带响应体 —— 已决:带 {"seq","messageId"}。
早期草稿决定「202 无体」,前提是「响应体里再没有服务端才知道的信息」—— 这个前提是错的:seq 只有服务端知道,而它是会话级流的续传游标。 没有它,「投递」与「流」之间就没有对账锚点:客户端重连时只能用自己记的 lastSeq, 分不清「没收到 m_1 的帧是因为它没入队」还是「我的 from 起点太靠后」(§5.12)。
同时明确禁止 {"queued":true} 这类状态字段:那要求 Enqueue 同步知道 trySchedule 的结果,把异步调度变成同步等待。「排队还是已开跑」由会话级流的帧报告。
7. 各种 id 由谁生成 —— 已决:分两类,标准是「它是不是资源身份」。
| id | 谁生成 | 为什么 |
|---|---|---|
sessionId |
服务端(POST /api/session) |
它是资源身份。准入检查、会话列表、孤儿回收、重启续答全靠它(§1.2) |
runId |
服务端(beginRunAtomic 内) |
同上,且它的发布时刻受不变量 9 约束 |
messageId |
客户端(UUID 形状) | 它是绑草稿的幂等键 + 回放对齐键,不是资源身份;客户端必须在发出请求之前就知道它(§1.2、§6.3 约束 6) |
clientId |
客户端 | 它是设备标识,不承担「这个资源存在吗」的问题 |
messageId 客户端生成还顺带给了一个 fencing token 的位置:expectedRunId 让服务端能判断「你说的那场已经不是现在这场了」(409 stale_view), 比「runID 只在提交后可见」更强——它还能检测客户端视图过期。 服务端仍要保证 messageId 在本会话内唯一(主键是 (session_id, message_id),§5.7; 冲突则 409 message_id_taken,这是正当的 409:它表达「你重复投递了」,不是「你来得不是时候」)。
messageId 为什么不由服务端铸造:三角约束,三者只能取二。
- id 由服务端铸造(形状漂亮、会话内递增,如
m_17) - 客户端在发出请求之前就知道 id(否则重发无法被认出)
- 服务端不为此新增任何状态
本方案取 2 + 3。第 1 条的收益纯粹是可读性,而可读性已经由 seq 承担 (排序、日志、「第几条」全走 inbox.seq / session_log.seq,messageId 从不参与排序), 所以放弃它不损失任何功能。至于「客户端为了不撞而在 id 里拼 clientId」——那是 A 的正当形态之一: clientId 本来就在请求体里,用 crypto.randomUUID() 更省事,两者都不承担可读性。
被排除的两个候选(都是取 1 + 2、放弃 3):
- B 案:幂等键分离(Stripe 式)。客户端带一个不透明的
clientKey,服务端 mintmessageId并永久保存(session_id, clientKey) → (messageId, seq)映射;重放同一个 key 返回原来那份 202 响应体。它是三案里去重最强的——连「消息已被 Drain 之后迟到的重发」都能识别。 排除理由:成本与收益不成比例。 映射行必须与 inbox 插入同一个事务 (否则「插了 inbox、还没写映射」的窗口崩掉就重复),于是一张只增不减的永久表、 它的 GC 策略、一个新错误码(同 key 配不同 text 要能拒)、帧里多背一个clientKey字段, 全都是为了把一个 UUID 变好看。 - C 案:预分配号池。发送前先向服务端领号(
POST /api/session的 201 带第一个,另开补货端点)。 领号行是永久记录,去重强度与 B 相当,且客户端发前就知道 id、对齐免费。 排除理由:它把通用问题做成了特例。「第一条」由创建接口赠予,后面每一条都要靠补货端点—— 于是客户端要维护号池、低水位补货,两个标签页各持一把号会让 id 空间交错留洞, 号池耗尽时发送路径上凭空多一个 RTT。发号器还必须放在数据库里 (多副本下进程内计数器失效,与 §5.9 的闸同一条理由),等于 B 那张表换个形式回来。
残留风险(照实登记):客户端跳过回放直接重发(前端 bug,或用户手动连点), 且那条消息已被 Drain → inbox 里没有行了 → 插成新行 → 同一句话被回答两次。 §6.3 约束 6 把这条路堵在前端,服务端不兜。 启动条件:实测出现重复回答。补救方向就是 B 案那张映射表——先不做。
8. 「会话」是不是服务端资源 —— 已决:是。Registry + session 表(§5.6)。
早期设计里 sessionId 只存在 localStorage,服务端只有 map[string]*Engine 这个进程内表—— 换浏览器就是新会话,清缓存就丢历史,且「未登记的 id」与「打错的 id」无法区分。 V4 把它提成登记资源:未登记一律 404,绝不隐式创建(不变量 1)。 这同时是账号级订阅(问题 15)的硬前置。
9. 服务端回显还是本地 pending 气泡 —— 未决,倾向先服务端回显。
§6.3 约束 2 定的是服务端回显(message_queued 帧画出气泡),代价是一个 RTT 的延迟感。 另一个选项:客户端用自己生成的 messageId 立刻画一个 pending 气泡, 帧到达时按同一 ID 对齐——即时感回来,且不需要「猜哪条是自己的」(ID 是同一个,对不上就是对不上)。
倾向:阶段一先服务端回显(§6.2 的状态机只有三态,简单且天然一致); 若实测延迟感明显,再加 pending 态。采纳后 §6.2 的状态机要多一个态、§6.3 约束 2 要改写, 所以这个决定要在第 10 步(冒烟前端)之前做完。
10. session_log / run_log 要不要修剪 —— 未决。
两者都是永久追加的,长会话会无限增长。修剪与 from=seq 续传直接冲突: 若 from 早于已修剪的最小 seq,不能静默丢帧(§7.10 竞态表最后一行)。 两个选项:(a) 不修剪,靠归档/分表;(b) 修剪,并给续传加一个显式信号 「你落后太多,请重新拉 Snapshot」(一种新的错误 code,前端据此走用例 3 的重建路径)。
倾向 (b),但它要求前端有一条完整的「重建」路径,所以启动条件是第 10 步之后。 两张表一起解决,不要分别定策略。
11. inject 模式怎么表达「已被消费」 —— 未决,倾向加一种会话级帧。
inject 消息直接进了正在跑的这一轮,后面不会跟 run_started(§7.9 用例 16), 所以前端不能用「有没有 run_started」判断它是否被消费。两个选项: (a) 新增 message_injected 会话级帧(干净,但多一种帧); (b) UI 对 inject 消息只显示「已插话」不再跟踪状态(够用,但状态机有例外)。 倾向 (a)——状态机有例外的代价,通常在写第三个用例时才显现。随第 12 步一并定。
12. 多副本部署下的三处进程内机制 —— 两处已在第一版设计中消除,一处未决。详见 §13.5。
目标是多副本(Postgres + Redis/asynq),SQLite 只是测试替身, 所以「单进程」不能当任何设计的论据。早期设计有三处进程内机制会被多副本打断; V4 定稿把前两处直接设计掉了(Engine 无状态化),只剩第三处:
| 机制 | 状态 |
|---|---|
闸(s.mu + s.live) |
已决且已消化进第一版设计:Engine 无状态,闸只有 DB 部分唯一索引 one_live_run_per_session 一种形态,插入失败本身就是闸(§5.9,随 §10 第 7 步落地,SQLite 上就能验)。早期设计的「进程内 mutex + 哨兵」已删除,不是「转正」而是从未存在 |
审批(早期设计的 pending map[string]chan string) |
已决且已消化进第一版设计:approval 表 + Approvals(决策写库 = 真源,本地通知只是加速,等待方靠轮询兜底跨副本,§5.11)。副本 B 收决策、副本 A 的 ask 照常醒来——「决策 POST 落错副本 → 404 → 永久卡死」这个路径不存在了 |
| 事件缓冲(Subscription 的内存尾部) | 仍未决,是仅剩的一处:需要 Subscription 的第二套实现(读库 + 轮询/通知)。接口已分层,换实现不动调用方。随多副本部署做 |
13. 一条 WS 多路复用,还是每会话两条 SSE —— 未决,阶段三第 18 步。
浏览器对同一 host 的 HTTP/1.1 并发上限是 6,SSE 长期占坑: 2 个标签页 × 2 条 = 4 个坑,只剩 2 个给普通请求(§9.1)。 这个缺陷只在多标签页下暴露,而多标签页正是本方案要修的场景——所以它不是理论问题。 外部产品用一条 WS 多路复用所有会话绕开了它(§12.4)。 §5.8 的 SessionFeed 已按可互换设计,换传输不用改存储层。
14. 要不要换到 adk.TurnLoop 底座 —— 未决,阶段二之后评估(§10 第 22 步)。
TurnLoop 是 eino 原生的「收件箱 + 调度器」,本方案的 Inbox / trySchedule / 合并窗口 / checkpoint-resume 有逐条对应物,而且它的 Push(item, WithPreempt()) 比 「下一个 round boundary 插入」更强(能打断当前正在跑的 turn)。 详细对照见项目记忆与 §13.3。
但换底座等于同时改语义层和执行层,而本方案的全部风险预算应该花在 语义层(阶段一)与数据面(阶段二)上。阶段一第 12 步的 inject 用 middleware 走 BeforeModelRewriteState 实现——不需要新机制,eino 已经把这个钩子造好了, 本方案的 compact 与 mediaoffload 两个 middleware 就是现成样板。
15. 账号级订阅 —— 未决,阶段三第 19 步。
「一个账号多个会话,在一个页面看全部」需要账号概念 + 账号级的第三层订阅(§4.2)。 硬前置是问题 8(会话成为服务端资源)——已满足。剩下的前置是账号体系本身, 它不属于运行引擎,所以不在本方案范围内,只在 §4.2 的三级模型里留了位置。
12. 外部产品的帧协议,以及它暴露的阶段一数据面复杂度(阶段二设计依据)
本节起点是观察 + 判断,在此升格为阶段二(数据面)的设计依据 (§10 第 13–17 步、§11 问题 12 之后的那一组决议)。阶段一的数据面仍是 Partial/sealed。 记在这里是因为:对照之后发现阶段一有几块复杂度是建模方式的产物,不是问题本身的。 证据来自对
POST www.kimi.com/apiv2/kimi.gateway.chat.v1.ChatService/Chat响应流的抓包(一次「真的吗」→「1+1」的短对话,33 帧)。另一个参考实现(WeKnora)的对照见 §13——它与本项目更直接相关, 因为传输层的若干设计就是从它借来的,而它自己也已经走出去了。
12.1 观察:帧的形状
{heartbeat{}}
{op:"set", mask:"chat.lastRequest", eventOffset:1, ...}
{op:"set", mask:"message", eventOffset:2, message:{role:"user", status:"MESSAGE_STATUS_COMPLETED", blocks:[{text:{content:"真的吗"}}]}}
{op:"set", mask:"message", eventOffset:3, message:{role:"assistant", status:"MESSAGE_STATUS_GENERATING"}}
{ heartbeat{}, eventOffset:3}
{op:"set", mask:"chat.name", eventOffset:4, chat:{name:"1+1算式验证"}}
{op:"set", mask:"block.text", eventOffset:5, block:{id:"1", text:{content:"是的"}}}
{op:"append", mask:"block.text.content", eventOffset:6, block:{id:"1", text:{content:","}}}
{op:"append", mask:"block.text.content", eventOffset:7..31, ...} ← 每次只推增量片段
{op:"set", mask:"message.status", eventOffset:32, message:{status:"MESSAGE_STATUS_COMPLETED"}}
{ done{}, eventOffset:33}
实体是一棵树:chat → message → block。帧说的是「某实体的某字段变成了这个值」: mask 是字段路径,op 是应用方式(set 覆盖 / append 尾部追加), eventOffset 是跨实体类型全局单调的游标。
12.2 与本方案阶段一的对照
| 维度 | 阶段一(§5.1–5.3) | 增量协议(阶段二) |
|---|---|---|
| 帧的含义 | 「发生了一件事」 | 「某字段变成了这个值」 |
| 客户端要做的事 | 理解 kind 语义,按 kind 分派渲染 |
维护一棵树,按 mask 打补丁 |
| 分类器 | 需要 Classify 把 eino 消息翻译成领域帧 |
不需要——没有「翻译」,只有「字段变了」 |
| 流式正文 | 同一预留 seq 反复推全文,n 个字 = 1+2+…+n = O(n²) 字节 | append 只推增量,O(n) |
| 「流式中 → 定稿」 | Partial 帧不落库 + AppendSealed + ErrSealConflict + dropPartialTail + 游标不前移 + 防忙等 |
op:"set" mask:"message.status" 一次普通字段变更 |
| 崩溃窗口 | Partial 不落库 → 进程死在流结束与 seal 之间,那条正文彻底没了(§9.2) | message 实体在 offset 3 就已存在,append 累积到哪儿库里就是哪儿 → 窗口不存在 |
| 用户自己那句话 | 服务端回显:message_queued 帧带全文(§6.3 约束 2) |
同样从流里回显(offset 2)→ 两者一致,这一条阶段一已经做对了 |
| run 中途的元数据变更 | 无法表达(run 级 seq 是 per-run,chat.name 这类东西没有位置) |
mask:"chat.name" 与内容帧共用一个 offset 序列 |
| 保活 | 无心跳 | heartbeat 带 eventOffset,客户端能区分「服务端卡住」与「在等 LLM」 |
| 流的终止 | 读终局帧(kind 三选一),run 级流见终局即关 |
done:{} 显式终止符,且它说的是「这条流完了」而非「这个会话完了」 |
注意倒数第五行:「用户那句话从流里回显」是阶段一与阶段二共同的选择, 不是阶段二要改的东西。多客户端同步因此免费(§7.9 用例 5)。 把它列进对照表是为了说明:阶段一在这一点上没有欠债。
12.3 最重的一条:Partial/sealed 是建模产物
阶段一为了「流式正文」需要一整套特殊机制(预留号、seal、冲突检测、尾部作废、游标不前移)。 根源在于把「正在输出」建成了一帧帧事件,于是必须回答「哪一帧才算数」—— 答案是「都不算,直到 sealed 那一帧」,整套机制由此展开。
增量协议把「正在输出」建成一个持久实体的一个状态字段(status: GENERATING)。 实体从一开始就存在、就在库里,内容通过 append 持续累积。 「哪一帧才算数」这个问题不成立,于是整套机制没有存在的必要。
连带消失的还有「补发」这个概念。 早期设计里考虑过一条兜底: 进程死在 seal 之前时,让持有全文的客户端把它补发回库。三条理由否掉了它(§5.3)—— 其中最硬的一条是前提不成立:全文的唯一来源就是那条流本身,流断了才需要补发, 断了就说明客户端也没收全。而增量协议下这个窗口根本不存在,补发无的放矢。
所以阶段二不是「省掉一个已经工作的兜底」,是让一个明知敞开的窗口结构性消失, 顺带省掉整套 Partial 机制。这是 §12.5 判断的核心依据。
12.4 连接拓扑:两条 SSE 不是唯一解
Kimi:1 条常驻控制流(WS,per 账号,多路复用所有会话)
+ 1 条长命数据流(流式 POST,per 一次 Chat 调用,跨越「排队」与「执行」两个阶段)
本方案:1 次短 POST(投递,JSON 应答)
+ 1 条常驻会话流(SSE)
+ N 条 run 流(SSE,一场一条)
实测细节(抓包佐证上面的拓扑):
| 观察 | 说明的机制 |
|---|---|
wss://notilo.kimi.com/im/v1/subscribe/ws?encoding=proto&ticket=<ticket> |
控制面 = WS + Protobuf + 多路复用 + 短时 ticket 鉴权 |
逐字输出走 POST …/ChatService/Chat,不走 WS |
数据面 = 流式 POST,与控制面物理分离 |
控制面挂在独立子域 notilo |
IM 基础设施复用,独立扩缩容域 |
| ticket 走 URL 参数 | 浏览器 JS 无法给 WS 设自定义 header,所以 ticket 必须是短时的 |
Kimi 的连接数更少,且天然没有「拿到 runID 却订阅不到」的竞态—— 它的流绑定的是「一次 Chat 调用」而非 runID,调用可以先排队后执行, 流一直开着,客户端从流里得知后续状态。本方案的不变量 9 是为了治这个竞态发明的; 在那个拓扑下它不需要被治,因为它不发生。
但 Kimi 的控制面 WS 依然必需:数据流只承载这一次调用产生的状态增量, 「B 删了会话」「会话列表多了一条」这类跨调用的事只能走 WS。 所以两个逻辑通道的划分是对的(§4),有争议的只是物理连接怎么摆。
本方案选两条 SSE 的理由是简单:不需要 WS 库、不需要 ticket 鉴权、不需要多路复用协议。 代价是浏览器连接上限(§9.1、§11 问题 13)。 这是一个「先能跑,再优化」的选择,不是终局——§5.8 的 SessionFeed 分层 就是为了保住这条演进路径。
顺带一条澄清(§2.3 已写进不变量的注脚):「POST 返回流」本身无罪, 外部产品的数据面恰恰就是流式 POST。有罪的是「一条连接既是执行的生命线又是观察的窗口」 与「冲突时拒绝投递」这两件事——改掉这两点,返回不返回流是自由选项。
12.5 判断:分两阶段——阶段一不动数据面,阶段二按本节重写
采纳增量协议要重写的东西:Event / StoredEvent / Classify、RunLog 的全部写方法、 Subscription 的 Partial 分支、前端整套渲染、以及测事件形状的大部分测试。 这是一次独立的重写,量级不小于阶段一本身。
而阶段一要解决的问题(投递被拒、排队、多客户端同步、重启续答)一个都不依赖它—— 它们全在入口与调度层。把两件事捆在一起做,会把两处的风险叠加, 且丢掉阶段一最好的性质:执行与档案这两个最难的部分可以一次写对、之后不动(§9.4)。
所以结论不是「不做」,而是分阶段:阶段一落地入口与调度(数据面用 Partial/sealed), 阶段二按本节重写数据面(§10 第 13–17 步)。阶段二不是另一个版本,是本方案的后半场; 它的启动条件是阶段一全绿——而「投递永不因冲突失败」从第 7 步起就直接站在 DB 上 (闸的部分唯一索引,§5.9)。
唯一现在就值得做的是 §5.8 的 SessionFeed 分层——它让将来换传输 (SSE → WS 多路复用)不需要动存储层,成本几乎为零,收益是保住演进路径。
13. 附录:外部来源、一次错判、多副本审计
§12 对照的是 Kimi(外部产品,抓包所得)。本节对照的是
ref-agent/WeKnora(腾讯,Go + Gin)——本项目传输层若干设计的直接来源。 它比 §12 更要紧的地方在于回答了另一个问题: 「参考实现自己有没有走出这条路?」答案是走出去了,而早期的设计没跟上。
13.1 借了什么,逐条对上
| 本方案 | WeKnora | 位置 |
|---|---|---|
| 没有继承:投递与回答共用一条流 | POST /knowledge-chat/:session_id → @Produce text/event-stream,同一个请求既提交输入又流回输出 |
internal/router/routes_chat.go:119-128;internal/handler/session/qa.go:890,920 |
| 失去对象:「冲突判断必须在写 SSE header 之前」。V4 里没有状态冲突可判(不变量 7) | 注释原文:「SetLiveRun happens before SSE headers: a 409/503 after text/event-stream has started cannot change the status, and the client would sit on a stream nobody will write to」 | qa.go:710-712;helpers.go:183 |
| 保留:run 级流要先知道 runID | GET /sessions/continue-stream/:session_id?message_id=…——同样要先知道 ID |
routes_chat.go:87;stream.go:35 |
★ 核心增量:会话级推送通道(session_log + 常驻 SSE) |
没有。全仓唯一的 WebSocket 是 sandbox 终端/桌面中继,与对话无关 | routes_chat.go:137-157 |
★ 核心增量:两条流都支持 from=seq 续传 |
GetEvents(ctx, sessionID, messageID, 0)——从 0 全量重放,全仓无 Last-Event-ID |
stream.go:116;frontend/src/utils/steerStreamFork.ts:79 |
| 继承并加强:客户端只存 sessionId、不存对话内容;sessionId 改为服务端登记 | localStorage 只有 embed session ID、模型选择、分组模式 | frontend/src/api/embed/index.ts:143 |
结论:本方案的传输层是 WeKnora 的下游,连「409 要在 SSE header 之前」的论证文字都同理同辞。 而 V4 相对它多出来的两样(会话级通道、from=seq 续传),恰好是它没有的那两样。
13.2 但 WeKnora 自己已经走出去了:steer
routes_chat.go:72-79 有四个路由,注释写着「Mid-run message injection」:
POST /sessions/:session_id/steer 投递一条消息
GET /sessions/:id/steer 列出排队中的
DELETE /sessions/:id/steer/:steer_id 撤回
POST /sessions/:session_id/steer/:steer_id/inject 手动提升到正在跑的那一轮
路由注释里有一句是决定性的:
Accepts even when no run is live (the client then falls back to a normal send)
即投递永不因状态冲突失败——这就是本方案的不变量 7。而这四个端点与 §5.12 的 POST /api/message / GET /api/session(Snapshot 的 queued)/ DELETE /api/message/:id 一一对应,WeKnora 还多一个本方案列为后置能力的「提升」(§11 问题 11、§7.9 用例 16)。
所以准确的判断不是「被 WeKnora 带歪了」,而是:抄了它的止血层,没抄它的治疗层。
而它只能止血是有原因的——它是多副本部署(Redis-backed StreamManager)。 steer.go:29-33 那句注释说明了这个约束:
steerDataConsumed… lives on the event itself (not in process memory) so every replica agrees on what is still pending
多副本下不能重写入口(会破坏其他副本上正在跑的 run),只能挂在旧协议旁边。 本方案的两个新组件(inbox、session_log)都是 DB 表, 独立走到了同一条教训的同一个答案(§13.5)。
13.3 借鉴纪律:区分「当前态」与「演进方向」
ref-agent/ 的纪律是「借设计,不抄实现」。这里暴露了一个盲区。
早期笔记对 WeKnora 的两处判断,分类恰好都错了:
| WeKnora 的东西 | 它的实际性质 | 早期笔记把它归成 |
|---|---|---|
| 「SetLiveRun 在 SSE header 之前」+ 409 | 历史遗留——被多副本 + 生产流量锁死,动不了 | 定律(「踩坑换来的,照学」)→ 升格成了一条不变量 |
| steer(投递永不失败) | 演进方向——它正在逃离上面那条遗留 | 可选功能(「第一期不做」) |
把别人的遗留当定律抄进不变量,把别人的演进当可选功能划掉。
排除清单本身没有错——第一期不做 steer 是完全合理的范围控制。 错在同时把 409 提升成了不变量:于是「暂不做 steer」从一个可撤销的范围决定, 变成了一个有约束力、要在测试里守护的架构法律。 范围决定可以随时改;不变量改起来要动测试、动文档、动心智模型。
可操作的检查方法,两条,缺一不可:
- 在参考实现里 grep「挂在旧协议旁边的新端点」——它们通常是演进的足迹。 本例中
steer就是这样一个端点:它不接受「会话忙」的拒绝, 与同一仓库里 20 行之外的 409 逻辑语义矛盾。那个矛盾本身就是信号。 - 找到那个「遗留」之后,问一句「它是因为什么约束才不得不存在的?」。 本例的答案是「多副本 + 生产流量」。如果那个约束在你这里也成立 (本项目目标栈是 Postgres + Redis/asynq,成立,§13.5), 那它对你就是未来的债,不是可以照抄的定律;如果不成立,那它是纯粹的包袱,更不该抄。 两种情况下「照学」都是错的。
这条纪律也适用于框架,不只适用于参考实现。 eino 的 adk.TurnLoop 本身就是「收件箱 + 调度器」,本方案的 Inbox / trySchedule / 合并窗口 / checkpoint-resume 在它里面都有对应物(§11 问题 14)——本方案在重造它,且是明知故犯。 理由不是「没看见」,是「换底座等于同时改语义层和执行层,而风险预算只够改一层」。 把「知道有更好的轮子、并说清为什么暂时不用」写进文档, 比假装那个轮子不存在诚实得多。
13.4 一次错判:「POST 返回流」不是原罪
错判的内容:早期设计里有一条不变量叫「响应三态不得跨越:未提交 / 已提交 / 已结束」, 它的实际作用只有一个——要求「409 必须在写 SSE header 之前判完」。 它被当成了一条普适的架构法律。
为什么错:这条不变量保护的不是「响应语义清晰」,而是「POST 的含义是开一场 run」。 一旦 POST 的含义变成投递(写进 inbox 就成功), 「未提交 / 已提交 / 已结束」这三态就不再是响应的属性,而是run 的属性—— 它由会话级流的 run_started / run_terminal 帧报告,与那个 202 无关。 不变量保护的对象消失了,不变量本身却还在。
正确的因果方向(§2.3 已写进正文):
不是「因为不返回流所以不用判状态」,而是「因为没有状态冲突可判,所以不必返回流」。
这次错判的第二个层面,比第一个更值得记:发现它之后, 我在论证另一个决定(sessionId 该由谁生成)时,引用了已作废的旧实现里的代码行号作为依据。 被当场指出:那份实现跟不上方案的进化,已经作废了。
两层教训合成一条:承重论断的前提,只能来自代码、配置、和用户的话—— 不能来自文档注释、记忆、或印象。 而「已作废的实现」连代码都不算: 它既不是现状,也不是约束,引用它等于用一个不存在的东西论证一个真实的决定。 V4 从头重写、并把旧实现整体转为备份(§10 第 1 步之前的那个动作), 就是要让「引用旧代码当论据」这件事在物理上做不到。
13.5 多副本审计
目标栈是多副本:Go + Gin + PostgreSQL/pgvector + Redis(asynq 任务队列)+ Vue。 asynq 是分布式任务队列 → 多 worker。SQLite 只是当前的测试替身,公测都不会用。 所以「单进程」不能当任何设计的论据——这一节把本方案的设计逐项过一遍,判定它在多副本下是否成立。
审计结果:三处进程内机制,两处已在定稿设计中消除
早期设计有三处会被多副本打断的进程内机制。定稿把前两处直接设计掉了 (Engine 无状态化,§5.9),不是「留到转正」:
| 机制(早期设计的形态) | 定稿的处理 |
|---|---|
闸(e.mu + e.live + 哨兵) |
已消除:Engine 无状态,闸只有 DB 部分唯一索引一种形态(见下)。「两个副本各开一场 run」的路径不存在——两边都会去 INSERT,唯一索引裁决 |
审批(pending map[string]chan string) |
已消除:approval 表 + Approvals(§5.11)。决策 POST 落到任何副本都写同一行;持有 run 的副本靠「本地通知(快)+ 轮询该行(慢但跨副本)」收敛。「落错副本 → 404 → 永久卡死」的路径不存在 |
| 事件缓冲(run 级 Subscription 的内存尾部) | 仍未决,是仅剩的一处:订阅只在拥有该 run 的副本上能拿到实时帧;其他副本只能读库追赶,Partial 帧永远看不到(它本来就不落库)。阶段二第 14 步之后正文随 append 进库,「永远看不到」这个前提消失,剩下的只是实时帧的跨副本投递问题(归传输层) |
WeKnora 正是为此才有 internal/stream/ 的 memory_manager 与 redis_manager 两套实现。 本方案的 RunLog / SessionFeed 已经是接口,迟早也要写第二套—— 这不是设计缺陷,是分层的收益兑现之处(换实现不动调用方)。
另一处照实登记的已知洞:Archive 的跨 run 内存缓存在多副本下不会跨副本失效 (副本 B 上的旧缓存看不到副本 A 跑出的新轮次)。单副本下闸的串行化保证它正确; 多副本的修法(失效广播,或每场 run 开跑时冷装)随上表第三行一起做(§5.4)。
恰好成立的部分
inbox、session_log、session、approval 都是 DB 表,不是进程内存。 这正是 WeKnora steerDataConsumed「lives on the event itself, not in process memory, so every replica agrees」那条教训的同一个答案。
更关键的是 beginRunAtomic:inbox.Drain + BeginRunInTx + run_started 在同一个事务里。 这是数据库级原子性,跨副本天然成立——不需要分布式锁,不需要 Redis。
闸为什么是部分唯一索引,而不是 Redis 标记
「每会话最多一场 live run」表达成数据库保证:
-- 部分唯一索引:同一会话最多一行 status='running'
CREATE UNIQUE INDEX one_live_run_per_session
ON run_archive(session_id) WHERE status = 'running';于是 trySchedule 的语义是:
两个副本同时 trySchedule
→ 都在同一事务里做 inbox.Drain + INSERT run_archive(status='running')
→ 先提交的成功;后提交的撞唯一索引 → 事务回滚 → Drain 的消息自动回到 inbox
→ **插入失败本身就是闸**
不需要 Redis,不需要分布式锁,不变量 8 在多副本下照样成立—— 因为闸和事实在同一个事务域里。
对比 WeKnora:它用 Redis SetLiveRun + ErrLiveRunExists(redis_manager.go:15-17,383) 做这件事,因为它的事件缓冲已经在 Redis 里了,顺手。本方案用部分唯一索引更省一次网络往返, 而且闸的判定与 run 的创建不可能不一致(同一个事务)—— Redis 方案里 SetLiveRun 与后续写入是两个操作,中间有窗口。
SQLite 也支持部分索引(
CREATE UNIQUE INDEX … WHERE), 所以这一条在当前测试环境下就能验证,不必等 Postgres(§10 第 7 步的门槛)。
一处更正:窗口是「未上线」,不是「单进程」
早期草稿在这里写过一句错的话:「本项目是单进程 SQLite,恰恰有条件做治疗—— 这是相对 WeKnora 的优势」。错在两处:目标栈不是 SQLite(见上); 而且「能重写入口」的真正理由不是进程数,是还没有生产流量。
WeKnora 不能重写入口,是因为旧路径上有真实用户、跨着多个副本,重写会破坏正在跑的 run。 本方案能重写,是因为它一行都还没上线。
这不是持久优势,是一个正在关闭的窗口。 公测之后本项目就会处在 WeKnora 今天的位置:旧入口上有真实用户, 重写变成破坏性变更,只能在旁边挂 steer 式的补丁, 然后再花几年时间解释「为什么我们有两套并存的输入语义」。
所以原结论方向对、理由全错。正确的表述是: 现在做治疗是唯一的免费机会,而且它与多副本目标不冲突——本节以上各段论证这一点。
结论
多副本目标不推翻本方案,反而是它的一个论据: 新增的组件(session / inbox / session_log / approval)本来就是 DB 表, 事务原子性本来就是数据库级的;曾经会被打断的三处进程内机制,两处在定稿里从未存在 (Engine 无状态化把闸与审批直接设计在 DB 上),只剩事件缓冲一处未决且接口已分层。
换句话说:本方案相对旧设计的改动,恰好是多副本方向上的改动; 而 V4 定稿又把其中两处从「将来要改」提前成了「第一版即如此」。 这不是设计时预料到的——全部动机是「投递被拒」与「多标签页画面分裂」——但结果是对的。