tako 文档 GitHub

30 · 崩溃续跑(doc/16 #7c)

性质:施工中(2026-10-21):A1–A5 已落地并验收;A6 已由客户端触发式恢复取代(2026-10-21 用户裁:server 自动巡检不做);A8 前端 reattach 已落地并验收;A7 回归收口已跑(矩阵重放全过,doc 回填随本批做)。 本篇是 #7c「在途轮次崩溃续跑」的设计真源;施工台账在 tmp/30-崩溃续跑/(不入库)。 已完成的活体验收:A4a r_01M57ESWS6M2FESYMGWQ35NDWK(psql 造终稿 → resume 202 → 首帧 resume → 不调模型直接定稿);A4b r_01M57ETJGQW7W5X380SC5N1J12(tool_result 后 kill -9 → resume → 3554 条新 delta → complete);A5 r_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、机器重启都行)。接下来发生的事,按今天的代码逐步演:

  1. 进程里的 goroutine 没了,turn 这个内存切片——本轮所有 assistant 消息、工具结果—— 跟着没了。
  2. Redis 的 tk:runlive:<run>(帧流)和 tk:runepoch:<run>(写口令牌)没人续租, 30 秒后(-lease-ttl 默认值)一起蒸发(2026-10-20 起 tk:draft 已移除,见 doc/38)。
  3. 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 根本不会执行。
  4. 用户的页面每 400ms 拉一次 GET /api/runs/{id}/frames。某一次开始返回 {"frames":[],"nextOffset":N,"status":"gone"},因为 runlive 键没了。 前端按既有收口逻辑转去拉 GET /api/sessions/{id}/log,只看到自己发的那句话, 没有 assistant 行,于是把气泡标成失败。
  5. 用户重新发一遍同样的请求。新 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)

证据在代码里,不在印象里:

仓库里唯一一处写「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。

所以「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),而不是新增一个存储状态。为什么不用新状态:

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 机制,但它的落点不在崩溃路径上:

所以 #7c 不接 eino 的 resume,自己落一份步骤账本。账本只记「模型见过什么」, 不试图复制 ADK 的内部状态;续跑时把账本重放成一份普通的模型输入,再走既有的 prepareInput / agent 循环。这个分界让恢复逻辑不依赖 eino 版本,也不要求 图能从中断点原地继续。

4. 目标与不变量

目标(按优先级):

  1. 进程崩溃后,同一个 run 可以被另一个进程(或另一个副本)接上,已完成的工具调用不重跑。
  2. 接管后的模型输入包含崩溃前模型已经见过的 assistant / tool 消息; 结果未知的工具调用有明确的「中断」文本,绝不自动重跑。
  3. 旧进程即使还活着(分区、GC 停顿、租约误判),它的任何写入都不能污染接管后的 run。
  4. 同一 run 的 runId 不变;会话闸在续跑窗口内继续占着,避免同一会话并行两轮。
  5. 所有恢复判定都在 PG / Redis 的持久状态上做,不依赖进程内注册表; 多副本下两个续跑者只能有一个赢。

不变量:

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 端到端业务链路(谁 → 谁 → 谁)

  1. 用户发消息 → POST /api/runs → AcquireRun 抢闸、落 user 行、建 Redis 两键 → go worker.Run(..., epoch=1)。
  2. 模型返回一枪 → worker 把合并后的 assistant 消息写进 run_journal(root-only)→ 发 tool_call 帧。
  3. eino ToolsNode 调用工具 → 工具包装层先写 tool_call 账本行 → 执行工具 → 再写 tool_result 账本行 → 结果回注模型。
  4. 进程崩溃 → 租约过期 → 用户/前端/巡检者发现 GET /api/runs/{id} 是 interrupted。
  5. 有人 POST /api/runs/{id}/resume → ClaimResume 在 PG 里锁行、检查、lease_epoch+1、 读账本 → 同一笔之后(Redis 单条 Lua)重置 runlive 并写入 resume 帧、 把 runepoch 设成新代。定稿不写 Redis。
  6. 新 worker 启动 → replayJournal 把账本还原成 ModelMessage / turn → 最后一枪已是终稿就直接 EndRun;否则把重放行接在会话历史后面,走既有 prepareInput / 折叠 / agent 循环。
  7. 续跑后的终稿照旧由 EndRun 写 run_model_messages / runlog_entries, 账本在同一笔事务里删掉。
  8. 用户轮询 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:

  1. 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)。
  2. tool_call 行:工具包装层在调用底层工具之前同步写。内容: tool_call_id = compose.GetToolCallID(ctx)、tool_name = inner.Info(ctx).Name、 args = 模型原始 arguments 字符串。
  3. 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 的消息,判定点有两层:

root 调用的工具——get_time、文件工具(含 read_media_file、read_pdf_text)、bash、memory、 search_history、web_search、MCP 工具(mcp__…)、delegationTool——全部记账。

为什么这样切:

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 为什么租约本身不够(具体失败戏)

假设只用今天的租约做接管:

  1. 进程 P1 的 run R 卡住(GC、网络分区、机器假死),watchdog 续不上,lease_until 过期。
  2. 进程 P2 看到过期,抢到 R:把 lease_until 续成未来的时间,开始续跑。
  3. P1 突然恢复。它的 watchdog 下一拍做 RenewLease:status='running' AND lease_until > now() ——P2 刚续过,这个条件成立。P1 以为闸还是自己的。
  4. 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 1
写点 新增条件 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 = 租约

一个旧 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
}

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、PEXPIRE runlive。定稿正文不进 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

三个决定:

  1. 旧 runlive 整个丢掉,不追加。 崩溃前的帧里可能有半截 delta(模型说到一半被杀), 这些文本从未进入账本。把它们留在新流里,用户会看到「模型说过但账本没有」的字, 续跑后的定稿却对不上。账本是权威:resume 帧的 text = 账本里所有 root assistant 正文按顺序拼接,前端看到 resume 就用它替换气泡,而不是追加。
  2. resume 帧是新流的第一帧。 前端(或 curl)续跑后从 eventOffset=0 拉, 第一帧就是它;eventOffset 从头开始,因为这是一个新的生成段。旧的半截流已经 没有阅读价值,重新编号比维护跨段的 offset 更简单。
  3. draft 用 SET 覆盖,不 APPEND。 之后新模型的 delta 照旧追加到它后面; EndRun complete 时 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 之后没有并发写者):

  1. 直接定稿分支:账本规范重放后,最后一个 assistant 消息没有 tool_calls。 说明模型在这一轮已经说完了终稿,崩溃只发生在「写终稿行」之前。此时不调模型, turn = 重放条目,status = complete,直接走 defer 的 EndRun。 EndRun 从 turn 里 root assistant 的累计拿全文,写 runlog 终稿行。 为什么必须这样:再调一次模型会把「已经有终稿」的对话再喂一遍,模型会再答一遍, 产生重复文本和额外 token;而且正常 agent 循环在「无 tool_calls 的 assistant」处 就结束了,续跑应该复现这个终点。
  2. 继续分支:最后一个 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 的:

算法(纯函数,单测直测):

  1. 第一遍扫 assistant 行:解析 tool_calls JSON,记下每个 call id 属于哪条 assistant 行;记下 assistant 行的顺序。
  2. 第二遍按 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,停止重放;它之后的行一律忽略(正常情况下也不该有; 有就是旧账本/异常写入,记日志不参与模型输入)。
  3. 输出坐标:每个输出的 ModelMessage.Seq 从 2 递增;RunID 固定当前 run。 user 行是 mh 里已有的 seq=1,不在账本里。
  4. turn 的顺序:assistant 条目后紧跟它名下的 tool 条目,与正常 run 的 「assistant 轮 → 工具结果轮」同形。并行工具的真实完成顺序不保留,按 call 顺序 规范化;runlog 的工具行也按这个顺序落,call id 保证配对不错。
  5. 合成文本(精确常量,单测逐字节断言):
错误:工具调用在执行中被进程中断,没有拿到结果;引擎不会自动重跑这次调用。需要的话请重新发起。

这个文本与 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 全部不变。于是:

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..."}

对旧前端的兼容性:它只检查 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}

10.5 resume 帧

Frame 复用现有结构(types.go:46-62),新 kind:

{"eventOffset":1,"kind":"resume","agent":"","model":"","text":"<账本里 root assistant 正文的拼接>"}

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 行的锁/条件决定:

这就是产品上的取舍:同一会话里,新消息优先于旧 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 永远能停,不管接管是否刚发生;这也是我们把 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 的锁只覆盖账本插入的那一小段事务,不覆盖工具执行本身。所以存在这个窗口:

  1. 旧 worker 写了 tool_call intent,开始执行一个 30 秒的 bash;
  2. 租约过期,接管者 claim 成功,读账本时看到 intent、没有 result;
  3. 旧 bash 执行完,包装层写 result —— epoch 已变,插入失败;
  4. 接管者的模型收到合成的「已中断」结果,不知道真实的 bash 结果;
  5. 如果 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 足够验收,但真实产品里用户不一定会在窗口内打开页面。 加一个可选的巡检器:

默认关闭的理由:自动续跑会在用户没发话的情况下花 token、执行工具(即使有「不自动 重跑」的保护,模型可能继续调用别的工具)。这属于产品决策,不塞默认。若用户希望 「崩溃后无感恢复」,把它开成默认值是一次单独的决定,不由实现者顺手定。

一个行为变化要写清楚:开着自动续跑时,崩溃后用户直接发新消息,可能先被巡检器 claim,拿 409 session_busy。前端应按既有 409 语义处理(等本轮收口再补投), 或者关掉自动续跑、手动决定。

13. 施工分期

每个 action 都遵守 AGENTS.md 的「写完就停、等验收、不自动 commit」。契约拍的第一行 必须是打一个正在跑的东西(curl / kill -9 / psql),不能是测试运行器。 详细的 curl 命令与期望字节在 tmp/30-崩溃续跑/todos.md,这里只给每拍的范围与目的。

A1 · 读侧状态面

A2 · 账本底座

A3 · 令牌围栏

A4a · claim + 种子 + 直接定稿

A4b · 继续调模型

A5 · 合成中断结果 + 真实崩溃端到端

A6 · 自动巡检

A7 · 回归与收口

状态(2026-10-21,随 A8 一起做):go test -count=1 ./internal/runengine 25.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),后端一行不改。

14. 验收

14.1 环境

14.2 主证(A5)

  1. 起引擎(短租约、workspace 指向临时目录)。
  2. POST /api/runs,prompt 明确要求先跑 bash:sh -c 'echo tick >> ticks.txt; sleep 20; echo done',再报告文件内容。
  3. 轮询 frames 直到看到 tool_call 帧(name=bash,args 含 ticks.txt), 确认 ticks.txt 已有一行 tick。
  4. kill -9 <自己起的 PID>;等 4s(> lease TTL)。
  5. curl GET /api/runs/{id}:status:"interrupted"、resumable:true、resumeCount:0。
  6. curl POST /api/runs/{id}/resume:202、 {"runId":"...","status":"running","resumeCount":1}。
  7. curl GET /api/runs/{id}/frames?eventOffset=0:第一帧 kind:"resume", text = 崩溃前 root 正文;随后出现新的 delta(模型基于「已中断」继续)。
  8. 等到 terminal complete;curl GET /api/sessions/{id}/log:assistant 终稿行在, tool_call/tool_result 行在,result 文本是 §9.2 的中断文本(不是 bash 的真实输出)。
  9. wc -l ticks.txt = 1(没有自动重跑);GET /api/dev/runs/{id}/journal rows:[]。

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. 残余风险与非目标

残余风险(接受并写清):

  1. 副作用不是恰好一次。工具可能执行了但结果没落账;续跑给模型的是「已中断」, 不是真实结果。是否重做由用户/模型决定。
  2. 跨接管边界的工具会继续跑。引擎不等待在途工具,也不杀进程树;kill -9 后 bash 的子进程可能继续,接管后的模型不知道它的最终副作用。
  3. 子代理内部不恢复。在途委派按普通工具中断处理;子代理已写的文件可能还在, 但它的推理链和中间消息丢了。
  4. 未记账的半截正文丢弃。崩溃发生在 drain 与 assistant 账本行之间时, 用户可能已经看到半截字,续跑的 resume 帧会把它替换成账本里的正文。
  5. 折叠中间态重算。崩溃前做过的摘要不持久,续跑可能重复花摘要 token。
  6. 失败的种子消耗一次 resume 次数。epoch 不回退;-resume-max 3 下连续三次 Redis 失败会让 run 耗尽。
  7. 账本写入成本。每次模型消息 1 笔 PG 写、每次工具 2 笔 PG 写;工具调用多的 run 会更慢。账本在终态删除,不长期增长。
  8. 自动续跑会花 token。默认关闭;开启后崩溃恢复不需要用户在场,但也可能在用户 不知情时继续执行工具。
  9. 旧前端没有续跑交互。它会把 interrupted 当失败;resume 帧被忽略。 已解决(2026-10-21,A8):前端已接上——interrupted 气泡显示琥珀提示 +「继续这一轮」, resume 帧按「整段正文」替换渲染,三个 409 分开处置(§13 A8)。新形态的残余风险: 用户不在场时那场 run 一直中断着,没人替它续——这是「不做 server 巡检」裁断的直接后果, 按用户在场时的可见性取舍,不是缺陷。
  10. 特性上线前启动的 run 没有账本。它们崩溃后只能从 user 消息重来;没有追溯恢复。
  11. 单会话仍是一活 run。续跑窗口内新消息可能 409 session_busy; 同一会话不能并行恢复两轮。
  12. 鉴权不在本篇。resume 端点和现有端点一样只绑本地/单用户;多租户见 doc/28。

明确不做:

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 里有同样的清单):

  1. 自动续跑默认关闭(推荐):-auto-resume 默认 false,手动 resume 先落地。 如果希望崩溃后无感恢复,改成默认 true 是一次单独产品决定。 2026-10-21 已拍:不做 server 自动巡检;恢复采用「延迟处理—客户端触发」—— 前端在 reconcile 中看到 lastRunStatus=interrupted(配合 lastRunId)即调 POST /resume,claim 的 CAS 天然幂等,多 tab/刷新并发只有一个赢。将来 IM/cron 入口 (doc/16 #8b)没有 client 可触发,若需无感恢复,作为该入口的装配决策重开(§12 留档)。 交互形态 2026-10-21 已拍:显式「继续这一轮」按钮(不做「检测后自动恢复」)。 实装见 §13 A8。
  2. A4 拆分:A4a(claim + 种子 + 直接定稿)和 A4b(继续调模型)分开验收; A4 整体会超过 80 行目标,拆开后每拍仍有 100+ 行,但各自有一个确定的验收脚本。
  3. 续跑上限:-resume-max 默认 3。上限越大,越能扛连续崩溃,也越可能反复烧 token; 3 是「两次完整重试 + 一次余量」的经验值,可按用户偏好改。
  4. 前端 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 帧」的位置:

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)

两个顺序与直觉不同,代码里就是这样:

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"}

形状说明:

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

在这个样例里:

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 SAME

jq -j 的关键是「不补分隔符、原样输出」,否则拼接结果会比 APPEND 多出换行。

19.7 两个边界

中途崩溃:如果进程在 C3 之后、C7 排干之前死掉——

这就是 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 收尾时这两份数据去哪

一句话:runlive 是过程,draft 是结果,journal 是崩溃时的重放原料;三者同源,但不等长。