Pi Agent 源码级教程
M10

会话 —— 从会话树到持久运行时

11,480 字 · 含 513 行代码 · 约 56 分钟

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 三个必须

判断一个会话存储设计好不好,用三个问题量:

  1. 回退不能丢数据。你嫌 Agent 答得不好,想退回上一轮重问。 如果实现方式是"删掉后面的消息",那另一条分支就永久没了。
  2. 崩溃不能丢半截。第 3 轮工具调用跑到一半进程被 kill。 重启后,这轮要么能续上,要么能干净地判定失败——不能留个既不算成功也不算失败的幽灵状态。
  3. 换后端不能换语义。今天存文件,明天想存 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:

ts
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 树上长一次

抽象讲"树"没人看得懂。用一个六节点的小会话:

text
1. 切模型到你想要的(model_change)2. 你问:"salt 校验为什么失败?"3. Agent 调 read 读 auth.ts(assistant + toolResult)4. Agent 答:"第 23 行没编码"5. 你不满意,回退到 26. 换个问法:"先看 hash 函数"

节点按顺序长成这样(parentId 用上一行的 id 简写):

text
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:

ts
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 里的分隔符换成 -,前后各包两个 -。举例:

text
/home/you/proj          → --home-you-proj--D:\code\pi              → --D-code-pi--

于是 ~/.pi/agent/sessions/ 下每个工作目录一个子目录,会话跟着项目走。

文件名在 :1079-1080:

ts
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):

ts
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 对象, 下面为了排版展开了,字段一个没删:

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:

ts
/** * 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):

ts
_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:

ts
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,核心是这段循环:

ts
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:

ts
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;

两件事:

  1. 先验 header 再动文件。如果第一行不是合法 session header,返回空数组, 一个字节都不改。这个顺序很重要——_setSessionFile(:1029-1046)靠这个区分 "空文件"和"不是 pi 会话的文件":空文件补 header,非空但解析不出就抛错并保持原样。
  2. pending 非空就给文件补一个换行。半截那一行本身没救了,但补上换行之后, 下次追加不会粘在它后面,把一整条新 entry 也污染掉。

代价是那半截 entry 丢了。丢的可能是半个工具结果,也可能是一整条用户消息。 第一代的取舍是:宁可丢一条,不能污染后面全部。

4.3 坏行静默跳过

parseSessionEntryLine(:616-624)和 parseSessionEntries(:355-370)都是同一个模式:

ts
try {	return JSON.parse(line) as FileEntry;} catch {	// Skip malformed lines	return null;}

不抛错,不警告,不计数。中间某一行坏了,前后照常加载。

这是"能打开就比打不开好"的工程选择。代价是损坏是无声的: 如果坏掉的是某条 entry 的父亲,那整条子树都从上下文里消失, 用户看到的是"我明明说过这句话",而日志里一个错都没有。

静默容错必须配一个外部可观测指标——第一代没有,这是它的债。

4.4 三版迁移

读到旧版本文件,_loadEntries(:1085-1101)会先迁移:

ts
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):

ts
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):

ts
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):

ts
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:

ts
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):

ts
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;}

三件事,用大白话说:

  1. 取路径上最后一条 compaction(循环覆盖 compaction,不留早期值)。
  2. 从 firstKeptEntryId 那条开始,到 compaction 之前,都算"保留段",逐条带上。
  3. compaction 之后的 entry 全部带上。

两个细节藏在代码里:

  • 跳过 system 消息(:506)。压缩边界会重写系统提示词, 保留段里的旧 system 消息属于"过期快照",带上就会和新的打架。
  • compaction 自己排第一位(:499)。摘要在消息序列里必须出现在 它概括的那些内容之前——虽然那些内容已经不在了。

这就是为什么 M09 说压缩是"墓碑":被压缩的 entry 还在文件里, 只是不再出现在这条路径的保留段里。

5.3 第三步:投影与上下文编辑

最后一层是 buildSessionProjection(:543-573)。它做两件额外的事。

事一:提取设置。 getSessionContextSettings(:418-433)沿路径扫三类 entry, 后者覆盖前者:

ts
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):

ts
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):

ts
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:

ts
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)解决这个:

ts
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"麻烦,因为有三处引用会失效。看核心循环:

ts
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):

ts
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 场景里越来越不成立。

考虑一次工具调用要落盘的东西:

  • 一条 toolResult entry;
  • 这次调用消耗的 token(usage entry);
  • 扩展自己的状态(比如"这个文件我读过",custom entry);
  • 如果有后台任务,任务走到了哪个阶段。

四条记录,四次 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:

ts
// 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 这个类的内部实现, 第二代把它拆成三层:

text
Storage(介质)   ← JSONL / SQLite / IndexedDB / Memory   ↑Session(内核)   ← 提交线、缓存、组提交、失败即终态   ↑Harness(运行时) ← 任务调度、工具、生成、压缩

这三层就是 M11 要展开的内容。本章后三节只讲最下面那半截: entry 长什么样、JSONL 怎么写、一次提交怎么变成一次落盘。


八、第二代:账本取代树

打开 packages/durable/src/types.ts:458-473,先看 entry 长什么样:

ts
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 的注释写得比任何二手解释都准:

ts
 * 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 给了两个容量常数:

ts
const LATEST_CAPACITY = 4096;   // 只存最新 entry ID 的会话数const MARKER_CAPACITY = 256;    // 连 head 标记整条一起存的会话数

两个数字差 16 倍:前者只存一个 ID,后者要存整条 entry(一条压缩摘要可能很长)。

8.3 分叉变成"新会话继承父会话"

types.ts:427-439:

ts
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,读时把父会话历史拼进来。

后者多一次拼接,换来两个好处:分叉可跨进程、跨后端、跨机器;一个会话的历史长度 也不再受"文件里有多少无关分支"影响。

调用的完整链路(三层,每层都短):

ts
// 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):

ts
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:

ts
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:

ts
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 里只留一个序号引用。

实际写出来是这样(真实文件里也是一行一条,这里为排版展开了):

text
# 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:

ts
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 的注释把不变量写得很死:

ts
 * 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 行加载不是一回事。 按顺序做五件事:

text
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 的类注释是全包写得最好的一段,值得逐句读:

ts
 * 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 组提交

串行有个直接代价:句句同步就慢了。他们的解法是把没有调用在飞的期间的提交合成一个:

text
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. 下一次读/写这个文档的提交;
  2. 到这个文档的截止时间(默认 1,000 ms);
  3. 缓存把它的 tracker 踢出去;
  4. close()。

四个时机的意思:只要有人要看,就必须先落盘,读者不会看到幽灵数据。 代价写清楚——进程被 kill 时最后 ≤1 秒的进度会丢,这是取舍不是 bug。

10.4 失败即终态

:212-217:

ts
 * 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 写入

text
你敲回车  |  +--[第一代] 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 重启恢复

text
进程启动,打开会话  |  +--[第一代] 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:看一个真实会话文件的结构

bash
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
powershell
# 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:手搓一个分叉,看路径怎么选

bash
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
powershell
@'…(与左例逐字相同的 JS)…'@ | Set-Content branch.mjs -Encoding utf8node branch.mjs

预期输出:a1:问题一 -> b1:换个问法。 a2 在文件里排第 3 行,但它不在 b1 的路径上——文件顺序不等于树顺序。

把最后一行的 byId.get("b1") 改成 byId.get("a2"),你就能看到另一条分支。 同一份文件,两个入口,两条不同的上下文。

实验 3:插一条坏行,看它静默消失

bash
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
powershell
@'…(与左例逐字相同的 JS)…'@ | Set-Content tamper.mjs -Encoding utf8node tamper.mjs bad branch.jsonlnode peek.mjs branch.jsonl

判据:entries 比刚才少一条,但没有任何报错。 这就是 4.3 的代价:能打开,但你看不见它坏在哪。

实验 4:截掉文件末尾,看修补动作

bash
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.jsonl
powershell
node 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 的重启示例

bash
cd packages/durablenode --conditions=source --experimental-strip-types \  test/examples/30-reload-and-restart.ts

这个示例干的事:开一个 SQLite 存储,跑一轮工具调用,中途重载扩展, 再模拟重启进程,验证存下来的东西能接着用。

看完之后回头读 session/session.ts 的类注释,会突然变得很好读: 里面每一句(组提交、延迟提交、失败即终态)都在回答"崩溃之后怎么办"。


本章小结

  1. 第一代是一棵只追加的树,节点是 entry,parentId 指向父。
  2. 文件是 JSONL,一行一条;恢复就是重放。
  3. 分叉只挪指针,不复制历史。
  4. 树撑不住四件事:崩溃、并发、跨端、提交原子性。
  5. 第二代换成账本:一次提交是原子单位,位置不是身份。

概念回顾

术语 一句话 在哪
只追加树 节点只加不改,靠 parentId 连父 §二
JSONL 一行一条 entry,恢复 = 重放 §三
分叉 换 parentId 或另存文件 §六
账本 一次提交为原子单位,带 marker §八
位置不是身份 firstKeptEntryId 取代下标 §五、§十四

练习

练习 1(读):§四 说恢复时遇到坏行静默跳过。 如果坏行正好是一棵子树的父节点,那棵子树会怎样?→ 回 §4.3。

练习 2(改):在任一会话 JSONL 末尾手工追加半行 {"type":, 再让宿主 load 一次。预期:静默跳过这一行,树照常加载; 回滚:删掉这半行,或直接删除会话文件重开。

常见误区

  1. 你会以为 压缩会把旧消息删掉;实际是 原 entry 还在,只是不进上下文; 证据 §五 与 M09 §一。
  2. 你会以为 第二代会话取代了第一代;实际是 两代并存, coding-agent 仍用自己的 SessionManager;证据 §十四 的表。
  3. 你会以为 分叉要复制历史;实际是 只挪指针;证据 §六。

读完自检

三条,能不能不看稿说出来?

自检 一句话答案 不会就去
两代会话,最根本的分歧在哪? 第一代"一行 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 句柄