30 · 崩溃续跑(doc/16 #7c)
性质:施工中(2026-10-21):A1–A5 已落地并验收;A6 已由客户端触发式恢复取代(2026-10-21 用户裁:server 自动巡检不做);A8 前端 reattach 已落地并验收;A7 回归收口已跑(矩阵重放全过,doc 回填随本批做)。 本篇是 #7c「在途轮次崩溃续跑」的设计真源;施工台账在
tmp/30-崩溃续跑/(不入库)。 已完成的活体验收:A4ar_01M57ESWS6M2FESYMGWQ35NDWK(psql 造终稿 → resume 202 → 首帧 resume → 不调模型直接定稿);A4br_01M57ETJGQW7W5X380SC5N1J12(tool_result 后 kill -9 → resume → 3554 条新 delta → complete);A5r_01M57EY98VEDQG6WS1R24GNCN7(bash 写文件后 sleep 中被 kill -9 → resume → ticks.txt 仍 1 行、中断文本逐字进 log、 tool_call 恰 1 条)。go test ./internal/runengine全量绿 + vet 干净。 关联:doc/19-v6(引擎主方案与存储真源划分)、doc/17 §6(子代理折叠)、doc/27(用量)、 doc/26(工具护栏)。doc/16:50 的 7c 行只是索引,方案以本篇为准。结论先给一句:给正在跑的 run 加一份可落 PG 的步骤账本(
run_journal)+ 一个单调递增的 接管令牌(runs.lease_epoch)。崩溃后,新进程按账本把模型见过的消息重放出来, 缺结果的工具调用写成「已中断、不自动重跑」再继续;旧进程即使还活着,它的每一笔写入都因 令牌过期而失败,不能污染接管后的 run。
1. 先演一场故障
用户让 tako 读 30 个文件、汇总成一份报告。模型很听话,一轮一轮地调工具: 读文件 A、读文件 B、跑 bash 统计行数、写笔记……到第 12 次工具调用时,已经跑了八分钟。
这时引擎进程被 kill -9(部署、OOM、机器重启都行)。接下来发生的事,按今天的代码逐步演:
- 进程里的 goroutine 没了,
turn这个内存切片——本轮所有 assistant 消息、工具结果—— 跟着没了。 - Redis 的
tk:runlive:<run>(帧流)和tk:runepoch:<run>(写口令牌)没人续租, 30 秒后(-lease-ttl默认值)一起蒸发(2026-10-20 起tk:draft已移除,见 doc/38)。 - PG 里只剩三样东西:
sessions一行、runs一行(status='running',租约已过期)、run_model_messages和runlog_entries各一行 user 消息。 assistant 和 tool 行一行都没有——它们要等EndRun的 complete 分支才落库 (store.go:323-492),而EndRun挂在Worker.Run的 defer 上(worker.go:296-320), 进程被kill -9时 defer 根本不会执行。 - 用户的页面每 400ms 拉一次
GET /api/runs/{id}/frames。某一次开始返回{"frames":[],"nextOffset":N,"status":"gone"},因为runlive键没了。 前端按既有收口逻辑转去拉GET /api/sessions/{id}/log,只看到自己发的那句话, 没有 assistant 行,于是把气泡标成失败。 - 用户重新发一遍同样的请求。新 run 从零开始:30 个文件重读、bash 重跑、笔记重写。 如果工具带副作用(写文件、发搜索、写笔记),副作用也再来一遍。 已经花掉的八分钟和 token 完全作废,而且用户没有任何办法把「刚才做到哪了」接上。
这就是 #7c 要解决的失败。它不是「页面断线重连」——断线重连今天已经能用 (用户的连接断了,run 还在跑,重连后按游标补帧)。它也不是「会话丢了」——会话一直在。 它坏在:run 的执行体死了以后,它已经做完的步骤没有任何持久记录,无法被另一个进程接上。
2. 先把三个词钉死
这一节是给「将来照着实现、照着对质」的人看的。名词先给真身,再给操作。
2.1 传输是拉取,不是 SSE
当前引擎和前端之间没有 SSE、没有长连接、没有推送。整张面是五个普通 JSON 端点, 前端每 400ms 用 fetch 轮询:
POST /api/runs 投一条消息,202 返回 {sessionId,runId,messageId}
POST /api/runs/{runId}/stop 手动停止
GET /api/sessions/{id} 会话状态:liveRunId、runlogOffset、lastRunStatus
GET /api/runs/{runId}/frames 拉生成中的帧(?eventOffset=N)
GET /api/sessions/{id}/log 拉已定稿历史(?runlogOffset=N)
证据在代码里,不在印象里:
server.go:52-53的端点注释逐字写着「实时性 = 客户端轮询节奏(dev 建议 300–500ms), 服务端无长连接、无推送、无 heartbeat」。server.go:57-67的路由表只有 JSON 拉取端点(dev 下多一个 reset;另有 MCP 管理面与 媒体取字节端点,都不是推送通道),没有text/event-stream的 handler,也没有Flusher。- 前端
web/src/chat.ts的pollFrames是一个for循环:getFrames(runId, eventOffset)→ 处理delta/usage/terminal→await sleep(POLL_MS)→ 下一轮。没有EventSource。
仓库里唯一一处写「SSE」的是 redisstore.go:24 的旧注释(「消费端 ReadFrames/SSE 从这里按 index 读」)。它是 D1 落库前旧传输的残留,代码早已改成纯拉取。A1 顺手把这行注释改掉, 避免下一个人再被它带到「现在是 SSE」的沟里。
注(2026-10-18):另有一条独立方案 doc/31 计划新增 GET /api/runs/{id}/stream(SSE 只做 运输优化,拉取仍是正确性真源)。即使它落地,本篇的续跑也不依赖传输方式——resume 后照旧从 frames/log 拉;SSE 只是同一帧面的第二种读法,不进入本方案的 claim/重放/定稿链。
2.2 session 不是连接
session 是 PG sessions 表里的一行(pgstore.go:26-32),外加一份永久的定稿历史 runlog_entries。它不是一个 TCP 连接、不是一个进程、也不是一个 goroutine。
- 用户第一次不带
sessionId发消息时,AcquireRun在投递事务里懒建s_<ULID>这一行 (store.go:126-129)。之后所有请求带着它。 - 这个会话「活着」的意思是:这一行还在,定稿历史还能按
runlogOffset拉出来。 它不依赖任何进程。
所以「run 死了,session 怎么会活」的答案是:session 从来没有跟着 run 一起死。 死的是 run 的执行体(goroutine)和它的临时 Redis 键;会话这个容器和历史一直在 PG 里。 今天的行为是「run 死了就放弃这一轮,会话继续接下一轮」;#7c 改的是 「run 死了以后,在窗口内还能把这同一轮接起来」,不是把会话变成连接。
2.3 run 是什么,死在哪
一个 run 由三部分组成:
| 组成 | 存在哪 | 死后怎样 |
|---|---|---|
runs 一行:状态 + 租约 + 闸 |
PG | 行还在,status='running',lease_until 过期 |
执行体:goroutine、turn、foldBox |
进程内存 | 随进程消失 |
实时流与令牌:tk:runlive:<run> 帧列表、tk:runepoch:<run> 写口令牌 |
Redis | 租约到期后 30s 左右蒸发 |
runs 这一行同时是会话闸:部分唯一索引 one_live_run_per_session (pgstore.go:39)保证同一会话最多一行 status='running'。新 POST 想开新 run, 要么这一行已经被放闸(终态),要么被清扫成 error(store.go:133-137), 否则 INSERT 撞索引、返回 409 session_busy。
租约(lease_until)是「这个 run 还归某个活进程」的判据:run 出生即带 now()+lease,watchdog 每 lease-renew 续一次(worker.go:665-698); 进程死了没人续,读侧立刻不再把它算作活 run(pgstore.go:155-156 的 liveRunId 子查询带 lease_until > now())。
这里有一个关键选择:崩溃后不把 runs 行翻成 error。 它继续以 status='running' + 过期租约留在表里——这既是「可以续跑」的窗口,也是会话闸继续被占着的原因。 读侧把这种行派生成 interrupted(见 §8.1),而不是新增一个存储状态。为什么不用新状态:
- 新增
interrupted状态会让one_live_run_per_session的部分索引(只盖status='running') 立刻放闸,新 run 可以和待续跑的 run 并存,同一会话会出现两套模型上下文; - 续跑需要对同一行做「检查 + 改租约 + 换令牌」,
running是唯一能同时表达「闸还占着」和 「等一个执行者」的存储值; - 读侧的
interrupted是视图,不动索引、不动写入路径,旧客户端最多把它当running/错误处理。
3. 现状:崩溃时到底丢了什么
3.1 写盘时机表(今天的代码)
| 数据 | 什么时候写 | 崩溃在写之前会怎样 |
|---|---|---|
sessions 行 |
POST 事务内 | 没有会话;POST 回滚 |
runs 行(闸 + 租约) |
POST 事务内 | 没有 run;POST 回滚 |
run_model_messages 的 user 行(seq=1) |
POST 事务内 | 没有这轮输入 |
runlog_entries 的 user 行 |
POST 事务内 | 页面看不到这句话 |
run_model_messages 的 assistant/tool 行 |
只在 EndRun complete |
本轮工具历史全丢 |
runlog_entries 的 assistant/tool 行 |
只在 EndRun complete(stopped 例外:只写已配对工具行) |
页面没有回复,工具动作也没有 |
tk:runlive / tk:runepoch |
帧生成中边流边写 / 令牌随续约刷 TTL,租约到期蒸发 | 半截流丢;令牌失配即拒写 |
turn(本轮消息全序) |
只在内存,defer 交给 EndRun |
全丢 |
一句话:模型做过什么,只有内存和会过期的 Redis 知道;PG 只记得用户说了什么。 #7c 要补的就是这一格。
3.2 为什么 eino 的 checkpoint 救不了
eino ADK 有 checkpoint/resume 机制,但它的落点不在崩溃路径上:
adk/runner.go:298-304和:330-337:checkpoint 只在 cancel / interrupt 分支里保存。kill -9不会走 cancel,进程直接消失,这两段都不执行。- eino 没有官方的 PG / Redis CheckPointStore。官方示例和常见做法是文件或内存; 文件在多副本目标栈里没有共享保证(本项目的方案挂账是共享盘,不是进程本地盘), 用文件做续跑真源会把「哪个副本能读到」变成新的部署问题。
- 就算 checkpoint 存下来,它恢复的是 ADK 的图执行状态;本项目还需要恢复
turn的落库投影、定稿文本(turn 里 root assistant 的累计)、工具副作用的记账,以及「旧进程不能写」的围栏。 这些都不是 eino checkpoint 的语义。
所以 #7c 不接 eino 的 resume,自己落一份步骤账本。账本只记「模型见过什么」, 不试图复制 ADK 的内部状态;续跑时把账本重放成一份普通的模型输入,再走既有的 prepareInput / agent 循环。这个分界让恢复逻辑不依赖 eino 版本,也不要求 图能从中断点原地继续。
4. 目标与不变量
目标(按优先级):
- 进程崩溃后,同一个 run 可以被另一个进程(或另一个副本)接上,已完成的工具调用不重跑。
- 接管后的模型输入包含崩溃前模型已经见过的 assistant / tool 消息; 结果未知的工具调用有明确的「中断」文本,绝不自动重跑。
- 旧进程即使还活着(分区、GC 停顿、租约误判),它的任何写入都不能污染接管后的 run。
- 同一 run 的 runId 不变;会话闸在续跑窗口内继续占着,避免同一会话并行两轮。
- 所有恢复判定都在 PG / Redis 的持久状态上做,不依赖进程内注册表; 多副本下两个续跑者只能有一个赢。
不变量:
- I1(先记账再执行):任何有副作用的工具调用,在真正执行之前,账本里已经有它的 call id、工具名和参数。没有这条记录就不执行。
- I2(根代理只记根):账本只记 root 的 assistant / tool 消息。子代理内部的消息不记; 子代理对 root 来说只是一次
delegationTool调用,按普通工具记账。 - I3(令牌随写):
runs的每次续约/收尾、账本的每次写入、Redis 的每次追加, 都带当前lease_epoch;令牌不匹配 = 0 行 / no-op,调用方按「本 run 已不归我」退出。 - I4(定稿真源):正常 complete 的 assistant 终稿 = turn 里 root assistant 文本的累计(
pending[""]);run_journal只在崩溃恢复时读,正常路径不读它。2026-10-20 起不再读 Redis 正文键(doc/38)。 - I5(error/stopped 零写入不变):续跑失败、再次崩溃、用户停止,都不会把半截 assistant/tool 行写进
run_model_messages/runlog_entries。账本是可删的临时表, 不污染两个永久投影。
5. 设计总览
5.1 一张图
正常路径(今天)
模型流 ──delta──> tk:runlive ──EndRun──> run_model_messages
│ runlog_entries
└──turn(内存)──────────────────────────────────┘
崩溃续跑(新增)
模型每说完一枪 ──> run_journal: assistant 行(text + tool_calls + usage)
工具执行前 ──> run_journal: tool_call 行(call id + name + args)
工具执行后 ──> run_journal: tool_result 行(call id + output)
│
进程崩溃,租约过期
│
POST /resume 或自动巡检
│
claim:runs.lease_epoch + 1(旧进程自此写不进)
│
Redis:重置 runlive,压一帧 resume(text = 账本里 root 正文的拼接)
│
重放账本 ──> 当前 run 的 ModelMessage 行 + turn 条目
│
最后一枪是终稿?──是──> EndRun(complete),直接用账本定稿
│否
走既有 prepareInput/agent,继续调模型
5.2 端到端业务链路(谁 → 谁 → 谁)
- 用户发消息 →
POST /api/runs→AcquireRun抢闸、落 user 行、建 Redis 两键 →go worker.Run(..., epoch=1)。 - 模型返回一枪 → worker 把合并后的 assistant 消息写进
run_journal(root-only)→ 发tool_call帧。 - eino ToolsNode 调用工具 → 工具包装层先写
tool_call账本行 → 执行工具 → 再写tool_result账本行 → 结果回注模型。 - 进程崩溃 → 租约过期 → 用户/前端/巡检者发现
GET /api/runs/{id}是interrupted。 - 有人
POST /api/runs/{id}/resume→ClaimResume在 PG 里锁行、检查、lease_epoch+1、 读账本 → 同一笔之后(Redis 单条 Lua)重置runlive并写入resume帧、 把runepoch设成新代。定稿不写 Redis。 - 新 worker 启动 →
replayJournal把账本还原成ModelMessage/turn→ 最后一枪已是终稿就直接EndRun;否则把重放行接在会话历史后面,走既有prepareInput/ 折叠 / agent 循环。 - 续跑后的终稿照旧由
EndRun写run_model_messages/runlog_entries, 账本在同一笔事务里删掉。 - 用户轮询
GET /api/runs/{id}/frames?eventOffset=0,第一帧是resume(带账本正文), 之后是新生成的 delta,最后是terminal。
6. 账本:run_journal
6.1 它不是什么(先划清三张表)
| 表 | 回答的问题 | 生命周期 | 谁读 |
|---|---|---|---|
run_journal(新) |
这一轮 run 的模型到现在为止见过什么(含在途工具调用) | run 终止/放弃/停止时删 | 只有续跑 |
run_model_messages |
下一轮 run 的模型应该看到什么(已定稿、可压) | 永久(compacted 行留审计) | prepareInput |
runlog_entries |
用户看到的历史(定稿行,append-only) | 永久 | log 端点 / 前端 |
不把步骤写进 run_model_messages 的原因:mh 的不变量是「闸失 / 进程死 ⇒ 只留 user 半」 (error/stopped 自 2026-10-22 失败留痕后会落已产出的内容——见 19v6-03)。 如果工具一执行就写 mh,error 的 run 会在会话模型历史里留下半截 assistant/tool 环, 下一轮模型会看到一次没完成的工具调用;而且这些行还要单独清理、不能参与 compact 的 (run_id, seq) 计数。账本是独立的、可整表按 run 删的临时真源,不动 mh 的既有语义。
不把步骤写进 runlog_entries 的原因:runlog 是给用户看的定稿历史,append-only, seq 即 runlogOffset。生成中的工具动作只在帧里出现(getSessionLog 的注释: 「这里永远只有已定稿的 message」)。把在途步骤写进去会破坏「offset N 恒指同一条消息」 和「只增不删」的地基。
6.2 表结构
CREATE TABLE run_journal (
seq bigserial PRIMARY KEY, -- 全局单调,只用于排序;不是任何对外 offset
run_id text NOT NULL, -- 归属 run
epoch bigint NOT NULL, -- 写这一行时的接管令牌
role text NOT NULL, -- 'assistant' | 'tool_call' | 'tool_result'
text text NOT NULL, -- assistant 正文 / tool_result 输出;其余空串
tool_calls text NOT NULL DEFAULT '',-- assistant 行:[]schema.ToolCall 的原始 JSON
tool_call_id text NOT NULL DEFAULT '',-- tool_call / tool_result:回指模型给的 call id
tool_name text NOT NULL DEFAULT '',-- tool_call / tool_result:工具名
args text NOT NULL DEFAULT '',-- tool_call:模型给的原始 arguments JSON 字符串
model text NOT NULL DEFAULT '',-- assistant:产出这枪的模型生效 ref
usage text NOT NULL DEFAULT '',-- assistant:UsageBill JSON(没有账单则空串)
created_at timestamptz NOT NULL
);
CREATE INDEX run_journal_run_id ON run_journal (run_id);(GORM 对应 RunJournal,加进 autoMigrate 的第六个 struct。seq 用 int64 gorm:"primaryKey;autoIncrement",PG 侧就是 bigserial。)
为什么 seq 必须由 DB 分配,不能用 MAX(seq)+1:root 的多个工具在 eino ToolsNode 里默认并行执行(NewWorker 的 ToolsNodeConfig 没关并行),两个包装层可以同时 写 tool_call 行。MAX+1 会分配出同一个号,撞主键。bigserial 让 PG 发号, 写进来的顺序不保证等于模型 tool_calls 的顺序——重放按 call id 归组,不靠 seq 猜配对(§9.1)。
媒体(doc/32)不需要在账本里加列:入口图与 read_media_file 在对话里都只落 [media … path=… ] 占位文本,字节只进 workspace/.media/(media.go)。账本按 text 原样记录占位行,重放时媒体引用随消息一起回来。
为什么 assistant 行可能晚于 tool_call 行:eino 先发出 assistant 的流式事件,模型事件 被 worker 消费的同时 ToolsNode 可能已经开始跑工具。worker 的消费是异步的, 所以账本里完全可能出现
seq 1 tool_call call_A
seq 2 tool_call call_B
seq 3 assistant tool_calls=[A,B]
seq 4 tool_result call_A
seq 5 tool_result call_B
按「assistant 一定在 tool 行前面」的假设去重放会错。§9.1 的规范排序就是为这个形状写的。
6.3 谁写、什么时候写
三处写入,全部 root-only:
- assistant 行:worker 的 agent 事件循环里,
drain把一条模型流排干、拿到merged之后,先写账本,再发 usage / tool_call 帧、再进turn。写的内容:text = merged.Content(思考在ReasoningContent,不进账本——它与模型输入里 被stripReasoning清掉的那部分同源,重放也不需要);tool_calls = json.Marshal(merged.ToolCalls);model = entry.ref(root 的生效 ref);usage = json.Marshal(bill)(usageBill成功时;没有账单则空串)。- 只对
agent == ""写。子代理的 assistant 消息不写:它对 root 来说只是delegationTool的一次结果(§6.5)。
- tool_call 行:工具包装层在调用底层工具之前同步写。内容:
tool_call_id = compose.GetToolCallID(ctx)、tool_name = inner.Info(ctx).Name、args = 模型原始 arguments 字符串。 - tool_result 行:同一包装层在底层工具返回之后同步写。
tool_call_id/tool_name同上,text = 工具返回的字符串。
包装层的顺序是 journalTool(wrapToolErrors(t)):错误回注在内层(wrapToolErrors 把工具错误转成「错误:…」结果,error 不再上抛),记账在外层。这样无论是正常结果、 工具自己报的错、还是 错误: 回注,都会先有一条 tool_result 账本行。
包装点必须在 handler 链尾,不能固定在池装配点。 一手池在 NewWorker 装配 (worker.go:169-212),但另外两类工具是 run 起手才 append 进 runCtx.Tools 的: MCP 工具由 mcpToolHandler.BeforeAgent 追加(mcp.go:243),委派工具由 agentSpecHandler.BeforeAgent 追加(agents.go:462-464)。如果只在池上包壳, 崩溃在 MCP 调用中时账本连 intent 都没有——恢复时模型只看到一条 assistant tool_call, 却不知道参数、也不知道它是否执行过。所以用一个 journalWrapHandler 注册在链的最后 (overflow guard 之后),它的 BeforeAgent 把当轮 runCtx.Tools 整个换成 journalTool 包壳:一手池、MCP、委派、以后新增的任何工具,一处覆盖。
这一步同时定义了子代理边界:agentSpecHandler 比链尾 handler 先跑,它给子代理做 入口快照时拿到的是未包壳的工具(agents.go:404),所以子代理内部调用天然不记账; journalTool 里的 callerNameFrom 守卫(§6.5)保留作第二道闸,防止以后有人把包装 点挪到快照之前。
写失败怎么办:账本写入失败 = 本 run 走 error 出口,不静默降级。 理由:账本是崩溃恢复的唯一依据;一次写失败如果继续跑,下一次崩溃就会丢掉这一段, 恢复出来的模型输入与真实发生的步骤不一致。工具包装层在写 tool_call 失败时 不执行底层工具,所以不会出现「副作用发生了但没有记账」;写 tool_result 失败时 副作用已经发生,run 走 error,账本里留下一条无结果的 intent——下次续跑会把它合成 「已中断、不自动重跑」(§9.2),这是安全方向。
6.4 写入顺序与崩溃窗口
把「模型说完一枪 → 工具执行 → 结果回注」拆成时间片,账本对每个窗口的形状:
| 崩溃发生在 | 账本里有什么 | 续跑时怎么解释 |
|---|---|---|
| 模型流还没排干 | 上一枪的完整记录 | 半截流丢弃,从上一枪之后继续 |
| 流排干、assistant 行还没写 | 上一枪记录(可能已有本枪的 tool_call intent,见 §6.2 的乱序) | 本枪 assistant 正文丢弃;若已有 intent,按孤儿调用处理(§9.1) |
| assistant 行写了、工具还没开始 | assistant 行(带 tool_calls) | 给每个 call 合成「已中断」结果 |
| 工具执行中 | intent 行,没有 result | 合成「已中断」结果;不重跑 |
| 工具返回、result 行还没写 | intent 行,没有 result | 同上。副作用可能已发生,但结果不可知 |
| result 行写了、worker 还没收进 turn | intent + result | 按 result 重放,继续 |
| 最后一枪 assistant 没有 tool_calls、还没 EndRun | 完整终稿行 | 直接定稿,不再调模型(§8.4) |
关键的一条是「工具执行前先写 intent」:任何可能带副作用的调用,账本里都能找到它 可能发生过。恢复时不需要猜「这个工具到底跑没跑」,只需要把「没有结果」如实告诉模型, 由模型/用户决定要不要重新发起。这是 at-most-once(至多一次执行)而不是 exactly-once (恰好一次)的分界,见 §15。
6.5 root-only 与子代理边界
账本只记 root 的消息,判定点有两层:
- 结构层(主判定):链尾的
journalWrapHandler把 root 的runCtx.Tools全量包壳; 子代理在更早的agentSpecHandler里已按未包壳的工具做入口快照(§6.3),所以子代理内部 调用根本不经过包装层。 - 调用点层(第二道闸):
journalTool仍读callerNameFrom(ctx)(websearch.go:25-34); root 的callerStampMiddleware写""(worker.go:234),子代理写规格名 (agents.go:440-442),非空直接透传。
root 调用的工具——get_time、文件工具(含 read_media_file、read_pdf_text)、bash、memory、 search_history、web_search、MCP 工具(mcp__…)、delegationTool——全部记账。
为什么这样切:
- 子代理的内部消息本来就不进 root 的
turn/ mh(mhRowsFromTurn跳过Agent != "",EndRun只把子代理终稿写 runlog)。恢复 root 的模型输入不需要子代理的中间步骤。 - 子代理对 root 的价值是
delegationTool的返回文本;这次调用本身是 root 的工具调用, intent/result 都在账本里。崩溃时如果它还在跑,结果未知——和 bash 在跑是同一种形状, 按「已中断」处理。 - 如果给子代理也记账,账本会多出一套「子代理内部的 call id」命名空间,重放时要重建 子代理的输入,等于把 #7c 扩成「子代理内部续跑」——这是明确不做的范围(§15)。
6.6 清理
账本不是永久历史,以下五个点必须删:
| 触发 | 删除范围 | 代码位置 |
|---|---|---|
EndRun 成功落终态(complete/error/stopped 的 stopped fallback) |
本 run 全部行 | EndRun 的成功事务内 |
| 新 POST 清扫死行 | 被清扫成 error 的每个 run | AcquireRun 的清扫 SQL(§11.2) |
手动停止 StopRun |
本 run | StopRun 的更新事务内 |
| 自动巡检发现续跑次数耗尽 | 被翻 error 的 run | A6 的 sweep |
dev Reset |
全表 | Reset 的 TRUNCATE 加第六张表 |
EndRun 的闸失分支(更新 0 行)不删:那说明本 run 不归自己了,账本可能正被接管者使用。 只有成功拿到终态的那一笔事务才删。
7. 围栏:runs.lease_epoch
7.1 为什么租约本身不够(具体失败戏)
假设只用今天的租约做接管:
- 进程 P1 的 run R 卡住(GC、网络分区、机器假死),watchdog 续不上,
lease_until过期。 - 进程 P2 看到过期,抢到 R:把
lease_until续成未来的时间,开始续跑。 - P1 突然恢复。它的 watchdog 下一拍做
RenewLease:status='running' AND lease_until > now()——P2 刚续过,这个条件成立。P1 以为闸还是自己的。 - P1 的
EndRun同样满足status='running' AND lease_until > now(),于是它把 自己内存里的旧 turn 写进 mh 和 runlog,放闸、压 terminal。 P2 的续跑结果被覆盖或被闸失打断,历史里出现两套 assistant 行/一次错误的定稿。
租约只回答「现在有没有人续」,不回答「续的人是不是当初那个」。接管场景下, 新执行者会续同一行的租约,所以旧执行者的守卫会重新成立。必须再加一个 单调递增、只增不减的令牌:每次接管 +1;旧执行者的写条件带上它自己的令牌, 令牌过期就写不进去。
7.2 PG 围栏
runs 加一列:
lease_epoch bigint NOT NULL DEFAULT 1AcquireRun的 INSERT 显式写lease_epoch=1(新 run 的常量);ClaimResume的 UPDATE 做lease_epoch = lease_epoch + 1(§8.2);- 所有写
runs/ 写账本的地方带AND lease_epoch = ?:
| 写点 | 新增条件 | 0 行的含义 |
|---|---|---|
RenewLease |
AND lease_epoch = ? |
已被接管 / 已放闸 → watchdog cancel 本场 run |
EndRun 的守卫 UPDATE |
AND lease_epoch = ? |
已被接管 / 已放闸 → errGateLost,零写入 |
StopRun |
不加(用户停止对任何 running 行都有效) | — |
账本 tool_call / tool_result / assistant 插入 |
先 SELECT 1 FROM runs ... AND lease_epoch=? FOR SHARE |
行不存在/令牌过期 → errJournalStale,工具不执行或 run 退出 |
账本插入为什么用「先 SELECT FOR SHARE 再 INSERT」而不是一条 INSERT ... SELECT ... WHERE lease_epoch=?:见 §11.5 的竞态。两条语句放在同一笔 短事务里,FOR SHARE 会让接管者的 FOR UPDATE 等待这次插入提交;接管者读到账本时 一定能看到已经提交的 intent,而令牌过期后的新插入会卡在锁上、等接管提交后发现令牌变了、 0 行退出。这个顺序保证了「接管后读到的账本」和「接管前已提交的写」之间没有缝。
7.3 Redis 围栏
Redis 侧加一把「当前令牌」的镜子:
tk:runepoch:<runID> STRING,十进制 epoch,TTL = 租约
AcquireRun的 Lua 出生时写1,与 runlive 同 TTL;AppendFrame(唯一的帧写口)的 Lua 先读这个键,和调用方传进来的 epoch 比: 不等或键缺失 → 返回 0(调用方按accepted=false收摊,写口拒收退出)。这一步挡的是旧 worker 的 delta/ tool_result/usage/tool_call 帧——这些热路径不写 PG,PG 的 epoch 守卫管不到它们;RenewLease的 Redis 半同样比对,并把tk:runepoch的 TTL 刷回租约(它与 runlive 同生同灭,不刷就会在租约到点时先蒸发,下一次 Append 返回accepted=false); PG 已经用 epoch 判过活,Redis 再判一次是为了堵住 「PG 续约和 Redis 续租之间被接管」的窗口;EndRun的 Redis 半(压 terminal、删 runepoch)不需要再比对:它只在 PG 的EndRun成功之后才调用,而 PG 的EndRun已经带 epoch 守卫。它顺手把tk:runepoch一起删掉;- 续跑的种子 Lua(第 8.3 节)先把 epoch 键设成新值,再重置 runlive。
一个旧 worker 在接管后的命运:它的下一次 AppendFrame 返回 0 → drain 返回 accepted=false → Run 退出 → EndRun 的 PG 守卫 0 行 → 日志「闸已不在,空转」。 如果它正卡在一个工具里,工具返回后的 tool_result 账本插入会因令牌过期失败, 包装层返回错误,事件循环走 error 出口,EndRun 同样写不进去。旧进程不会有任何 一笔成功的历史写入。
7.4 runCancels 的 epoch
Worker.runCancels 现在是 runID → context.CancelFunc(worker.go:122)。 续跑引入后,同一个 runID 可能先后有两个 worker 注册;旧 worker 的 defer w.runCancels.Delete(runID) 会把新 worker 的条目删掉,stop 端点也可能取消错人。
改成:
type runCancel struct {
epoch int64
cancel context.CancelFunc
}Run存{epoch, cancel};- 自己的 defer 只在
entry.epoch == 自己的 epoch时 Delete; - watchdog 的「闸不属于我」取消只在 epoch 匹配时 cancel(否则会误杀新 worker);
- stop 端点取消当前条目(不看 epoch)——它就是要停这场 run;如果新 worker 还没注册, 下一拍续约失败会让它自己停,最坏晚一个
lease-renew。
8. 接管:claim 与 resume
8.1 状态与可续跑判定
对外状态(GET /api/runs/{id} 的 status)是派生的,不新增存储值:
runs.status |
租约 | 派生 status | 说明 |
|---|---|---|---|
running |
lease_until > now() |
running |
有活执行者 |
running |
过期 / NULL | interrupted |
崩溃或被分区,可尝试接管 |
complete |
NULL | complete |
正常定稿 |
error |
NULL | error |
失败/被清扫/续跑耗尽 |
stopped |
NULL | stopped |
用户停止 |
resumeCount = max(lease_epoch - 1, 0);resumable = status == "interrupted" && resumeCount < resumeMax。 resumeMax 是每个 run 最多被接管的次数(默认 3,-resume-max)。次数用尽后 resumable=false,续跑端点返回 409 resume_exhausted,自动巡检把它翻 error 并删账本。
8.2 claim CAS
POST /api/runs/{id}/resume 和自动巡检都走同一条 PG 路径:
-- 一笔事务
SELECT session_id, status, lease_epoch,
(lease_until IS NOT NULL AND lease_until > now()) AS alive
FROM runs
WHERE id = $1
FOR UPDATE;
-- status != 'running' → 409 not_resumable
-- alive → 409 run_alive(可能真活着,不抢)
-- lease_epoch - 1 >= $max → 409 resume_exhausted
UPDATE runs
SET lease_epoch = lease_epoch + 1,
lease_until = now() + make_interval(secs => $lease),
finished_at = NULL
WHERE id = $1
RETURNING lease_epoch;
SELECT seq, epoch, role, text, tool_calls, tool_call_id, tool_name, args, model, usage
FROM run_journal
WHERE run_id = $1
ORDER BY seq;
-- 提交FOR UPDATE 是裁决点:两个 resume 同时到,第二个在锁上等第一个提交,然后看到 alive=true → 409 run_alive。它也是一道「等账本写入落定」的闸:正在写 intent 的 工具包装层持有 FOR SHARE,接管者必须等它提交或退出(§11.5)。
alive 为真时不接管。为什么不用「租约快过期了先抢」:进程可能只是慢了一拍, 抢过来会造成两个执行者同时写;租约到期是唯一安全的接管信号。用户想立刻停, 走 POST /stop,那条路不看租约。
8.3 Redis 重建:resume 帧
2026-10-20 起 draft 已移除,现行见 doc/38。现行种子只动
runlive与runepoch:SET新令牌后PEXPIRE补回 TTL,再DEL旧帧、RPUSH一条resume、PEXPIRErunlive。定稿正文不进 Redis,EndRun读 turn。下面的旧脚本保留作历史诊断。
PG claim 提交后,执行一条 Lua(失败可补偿):
-- KEYS: runlive, draft, runepoch
-- ARGV: newEpoch, resumeFrameJSON, leaseMillis, seedText
redis.call('SET', KEYS[3], ARGV[1])
redis.call('DEL', KEYS[1]) -- 旧帧全部丢掉
redis.call('RPUSH', KEYS[1], ARGV[2]) -- 第一帧 = resume
redis.call('PEXPIRE', KEYS[1], ARGV[3])
redis.call('SET', KEYS[2], ARGV[4]) -- draft = 账本正文拼接
redis.call('PEXPIRE', KEYS[2], ARGV[3])
return 1三个决定:
- 旧 runlive 整个丢掉,不追加。 崩溃前的帧里可能有半截 delta(模型说到一半被杀), 这些文本从未进入账本。把它们留在新流里,用户会看到「模型说过但账本没有」的字, 续跑后的定稿却对不上。账本是权威:
resume帧的text= 账本里所有 root assistant 正文按顺序拼接,前端看到 resume 就用它替换气泡,而不是追加。 - resume 帧是新流的第一帧。 前端(或 curl)续跑后从
eventOffset=0拉, 第一帧就是它;eventOffset从头开始,因为这是一个新的生成段。旧的半截流已经 没有阅读价值,重新编号比维护跨段的 offset 更简单。 - draft 用
SET覆盖,不APPEND。 之后新模型的 delta 照旧追加到它后面;EndRuncomplete 时draft就是「崩溃前已定稿的 root 正文 + 新生成的正文」, 与正常 run 的「Σ root delta」语义一致。
Redis 失败怎么办:PG claim 已经把 epoch +1、租约续上,此时补偿 UPDATE runs SET lease_until = now() - interval '1 second' WHERE id=$1 AND lease_epoch=$2, 返回 500。run 仍是 running,下一次可以再 claim(epoch 再 +1)。这次失败的尝试 会消耗一次 resume 次数(epoch 已经加了),这是可接受的代价:令牌不能回退, 否则旧 worker 有可能重新获得写权限。
8.4 两个恢复分支
新 worker 启动后先读账本(claim 之后没有并发写者):
- 直接定稿分支:账本规范重放后,最后一个 assistant 消息没有 tool_calls。 说明模型在这一轮已经说完了终稿,崩溃只发生在「写终稿行」之前。此时不调模型,
turn = 重放条目,status = complete,直接走 defer 的EndRun。EndRun从 turn 里 root assistant 的累计拿全文,写 runlog 终稿行。 为什么必须这样:再调一次模型会把「已经有终稿」的对话再喂一遍,模型会再答一遍, 产生重复文本和额外 token;而且正常 agent 循环在「无 tool_calls 的 assistant」处 就结束了,续跑应该复现这个终点。 - 继续分支:最后一个 assistant 有 tool_calls(说明还要把工具结果回注、再调模型), 或者账本为空(崩溃在第一枪之前)。把重放行接在会话历史后面,走
prepareInput→ 折叠(如果需要)→agent.Run。模型看到的是: 之前的 assistant 正文 + assistant(tool_calls) + tool_result(真实或合成的「已中断」)。 然后像正常 run 一样继续,直到它给出无 tool_calls 的终稿。
两个分支的落库出口相同:defer 里的 EndRun(complete)。没有新的终态、没有新的写路径。
9. 重放:把账本还原成模型输入
9.1 规范排序(按 call id,不按 seq)
输入是 run_journal 按 seq 升序的全部行。输出是当前 run 的:
rows []ModelMessage:RunID = 当前 run,Seq从 2 连续排;turn []TurnEntry:给EndRun的两个投影用;seed string:所有 root assistant 正文的拼接;final bool:最后一个规范 assistant 是否没有 tool_calls。
算法(纯函数,单测直测):
- 第一遍扫 assistant 行:解析
tool_callsJSON,记下每个 call id 属于哪条 assistant 行;记下 assistant 行的顺序。 - 第二遍按 seq 遍历:
- 遇到 assistant 行:输出一条 assistant
ModelMessage(正文 + tool_calls), 然后按它tool_calls的顺序输出每个 call 的结果:账本里有tool_result就用它, 没有就输出合成的「已中断」文本。结果在账本里的实际 seq 可能更早(§6.2 的乱序), 这里按 assistant 的计划顺序归位。 - 遇到不属于任何 assistant 行的
tool_call/tool_result(孤儿行): 把相邻的孤儿按 call id 归成一组,输出一条合成 assistant(正文空 + 这些 tool_calls,参数取 intent 行的args),再按同样规则输出结果/合成中断。 孤儿 intent 是「assistant 行还没写、工具已经开始」的崩溃窗口;合成 assistant 是为了让 tool 行在 OpenAI 协议里有合法的发起行。 - 如果遇到一条没有 tool_calls 的 assistant 行:它是这一轮的终点。输出它,
final=true,停止重放;它之后的行一律忽略(正常情况下也不该有; 有就是旧账本/异常写入,记日志不参与模型输入)。
- 遇到 assistant 行:输出一条 assistant
- 输出坐标:每个输出的
ModelMessage.Seq从 2 递增;RunID固定当前 run。 user 行是 mh 里已有的 seq=1,不在账本里。 turn的顺序:assistant 条目后紧跟它名下的 tool 条目,与正常 run 的 「assistant 轮 → 工具结果轮」同形。并行工具的真实完成顺序不保留,按 call 顺序 规范化;runlog 的工具行也按这个顺序落,call id 保证配对不错。- 合成文本(精确常量,单测逐字节断言):
错误:工具调用在执行中被进程中断,没有拿到结果;引擎不会自动重跑这次调用。需要的话请重新发起。
这个文本与 wrapToolErrors 的「错误:」前缀同一风格,模型能把它当工具结果读; 它明确说「不会自动重跑」,把是否重做的决定留给模型/用户。
9.2 为什么缺结果不自动重跑
如果引擎在续跑时自动重放 tool_call,会有一个无法回答的问题:崩溃前那次调用 到底执行了吗?
- 执行了但结果没落账 → 再执行一次 = 副作用重复(写文件、发搜索、写笔记);
- 没执行 → 不重跑 = 模型以为工具失败了,可能绕路或向用户报错。
账本只知道「intent 存在、result 不存在」,不知道底层副作用的状态。唯一安全的默认是 不自动执行,把「结果未知」如实告诉模型。用户看到「已中断」后可以自己说 「再跑一次」;那时是一次新的、有明确授权的调用。这是 at-most-once 的取舍。
9.3 与 prepareInput / compact 的接法
prepareInput 今天从 ModelMessages(sessionID) 读全序,当前 run 只有 user 行。 续跑时要把重放行接在它后面:
history, err := w.store.ModelMessages(ctx, sessionID) // 老 run + 本 run user 行
history = append(history, replay.Rows...) // 本 run seq 2..
msgs, err := w.prepareInputFrom(ctx, sessionID, runID, history)prepareInputFrom 是现有 prepareInput 去掉「自己读库」那一步的内部形态; 折叠逻辑、box.setBase(history)、baseCount 全部不变。于是:
- 当前 run 的重放行会作为「当前 run 的交换单位」参与 compact:每个 assistant(tool_calls)
- 它名下的 tool 行是一个单位;
currentRunUnits(compact.go:286-308)要求单位以 assistant 开头,重放的规范顺序正好满足;
- 它名下的 tool 行是一个单位;
- 崩溃前已经做过的折叠不持久(
foldBox在内存里,EndRun才落staged)。 续跑时从原文重算;如果原文超线,prepareInput会再折一次。代价是摘要 token 可能重复花,但换来的是「账本只存原文、恢复逻辑不依赖折叠中间态」的简单性。 box.setBase的行带RunID=当前 run、Seq连续,ADK 后续追加的新行按nextRunSeq(midfold.go:229-237)接在最大值之后;mhRowsFromFold在EndRun时按「当前 run、seq≥2」筛出来、从 2 重编号(midfold.go:278-291)。 这条路径与正常 run 的折后落库完全同构。
9.4 turn / mh / runlog 的三路落点
| 产物 | 来源 | 落点 |
|---|---|---|
| 续跑前的 assistant/tool | replay.Turn |
和正常 turn 一起交给 EndRun |
| 续跑后的新消息 | agent 事件循环照旧 append 到 turn |
同上 |
| mh 行 | complete 时 box.finalRows()(正常)或 mhRowsFromTurn(直接定稿/兜底) |
run_model_messages |
| runlog 工具行 + 终稿 | EndRun complete 的既有分支 |
runlog_entries |
注意:续跑前的消息没有在崩溃前写进 mh/runlog(EndRun 没跑),所以由续跑后的 这一笔 EndRun 一次性写进去。这正是账本存在的意义:它不是「再存一份历史」, 而是「把这次 run 的记忆撑到下一次 EndRun 能执行」。
10. API 契约
10.1 GET /api/runs/{runId}
新增。字段序由 struct 固定(runId → sessionId → status → resumeCount → resumable):
GET /api/runs/r_01M...
200 {"code":0,"message":"","data":{"runId":"r_01M...","sessionId":"s_01M...","status":"interrupted","resumeCount":0,"resumable":true}}
200 {"code":0,"message":"","data":{"runId":"r_01M...","sessionId":"s_01M...","status":"running","resumeCount":0,"resumable":false}}
200 {"code":0,"message":"","data":{"runId":"r_01M...","sessionId":"s_01M...","status":"complete","resumeCount":0,"resumable":false}}
404 {"code":112002,"message":"找不到这次运行","data":null}
判定用 PG 时钟(now()),不用进程时钟。status 的派生规则见 §8.1; resumeCount = max(lease_epoch-1,0);resumable 还要看 resumeMax。
10.2 POST /api/runs/{runId}/resume
新增。无请求体(不读 JSON;空 body 合法)。
POST /api/runs/r_01M.../resume
202 {"code":0,"message":"","data":{"runId":"r_01M...","status":"running","resumeCount":1}}
404 {"code":112002,"message":"找不到这次运行","data":null}
409 {"code":112103,"message":"这场 run 还活着,别抢","data":null} ← 租约仍有效,可能真活着,不抢
409 {"code":112102,"message":"这场 run 已经定稿,没有可续的","data":null} ← 已是 complete/error/stopped
409 {"code":112104,"message":"续跑次数用完了,重新发一轮","data":null} ← resumeCount 已到 -resume-max
500 {"code":111901,"message":"服务暂时不可用,请再试一次","data":null} ← claim/Redis 失败;租约已补偿为过期
成功返回 202 表示「已经有一个执行者接管并在跑」,不等于完成;客户端应去拉 GET /api/runs/{id}/frames?eventOffset=0,第一帧是 resume。 重复调用时的第二个请求会拿到 409 run_alive——这是幂等语义:已经在跑了,别再开一个。
10.3 GET /api/sessions/{id} 的增量
在现有字段后追加 lastRunId(不改变已有字段顺序):
200 {"liveRunId":"","runlogOffset":5,"lastRunStatus":"interrupted","lastRunId":"r_01M..."}
liveRunId仍是「租约有效的 running run」,interrupted 不算活;lastRunStatus改成派生值:最新 run 若是「running + 租约过期」,返回interrupted; 其余照旧(complete/error/stopped/"");lastRunId是最新一场 run(按created_at DESC, id DESC),给客户端一个「哪一场中断了」 的入口,不用先知道 runId。
对旧前端的兼容性:它只检查 lastRunStatus === "stopped";看到 interrupted 会走 「无定稿行 → error」的旧分支,和今天崩溃后的表现一致,不会崩。真正的续跑交互 (显示中断、按钮、resume 帧替换气泡)是独立的前端 loop(§15)。
10.4 GET /api/dev/runs/{runId}/journal(dev-only)
新增,只在 -dev 时注册(与 /api/dev/reset 同待遇)。它是长期 dev 工具, 不是临时脚手架——验收、排障都要看账本。
GET /api/dev/runs/r_01M.../journal
200 {"code":0,"message":"","data":{"runId":"r_01M...","epoch":1,"rows":[
{"seq":1,"epoch":1,"role":"assistant","model":"deepseek/deepseek-v4-flash",
"text":"我先读文件。","toolCalls":"[{\"id\":\"call_A\",\"type\":\"function\",...}]",
"toolCallId":"","toolName":"","args":"","usage":"{\"promptTokens\":...}"},
{"seq":2,"epoch":1,"role":"tool_call","model":"","text":"",
"toolCalls":"","toolCallId":"call_A","toolName":"read_text_file",
"args":"{\"path\":\"a.txt\"}","usage":""}
]}}
404 {"code":112002,"message":"找不到这次运行","data":null}
rows按seq升序;字段全出(空串也出),方便 curl 逐字段断言;- 顶层
epoch是runs.lease_epoch的当前值;每行epoch是写它时的令牌; - run 已终态/被清扫时账本已删,
rows:[](run 存在就 200);未知 run 404。
10.5 resume 帧
Frame 复用现有结构(types.go:46-62),新 kind:
{"eventOffset":1,"kind":"resume","agent":"","model":"","text":"<账本里 root assistant 正文的拼接>"}
eventOffset由读侧按 LIST index+1 注入,写侧不填;agent/model恒在(与现有帧一致),空 = 非模型产物/root;text是种子全文,不是增量。前端收到它应替换气泡正文,并把eventOffset游标重置到这一帧;之后按 delta 追加。- 当前前端
pollFrames只处理delta/usage/terminal,未知 kind 直接忽略, 所以这个帧不会让旧前端崩;旧前端会停在旧游标(runlive 已被重置时可能空转), 这是独立的 reattach loop 要解决的事。
11. 竞态与裁决
11.1 两个 resume 同时到
SELECT ... FOR UPDATE 序列化。第一个 bump epoch、续租约、提交;第二个拿到锁后 alive=true → 409 run_alive。自动巡检的多个副本同理,只有一个能把 run 拉起来。
11.2 resume vs 新 POST(同一会话)
新 POST 在 AcquireRun 的事务里先清扫死行(store.go:133-137),再 INSERT 新 run。 两边的竞争由 runs 行的锁/条件决定:
- resume 先拿到行锁:它 bump epoch、续租约、提交。新 POST 的清扫 UPDATE 带
lease_until < now(),此时租约已被续成未来 → 不满足;INSERT 撞one_live_run_per_session→ 409session_busy。用户看到「会话忙」, 应等续跑结束或先 stop。 - 新 POST 的清扫先拿到行:它把行翻
error、删账本、提交;resume 的 SELECT 看到status='error'→ 409not_resumable。这一轮被放弃(abandon), 不再可续跑;新消息开新 run。
这就是产品上的取舍:同一会话里,新消息优先于旧 turn 的恢复。 用户如果在意旧 turn, 应该先 resume;如果直接发新消息,引擎把旧的一轮判死,不让一个崩溃的 run 永久占着会话。 清扫的 CTE 必须把「更新成功的那批行」的账本一起删(§6.6):
WITH dead AS (
UPDATE runs
SET status='error', finished_at=now(), lease_until=NULL
WHERE session_id = $1 AND status='running'
AND (lease_until IS NULL OR lease_until < now())
RETURNING id
)
DELETE FROM run_journal WHERE run_id IN (SELECT id FROM dead);必须是同一条语句(或同一笔带锁事务):先 DELETE 再 UPDATE 会让「刚好在这两步之间 续约成功」的活 run 被误删账本;UPDATE ... RETURNING 只返回真正被翻死的行。
11.3 resume vs stop
StopRun 的条件 UPDATE(status='running')和 claim 的 FOR UPDATE 在同一行上序列化:
- stop 先赢:行变
stopped(lease_until=NULL),账本删;resume 看到非 running → 409。 - resume 先赢:行续租约、epoch+1;stop 的 UPDATE 仍然匹配
status='running'(它不看租约),把行翻stopped、删账本;新 worker 的下一拍续约失败 → 取消,EndRun走 stopped fallback。停止仍然生效。
结论:stop 永远能停,不管接管是否刚发生;这也是我们把 StopRun 设计成 「不看租约、只看 status」的原因(store.go:526-545)。
11.4 旧进程 vs 新进程
| 旧进程的动作 | 被什么挡住 | 结果 |
|---|---|---|
AppendFrame |
Redis epoch 键不匹配 | 返回 0,写口拒收退出(accepted=false) |
RenewLease |
PG lease_epoch 不匹配 |
0 行 → watchdog cancel 自己 |
| 工具 intent/result 插入 | FOR SHARE + epoch 不匹配 |
errJournalStale;intent 时工具不执行 |
EndRun |
PG 守卫 epoch 不匹配 | errGateLost,零写入 |
runCancels.Delete |
epoch 匹配检查 | 不会删掉新 worker 的条目 |
旧进程如果还卡在模型流里,它可能继续消耗 token,直到下一次写帧/续约发现失效。 这是残余成本(§15)。
11.5 在途工具跨过接管边界
claim 的锁只覆盖账本插入的那一小段事务,不覆盖工具执行本身。所以存在这个窗口:
- 旧 worker 写了
tool_callintent,开始执行一个 30 秒的 bash; - 租约过期,接管者 claim 成功,读账本时看到 intent、没有 result;
- 旧 bash 执行完,包装层写 result —— epoch 已变,插入失败;
- 接管者的模型收到合成的「已中断」结果,不知道真实的 bash 结果;
- 如果 bash 有副作用,它可能已经发生。
这是 #7c 的硬边界:引擎不等待在途工具完成才允许接管(否则一个卡死的工具会让 run 永远无法恢复),也不自动重跑(否则副作用重复)。它选择把「结果未知」告诉模型。 缓解手段是工具侧尽量幂等/可检查(用户可以再问一次,或让模型先 ls/cat 检查现状), 不是引擎假装知道。
另一个窗口:工具执行完、result 插入成功,但 worker 的事件循环还没把结果收进 turn。 这不影响恢复——账本有 result,重放会把它收进来;turn 只是内存投影。
12. 自动续跑(可选)
2026-10-21 已拍:不做 server 巡检。 恢复触发走「延迟处理—客户端触发」:前端 reattach loop 在 reconcile 里看到
lastRunStatus=interrupted后自己调POST /resume(依据 §10.3 的lastRunId入口;多 tab/刷新并发由 claim 的 CAS 裁决,见 §17 第 1 条)。本节保留作 doc/16 #8b(IM/cron 入口)将来需要「无 client 可触发」的无感恢复时的方案素材。
手动 POST /resume 足够验收,但真实产品里用户不一定会在窗口内打开页面。 加一个可选的巡检器:
-auto-resume(默认false):关闭时只有手动/前端触发续跑;-resume-scan(默认30s):巡检间隔;- 巡检 SQL:
status='running' AND (lease_until IS NULL OR lease_until < now()), 按created_at取前 N 条; - 对每条:
resumeCount < resumeMax→ 走与手动端点相同的 claim + Redis 种子 +go worker.Run;- 次数耗尽 → 用 §11.2 的 CTE 翻
error、删账本,记日志;
- 多副本安全:两个副本同时扫到同一条,claim 的
FOR UPDATE只有一个赢,输家拿run_alive/not_resumable,忽略; - 巡检器和手动端点共用同一套 claim 代码,不复制判定。
默认关闭的理由:自动续跑会在用户没发话的情况下花 token、执行工具(即使有「不自动 重跑」的保护,模型可能继续调用别的工具)。这属于产品决策,不塞默认。若用户希望 「崩溃后无感恢复」,把它开成默认值是一次单独的决定,不由实现者顺手定。
一个行为变化要写清楚:开着自动续跑时,崩溃后用户直接发新消息,可能先被巡检器 claim,拿 409 session_busy。前端应按既有 409 语义处理(等本轮收口再补投), 或者关掉自动续跑、手动决定。
13. 施工分期
每个 action 都遵守 AGENTS.md 的「写完就停、等验收、不自动 commit」。契约拍的第一行 必须是打一个正在跑的东西(curl / kill -9 / psql),不能是测试运行器。 详细的 curl 命令与期望字节在 tmp/30-崩溃续跑/todos.md,这里只给每拍的范围与目的。
A1 · 读侧状态面
GET /api/runs/{runId}:派生running/interrupted/complete/error/stopped、resumeCount、resumable;GET /api/sessions/{id}追加lastRunId,lastRunStatus派生interrupted;runs.lease_epoch的读取(列在 A3 才加;A1 需要先有一个可读的 epoch 来源—— 实现时把列和DEFAULT 1一起加,写入路径仍只用 1,claim 留到 A4);- 修
redisstore.go:24的 SSE 旧注释。 - 目的:让「崩溃后 run 是 interrupted、能不能续」第一次对 curl 可见; 也是后面所有动作的观测面。
- 验收:短租约(
-lease-ttl 3s -lease-renew 1s)起引擎,发一条长回复, 在生成中kill -9,等 4s、重启引擎(状态在 PG/Redis,不随进程死),GET /api/runs/{id}从running变interrupted、resumable:true;GET /api/sessions/{id}的liveRunId为空、lastRunStatus为interrupted、lastRunId对上。
A2 · 账本底座
run_journal表 +RunJournalGORM 模型 +autoMigrate第六个;journalTarget(runID + epoch;A2 阶段 epoch 固定写 1,A3 接真值);journalTool包装层(intent / result)+ 链尾journalWrapHandler统一包当轮runCtx.Tools(一手池 + MCP + delegation,§6.3);- worker 在 root assistant 排干后写 assistant 行(先账本、后帧/turn);
- 清理:
EndRun成功、AcquireRun清扫、StopRun、Reset; - dev
GET /api/dev/runs/{runId}/journal。 - 目的:先把「崩溃时 PG 里到底有什么」变成可验证的事实;这一拍还不恢复。
- 验收:起引擎,发一个会调 bash 的请求(要求执行
sh -c 'echo tick >> ticks.txt; sleep 20'), 在tool_call帧出现后kill -9;等租约过期、重启引擎,GET /api/dev/runs/{id}/journal看到 assistant 行 + tool_call 行、没有 tool_result;盘上的ticks.txt有一行。 再跑一个正常完成的 run,journal 应为空(EndRun 删了)。MCP 工具的覆盖由TestJournalWrapHandlerCoversRunPool单测证明(不真拉子进程)。
A3 · 令牌围栏
runs.lease_epoch(默认 1)+AcquireRun显式写 1;RenewLease/EndRun/ 账本插入带 epoch 条件;账本插入的SELECT ... FOR SHARE;- Redis
tk:runepoch+ 三个 Lua(acquire / renew / append delta / append frame) 加 epoch 参数与比对;runliveFinish删 epoch 键; runCancels改{epoch, cancel},watchdog / defer / stop 端点适配;Worker.Run(..., epoch)与所有 store 写方法的 epoch 参数(测试机械补1)。- 目的:让「旧进程还活着但已被接管」不能写。没有这一拍,A4 的接管会覆盖/污染。
- 验收:起一个长 run,生成中在 psql 里
UPDATE runs SET lease_epoch = lease_epoch+1并redis-cli SET tk:runepoch:<run> 2 PX ...(模拟接管);观察下一次续约后 run 被 cancel、没有新的 delta、EndRun没有写出 assistant 行(GET /log仍只有 user); 再验证正常 run 不受影响。
A4a · claim + 种子 + 直接定稿
ClaimResume(§8.2)+ 错误映射(404/409 四态);POST /api/runs/{id}/resume;replayJournal的规范排序 +seed+final判定(纯函数);- Redis 种子 Lua + resume 帧;
- worker:读账本、重放、直接定稿分支(
turn种子 +EndRun);未实现的「继续」 先用临时 409tool_in_flight挡住——判定在 handler claim 之前读一次账本, 有「tool_calls 但缺 result」就不 claim,直接 409(避免烧掉一次 epoch;见下)。 - 目的:先把「账本 → 模型输入 → 定稿」这条链走通,用 psql 造一个确定的账本, 不赌崩溃时机。
- 验收:起引擎,发一条 run 再
kill -9;等租约过期、重启引擎;用 psql 往run_journal插一条assistant终稿行(无 tool_calls);POST /resume202;GET /frames?eventOffset=0第一帧resume的 text 等于该行;GET /log出现 assistant 行(text 为该行);GET /journal为空;GET /runs/{id}为 complete。 - 临时脚手架:当账本里有「有 tool_calls 但没有 result」的调用时,
/resume返回 409tool_in_flight(不是公开契约,A5 删除)。登记在 planning 的脚手架表。 施工状态:已按 A5 删除——缺 result 现由 §9.2 的合成中断文本处理,本条留作施工史。 - 这一拍回答:「账本能不能被 claim 后读出来、重放成一份正确的模型输入并定稿」。
A4b · 继续调模型
- 把重放行接进
prepareInputFrom,走既有折叠/agent 循环; box.setBase/nextRunSeq/mhRowsFromFold的坐标对齐;- 验收:发一场「先调
get_time、再写长文」的 run,在账本出现tool_result行后 (第二枪终稿还没排干)kill -9,重启引擎;POST /resume后模型继续生成新的 delta, terminal complete,runlog 里工具行 + 终稿行齐全,journal 为空。 账本用真实 run 产生(A2 的包装层已经能稳定写出assistant(tool_calls) + tool_result), psql 手写[]schema.ToolCallJSON 容易与 eino 结构漂移;psql 造账本只留给 A4a 的 「空账本 + 终稿行」;exhausted 等负路径由单测造数据,不跑失败活体。 - 目的:证明续跑不是「只能定稿」,而是真的能接着一顿工具循环跑。
A5 · 合成中断结果 + 真实崩溃端到端
- 缺 result 的调用合成 §9.2 的精确文本;孤儿 intent 合成 assistant;
- 删除 A4a 的临时 409
tool_in_flight; - 验收(本方案的主证):起引擎,发一个会调 bash 的请求,让命令先写文件再 sleep; 在
tool_call帧出现后kill -9;等租约过期、重启引擎,POST /resume202; 第一帧resume,随后模型收到「已中断」并继续;terminal complete;GET /log有 assistant 终稿;GET /journal空;ticks.txt只有一行(引擎没有自动重跑原调用)。 - 这一拍回答:「真实的 kill -9 能不能被完整接上,且副作用不重复」。
A6 · 自动巡检
- 状态(2026-10-21):已被客户端触发式恢复取代,不施工。 web 入口的恢复由前端 reattach loop 触发(检测
interrupted→ 调POST /resume);原拍范围留档: -auto-resume/-resume-scan+ 巡检循环 + 次数耗尽的清扫;- 验收:开巡检、短租约,
kill -9后不手动 resume,等一个 scan,run 自己完成; 次数耗尽与「重复扫描不再拉起终态 run」由单测覆盖(2026-10-18 验收纪律:活体只跑成功路径); 两个引擎连同一套 PG/Redis 时只有一个接管成功(另一个日志run_alive/not_resumable)。 - 目的:把「崩溃后续跑」从手动动作变成可选的产品行为;多副本裁决同一套 claim。
A7 · 回归与收口
go test ./internal/runengine全量 +go vet ./internal/runengine ./cmd/yktako;- 重放既有验收矩阵(四端点字节、折叠/溢出、用量帧、停止、子代理),确认 #7c 不改坏;
- 回填 doc/16 #7c 状态、doc/19-v6 索引、本篇施工状态;
- 台账
tmp/30-崩溃续跑/的实录与帧不入库。
状态(2026-10-21,随 A8 一起做):
go test -count=1 ./internal/runengine25.3s 绿(非缓存)、go vet ./internal/runengine ./cmd/yktako干净、npm run typecheck+npm run build绿; 验收矩阵按19v6-04的用例 1/2/3/4/6 + 停止逐条 curl 重放,全过(脚本见下)。 折叠/溢出/子代理三类不在 curl 矩阵里——它们由go test全量覆盖,且本轮只改前端、没动引擎。
A8 · 前端 reattach(客户端触发式恢复)
状态(2026-10-21):已落地并活体验收。 这是 #7c 的最后一块——谁来按那个按钮。 施工面只有
web/(api.ts/chat.ts/App.vue),后端一行不改。
- 改什么:
api.ts:Frame.kind加'resume'、SessionStatus加lastRunId、 新增getRun()/postResume()与RunState/ResumeResult类型;chat.ts:Bubble.state加'interrupted'+resumable?: boolean标志;reconcile()与closeOut()两处认出 interrupted;pollFrames()加 resume 帧分支; 新增resumeRun()(POST → 202 → 从eventOffset=0重拉);App.vue:interrupted 气泡用琥珀色(--warn,不是--danger)+「继续这一轮」按钮。
- 为什么:引擎侧 A1–A5 已把账本、令牌围栏、claim、重放做完并验收过, 但没人去调那个已经存在的
POST /resume——用户看到的是红色「失败,没有写进历史」, 只能重发,30 个文件重读、副作用重来、token 作废(§1 的失败故事)。 2026-10-21 裁「不做 server 巡检」后(A6),触发器只能落在前端。 - 三个 409 分开处置(§10.2 的契约,前端最容易做错的地方):
run_alive→ 不是失败(别人已在续),跟着重建帧面;not_resumable→ 回 log 收口;resume_exhausted→ 提示重发、不再给按钮。 - 两个语义陷阱(前端接线必读):
- resume 帧的
text是账本里已产出的整段正文,不是增量片段 → 用=替换, 不能用+=(会把崩溃前的正文重复拼一遍); - 续跑后必须从
eventOffset=0重拉——seedResume把tk:runlive整个删掉重建, 客户端手上的旧游标全部作废。
- resume 帧的
- 验收(2026-10-21,Playwright + 系统 Chrome;脚本不入库):
- 崩溃 → 重启引擎 → 刷新:气泡是
interrupted(琥珀「这次运行中断了」+「继续这一轮」按钮), 不是红色失败;runs行仍running/租约已过期没被翻 error;账本活着;ticks.txt 仍 1 行。 - 点「继续」:气泡转
done;runs行complete/lease_epoch=2;账本归零(终态即删); runlog 里能看到那句逐字节固定的中断文本;ticks.txt 仍 1 行(副作用没重复)。 - 并发:curl 先 claim 这场 run,浏览器再点同一个按钮 → 拿到 409
run_alive→ 没有 error 气泡,跟着重建帧面拿到续跑内容。 - 模型侧的行为正是设计要的:它读到「已中断、不自动重跑」后,自己去查 ticks.txt 核实副作用 到底发生没有,如实报告并问用户要不要重跑,没有自作主张再执行一次。
- 崩溃 → 重启引擎 → 刷新:气泡是
- 交互形态:显式「继续这一轮」按钮(2026-10-21 用户拍)——用户不在场时不会自动烧 token, 与「不做 server 巡检」的裁断一致。检测到 interrupted 就自动恢复的形态不做。
14. 验收
14.1 环境
- 真二进制,不是
go test:在yk-tako-eino/里PATH="$HOME/sdk/go1.27.0/bin:$PATH" go build -o /tmp/yktako-30 ./cmd/yktako; - 端口用 18990(先
lsof -i :18990,被占就换;不杀别人的进程); -lease-ttl 3s -lease-renew 1s(续约必须严格小于租约,main.go:106-108会 fail fast);- workspace 指到
tmp/30-崩溃续跑/ws,不要污染仓库根; - 会话每次新开(不带 sessionId,或记下返回的
s_...); - 不要调
/api/dev/reset(dev PG/Redis 是共享的;用独立会话/workspace 隔离); - kill 只 kill 自己起的 PID;清理自己留下的
sleep子进程; - 每个 action 收尾跑
go test ./internal/runengine+go vet。
14.2 主证(A5)
- 起引擎(短租约、workspace 指向临时目录)。
POST /api/runs,prompt 明确要求先跑bash:sh -c 'echo tick >> ticks.txt; sleep 20; echo done',再报告文件内容。- 轮询 frames 直到看到
tool_call帧(name=bash,args 含ticks.txt), 确认ticks.txt已有一行tick。 kill -9 <自己起的 PID>;等 4s(> lease TTL)。curl GET /api/runs/{id}:status:"interrupted"、resumable:true、resumeCount:0。curl POST /api/runs/{id}/resume:202、{"runId":"...","status":"running","resumeCount":1}。curl GET /api/runs/{id}/frames?eventOffset=0:第一帧kind:"resume",text= 崩溃前 root 正文;随后出现新的 delta(模型基于「已中断」继续)。- 等到
terminal complete;curl GET /api/sessions/{id}/log:assistant 终稿行在, tool_call/tool_result 行在,result 文本是 §9.2 的中断文本(不是 bash 的真实输出)。 wc -l ticks.txt= 1(没有自动重跑);GET /api/dev/runs/{id}/journalrows:[]。
14.3 负路径(单测覆盖,不跑故意失败的活体)
2026-10-18 验收纪律:活体只跑成功路径,失败分支交给单测。下表的每一行对应一个测试名, 不在验收现场制造失败。
| 场景 | 期望 | 覆盖 |
|---|---|---|
| 租约未过期就 resume | 409 run_alive,run 继续跑 |
TestClaimResumeErrors |
| 对 complete/stopped/error 的 run resume | 409 not_resumable |
TestClaimResumeErrors |
| 续跑次数用尽 | 409 resume_exhausted;自动巡检把它翻 error |
TestClaimResumeErrors / TestSupervisorExhaustedSweeps |
| 未知 runId | 404 run_not_found |
TestClaimResumeErrors |
| 崩溃后直接发新 POST | 旧 run 被清扫成 error,账本删除,不能再 resume | TestAcquireSweepsDeadRun |
| 两个 resume 并发 | 一个 202,一个 409 run_alive |
TestClaimResumeConcurrent |
| stop 与 resume 并发 | 最终 stopped;不会留下 running 行 | TestStopWinsOverResume |
| Redis 种子失败 | 500;run 仍是 interrupted(租约补偿为过期);可再次 resume | TestResumeSeedFailureCompensates |
| MCP / 委派工具漏出账本,或子代理内部误记账 | 链尾包装覆盖全部 root 工具;子代理 ctx 透传 | TestJournalWrapHandlerCoversRunPool |
15. 残余风险与非目标
残余风险(接受并写清):
- 副作用不是恰好一次。工具可能执行了但结果没落账;续跑给模型的是「已中断」, 不是真实结果。是否重做由用户/模型决定。
- 跨接管边界的工具会继续跑。引擎不等待在途工具,也不杀进程树;
kill -9后 bash 的子进程可能继续,接管后的模型不知道它的最终副作用。 - 子代理内部不恢复。在途委派按普通工具中断处理;子代理已写的文件可能还在, 但它的推理链和中间消息丢了。
- 未记账的半截正文丢弃。崩溃发生在
drain与 assistant 账本行之间时, 用户可能已经看到半截字,续跑的 resume 帧会把它替换成账本里的正文。 - 折叠中间态重算。崩溃前做过的摘要不持久,续跑可能重复花摘要 token。
- 失败的种子消耗一次 resume 次数。epoch 不回退;
-resume-max 3下连续三次 Redis 失败会让 run 耗尽。 - 账本写入成本。每次模型消息 1 笔 PG 写、每次工具 2 笔 PG 写;工具调用多的 run 会更慢。账本在终态删除,不长期增长。
- 自动续跑会花 token。默认关闭;开启后崩溃恢复不需要用户在场,但也可能在用户 不知情时继续执行工具。
旧前端没有续跑交互。它会把 interrupted 当失败;resume 帧被忽略。已解决(2026-10-21,A8):前端已接上——interrupted 气泡显示琥珀提示 +「继续这一轮」, resume 帧按「整段正文」替换渲染,三个 409 分开处置(§13 A8)。新形态的残余风险: 用户不在场时那场 run 一直中断着,没人替它续——这是「不做 server 巡检」裁断的直接后果, 按用户在场时的可见性取舍,不是缺陷。- 特性上线前启动的 run 没有账本。它们崩溃后只能从 user 消息重来;没有追溯恢复。
- 单会话仍是一活 run。续跑窗口内新消息可能 409
session_busy; 同一会话不能并行恢复两轮。 - 鉴权不在本篇。resume 端点和现有端点一样只绑本地/单用户;多租户见 doc/28。
明确不做:
- 不做子代理内部的步骤恢复;
- 不做工具副作用的 exactly-once / 事务性补偿;
- 不做跨 run 的会话分支/回滚;
- 不做「检测到 interrupted 就自动恢复」的形态(只做显式「继续这一轮」按钮,2026-10-21 用户拍);
- 不做 server 端自动巡检(A6 已裁,§12 留档作 doc/16 #8b 的素材);
- 不做 eino checkpoint 的接入;
- 不做「自动重跑结果未知的工具」;
- 不改
run_model_messages/runlog_entries的既有语义; - 不新增存储状态
interrupted(只做读侧派生)。
16. 文档回填清单
| 文档 | 改什么 |
|---|---|
| doc/16:50、:156 | #7c 从 ⬜ 翻 🚧/✅(验收后),指向本篇 |
| doc/19-v6 索引 | 存储真源表加 run_journal / runs.lease_epoch / tk:runepoch;API 表加 run 状态与 resume;恢复语义指向本篇 |
| doc/30(本篇) | 施工状态、A1–A7 实录、残留风险按验收结果更新 |
redisstore.go:24 |
删掉「SSE」旧注释(A1) |
| doc/27 | 无需改;续跑的直接定稿分支沿用「最后一枪账单」规则,行为在 A5 验收里覆盖 |
| doc/17 §6 | 无需改;子代理仍不参与 root 账本,边界在本篇 §6.5 说明 |
| doc/33 §4.2 / §6 | MCP 工具与一手工具同经链尾 journalWrapHandler 记账,接口不变;崩溃时按普通工具中断处理(§6.3) |
| doc/32 | 无需改;媒体在对话里只有占位文本,账本按 text 原样记录(§6.2) |
web/src/api.ts、chat.ts、App.vue |
A8 的施工面(§13 A8):协议层 + interrupted 识别 + resume 帧 + 「继续这一轮」按钮 |
doc/19-v6 19v6-04 |
~~待补:该篇的期望字节仍停在 doc/28 之前(session 少了 lastRunStatus/lastRunId、 |
少了 workspaceId),A7 的矩阵重放是按现行代码的字节断言的。补这一篇时以 19v6-01 + 现行响应体为准,别照抄旧文本。~~ 已补(2026-10-21):按 19v6-01 + 现行响应体追平了 session 期望字节,并把实跑实录写进 该篇头注(跑中 / 定稿后两条 session 响应 + frames 四帧逐字实录)。同批发现并修了更宽的一处 漂移——19v6-01 §2 的「帧有五种 kind」断言(实际七种,usage / resume 是后加的), 连带 index 概念表与 doc/31 的计数。详见 19v6-90 二十五次修订 |
17. 待拍项
以下几项需要用户点头(planning 里有同样的清单):
- 自动续跑默认关闭(推荐):
-auto-resume默认false,手动 resume 先落地。如果希望崩溃后无感恢复,改成默认2026-10-21 已拍:不做 server 自动巡检;恢复采用「延迟处理—客户端触发」—— 前端在 reconcile 中看到true是一次单独产品决定。lastRunStatus=interrupted(配合lastRunId)即调POST /resume,claim 的 CAS 天然幂等,多 tab/刷新并发只有一个赢。将来 IM/cron 入口 (doc/16 #8b)没有 client 可触发,若需无感恢复,作为该入口的装配决策重开(§12 留档)。 交互形态 2026-10-21 已拍:显式「继续这一轮」按钮(不做「检测后自动恢复」)。 实装见 §13 A8。 - A4 拆分:A4a(claim + 种子 + 直接定稿)和 A4b(继续调模型)分开验收; A4 整体会超过 80 行目标,拆开后每拍仍有 100+ 行,但各自有一个确定的验收脚本。
- 续跑上限:
-resume-max默认 3。上限越大,越能扛连续崩溃,也越可能反复烧 token; 3 是「两次完整重试 + 一次余量」的经验值,可按用户偏好改。 前端 reattach 另立 loop:本篇只保证后端契约和 curl 验收;页面上的「中断/续跑」 交互不在本篇做。已做(2026-10-21):作为本篇的 A8 一拍落地(§13 A8),施工面在web/, 后端一行未改。
18. 产品视角:用户会遇到的场景
本节不引入新机制,只用产品和用户能感知的语言把 §2–§15 的结论走一遍,供产品、运营、前端 对齐。与实现细节冲突时以正文为准;完整的取舍清单见 §15。
一句话承诺:一次进程崩溃,不该让用户重讲需求,也不该让系统偷偷把有副作用的操作再做一遍。
场景一:一切正常 用户发消息、模型回复、工具执行,全部照旧。系统只是多记了一份「这一轮跑到哪了」的流水账, 跑完就删。用户感觉不到任何变化。
场景二:消息刚发出去,进程就没了 模型还没来得及说第一句话。用户重新打开时,这场回复先是显示「中断」,等心跳过期 (默认 30 秒,验收环境调成 3 秒)后可以续跑。续跑后模型从头想这一轮,用户那条消息 不会重复出现,也不会变成两条。
场景三:模型已经说完,就差最后「存档」 模型把完整回复说完了,进程在写历史之前挂了。续跑时系统发现「最后一段已经是完整答案」, 就不再调一次模型,直接存档。用户看到完整回复;系统不多花一次模型的钱,也不会给出 两遍不同的答案。
场景四:工具跑完了,模型还在写后半段 比如已经查完资料、写完文件,模型正在组织最终回复时崩了。续跑会把已经落账的对话 重新摆到模型面前,让它接着写。之前落账的内容先出现,然后新内容继续一个字一个字长出来。 正在写但还没落账的那半截字不算数——原因见场景十三。
场景五:工具跑到一半,进程没了(最危险的一种) 比如正在执行一条要跑 20 秒的命令,进程被杀。系统只知道「这个工具发出去过,但没收到 结果」,不知道它到底执行到哪、有没有产生副作用。这时候绝不偷偷重跑。续跑会给模型 一句明确交代:「这次调用执行中被中断,没拿到结果,引擎不会自动重跑。」要不要再来一次, 由模型或用户决定。历史里这次调用显示为「已中断」,而不是一个假成功。
场景六:进程只是假死,过一会儿又醒了 机器卡顿、网络分区、容器暂停——旧进程没真死。新执行者接管后,旧进程醒来写的任何东西 都会被拒收。用户不会看到两个回复交错,也不会看到同一句话出现两遍。代价是旧进程正在跑的 底层命令可能还在继续(引擎不杀进程树),所以「命令本身的副作用」不承诺恰好一次。
场景七:用户自己点了停止 停止优先于续跑。这场 run 以「已停止」收尾,不会再被接管。用户主动放弃的对话, 不会被系统偷偷捡起来继续跑。
场景八:多个副本、多个人同时点续跑 只有一个能抢到,其余的会收到「这场已经在跑了」。不会出现两个执行者同时写同一场对话。
场景九:刚崩完立刻点续跑 心跳还没过期,系统会认为「它可能还活着」,拒绝接管,提示稍后再试。宁可等几十秒, 也不冒两个执行者同时写的风险。
场景十:反复崩 一场 run 默认最多被接管 3 次(可配置)。超过之后不再提供续跑;开启自动巡检时, 巡检会把它标记为失败并清理流水账。用户重新发一条新消息即可。避免一个坏掉的场景 无限烧 token。
场景十一:崩溃时没人在场(可选能力,默认关闭,待点头) 打开后由后台巡检自动接管中断的 run,用户下次打开时可能已经恢复好了。代价是用户不在场时, 模型可能继续调用工具、继续花钱——所以这是个需要明确点头的开关。
场景十二:子代理跑到一半崩了 不承诺恢复子代理内部的推理过程。整个子代理调用按「工具中断」处理:告诉主模型这次委派 没拿到结果,它自己决定要不要重新委派。子代理之前已经写下的文件可能还在,系统不自动清理。
场景十三:崩溃前页面上已经出现半截字 这半截字没有进流水账,不算数。续跑后以流水账为准,用它替换气泡,而不是接在半截字后面。 用户可能看到已显示的文字「回退」一下,但最终历史是完整自洽的,不会出现「说过的话 在存档里找不到」。这一条描述的是契约行为;前端 reattach 交互本篇不做(§17 第 4 条)。
这一版明确不包含的:页面上还没有「中断/续跑」按钮,先把后端能力和契约做出来, 前端交互另立一轮;工具副作用不承诺恰好一次;子代理内部不恢复;半截正文会丢弃; 功能上线前产生的旧 run 没有流水账,救不回来;同一会话仍然一次只能跑一场, 恢复期间发新消息会被拒绝。
所以它解决的是:进程崩了,用户已完成的部分不丢、不用重讲,系统也不会为了「看起来 恢复成功」而偷偷重做那些可能有副作用的操作——拿不准的时候,如实告诉模型和用户 「这次中断了」。
19. 附录:LLM 输出到 runlive / draft 的字节级推导
2026-10-20 起 draft 已移除,现行见 doc/38。本节保留作历史诊断:它描述的是移除前 runlive 与 draft 两路的字节推导,不是现行写路径。现行定稿读 turn 里 root assistant 的累计。
本节是 byte-level 样例,不新增契约。目的:把「模型输出 → 两路存储」的每一步摊开, 让 runlive 与 draft 的对比有可逐字节核对的依据。示例 run id / message id 是 mock, model ref 取
deepseek/deepseek-flash。
19.1 场景
用户发「看看当前目录有什么文件」。主模型第一枪先说半句、再调 bash;工具返回后第二枪把答案说完。 这段经过:模型 chunk → Translator → AppendDelta / AppendFrame → Redis;其中 root 的 assistant 轮还要在整枪排干后写 run_journal。收尾时 draft 被读成 runlog 的 root 终稿, runlive 压 terminal。
19.2 模拟 LLM 输出(worker 看到的归一化 chunk 流)
这是 eino 归一化之后的 chunk,不是 provider 原始 SSE。对应关系:delta.content → Content、 delta.tool_calls → ToolCalls、尾部 usage → ResponseMeta.Usage。
第 1 枪(root)
C1 Content="" ReasoningContent="用户在问目录内容"
C2 Content="我先看" ReasoningContent=""
C3 Content="一下目录。\n\n" ReasoningContent=""
C4 ToolCalls=[{index:0, id:"call_00_Ls1", type:"function",
function:{name:"bash", arguments:""}}]
C5 ToolCalls=[{index:0, function:{arguments:"{\"command\":"}}]
C6 ToolCalls=[{index:0, function:{arguments:"\"ls -1\"}"}}]
C7 FinishReason="tool_calls"
Usage={prompt_tokens:1200, completion_tokens:40, total_tokens:1240}
—— 工具执行:bash "ls -1" → 输出 "a.txt\nb.txt\nc.txt\n" ——
第 2 枪(root,工具结果已回注)
C8 Content="目录里有 3 个文件:"
C9 Content="a.txt、b.txt、c.txt。"
C10 FinishReason="stop"
Usage={prompt_tokens:1300, completion_tokens:30, total_tokens:1330}
三个「不产生 delta 帧」的位置:
- C1 是思考内容;Translator 只读
Content(worker.go:78-100),ReasoningContent不进帧。 - C4–C6 是 tool_call 的参数分片;流式期间一帧不发,整枪排干后由
merged.ToolCalls合成一条。 - 每枪结尾的 finish / usage 本身也不产生 delta。
19.3 每个 chunk 被谁消费
| 模型输出 | worker 动作 | runlive 新增 | draft 变化 |
|---|---|---|---|
| C1 | Translator 返回 ok=false |
无 | 无 |
| C2 | AppendDelta |
第 2 帧 delta "我先看" |
+= "我先看" |
| C3 | AppendDelta |
第 3 帧 delta "一下目录。\n\n" |
+= "一下目录。\n\n" |
| C4–C6 | 流中只累积 merged.ToolCalls,不发帧 |
无 | 无 |
| C7(排干后) | ① writeJournalAssistant ② 发 usage 帧 ③ 逐条发 tool_call 帧 |
第 4 帧 usage、第 5 帧 tool_call |
无 |
| root 工具执行 | 包装层写 journal intent / result;ADK 产非流式 tool 事件 → 发 tool_result 帧 | 第 6 帧 tool_result |
无 |
| C8 | AppendDelta |
第 7 帧 delta |
+= "目录里有 3 个文件:" |
| C9 | AppendDelta |
第 8 帧 delta |
+= "a.txt、b.txt、c.txt。" |
| C10(排干后) | ① writeJournalAssistant(无 tool_calls)② 发 usage 帧 |
第 9 帧 usage |
无 |
| EndRun | 读 draft 定稿;压 terminal | 第 10 帧 terminal |
不变(随后整个键 DEL) |
两个顺序与直觉不同,代码里就是这样:
- usage 帧在 tool_call 帧之前:worker 先发账单(
worker.go:736-747),再循环merged.ToolCalls(worker.go:751-762)。 - journal 的 assistant 行在排干后立刻写,早于 usage / tool_call 两类帧(
worker.go:730)。
19.4 结果一:runlive(10 个 LIST 元素)
存储原样没有 eventOffset(写侧不填),下面的序号是 ReadFrames 按 LIST index+1 注入的:
1 {"kind":"start","agent":"","model":"","messageId":"m_01M5C73P8YQK2V3N4R5S6T7U8V"}
2 {"kind":"delta","agent":"","model":"deepseek/deepseek-flash","text":"我先看"}
3 {"kind":"delta","agent":"","model":"deepseek/deepseek-flash","text":"一下目录。\n\n"}
4 {"kind":"usage","agent":"","model":"deepseek/deepseek-flash","promptTokens":1200,"completionTokens":40,"reasoningTokens":12,"totalTokens":1240,"window":128000}
5 {"kind":"tool_call","agent":"","model":"deepseek/deepseek-flash","name":"bash","args":"{\"command\":\"ls -1\"}"}
6 {"kind":"tool_result","agent":"","model":"deepseek/deepseek-flash","name":"bash","output":"a.txt\nb.txt\nc.txt\n"}
7 {"kind":"delta","agent":"","model":"deepseek/deepseek-flash","text":"目录里有 3 个文件:"}
8 {"kind":"delta","agent":"","model":"deepseek/deepseek-flash","text":"a.txt、b.txt、c.txt。"}
9 {"kind":"usage","agent":"","model":"deepseek/deepseek-flash","promptTokens":1300,"completionTokens":30,"totalTokens":1330,"window":128000}
10 {"kind":"terminal","agent":"","model":"","status":"complete"}
形状说明:
- 第 1、10 帧是生命周期帧,不来自模型:
start由AcquireRun写,terminal由EndRun写。 - 第 6 帧来自工具结果事件(非流式,
Role=Tool),不是模型文本;它不产 delta。 - 第 9 帧没有
reasoningTokens:这一枪是 0,字段带omitempty被省略。 window是引擎的-compact-window配置值,不是模型真值。- usage 帧只在 provider 报了账单时发;账单缺失或三数全 0 就不发(
worker.go:721,736-747)。
19.5 结果二:draft(77 字节)
只有第 2、3、7、8 帧的 text 进入 draft,按顺序拼接:
我先看一下目录。
目录里有 3 个文件:a.txt、b.txt、c.txt。
推导式:
draft = C2.text + C3.text + C8.text + C9.text
= "我先看" + "一下目录。\n\n" + "目录里有 3 个文件:" + "a.txt、b.txt、c.txt。"
C1 的思考、C4–C6 的工具参数、第 6 帧的工具输出、两帧 usage 和 terminal,全都不进 draft。
19.6 对账:哪些帧进 draft
同一代执行内,等式只有一条:
draft = Σ (kind == "delta" AND agent == "") 的帧.text
在这个样例里:
- 进:第 2、3、7、8 帧。
- 不进:
start/usage/tool_call/tool_result/terminal;子代理的 delta(agent != "") 也不进(worker.go:880-917)。 - 因此不能拿整条 LIST 和
GET draft逐字节比;要比就按上面的过滤条件重拼。
redis-cli -p 6390 LRANGE tk:runlive:<run> 0 -1
redis-cli -p 6390 --raw GET tk:draft:<run>
# 按等式重拼后逐字节比(--raw GET 会补一个换行,先按 STRLEN 截)
redis-cli -p 6390 LRANGE tk:runlive:<run> 0 -1 \
| jq -j 'select(.kind=="delta" and .agent=="") | .text' > /tmp/from-frames.bin
n=$(redis-cli -p 6390 STRLEN tk:draft:<run>)
redis-cli -p 6390 --raw GET tk:draft:<run> | head -c "$n" > /tmp/draft.bin
cmp /tmp/draft.bin /tmp/from-frames.bin && echo SAMEjq -j 的关键是「不补分隔符、原样输出」,否则拼接结果会比 APPEND 多出换行。
19.7 两个边界
中途崩溃:如果进程在 C3 之后、C7 排干之前死掉——
- runlive 已有
start+ 2 条 delta,draft 已是「我先看一下目录。\n\n」; - 但 journal 里没有这一枪的 assistant 行(它要等排干才写);
- 续跑时
replayJournal的 Seed 不包含这半句,seedResume又用SET覆盖 draft, 所以 resume 帧和 draft 里都没有它。客户端看到过的这半句会被丢掉,模型重新生成。
这就是 at-most-once 的可见代价:帧和 draft 边到边写,journal 只在整枪排干后落一次账。
续跑之后:runlive 被重置为一帧 resume(text = Seed),draft 被 SET 成同一个 Seed; 之后的新 delta 继续 APPEND。等式变成:
draft = resume 帧.text + Σ (续跑后 kind == "delta" AND agent == "") 的帧.text
老帧全部被删,所以续跑后不能拿帧数或帧文本总量去和 draft 对账;唯一能跨代对齐的锚点 就是那条 resume 帧。
19.8 收尾时这两份数据去哪
- draft → 读出来写 runlog 的 root 终稿行(
store.go:316-324、store.go:579-596),随后 DEL。 - runlive → 压 terminal + 300s TTL,不参与落库;客户端见 terminal 后转拉 log。
- journal → 与 mh / runlog 的写入同一笔 PG 事务里删;mh 的 assistant/tool 行来自 每枪的 journal 重放 + 本轮 turn。
一句话:runlive 是过程,draft 是结果,journal 是崩溃时的重放原料;三者同源,但不等长。