19 · 运行引擎架构 v3(设计草稿)
v3 是文档版本,不是软件版本。它描述的是一个完整的设计方案。§9 的「阶段」是方案内的实施顺序(先做什么、后做什么),不是软件发布阶段或开发阶段。
v3 的变化:v2 把「一次执行」拆成了四个职责单一的组件,但入口仍然是
POST /api/chat→ SSE 流,也就是**「输入」与「执行」是同一个动作**。 v3 把这两者解耦:POST 只负责投递,执行由调度器决定何时发生。这不是推翻 v2。 v2 的 Event、Subscription、RunLog(run 级)、 Archive、Approval、Checkpoint 全部原样继承,已并入本文 §4.1–4.4、§4.10–4.11。 v3 只重写三处:Engine 的生命周期入口(§4.8)、Transport 的路由与响应形态(§4.12)、 以及新增两个组件(Inbox §4.6、SessionLog §4.7)。执行链路(drive 的 stream 循环、 A/B 两路、compact 补偿事务)不动,见 §5.3–5.6。
v3 内部分两个阶段(§9):阶段一(第 1–13 步)只改入口与调度,数据面沿用 v2 的 Event 帧(Partial/sealed);阶段二(第 14–18 步)按 §11 的增量协议重写数据面 ——帧的含义从「发生了一件事」变成「某实体的某字段变成了这个值」,正文
op:"append"只推增量(O(n²) 重发 → O(n)),Partial/sealed 整套机制退役,崩溃窗口(§10 问题 7) 结构性消失。分阶段不改变「数据面重写量级独立」的判断(§11.5),改变的只是路线图位置: 它是 v3 的第二阶段,不是另一个版本。性质:设计草稿,未实施。重写,不是重构。 术语:message 指用户投递的一条输入;run 指一次执行;一场 run 可能消费多条 message。 诊断依据:见《会话级并发:从 409 到收件箱》访谈稿(含 Kimi 实测与代码位置对照表)。
1. 三真源(v2 是双真源)
v2 有两条真源。v3 在会话粒度上再加一条,另有一个暂存区:
run_log |
run_archive |
session_log |
inbox |
|
|---|---|---|---|---|
| 粒度 | run | run | 会话 | 会话 |
| 回答的问题 | 这场 run 发生过什么 | 下一轮该给模型看什么 | 这个会话发生过什么 | 还有哪些话没被回答 |
| 写规则 | 只追加,永不改 | 可改写(compact 破坏性覆盖) | 只追加,永不改 | 可变:行会被消费或删除 |
| 读者 | 人 / UI / 回放 / 对账 | LLM | UI / 多客户端同步 | 调度器 |
| seq 命名空间 | per-run | — | per-session | per-session(仅排序用) |
| 生命 | 永久 | 永久 | 永久 | 短暂:消费即删 |
为什么 inbox 与 session_log 是两张表而不是一张?
因为它们的写规则相反。session_log 是事实(只追加,回答「发生过什么」), inbox 是状态(可变,回答「现在还有什么没做」)。硬合成一张就得在事实表上 做 UPDATE(标记 consumed),破坏追加式纯净性;或者用「追加一条 consumed 事件、 读时做差集」,把简单查询变成折叠计算。分成两张,各自的语义都干净—— 这与 v2 §2 把 run_log 和 run_archive 分开的理由是同一个。
inbox 被消费后,「m1 曾排队过」这个事实不会丢:它在 session_log 里有 message_queued 帧,在 run_started 帧的 messageIds 里也有一份。 所以断线重连的客户端能完整重建时间线。
推论(继承 v2 并扩展):不能从 run_log 重建模型上下文(压缩是有意的信息销毁); 也不能从 session_log 重建 run 内容(它只记「发生了什么」,不记「产出了什么」)。 四份存储不是冗余,是四种不同的东西:run 级事实 / 当前模型视图 / 会话级事实 / 待办队列。
2. 不变量
v2 六条。v3 删 1 条、扩 2 条、增 3 条。
| # | 不变量 | v3 状态 |
|---|---|---|
| 1 | run 的命不属于任何连接。runCtx 是进程 ctx 的子 ctx;浏览器关掉、刷新、断网,run 照跑、帧照落库。只有 Stop 能取消它。 |
不变 |
| 2 | 库操作一律用进程 ctx,绝不用请求 ctx。 | 不变 |
| 3 | 先落库,再推浏览器。 | 扩展:也包括「先落库,再回 2xx」。用户打的字比输出帧更贵重——丢一帧输出可以从库补,丢一条用户输入无从恢复。 |
| 4 | seq 是唯一的续传坐标。 | 扩展:现在有两个独立的 seq 命名空间(run 级、会话级),各自续传,互不换算。 |
| 5 | 终局唯一。Finish 在一个事务里写终局帧 + 改 status,之后 Append 直接拒绝。 |
不变 |
删除。投递永不冲突(不变量 7),没有需要在写 header 前判完的状态;POST /api/message 也就用不着返回流了。注意因果方向:不是「因为不返回流所以不用判」,而是「因为没有冲突可判所以不必返回流」。返回流本身无罪(§11.4:外部产品的数据面就是流式 POST)。 |
||
| 7 | 投递永不因状态冲突失败。Enqueue 只可能因存储故障失败(500),绝不会因为「会话正忙」被拒。忙是调度器的内部事实,不是 API 层错误。 |
新增 |
| 8 | 放闸与调度必须原子。drive 收尾时,「置 live = nil」与「检查 inbox 是否非空」必须在同一个临界区里完成。 |
新增 |
| 9 | runID 只在事务提交后才对外可见。发布 runID 的那一帧(run_started)与 run 的档案行、start 帧在同一个事务里写入。 |
新增 |
不变量 8 为什么是硬要求:如果放闸和查收件箱之间有窗口,那么正好落在窗口里到达的 消息会永久搁浅——它入队时看到闸是 occupied(所以没触发调度),而收尾时查收件箱 又发生在它入队之前。除非下一条消息到来,它永远不会被执行。这是经典的 「signal lost between unlock and wait」竞态,只能靠原子性解决。伪代码见 §4.8。
不变量 9 消灭了 v2 遗留的一个窄竞态:v2 里 LiveRunID() 在占闸那刻就有值, 而档案行要等 BeginRun 才写;这个窗口内客户端拿到 runID 去订阅会吃 404 (诊断见《会话级并发》§2.1)。v3 里客户端只可能从 run_started 帧得知 runID, 而那一帧与档案行同事务提交,窗口不存在。
3. 组件关系
浏览器 / APP / IM / cron
│
│ ① POST /api/message ──────────▶ 投递(永远 2xx,JSON)
│ ② GET /api/session/stream ───▶ 会话级订阅(常驻长连接,只收通知)
│ ③ GET /api/chat/stream ──────▶ run 级订阅(收到 run_started 后才挂,收内容)
▼
┌──────────────────────────────────────────────┐
│ internal/webui/ (只剩 transport) │
│ ├─ server.go 装配 + 路由 │
│ ├─ middleware.go 中间件链 │
│ ├─ handler_msg.go 投递 / 撤回 │ ← 原 handler_run.go
│ ├─ handler_stream.go 两条 SSE │
│ ├─ dto.go 请求/响应 DTO │
│ └─ sse.go Stream() / StreamSession() │
└──────────────────┬───────────────────────────┘
│ 函数调用(webui → run,反向不依赖)
▼
┌──────────────────────────────────────────────────────────┐
│ internal/run/ │
│ │
│ Engine ──────┬── Inbox (新) 待办队列,可变状态 │
│ (生命周期) ├── SessionLog (新) 会话级事实真源 │
│ ├── RunLog (v2) run 级事实真源 │
│ │ ├─ sqlite/runlog.go │
│ │ └─ 内存 Subscription │
│ └── Archive (v2) 模型视图真源 │
│ ├─ sqlite/archive.go │
│ ├─ 内存模型消息缓存 │
│ └─ 实现 compact.Memory │
│ │
│ 调度器不是独立组件,是 Engine 的 trySchedule 私有方法 │
│ │
│ Event / StoredEvent / Subscription (v2 领域类型) │
│ SessionEvent / SessionSubscription (新领域类型) │
│ Approval (v2) │
└──────────────────┬───────────────────────────────────────┘
│ eino adk.Agent / adk.Runner(出站,不经 webui)
▼
LLM
谁持有谁(相对 v2 的增量用 ★ 标):
Server持有map[string]*Engine+ 共享的RunLog★ + 共享的SessionLogEngine持有自己的Archive★ + 自己的Inbox+RunLog/SessionLog引用 +agent/runnerInbox持有 SQLite 连接(或共享连接 + 独立事务域)- ★
SessionLog持有 SQLite 连接 + 每会话的内存事件缓冲(结构同runLog.runBuffer)
依赖方向:同 v2。webui → run → eino / compact。run 不依赖 webui、guard。
4. 组件详细设计
4.0 三级订阅:先说使用场景,再说结构
先说一个容易踩的语义陷阱。如果把投递接口(POST /api/message)的含义定义成「开一场 run」, 那么会话正忙时这个含义无法兑现,只能用状态码拒绝(409);而 POST 又要返回流、状态码只能提交一次, 于是 409 必须赶在写 header 之前判完——输入与执行就此绑死,「你输入的时机不对」被迫表达成一个 HTTP 错误:
POST 的含义是「开一场 run」
→ 会话正忙时这个含义无法兑现
→ 只能用状态码拒绝(409)
→ 而 POST 又返回流,状态码只能提交一次
→ 409 必须赶在写 header 前
→ 投递入口必须同步完成占闸 + 开跑
→ 输入与执行绑死
根因不在实现,在语义。 把 POST 的含义从「开 run」改成「投递」,整条约束链自然消失: 投递永不失败,没有冲突需要表达,409 这个概念不存在(不变量 7)。
罪不在「返回流」本身——外部产品的数据面恰恰就是流式 POST(§11.4)。有罪的是 流的寿命被绑死在一个 runID 上,以及 POST 的含义是「开 run」而非「投递」。 把这两点改掉,返回不返回流是自由选项。
由此得到一条贯穿本节的判断:
当有了一条常开的控制面通道,单次请求就不再需要承载状态语义。 「正忙」「已排队」「已开始」从「HTTP 状态码」降级成「流内状态」——客户端本来就在监听。
那么这条常开的控制面该推什么、推给谁?「为什么不止一条流」这个问题,答案不在架构里, 在谁需要知道什么里。先把场景摊开:
| # | 场景 | 谁需要知道 | 需要知道什么 | 这信息属于哪场 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 行再往上推一层:会话的增删本身也不是会话级事件,是账号级事件。
于是粒度天然是三级:
| 级别 | 订阅键 | 生命周期 | 推什么 | tako v3 | Kimi |
|---|---|---|---|---|---|
| 账号级 | userID | 与登录态同寿 | 会话列表增删改、跨会话通知 | 不做(单用户,会话列表在 localStorage) | WS topic |
| 会话级 | sessionID | 常驻,页面开着就在 | 投递、排队、撤回、run 开始/落幕 | GET /api/session/stream |
WS topic |
| run 级 | runID | 一场 run 的寿命 | 正文、工具调用、看板、审批 | GET /api/chat/stream |
流式 POST 的响应体 |
注意 Kimi 把账号级和会话级复用在同一条 WS 上(多路复用),tako v3 只做到会话级。 这不是偷懒:v3 的会话列表在前端 localStorage 里,没有服务端实体, 所以账号级订阅无源可订。要做它得先把会话提升成服务端资源(见 §10 问题 9)。
由此得出的两条物理连接(v3 的选择,代价见 §7.1):
① 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 个坑),这个缺陷只在多标签页下暴露, 而多标签页正是本次要修的场景。§11 记录 Kimi 的替代拓扑。
三个通道的技术差异,是拆分的后果,不是拆分的原因:
| 会话级 | run 级 | |
|---|---|---|
| Partial 帧 | 无(通知是一次性的,不存在「半个通知」) | 有,且需要预留号 + sealed 机制 |
| 游标 | per-session seq | per-run seq |
| 寿命 | 不自然结束,页面关才断 | 终局帧后自然结束 |
| 重连代价 | 补几帧通知,很轻 | 可能要重放整场 run |
打个比方:会话级通道是门磁推送(「有人进屋了」),run 级通道是摄像头画面(点开才看)。 你不会为了知道「有人进屋」而 24 小时开着摄像头,也不会指望门磁告诉你屋里人在干什么。
4.1 Event(run 级领域帧)
文件:
internal/run/event.go
描述「发生过什么」的一条记录。不带 seq(落库时由 RunLog 分配)、不带 JSON tag(序列化是 transport 的事)。
type EventKind string
const (
EventMessage EventKind = "message"
EventToolCall EventKind = "tool_call"
EventToolResult EventKind = "tool_result"
EventBoard EventKind = "board"
)
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 用)
Partial bool // 正文还在逐字流出,只进内存不落库
Drop bool // 模型流出失败,半截作废
Discard bool // 半截正文被最终结果取代,静默丢掉
}
// StoredEvent 是已被 RunLog 分配身份的帧。
// Event 描述「要写什么」,StoredEvent 描述「写下了什么」——
// 订阅(Subscription.Next)、写方法的返回值、DTO 转换只流转这个类型。
type StoredEvent struct {
Run string // 所属 run id
Seq int64 // 库内序号;Partial 帧是内存预留号(见 §4.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,Event 本身只是「要写什么」的输入。
纯函数 Classify(原 eventFrom):
// Classify 把 eino 的一条消息分类成领域事件。ok=false 表示没有可呈现内容。
// 纯函数,不读任何状态,不写任何状态。
func Classify(agentName string, mv *adk.MessageVariant, msg *schema.Message) (Event, bool)4.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 那条沿用同一预留号落库后推出,游标才走到这个号。不变量 4 不受影响—— 重连的读者(from ≥ 预留号)只会收到 sealed 的那一条,不丢不重。
sealed(定稿):流式正文逐字产出期间只有 Partial 帧(不落库);流结束那一刻, 把最终全文作为一帧经 AppendSealed 按预留号落库、原位替换内存里的 Partial 帧—— 这个动作叫 sealed。「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 那条——不变量 4 的另一面。
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
}
}
}4.3 RunLog(run 级事实真源)
文件:
internal/run/runlog.go(接口)+internal/run/sqlite/runlog.go(实现)
追加式存储。分配 seq,保证终局唯一。内存缓冲让 Subscription 能阻塞式推送。
type RunLog interface {
// ── 写(一律用进程 ctx)──
// Reconcile 把上次进程没写上终局的 run 标成 failed。启动时调一次。
Reconcile(ctx context.Context) 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 → 返回错误。
Append(ctx context.Context, runID string, ev Event) (StoredEvent, error)
// AppendSealed 把流式正文的最终全文按预留号落库。
// seq 必须正好是库内 max+1,否则返回错误——预留号只存在于内存,
// 若 seal 前被别的持久帧占了号(理论上只有并发写库能造成),
// 这里报错,由 drive 按 persistErr 走 error 终局。
AppendSealed(ctx context.Context, runID string, seq int64, ev Event) (StoredEvent, error)
// Finish 写终局帧 + 改 run_archive 状态,同一事务。
// kind 只接受 "complete" / "error" / "stop"。
// 只有 complete 写入 producedJSON;失败和停止不把产出放进模型历史。
// patch 非 nil 时在同一事务里改 user_message 和清空被换掉的行。
Finish(ctx context.Context, runID, kind, text string, producedJSON []byte, patch *ArchivePatch) (StoredEvent, error)
// RestoreMessage 把浏览器补发的一条正文写入库。保留(§10 问题 7 已决)。
// 兜的崩溃窗口:进程死在流结束与 AppendSealed 之间——Partial 不落库,
// 浏览器手里的全文是唯一副本。补发按原序号写回事件表并修复 produced_json,
// 下一轮模型档案才不缺这条正文。幂等:该序号已存在则 stored=false。
RestoreMessage(ctx context.Context, sessionID string, seq int64, ev Event) (bool, error)
// ── 读 ──
// Subscribe 返回阻塞式订阅。from=0 从头。
// run 不存在 → ErrRunNotFound。
// 内部判断 run 是否已结束:已结束则冷启动装库后流完即止。
Subscribe(runID string, from int64) (Subscription, error)
// HistoryPage 返回会话里已结束的 run(档案 + 事件),按 created_at 降序分页。
// cursor 格式 "<created_at>|<run_id>",空表示第一页。
// 不含 status='running' 的行——正在跑的 run 由 LiveRunID 报告。
// 归 RunLog 而非 Archive:响应里带事件帧,且 run_archive 的
// status/produced_json 本来就由 BeginRun/Finish 的事务写,是同一块地盘。
HistoryPage(ctx context.Context, sessionID, cursor string, limit int) (HistoryPage, error)
// HasEvent 报告事件表里是否已有这个序号。给 RestoreMessage 用。
HasEvent(ctx context.Context, runID string, seq int64) (bool, error)
// Close 关闭底层连接。
Close() error
}
// HistoryPage / HistoryRun 是历史分页 API 的响应形状(字段同现行 logdb.go)。
type HistoryRun struct {
RunID string
CreatedAt string
Status string
Events []StoredEvent
}
type HistoryPage struct {
Runs []HistoryRun
NextCursor string
}内部结构(实现细节,接口不暴露):
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——不变量 3):
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 } // 不变量 5:终局后拒绝追加
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
}4.4 Archive(模型视图真源)
文件:
internal/run/archive.go(接口)+internal/run/sqlite/archive.go(实现)
每会话一个。管理「下一轮该给模型看什么」。冷热缓存、compact 的改写目标。实现 compact.Memory。
// ArchivePatch 是成功收尾时和 produced_json 同一笔写入的档案修改。
type ArchivePatch struct {
UserMessage string // 非空时覆盖 run_archive 的 user_message(压缩后的摘要)
DropRunIDs []string // 这些行的 produced_json 清成 NULL
}
type Archive interface {
// ── 模型消息缓存 ──
// ModelMessages 返回下一轮要给模型的完整消息列表。
// 热路径直接返回缓存副本;冷路径从 run_archive 装入已完成 run 的产出。
// 调用方拿到的是副本,改不到缓存。
ModelMessages(ctx context.Context, sessionID string) ([]*schema.Message, error)
// AddRun 一轮成功收尾后,把这轮的产出接进缓存。
// userText 是这一轮的用户原话(或压缩后的摘要)。
// 还没装过库(冷路径没走过)则不动,下次 ModelMessages 再读库。
AddRun(produced []*schema.Message, userText string, runID string)
// InvalidateCache 丢掉已装入的缓存。补发改过 run_archive 时调,下次 ModelMessages 重读。
InvalidateCache()
// ── compact 快照(补偿模式)──
// Stage 暂存压缩改动。只改内存,不碰库。
// 第一次调留下快照(退回用);同一轮里再压,仍相对原始快照取舍。
// 失败时调 RevertStage 退回。
Stage(c compact.Commit) error
// RevertStage 退回这一轮第一次压缩前的快照。
RevertStage()
// CommitPatch 返回成功收尾时要写入库的补丁。没 Stage 过则 ok=false。
CommitPatch() (ArchivePatch, bool)
// ── compact.Memory 接口(供压缩 middleware 调用)──
SessionID() string
OriginalUser() string // 这一轮的用户原话(压缩前)
CurrentRunID() string // 正在进行的 run id
CompletedRunIDs() []string // 已完成的 run id 列表,顺序与缓存一致
// Notify 追加一条 kind 为 compact 的事件到 run_log,不改已写下的帧。
// text 为空则不做。run 不在 running 时只记日志。
Notify(text string)
// WriteRAG 把被换掉的原文追加进 compact_rag。
WriteRAG(runID, body string) error
// SearchRAG 按词重叠检索这一会话的 compact_rag 原文。
SearchRAG(query string) (string, error)
}内部结构(实现细节):
type archive struct {
mu sync.Mutex
sessionID string
runLog RunLog // Notify 写事件用
loaded bool // 冷路径是否走过
modelMsgs []*schema.Message // 缓存:下一轮给模型的完整列表
runs []runRecord // 按完成顺序,与 modelMsgs 对应
// 压缩快照
staged bool
snapMsgs []*schema.Message
snapRuns []runRecord
// 当前 run 的上下文(Engine.trySchedule 时注入,run 期间为常量)
liveUserText string // 用户原话
liveModelText string // 压缩后的摘要(空表示没压缩)
liveRunID string // 当前 run id
}
type runRecord struct {
RunID string
Msgs []*schema.Message
}Stage / CommitPatch / RevertStage 伪代码(难写点:这是一套「补偿式事务」—— 内存先改、库要等到收尾的 Finish 事务才写;中间任何一步失败都必须能干净退回, 否则模型视图和 run_archive 永久分叉,见 §5.6 补偿路径):
func (a *archive) Stage(c compact.Commit) error {
a.mu.Lock(); defer a.mu.Unlock()
if !a.staged { // 本轮第一次压缩:留快照,作为回退基准。
a.snapMsgs = copy(a.modelMsgs) // 同一轮再压,仍相对这份原始快照取舍
a.snapRuns = copy(a.runs)
a.staged = true
}
a.runs = filter(a.runs, r => c.KeptRunIDs.contains(r.RunID)) // 丢掉被换掉的轮
a.modelMsgs = rebuild(a.runs) // 按保留集重装消息列表
a.pendingDrop = append(a.pendingDrop, c.DroppedRunIDs...)
a.liveModelText = c.CombinedUser // 摘要接在本轮用户原话前的整句
return nil // 全程不碰库;被丢原文的去处是 Handler 调 WriteRAG 写 compact_rag
}
func (a *archive) CommitPatch() (ArchivePatch, bool) {
a.mu.Lock(); defer a.mu.Unlock()
if !a.staged { return ArchivePatch{}, false }
return ArchivePatch{UserMessage: a.liveModelText, DropRunIDs: a.pendingDrop}, true
// 调用方(drive)把它交给 Finish,与终局帧同一事务写 run_archive
}
func (a *archive) RevertStage() {
a.mu.Lock(); defer a.mu.Unlock()
if !a.staged { return } // 没 Stage 过,无事发生(幂等)
a.modelMsgs, a.runs = a.snapMsgs, a.snapRuns
a.staged = false
a.pendingDrop = nil
a.liveModelText = ""
}4.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(变成「新设备」)
Text string // queued 帧带全文,重连的客户端不用再查一次就能画出排队气泡
// run_started 用:
RunID string
MessageIDs []string // 这场 run 消费了哪些消息(合并窗口的结果,UI 据此表达「这两句被一起回答了」)
MergedText string // 合并后交给模型的那句
Resumed bool // true = 进程重启后由 Reconcile 重新调度的(§5.8)
// run_terminal 用:
TerminalKind string // "complete" / "error" / "stop"
}
// StoredSessionEvent 是已被 SessionLog 分配身份的帧。
type StoredSessionEvent struct {
Session string
Seq int64 // 会话级 seq,与 run 级 seq 是两个独立命名空间
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 级简单得多。
4.6 Inbox(收件箱)
文件:
internal/run/inbox.go(接口)+internal/run/sqlite/inbox.go(实现)
每会话一个。可变状态,行会被消费或删除。
// QueuedMessage 是收件箱里的一条待发消息。
type QueuedMessage struct {
ID string
Text string
Seq int64 // 会话级排序坐标,决定合并时的先后
}
type Inbox interface {
// Put 投递一条消息。messageID **由客户端生成**(§10 问题 12),
// 本会话内重复 → ErrMessageIDTaken(transport 回 409,正当的重复投递)。
// 除此之外只可能因存储故障失败——**没有「会话正忙」这种失败**(不变量 7)。
Put(ctx context.Context, sessionID, messageID, text string) error
// Drain 取空收件箱,返回按 seq 升序的全部待发消息。
// **必须在与 BeginRun 同一个事务里调用**(见 §4.8 trySchedule):
// 取空与开跑原子完成,才不会有消息在两步之间溜进来又被漏掉。
// 空收件箱 → 返回 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)
// Pending 返回当前待发消息,按 seq 升序。给 GET /api/session 的快照用。
Pending(ctx context.Context, sessionID string) ([]QueuedMessage, error)
// PendingCount 只返回条数。Enqueue 用它做队列深度上限检查(§10 问题 4),
// 不必为此拉出全部消息体。
PendingCount(ctx context.Context, sessionID string) (int, error)
}
// maxQueueDepth 是单个 run 期间可累积的排队上限。取值与理由见 §10 问题 4
// (参考 WeKnora steer.go:52-57 的 maxSteerQueueDepth = 10)。
const maxQueueDepth = 10建表:
CREATE TABLE inbox (
session_id TEXT NOT NULL,
message_id TEXT NOT NULL PRIMARY KEY,
text TEXT NOT NULL,
seq INTEGER NOT NULL, -- 会话级递增,与 session_log.seq 同源分配
created_at INTEGER NOT NULL
);
CREATE INDEX idx_inbox_session ON inbox(session_id, seq);seq 与 session_log.seq 同源分配(同一个会话级计数器),这样「消息 m1 入队」这件事 在两张表里用的是同一个坐标,客户端对齐时间线时不需要换算。
4.7 SessionLog(会话级事实真源)
文件:
internal/run/sessionlog.go(接口)+internal/run/sqlite/sessionlog.go(实现)
结构与 v2 的 RunLog 完全平行,只是粒度从 run 换成 session。
type SessionLog interface {
// Reconcile 启动时调一次。做两件事:
// 1. 把上次进程没写上终局的 run 标成 failed(同 v2 RunLog.Reconcile)
// 2. ★ 返回所有 inbox 非空的会话,交给 Server 逐个 trySchedule(§5.8)
Reconcile(ctx context.Context) (pendingSessions []string, err error)
// Append 追加一帧会话级事件。seq 由库分配。写成功后 bump 内存缓冲通知订阅者。
Append(ctx context.Context, sessionID string, ev SessionEvent) (StoredSessionEvent, error)
// Subscribe 返回阻塞式会话级订阅。from=0 从头。
// 会话不存在(库里没有任何帧)→ 返回一个空订阅,Next 阻塞等第一帧,不报错。
// 与 run 级的区别:**不会因为「已结束」而流完即止**——会话没有终局。
Subscribe(sessionID string, from int64) SessionSubscription
// AppendInTx 在调用方的事务里追加一帧,但不 bump。
// trySchedule 用它在同一事务里写 run_started(不变量 9),事务提交后再统一 bump。
AppendInTx(ctx context.Context, tx *sql.Tx, sessionID string, ev SessionEvent) (StoredSessionEvent, error)
// CloseSession 关掉这个会话的所有订阅并丢掉内存缓冲。Engine.Delete 用。
CloseSession(sessionID string)
Close() error
}存储与传输分离(重要):上面的 Subscribe 返回的是一个阻塞式迭代器, 它把「会话级事件增量怎么拿到」和「用哪种连接推给客户端」绑在了一起—— 一旦绑死,换成轮询或 WS 多路复用就得改接口。拆成两层:
// SessionFeed 是「拿到增量」的能力,与传输无关。SessionLog 实现它。
type SessionFeed interface {
// Since 非阻塞拉取 (from, from+limit] 的帧。轮询模式直接用这个。
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 + 逐帧写 |
v3 的默认。最简单,自动重连 |
| 轮询 JSON | Since(?since=) |
降级路径;或客户端不便持有长连接时 |
| WS 多路复用 | Notify + Since |
多会话/多标签页,受浏览器 6 连接上限约束时(§4.0) |
v3 先只做 SSE,但接口按可互换来设计——因为 §11 那条拓扑(一条 WS 承载所有会话) 是明确的演进方向,不该等到要做时才发现接口绑死了。
建表:
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,字段与 v2 的 runBuffer 同构 (events []StoredSessionEvent + gen uint64 + notify chan struct{}), 但不需要 Partial 分支,所以 Next 的伪代码比 §4.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
}
}
}4.8 Engine v3:Enqueue / Cancel / trySchedule / drive
文件:
internal/run/engine.go
type Engine struct {
// ── 不可变(构造时注入)──
ctx context.Context
sessionID string // ★ 新:Engine 每会话一个,自己知道身份。
// v2 的 Start(ctx, sessionID, text) 收 sessionID 参数,
// v3 的 Enqueue(ctx, messageID, expectedRunID, text) 不收——
// 投递方只给消息本身,会话身份由 transport 层选 Engine 时决定。
// (v2 里可从 archive.SessionID() 间接取,但那绕一层,
// 而且 Engine 用它的时机早于 Archive 构造完成)
runLog RunLog
sessionLog SessionLog // ★ 新
inbox Inbox // ★ 新
archive Archive
agent adk.Agent
runner *adk.Runner
// ── 可变(mu 保护)──
mu sync.Mutex
live *liveRun // 非 nil = 有 run 在跑。**不再是 409 的依据**——409 不存在了
pending map[string]chan string // 审批 id → 决策通道
}live 的一个新语义:trySchedule 会先放一个 id 为空的哨兵 &liveRun{} 占位(§4.8 伪代码),表示「正在开跑,但 runID 还没提交」。此时:
Stop(runID)匹配不上空 id → 返回 false(正确:还没有 run 可停)Snapshot().LiveRunID返回空字符串(正确:runID 只在事务提交后可见,不变量 9)
哨兵存在的意义是防止两个并发的 trySchedule 都判断闸空、都去开跑。
// liveRun 相对 v2 增加一个字段:
type liveRun struct {
id string
cancel context.CancelFunc
stopped bool
messageIDs []string // ★ 这场 run 消费的消息 id,收尾时写进 run_started 的对账
userText string // 合并后的整句(多条消息用 "\n\n" 连接)
modelUserText string // 压缩后的摘要(空 = 没压缩)
dropped []string
}导出方法:
// Enqueue 投递一条用户消息。这是 v2 Engine.Start 的替代品。
//
// 语义:**永远成功**(除非存储故障或队列已满)。不判断会话忙不忙,不开 run,不返回 runID。
// 同步完成两件事:
// 1. inbox.Put() —— 落库(不变量 3:先落库再回 2xx)
// 2. sessionLog.Append(message_queued) —— 落库 + 推给所有会话级订阅者
// 然后调 trySchedule():闸空就立刻开跑,闸忙就什么都不做(消息已在收件箱里等着)。
//
// 参数(依据见 §10 问题 12,参考 WeKnora steer.go:41-49):
// messageID —— **由客户端生成**。让前端能立刻用自己的 ID 画 pending 气泡,
// 帧到达时按同一 ID 对齐;也让「消费事件早于 HTTP 响应到达」成为可能。
// 本会话内重复 → 409(**正当的 409**:表达「你重复投递了」,
// 不是「你来得不是时候」,与不变量 7 不冲突)
// clientID —— ★ 投递方的设备标识(客户端生成 UUID,存 localStorage)。
// 多客户端场景下 UI 据此区分「谁发的」。同一设备换浏览器/清缓存 → 新 clientId
// expectedRunID —— 客户端**看到的那场 run**(fencing token,可为空)。
// 非空且与当前 live 不符 → 409 + 当前 liveRunID,
// 让客户端知道自己的视图过期了。比不变量 9 更强:
// 9 只保证「runID 提交后才可见」,这个还能检测「客户端停在旧视图」
// text —— 正文
func (e *Engine) Enqueue(ctx context.Context, messageID, clientID, expectedRunID, text string) error
// Cancel 撤回一条排队中的消息。已被 run 消费 → false(transport 回 404)。
func (e *Engine) Cancel(ctx context.Context, messageID string) (bool, error)
// Stop 取消一场正在跑的 run。幂等。run 不存在或不匹配 → false。
// **不清空收件箱**:停止的语义是「这一轮不对」,不是「我说的话不算」。
// 收尾时 trySchedule 会照常消费剩余消息(前端需明示,见 §4.13)。
func (e *Engine) Stop(runID string) bool
// Delete 销毁整个会话。级联:停 live run + 清收件箱 + 删四张表的会话行 + 广播。
// 幂等。这是 Kimi 实测暴露的行为(B 删会话 → A 的任务被停 → A 的列表同步删除)。
//
// **当前代码缺这个能力,而且缺得有后果**:index.html:1090-1104 的 startNewSession() 是
// const run = state.runID; if (run) { POST /api/stop }
// 而 state.runID 只在收到第一帧 SSE 时才被赋值(:1215),send() 开头还会清空它(:1139)。
// 于是从「按下发送」到「第一帧到达」之间它是空的——**这段窗口覆盖模型首 token 之前的
// 全部思考时间,通常好几秒**。此时按「新会话」,stop 根本不发,
// **旧 run 在后台跑到底**,帧继续写进一个用户以为已经不存在的会话。
// Delete 的语义必须是「以 sessionID 为键、无条件取消 live」,不能依赖客户端知道 runID。
//
// 顺序(每步都不可跳过):
// 1. 取消 live run 的 runCtx(不等它收尾——它会在 drive 里撞到已删除的行)
// 2. 清 inbox(否则 trySchedule 会把已删会话的消息捞起来开新 run)
// 3. 同一事务删 run_log / run_archive / session_log / inbox 的会话行
// 4. 关会话级订阅(SessionLog.CloseSession),让所有客户端的 ② 断开
// 5. Server 从 map[string]*Engine 摘掉这个 Engine
func (e *Engine) Delete(ctx context.Context) error
// Approve 把审批决策送进挂起的 ask。(同 v2,不改)
func (e *Engine) Approve(id, decision string) bool
// Snapshot 返回会话当前状态,给 GET /api/session 用。
// 是会话级流的「快照版」——客户端首屏用它对齐,之后靠流增量。
func (e *Engine) Snapshot(ctx context.Context) (SessionSnapshot, error)
type SessionSnapshot struct {
LiveRunID string
Queued []QueuedMessage
LastSeq int64 // 会话级流的当前 seq,客户端据此决定 from
}trySchedule —— v3 的核心,也是唯一的难写点:
// trySchedule 尝试开一场 run。可以从任意 goroutine 调,幂等。
//
// 难写点:三件事必须原子——「判断闸空」「取空收件箱」「开 run 并占闸」。
// 少任何一步的原子性都会漏消息或开两场 run(不变量 8)。
//
// 调用点有两个,缺一不可:
// - Enqueue 之后(消息到了,看看能不能立刻跑)
// - drive 收尾放闸之后(闸空了,看看有没有排队的)
func (e *Engine) trySchedule(ctx context.Context) {
e.mu.Lock()
if e.live != nil { // 闸忙:什么都不做。消息已在收件箱,收尾时会再来一次
e.mu.Unlock()
return
}
// 关键:**占闸与取空收件箱之间不留窗口**。
// 先乐观占一个哨兵,防止并发的另一个 trySchedule 也进来。
e.live = &liveRun{} // 哨兵:id 为空,表示「正在开跑」
e.mu.Unlock()
// 以下在一个 DB 事务里完成(不变量 9:runID 只在提交后可见)
runID, msgs, stored, err := e.beginRunAtomic(ctx)
// beginRunAtomic 内部:
// tx:
// msgs, ok := inbox.Drain(tx, sessionID) // 取空收件箱
// if !ok → 回滚,返回 ErrInboxEmpty
// merged := join(msgs, "\n\n")
// runLog.BeginRunInTx(tx, runID, sessionID, merged, agentName)
// // run_archive 行 + seq=1 start 帧
// // + message_ids 列(§4.9)
// 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) {
e.mu.Lock(); e.live = nil; e.mu.Unlock() // 收件箱空,放掉哨兵
return
}
if err != nil {
e.releaseSentinelAndReport(ctx, err)
// 开跑失败不是 HTTP 错误(没有 HTTP 请求在等)——
// 写一帧 message_queued 之外的会话级错误帧,或退回收件箱由下次重试。
// 决策见 §10 待定问题 2。
return
}
e.mu.Lock()
e.live = &liveRun{
id: runID, cancel: cancel, userText: merged, messageIDs: ids(msgs),
}
e.mu.Unlock()
messages, err := e.archive.ModelMessages(ctx, e.sessionID) // §4.4,冷热缓存
if err != nil { /* 走 error 终局,见下 */ }
messages = append(messages, schema.UserMessage(merged))
go e.drive(runCtx, runID, messages) // ← §5.3–5.6 的 drive,一字不改
}drive 的收尾变化(相对 v2 只多两步):
func (e *Engine) drive(runCtx context.Context, runID string, messages []*schema.Message) {
// ... §5.3–5.6 的 stream 循环、A/B 两路、审批挂起,全部不变 ...
// 收尾(§5.6 的三个问题不变),最后:
e.mu.Lock()
e.live = nil // 放闸
e.mu.Unlock()
e.sessionLog.Append(e.ctx, sessionID, SessionEvent{ // ★ 新:广播落幕
Kind: SessRunTerminal, RunID: runID, TerminalKind: kind,
})
e.trySchedule(e.ctx) // ★ 新:闸空了,看看收件箱
}注意 e.live = nil 与 trySchedule 之间没有窗口——trySchedule 自己会重新加锁判断, 而 Enqueue 那边如果正好在这个瞬间入队,它会:inbox.Put(落库)→ trySchedule → 看到闸空 → 开跑。 两边都调 trySchedule,谁先拿到锁谁开跑,另一个看到 live != nil 直接返回。 消息不会搁浅,因为它先落库再触发调度(不变量 3 + 8 的合力)。
Enqueue 伪代码:
func (e *Engine) Enqueue(ctx context.Context, messageID, clientID, expectedRunID, text string) error {
if n, _ := e.inbox.PendingCount(e.ctx, e.sessionID); n >= maxQueueDepth {
return ErrQueueFull // → transport 回 422 + 当前条数(§10 问题 4)
}
e.mu.Lock()
live := ""
if e.live != nil { live = e.live.id }
e.mu.Unlock()
if expectedRunID != "" && expectedRunID != live {
return &StaleViewError{LiveRunID: live} // → 409 + 当前 liveRunID(fencing,§10 问题 12)
}
err := e.inbox.Put(e.ctx, e.sessionID, messageID, text) // ① 落库(进程 ctx,不变量 2)
if errors.Is(err, ErrMessageIDTaken) { return err } // → 409,正当的重复投递
if err != nil { return err } // → 500。唯一的意外失败路径
_, err = e.sessionLog.Append(e.ctx, e.sessionID, SessionEvent{ // ② 落库 + 广播
Kind: SessMessageQueued, MessageID: messageID, ClientID: clientID, Text: text,
})
if err != nil {
// 消息已入收件箱但没广播出去。不回滚 inbox——
// 用户的字比一帧通知重要(不变量 3 的优先级排序)。
// 客户端下次 Snapshot / 重连时会从 Pending() 看到它。
log.Printf("会话级帧落库失败: %v", err)
}
e.trySchedule(e.ctx) // ③ 闸空就立刻开跑
return nil
}注意 messageID 现在由客户端给,Put 不再返回它——这是相对本文早期草稿的变化, 理由见 §10 问题 12。它带来一个好处:message_queued 帧的 ID 与前端 pending 气泡的 ID 天然是同一个,对齐不需要映射表。
4.9 run_archive 的变化:message_ids
v2 的 run_archive.user_message 是单条用户输入。v3 一场 run 可能消费多条,所以:
| 列 | v2 | v3 |
|---|---|---|
user_message |
用户那一句 | 合并后的整句(多条用 "\n\n" 连接)。compact 仍可破坏性改写它,语义不变 |
message_ids |
— | ★ 新增,JSON 数组,记录这场 run 消费了哪些 messageID |
message_ids 是给 UI 用的:前端据此把 N 个排队气泡归组到同一个回答下面, 表达「这两句被一起回答了」。模型侧不需要它——模型看到的是 user_message, 它本来就该是「用户连说了两句」的自然形态。
Archive.AddRun(produced, userText, runID) 的签名不变,userText 传合并后的整句 (或压缩后的 modelUserText)。Archive 完全不知道「多条消息」这件事的存在—— 合并发生在 Inbox 与 Engine 之间,Archive 看到的永远是一句 user 输入。 这是把复杂度挡在正确边界外的结果。
4.10 Approval(领域类型)
文件:
internal/run/approval.go
把 guard.ApprovalInfo 挡在引擎外面。引擎只知道 Approval,不知道 guard。
type Approval struct {
Tool string // 请求审批的工具名
Args string // 工具参数
Message string // 兜底文案(info 类型对不上时用)
}transport 层的 middleware 或 handler 负责把 guard.ApprovalInfo 转成 Approval。
4.11 Checkpoint(内存 checkpoint)
文件:
internal/run/checkpoint.go
实现 adk.CheckPointStore。每会话一份,进程内存,重启即丢。 和现在的 adkrun.Store 完全一样,只是搬家。
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) error4.12 Transport v3
路由表(★ = 相对 v2 的变化):
| 路由 | handler | 做什么 |
|---|---|---|
GET / |
handleIndex | 返回静态页面 |
★ POST /api/message |
handleMessage | engine.Enqueue() → 202,无响应体;队列超上限 → 422(§10 问题 4、用例 10)。不返回流(messageId 由客户端生成,不需要回传) |
★ DELETE /api/message/:id |
handleCancel | engine.Cancel() → 204 / 404 |
★ DELETE /api/session/:id |
handleDelete | engine.Delete() → 204。级联停 run + 清四张表 + 断开该会话所有订阅(§4.8) |
GET /api/session |
handleSession | engine.Snapshot() → liveRunID + queued + lastSeq |
★ GET /api/session/stream |
handleSessionStream | sessionLog.Subscribe() → 会话级 SSE(常驻) |
GET /api/chat/stream |
handleStream | runLog.Subscribe() → run 级 SSE(语义不变) |
GET /api/session/history |
handleHistory | runLog.HistoryPage() |
POST /api/approval |
handleApproval | engine.Approve() |
POST /api/stop |
handleStop | engine.Stop() |
POST /api/chat/restore |
handleRestore | runLog.RestoreMessage()(崩溃补发)——★ 建议删除,见 §10 问题 16 |
POST /api/chat |
— | ★ 删除。语义被 /api/message + /api/session/stream 取代 |
每个 handler 依然 ≤ 15 行(v2 §5.8 的绊线保留)。而且新的 handleMessage 比旧的 handleChat 短得多——它不再有「写 header 之前必须判完所有冲突」的压力:
func (s *Server) handleMessage(c *gin.Context) {
var req messageRequest
if err := c.ShouldBindJSON(&req); err != nil { c.Error(err); return }
engine, err := s.engineFor(req.SessionID)
if err != nil { c.Error(err); return }
if err := engine.Enqueue(s.ctx, req.MessageID, req.ClientID, req.ExpectedRunID, req.Text); err != nil {
c.Error(err); return
}
c.Status(http.StatusAccepted)
}六行。没有一个状态码是「因为你来得不是时候」——这正是解耦的兑现。 Enqueue 仍会返回 409,但那两种 409 表达的是「你重复投递了」和「你的视图过期了」, 都是客户端自己的错误,不是时机问题(§10 问题 12)。
DTO 增量:
type messageRequest struct {
SessionID string `json:"sessionId" binding:"required"`
MessageID string `json:"messageId" binding:"required"` // 客户端生成(§10 问题 12)
ClientID string `json:"clientId" binding:"required"` // ★ 设备标识(客户端生成 UUID,存 localStorage)
ExpectedRunID string `json:"expectedRunId"` // fencing token,可空
Text string `json:"text" binding:"required"`
}
// 无响应体:202 Accepted 就够。messageId 是客户端自己给的,不需要回传。
// 排队状态由会话级流的 message_queued 帧报告——与 §10 问题 6 删掉 Queued 字段的结论一致。
// 会话级 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 写出:sse.go 增加一个 StreamSession,结构与 v2 的 Stream 相同, 唯一区别是没有 if se.Kind.IsTerminal() { return }——会话级流不自然结束。
4.13 前端:两层订阅的编排
这是 v3 对客户端最大的改动,也是最容易写错的地方。
页面加载
│
├─ ① GET /api/session?id= → Snapshot{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 对应的气泡标记为「已被回答」
│ on run_terminal → run 级流自己会结束;这里只更新状态文案
│
└─ ③ run 级流(可能同时有多条?不——闸保证每会话最多一场 run)
关键性质:
- 发送按钮永远可用。
state.busy这个概念删掉。用户随时能投递,投递永远成功。 这解决了当前实现里「run 期间发送键被停止键替换、连排队的入口都没有」的问题 (index.html:967-971)。 - 多标签页 / 多设备自动同步。每个客户端都开着会话级流,任何一端投递, 所有端立刻收到
message_queued。《会话级并发》§2.1 的 t3–t5「A 看不到 B」整行消失。 - 409 处理逻辑删除。不存在这个状态码了,
attachLive()那套「只在加载时调一次」的 补丁也不需要了——会话级流就是活的 attachLive。
撤回的语义边界要在 UI 上表达清楚:只有 message_queued 且尚未出现在任何 run_started.messageIds 里的气泡能撤回。一旦被消费,撤回按钮消失 (服务端 Cancel 会返回 404,但前端不该让用户点到)。
停止后的排队提示:Stop 不清收件箱(§4.8),所以按下停止后如果还有排队消息, 它们会立刻开跑。前端必须在停止按钮旁边明示「还有 N 条排队,会继续」并提供一键清空, 否则用户会觉得「我明明停了它怎么又跑了」。
删掉 state.localEcho:当前实现在 send() 里先 appendUser(text) 画一个本地气泡, 再等服务端确认。v3 下这会变成画面分裂的来源——A 本地画的气泡,B 要等会话级流推来才画, 两端时序不同,撤回时更容易对不上。改成服务端回显:send() 只 POST, 气泡由 message_queued 帧画出(帧里带 text 全文,正是为此)。 POST 失败就把输入框内容还回去。代价是本地回显的那点即时感没了(多一个 RTT), 换来的是所有客户端画的用户消息来自同一个 seq 序列——同步是免费的。
一条消息气泡的状态机(前端只需实现这一个,所有转移都由流帧驱动):
POST /api/message
│
┌──────────────────┴───────────────────┐
│ 失败 │ 成功
▼ ▼
[输入框内容还回] ┌───────────────┐
│ 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 已到。 前端不保存任何服务端不知道的状态——刷新后靠 Snapshot + 会话级流冷启动重建, 不需要 localStorage 兜底。
4.14 前端删除清单
| 现在(index.html) | v3 |
|---|---|
state.busy + setBusy()(:967-973) |
删。发送键永在,停止键按 liveRunID 显隐 |
state.localEcho + appendUser 本地回显 |
删。改服务端回显(见上) |
409 分支 appendError 后 return(:1152-1156) |
删。没有这个状态码了 |
attachLive() 只在加载时调一次(:1308-1312) |
删。会话级流就是活的 attachLive |
startNewSession() 只 POST /api/stop(:1090-1129) |
改调 DELETE /api/session/:id(§4.8 Delete),修掉旧 run 后台续跑的漏洞 |
滚到顶 loadHistory() 只朝更早翻(:1017-1021) |
保留。新 run 由流推来,不再需要它兜底 |
5. 完整链路:八幕
v2 是五幕,主角是 drive。v3 是八幕,主角前移——第一幕的主角是投递请求, 第二幕是调度器,drive 从第三幕才出生。
示例数据(贯穿六幕,每幕末尾只列增量):
- 会话
s_1已有两个完成的 run:r_15、r_16; - 用户发「读一下 doc/19」→
m_1→ 立刻开跑r_17; r_17跑工具期间(耗时长),用户又发「顺便看看 v1」→m_2,再发「对比一下差异」→m_3,两条都排队;r_17落幕,调度器合并m_2 + m_3开出r_18;r_18期间上下文超阈值,压缩换掉r_15。
5.1 第一幕:投递
用户按下发送,POST /api/message 到达 handler。这里没有任何冲突判断—— handler 只问一个问题:存储写进去了吗?
POST /api/message {sessionId:"s_1", messageId:"m_1", clientId:"A-desktop", text:"读一下 doc/19"} handler 6 行 → 202
│
├─ engine.Enqueue(ctx, "m_1", "", text)
│ ├─ ⓪ 队列深度检查 + expectedRunID fencing(§10 问题 4 / 12)
│ ├─ ① inbox.Put() → m_1 落库。**用户的字从此不会丢**(不变量 3)
│ ├─ ② sessionLog.Append(message_queued)
│ │ → 落库 + bump → 所有会话级订阅者立刻收到
│ │ → 另一个标签页 / APP 上立刻出现这条消息的排队气泡
│ └─ ③ trySchedule()
│ ├─ e.live == nil → 闸空,占哨兵
│ ├─ beginRunAtomic:一个事务里
│ │ inbox.Drain → [m_1]
│ │ runLog.BeginRunInTx → r_17 档案行 + seq=1 start 帧
│ │ sessionLog.AppendInTx(run_started{r_17, [m_1]})
│ │ commit → bump 两个缓冲
│ ├─ archive.ModelMessages() + 用户这句
│ └─ go drive(runCtx, r_17, messages)
│
└─ 200 {messageId:"m_1", queued:true} ← JSON,不是流
客户端此时已经通过会话级流收到了 message_queued(m_1) 和 run_started(r_17, [m_1]), 后者触发它去挂 GET /api/chat/stream?run=r_17&from=0。POST 的 200 响应只是确认, 不承载任何内容。
数据变化:
inbox + m_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"}
run_archive +行: r_17 | s_1 | user_message:"读一下 doc/19" | message_ids:["m_1"]
| status:"running" | produced_json:NULL | is_completed:0
事件表 + r_17 seq=1 {kind:"start", text:"读一下 doc/19"}
Archive 内存 只读:ModelMessages() 返回 [r_15…, r_16…, user:"读一下 doc/19"]
Engine live: nil→{id:"r_17", messageIDs:["m_1"], …}
5.2 第二幕:排队(v3 独有)
r_17 在跑工具,耗时几十秒。用户等不及,又打了两句。
当前实现(v2 及之前):发送键被停止键替换,send() 首行 state.busy 直接 return。 用户打的字无处可去。
v3:两次 POST 都成功,两条消息躺在收件箱里。
POST /api/message {text:"顺便看看 v1"}
├─ inbox.Put → m_2 落库
├─ sessionLog.Append(message_queued) → 所有客户端画出 m_2 的排队气泡
└─ trySchedule → e.live != nil(r_17 在跑)→ **直接返回,什么都不做**
POST /api/message {text:"对比一下差异"}
└─ 同上 → m_3 排队
注意 trySchedule 的早退不是丢弃——消息已经在 inbox 里落库了, r_17 收尾时会再调一次 trySchedule(第六幕)。这就是不变量 8 要保的事。
数据变化:
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", "对比一下差异"}
run_archive 不变:r_17 仍 running
事件表 r_17 继续追加它自己的帧(seq 2,3,4…)
Archive 内存 不变
Engine live 不变,仍是 r_17
所有客户端此刻看到的画面完全一致:一条正在跑的回答 + 两个排队气泡(可撤回)。
5.3 第三幕:模型开口,一句话变成两件事
drive 把第一幕取好的 messages 交给 eino Runner,模型开始吐字。 吐出的每条 *schema.Message 在 drive 的 stream 循环里一变二:
- A 路(给模型的):只有 root agent 的消息被攒进一个 list,一轮结束时整体序列化成
produced_json——下一轮 Archive 的原料(第六幕用)。子代理的消息不进档案。 - B 路(给人的):
Classify把它翻译成领域 Event(§4.1),经emit写进 RunLog。 这是外界观察这轮 run 的唯一出口。
进图前先认识两个词:
- emit:drive 里「写一帧进库」的闭包。写失败会记下
persistErr并取消整轮 run—— 帧写不进库就不许推给读者(不变量 3:先落库,再推浏览器); - sealed(定稿):流式正文先以 Partial 帧在内存里反复更新(不碰库), 流结束时才把最终全文一次落库(定义和逐帧例子见 §4.2,伪代码见 §4.3)。 这是阶段一机制;阶段二的增量协议下「哪一帧才算数」这个问题不成立, sealed 连同整套 Partial 机制一起消失(§11.3)。
模型吐 *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 时才落库(§4.2)
+ r_17 seq=3 {kind:"tool_call", tool_calls:[{name:"read_file", args:"{\"path\":\"doc/19-…-v3.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 内存 不变:本轮第一次调模型未超阈值,压缩没触发
读者从哪来?第一幕的 handler 是第一个,但 run 不要求有读者:刷新页面走 GET /api/chat/stream?from=N 续传、第二个标签页、将来的 IM/cron(#8b)和 MQ(#8c) 都只是又一个 Subscribe。一个读者都没有时,run 照跑、帧照落库(不变量 1:run 的命 不属于任何连接)。所以 B 路的终点是 RunLog 而不是 SSE——执行与观察彻底解耦, 新读者类型接入时一行引擎代码都不用改。
5.4 第四幕:中途停顿,等人拍板
模型要调一个需要审批的工具,eino 把 run 中断。drive 里构造的 ask 闭包接住中断,做五件事:
- 生成审批 id;
emit一帧 approval——读者立刻看到审批卡片(走的就是第三幕的 B 路);- 挂起:阻塞在一个 channel 上,什么都不干;
- 决策从
POST /api/approval进来,Engine.Approve把它塞进 channel (与 Stop/断连的竞态处理和伪代码见 §4.8); emit一帧 approval_result,把 decision 交还 runner,run 从原地继续(回到第三幕)。
要点:挂起的只是 drive 这个 goroutine——闸没放(本会话开不了第二轮)、 SSE 没断(读者先看到卡片、再看到后续)。若用户等不及按了 Stop,runCtx 取消, ask 从 Done 分支醒来、清掉挂起表,run 直接进入第六幕的「停止」结局。
v3 的交互改善:审批挂起期间闸不放,所以此时投递的消息一律排队。 这在 v2 里是「用户困惑为什么打不了字」,在 v3 里变成「用户看到排队气泡, 知道系统在等自己拍板,顺便把下一句先说了」。同一个机制,体验完全不同。
数据变化(模型接着要调 bash,命中审批;用户点了允许):
run_log + r_17 seq=5 {kind:"approval", tool:"bash", args:"…"} ← ask 第 2 步,读者看到审批卡片
(drive 挂起在 channel 上,期间三处存储零变化)
+ r_17 seq=6 {kind:"approval_result", text:"allow"} ← POST /api/approval 送达后
+ 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 内存 不变
5.5 第五幕:压缩在暗处进行
compact 不是独立的一幕,它藏在第一、三幕的 middleware 链里:每次要调模型前, 如果上下文超了阈值,它就地改写发给模型的消息,并调 archive.Stage() 把 「丢了哪些轮、摘要是什么」记进内存(§4.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 被换掉…"} ← Notify 只追加,不改任何旧帧(§1)
compact_rag + r_15 被换掉的原文(WriteRAG,从此只以可检索形式存在)
run_archive 不变——这正是本幕的全部要点:r_15 的 produced_json 原封不动,压缩只活在内存
5.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 永久分叉。
问题三:这一轮的产出怎么接进下一轮? complete 且落库成功后 archive.AddRun(produced, userText, runID)——第三幕 A 路攒的 list 进缓存, 成为下一轮第一幕的档案原料。最后放闸:e.live = nil,会话可以接下一条消息了。
v3 的增量:放闸后多做两步——广播落幕 + 再调度。
drive 收尾
│
├─ kind := terminalOf(persistErr, err, produced, stopped) // 判断顺序见上表
├─ Finish(+ CommitPatch) 同一事务 // §4.3 不变
├─ 成功且 complete → archive.AddRun(produced, userText, r_17) // §4.4 不变
│
├─ 放闸:e.live = nil
│
├─ ★ sessionLog.Append(run_terminal{r_17, "complete"})
│ → 所有客户端更新状态文案
│
└─ ★ trySchedule(ctx)
├─ e.live == nil → 闸空,占哨兵
├─ beginRunAtomic:一个事务里
│ inbox.Drain → [m_2, m_3] ← **合并窗口的兑现点**
│ merged = "顺便看看 v1\n\n对比一下差异"
│ runLog.BeginRunInTx → r_18 档案行 + start 帧
│ user_message: merged
│ message_ids: ["m_2","m_3"]
│ sessionLog.AppendInTx(run_started{r_18, [m_2,m_3], merged})
│ commit → bump
└─ go drive(runCtx, r_18, [...历史, user:merged])
合并的结果:模型看到的是一句 user 输入「顺便看看 v1\n\n对比一下差异」, 一次回答覆盖两句。而不是跑两场 run、第一场的回答看不到第二句。
客户端收到 run_started{r_18, messageIds:[m_2,m_3]},把 m_2、m_3 两个气泡 归组标记为「已被 r_18 回答」,然后挂 GET /api/chat/stream?run=r_18&from=0。
数据变化:
事件表 + r_17 seq=10 {kind:"complete"} ← 终局帧(v2 不变)
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}
Archive 内存 AddRun(r_17 产出);随后为 r_18 调 ModelMessages()
Engine live: r_17→nil→{id:"r_18", messageIDs:["m_2","m_3"]}
5.7 四处存储的终态对照
| 存储 | r_18 开跑后的内容 | 谁写的 |
|---|---|---|
| 事件表(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 |
| inbox(待办队列) | 空 | Put / Drain / Cancel |
| compact_rag | r_15 被换掉的原文(第六幕压缩发生后) | WriteRAG |
session_log 是这个会话的完整编年史,六帧讲清了「谁在什么时候说了什么、 系统什么时候开始回答、哪些话被合并回答了」。这份时间线在 v2 里根本不存在—— v2 只能从 run_log 里各个 run 的 start 帧反推,而排队消息因为从未成为 run, 在 v2 的存储里没有任何痕迹。
5.8 进程重启
Reconcile 在 v2 只做一件事(把遗留 running 标 failed)。v3 多做一件:
启动
├─ sessionLog.Reconcile(ctx)
│ ├─ 遗留 running 的 run → 标 failed(同 v2)
│ └─ ★ 返回所有 inbox 非空的 sessionID
│
└─ 对每个 pendingSession:engine.trySchedule(ctx)
→ 重启前排队的消息**继续被回答**,不静默丢弃
→ run_started 帧带 Resumed:true,UI 明示「这条是重启前排队的」
为什么自动继续而不是等用户确认:不变量 3 说用户的字比输出帧贵重。 既然它已经落库了,进程重启就不是丢弃它的理由——这与不变量 1 「run 的命不属于任何连接」是同一个精神:执行的生命周期独立于任何偶然事件。
5.9 业务用例链路:从用户视角看路由怎么串
§5.1–5.8 是技术链路(八幕),每幕末尾的「数据变化」列的是存储增量。 本节从用户操作出发,看路由、SSE 流、UI 状态怎么配合,每个用例给出线上真实字节。
样例约定(下面所有 JSON 都按这个写,字段来源可查):
- 两条流都是
data: <JSON>\n\n,不带 event 名(sse.go:74)。 下文说「会话级 SSE 推」=GET /api/session/stream?id=&from=(handleSessionStream, 背后sessionLog.Subscribe(),§4.7)——页面加载时挂一次、常驻不断开, 一个会话一条;说「run 级 SSE 推」=GET /api/chat/stream?run=&from=(handleStream, 背后runLog.Subscribe())——收到run_started才新挂,一个 run 一条、见终局帧即关。 两者的生命周期不同,这是 §4.0 三级订阅的核心。 - run 级帧 =
sseEvent(sse.go:33-46),身份字段run+seq; 会话级帧 =sessionFrame(§4.12),身份字段只有seq,指向 run 用runId。 两套 seq 是独立命名空间(§4.5)——看到seq:2得先问「哪条流」。 - 帧字段全是
omitempty,每类帧只带自己用得上的那几个(§4.12)。 ts是 RFC3339 UTC 秒(logdb.go:700),样例里缩写成T0、T1… 省宽度;…表示省略与前一行相同的run/ts/agent字段,不是合法 JSON。- 会话
s_1,客户端clientId:"A-desktop",沿用 §5 的示例数据(r_17 / m_1 / m_2)。 - seq 只在本用例内自洽:用例 1→2 是一条连续时间线(seq 接着长), 用例 3–6 各自从自己的前置状态起算,不要跨用例对齐数字。
- 适用范围:单副本。以下帧序列在多副本下不全部成立——审批的
pending map是 Go channel、不跨进程,闸是进程内 mutex(§12.5)。多副本要改的三处见 §12.5, 改完后本节用例的帧形状不变,变的是它们由谁写、由谁推。
用例索引(1–6 是主干,7–14 是打断路径与边界):
| # | 场景 | 主要涉及的路由 / 机制 |
|---|---|---|
| 1 | 首次发消息,无并发 | POST /api/message、两条流的挂载时机 |
| 2 | 已有 run 在跑时发消息 | 撞闸早退、合并窗口、两种 409 |
| 3 | 刷新页面 | GET /api/session、两条流续传起点不对称 |
| 4 | 撤回排队消息 | DELETE /api/message/:id、乐观更新与 404 |
| 5 | 多标签页同步 | 同一行 session_log 推给两条连接、clientId 的边界 |
| 6 | 进程重启 | Reconcile、resumed:true、failed run 无终局帧(§10 问题 14) |
| 7 | 审批挂起期间排队 | POST /api/approval、闸没放但收件箱能收 |
| 8 | 停止 | POST /api/stop、停止不清收件箱 → 排队消息立刻开跑 |
| 9 | 新会话(删会话) | DELETE /api/session/:id、§6 第四行那个 bug 的验证 |
| 10 | 队列上限 | 422 + 当前排队条数(§10 问题 4) |
| 11 | 滚到顶翻历史 | GET /api/session/history 与流帧的接缝 |
| 12 | SSE 单独断线重连 | from=seq 续传(≠ 用例 3 的整页刷新) |
| 13 | run 中途压缩 | kind:"compact" 帧、压缩换掉旧 run 后历史读到什么 |
| 14 | inject 插话(后置能力) | delivery:"inject",§10 问题 11 / 实施第 12 步 |
用例 1:首次发消息,无并发
用户动作:打开页面,输入「读一下 doc/19」,按回车
时序:
① GET /api/session?id=s_1 → Snapshot{liveRunID:"", queued:[], lastSeq:0}
随即挂上会话级流 GET /api/session/stream?id=s_1&from=0(★ 常驻,页面活着就一直开)
UI:空页面,无排队气泡,无 run 流
② POST /api/message {messageId:"m_1", text:"读一下 doc/19"} → 202
UI:立刻画 pending 气泡(用客户端生成的 m_1,不等服务端回显)
③ 会话级 SSE 推(就是 ① 挂的那条 /api/session/stream,不是新请求):
message_queued(m_1, clientId:"A-desktop", text:"读一下 doc/19")
UI:pending 气泡变成 queued 气泡(带撤回按钮)
④ 会话级 SSE 推:run_started(r_17, messageIds:[m_1])
UI:**新挂一条** run 级 SSE(GET /api/chat/stream?run=r_17&from=0,见终局帧即关)
queued 气泡变成 consumed 状态(等回复)
⑤ run 级 SSE 推:message(role:"assistant", text:"好", partial:true) → text:"好的,我来…" → …
UI:助手气泡逐字更新(阶段一是快照全文,阶段二改成增量 append)
⑥ run 级 SSE 推:终局帧 kind:"complete"
UI:助手气泡定稿,consumed → answered(与助手回复配成一对)
会话级 SSE 推:run_terminal(r_17, terminalKind:"complete") → 所有客户端同步
数据样例:
→ 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(无响应体,§4.12)
会话级流 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 机制,阶段二整体退役,§11.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" 收尾并关闭(server.go:440), 会话级流另推一帧 run_terminal 让没挂 run 级流的客户端也知道落幕了。二者不可互替。
用例 2:发消息时已有 run 在跑
用户动作:r_17 正在跑,用户又发「顺便看看 v1」
时序:
① POST /api/message {messageId:"m_2", text:"顺便看看 v1"} → 202
UI:画 pending 气泡(m_2)
② 会话级 SSE 推:message_queued(m_2)
UI:m_2 变成 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 级 SSE
④ 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
会话级流
data: {"seq":4,"ts":"T3","kind":"message_queued","messageId":"m_2","clientId":"A-desktop","text":"顺便看看 v1"}
↑ 后面没有 run_started——trySchedule 撞闸早退(§5.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"}
…
若合并窗口里排了两条(§5.2 的 m_2 + m_3),run_started 长这样—— messageIds 是 UI 表达「这两句被一起回答了」的唯一依据(§7.2 第 3 条):
data: {"seq":6,"ts":"T9","kind":"run_started","runId":"r_18","messageIds":["m_2","m_3"],
"mergedText":"顺便看看 v1\n\n对比一下差异"}
v3 只剩两种 409,都是客户端自己的错,不是时机问题(§4.12):
① expectedRunId 对不上(前端以为还是 r_16,其实 r_17 已开跑)
→ {"sessionId":"s_1","messageId":"m_9","clientId":"A-desktop","expectedRunId":"r_16","text":"…"}
← 409 {"error":"视图过期","liveRunId":"r_17"} (StaleViewError,§4.8)
② messageId 重复(重试/双击撞车)
→ {"sessionId":"s_1","messageId":"m_2",…}
← 409 {"error":"messageId 已用过"} (ErrMessageIDTaken,§4.6)
错误体的字段名 §4.12 未定义(现实现是 http.Error 纯文本,server.go:133), 随 §10 问题 12 一起收口。
用例 3:刷新页面,run 正在跑
用户动作:r_17 跑到一半,用户刷新页面
时序:
① GET /api/session → Snapshot{liveRunID:"r_17", queued:[m_2], lastSeq:3}
UI:立刻画 r_17 的 run 级 SSE(from=0,追赶已推的帧)
画 m_2 的 queued 气泡(从 Snapshot.Queued 取)
② run 级 SSE 推:从 seq=0 开始重放已推的帧 → 实时帧
UI:助手气泡从开头开始渲染,追上实时
③ 会话级 SSE 推:从 lastSeq=3 开始(from=3)→ 新帧
UI:后续 message_queued / run_terminal 正常推
**关键点**:刷新后 UI 立刻恢复,不丢状态,不等待。
数据样例(承接 §5 的编年史: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","text":"顺便看看 v1","seq":3}],
"lastSeq":3}
(SessionSnapshot §4.8 / QueuedMessage §4.6 都没写 json tag,
此处按全篇 camelCase 约定给出——实施第 9 步落 DTO 时要补进 §4.12)
→ 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-运行引擎架构-v3.md\"}"}]}
data: {"run":"r_17","seq":4,"ts":"T4","kind":"tool_result",…,"role":"tool","toolName":"read_file","text":"<文件原文 41KB>"}
(此后是实时帧。前端分不出「重放」与「实时」——同一条流、同一套 seq、同一种帧)
两条流的续传起点不对称,这是设计而不是巧合: run 级流从 0 开始(这个客户端一份都没看过),会话级流从 lastSeq 开始 (它只是补齐断开期间漏掉的几帧)。所以 Snapshot.LastSeq 必须和 queued 同源读取, 否则会出现「快照说有 m_2,流又从 seq=2 重放一遍 m_2」的重复气泡。 前端按 messageId 幂等对齐可以兜住,但不该依赖它。
用例 4:撤回排队消息
用户动作:m_2 在排队(等 r_17),用户点撤回
时序:
① DELETE /api/message/m_2 → 204
UI:m_2 的 queued 气泡立刻消失
② 会话级 SSE 推:message_cancelled(m_2)
UI:所有客户端同步(多标签页场景下,另一个标签页也看到气泡消失)
**语义边界**:只有 queued 状态能撤回。consumed(已被 run 消费)或 answered(已完成)不能撤回。
数据样例:
→ DELETE /api/message/m_2
← 204(无响应体,§4.12 路由表:204 / 404)
会话级流(所有客户端都收到)
data: {"seq":4,"ts":"T5","kind":"message_cancelled","messageId":"m_2"}
↑ 只带 messageId:撤回不需要重述全文,气泡早就画在那了
已被消费的:
→ DELETE /api/message/m_1 (m_1 已在 r_17 的 messageIds 里,inbox 里没这行)
← 404
乐观更新与 404 的关系:前端点撤回时先本地摘掉气泡,再发 DELETE。 若回来 404(那条刚好被 trySchedule 抢走消费了,就是上面 m_1 那种情况), 本地状态与事实不符——纠正方式不是回滚那一次点击,而是等 run_started 帧到达, 它的 messageIds 含这条 messageId,前端据 §4.13 的状态机把气泡从 queued 直接推到 consumed。 流是唯一事实源,HTTP 响应只是操作回执,这条竞态因此不需要额外处理。
用例 5:多标签页同步
用户动作:开两个标签页(tab A, tab B),在 tab A 发消息
时序:
① tab A:POST /api/message → 202
② tab A 和 tab B 的会话级 SSE 都推:message_queued(m_1)
UI:两个标签页同时画出 m_1 的 queued 气泡
③ tab A 和 tab B 都收到 run_started(r_17, [m_1])
UI:两个标签页同时挂 r_17 的 run 级 SSE,看到同样的回复流
**关键点**:《会话级并发》§2.1 的 t3–t5「A 看不到 B」整行消失。
两个标签页通过会话级 SSE 共享同一个事实源(session_log),状态天然一致。
数据样例(两条会话级流各自独立连接,但读的是同一行 session_log):
tab A → POST /api/message {"sessionId":"s_1","messageId":"m_1","clientId":"A-desktop","text":"读一下 doc/19"}
← 202
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,此后看到同样的回复流
这里暴露一个 clientId 的边界:clientId 存 localStorage(§4.5、§4.12), 同一浏览器的两个标签页读到的是同一个值。所以「谁发的」这个标记只在 跨浏览器 / 跨设备时可辨;同浏览器多标签页里,B 看不出 m_1 是 A 那个标签页发的 (帧里 clientId 与自己相同)。要区分标签页得把它挪到 sessionStorage(每标签页一份), 代价是刷新后仍是同一个值、但「关掉再开」就变成新设备——两种语义各有用处, v3 选了 localStorage 版本(认设备,不认标签页)。这不是缺陷,是要写进 UI 文案的约定: 「A-desktop」是设备名,不是标签页名。
用例 6:进程重启,排队消息继续被回答
用户动作:m_2 在排队,进程崩溃重启
时序:
① 重启 → sessionLog.Reconcile → 发现 inbox 非空(m_2 还在)
② engine.trySchedule → 捞起 m_2 → run_started(r_18, [m_2], resumed:true)
UI:会话级 SSE 推 run_started(resumed:true) → 气泡明示「这条是重启前排队的」
③ r_18 跑完 → run_terminal(r_18)
UI:m_2 从 queued → answered
**关键点**:用户的字不丢。不变量 3(用户的字比输出帧贵重)+ 不变量 1(run 的命不属于任何连接)。
数据样例(崩溃前:session_log seq 1..3,inbox 有 m_2,r_17 档案行 status='running'):
—— 进程死掉。所有 SSE 连接随之断开,客户端进入重连 ——
重启后服务端做的两件事(§5.8):
UPDATE run_archive SET status='failed' WHERE status='running' ← r_17,logdb.go:110-115
trySchedule(s_1) → inbox.Drain=[m_2] → beginRunAtomic → r_18
客户端重连:
→ GET /api/session?id=s_1
← 200 {"liveRunId":"r_18","queued":[],"lastSeq":4}
会话级流 GET /api/session/stream?id=s_1&from=3 ← 补齐断开期间漏掉的帧
data: {"seq":4,"ts":"T6","kind":"run_started","runId":"r_18","messageIds":["m_2"],
"mergedText":"顺便看看 v1","resumed":true}
↑ resumed:true 是 UI 明示「这条是重启前排队的」的钩子,只在 Reconcile 路径上为 true
run 级流 GET /api/chat/stream?run=r_18&from=0
data: {"run":"r_18","seq":1,"ts":"T6","kind":"start","text":"顺便看看 v1"}
…
会话级流
data: {"seq":5,"ts":"T8","kind":"run_terminal","runId":"r_18","terminalKind":"complete"}
一处 v3 尚未覆盖的空档:Reconcile 只改 run_archive.status, 不给 r_17 补写终局帧——run_log 里没有 kind:"error",session_log 里也没有 run_terminal(r_17)。于是:
- 刷新/重连的客户端没事:它读
Snapshot.liveRunId(此刻是""或r_18), 根本不会去挂 r_17 的 run 级流; - 但一个执意重挂旧流的客户端(
GET /api/chat/stream?run=r_17&from=5, 例如断线重连逻辑里存着上次的 runID)会得到已落库的帧、然后永远等不到终局帧, 连接挂在半空,UI 停在「正在回答」。
修法有两条,都不贵:Reconcile 时给这些 run 补写一帧 kind:"error" (文本「进程重启,本轮中断」);或者让 run 级流在档案 status 非 running 且无更多帧时 主动收尾。已挂进 §10 问题 14,倾向补帧,随实施第 6 步(Inbox + SessionLog 落地)一并定。
以下 7–14 是打断路径与边界。前六个用例都是「一件事按顺序发生」, 这八个里有一半是两件事同时发生——真正的复杂度在这里。
用例 7:审批挂起期间排队
场景:r_17 要调 write_file,卡在审批上等人拍板(§5.4)。用户等不及,又发一句。 这是 v3 相对 v2 最直观的体验差:v2 里发送键被停止键替换,连排队的入口都没有; v3 里投递照常成功,只是不会有新 run 开出来。
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 闭包产出(session.go:319)。此刻:drive goroutine 阻塞、闸没放、SSE 没断
→ POST /api/message {"sessionId":"s_1","messageId":"m_2","clientId":"A-desktop","text":"顺便把 v1 也看看"}
← 202
会话级流
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(server.go:511);reject 时 run 不结束, 模型收到拒绝后自己决定怎么办(继续别的、或收尾),所以后面仍可能是 complete。
关键点:审批挂起占的是闸,不是收件箱。二者分离正是 v3 的结构, 这个用例是它唯一能被用户直接感知的地方。
用例 8:停止
场景:r_17 在跑,m_2、m_3 在排队。用户按停止。
→ POST /api/stop {"sessionId":"s_1","run":"r_17"}
← 200(run 对不上则 404,server.go:310)
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 不清收件箱(§10 问题 3 已决)
这是全套用例里最反直觉的一帧:用户按下「停止」,系统却开始了新一轮。 §4.13 因此要求停止按钮旁边明示「还有 2 条排队,会继续」并给一键清空 (DELETE /api/message/:id 逐条,或 §4.8 的 Delete 之外的批量清空——见 §10 问题 15)。 不做这个提示,用户会觉得「我明明停了它怎么又跑了」,而这恰恰是产品决定(§10 问题 3): 停止的语义是「这一轮不对」,不是「我说的话不算」。
用例 9:新会话(删会话)
场景:r_17 在跑,首帧还没到(模型还在思考)。用户点「新会话」。 这正是 §6 第四行那个 bug 的现场:v2 的 startNewSession() 依赖 state.runID, 而它只在收到第一帧 SSE 时才被赋值(index.html:1215),所以 if (run) 为假、 stop 根本没发,旧 run 继续写进一个用户以为已不存在的会话。
v2(错):
→ POST /api/stop {"sessionId":"s_1","run":""} ← state.runID 还是空,前端压根没发这个请求
旧 run 无人知晓地续跑,帧写进 s_1
v3:
→ DELETE /api/session/s_1
← 204
服务端按 §4.8 的 Delete 五步走:取消 live runCtx(不依赖客户端知道 runID)
→ 清 inbox → 一个事务删 run_log / run_archive / session_log / inbox 的会话行
→ SessionLog.CloseSession 断开该会话所有订阅 → 从 map 摘掉 Engine
所有客户端的会话级流:连接被服务端关闭(不是收到一帧,是流断了)
所有客户端的 run 级流(r_17):同样被关闭
被取消的 r_17 若已在写帧:emit 撞到已删除的行 → 写失败 → drive 记下 persistErr 退出。
**它写不进任何东西,因为没有行可写**——这是「删表」比「发 stop」强的地方。
验收方式:点「新会话」后立刻用 sqlite3 查四张表,session_id='s_1' 的行数必须是 0; 再等 10 秒查一次,仍必须是 0(证明旧 run 没有复活写入)。
用例 10:队列上限(422)
场景:r_17 跑得很久,用户已经排了 10 条。第 11 条投递。
→ POST /api/message {"sessionId":"s_1","messageId":"m_11","clientId":"A-desktop","text":"…"}
← 422 {"error":"队列已满","queued":10,"limit":10}
前端提示:「已经排了 10 条,先停一下当前任务?」
§10 问题 4 已决:排到 10 条说明这场 run 已经久到用户在对着它自言自语, 静默排队是不诚实的。这与不变量 7 不冲突——不变量 7 说的是「不因状态冲突失败」, 队列过深是用户的输入本身需要被重新考虑,是 4xx 的正当用途。 注意它不写 inbox、不推帧:422 是唯一一个「投递没发生」的出口,前端不该画任何气泡。
用例 11:滚到顶翻历史
场景:会话里有 40 个已结束的 run,页面首屏只画最近的。用户滚到顶。
→ GET /api/session/history?session=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?session=s_1&limit=20&before=2026-09-30T08:11:02Z|r_-3
← 200 更早的一页
接缝在哪里:HistoryPage 不返回 status='running' 的行(logdb.go:474)—— 正在跑的 run 由 Snapshot.liveRunId 报告、由 run 级流呈现。所以「历史」与「实时」 天然不重叠:一个是已结束的 run 数组,一个是活的帧流。
但 v3 引入了一处新的接缝:排队中的消息既不在 history 里,也不在任何 run 的帧里 (它只在 inbox 和 session_log 的 message_queued 帧里)。刷新页面时它靠 Snapshot.queued 恢复(用例 3),而翻历史翻不到它——正确,因为它还没成为历史。 UI 要把排队气泡画在输入框上方那一区,不要混进历史流,否则翻页时会被重复插入。
用例 12:SSE 单独断线重连(≠ 用例 3 的整页刷新)
场景:网络抖了一下,会话级流断了 3 秒。这期间另一端投递了 m_2,r_17 也落幕了。 页面没刷新,JS 状态还在,state.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"}
↑ 它自己会收尾关闭
为什么这条用例必须存在:§7.2 失败模式 1 说会话级流的 from=seq 续传 「不是可选优化」,session_log 持久化就是为它存在的。用例 3 走的是整页刷新 (JS 状态归零,靠 Snapshot 重建),没有验证「JS 状态还在、只补漏帧」这条路—— 而它才是日常最常见的那种断线。
前端实现上的关键:sessionSeq 必须每收一帧就更新,不能等批处理完; 否则重连时 from 报小了会重放(气泡重复),报大了会丢帧(气泡永久缺失)。 重放可以靠 messageId 幂等兜住,丢帧兜不住。
用例 13:run 中途压缩
场景:r_18 跑到一半上下文超阈值,压缩换掉了 r_15(§5.5)。
run 级流(r_18)
data: {"run":"r_18","seq":4,"ts":"T4","kind":"compact","text":"上下文较长,正在压缩早期对话"}
↑ compact 只表示「正在压缩」,text 是短句,不是摘要正文(sse.go:32)
…后续帧照常
用户看到什么:一句轻提示,不是新气泡、不是新 run。压缩是暗处的事(§5.5), 它不改 runID、不结束 run、不产生会话级帧——所以会话级流对压缩完全无感。 这是刻意的:压缩属于「模型视图真源」(Archive)的内部事务,不是会话级事实。
压缩之后翻历史会读到什么(接用例 11):r_15 的 produced_json 被清空、 原文挪进 compact_rag(§4.4)。GET /api/session/history 读的是 run_log 的帧, 不是 produced_json,所以 r_15 的对话在历史里照样能翻到、字还在。 被压掉的只是「下一轮模型看到什么」,不是「用户看到什么」。 这个区分是 §1 三真源的直接后果,也是最容易被实现搞反的地方。
用例 14:inject 插话(后置能力,实施第 12 步)
场景:r_17 正在读错的文件,用户想立刻纠正,不等它跑完。
→ POST /api/message {"sessionId":"s_1","messageId":"m_2","clientId":"A-desktop",
"delivery":"inject","text":"不对,看 doc/16"}
← 202
会话级流
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"}
与 after 模式的区别就在这一点:after 的 message_queued 后面必然跟着 (当前 run 落幕后的)run_started;inject 的后面什么都没有, 那句话直接进了正在跑的这一轮。前端因此不能用「有没有 run_started」判断消息是否被消费—— inject 消息的消费信号是它出现在 r_17 后续帧的语义里,没有专门的帧。
这是本用例集里唯一一个「帧协议不足以表达状态」的地方,所以 §10 问题 11 把它列为 可选阶段:要么加一种 message_injected 会话级帧(干净,但多一种帧), 要么让 UI 对 inject 消息只显示「已插话」不再跟踪状态(够用,但状态机有例外)。 倾向前者,随实施第 12 步一并定。
启动条件:after 模式稳定,且你真的开始嫌「等它跑完」太久。没有它 v3 仍然完整。
5.10 竞态对照表
用例 7–14 里有四个是「两件事同时发生」。把它们单独列出来,因为测试必须逐条覆盖, 而它们恰好是 server_test.go 那 1200 行里没有对应物的部分(v2 没有收件箱,就没有这些竞态)。
| 竞态 | 谁和谁 | 正确结果 | 靠什么保证 | 测法 |
|---|---|---|---|---|
| 撤回 vs 开跑 | DELETE /api/message/m_2 与 trySchedule 的 Drain |
二者只有一个赢:要么 204 + message_cancelled,要么 404 + 该 id 出现在 run_started.messageIds。不可能既撤回成功又被回答 |
inbox 行的删除与 Drain 在同一把锁/同一事务内(§4.6) | 并发 goroutine 各打一次,断言恰好一帧 |
| 停止 vs 正常完成 | POST /api/stop 与 drive 自然返回 |
只写一条终局帧。若产出已拿到,按 complete 记(产出仍算数,server.go:191-201) |
terminalOf 的判断顺序:err==nil 优先于 stopped |
在最后一帧前触发 stop,断言终局帧唯一 |
| 删会话 vs 投递 | DELETE /api/session/s_1 与另一端的 POST /api/message |
投递可能拿到 202,但它的帧和 inbox 行随会话一起消失;不留孤儿行 | Delete 第 2 步清 inbox、第 3 步删四张表在同一事务(§4.8) | 删完后查四张表行数必须为 0,再等 10 秒查一次 |
| 重连 vs 修剪 | from=3 续传与 session_log 修剪(§10 问题 5,未决) |
若 from 早于已修剪的最小 seq,不能静默丢帧 |
待定:要么返回一个「你落后太多,请重新拉 Snapshot」的信号,要么不修剪 | 问题 5 决议后补 |
这四条都还没有测试,因为 v3 还没落地。它们应该随对应的 action 一起写, 不是留到最后补——竞态测试事后补的成本是当场写的三倍,而且事后补的往往只测「不崩」, 测不出「恰好一帧」。
6. 顺带消灭的四个老问题
v3 不是为这四个问题设计的,但它们都随解耦一起消失了。这本身是「根因正确」的证据。
| 问题(会话级并发访谈稿) | v2 的表现 | v3 为什么消失 |
|---|---|---|
| B 吃 409 后变瞎子 | 前端只 appendError 就 return,不自愈 | 409 不存在。投递永远成功,B 的气泡立刻出现在所有端 |
| A 看不到 B 新开的内容 | 订阅是 run 级,A 无从得知 runID | 会话级流常驻。A 一直开着它,run_started 主动送达 |
| attachLive 的 404 窄竞态 | liveID() 早于 BeginRun 可见 |
不变量 9:runID 只在同事务提交后经 run_started 发布 |
| 「新会话」时旧 run 后台续跑 | startNewSession() 是 const run = state.runID; if (run) { POST /api/stop }(index.html:1092-1104)。而 state.runID 只在收到第一帧 SSE 时才被赋值(:1215)或 attachLive 时(:1286),send() 一开始还会把它清空(:1139)。所以从「按下发送」到「第一帧到达」之间它是空的——这段窗口覆盖了模型首 token 之前的全部思考时间,通常有好几秒,不窄。此时按「新会话」→ if (run) 为假 → stop 根本没发,旧 run 继续写进一个用户以为已不存在的会话 |
Engine.Delete:以 sessionID 为键、无条件取消 live(不依赖客户端知道 runID),再清 inbox、删四张表、关订阅(§4.8) |
另外两个体验改善:
- run 期间可以打字了。当前实现里发送键被停止键替换(index.html:967-971),
send()首行 busy 短路(:1132)。v3 删掉state.busy这个概念。 - 审批挂起期间可以排队。同一机制,从「困惑」变成「顺手」。
7. 取舍与代价
诚实列出。这些是 v3 真实变复杂的地方,不是可以忽略的脚注。
7.1 复杂度上升
| 项 | v2 | v3 |
|---|---|---|
| 表 | 3(run_log / run_archive / compact_rag) | 5(+ session_log / inbox) |
| 流 | 1 种(run 级) | 2 种(run 级 + 会话级) |
| 客户端游标 | 1 个(runSeq) | 1 + N(sessionSeq + 每 run 一个) |
| Engine 导出方法 | Start / Stop / Approve / LiveRunID | Enqueue / Cancel / Stop / Approve / Snapshot / Delete |
| 并发临界区 | 占闸(一处) | 占闸 + 取空收件箱 + 发布 runID(必须同事务) |
| 浏览器连接占用 | 1 条 SSE | 2 条 SSE(见下) |
连接占用是唯一一个「只在多标签页暴露」的代价,而多标签页正是 v3 要修的场景, 所以它不能当脚注:浏览器对同一 host 的 HTTP/1.1 并发上限是 6,SSE 长期占坑, 2 个标签页 × 2 条 = 4 个坑,只剩 2 个给普通请求。 缓解手段是 §4.7 的 SessionFeed 分层(换 WS 多路复用不动存储)与 §10 问题 10。
7.2 新的失败模式
- 会话级长连接断开期间的事件会丢——所以会话级流必须支持
from=seq续传, 这不是可选优化。session_log 持久化就是为它存在的。 beginRunAtomic事务失败时,消息何去何从? 它已从 inbox 被 Drain(事务回滚则恢复)。回滚是安全的,但需要一个重试策略, 否则消息会躺在收件箱里直到下一次 Enqueue 才被捞起。见 §10 待定问题 2。- 合并窗口让「我发的那句」与「回答」不再一对一。UI 必须能表达归组关系, 否则用户会困惑「我只问了一句,为什么回答里在讲两件事」。
message_ids就是为此存在的。 - 服务端回显引入一个 RTT 的延迟感(§4.13)。用户按下回车到气泡出现, 从「立刻」变成「一个来回」。这是拿即时感换多端一致性,是取舍不是纯收益。 已有解法(§10 问题 12):messageID 改客户端生成,前端用自己的 ID 立刻画 pending 气泡,
message_queued帧到达时按同一 ID 对齐——即时感回来,且不需要localEcho那种猜。 采纳后本条可以删除。
7.3 什么没变(这是阶段一的主要优点)
以下「不变」指阶段一。阶段二会动数据面(B 路的 emit、RunLog 写方法、Subscription、 前端渲染),改动范围见 §9 第 14–18 步与 §11.5;Archive 与 A 路两个阶段都不动。
- Archive 一行不改。合并发生在 Inbox 与 Engine 之间,Archive 看到的永远是一句 user 输入。
- drive 的 stream 循环、A/B 两路、审批挂起、compact 补偿事务全部不改。
- RunLog 的 run 级部分不改,只增加一个
BeginRunInTx变体供事务内调用。 - run 级 Subscription 不改,Partial 预留号、sealed、续传语义全部保留 (阶段一内;阶段二把这套机制整体退役,换成实体 + 字段补丁,见 §9 第 14–18 步)。
server_test.go那 1200 行里,测 run 内部行为的部分全部保留, 只有测「同会话第二次 POST 得 409」的用例需要改写成「第二次 POST 得 200 + 排队」。
8. 搬迁表(相对 v2 的增量)
本表覆盖阶段一。阶段二的搬迁范围(Partial/sealed 退役清单与新建的实体/补丁层) 见 §9 第 14–18 步与 §11.5,规格待第 14 步产出后再补表。
v3 新建
| 新文件 | 职责 |
|---|---|
internal/run/session_event.go |
SessionEvent / StoredSessionEvent / SessionEventKind / SessionSubscription |
internal/run/sessionlog.go |
SessionLog + SessionFeed(存储与传输分层,§4.7)+ 内存 sessionBuffer |
internal/run/inbox.go |
Inbox 接口 + QueuedMessage |
internal/run/sqlite/sessionlog.go |
SessionLog 的 SQLite 实现 |
internal/run/sqlite/inbox.go |
Inbox 的 SQLite 实现 |
internal/webui/handler_msg.go |
投递 / 撤回 / 删会话(替掉 v2 的 handler_run.go 里的 Start 部分) |
internal/webui/handler_stream.go |
两条 SSE:run 级 + 会话级 |
v3 修改(相对 v2 的设计)
| 文件 | 改什么 |
|---|---|
internal/run/engine.go |
Start → Enqueue + Cancel + Snapshot + Delete;新增 trySchedule / beginRunAtomic;liveRun 加 messageIDs |
internal/run/sqlite/migrate.go |
三张表 → 五张表;run_archive 加 message_ids 列 |
internal/run/sqlite/runlog.go |
加 BeginRunInTx;Reconcile 的遗留 running 检测移到 SessionLog(或两者协作) |
internal/webui/server.go |
路由表按 §4.12 改;Server 多持有一个 SessionLog |
internal/webui/dto.go |
加 messageRequest / messageResponse / sessionFrame |
internal/webui/sse.go |
加 StreamSession(无终局判断) |
internal/webui/static/index.html |
改动最大:删 state.busy、删 409 分支、删 attachLive,改成两层订阅编排(§4.13) |
不动
v2 §7「不动」清单全部照旧(compact / guard / taskboard / mediaoffload / tools / config / msgtext / fsbackend / repl)。
9. 实施顺序
v3 分两个阶段:阶段一只动入口与调度,数据面沿用 v2;阶段二按 §11 的增量协议重写数据面。 分阶段的理由在 §11.5——数据面重写量级不小于阶段一本身,捆成一步会丢掉阶段一最好的性质 (「执行与档案两个最难的部分完全复用 v2 的设计和测试」)。但分阶段 ≠ 分版本: 阶段二是 v3 的一部分,启动条件是阶段一的语义(投递永不因冲突失败)在 DB 上站稳。
本节是按「依赖」排的(先铺基础设施,再往上接)。实际执行按 doc/20 的用例 loop 排 (先让最痛的 409 消失,再为下一个用例引入下一个组件)。两套顺序不冲突,映射关系:
| §9 的步 | 兑现 §5.9 的用例 |
|---|---|
| 第 6 步(Inbox + SessionLog 落地) | 1、2 的存储面;顺带修 §10 问题 14(用例 6) |
| 第 7 步(Enqueue + trySchedule) | 1、2、10(422) |
| 第 8 步(两条 SSE) | 1、5、12 |
| 第 9 步(transport + 路由表) | 3、4、11 |
| 第 10 步(Delete) | 9 |
| 第 11 步(前端两层订阅) | 1–5、8、12、13 |
| 第 12 步(inject) | 14 |
| 停止 / 审批相关 | 7、8(§9 没有对应步——它们沿用 v2 的 Stop/Approve,v3 只加了「挂起期间能排队」这一层,随第 7、11 步落地) |
阶段一:入口与调度(第 1–13 步)
v2 的 7 步前 5 步照旧(领域帧独立 → adkrun 并入 → Engine 成形 → Subscription 替轮询 → Archive 成形)。 v3 的增量插在第 6 步之前,因为第 6、7 步(transport 换 Gin、同步前端)是改对外契约的, 应该一次改到位,不要改两遍。
- 领域帧独立(v2 第 1 步)
adkrun并入run(v2 第 2 步)- Engine 成形(v2 第 3 步)——先按 v2 的 Start 写,跑通再改
- Subscription 替掉轮询(v2 第 4 步)
- Archive 成形(v2 第 5 步)
- ★ Inbox + SessionLog 落地:建表、接口、SQLite 实现。此时还没有调用方,纯基础设施
- ★ Engine 入口换成 Enqueue + trySchedule:
Start删除,drive收尾加两步。 这一步做完,server_test.go里测 409 的用例必须改写——它们是 v2 不变量 6 的可执行版本, v3 删了这条不变量,测试也要跟着删/改 - ★ 会话级订阅 + 两条 SSE:
StreamSession、handler_stream.go - transport 换 Gin 原生(v2 第 6 步)+ 路由表按 §4.12
- ★
Engine.Delete+DELETE /api/session/:id:修掉「新会话时旧 run 后台续跑」(§6 第四行)。 这一步可以提前到任何时候单独做——它不依赖 Inbox/SessionLog, 只要Server能从 map 里摘掉 Engine 即可。是本次改动里投入产出比最高的一步。 - ★ 前端两层订阅重写(§4.13 / §4.14):删
state.busy、删state.localEcho、 删 409 分支、删attachLive,加排队气泡与撤回、加消息气泡四态状态机 - ★ inject 模式(§10 问题 11):
Enqueue加delivery参数、inbox 表加一列、 新增一个 steer middleware 走BeforeModelRewriteState把 pending 消息 append 进state.Messages。放在最后,因为它依赖第 6–7 步的 inbox,且失败时可以整块不做—— 没有它 v3 仍然完整(只是插话要等当前 run 结束)。 - 同步文档:doc/10、11、15 的接口描述,以及本文的 §10 待定问题决议
第 6–8 步可以在没有前端的情况下用 curl + 两个 curl -N 验证, 不必等第 11 步。这是把「改协议」和「改前端」分开的收益。
阶段二:数据面增量协议(第 14–18 步)
设计依据是 §11(Kimi 抓包对照):帧从「发生了一件事」改成「某实体的某字段变成了这个值」, 流式正文 op:"append" 只推增量,O(n²) 重发变 O(n),「流式中→定稿」退化为一次普通字段变更。 §11 给出的是形状与判断,不是可实施的规格——所以第 14 步是先把规格写死。
- 协议规格:实体树(message → block)、
op:set/append+mask字段路径、 跨实体全局单调 offset、带 offset 的heartbeat、显式done终止符。 落成文档:存储 schema、帧形状、续传语义(重连from=offset时增量帧如何补齐—— 实体在库里,追赶者读实体当前态即可,这是增量协议续传比 Partial 简单的地方) - 存储层:message 实体在
status:GENERATING时创建即落库,正文 append 累积进库。 崩溃窗口(§10 问题 7)从这一刻起结构性消失;删RestoreMessage与handleRestore悬空路由——doc/15:252 的「等 MQ」注记就此撤销, MQ 不再承担这个兜底职责(多副本投递价值不受影响,doc/16 #8c 相应收敛) - 订阅层:删
Subscription的 Partial 分支——预留号、AppendSealed、ErrSealConflict、dropPartialTail、游标不前移、buf.gen防忙等全部退役; run 级续传统一为「按 offset 追赶 + 读实体当前态」; 「流式中→定稿」变成一次op:"set" mask:"message.status" - 前端:从「按
Kind分派渲染」改成「维护实体树、按mask打补丁」;done终止符替换isTerminal判定(连带消掉 liveID-有值-档案-未写的 404 窄竞态);heartbeat带 offset 让客户端能区分「服务端卡住」与「在等 LLM」 - 测试与文档:
server_test.go里测事件形状的大部分改写; doc/10、11、15、16 同步,本文 §10 决议销账
阶段三:连接拓扑演进(未来)
阶段二完成后,如果多标签页场景下浏览器连接上限成为瓶颈(§10 问题 10:HTTP/1.1 并发上限 6, 2 个标签页 × 2 条 SSE = 4 个坑),可以把两条 SSE(会话级 + run 级)换成一条 WS 多路复用 (per 账号,承载所有会话)。§4.7 的 SessionFeed 已做存储与传输分层,换 WS 不需要动存储层, 只需要写 SessionFeed 的 WS 实现。
不在本顺序里的:账号级订阅(需先有 session 表,见 §10 问题 9)、adk.TurnLoop 换底座(阶段二之后再评估,见 §10 问题 11)。两者都不要提前塞进 v3—— 账号级订阅有硬前置;TurnLoop 尤其诱人(它原生就有收件箱、合并窗口、抢占和 checkpoint-resume),但换底座等于同时改语义层和执行层, 而 v3 的全部风险预算应该花在语义层(阶段一)与数据面(阶段二)上。
每一步 -race 全绿再走下一步(v2 的门槛保留,两个阶段同样适用)。 第 7 步尤其要压测不变量 8: 写一个测试,让 Enqueue 与 drive 收尾在纳秒级并发,断言消息不会搁浅。 阶段二的对应门槛:第 16 步删 Partial 分支前,先用测试钉住 「重连读者在流式中途加入,能看到实体当前态且不重不漏」。
10. 待定问题
会话级 seq 与 run 级 seq 的关系:已决——独立命名空间,但 inbox.seq 与 session_log.seq 同源。理由:两者都是会话粒度,共用一个计数器能让「消息入队」 在两张表里用同一坐标,客户端对齐时间线无需换算。run 级 seq 保持 per-run, 因为它的续传语义(Partial 预留号)依赖「本 run 内 max+1」,跨 run 共用会破坏不变量 4。
beginRunAtomic事务失败后消息怎么办:未决。三个选项:- (a) 事务回滚,消息留在 inbox,等下一次
Enqueue或trySchedule捞起 —— 简单,但可能长时间搁浅(如果用户不再发消息) - (b) 回滚后立刻重试 N 次,仍失败则写一帧会话级
error通知客户端 —— 用户可见,但要新增一种 SessionEventKind - (c) 起一个后台定时器周期性
trySchedule所有非空 inbox —— 兜底最稳,代价是多一个常驻 goroutine
倾向 (a) + (c):正常路径靠 (a),(c) 作为低频兜底(比如 30 秒一次)。 (b) 的可见性收益不大,因为 (c) 会让它最终一定被执行。
- (a) 事务回滚,消息留在 inbox,等下一次
Stop要不要清空收件箱:已决——不清(§4.8)。理由:停止的语义是 「这一轮不对」,不是「我说的话不算」。但前端必须明示剩余排队条数并提供一键清空, 否则用户会觉得「我明明停了它怎么又跑了」。这是产品决定,不是技术决定。合并窗口要不要设上限:已决——设上限 10,超出拒绝。 参考实现(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 的正当用途。
POST /api/message返回 422 + 当前排队条数,前端提示「已经排了 10 条,先停一下当前任务?」。session_log要不要修剪:未决。它是永久追加的,长会话会无限增长。run_log有同样的问题(v2 未处理)。倾向两者一起解决,不在 v3 范围内。Queued响应字段的意义:已决——整个响应体删掉。 本文早期草稿留了一个messageResponse{MessageID, Queued},Queued恒为 true, 理由是「将来可区分已开跑与在排队」。但那要求Enqueue同步知道trySchedule的结果, 把异步调度变成同步等待,与解耦的初衷相悖。 §10 问题 12 决定 messageID 由客户端生成之后,响应体里再没有服务端才知道的信息—— 所以POST /api/message直接回 202 无体,实际状态由会话级流的message_queued帧报告。RestoreMessage的现状:服务端死代码,兜底从来没接上:已核实,需要决定。⚠️ 本节早期草稿写过「v3 里补发的责任方倾向仍由 run 级流的持有者负责,因为它才有全文」。 这句话的前提是错的——浏览器手里根本没有全文。下面是核实结果。
服务端那一半存在且被测过:路由
POST /api/chat/restore(server.go:67)、 handler(server.go:456-485)、DB 方法(logdb.go:243,四重校验)、 测试TestRestoreCompletedMessage(server_test.go:1092)。但客户端那一半已经不在了,而且是主动拆掉的:
internal/webui/static/下只有 index.html 一个文件,其中restore出现 0 次- 全仓 grep
/api/chat/restore,除路由注册那一行外没有任何调用方 - 浏览器 localStorage 只存 sessionId(index.html:562-563、:1110),不存任何对话内容
- 那个测试直接调
d.RestoreMessage(...),d是 DB 结构体——不经过 HTTP,也不经过浏览器
这不是忘了写。doc/15:252 明确记着:
RestoreMessage和handleRestore暂时保留,等 MQ 落地后再删即:浏览器备份曾经有过,被有计划地移除了,服务端那一半是明知故留的悬空代码, 等 #8c(MQ 同步写入)接管。所以现状是一个已知、已记录、有既定修复计划的洞, 不是疏漏。
洞本身仍然敞开:现行代码确实在跑 Partial/seal(session.go:289-311), 逐字正文只进
eventMem,写完才AppendSealed落库。进程死在这两步之间时, 全文在eventMem里——而eventMem也是进程内存,一起没了。 那条 assistant 正文从 run_log 和 run_archive 同时消失,下一轮模型上下文缺这一条。 这是真实的(虽然窄的)数据丢失。已决(按两阶段修订):阶段一不动它,阶段二结构性消灭它。 阶段一数据面沿用 v2,窗口照旧敞开——按 doc/15 的既定计划等 MQ(#8c)接管, MQ 方案是「推浏览器前同步写 MQ」,MQ 里有完整内容,窗口自然消失。 阶段二的增量协议(§9 第 14–18 步)是达成同一目标的另一条路,而且更彻底: 实体从
GENERATING起就在库里,窗口不存在(§11.3)。届时删RestoreMessage, MQ 不再需要承担这个兜底职责——它的多副本投递价值不受影响,doc/16 #8c 相应收敛。阶段一唯一要做的是别让这个洞被误认为已堵: §11.2 与《会话级并发》§1.1 都已加更正。另外, 留着一条没人调的路由本身是有害的——它让读文档的人以为窗口被兜住了 (本文作者连续两轮就是这么以为的)。建议在
handleRestore上加一行注释指向 doc/15:252, 或者干脆现在就删掉——阶段二第 15 步本来就会把补发概念整个移除,不必等 MQ。要不要采纳 §11 的「实体 + 字段增量」协议替代 v2 的 Event 帧:已决——采纳,作为 v3 阶段二(§9 第 14–18 步)。 它同时消掉三块复杂度(Partial/sealed 预留号、
RestoreMessage、O(n²) 重发), 但它是数据面的重写,量级不小于阶段一——所以不与阶段一(入口与调度)捆成一步, 而在 v3 内部分阶段:阶段一保住「复用 v2 设计与测试」的优点, 阶段二等调度语义在 DB 上站稳后启动。理由见 §11.5。要不要把「会话」提升成服务端资源:未决,但这是 §4.0 账号级订阅的前置。 现在 sessionId 存在 localStorage(index.html:563),服务端只有
map[string]*Engine这个 进程内表——换浏览器就是新会话,清缓存就丢历史。要做账号级订阅(会话列表同步、 跨设备看到新会话),必须先有session表 + 用户身份。 v3 明确不做,但 §4.0 的三级模型为它留了位置。一条常驻流承载所有会话,还是每会话一条 SSE:未决,倾向后者起步、前者演进。 浏览器对同一 host 的 HTTP/1.1 并发上限是 6,SSE 长期占坑: 2 个标签页 × 2 条 SSE = 4 个坑,只剩 2 个给普通请求。 这个缺陷只在多标签页下暴露,而多标签页正是本次要修的场景——所以它不是理论问题。 Kimi 用一条 WS 多路复用所有会话绕开了它(§11.4)。 §4.7 的
SessionFeed已按可互换设计,换传输不用改存储层。要不要支持「插话进正在跑的这一轮」(inject 模式):前置已查证,结论是「可行,而且 eino 已经把 v3 的收件箱造好了」。
参考实现(WeKnora
internal/handler/session/steer.go:18-27)的投递有两种模式:steerDeliveryInject = "inject" // 在下一个 round boundary 排进正在跑的这一轮 //(并在自然停止前再排一次,让 agent 继续而不是收尾) steerDeliveryAfter = "after" // 默认。留在队列里等当前 run 退出,成为下一场 run 的 queryv3 只设计了
after。inject是严格更强的能力:用户看到 agent 走错方向, 想说「不对,看另一个文件」——after要等它跑完(可能几分钟),inject立刻生效。 这是产品级差异,不是优化。✅ 前置未知项已核实(eino v0.9.21,
$GOMODCACHE/github.com/cloudwego/eino@v0.9.21/adk/)。 答案是「有,而且不止一个」——原先列的三个选项里 (b) 成立,且存在比 (b) 更好的 (d)。(b) middleware 注入 —— 可行,且 tako 已有两个现成样板。
TypedChatModelAgentMiddleware.BeforeModelRewriteState(handler.go:160-171):called before each model invocation. The returned state is persisted to the agent's internal state and passed to the model. … access to
Messages: the conversation history. This is the recommended place to modify messages and tools before a model call. Changes here are persisted in state and reflected in subsequent iterations.这正是「下一个 round boundary 插一条 user 消息」。而且 tako 已经在用这个钩子:
internal/compact/handler.go:114、internal/mediaoffload/handler.go:40(都在BeforeModelRewriteState里重写state.Messages)。 一个 steer middleware 只是在末尾 append 队列里的消息——不需要新机制,只需要新调用方。注意
WrapModel不行(handler.go:246-250明写「Modifying input messages: changes here are NOT persisted in state, only affect a single model call」)——必须用BeforeModelRewriteState,因为只有它的改动会落进 state、被后续迭代看到。(d)
adk.TurnLoop[T, M]—— eino 原生的「收件箱 + 调度器」,v3 §4.6/§4.8 在重造它。turn_loop.go:879起,公开的泛型 push-based 事件循环。逐条对上 v3:v3 §4 设计的东西 TurnLoop 里的对应物 位置 Inbox.PutPush(item T, opts...) (bool, <-chan struct{})turn_loop.go:1381队列上限 / 拒绝 Push返回false(loop 已停);失败的投递可从TurnLoopExitState.TakeLateItems()取回:1368、:933合并窗口(一场 run 消费多条排队消息) GenInput(ctx, loop, items) (*GenInputResult, error)——「receives all buffered items, and decides what to process」,返回Consumed/Remaining:567、:636-667按本批消息装配 agent PrepareAgent(ctx, loop, consumed) (TypedAgent[M], error)——「set up the agent with appropriate system prompt, tools, and middlewares based on what items are being processed」:592事件 sink OnAgentEvents(ctx, tc *TurnContext, events *AsyncIterator[*TypedAgentEvent[M]]):611Engine.StopStop(WithImmediate/WithGraceful/WithGracefulTimeout/UntilIdleFor)+Wait():1524-1545、:1565崩溃恢复(未处理消息不丢) Store CheckPointStore+CheckpointID+GenResume(ctx, loop, interruptedItems, unhandledItems, newItems)——「the stored unhandled items are buffered and the loop proceeds normally」:584、:618-632inject 模式 Push(item, WithPreempt())——「atomically push an item and signal preemption of the current agent. This is useful for urgent items that should interrupt the current processing」;WithPreemptDelay()可延迟打断;WithPushStrategy(func(runCtx, tc) []PushOption)可按 item 动态决定 inject/after:1372-1380、:1411inject 的 round-boundary 落点 WithAfterToolCallsHook(fn)——「fires synchronously after all tool calls in a react iteration complete, before the next ChatModel call. This is suitable for TurnLoop Push+Preempt patterns where the pushed item must be visible to the next turn's GenInput」chatmodel.go:125-134WithPreempt比 WeKnora 的 inject 更强:WeKnora 只能在「下一个 round boundary」 插进去,TurnLoop 可以打断当前正在跑的 agent turn(preemptCtrl.requestPreempt,:1452),并且TurnContext上直接暴露tc.Preempted/tc.Stopped信号(:594-598)、tc.Loop(回调里可以再 Push/Stop,:846-847)。代价:tako 现在走的是
adk.NewRunner+internal/adkrun/turn.go:78每轮一次 (session.go:87),不是 TurnLoop。换过去意味着重构adkrun那一层, 且 v3 §4.8 的trySchedule/drive大部分要删(改由GenInput承担)。倾向(修正后):分两步,且顺序与 §9 的实施顺序一致——
- v3 阶段用 (b):加一个 steer middleware 走
BeforeModelRewriteState,Enqueue加delivery参数、inbox 表加一列。改动小、不动adkrun、 立刻拿到 inject 语义(只是落点在「下一次模型调用前」而非「打断当前调用」)。 - 阶段二之后再评估 (d):TurnLoop 是更正确的底座,但它同时重写了 v3 的 Inbox/scheduler/合并窗口/checkpoint-resume——在 v3 还没落地前换底座, 等于同时改两层。等 v3 的语义(投递永不因冲突失败)在 DB 上站稳了, 再把进程内的调度换成 TurnLoop,那时它带来的抢占与 resume 才是净收益。
一个额外收获:
GenResume的unhandledItems会被持久化并在Run()时重新缓冲 (:624-626),这覆盖了问题 7 那个崩溃窗口里排队消息的那一半 (assistant 正文那一半由阶段二落库后窗口关闭,见问题 7 与 §9 第 15 步)。- v3 阶段用 (b):加一个 steer middleware 走
messageID 由谁生成:已决——改成客户端生成。
参考实现(WeKnora
steer.go:41-49)的请求体里有两个客户端提供的字段:SteerID:「supply a stable ID so a consume event may precede the HTTP response」ExpectedAssistantMessageID:客户端把它看到的那场 run 带上(fencing token)
这同时解决 v3 的两个问题:
v3 的问题 客户端生成 ID 怎么解决 §7.2 失败模式 4:服务端回显引入一个 RTT 的延迟感 客户端用自己的 ID 立刻画 pending 气泡, message_queued帧到达时按同一 ID 对齐。即时感回来了,且不需要localEcho那种猜——ID 是同一个,对不上就是对不上不变量 9 治的 404 窄竞态 expectedRunID让服务端能判断「你说的那场已经不是现在这场了」,比「runID 只在提交后可见」更强:它还能检测客户端视图过期对 §4.8 的影响:已落进正文——
Enqueue(ctx, messageID, clientID, expectedRunID, text string) error,messageRequest加两个字段,messageResponse删除,handler 回 202 无体。多副本部署下 v3 还成立吗:成立,但有三处必须改。详见 §12.5。
背景:本文早期草稿断言「tako 是单进程 SQLite,有条件做治疗」——这是错的。 doc/03:42 的目标栈是
PostgreSQL/pgvector + Redis(asynq 任务队列), asynq 即多 worker;SQLite 只是测试替身。结论摘要:
- 会被打断的三处全是从 v2 继承的进程内机制:闸(
s.mu+s.live)、 审批(pending map[string]chan string,Go channel 不跨进程, 副本 A 阻塞等待、POST 落到副本 B → 404 → 审批永久卡死)、事件缓冲(eventMem)。 - v3 新增的两个组件恰好成立:
inbox与session_log都是 DB 表 (与 WeKnorasteerDataConsumed「放在事件上而非进程内存」是同一个答案);beginRunAtomic的同事务原子性是数据库级的,跨副本天然成立。 - 一处改法已给出:把闸从 mutex 换成 Postgres 部分唯一索引
CREATE UNIQUE INDEX one_live_run_per_session ON run_archive(session_id) WHERE status='running'——插入失败本身就是闸,不需要 Redis 或分布式锁,且比 WeKnora 的SetLiveRun更强(闸的判定与 run 的创建在同一事务,不可能不一致)。 SQLite 也支持部分索引,当前测试环境即可验证。 - 两处需要新设计:审批跨副本投递(倾向复用 §4.7
SessionFeed.Notify的模式)、Subscription的第二套实现(接口已分层,换实现不动调用方)。
即:v3 相对 v2 的改动,恰好是多副本方向上的改动。 这不是设计时预料到的(v3 的全部动机是 409 与多标签页),但结果是对的。 服务端仍要保证 messageID 在本会话内唯一(冲突则 409——这是正当的 409, 因为它表达的是「你重复投递了」,不是「你来得不是时候」,与不变量 7 不冲突)。 §7.2 失败模式 4 因此可以删除。
- 会被打断的三处全是从 v2 继承的进程内机制:闸(
Reconcile标 failed 的 run 要不要补终局帧:未决。 现实现的 Reconcile 只执行UPDATE run_archive SET status='failed'(logdb.go:110-115), 既不给 run_log 补kind:"error",也没有 session_log 的run_terminal(v3 新增路径同样没写)。 后果见 §5.9 用例 6:重连时读Snapshot.liveRunId的客户端没事, 但存着旧 runID 直接重挂 run 级流的客户端会拿到已落库的帧后永远等不到终局帧, 连接挂在半空,UI 停在「正在回答」。两个候选修法:- (a) Reconcile 时给每个遗留 run 补写一帧
kind:"error"(文本「进程重启,本轮中断」) —— run 级流自然收尾,回放历史时也能看到「这轮是怎么断的」,代价是写库量 = 遗留 run 数; - (b) run 级流在「档案 status 非 running 且库内无更多帧」时主动收尾 —— 不写库,但把「run 结束了吗」的判定从数据挪到了传输层,与不变量 3 的精神相悖。
倾向 (a):终局是事实,事实就该落在事实真源里。 实施时并入第 6 步(Inbox + SessionLog 落地)。
- (a) Reconcile 时给每个遗留 run 补写一帧
「停止后一键清空排队」要不要专门的接口:未决。 §10 问题 3 已决「Stop 不清收件箱」,且 §4.13 要求 UI 明示剩余条数并提供一键清空。 但清空用什么接口没定,两个选项:
- (a) 前端循环调
DELETE /api/message/:id—— 不加接口,但 N 条要 N 个请求, 中间任何一条撞上trySchedule就 404,前端得容忍部分成功; - (b) 加
DELETE /api/session/:id/inbox—— 一个事务清空 + 推 N 帧message_cancelled, 语义干净,代价是多一个路由。
倾向 (b):竞态由服务端一次解决,前端不需要处理「清了一半」。 用例 8 的帧序列按 (b) 写。
- (a) 前端循环调
POST /api/chat/restore留不留:未决,倾向删。 现状是死路由:handler(server.go:456)、DB 方法(logdb.go:243)、 测试(server_test.go:1092)都在,但前端从不调它(static/里搜不到 restore)。 更要紧的是它的前提与不变量 3 矛盾:restore 补的是「浏览器有、库里没有」的正文, 而不变量 3 要求「先落库,再推浏览器」——v3 下这种状态不可能出现。 唯一像的是 Partial 帧(内存里反复更新、sealed 才落库),但 Partial 帧本来就 不该被客户端补发:它不是事实,是过程。 删掉它同时删掉RestoreMessage与那个测试;若担心崩溃窗口, 正确的修法是让 sealed 落库失败时把 run 判为 error(不变量 3 的既有语义), 而不是让浏览器当备份。
11. 外部产品的帧协议,以及它暴露的 v2 数据面复杂度(阶段二设计依据)
本节起点是观察 + 判断,现已升格为 v3 阶段二(数据面)的设计依据 (§9 第 14–18 步、§10 问题 8 决议)。阶段一的数据面仍沿用 v2。 记在这里是因为:对照之后发现 v2 有几块复杂度是建模方式的产物,不是问题本身的。 证据来自对
POST www.kimi.com/apiv2/kimi.gateway.chat.v1.ChatService/Chat响应流的抓包(一次「真的吗」→「1+1」的短对话,33 帧)。另一个参考实现(WeKnora)的对照见 §12——它比 Kimi 更直接相关,因为 tako 的 现行设计就是从它抄来的。
11.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 是跨实体类型全局单调的游标。
11.2 与 tako 的对照
| 维度 | tako 阶段一(§4.1–4.3) | 增量协议(阶段二) |
|---|---|---|
| 帧的含义 | 「发生了一件事」 | 「某字段变成了这个值」 |
| 客户端要做的事 | 理解 Kind 语义,按 kind 分派渲染 |
维护一棵树,按 mask 打补丁 |
| 分类器 | 需要 Classify 把 eino 消息翻译成领域帧 |
不需要——没有「翻译」,只有「字段变了」 |
| 流式正文 | 同一预留 seq 反复推全文,n 个字 = 1+2+…+n = O(n²) 字节 | append 只推增量,O(n) |
| 「流式中→定稿」 | Partial 帧不落库 + AppendSealed + ErrSealConflict + dropPartialTail + 游标不前移 + buf.gen 防忙等 |
op:"set" mask:"message.status" 一次普通字段变更 |
| 崩溃窗口 | Partial 不落库 → 进程死在流结束与 seal 之间,全文只在 eventMem(也是进程内存,一起没了)。设计了 RestoreMessage 让前端补发,但浏览器那一半已被主动移除,服务端那半按 doc/15:252 留着等 MQ(§10 问题 7),窗口至今敞开 |
message 实体在 offset 3 就已存在,append 累积到哪儿库里就是哪儿 → 窗口不存在 |
| 用户自己那句话 | 前端 appendUser + state.localEcho 本地回显 |
服务端从流里回显(offset 2)→ 多客户端同步免费 |
| run 中途的元数据变更 | 无法表达(seq 是 per-run,chat.name 这类东西没有位置) |
mask:"chat.name" 与内容帧共用一个 offset 序列 |
| 保活 | 无心跳;writeEvents 里是 timer/notify select |
heartbeat 带 eventOffset,客户端能区分「服务端卡住」与「在等 LLM」 |
| 流的终止 | 查 run_archive.status,靠 isTerminal 判断(衍生出 liveID-有值-档案-未写的 404 竞态) |
done:{} 显式终止符,且它说的是「这条流完了」而非「这个会话完了」 |
11.3 最重的一条:Partial/sealed 是建模产物
v2 为了「流式正文」发明了一整套特殊机制(预留号、seal、冲突检测、尾部作废、游标不前移)。 根源在于把「正在输出」建成了一帧帧事件,于是必须回答「哪一帧才算数」—— 答案是「都不算,直到 sealed 那一帧」,机制由此展开。
增量协议把「正在输出」建成一个持久实体的一个状态字段(status: GENERATING)。 实体从一开始就存在、就在库里,内容通过 append 持续累积。 「哪一帧才算数」这个问题不成立,于是整套机制没有存在的必要。
连带消失的还有 RestoreMessage——它整个方法的存在理由就是 Partial 不落库造成的窗口 (v2 §9 决议 2)。而这个兜底现在只有一半,且是刻意如此的:服务端的路由、handler、DB 方法、测试都在, 浏览器那一半曾经有过、被主动移除;doc/15:252 明写「暂时保留,等 MQ 落地后再删」(核实过程见 §10 问题 7)。 所以增量协议不是「省掉一个已经工作的兜底」,是省掉一个已知悬空、正等着被 MQ 取代的兜底 ——这让 §11.5 的判断更强:两条路(增量协议 / MQ)都能关掉这个窗口,而增量协议还顺带省掉整套 Partial 机制。
11.4 连接拓扑:v3 的方案不是唯一解
Kimi:1 条常驻控制流(WS,per 账号,多路复用所有会话)
+ 1 条长命数据流(流式 POST,per 一次 Chat 调用,跨越「排队」与「执行」两个阶段)
v3 :1 次短 POST(投递,JSON 应答)
+ 1 条常驻会话流(SSE)
+ N 条 run 流(SSE,一场一条)
实测细节(抓包佐证上面的拓扑):
| 观察 | 说明的机制 |
|---|---|
wss://notilo.kimi.com/im/v1/subscribe/ws?encoding=proto&ticket=<ticket> |
控制面 = WS + Protobuf + 多路复用 + 短时 ticket 鉴权 |
逐字输出走 POST www.kimi.com/apiv2/kimi.gateway.chat.v1.ChatService/Chat,不走 WS |
数据面 = 流式 POST,与控制面物理分离 |
控制面挂在独立子域 notilo |
IM 基础设施复用,独立扩缩容域 |
| ticket 走 URL 参数 | 浏览器 JS 无法给 WS 设自定义 header,所以 ticket 必须是短时的 |
| Chrome Network / SharedWorker 里看不到这条长连接 | 控制面连接不在页面上下文里,或用了 DevTools 不记录的载体 |
Kimi 的连接数更少,且天然没有 404 竞态——它的流绑定的是「一次 Chat 调用」而非 runID, 调用可以先排队后执行,流一直开着,客户端从流里得知 runID。 v3 的不变量 9(runID 只在事务提交后可见)是为了治这个竞态发明的;在 Kimi 的拓扑下它不需要被治, 因为它不发生。
但 Kimi 的控制面 WS 依然必需:数据流只承载这一次调用产生的状态增量, 「B 删了会话」「会话列表多了一条」这类跨调用的事只能走 WS。 所以两个逻辑通道的划分是对的(§4.0),有争议的只是物理连接怎么摆。
v3 选两条 SSE 的理由是简单:不需要 WS 库、不需要 ticket 鉴权、不需要多路复用协议。 代价见 §10 问题 10 的浏览器连接上限。这是一个「先能跑,再优化」的选择,不是终局。
11.5 判断:分两阶段——阶段一不动数据面,阶段二按本节重写
采纳增量协议要重写的东西:Event/StoredEvent/Classify、RunLog 的全部写方法、 Subscription 的 Partial 分支、RestoreMessage、前端整套渲染、以及 server_test.go 里 1200 行中测事件形状的大部分。这是一次独立的重写,量级不小于 v3 阶段一本身。
而阶段一要解决的问题(409、排队、多客户端同步)一个都不依赖它—— 它们全在入口与调度层。把两件事捆在一起做,会丢掉阶段一最好的性质: 「执行与档案两个最难的部分完全复用 v2 的设计和测试」(§4.1–4.4)。
所以结论不是「不做」,而是分阶段:阶段一落地入口与调度(数据面沿用 v2), 阶段二按本节重写数据面(§9 第 14–18 步)。阶段二不是另一个版本,是 v3 的后半场; 它的启动条件是阶段一的语义(投递永不因冲突失败)在 DB 上站稳。 唯一现在就值得做的是 §4.7 的 SessionFeed 分层——它让将来换传输(SSE→WS 多路复用) 不需要动存储层,成本几乎为零,收益是保住演进路径。
12. 附录:WeKnora 对照——我们的设计从哪来,以及它自己走到了哪
§11 对照的是 Kimi(外部产品,抓包所得)。本节对照的是
ref-agent/WeKnora(腾讯,Go + Gin,tako 现行设计的直接来源)。 这一节比 §11 更要紧:它回答了「409 这个设计是从哪来的」, 也回答了「参考实现自己有没有走出这条路」——答案是走出去了,而我们没跟上。
12.1 tako 现行设计逐条对上 WeKnora
| tako(当前代码 / doc/19-v2) | WeKnora | 位置 |
|---|---|---|
POST /api/chat → text/event-stream,同一个请求既提交输入又流回输出 |
POST /knowledge-chat/:session_id → @Produce text/event-stream |
internal/router/routes_chat.go:119-128;internal/handler/session/qa.go:890,920 |
不变量 6:409 与 BeginRun 必须在写 SSE header 之前 |
注释原文:「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 |
session.live != nil → 409 |
rejectIfOtherAgentRunLive → NewConflictError("another turn is already running in this session") |
qa.go:1049-1065;internal/errors/errors.go:126 |
| 订阅是 run 级,要先知道 runID | GET /sessions/continue-stream/:session_id?message_id=...——同样要先知道 ID |
routes_chat.go:87;stream.go:35 |
| 没有会话级推送通道 | 也没有。全仓唯一的 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,不存对话内容 | 同样:localStorage 只有 embed session ID、模型选择、分组模式 | frontend/src/api/embed/index.ts:143 |
结论:tako 的传输层设计是 WeKnora 的忠实下游,连不变量 6 的论证文字都同理同辞。
12.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)
即投递永不因状态冲突失败——这就是 v3 的不变量 7。而这四个端点与 v3 §4.12 的 POST /api/message / GET /api/session(Snapshot 的 queued)/ DELETE /api/message/:id 一一对应,WeKnora 还多一个 v3 没设计的「提升」。
所以准确的判断不是「被 WeKnora 带歪了」,而是:抄了它的止血层,没抄它的治疗层。
而 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
多副本下不能重写入口(会破坏正在跑的其他副本),只能挂在旧协议旁边。
12.2b 一处更正:tako 也是多副本目标,而且 steer 是被明确划掉的
本文早期草稿在这里写过一句错的话:
「tako 是单进程 SQLite,恰恰有条件做治疗——这是 v3 相对 WeKnora 的优势,不是劣势。」
错在两处:
① tako 的目标栈不是 SQLite。 doc/03:42 记录的目标技术栈是 Go + Gin + PostgreSQL/pgvector + Redis(asynq 任务队列)+ MCP + 沙箱 + Vue。 asynq 是分布式任务队列 → 多 worker。SQLite 只是当前的测试替身,公测都不会用。 所以「多副本约束不适用于 tako」是假的——一样适用,v3 有三处进程内机制会被打断(§12.5)。
② steer 不是「没看见」,是看见了并明确划掉了。 doc/10:190-197 那张 「写下来是为了防止实现时被 WeKnora 带跑」的排除清单里,第 4 条就是 ❌ steer 运行中插话(同列的还有 ❌ 跨实例、Redis)。
而同一份 doc/10 的第 99 行,对 WeKnora 的 409 是这么写的:
特别注意它在写
text/event-streamheader 之前先做冲突检查(409/503,qa.go注释原文 "SetLiveRun happens before SSE headers")—— 流一旦开了就没法回头报错,这个顺序是踩坑换来的,照学。
于是分类错了:
| WeKnora 的东西 | 它的实际性质 | doc/10 把它归成 |
|---|---|---|
| 「SetLiveRun 在 SSE header 之前」+ 409 | 历史遗留——被多副本 + 生产流量锁死,动不了 | 定律(「踩坑换来的,照学」)→ 升格为 v2 不变量 6 |
| steer(投递永不失败) | 演进方向——它正在逃离上面那条遗留 | 可选功能(「❌ 第一期不做」) |
把别人的遗留当定律抄进不变量,把别人的演进当可选功能划掉。
排除清单本身没有错——第一期不做 steer 是完全合理的范围控制。 错在同时把 409 提升成了不变量:于是「暂不做 steer」从一个可撤销的范围决定, 变成了一个有约束力、要在 server_test.go 里守护的架构法律。 范围决定可以随时改;不变量改起来要动测试、动文档、动心智模型。
12.2c 修正后的结论:窗口是「未上线」,不是「单进程」
WeKnora 不能重写入口,是因为旧路径上有生产流量、跨着多个副本—— 重写会破坏其他副本上正在跑的 run。
tako 能重写,是因为 v2/v3 都还只是「设计草稿,未实施」,一行都没上线。
这不是持久优势,是一个正在关闭的窗口。 公测之后 tako 就会处在 WeKnora 今天的位置:旧入口上有真实用户, 重写变成破坏性变更,只能在旁边挂 steer 式的补丁, 然后再花几年时间解释「为什么我们有两套并存的输入语义」。
所以原结论方向对、理由全错。正确的表述是: 现在做治疗是唯一的免费机会,而且它与多副本目标不冲突——§12.5 论证这一点。
12.3 三处直接改进 v3 的细节
已吸收进 §10 的待定问题:
| WeKnora | 改进 | 落在 |
|---|---|---|
maxSteerQueueDepth = 10,理由「past that the run is clearly ignoring its user and the honest answer is to refuse instead of queueing silently」 |
队列上限从「软上限 5、超出延后」改成「上限 10、超出拒绝」。静默延后是不诚实的 | §10 问题 4(已决) |
delivery: inject | after(steer.go:18-27)——inject 在下一个 round boundary 排进正在跑的那一轮 |
v3 只有 after。inject 严格更强(用户能立刻纠偏),但要求引擎循环有 drain point。已查证:eino v0.9.21 有两处钩子——BeforeModelRewriteState(每次模型调用前重写 state.Messages,tako 的 compact/mediaoffload 已在用)与 WithAfterToolCallsHook(chatmodel.go:125-134,注释直接点名「suitable for TurnLoop Push+Preempt patterns」)。更进一步,adk.TurnLoop 本身就是收件箱+调度器 |
§10 问题 11(已决:v3 阶段一用 middleware,TurnLoop 阶段二后再评估) |
客户端提供 SteerID(「so a consume event may precede the HTTP response」)+ ExpectedAssistantMessageID(fencing token) |
messageID 改客户端生成。一举解决服务端回显的 RTT 延迟感(§7.2 失败模式 4 可删)与客户端视图过期检测 | §10 问题 12(已决) |
12.4 对「借鉴纪律」的一点修正
ref-agent/ 的纪律是「借设计,不抄实现」。这次暴露了一个盲区: 借鉴时要区分参考实现的「当前态」与「演进方向」。
WeKnora 的 409 + POST-returns-SSE 是它的历史遗留(被多副本部署锁死,动不了), steer 是它的演进方向。tako 把前者抄成了不变量,把后者划进了「第一期不做」(§12.2b)。
可操作的检查方法:在参考实现里 grep 「挂在旧协议旁边的新端点」—— 它们通常是演进的足迹。本例中 steer 就是这样一个端点:它不接受「会话忙」的拒绝, 与同一仓库里 20 行之外的 409 逻辑语义矛盾。那个矛盾本身就是信号。
配套的另一半检查:找到那个「遗留」之后,问一句 「它是因为什么约束才不得不存在的?」。本例的答案是「多副本 + 生产流量」。 如果那个约束在你这里也成立(tako 的目标栈是 Postgres + Redis + asynq,成立), 那它对你就是未来的债,不是可以照抄的定律; 如果不成立,那它就是纯粹的包袱,更不该抄。 两种情况下「照学」都是错的——这才是 doc/10:99 那句「照学」真正的问题。
12.5 多副本目标下,v3 哪些成立、哪些必须改
doc/03:42 的目标栈(PostgreSQL + Redis + asynq)意味着多副本。 这一节把 v3 的设计逐项过一遍,判定它在多副本下是否成立。
会被打断的三处(全是进程内机制,且都是从 v2 继承的)
| 机制 | 当前代码 | 多副本下的后果 |
|---|---|---|
| 闸 | s.mu.Lock(); if s.live != nil { return false }(session.go:93-96) |
每个副本各有一把 mutex,互不知情 → 同一会话在两个副本上各开一场 run,两边都写 run_archive、都改模型上下文,互相覆盖 |
| 审批 | s.pending[id] = make(chan string, 1)(session.go:241-247) |
最严重:副本 A 的 ask 阻塞在 Go channel 上;用户的 POST /api/approval 被负载均衡送到副本 B;B 的 pending 里没有这个 id → 返回 404,审批永久卡死,A 那边的 run 一直挂着直到 ctx 取消。Go channel 不跨进程 |
| 事件缓冲 | eventMem(进程内存,eventmem.go:75-153) |
订阅只在拥有该 run 的副本上能拿到实时帧;其他副本只能读库追赶,Partial 帧永远看不到(它本来就不落库)。阶段二(§9 第 15 步)后正文随 append 进库,这行的「永远看不到」前提消失,剩下的只是实时帧跨副本投递问题(归 MQ/传输层) |
WeKnora 正是为此才有 internal/stream/ 的 memory_manager 与 redis_manager 两套实现 (doc/10:100 已经注意到了这一点,但只当作「sink 抽象」的印证,没意识到它意味着 tako 迟早也要写第二套)。
恰好成立的部分(v3 的两个新组件)
inbox 与 session_log 都是 DB 表,不是进程内存——这正是 WeKnora steerDataConsumed「lives on the event itself, not in process memory, so every replica agrees」 那条教训的同一个答案。v3 独立走到了同一处。
更关键的是 beginRunAtomic:inbox.Drain + BeginRunInTx + run_started 在同一个事务里。 这是数据库级原子性,跨副本天然成立——不需要分布式锁,不需要 Redis。
一处必须改:把闸从 mutex 变成 DB 约束
v3 的不变量 8(放闸与调度必须原子)目前靠「持 e.mu 时判断 live == nil」实现, 多副本下失效。改法是把「每会话最多一场 live run」表达成数据库保证:
-- Postgres 部分唯一索引:同一会话最多一行 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 里了,顺手。tako 用 Postgres 部分唯一索引更省一次网络往返, 而且闸的判定与 run 的创建不可能不一致(同一个事务)—— Redis 方案里 SetLiveRun 与后续写入是两个操作,中间有窗口。
⚠️ SQLite 也支持部分索引(
CREATE UNIQUE INDEX ... WHERE), 所以这一条在当前的测试环境下就能验证,不必等 Postgres。
两处需要新增设计(v3 尚未覆盖)
- 审批必须跨副本。
pending map[string]chan string换成 「决策写进 DB/Redis + 持有 run 的副本订阅它」。最小改动是把审批决策也做成一行记录,ask从「阻塞在 channel 上」改成「阻塞在一个以 approvalID 为键的通知上」—— 与 §4.7SessionFeed.Notify是同一个模式,可以复用。 或者用 sticky session(按 sessionID 一致性哈希路由), 代价是副本挂了那个会话的审批就丢了。倾向前者。 - Subscription 需要第二套实现。
eventMem→ 共享缓冲(Redis Stream 或 Postgres LISTEN/NOTIFY)。 接口已经是RunLog/SessionFeed,换实现不动调用方—— 这正是 §4.7 把存储与传输分层的收益兑现之处。
结论
多副本目标不推翻 v3,反而是 v3 的一个论据: 它新增的两个组件本来就是 DB 表,事务原子性本来就是数据库级的。 需要改的三处全部是从 v2 继承来的进程内机制,与 v3 的新增部分无关。
换句话说:v3 相对 v2 的改动,恰好是多副本方向上的改动。 这不是设计时预料到的——v3 的全部动机是 409 与多标签页——但结果是对的。