tako 文档 GitHub

38 · 删除 tk:draft 键

性质:已落地(2026-10-20 验收并提交)。 施工台账:tmp/38-删除draft键/(不入库)。复查结束前先留着。 一句话:draft 的两个职责——定稿正文的缓存、run 活着的哨兵——分别已经有 turn 和 runepoch 两个更准确的承载者;删掉它,Redis 临时态从三键收敛为 tk:runlive + tk:runepoch 两键, 定稿路径不再读 Redis。 关联:doc/30(崩溃续跑,draft 的出生地)、19v6-03(存储形态)、19v6-01(帧契约)、 doc/31(SSE,读 runlive)。doc/30 第 8.3 节和第 19 节里的旧 draft 设计已标明「现行见 doc/38」,原文留作历史诊断。 验收(隔离库 tako_38、Redis 6390/9、端口 8938):

1. 先看一场 run 的完整链路

用户发一句话,服务端做这些事(箭头 = 数据流向):

  1. 用户 → POST /api/runs。
  2. 引擎在 PG 事务里抢闸(runs 插入 running 行 + 部分唯一索引)、写 user 行 (run_model_messages seq=1、runlog_entries),同时在 Redis 出生三个键: tk:runlive:<run>(帧流,压入 start 帧)、tk:draft:<run>(空字符串)、 tk:runepoch:<run>(接管令牌,出生值 1),三者同一租约 TTL。
  3. 模型流 → worker.drain:每个 chunk 先过 translator 取 chunk.Content,然后对 root 调 AppendDelta。这条 Lua 做两件事:RPUSH 一帧 delta 到 tk:runlive, APPEND 同一段文本到 tk:draft。
  4. 一枪排干后,worker 把合并后的 merged.Content 追加到内存里的 turn;如果模型要调工具, 工具结果也进 turn,然后发下一枪。同一枪结束时还把 merged.Content 写进 PG 的 run_journal(续跑账本)。
  5. 用户 → GET /frames 轮询 tk:runlive,看到 start / delta / tool_call / tool_result / terminal。
  6. run 结束 → EndRun。今天它在开 PG 事务之前先 GET tk:draft 拿全文;然后在同一笔 PG 事务里放闸、把 turn 投影成 run_model_messages、把 draft 写成 runlog_entries 的 root 终稿行;commit 后再压 terminal、删 tk:draft / tk:runepoch。
  7. 用户 → GET /log 看到定稿的 assistant 全文。

同一段回复正文,在这条链路里出现了三次:

§4 会证明 draft 与 turn 逐字节同源;§2 说明为什么保留 turn、删掉 draft。

2. 病灶:把缓存当成了真源

2.1 故事一:模型写完了,Redis 恰好不可用

一场 3000 字的回答,最后一段 delta 已经推给客户端。EndRun 开始收尾,第一件事是 GET tk:draft。这时 Redis 正在主从切换 / 重启 / 网络抖动,GET 返回连接错误。EndRun 在开 PG 事务之前就返回错误;worker 的 defer 只能记日志。PG 里的 run 仍是 running,租约 30 秒后过期。读侧把它判成 interrupted,下一次 POST 清扫成 error。

用户刚才明明在屏幕上看到了完整回答;刷新页面后,/log 里没有这条 assistant 行,气泡变成失败。 模型已经写完,PG 也健康,但这场回答永远不会进 runlog。

2.2 故事二:draft 被逐出,活 run 被缓存判死

Redis 配了 maxmemory,在内存压力下逐出了 tk:draft。下一次 AppendDelta 的 Lua 第一句是 EXISTS draft,返回 0,脚本直接返回 0;worker 把 !live 当成「run 已被判死」,停止推流。 PG 里的租约还在,watchdog 还在续约,但客户端再也收不到 delta。 一个缓存键的消失,被当成了执行者的死亡。

还有更安静的一种:如果 draft 在最后一枪之后、EndRun 之前消失(TTL 被误设、人工删除、 故障转移),EndRun 会读到空串,然后在 complete 状态下写一条 text='' 的 assistant 行—— complete 但空回复,且没有任何错误日志。

2.3 不做会怎样

3. draft 到底是什么(操作定义)

不是比喻,逐条操作:

所以它有两个职责:

职责 谁在用 今天怎么用
定稿正文 EndRun GET 全文 → runlog root assistant 行
活判哨兵 AppendDelta / AppendFrame EXISTS = 0 → 停流

它不是锁:锁是 PG runs 的活行 + one_live_run_per_session 部分唯一索引;活判的权威是 PG lease_until;防旧执行者的是 PG lease_epoch 与 Redis runepoch 的比对。这些在 doc/30 里已经是现行设计。

4. 为什么可以删:逐字节等价证明

4.1 记号

4.2 归纳

设 D_i 为第 i 枪结束后的 draft,T_i 为此时 turn 中所有 root assistant 条目的 Text 拼接。

EndRun 里的 pending[""] 正是 Σ root assistant turn Text(store.go:521-529 的循环), 也就是 T_n。因此把 EndRun 的正文来源从 GET draft 换成 pending[""],写入 runlog 的 字节完全相同。

4.3 续跑也成立

4.4 边界

4.5 哨兵等价

EXISTS draft 与 runepoch == epoch 的同生同灭关系:

反过来,epoch 还在而 draft 不在的唯一正常场景不存在;epoch 不在而 draft 在也不可能(同一 Lua)。 所以 runepoch == epoch 是比 EXISTS draft 更准确的判据:它回答的是「我还是不是这一代的 执行者」,而不是「一个缓存键还在不在」。

5. 目标机制

5.1 键空间

键 类型 谁写 谁读 生命周期
tk:runlive:<run> LIST acquire / append / end / seed frames / stream 出生带 lease TTL;terminal 后 300s TTL;TTL 到 = gone
tk:runepoch:<run> STRING acquire / seed append / renew 出生带 lease TTL;续约刷新;end 删除;TTL 到 = 写口拒收

tk:draft:<run> 不再存在。

5.2 各动作

5.3 端到端链路(删除后)

用户 → POST → PG 抢闸 + Redis 两键出生 → 模型流 → drain → RPUSH runlive(每 delta)→ 客户端 frames → 每枪 turn 追加 → EndRun → PG 事务(pending[""] → runlog;turn → mh)→ commit → Redis terminal + DEL epoch → 客户端 log。

箭头每一环都能点名;没有一环需要 draft。

5.4 删除后的故障行为

5.5 命名:拒写不等于 run 死了

删掉 draft 后,append 返回 0 的唯一原因是 runepoch 缺失或与本执行者 epoch 不等。它回答的是 「本执行者还是不是当前一代」,不是「run 还在不在」:run 可能已被接管、已收尾,也可能只是令牌键 到期/被逐出而 PG 租约仍有效。旧名字把这层意思说错了:

位置 今天 改为 为什么
AppendDelta / AppendFrame 的命名返回值 ok bool accepted bool 值 = 本代令牌接受这一帧写进 runlive
drain 的局部与返回 live bool / !live accepted bool / !accepted 同上;不再是「run 活不活」
worker 四处帧写出口的局部 live accepted tool_result / drain / usage / tool_call
相关注释 「run 判死」「liveness 由 draft 承载」 「本执行者已不是当前一代」「令牌缺失/不等」 删掉 draft 时代语言

现状(2026-10-21):AppendDelta 与 AppendFrame 已合并为唯一的 AppendFrame—— 两个写口的 Lua 本就逐字节相同(同一段「比对 runepoch → RPUSH → 返 LLEN」), 所谓 root-only 护栏实际在调用方的 agent == "" 分支上,不在存储层。 上表是 doc/38 当时的改动记录(「今天」列指删除 draft 之前的状态,那时确实有两个写口), 保留原样作历史;现在只有一个帧写口,返回值仍是 accepted bool。

只改名字,不改行为:四个 !accepted 出口仍然直接 return,不把 status 改成 error(见 §5.4)。 search.go 的结果计数、product_api.go 的活 run 数、SessionStatus 的 liveRunId 是别的 「live」,不在本批范围。

6. 移除方式:一次性删除(2026-10-20 用户拍)

不做「先换正文源、再换哨兵」的过渡态,一次把 draft 从代码里删干净。交付分三拍, 但后两拍不改变运行时行为:

拍 改什么 活体证明什么
A1 一次性删除:EndRun 正文源改 pending[""];append 守卫只认 epoch;删 keyDraft、各 Lua 的 draft 读写、seedResume 的 seed 参数、注释与测试机械修复;live/ok 改名为 accepted 多枪 run 全程无 tk:draft:*;log 全文 == Σ root delta;kill -9 后 resume 仍 complete
A2 只加结构不变量测试(无 draft 键、seed 只留两键、租约过期仍挡住晚到 EndRun、Reset=2) 复用 A1 的活体;把「不能把 draft 加回来」写成测试
A3 文档收口 + 最终回归(正常多枪 + kill -9 resume) 代码、文档、索引同一套真源

为什么可以一把梭:§4 已证明 turn 与 draft 逐字节同源,§4.5 已证明 runepoch 与 draft 同生同灭。过渡态的唯一价值是「draft 还在,可逐字节对照」,代价是两个不可发布的中间状态 (A1 后 draft 只写不读;A2 后 APPEND 可能重建无 TTL 的孤儿键)。用户选择一次性,用单测 (EndRun 不读 Redis、错 epoch 仍拒绝)与活体对账替代过渡态对照。

回滚:A1 是单批代码回退,键布局回到三键;draft 是临时态,没有数据迁移。整个方案不动 PG 表结构。

7. 文档清单(A3)

8. 风险、边界、不做

8.1 风险

8.2 边界

8.3 不做

9. 被否决的替代方案

  1. 用 EXISTS runlive 当哨兵:runlive 在 terminal 后还有 300s TTL,这段时间 EXISTS=1, 旧执行者可以在收尾后继续追加帧;而且 runlive 是客户端消费的帧流,把它的存在性当判活依据 会把两个契约绑死。否决。
  2. EndRun 读 run_journal 拼正文:journal 在 PG,文本确实在,但多一次读、多一个失败面; turn 已经在 EndRun 的参数里(worker 的 defer 直接传),没有任何理由再读一次。否决。
  3. draft 只留作缓存(写但不读/不当哨兵):每个 delta 仍多一次 APPEND,多一个生命周期; 没有读者 = 死代码。否决。
  4. 配置开关(TAKO_DRAFT=on/off):两条代码路径都要测,且「要不要一个缓存」不是运维 选择,是结构决定。用户要的是安全、结构性的移除,不是可回退的影子模式。否决。
  5. 把 epoch 塞进 runlive 头/尾:eventOffset = LIST index + 1 是帧契约;头部加元素会让 所有游标偏移,客户端全部返工。否决。
  6. 把半截 delta 持久化到 journal 再 resume:那是另一个需求(at-least-once),需要每 delta 一次 PG 写或新的持久化层;doc/30 已裁 at-most-once。本方案不改变它。否决。
  7. 本批顺手把 append 拒写出口的 status 改成 error:能消除「令牌被逐出 + 租约仍有效 → 部分正文按 complete 落库」的边角,但「被逐出」到底是失败还是可接受的部分定稿,是产品判断, 牵扯前端对 complete 的信任。2026-10-20 用户拍:本批只改命名(§5.5),结局语义单独裁决。 否决(本批)。

10. 验收总览

拍 活体验收(第一行是跑着的命令) 单测
A1 多枪 run(tool_call 至少 1 帧)→ 全程 --scan --pattern 'tk:draft:*' 为空;log 的 root assistant 文本 == Σ kind=delta, agent="" 的 text;kill -9 后 resume → 首帧 kind=resume、terminal complete,仍无 draft 键 EndRun 正文来自 turn(不读 Redis);Redis 不可达时 PG 事务仍提交(ok=true,历史正确);错 epoch 仍拒绝;出生/追加/收尾/seed 后无 draft 键
A2 短 run 扫键(复用 A1 活体);SCAN tk:* 只有 runlive + runepoch 无第三类键;seed 只留两键;租约过期后带非空 turn 的 EndRun 仍 ok=false、无 assistant 行(Reset deleted=2 由 A1 修现有测试时覆盖)
A3 最终回归:正常多枪 + kill -9 resume 各一场;go test ./internal/runengine + go vet 绿;代码/脚本 grep draft = 0 —(回归)

活体验收使用隔离环境:PG 库 tako_38、Redis db9(redis://127.0.0.1:6390/9)、 独立 workspace、独立端口;不碰 dev 的 db0/tako 库,不调用 /api/dev/reset。 原因:Reset 的 SCAN tk:* 是库内全局的,共享 db0 会误删别的会话的活 run 键。

11. 一句话

draft 是 turn 的缓存、runepoch 的孪生哨兵;两个真身都已经在链路里。删掉缓存, 定稿只信 PG 里的 turn,帧流只认 runepoch。