ZiyaZhang
8ea5cdd894
146 篇 RFC 译文按 v4 基线（#348）重出：v4 模板+术语表、金标 few-shot、三段协议、切换行后处理；全量机械核对零异常（一处 task id 术语违规已修）。三篇超长 RFC（code-mode 已入，web-seam/ agent-scope/sandbox/cds-core 仍在长文档通道产出）随后补。
5.4 KiB
RFC：持久化 seed 边界以确保 fork 子会话回放正确路由
English | 中文
Status: implemented
问题
逐会话快照回放 RFC 让快照层表达了嵌套 agent（智能体）的形状：一个父会话加上每个进程内 subagent 各一份已录制的日志，各自作为独立脚本回放、以调用方会话为键。该 RFC 指出（§ Scope 末尾条目）fork 快照是「一个平凡的后续补充，不是键控方案的缺口」。这对 fork 子会话而言是错的——问题不在键控，而在脚本推导。
subagent 脚本由 deriveReplayScript 从已录制的会话日志推导：它按 (turn, step) 对日志中的 assistant/chunk 事件分组，每次 stream() 调用对应一条回放条目。对 spawn 子会话而言这是正确的，因为其日志只包含自身的模型调用。
fork 子会话不同。fork 后端用父日志的一段平衡的已完成轮次前缀（dsh-subagent-inprocess）来播种子会话，而该 seed 会成为子会话持久化的 log（Session 构造函数将 seed 复制进 this.log）。因此 fork 子会话的 .jsonl 以父会话的事件开头——包括父会话的 assistant/chunk 事件——之后才是子会话自身的轮次。
从 fork 子会话的完整日志推导脚本，会把父会话的已录制响应当作子会话的模型调用来回放：实际运行的 fork 子会话第一次调用 stream() 时，会收到父会话的第一段 chunk 序列而非自身的。目前已录制的场景全部是 spawn，所以这从未触发——但 fork 快照会静默地错误路由，恰好属于快照层存在的意义所要捕获的那类 bug。
决策
记录会话继承前缀的结束位置，将其持久化，并让回放 harness 仅从子会话自身的事件推导脚本。
1. 会话头部的 seedLength
SessionHeader 新增可选字段 seedLength: number——表示有多少前导事件是通过 seed 继承而来、而非本会话产生的。fork 后端在创建子会话时设置它（= 播种前缀的长度）；全新的 spawn 子会话不设置（等同于 0）。它通过 CreateSessionOptions.meta（及 CreateAgentOptions.meta）传递，在 SessionStore.prepare 中设置。
seedLength 是显式的，绝不从 seed.length 推断。重建（resume/load）时用会话的完整已存储日志作为 seed，此时 seed.length 是全长而非原始边界——resume 路径改为从加载的 header 中取回持久化的 seedLength。（形状与 createdAt 相同：重建时显式保留，而非重新默认为当前时间。）
2. 两个持久化后端均完整往返
- JSONL：header 行上的
seedLength字段（toHeaderLine/fromHeaderLine）。 - SQLite：
sessions表上的seed_length列。
包含 seed_length、source_event_seqs 和 surface_op 的 SQLite 布局为 schema version 4。更早的 version 3 布局存在歧义，因此在预发布策略下，所有非当前 user_version 均直接拒绝，不做迁移。
3. 回放从边界之后推导子会话脚本
dsh-llm-replay 的 parseSessionHeader 现在也读取 seedLength（缺失则为 0），loadSessionScripts 从 parseSessionLog(text).slice(seedLength) 推导子会话条目——即边界及之后的事件，也就是子会话自身的模型调用。对 spawn 子会话而言 seedLength 为 0，此操作是空操作，spawn 场景逐字节不变。
这关闭了路由正确性的缺口，两个已录制的 fork 场景对其进行端到端验证——见 Record fork and mixed spawn+fork snapshot scenarios。
曾考虑的替代方案
- 在
llm-replay中启发式推导边界（播种前缀是连续的父事件，止于子会话第一条user/message之前的最后一个turn/end）。否决：在测试 harness 中用脆弱的启发式重新推导一个生产者已经知道的事实。在源头（fork 后端）持久化边界，是「在包（package）seam 处显式优于隐式」这条规则跨越持久化边界的应用——子会话 fixture（测试前置数据）的读取者永远不需要重建继承在哪里结束。 - 固定格式版本而不递增（事件日志使用的
SESSION_FORMAT_VERSION = 0「不稳定」姿态）。对 SQLite 表布局否决：SCHEMA_VERSION是单调递增并拒绝旧版的旋钮（一组小的、值得区分的修订），与事件词汇表的version不同。新增列正是它所版本化的那种破坏性表变更，因此需要递增。
后果
- core 与两个后端新增一个持久化 header 字段；核心数据结构目录（
persistence.md）在同一变更中更新（其SessionHeader/CreateSessionOptions的type-equiv块）。 - 既有的 schema v2 SQLite 数据库在打开时被拒绝（预发布阶段无用户数据）。
- spawn 回放不变（
seedLength为 0）。fork 回放现在将子会话路由到自身的脚本；由llm-replay测试中的一个回归用例覆盖（一个子会话 fixture，其播种前缀包含父会话的 chunk——推导出的子会话脚本必须排除它，不做 slice 时该用例为红）以及一个持久化往返测试（两个后端，通过共享的 coordinator 契约）。