tako 文档 GitHub

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),不由客户端生成。理由是三条,都来自本方案自己的前提:

  1. session_log 的 lastSeq:0 必须有出处。 它是第三真源,「从 0 开始重放」这句话要有起点; 起点就是登记表里那一行(session_id + created_at)。若 sessionId 由客户端生成, 服务端面对一个空日志就分不清「会话刚建、还没有帧」和「查无此会话」——seq 0 只由客户端报的 一个字符串召唤出来,背后没有创建事实兜底。 创建事实不写成 session_log 的帧——那会多出一个除创建者自己重放以外没有任何消费者的帧类型。
  2. 目标是多副本部署(§13.5)。会话身份要在副本之间可路由、可归属。客户端生成的 UUID 唯一性没问题,但没有创建事实——配额、回收、会话列表、账号级订阅全都无从下手。
  3. 重启续答(§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 推论:哪些东西不能互相重建

每一份都只有它能回答的那个问题。

另有三张辅助表不算「持久状态」,因为它们不回答任何新问题: 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

谁持有谁:

依赖方向: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_<...>。 三个要求:

  1. 多副本安全——不能依赖单进程计数器或数据库自增序列(换 Postgres 后序列可用, 但 ULID 让「id 由谁发」这件事与存储解耦)。
  2. 趋势递增——会话列表将来要按创建时间排,id 本身可排就省一个索引。
  3. 带前缀——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 由事务本身兑现:

导出方法:

// 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) error

5.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)

没有的路由(明确不留,免得将来被当成「忘了实现」):

每个 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 六条必须遵守的约束

  1. 发送按钮永远可用。 不存在「busy」这个概念——用户随时能投递,投递永远成功。 停止键按 liveRunId 是否非空显隐,与发送键无关。
  2. 服务端回显,不要本地回显。 send() 只 POST,用户气泡由 message_queued 帧画出 (帧里带 text 全文,正是为此)。POST 失败就把输入框内容还回去。 代价是本地回显的那点即时感没了(多一个 RTT),换来的是 所有客户端画的用户消息来自同一个 seq 序列——同步是免费的。 本地先画一个气泡会让两端时序不同,撤回时更容易对不上。
  3. 前端不保存任何服务端不知道的状态。 刷新后靠 Snapshot + 会话级流冷启动重建, 不需要本地存储兜底对话内容。本地只存两样:sessionId(资源句柄)与 clientId(设备标识)。
  4. 撤回的语义边界要在 UI 上表达清楚:只有 queued 且尚未出现在任何 run_started.messageIds 里的气泡能撤回。一旦被消费,撤回按钮消失 (服务端 Cancel 会返回 404,但前端不该让用户点到)。
  5. 停止后必须提示队列还在:Stop 不清收件箱(§5.9),所以按下停止后如果还有排队消息, 它们会立刻开跑。停止按钮旁边要明示「还有 N 条排队,会继续」并提供一键清空 (DELETE /api/session/:id/inbox),否则用户会觉得「我明明停了它怎么又跑了」。
  6. 重发必须在回放到位之后,且复用同一个 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. 完整链路:八幕

前六节讲的是「每个组件是什么」,这一节讲「它们怎么串起来」。 一个贯穿全节的例子:

会话级 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 循环里一变二:

进图前先认识两个词:

模型吐 *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 闭包接住中断,做五件事:

  1. 生成审批 id,approvals.Create 先落一行 decision=NULL 的审批行(§5.11:行先于帧存在);
  2. emit 一帧 approval——读者立刻看到审批卡片(走的就是第三幕的 B 路);
  3. 挂起:approvals.Wait 阻塞在双通道上(本进程通知 + 低频轮询审批行),什么都不干;
  4. 决策从 POST /api/approval 进来,Engine.Approve → Decide 写库 + 唤醒等待者 (决策的真源是审批行,所以这个 POST 落到哪个副本都一样;与 Stop / 断连的竞态处理见 §5.11);
  5. 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:

这也是 §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 都按这个写):

用例索引(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 新的失败模式

  1. 会话级长连接断开期间的事件会丢——所以会话级流必须支持 from=seq 续传, 这不是可选优化。session_log 持久化就是为它存在的(§7.9 用例 14)。 实现上最易错的一点:前端的 sessionSeq 必须每收一帧就更新, 报小了会重放(气泡重复,可靠 messageId 幂等兜住),报大了会丢帧(兜不住)。
  2. beginRunAtomic 事务失败时,消息何去何从? 它已从 inbox 被 Drain,事务回滚则恢复——回滚本身是安全的。 但需要一个重试策略,否则消息会躺在收件箱里直到下一次 Enqueue 才被捞起。 阶段一的处理:回滚 + 退回收件箱 + 写一帧会话级错误,由下次投递触发重试(§5.9、§11)。
  3. 合并窗口让「我发的那句」与「回答」不再一对一。 UI 必须能表达归组关系,否则用户会困惑「我只问了一句,为什么回答里在讲两件事」。 message_ids(§5.10)就是为此存在的,run_started.messageIds 是它的线上形式。
  4. 服务端回显引入一个 RTT 的延迟感(§6.3 约束 2)。 用户按下回车到气泡出现,从「立刻」变成「一个来回」。 这是拿即时感换多端一致性,是取舍不是纯收益。 阶段一先用服务端回显(简单、天然一致);若实测延迟感明显, 可用「客户端生成的 messageId 先画一个 pending 气泡、帧到达时按同一 ID 对齐」补回即时感—— 这条已列为 §11 的待定项,采纳后 §6.2 的状态机要多一个 pending 态。
  5. 停止之后系统会自己开跑新一轮(§7.9 用例 8)。 这是产品决定而非 bug(停止的语义是「这一轮不对」,不是「我说的话不算」), 但它反直觉到必须在 UI 上明示,并配一个一键清空(用例 9)。 不做这两件事,用户会认为系统失控。
  6. 重发跳过回放,会让同一句话被回答两次(§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 路两个阶段都不动。


10. 实施顺序

本方案分三个阶段:阶段一只做入口与调度,数据面沿用 Partial/sealed; 阶段二按 §12 的增量协议重写数据面;阶段三是连接拓扑与新入口。 分阶段的理由在 §12.5——数据面重写的量级不小于阶段一本身,捆成一步会把两处的风险叠加。

但分阶段 ≠ 分版本:阶段二是本方案的一部分,不是「以后再说」。 它的启动条件写在下面,条件满足就做,不需要重新立项。

实施方式是重写,不是重构(见文首):新 module 从零起步, 与运行引擎无关的能力包作为既有资产搬入(第 1 步)。

阶段一:入口与调度(第 1–12 步)

顺序原则是 先 API 契约、再存储、最后前端: 第 3 步就把路由表与错误体钉死并用 curl 手打验证(此时存储是内存假实现), 这样存储层是在已知契约下写的,不会出现「表设计好了才发现接口要改」。 前端排到最后,且阶段一只做冒烟页——产品前端是 Vue,属于独立 loop(§6)。

  1. 模块骨架 + 搬能力包:go.mod、cmd/yktako/、目录结构(§3); 把与运行引擎无关的既有资产搬入:internal/tools、guard、compact、 mediaoffload、msgtext、adkrun、config(含 provider-catalog.json)。 门槛:go build ./... 与搬入包的既有单测全绿。
  2. 领域类型与接口先行,不写实现:internal/run/event.go(十一种 EventKind、 Event、Approval、StoredEvent、Classify、Subscription)、 五个存储接口(RunLog / Archive / Registry / Inbox / SessionLog)、 SessionFeed、Engine 的导出方法签名、transport 的 DTO 与错误体。 门槛:go build ./... 过,Classify 的单测穷举四种输入(纯函数,此时就能测)。
  3. API 契约落地(存储用内存假实现顶着):Gin 路由表(§5.12)、 errorMapper(§5.13)、sse.go 的 Stream / StreamSession、各 handler。 门槛:curl 手打 §7.9 的用例 1、11、12,逐字节对响应体。 这一步不追求功能完整,追求「契约不再变」。
  4. RunLog 的 SQLite 实现:建表(§5.14)、BeginRun(InTx)、Append(含 Partial 预留号)、 AppendSealed、Finish(含 patch)、Reconcile(补终局帧 + 返回 []FailedRun)、 Subscribe、HistoryPage。门槛:sealed / 预留号作废 / ErrSealConflict 三类单测。
  5. Archive:ModelMessages、AddRun、Stage / CommitPatch / RevertStage、 Notify、WriteRAG。门槛:压缩后回退的单测(stage → revert → 视图必须与 stage 前逐条相同)。
  6. Registry + Inbox + SessionLog:三张表 + session_seq 同源计数器(§5.7)、 SessionFeed 的 Since / Subscribe、CloseSession、两个 Reconcile。 门槛:Put 与 Append 拿到的 seq 严格同源、不跳号、不重号。
  7. 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 步内必须证实或调整。
  8. Engine.Delete + 启动编排:DELETE /api/session/:id(场景 A); Reconcile 的四步顺序(场景 D,§7.8)。 门槛:§7.10 竞态表里的「删会话 vs 投递」与「重挂旧流」两条。
  9. §7.9 用例 1–9 全绿:curl + 两个 curl -N 手打,逐字节对; §7.10 竞态表六条各有一个测试。这是阶段一的总验收。
  10. 冒烟前端(go:embed 单页):只为「不用 curl 也能手工点一遍」, 不是产品前端。实现 §6.1 的启动编排与 §6.2 的状态机即可,样式从简。
  11. 文档同步:doc/ 下描述接口与存储的文档按本文校正;本文 §11 的决议销账。
  12. inject 模式(§7.9 用例 16,后置能力):Enqueue 加 delivery 参数、 inbox 表加一列、新增一个 middleware 走 eino 的 BeforeModelRewriteState 把 pending 消息 append 进 state.Messages。 放在最后,因为它依赖第 6–7 步,且失败时可以整块不做——没有它本方案仍然完整。

阶段二:数据面增量协议(第 13–17 步)

启动条件:阶段一第 9 步全绿。第 7 步起「投递永不因状态冲突失败」就直接站在 DB 上 (闸的部分唯一索引从第一版就生效)。设计依据是 §12:帧从「发生了一件事」改成 「某实体的某字段变成了这个值」,流式正文只推增量,「流式中 → 定稿」退化为一次普通字段变更。 §12 给出的是形状与判断,不是可实施的规格——所以第 13 步是先把规格写死。

  1. 协议规格:实体树(message → block)、op:set/append + mask 字段路径、 跨实体全局单调 offset、带 offset 的 heartbeat、显式 done 终止符。 落成文档:存储 schema、帧形状、续传语义 (重连 from=offset 时增量帧如何补齐——实体在库里,追赶者读实体当前态即可, 这是增量协议的续传比 Partial 简单的地方)。
  2. 存储层:message 实体在 status:GENERATING 时创建即落库,正文 append 累积进库。 §9.2 那个窗口从这一刻起结构性消失。
  3. 订阅层:删 Subscription 的 Partial 分支——预留号、AppendSealed、 ErrSealConflict、dropPartialTail、游标不前移、防忙等全部退役; run 级续传统一为「按 offset 追赶 + 读实体当前态」; 「流式中 → 定稿」变成一次 op:"set" mask:"message.status"。
  4. 前端:从「按 kind 分派渲染」改成「维护实体树、按 mask 打补丁」; done 终止符替换终局帧判定;heartbeat 带 offset 让客户端能区分 「服务端卡住」与「在等 LLM」。
  5. 测试与文档:测事件形状的用例大部分改写;文档同步,§11 决议销账。

门槛:第 15 步删 Partial 分支之前,先用测试钉住 「重连读者在流式中途加入,能看到实体当前态且不重不漏」。

阶段三:连接拓扑与新入口(第 18 步起)

启动条件:阶段二完成,且出现了下面任一具体压力。逐条列,免得被当成「以后再说」的垃圾场:

  1. 一条 WS 多路复用替换两条 SSE——启动条件:多标签页场景下浏览器连接上限成为瓶颈 (HTTP/1.1 并发上限 6,2 标签页 × 2 条 SSE = 4 个坑,§9.1)。 §5.8 的 SessionFeed 已做存储与传输分层,换 WS 不需要动存储层,只写一个 WS 实现。
  2. 账号级订阅——启动条件:出现「一个账号多个会话,要在一个页面看全部」的需求(§4.2)。 硬前置是 session 表已存在(第 6 步),且要有账号概念。
  3. MQ 投递——启动条件:多副本部署真的上线,且出现了「非浏览器的投递方」。 MQ 不承担崩溃兜底:那个职责在阶段二第 14 步已经由存储层接管(§9.2)。 MQ 剩下的唯一价值是多副本之间的投递与解耦。
  4. IM / cron 入口——启动条件:有真实的 IM 接入或定时任务需求。 它们只是「又一个 Subscribe」与「又一个 Enqueue」,引擎一行不改(§7.3 末)。
  5. 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) + (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 为什么不由服务端铸造:三角约束,三者只能取二。

  1. id 由服务端铸造(形状漂亮、会话内递增,如 m_17)
  2. 客户端在发出请求之前就知道 id(否则重发无法被认出)
  3. 服务端不为此新增任何状态

本方案取 2 + 3。第 1 条的收益纯粹是可读性,而可读性已经由 seq 承担 (排序、日志、「第几条」全走 inbox.seq / session_log.seq,messageId 从不参与排序), 所以放弃它不损失任何功能。至于「客户端为了不撞而在 id 里拼 clientId」——那是 A 的正当形态之一: clientId 本来就在请求体里,用 crypto.randomUUID() 更省事,两者都不承担可读性。

被排除的两个候选(都是取 1 + 2、放弃 3):

残留风险(照实登记):客户端跳过回放直接重发(前端 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」从一个可撤销的范围决定, 变成了一个有约束力、要在测试里守护的架构法律。 范围决定可以随时改;不变量改起来要动测试、动文档、动心智模型。

可操作的检查方法,两条,缺一不可:

  1. 在参考实现里 grep「挂在旧协议旁边的新端点」——它们通常是演进的足迹。 本例中 steer 就是这样一个端点:它不接受「会话忙」的拒绝, 与同一仓库里 20 行之外的 409 逻辑语义矛盾。那个矛盾本身就是信号。
  2. 找到那个「遗留」之后,问一句「它是因为什么约束才不得不存在的?」。 本例的答案是「多副本 + 生产流量」。如果那个约束在你这里也成立 (本项目目标栈是 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 定稿又把其中两处从「将来要改」提前成了「第一版即如此」。 这不是设计时预料到的——全部动机是「投递被拒」与「多标签页画面分裂」——但结果是对的。