会话 —— 从会话树到持久运行时
M09 讲压缩时,一句话带过:压缩结果是挂在 Session Tree 上的一条 entry。
这一章把那个词拆开。会话到底怎么存、怎么读回来、怎么分叉?
而且这一章有个特殊之处:它要讲两代实现。
coding-agent 里有一套跑了几年的 SessionManager,一个会话一个 JSONL 文件,
树结构存在文件里。packages/durable 里另有一套,把会话变成了"提交账本"。
两套代码同时存在于 v1.4 的快照里,前者被 CLI 使用,后者是可持久化运行时。 它们的差别不是代码风格,是对同一个问题的两种回答。
零、读这章之前,你需要先知道一件事
两代会话:这个仓库里"会话"被实现了两次——一是 coding-agent 的 JSONL 树
(能回退、能分支),二是 durable 的持久运行时(能崩溃续跑)。两者互不依赖。
没有它会怎样:在 durable 里找 /tree,或者在 coding-agent 里找"任务恢复"——
两边都找不到,然后怀疑自己看漏了文件。它们真的不在一起。
本书哪里用到:§二 那张决策表;第二代的细节在 M11。
一、一个数组的两个问题
前九章我们反复跟 context.messages 打交道:一个数组,按顺序放着这一轮要发给模型的消息。
进程退出,数组就没了。下次启动,它从哪来?
这引出本章的主问题:会话数据怎么存。拆开是两个正交的子问题:
| 维度 | 问的是 | 常见选择 |
|---|---|---|
| 介质 | 数据落在什么载体上 | 数据库表 / 本地文件 / 内存 |
| 结构 | 数据的逻辑形态 | 线性数组 / 树 / 追加日志 |
两个维度互不绑定。"用 MySQL 存一个线性数组"和"用 JSONL 文件存一棵树"都成立。 混在一起谈,后面全糊。
Pi 的两代实现刚好落在这个象限的两头:
| 介质 | 结构 | |
|---|---|---|
第一代 SessionManager |
本地 JSONL 文件 | 树(每条 entry 带 parentId) |
第二代 durable |
可插拔 Storage | 线性账本(每条 entry 带 head 标记) |
1.1 三个必须
判断一个会话存储设计好不好,用三个问题量:
- 回退不能丢数据。你嫌 Agent 答得不好,想退回上一轮重问。 如果实现方式是"删掉后面的消息",那另一条分支就永久没了。
- 崩溃不能丢半截。第 3 轮工具调用跑到一半进程被 kill。 重启后,这轮要么能续上,要么能干净地判定失败——不能留个既不算成功也不算失败的幽灵状态。
- 换后端不能换语义。今天存文件,明天想存 SQLite 或浏览器 IndexedDB, 上层代码不该跟着改。
第一代满足第 1 条,第 2、3 条只满足一半。第二代是冲着后两条去的——这就是本章的叙事线。
1.2 本章读法
- 二到六节:
session-manager.ts(2,029 行)——树、JSONL、恢复、分叉。 - 第七节:这棵树在什么场景下撑不住,全章转折点。
- 八到十节:
packages/durable/src/session/——账本、head、组提交。
先给结论,省得你读到一半猜:
会话搬到独立运行时,不是因为文件不好用,是因为"一次追加"承载的语义变多了。 第一代的追加 = 写一行 JSON。第二代的追加 = 一次事务, 里面可能同时有 entry、文档状态、任务检查点、待处理的输入队列。
二、第一代:一棵只追加的树
两代会话都还活着,先给一张选型表——不然后面两章你会以为是新旧版本:
| 你要的是 | 第一代(coding-agent 的 JSONL 树) |
第二代(durable 的持久运行时) |
|---|---|---|
查历史、回退、分支(/tree) |
是 | 否 |
| 崩溃后从断点续跑 | 否 | 是 |
| 一次追加一行、人能直接读 | 是 | 是(marker + sidecar) |
| 换成外部存储/多进程共享 | 否 | 是 |
本书用两章写它们,就是因为它们是两套东西,不是新旧版本。 本章写第一代(§二到§七),M11 写第二代。
先看结构。会话树的每个节点叫 entry。
2.1 四个共同字段
session-manager.ts:57-62:
export interface SessionEntryBase { type: string; id: string; parentId: string | null; timestamp: string;}所有 entry 都长这样。type 是判别式,id 是自己,parentId 是父亲。
parentId 指向父亲、而不是持有一份 children 数组——这个选择是整棵树成立的前提,
后面 2.3 单独讲。
2.2 十一种 entry
session-manager.ts:183-194 把十一种 entry 联合成一个类型。按职责分三组:
| 类型 | 主要载荷 | 进不进模型上下文 |
|---|---|---|
message |
message: AgentMessage |
进 |
thinking_level_change |
thinkingLevel |
不进 |
model_change |
provider + modelId |
不进 |
usage |
kind / usage / note? |
不进 |
compaction |
summary / firstKeptEntryId |
进(摘要 + 保留段) |
branch_summary |
fromId / summary |
进 |
custom_message |
customType / content / display |
进 |
custom |
customType / data? |
不进 |
context_edit |
targetId / replacement |
改写别的 entry |
label |
targetId / label? |
不进 |
session_info |
name? |
不进 |
注意第三列:树上绝大部分节点不产生消息。会话文件是"对话记录 + 运行时状态 + 用户标注"的混合体,不是单纯的 messages 数组。这个隐含成本第七节再算。
其中 custom 与 custom_message 的区分值得记一笔(:118-165):
custom:扩展自己的状态。重载后靠customType扫出来重建,不进上下文。custom_message:扩展要"说给模型听"的内容,进上下文,由buildSessionContext()转成一条 user 消息。
注释里写得很直白:一个给代码看,一个给模型看。
2.3 认父不认子
为什么 parentId 存父亲,不存 children: string[]?
因为要 append-only。
如果每个节点持有 children 数组,那么"给某个节点加一个孩子"就是修改这个节点—— 它已经写在文件的第 300 行了,怎么改?只能重写整个文件。
反过来,新节点自己记住父亲是谁,追加就永远是"在文件末尾加一行,谁也碰不到"。 这两个动作的成本差了一个数量级:
| 操作 | 认父不认子 | 认子不认父 |
|---|---|---|
| 追加一个节点 | 写 1 行 | 改父节点 + 写 1 行(父节点可能在文件任意位置) |
| 找父亲 | 一次 map 查表 | 一次 map 查表 |
| 找孩子的孩子 | 全表扫一遍 | 顺着数组走 |
| 树结构一致性 | 只要父存在就对 | 双向指针必须同时改,崩溃就断链 |
代价是"往下走"变慢。第一代的答案是:根本不需要往下走。 上下文永远是从当前叶子往根回溯,方向是单侧的。
一条很硬的推理链,第一代的每个设计都从这里长出来:
append-only → 只能改末尾 → 新节点自带指针 → 指针只能指父亲 → 遍历只能逆着来。
2.4 树上长一次
抽象讲"树"没人看得懂。用一个六节点的小会话:
1. 切模型到你想要的(model_change)2. 你问:"salt 校验为什么失败?"3. Agent 调 read 读 auth.ts(assistant + toolResult)4. Agent 答:"第 23 行没编码"5. 你不满意,回退到 26. 换个问法:"先看 hash 函数"节点按顺序长成这样(parentId 用上一行的 id 简写):
e1 model_change parentId: null └ e2 user parentId: e1 "salt 校验为什么失败?" └ e3 assistant parentId: e2 toolCall: read("auth.ts") └ e4 toolResult parentId: e3 <auth.ts 内容> └ e5 assistant parentId: e4 "第 23 行没编码" └ e6 user parentId: e2 "先看 hash 函数" ← 回退后新增看 e6:它的父亲是 e2,不是 e5。
这就是分叉的全部机制——没有删除,没有修改,只是新节点的父亲指到了别处。
e3、e4、e5 仍然完整地躺在文件里,随时可以走回去。
e6 之后如果继续对话,e7 的父亲是 e6,e7 追加在文件末尾。
于是文件里的物理顺序是 e1 e2 e3 e4 e5 e6 e7,
逻辑上的树有两条分支。文件顺序 ≠ 树顺序,这是理解会话文件的关键。
三、JSONL:树怎么写进文件
3.1 文件在哪
session-manager.ts:589-594:
function getDefaultSessionDirPath( cwd: string, agentDir = getDefaultAgentDir(),): string { const resolvedCwd = resolvePath(cwd); const resolvedAgentDir = resolvePath(agentDir); const safePath = `--${resolvedCwd.replace(/^[/\\]/, "") .replace(/[/\\:]/g, "-")}--`; return join(resolvedAgentDir, "sessions", safePath);}把 cwd 里的分隔符换成 -,前后各包两个 -。举例:
/home/you/proj → --home-you-proj--D:\code\pi → --D-code-pi--于是 ~/.pi/agent/sessions/ 下每个工作目录一个子目录,会话跟着项目走。
文件名在 :1079-1080:
const fileTimestamp = timestamp.replace(/[:.]/g, "-");const name = `${fileTimestamp}_${this.sessionId}.jsonl`;this.sessionFile = join(this.getSessionDir(), name);2026-03-11T08:12:04.115Z 变成 2026-03-11T08-12-04-115Z,拼上会话 id。
会话 id 来自 uuidv7()(:264-266)。选 v7 而不是 v4 是因为 v7 前 48 位是毫秒时间戳,
按字符串排序就等于按时间排序——后面 listSessionsFromDir() 靠这个省掉一次读取。
3.2 文件里长什么样
第一行一定是 header(session-manager.ts:43-50):
export interface SessionHeader { type: "session"; version?: number; // v1 sessions don't have this id: string; timestamp: string; cwd: string; parentSession?: string;}version 是可选字段,因为 v1 的文件里根本没写这个字段——读到 undefined 就当 1。
parentSession 只在分叉产生的新文件里出现,指回父会话文件。
后面每一行一条 entry。真实文件里每行是一个压扁的 JSON 对象, 下面为了排版展开了,字段一个没删:
{ "type": "session", "version": 3, "id": "01932c7e-4b1a-7c3d-9e2f-5a6b7c8d9e0f", "timestamp": "2026-03-11T08:12:04.115Z", "cwd": "/home/you/proj" }{ "type": "model_change", "id": "3f9a0c21", "parentId": null, "timestamp": "2026-03-11T08:12:09.002Z", "provider": "anthropic", "modelId": "claude-sonnet-4-6" }{ "type": "message", "id": "a17b4de0", "parentId": "3f9a0c21", "timestamp": "2026-03-11T08:12:31.480Z", "message": { "role": "user", "content": "salt 校验为什么失败?", "timestamp": 1773216751480 } }三个细节:
- header 没有
id/parentId,它是文件元信息,不是树节点; - entry 的
id是 8 位十六进制,header 的id是完整 UUIDv7; - 消息自己的
timestamp是数字(毫秒),entry 的timestamp是 ISO 字符串。 两套时间是因为消息类型来自模型层,entry 类型来自存储层。
3.3 懒落盘
打开 pi、切个模型、什么都不问就退出——会不会留下一个空会话文件?
不会。session-manager.ts:1160-1170:
/** * A new session file is created only once the session contains a user or * assistant message. Setup entries alone (model, thinking level, system prompt) * stay in memory, so opening and closing pi without chatting leaves no file. * Starting at the user message (not the first assistant reply) keeps the prompt * on disk if the first turn never completes (#10000). */private _hasConversation(): boolean { return this.fileEntries.some((e) => e.type === "message" && (e.message.role === "user" || e.message.role === "assistant"));}注释第二句是血换来的:从 user 消息起算。曾经按"有 assistant 回复"判断, 结果第一轮请求卡住、进程被杀,你输的那句话一个字都没落盘。
落盘函数 _persist(:1172-1189):
_persist(entry: SessionEntry): void { if (!this.persist || !this.sessionFile) return; if (!this.flushed) { if (!this._hasConversation()) return; const fd = openSync(this.sessionFile, "wx"); try { for (const e of this.fileEntries) { writeFileSync(fd, `${JSON.stringify(e)}\n`); } } finally { closeSync(fd); } this.flushed = true; } else { appendFileSync(this.sessionFile, `${JSON.stringify(entry)}\n`); }}第一次落盘不是"追加一行",是把内存里攒的所有 setup entry(模型、思考等级、
系统提示词)一次性写出去。"wx" 表示"不存在才创建",并发生成同名文件会直接抛错,
而不是悄悄覆盖别人的会话。之后每次追加只有一行 appendFileSync——写入 O(1),
跟文件多大无关,这是第一代的性能优势。
3.4 追加失败要回滚三件
写入可能失败:磁盘满、权限、路径被删。失败之后内存和文件就不一致了。
session-manager.ts:1191-1206:
private _appendEntry(entry: SessionEntry): void { const previousLeafId = this.leafId; this.fileEntries.push(entry); this.byId.set(entry.id, entry); this.leafId = entry.id; try { this._persist(entry); } catch (error) { // Keep memory in line with the file: an entry that was not written // must not become the parent of later entries, or the file would // hold entries pointing to a missing parent. this.fileEntries.pop(); this.byId.delete(entry.id); this.leafId = previousLeafId; throw error; }}三件都要退:数组、索引表、叶子指针。理由就是注释那句——没写进去的 entry 不能
成为后来者的父亲。只弹数组不清 byId,下一条 entry 的 parentId 就指向文件里不
存在的节点,重载时那条链直接断掉,用户看到"后半段对话凭空消失"。
3.5 什么时候全量重写
追加是常态,三个时刻必须重写整个文件:
| 时刻 | 方法 | 原因 |
|---|---|---|
| 版本迁移 | _loadEntries → _rewriteFile |
entry 要补字段,没有增量路径 |
| 分叉另存 | createBranchedSession → _rewriteFile |
新文件只有一条路径 |
| 空文件初始化 | _setSessionFile → _rewriteFile |
补上 header |
_rewriteFile(:1124-1134)就是 openSync(file, "w") 后全量写一遍。
对一次会话没什么。对几十万条 entry 的老会话就是 O(n) 停顿——
而且发生在你最不希望停顿的时刻(打开会话)。这个成本点第七节要用。
四、恢复:从文件读回一棵树
写是一行一行加的,读却不能一行一行读——因为树要靠 parentId 重建。
读的整个过程分四步:解码、解析、迁移、建索引。
4.1 逐块解码,处理被切断的多字节字符
session-manager.ts:627-670,核心是这段循环:
const decoder = new StringDecoder("utf8");const buffer = Buffer.allocUnsafe(SESSION_READ_BUFFER_SIZE); // 1 MiBwhile (true) { const bytesRead = readSync(fd, buffer, 0, buffer.length, null); if (bytesRead === 0) break; pending += decoder.write(buffer.subarray(0, bytesRead)); let lineStart = 0; let newlineIndex = pending.indexOf("\n", lineStart); while (newlineIndex !== -1) { const entry = parseSessionEntryLine(pending.slice(lineStart, newlineIndex)); if (entry) entries.push(entry); lineStart = newlineIndex + 1; newlineIndex = pending.indexOf("\n", lineStart); } pending = pending.slice(lineStart); // 最后一段没换行的留到下一块}为什么不能直接 readFileSync(path, "utf8")?两个原因:
- 会话文件可能很大,一次性读进内存会顶到堆上限;
- 1 MiB 的块边界会切断一个 UTF-8 字符。中文一个字三字节,切在中间就解出乱码, 那一行的 JSON 解析必然失败,然后被静默丢弃。
StringDecoder 就是为这件事存在的:它把不完整的字节序列留在内部,等下一块到了再拼。
pending 保存"还没遇到换行的尾巴",跨块保留。这个变量在循环结束后还有第二个用途。
4.2 文件末尾没有换行时
正常写入每行都以 \n 收尾。但如果上次进程在 write 的系统调用中间被 kill,
文件末尾可能是一行没有换行的半截 JSON。
:661-669:
if (entries.length === 0) return entries;const header = entries[0];if (header.type !== "session" || typeof (header as { id?: unknown }).id !== "string") { return [];}if (pending) appendFileSync(resolvedFilePath, "\n");return entries;两件事:
- 先验 header 再动文件。如果第一行不是合法 session header,返回空数组,
一个字节都不改。这个顺序很重要——
_setSessionFile(:1029-1046)靠这个区分 "空文件"和"不是 pi 会话的文件":空文件补 header,非空但解析不出就抛错并保持原样。 pending非空就给文件补一个换行。半截那一行本身没救了,但补上换行之后, 下次追加不会粘在它后面,把一整条新 entry 也污染掉。
代价是那半截 entry 丢了。丢的可能是半个工具结果,也可能是一整条用户消息。 第一代的取舍是:宁可丢一条,不能污染后面全部。
4.3 坏行静默跳过
parseSessionEntryLine(:616-624)和 parseSessionEntries(:355-370)都是同一个模式:
try { return JSON.parse(line) as FileEntry;} catch { // Skip malformed lines return null;}不抛错,不警告,不计数。中间某一行坏了,前后照常加载。
这是"能打开就比打不开好"的工程选择。代价是损坏是无声的: 如果坏掉的是某条 entry 的父亲,那整条子树都从上下文里消失, 用户看到的是"我明明说过这句话",而日志里一个错都没有。
静默容错必须配一个外部可观测指标——第一代没有,这是它的债。
4.4 三版迁移
读到旧版本文件,_loadEntries(:1085-1101)会先迁移:
if (migrateToCurrentVersion(this.fileEntries)) { this._rewriteFile();}migrateToCurrentVersion(:337-347)按 header 的 version 依次跑:
| 版本跃迁 | 函数 | 干了什么 |
|---|---|---|
| v1 → v2 | migrateV1ToV2 |
补 id/parentId 链;firstKeptEntryIndex 转 firstKeptEntryId |
| v2 → v3 | migrateV2ToV3 |
消息角色 hookMessage 改名为 custom |
v1→v2 是结构性的,代码值得看一眼(:287-313):
function migrateV1ToV2(entries: FileEntry[]): void { const ids = new Set<string>(); let prevId: string | null = null; for (const entry of entries) { if (entry.type === "session") { entry.version = 2; continue; } entry.id = generateId(ids); entry.parentId = prevId; prevId = entry.id; // Convert firstKeptEntryIndex to firstKeptEntryId for compaction if (entry.type === "compaction") { const comp = entry as CompactionEntry & { firstKeptEntryIndex?: number }; if (typeof comp.firstKeptEntryIndex === "number") { const targetEntry = entries[comp.firstKeptEntryIndex]; if (targetEntry && targetEntry.type !== "session") { comp.firstKeptEntryId = targetEntry.id; } delete comp.firstKeptEntryIndex; } } }}parentId = prevId 把线性顺序直接翻译成一条链:迁移出来的树是一条直线,
因为 v1 压根没有分叉这个概念。
compaction 那一支更值得看:v1 用数组下标记录"从哪开始保留",v2 改成entry id。 下标是相对文件的位置,一旦分叉或被重写就指错地方;id 是身份,跨分叉、跨重写都成立。 持久化数据里不要存位置,要存身份——第七节会看到第二代把这条推到极致。
4.5 建索引:leafId 是"最后一条"
迁移之后 _buildIndex()(:1103-1122):
for (const entry of this.fileEntries) { if (entry.type === "session") continue; this.byId.set(entry.id, entry); this.leafId = entry.id; // 每一轮都被覆盖 if (entry.type === "label") { /* 更新 labelsById */ }}leafId 被循环覆盖,最后等于文件里最后一条 entry 的 id。
容易误解:leafId 不是"树的叶子",是"逻辑上最新的那个节点",恢复后就是文件末尾那条。
上次退出前回退过也一样——回退状态不落盘,branch() 只改内存里的 leafId
(:1589-1594),不产生任何 entry。所以重启后,你总是回到"最后一次实际对话的位置",
而不是"最后停留的位置"。对 CLI 来说这合理:用户想接着聊,不想接着停在某条旧消息上。
4.6 8 位短 id 撞了怎么办
generateId(:277-284):
function generateId(byId: { has(id: string): boolean }): string { for (let i = 0; i < 100; i++) { const id = randomUUID().slice(0, 8); if (!byId.has(id)) return id; } // Fallback to full UUID if somehow we have collisions return randomUUID();}完整 UUID 是 36 个字符,8 位短 id 每条省 28 个字符:一万条 entry 就是 280 KB。
代价是:跨文件不唯一。createBranchedSession 重建时用 new Set(pathEntryIds)
作为已用集合,新 id 只在当前文件范围内避重。跨文件唯一性没人保证,也没人需要——
parentSession 只是个字符串路径,不参与任何 id 解析。
五、从树到上下文
索引建好了,树在内存里了。接下来要回答:哪条路径上的哪些 entry,变成发给模型的消息。
这一步有三个函数,层层递进:buildSessionPath → buildContextEntries → buildSessionProjection。
5.1 第一步:从叶子回溯
session-manager.ts:390-416:
const path: SessionEntry[] = [];let current: SessionEntry | undefined = leaf;while (current) { path.push(current); current = current.parentId ? index.get(current.parentId) : undefined;}path.reverse();return path;从叶子一路往父亲走,走不动了就停,然后整体反转。得到的是根到叶子的顺序。
两个边界:leafId === null 返回空路径(:397-399,对应 resetLeaf() 后"下一条会成为
新根");没传时 leaf ??= entries[entries.length - 1](:403,跟 _buildIndex 口径一致)。
parentId 指向不存在的 id 时 index.get() 返回 undefined,循环自然结束。
断链不抛错,只是路径到此为止——4.3 静默跳过的下游后果。
5.2 第二步:压缩之后的保留规则
拿到完整路径还不够。M09 讲过,压缩会把旧历史折叠成一条摘要, 所以路径上可能有 compaction entry,它之前的 entry 要按规则丢弃。
buildContextEntries(:476-512):
export function buildContextEntries(entries, leafId?, byId?): SessionEntry[] { const path = buildSessionPath(entries, leafId, byId); let compaction: CompactionEntry | null = null; for (const entry of path) { if (entry.type === "compaction") compaction = entry; } if (!compaction) return path; const compactionIdx = path.findIndex((entry) => entry.id === compaction.id); if (compactionIdx < 0) return path; const contextEntries: SessionEntry[] = [compaction]; let foundFirstKept = false; for (let i = 0; i < compactionIdx; i++) { const entry = path[i]; if (entry.id === compaction.firstKeptEntryId) foundFirstKept = true; if (foundFirstKept && !(entry.type === "message" && entry.message.role === "system")) { contextEntries.push(entry); } } contextEntries.push(...path.slice(compactionIdx + 1)); return contextEntries;}三件事,用大白话说:
- 取路径上最后一条 compaction(循环覆盖
compaction,不留早期值)。 - 从
firstKeptEntryId那条开始,到 compaction 之前,都算"保留段",逐条带上。 - compaction 之后的 entry 全部带上。
两个细节藏在代码里:
- 跳过 system 消息(
:506)。压缩边界会重写系统提示词, 保留段里的旧 system 消息属于"过期快照",带上就会和新的打架。 - compaction 自己排第一位(
:499)。摘要在消息序列里必须出现在 它概括的那些内容之前——虽然那些内容已经不在了。
这就是为什么 M09 说压缩是"墓碑":被压缩的 entry 还在文件里, 只是不再出现在这条路径的保留段里。
5.3 第三步:投影与上下文编辑
最后一层是 buildSessionProjection(:543-573)。它做两件额外的事。
事一:提取设置。 getSessionContextSettings(:418-433)沿路径扫三类 entry,
后者覆盖前者:
for (const entry of path) { if (entry.type === "thinking_level_change") { thinkingLevel = entry.thinkingLevel; } else if (entry.type === "model_change") { model = { provider: entry.provider, modelId: entry.modelId }; } else if (entry.type === "message" && entry.message.role === "assistant") { model = { provider: entry.message.provider, modelId: entry.message.model }; }}注意第三支:assistant 消息也能定模型。消息自带 provider 和 model,
一条真实产生过的回复就是"当时用的哪个模型"的硬证据,比 model_change 更可信。
所以分叉之后回到一条两个月前的 entry 继续聊,模型会自动切回那条路径上最后实际用过的那个。
事二:应用上下文编辑。 context_edit 这条 entry 不产生消息,它改写别人(:519-540):
function projectContextEntry( entry: SessionEntry, edit: ContextEditEntry | undefined,) { const messages = sessionEntryToContextMessages(entry); if (!edit) return messages; const replacement = edit.replacement; if (replacement === null) return []; // null = 从上下文里删掉 return messages.map((message) => { /* 只替换 content */ });}null 表示"从模型上下文里消失,文件里保留",有值表示"只换 content,元数据不动"。
这解决一个真实痛点:Agent 读了 3 万行日志,你不想让它占据后续每一轮的上下文,
又不想删记录。追加一条 context_edit 指向那条 toolResult、replacement: null 就行。
文件 append-only,上下文可以裁——这是第一代里最接近第二代思想的一处。
5.4 旧 compaction 只算一次
buildSessionProjection 里有个容易看漏的分支(:555-566):
const projectedEntries = contextEntries.map((sourceEntry, index) => ({ sourceEntry, messages: sourceEntry.type === "compaction" && index > 0 ? [] : projectContextEntry(sourceEntry, edits.get(sourceEntry.id)),}));index > 0 的 compaction 贡献空数组。第二条 compaction 从哪来?
buildContextEntries 可能把一条旧的 compaction 也留在保留段里——它的 id 恰好落在
firstKeptEntryId 之后,被当成普通 entry 带上了。
带上是对的,它在树上确实在那儿。但摘要不能再算一遍,否则模型看到两份重叠的摘要。
这一行 index > 0 堵的是"压缩两次之后 token 反而变多"。
六、分叉
前面 2.4 已经看到分叉在数据层的样子:新节点的 parentId 指向旧节点。
这里看 API 层怎么把它做出来。
6.1 branch:只挪一个指针
session-manager.ts:1589-1594:
branch(branchFromId: string): void { if (!this.byId.has(branchFromId)) { throw new Error(`Entry ${branchFromId} not found`); } this.leafId = branchFromId;}三行。不写文件,不产生 entry,不改任何已有节点。
下一次 appendMessage() 时,新 entry 的 parentId 就是这个 leafId,分叉自然发生。
这是"认父不认子"换来的最大好处:分叉成本 O(1),跟历史多长无关。 在 MySQL 里做同样的事通常要一张自引用表加一次 UPDATE,还要担心两个客户端同时改同一个分支。
6.2 branchWithSummary:回退时留遗言
直接 branch() 有个问题:被放弃的那段对话,模型再也看不见了。
如果那段里有"我们排除了方案 A,因为它跟 X 冲突"这种结论,重问一遍要从头再来。
branchWithSummary(:1610-1635)解决这个:
const fromId = this.leafId ?? "root";this.leafId = branchFromId;const entry: BranchSummaryEntry = { type: "branch_summary", id: generateId(this.byId), parentId: branchFromId, timestamp: new Date().toISOString(), fromId, summary, details, usage, fromHook,};this._appendEntry(entry);顺序很关键:先挪叶子,再追加。于是摘要 entry 挂在目标分支上,
而 fromId 记着"我是从哪条路回来的"。它进上下文(:458-460),
所以新分支一开始就带着一句"之前走过那条路,结论是这样"。
M09 第九节讲了这套摘要怎么生成。存储侧只看两个字段:fromId 指向被放弃路径的末端,
parentId 指向新路径的起点。一条 entry 同时挂在两个位置上,
这是树结构里唯一一处"双向引用"。
6.3 createBranchedSession:把一条路径抠出来另存
树在文件里,但文件不能拆。如果你想把某条分支单独交给别人、或者单独归档,
只能另存一个新文件。createBranchedSession(:1642-1758)就是干这个的。
它比"复制路径上的 entry"麻烦,因为有三处引用会失效。看核心循环:
const pathWithoutLabels: SessionEntry[] = [];const replacementByLabelId = new Map<string, string>();const pendingLabelIds: string[] = [];let pathParentId: string | null = null;for (const entry of path) { if (entry.type === "label") { pendingLabelIds.push(entry.id); continue; } for (const labelId of pendingLabelIds) { replacementByLabelId.set(labelId, entry.id); } pendingLabelIds.length = 0; if (entry.type === "compaction") { const kept = replacementByLabelId.get(entry.firstKeptEntryId); pathWithoutLabels.push({ ...entry, parentId: pathParentId, firstKeptEntryId: entry.firstKeptEntryId === entry.id ? entry.id : (kept ?? entry.firstKeptEntryId), }); } else { pathWithoutLabels.push({ ...entry, parentId: pathParentId }); } pathParentId = entry.id;}三处失效引用,逐一处理:
| 问题 | 原因 | 处理 |
|---|---|---|
| label 掉了会断链 | label 是真实节点,后面的 entry 可能挂在它下面 | 删掉 label 后把它下面的 entry 重挂到前一个非 label 节点 |
| 谁的 label 指谁 | label 引用 targetId |
收集 labelsById 里目标在新路径上的,重新追加 |
firstKeptEntryId 指空 |
它可能指向被删掉的 label | 用 replacementByLabelId 换一次 |
第一行最反直觉:label 不是元数据,是真正的树节点。 你给第 5 条消息打了个标记,这条 label entry 就成了第 6 条消息的父亲。 删它必断链,所以必须重挂。
最后写新文件头(:1685-1692):
const header: SessionHeader = { type: "session", version: CURRENT_SESSION_VERSION, id: newSessionId, timestamp, cwd: this.cwd, parentSession: this.persist ? previousSessionFile : undefined,};parentSession 指回原文件。这是整棵树里唯一的跨文件边,
而且是单向的、纯字符串的——不影响任何解析逻辑,只用于回溯展示。
6.4 分叉的两种成本
把 6.1 和 6.3 放在一起看,第一代其实提供了两种"分叉":
branch() |
createBranchedSession() |
|
|---|---|---|
| 粒度 | 挪指针 | 复制一条路径 |
| 成本 | O(1) | O(路径长度),且要重写整个新文件 |
| 结果 | 同一文件里多一条分支 | 一个新文件 |
| 能带走吗 | 不能 | 能(parentSession 留个指针) |
| 谁在用 | 交互里回退 | 导出/归档/交接 |
注意第二行:默认的分叉是 O(1) 的,这正是树结构的价值。 但它有个前提——所有分支必须待在同一个文件里,由同一个进程写。
这个前提,就是第一代撑不住的地方。
七、树撑不住的四件事
到这儿,第一代的设计已经完整:append-only 的树、一行一条的 JSONL、 O(1) 的追加和分叉。对 CLI 来说这套东西跑了很多年,没什么大毛病。
那 packages/durable 为什么还要重做一遍?四个具体的压力点。
7.1 一次追加要原子的不止一条 entry
第一代的追加单位是"一行 JSON"。这个假设在 Agent 场景里越来越不成立。
考虑一次工具调用要落盘的东西:
- 一条
toolResultentry; - 这次调用消耗的 token(
usageentry); - 扩展自己的状态(比如"这个文件我读过",
customentry); - 如果有后台任务,任务走到了哪个阶段。
四条记录,四次 appendFileSync。中间崩了,文件里就有两条、三条。
没有事务,就没有"要么全有要么全无"。
第一代靠事后修复兜着:读的时候跳过坏行(4.3)、请求前补合成结果(7.2)、
_appendEntry 失败回滚内存(3.4)。三处补丁,各管一段。
第二代把这个假设翻过来:追加的单位是一次提交。
durable 的 Tx 一次能写 entry、文档、任务、提交记录,
它们进同一个 batch,要么全落,要么全不落。
README 的 Errors 第一条写得很干脆:
一次提交是原子的:
conversation.commit()可以同时追加 entry、改文档、建任务; 要么全部存储,要么一条都不。
这不是把三行写合成一行写,是把"一致性"从补丁层提到了 API 层。
7.2 树没有"未完成"这个状态
更麻烦的是语义缺口。
Agent 调工具时,先写一条 assistant 消息(带 toolCall),
工具跑完再写一条 toolResult。两步之间进程被杀,文件里就留下一个
只有调用、没有结果的洞。
这个洞在文件里是合法的输入——JSON 没问题,树也没问题。 但它发不出去:模型 API 要求每个 tool call 后面必须跟一个 result。
第一代的处理在 packages/ai/src/api/transform-messages.ts:179-207:
// Second pass: insert synthetic empty tool results for orphaned tool calls// This preserves thinking signatures and satisfies API requirementsconst closePendingToolCalls = () => { if (pendingToolCalls.length > 0) { for (const tc of pendingToolCalls) { if (!existingToolResultIds.has(tc.id)) { result.push({ role: "toolResult", toolCallId: tc.id, toolName: tc.name, content: [{ type: "text", text: "No result provided" }], isError: true, }); } } pendingToolCalls = []; }};也就是说:存储层不知道这次调用失败了,发送层每次请求都重新补一遍洞。
同一段逻辑还有一条补充(:216-224):stopReason 是 error 或 aborted 的
assistant 消息整条跳过,理由是"回放半截内容会让 API 报错"。
这套做法能用,但它把"这次调用到底成没成"变成了每次请求时的一次猜测。
补出来的 No result provided 是假的错误结果,模型分不清"工具真失败了"和"进程死了"。
第二代把状态显式建模:工具调用本身是一个持久任务(pi.tool),
有阶段、有检查点、有终态。进程死在中途,重开时从最后一个检查点重跑;
真跑挂了,写进去的是真实的错误结果。
顺带解决了崩溃循环:settings.restartLimit 默认 5,
一个任务连续把进程搞死 5 次,就不再重试,直接判定终态并上报。
第一代没有这个计数器——因为树里没有"这次尝试"这个概念。
7.3 一个文件一个写者
第一代的介质绑定得很死。
SessionManager 直接用 node:fs 的 openSync / appendFileSync / readSync,
没有介质接口,换介质就得重写这个类。这不是疏忽——CLI 就跑在本地磁盘上,
加一层抽象只多一次函数调用。但只要想在别处跑,这层绑定立刻变成墙:
| 想跑在 | 第一代 | 第二代 |
|---|---|---|
| 本地磁盘 | 可以 | 可以(JSONL / SQLite) |
| 浏览器 | 不行,没有 fs | 可以(IndexedDB) |
| Cloudflare Durable Object | 不行 | 可以(DO 的 SQLite,提交即事务) |
| 只读观察端 | 不行 | 可以(readOnly: true) |
| 多进程共享 | 不行(追加会打架) | 不行,但明确写清了"一个进程拥有一个 storage" |
最后一行值得注意:第二代也没有做跨进程锁。它做的是把限制写成契约, 而不是让它在某天以数据损坏的形式暴露。
7.4 分叉的单位是文件,不是 entry
6.1 说 branch() 是 O(1),这是真的。但那个 O(1) 只对同一个进程、同一个文件成立。
一旦你想做这几件事,树就露馅了:
- 把某个中间节点单独变成一个会话(
createBranchedSession,O(n) 重写); - 两个会话共享前缀、各自独立演进(树里做不到,只能复制);
- 从某条 entry 开始跑一个子 Agent,它跟你共享历史但不共享后续(得手工拼上下文);
- 从一个会话的某个点 fork 到另一台机器(文件搬过去,id 空间全乱)。
根本原因:第一代的分叉是"文件内部的指针技巧",不是"一等公民"。 树是文件的内部结构,不是 API 的概念。
第二代的回答很直接:分叉就是新建一个会话,让它继承父会话到某条 entry 的历史。 没有"树内分叉"这回事,只有会话与会话之间的父子关系。
7.5 结论
四条压力,指向同一个结论:
会话不再只是一个文件格式,它是一个需要被多个后端实现、需要事务、 需要显式状态的运行时接口。
第一代把"会话"当成 SessionManager 这个类的内部实现,
第二代把它拆成三层:
Storage(介质) ← JSONL / SQLite / IndexedDB / Memory ↑Session(内核) ← 提交线、缓存、组提交、失败即终态 ↑Harness(运行时) ← 任务调度、工具、生成、压缩这三层就是 M11 要展开的内容。本章后三节只讲最下面那半截: entry 长什么样、JSONL 怎么写、一次提交怎么变成一次落盘。
八、第二代:账本取代树
打开 packages/durable/src/types.ts:458-473,先看 entry 长什么样:
export type EntryRecord = { readonly id: EntryId; readonly conversationId: ConversationId; /** Application-defined entry discriminator. */ readonly kind: string; /** Messages for model context; absent for display/bookkeeping entries. */ readonly model?: readonly Message[]; /** JSON payload consumed by views, extensions, or bookkeeping logic. */ readonly data?: JsonValue; /** First entry in the active context selected by this entry. */ readonly head?: EntryId; /** Context-only overrides of earlier visible entries. */ readonly edits?: readonly ContextEdit[]; /** Task that appended this entry, when it was produced by durable work. */ readonly byTaskId?: TaskId;};跟第一代对比着看,三处结构性差异:
| 字段 | 第一代 | 第二代 |
|---|---|---|
parentId |
有,构成树 | 没有 |
head |
无 | 有,标记"上下文从这里开始" |
type |
联合类型,编译期穷举 | kind 字符串,运行期可注册 |
model |
混在 message 里 |
单独一列,与 data 分开 |
最后一行很关键:model(给模型看的)和 data(给程序看的)是两列。
第一代里,一条 entry 要么是 message(给模型),要么是 custom(给程序),
二选一。第二代允许同一条 entry 两者都带。
8.1 六种内置 kind
entries.ts:15-34 一共只定义了六个:
| kind | 含义 | model 里放什么 |
谁写的 |
|---|---|---|---|
pi.user |
用户输入 | [UserMessage] |
submit() |
pi.assistant |
模型回复(任意 stop reason) | [AssistantMessage] |
generation 任务 |
pi.system |
系统提示词/工具集变了 | [SystemMessage],content 为空 |
generation 任务 |
pi.tool-result |
工具结果 | [ToolResultMessage] + 诊断块 |
tool 任务 |
pi.reset |
新上下文的起点 | 纯 reset 时无;带交接文本时 [UserMessage] |
reset() / handoff |
pi.compaction |
压缩摘要 | [UserMessage](包好的摘要),head 指向第一条保留 entry |
compaction 任务 |
pi.system 的 content 为什么是空的?因为它不是一条真消息,是个边界标记:
真正的系统提示词由运行时根据当前工具集重新拼,entry 只说"从这一条开始变过了"。
这跟 M08 的"每轮重算系统提示词"是同一件事——提示词不进文件,只进标记。
8.2 head 取代 parentId
这是两代之间最大的一处置换。
第一代:树。上下文 = 从叶子回溯到根的一条路径,压缩在路径上打个洞。 第二代:线性。上下文 = 从最新的 head 标记开始,往后到末尾的一段区间。
harness/context.ts:144-158 的注释写得比任何二手解释都准:
* H = newest visible head marker; the range runs from `H.head` (or transcript * start) through the tail. Per target, the newest edit in the range wins. * Context entries are H followed by the range's non-head entries.即:H 是可见范围内最新的 head 标记,区间从 H.head 指向的 entry 到末尾;
同一 target 多次编辑时区间里最新那条赢;上下文 = H 自己 + 区间内除 head 以外的 entry。
跟 5.2 的 buildContextEntries 对着看,会发现两边在解同一道题:
| 问题 | 第一代 | 第二代 |
|---|---|---|
| 旧历史怎么丢 | 压缩 entry 的 firstKeptEntryId |
head 标记的 head 字段 |
| 谁提供摘要 | 压缩 entry 自己 | head 标记自己(它就是 pi.compaction) |
| 怎么找边界 | 沿 parentId 回溯,在路径上找 compaction |
直接读"最新 head 标记"缓存 |
| 多次压缩 | 只让 index 0 出摘要(5.4) | 新 head 直接覆盖旧的可见起点 |
| 编辑旧 entry | context_edit 扫区间建 map |
entry 自带 edits,区间内后者覆盖前者 |
第一列那个"沿 parentId 回溯"是重点:它的成本是 O(路径长度),每次构建上下文都要走一遍。
第二列的新方案成本是 O(1)——ConversationTails 直接把"每个会话最新的 head 标记"缓存在内存里。
conversation-tails.ts:8-11 给了两个容量常数:
const LATEST_CAPACITY = 4096; // 只存最新 entry ID 的会话数const MARKER_CAPACITY = 256; // 连 head 标记整条一起存的会话数两个数字差 16 倍:前者只存一个 ID,后者要存整条 entry(一条压缩摘要可能很长)。
8.3 分叉变成"新会话继承父会话"
types.ts:427-439:
export type ConversationRecord = { readonly id: ConversationId; /** Fork source and the inclusive parent entry. */ readonly parent?: { readonly conversationId: ConversationId; readonly at: EntryId; }; /** Creator edge: attribution, subtree abort, subtree idle waits. */ readonly owner?: { readonly conversationId: ConversationId; readonly taskId: TaskId; };};parent 只有两个字段:父会话 id,和"继承到哪条 entry 为止"。
没有"树根",没有"子节点列表",没有"分支名"。分叉 = 一条记录里的两个字段。
- 第一代:一个文件 = 一棵树,分叉 = 树内一个指针。
- 第二代:一个会话 = 一条线性历史,分叉 = 新会话带上
parent,读时把父会话历史拼进来。
后者多一次拼接,换来两个好处:分叉可跨进程、跨后端、跨机器;一个会话的历史长度 也不再受"文件里有多少无关分支"影响。
调用的完整链路(三层,每层都短):
// harness/harness.ts:170-172fork(at: EntryId, options: ConversationCreateOptions, context: Context) { return this.#host.create( { kind: "fork", parentId: this.id, at, ownership: options.ownership }, options, context);}// session/transaction.ts:356-364forkConversation( parentConversationId: ConversationId, at: EntryId, options: { readonly ownership: ConversationOwnership },): Promise<ConversationRecord> { return this.#write(() => this.#stageConversation( { conversationId: parentConversationId, at }, options.ownership));}#stageConversation 里还有一步值得单独看(transaction.ts:386-389):
const copies = parent === undefined ? [] : await prepareForkDocumentCopies( this.#host.storage, parent.conversationId, parent.at, id, this.#context);文档也要跟着分叉。
这是第一代根本没想到的一层。forks.ts:26-59 里把文档分成两种策略:
| 文档策略 | 含义 | 分叉时怎么办 |
|---|---|---|
asOf |
历史型,要能回到过去某个时刻 | 拷贝父会话在 at 那个提交点的值 |
current |
只有最新值有意义(如 agent 配置) | 拷贝父会话当前的値 |
为什么这重要?因为第二代的会话不只存消息,还存状态:当前模型、 待处理的输入队列、压到哪了、这次 run 花了多少 token。 你在某条 entry 上分叉,新会话应该拿到"那一刻的全部状态",而不只是消息。
第一代做不到,因为它的 entry 类型里没有"文档"这个维度。 这是第七节 7.1 说的"追加的语义变多了"的具体表现。
九、第二代 JSONL:marker 与 sidecar
durable 也支持 JSONL,但格式完全不同。
storage/jsonl/storage.ts:30-31:
const FORMAT_VERSION = 1;const MAIN_FILE = "main.jsonl";一个目录,两种文件:一个 main.jsonl,加一堆 sidecar(doc-<id>.jsonl / task-<id>.jsonl,
命名规则在 :102)。
9.1 main.jsonl 里只有 marker
storage.ts:44-49:
type MainMarker = { readonly format: typeof FORMAT_VERSION; readonly type: "commit"; readonly seq: Seq; readonly writes: readonly MainOperation[];};一行一个提交。writes 是这个提交做了什么的清单,操作类型在 :37-42:
| 操作 | 意思 | 内容在哪 |
|---|---|---|
conversation |
新建会话 | marker 里 |
entry |
追加一条 entry | marker 里 |
submission |
提交记录变更 | marker 里 |
task |
任务状态 | sidecar |
document.create / document.change |
文档变更 | sidecar |
document.retire |
文档下线 | marker 里 |
规律很清楚:小对象直接进 marker,大对象进 sidecar,marker 里只留一个序号引用。
实际写出来是这样(真实文件里也是一行一条,这里为排版展开了):
# main.jsonl{"format":1,"type":"commit","seq":42,"writes":[ {"type":"entry","value":{"id":7,"conversationId":1, "kind":"pi.user","model":[{"role":"user","content":"hi"}]}}, {"type":"document.change","id":3,"ordinal":1}]}# doc-3.jsonl{"format":1,"type":"record","seq":42,"ordinal":1, "payload":{"type":"document","id":3, "content":{"kind":"base","version":4,"value":{"busy":false}}}}marker 里的 document.change 只有 id 和 ordinal,真值去 sidecar 按
(seq, ordinal) 找;content.kind 是 base 还是 delta,决定恢复时能否直接用(9.4)。
9.2 sidecar 一行一个版本
storage.ts:55-61:
type SidecarRecord = { readonly format: typeof FORMAT_VERSION; readonly type: "record"; readonly seq: Seq; readonly ordinal: number; readonly payload: SidecarPayload;};seq 跟 marker 对得上,ordinal 是"同一次提交里的第几个"。两个字段合起来
唯一确定一个版本。
文档要单独开文件,因为它是被反复重写的:pi.live(当前 run 状态)、
pi.inbox(队列)每一轮都变。混进 entry 文件里,要么每次 O(n) 重写整条历史,
要么原地修改、违背 append-only。拆开后 entry 只追加,文档只追加自己的版本。
9.3 先写 sidecar,再写 marker
storage.ts:281-286 的注释把不变量写得很死:
* Commit `batches` with one append per affected file: every batch's sidecar * records first, then their markers in one write of `main.jsonl`. Each batch is * checked against the state the earlier ones left ... the first batch refused * ends the batch. A torn append of the markers recovers a shorter complete * prefix; any failure once a batch applied poisons the storage.关键句:"a torn append of the markers recovers a shorter complete prefix"。
marker 是提交点。先写完所有 sidecar,再写 marker;marker 一落,这次提交就算成了。 如果进程在写 marker 的中途死了,那个 marker 行是残的,恢复时直接丢掉, 前面写的 sidecar 变成没人引用的孤儿——无害,下次覆盖。
这是一个非常经典的方案,名字叫 write-ahead + commit record。 数据库的 WAL 用的是同一套。差别在于:第一代根本没这个东西。
对比两边在最坏情况下的表现:
| 崩溃时刻 | 第一代(一行一条) | 第二代(marker + sidecar) |
|---|---|---|
| 写到一半 | 半行 JSON,下次加载被静默丢弃 | 残 marker 被截掉,整个提交不存在 |
| 多条记录只写了一半 | 前面几条在,后面几条没了 | 不可能:一个 marker 管一个提交 |
| 写完但没落盘 | 随 OS 缓冲,丢掉最后几条 | 同样是 OS 缓冲;传 fsync: true 可以 flock 后才算提交 |
第二行是核心:粒度的区别。第一代的一致性单位是"一条 entry", 第二代是"一次提交"。前者只能保证单条不碎,后者能保证一组互不碎。
9.4 recover():启动时重建全部状态
storage.ts:590 开始,一共两百多行,跟第一代的 40 行加载不是一回事。
按顺序做五件事:
1. 读 main.jsonl,校验 seq 严格递增 (:597-603)2. 删掉所有遗留的 *.reclaim 临时文件 (:607-611)3. 读所有 sidecar,校验 seq/ordinal 递增 (:618-637)4. 扫 marker,找出每个文档最新的 base (:657-682)5. 重放:逐个 marker 重建内存状态 (:690 起)第 4 步值得说一下。文档有两种内容形态:base(全量快照)和 delta(差分)。
重放时要先找到最新的 base,前面的 delta 才有意义。latestBases 这个 map 就是干这个的
(:657-682),它把"找最近快照"这个动作从无限回溯压缩成一次扫描。
第 1 步的校验很硬:seq 必须严格递增,不递增直接抛 JsonlCorruptionError
(:599-601),不是静默跳过。态度上的差别是——第一代认为"文件是用户的,
坏了也要能打开",第二代认为"不变量破了就是存储坏了,继续跑只会写出更多脏数据"。
所以错误分了类(errors.ts):StorageRequestError 只让那一次读失败,
其余让整个 Session 进入失败态。
十、提交作为一等公民
durable 里最重要的类不是 Storage,是 SessionImpl。
session/session.ts:191-217 的类注释是全包写得最好的一段,值得逐句读:
* Session kernel: one mutation line, the loaded document tracker cache, and * committed publication. * * Group commit: the line runs one job at a time, a commit's callback and * settlement; a commit with writes then joins the writer's pending batch ... * The writer stores every commit admitted while no call is in flight in one * `commit()` call, off the line, and publishes them one by one, in line order, * a macrotask apart ...10.1 一条变更线
所有写操作排成一条线(mutation line),一次只跑一个 job——一次 commit 的回调加收尾。
排队的原因:Tx 允许写之前先读(比如"这个会话存不存在"),两个事务并发读同一状态
再各自写就会互相覆盖。串行化是最便宜的解法。
10.2 组提交
串行有个直接代价:句句同步就慢了。他们的解法是把没有调用在飞的期间的提交合成一个:
line: [job1] [job2] [job3] ... ← 每个都只看内存writer: └──── 一次 commit(3 个 batch) ────┘ ← 离线攒的publish: batch1 → (macro) → batch2 → (macro) → batch3发布是一个一个来、中间隔一个 macrotask 的:每个 batch 发布后会唤醒它的 await,
那些后续代码得先跑完再发下一个,否则会看见比自己晚的提交。
一个工具循环里连发五次追加,存储层只写一次。
10.3 延迟提交
另一类写入不急着落盘:"这个文件我读过"、"已经提示过用户一次"。 这类状态丢了不影响正确性,但每次都写盘就是浪费时间。
CommitPersistence 就是干这个的:先在内存提交,变更按文档折叠,
固定在缓存里,等四个时机之一才落盘(session.ts:198-201):
- 下一次读/写这个文档的提交;
- 到这个文档的截止时间(默认 1,000 ms);
- 缓存把它的 tracker 踢出去;
close()。
四个时机的意思:只要有人要看,就必须先落盘,读者不会看到幽灵数据。 代价写清楚——进程被 kill 时最后 ≤1 秒的进度会丢,这是取舍不是 bug。
10.4 失败即终态
:212-217:
* Storage failures are final. Every Storage call goes through one guard: the * first error a Storage method throws, other than for a cancelled caller, * fails the Session ... Nothing retries: transient errors are the Storage's to * retry. Reopening recovers from what was committed.一句话:任何 Storage 错误 = 这个 Session 死了。
当前调用拿到原错误,之后所有调用拿到 SessionFailed,监听器立即用错误回调,
然后 Session 自己关掉自己。
"transient errors are the Storage's to retry"——重试解在错误的层。网断、磁盘抖动, 存储实现最清楚怎么退避;让它自己处理,上层只负责一个干净的失败。
对照第一代:_appendEntry 失败回滚三件然后 throw(3.4),
调用方(TUI)拿到异常弹个错,会话继续跑,下一句话又能追加成功。
两种都合理,区别是代价模型不同:
| 第一代 | 第二代 | |
|---|---|---|
| 一次写失败 | 回滚这一条,继续 | 整个 Session 失败 |
| 为什么 | 每条 entry 独立 | 一次提交可能同时改了 entry、文档、任务 |
| 恢复手段 | 重试那一句 | 重开 Session(从已提交状态恢复) |
左边的模型成立的前提是"一次追加只动一处"。一旦你允许一个提交改三处, 部分成功就会留下不一致的组合,所以只能全死。
10.5 几个数字
这些常数把设计意图钉得很死:
| 常数 | 值 | 哪 | 管什么 |
|---|---|---|---|
MAX_OUTSTANDING |
256 | session.ts:121 |
线上未交付的 job 数上限(按个数,不按字节) |
| 默认文档保留 | 600,000 ms | session.ts:165 |
无观察者的文档多久没读写就踢出缓存 |
DEFAULT_PERSIST_WITHIN_MS |
1,000 | session.ts:181 |
延迟提交的默认窗口 |
LATEST_CAPACITY |
4096 | conversation-tails.ts:8 |
缓存多少个会话的最新 entry |
MARKER_CAPACITY |
256 | conversation-tails.ts:11 |
缓存多少个会话的最新 head 标记 |
SCAN_PAGE_SIZE |
256 | forks.ts:15 |
分叉时扫文档的页大小 |
限流按个数不按字节:单次提交能装多少已被输出上限卡住,个数 × 单次上限就是可控上界。
十一、完整链路
两条链路,各取"你输入一句话"到"数据落定"的全过程。
11.1 写入
你敲回车 | +--[第一代] appendMessage("我...") | | | +-> 构造 entry { type, id, parentId: leafId, timestamp, message } | +-> _appendEntry:push 数组 / set byId / leafId = entry.id | +-> _persist:首次一次性写全部 entry,之后 appendFileSync 一行 | +-> 失败则回滚三件(数组 / byId / leafId) | +--[第二代] conversation.submit({ type: "input", content: "我..." }) | +-> 一个 commit:写 submission + entry(pi.user) + 改 pi.inbox +-> 进入变更线排队,拿到 job index +-> writer 把无调用在飞的提交合成一个 batch 集合 +-> storage.commit(batches, receive) | +-> 先写各文档的 sidecar 记录 +-> 再一次性 append main.jsonl 的 marker +-> 先 receive 回执,再按 line order 逐个发布两边的第一个分岔就在第一行:左边 appendMessage 直接就是"写文件",
右边 submit 只是"登记一个意图",真正落盘在几层之下。
11.2 重启恢复
进程启动,打开会话 | +--[第一代] loadEntriesFromFile(path) | | | +-> 1 MiB 块读 + StringDecoder 拼多字节字符 | +-> 按 \n 切行,JSON.parse 失败的行静默丢弃 | +-> 末尾残行:丢弃 + 补一个换行 | +-> 首行验 header,不是 session 就返回 [] | +-> migrateToCurrentVersion:v1→v2→v3,需要时全文件重写 | +-> _buildIndex:leafId 反复覆盖,终值 = 文件最后一条 | +-> buildSessionContext:回溯 → 裁压缩 → 投影编辑 | +--[第二代] Harness.open(storage) → recover() | +-> 校验 main.jsonl 的 seq 严格递增(破则抛 Corruption) +-> 删除遗留 *.reclaim +-> 读所有 sidecar,校验 seq/ordinal 递增 +-> 找每个文档最新的 base 快照 +-> 重放 marker,重建内存状态与 conversation tails +-> harness.resume():继续上次没跑完的任务最下面一行是两代最本质的差别:第一代恢复的是"数据",第二代恢复的是"工作"。
第一代不知道上次那个工具调用是不是跑完了,只能等下一次请求时用
transform-messages.ts 把那道口子补上(7.2)。第二代用 resume() 把没跑完的任务
重新拉起来——任务有阶段和检查点,"跑到哪了"是个持久事实,不是猜的。
十二、工程暗坑
下面每一条都是读代码时真卡住过的地方。
1. leafId: null 和 leafId: undefined 不是一个意思。
buildSessionPath 里 null 直接返回空路径(:397-399),undefined 则回退到"文件最后一条"(:403)。
传错一个值,你会得到完全相反的上下文。
2. 回退状态不落盘。
branch() 只改内存 leafId(:1589-1594),不产生 entry。
重启后回到"最后一次实际对话",不是"最后停留的位置"。做"继续上次会话"功能时这是真坑。
3. 断链是无声的。
buildSessionPath 遇到不存在的 parentId 时循环自然结束(:412),不抛错。
坏行被跳过后整条子树直接消失——查问题得自己写脚本对 id。
4. 8 位 id 只在单个文件内唯一。
generateId 只拿当前 byId 去重(:277-284),分叉出的新文件可能撞 id;
parentSession 只是路径字符串,所以不出事——但别拿它做跨文件引用。
5. label 是树节点,不是元数据。
给一条消息打标会插一条真 entry,后面的 entry 可能挂在它下面。
这就是 createBranchedSession 要花 30 行代码重挂 label 的原因(:1649-1678)。
6. 两条 compaction 只能有一条出摘要。
buildSessionProjection 的 index > 0 ? [](:561-564)不是防重复,是防"压缩两次之后 token 反而变多"。
改动这段逻辑前先把两个 compaction 叠加的场景跑一遍。
7. 位置不能当身份。
v1→v2 把 firstKeptEntryIndex(下标)换成 firstKeptEntryId(id)(:301-311)。
文件一旦重写或分叉,下标就指错。存位置的地方,迟早要还。
8. 懒落盘的判定基准是 user 消息。
:1161-1164 的注释写着 #10000:按"有 assistant 回复"判定,第一轮请求卡死时用户输入会全丢。
任何"延后创建资源"的逻辑都要想清楚:以哪个事件为信号,才能保证半途崩溃也不丢数据。
9. durable 的 Storage 错误不重试。
第一个错误就让整个 Session 变 SessionFailed(session.ts:212-217)。
想重试必须在 Storage 实现里包一层,不能指望上层。
10. durable 的 JSONL 把全历史留在内存。
README 的 Storage 表格直接写了:"Keeps the whole history in memory too, so memory grows with it;
use SQLite for long-running agents." 数据量一大就换 SQLite,别等 OOM 再换。
11. 延迟提交的 1 秒是真实的数据丢失窗口。
默认 persistWithinMs = 1_000(:181)。kill -9 时最后 1 秒的进度没了。
要严格不丢,把窗口设成 0(每次读/写就落盘),代价是吞吐。
12. 一个 storage 只能一个进程开。 没有跨进程锁(README 写得很明确)。两个进程开同一个 SQLite 库, 出事的时候不会报错,只会在某天发现数据错乱。
十三、自己动手验证
环境:v1.4.0 / node v24.12.0 / Windows 24H2。每条判据都是这一版实跑的输出。
五个实验,从简到难。前四个只靠一个会话文件,第五个要跑 durable 的示例。
实验 1:看一个真实会话文件的结构
cat > /tmp/peek.mjs <<'EOF'import fs from "node:fs";const rows = fs.readFileSync(process.argv[2], "utf8") .split("\n").filter(Boolean).map((l) => JSON.parse(l));const [head, ...entries] = rows;console.log("header:", head.id, head.version, head.cwd);for (const e of entries) { console.log(e.id, e.parentId ?? "(root)", e.type);}console.log("entries:", entries.length);EOFnode /tmp/peek.mjs ~/.pi/agent/sessions/--home-you-proj--/*.jsonl# PS 用 here-string 代替 heredoc:把 <<'EOF' 与 EOF 之间的 JS 逐字放进来@'…(与左例逐字相同的 JS)…'@ | Set-Content peek.mjs -Encoding utf8node peek.mjs "$env:USERPROFILE\.pi\agent\sessions\--home-you-proj--\*.jsonl"判据:parentId 会指向前面的某个 id,不一定是上一行。
找到第一处"不连续",那就是你哪次回退留下的分叉点。
实验 2:手搓一个分叉,看路径怎么选
cat > /tmp/branch.mjs <<'EOF'import fs from "node:fs";const file = "/tmp/branch.jsonl";const head = { type: "session", version: 3, id: "s1", timestamp: new Date().toISOString(), cwd: "/tmp" };const msg = (id, parentId, text) => ({ type: "message", id, parentId, timestamp: new Date().toISOString(), message: { role: "user", content: text } });const rows = [head, msg("a1", null, "问题一"), msg("a2", "a1", "问题二"), msg("b1", "a1", "换个问法")];fs.writeFileSync(file, rows.map((r) => JSON.stringify(r)).join("\n") + "\n");// 下面这段就是 buildSessionPath 的同款逻辑const all = rows.slice(1);const byId = new Map(all.map((e) => [e.id, e]));const path = [];let cur = byId.get("b1");while (cur) { path.push(cur); cur = cur.parentId && byId.get(cur.parentId); }const ids = path.reverse().map((e) => e.id + ":" + e.message.content);console.log(ids.join(" -> "));EOFnode /tmp/branch.mjs@'…(与左例逐字相同的 JS)…'@ | Set-Content branch.mjs -Encoding utf8node branch.mjs预期输出:a1:问题一 -> b1:换个问法。
a2 在文件里排第 3 行,但它不在 b1 的路径上——文件顺序不等于树顺序。
把最后一行的 byId.get("b1") 改成 byId.get("a2"),你就能看到另一条分支。
同一份文件,两个入口,两条不同的上下文。
实验 3:插一条坏行,看它静默消失
cat > /tmp/tamper.mjs <<'EOF'import fs from "node:fs";const [mode, file] = process.argv.slice(2);const text = fs.readFileSync(file, "utf8");if (mode === "bad") { const lines = text.split("\n"); lines.splice(2, 0, '{"type":"message",oops'); fs.writeFileSync(file, lines.join("\n"));} else { const buf = fs.readFileSync(file); fs.writeFileSync(file, buf.subarray(0, buf.length - 25));}EOFnode /tmp/tamper.mjs bad /tmp/branch.jsonlnode /tmp/peek.mjs /tmp/branch.jsonl@'…(与左例逐字相同的 JS)…'@ | Set-Content tamper.mjs -Encoding utf8node tamper.mjs bad branch.jsonlnode peek.mjs branch.jsonl判据:entries 比刚才少一条,但没有任何报错。
这就是 4.3 的代价:能打开,但你看不见它坏在哪。
实验 4:截掉文件末尾,看修补动作
node /tmp/tamper.mjs cut /tmp/branch.jsonlwc -c /tmp/branch.jsonlnode /tmp/peek.mjs /tmp/branch.jsonl 2>&1 | tail -3wc -c /tmp/branch.jsonlnode tamper.mjs cut branch.jsonl(Get-Item branch.jsonl).Lengthnode peek.mjs branch.jsonl 2>&1 | Select-Object -Last 3(Get-Item branch.jsonl).Length判据:最后一条 entry 丢了,文件变大了一字节——那是 loadEntriesFromFile
补上的 \n(:668)。它不修复数据,只保证下一行不会粘在残句后面。
实验 5:跑 durable 的重启示例
cd packages/durablenode --conditions=source --experimental-strip-types \ test/examples/30-reload-and-restart.ts这个示例干的事:开一个 SQLite 存储,跑一轮工具调用,中途重载扩展, 再模拟重启进程,验证存下来的东西能接着用。
看完之后回头读 session/session.ts 的类注释,会突然变得很好读:
里面每一句(组提交、延迟提交、失败即终态)都在回答"崩溃之后怎么办"。
本章小结
- 第一代是一棵只追加的树,节点是 entry,
parentId指向父。 - 文件是 JSONL,一行一条;恢复就是重放。
- 分叉只挪指针,不复制历史。
- 树撑不住四件事:崩溃、并发、跨端、提交原子性。
- 第二代换成账本:一次提交是原子单位,位置不是身份。
概念回顾
| 术语 | 一句话 | 在哪 |
|---|---|---|
| 只追加树 | 节点只加不改,靠 parentId 连父 |
§二 |
| JSONL | 一行一条 entry,恢复 = 重放 | §三 |
| 分叉 | 换 parentId 或另存文件 |
§六 |
| 账本 | 一次提交为原子单位,带 marker | §八 |
| 位置不是身份 | firstKeptEntryId 取代下标 |
§五、§十四 |
练习
练习 1(读):§四 说恢复时遇到坏行静默跳过。 如果坏行正好是一棵子树的父节点,那棵子树会怎样?→ 回 §4.3。
练习 2(改):在任一会话 JSONL 末尾手工追加半行 {"type":,
再让宿主 load 一次。预期:静默跳过这一行,树照常加载;
回滚:删掉这半行,或直接删除会话文件重开。
常见误区
- 你会以为 压缩会把旧消息删掉;实际是 原 entry 还在,只是不进上下文; 证据 §五 与 M09 §一。
- 你会以为 第二代会话取代了第一代;实际是 两代并存,
coding-agent仍用自己的SessionManager;证据 §十四 的表。 - 你会以为 分叉要复制历史;实际是 只挪指针;证据 §六。
读完自检
三条,能不能不看稿说出来?
| 自检 | 一句话答案 | 不会就去 |
|---|---|---|
| 两代会话,最根本的分歧在哪? | 第一代"一行 entry 是原子单位",第二代"一次提交是" | §八、§十 |
为什么 firstKeptEntryId 不用下标? |
位置不是身份——会被重写、分叉、重排 | §14.1 |
| 恢复时碰到坏行怎么办? | 静默跳过,不阻断整棵树 | §4.3 |
十四、收束
14.1 三个可迁移的方法
一、区分"持久化什么"和"暴露什么"。
第一代的 context_edit 已经摸到这个思路:文件里保留全文,上下文里可以删。
第二代的 head、edits、model/data 分列,是把它做成了结构。
存储的完整性和读取的投影是两件事;混在一起(比如压缩时直接删旧消息),一定会后悔。
二、一致性的单位要跟语义的单位对齐。 一次追加只写一条记录时,"一行"就是合理的原子单位。 一旦一次操作要动 entry + 状态 + 任务,还按行来就必定出事。 看到"先写 A 再写 B",先问:A 和 B 之间崩了会怎样?
三、位置不是身份。
firstKeptEntryIndex → firstKeptEntryId 是个小改动,背后的原则很大:
只要一个东西会被重写、分叉、重排,就不能用下标引用它。
14.2 两代的分工
最后把本章对比表压成一张:
第一代 SessionManager |
第二代 durable.Session |
|
|---|---|---|
| 存储单位 | 一行 entry | 一次提交(marker) |
| 历史结构 | 树(parentId) |
线性 + head 标记 |
| 分叉 | 文件内挪指针 / 另存文件 | 新会话带 parent |
| 原子性 | 单条 | 整次提交 |
| 失败处理 | 回滚当前条,继续 | Session 失败,重开恢复 |
| 后端 | 只有 node:fs |
JSONL / SQLite / IndexedDB / DO |
| 恢复的是什么 | 数据 | 数据 + 未完成的工作 |
| 适合 | 单机 CLI | 需要恢复/多端/多会话的宿主 |
两代不是替代关系。截止 v1.4 的代码快照,coding-agent 仍然用它自己的
SessionManager;packages/durable 是并行的另一条线,被 harness/ 之上的一整层使用。
所以"会话搬到独立运行时"这句话,准确的说法是: 会话有了第二个实现,那个实现把会话从"文件格式"升级成了"运行时内核"。
14.3 下一站
M11 进 durable 的上面两层:harness/ 里的任务调度、工具任务、生成任务。
本章只讲了"提交怎么落盘",还没讲"谁在制造提交"。
那个答案叫 task:一个带阶段和检查点的状态机。 它才是"崩溃之后能接着跑"的真正原因——存储只是把它的状态记下来。
下一章:M11 durable——把"崩溃后接着跑"拆成三层:状态机、调度器、generation 交接。
想亲手写一份最简 JSONL 会话存储?Part E 的 E06 用 37 行造了同构的追加写 + 逐行读,坏行报行号。
本章源码索引
| 文件 | 行数 | 职责 |
|---|---|---|
coding-agent/src/core/session-manager.ts |
2,029 | 第一代全部:entry 类型、JSONL、迁移、路径、投影、分叉 |
ai/src/api/transform-messages.ts |
257 | 请求前修补孤儿 tool call(7.2) |
durable/src/session/session.ts |
2,105 | Session 内核:变更线、缓存、组提交、失败即终态 |
durable/src/session/transaction.ts |
1,293 | Tx:entry / 文档 / 任务 / 文档拷贝 |
durable/src/session/writer.ts |
362 | 批写入与按行发布(PartSpec / gate) |
durable/src/session/cached-storage.ts |
379 | 文档缓存与作用域 |
durable/src/session/conversation-tails.ts |
116 | 每会话最新 entry / head 标记的 LRU 缓存 |
durable/src/session/forks.ts |
98 | 分叉时的文档拷贝(asOf / current) |
durable/src/session/keys.ts |
275 | 提交键编码(appendKey / conversationKey 等) |
durable/src/storage/jsonl/storage.ts |
908 | marker + sidecar 格式、commit()、recover() |
durable/src/types.ts |
1,446 | EntryRecord / ConversationRecord / Storage 契约 |
durable/src/entries.ts |
35 | 六个内置 entry kind 的声明 |
durable/src/harness/context.ts |
383 | head 标记到上下文区间(deriveContext) |
durable/src/harness/harness.ts |
612 | fork() / create() / conversation 句柄 |