从一棵会话树恢复当前对话

#先看这一棵树

第 09 章结束时，Agent 已经能完成多轮运行。现在把其中一次“读取 README”的对话保存 下来。每个完成对象都得到一个稳定的 id，并用 parentId 指向上一条记录：

追加顺序    id          parentId     内容
1           u-1         null         user: 读取 README.md，告诉我项目名
2           a-read      u-1          assistant: toolCall call-1 / read
3           r-read      a-read       toolResult call-1: # tiny-pi ...
4           a-final     r-read       assistant: 项目名是 tiny-pi
5           a-alt       u-1          assistant: 我无法读取该文件
6           meta-cwd    a-final      metadata: cwd=/workspace/tiny-pi

数组记录的是写入先后，parentId 表达的关系却是：

u-1
├── a-read
│   └── r-read
│       └── a-final
│           └── meta-cwd
└── a-alt

a-read 和 a-alt 都接在 u-1 后面，所以同一段历史长出了两个分支。旧分支没有被 覆盖，新的尝试也没有要求重写前面的记录。

假设界面当前选择的 leaf 是 meta-cwd。pathTo(entries, "meta-cwd") 返回：

u-1 → a-read → r-read → a-final → meta-cwd

这就是本章所说的 active path：调用者选中一个 leaf，pathTo() 沿 parent pointer 回到 root，再把顺序翻转为 root 到 leaf。Session 本身没有一个会偷偷变化的“当前指针”； 当前是哪条路径，由调用 pathTo() 时传入的 leaf id 决定。

模型需要的是消息，不是所有磁盘记录。对同一个 leaf 调用 messagesOnPath(entries, "meta-cwd")，得到：

user(u-1)
→ assistant(a-read, toolCall call-1)
→ toolResult(r-read, toolCallId call-1)
→ assistant(a-final)

meta-cwd 在路径上，但它是 metadata，所以不会进入 AgentMessage[]。a-alt 是 sibling， 也不会混入当前对话。若改选 a-alt，路径就只有 u-1 → a-alt。

本章的六段实现都在回答同一个问题：这棵树怎样从内存安全地落到磁盘，又怎样从指定 leaf 无损恢复为模型消息？

#从第 09 章进入第 10 章

第 09 章保留的是运行完成后的 AgentMessage。text_delta、AbortController、未消费的 队列和正在变化的局部文本仍属于一次运行，不写入 session。第 10 章只给完成事实增加 身份和父子关系：

第 09 章的完成消息
  user / assistant / toolResult
          │ 加 id、parentId、timestamp
          ▼
第 10 章的会话记录
  message / metadata
          │ 选择 leaf
          ▼
active path → AgentMessage[]

第 11 章才会从这条真实路径派生较短的模型上下文。当前 checkpoint 的 entry union 因此 只有 message 和 metadata 两种成员；compaction entry 留到下一章，由压缩需求引入。

练习在教学历史仓库 pi-course 中运行：

cd <你的工作区>/pi-course
npm run practice -w @pi/course -- 10 <新目录>
cd <新目录>
npm install

生成的 packages/pi-course/src/session.ts 已经声明公共类型和六处施工位。它能通过 TypeScript 编译，但每段行为都还没有实现。

#1. id 和 parentId 如何组成路径

会话记录共享三个基础字段：

interface EntryBase {
  id: string;
  parentId: string | null;
  timestamp: number;
}

type SessionEntry =
  | (EntryBase & { type: "message"; message: AgentMessage })
  | (EntryBase & { type: "metadata"; key: string; value: JsonValue });

id 回答“这是哪条记录”，parentId 回答“它直接接在哪条记录后面”。数组下标只说明 写入位置，不能表达分支。上例中 a-alt 的下标在 a-final 之后，逻辑 parent 却是 u-1。

pathTo(entries, leafId) 可以分成两次遍历：

第一次遍历 entries
  建立 byId
  发现任意重复 id → 立即失败

第二次从 leaf 回溯
  current 放进 reversePath
  parentId === null → 到达 root
  parent 不存在 → 报告 child id 与 parent id
  再次遇到 seen 中的 id → 报告环

reversePath.reverse()
返回每个 entry 的深副本

为什么重复 id 要在全数组检查，而缺失 parent 与环只检查所选路径？重复 id 会让 byId.get(id) 不再具有唯一含义，任何路径选择都不可信。相反，pathTo() 的契约只是 恢复指定 leaf；未选中的另一棵 root 或坏分支不应阻止健康路径被读取。

返回深副本也属于契约。若调用者改写返回值里的 toolCall.arguments.path，Store 中的事实 不能跟着变化。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 10.1" \
  packages/pi-course/dist/test/10-*.test.js

pathTo() 通过后，固定样例已经能得到 u-1 → a-read → r-read → a-final → meta-cwd。现在再处理一个现实问题：磁盘读回的对象 还不能直接当作 SessionEntry。

#2. JSON 进入程序时仍然是 unknown

TypeScript 类型只约束通过编译器的源码。下面的断言不会检查磁盘内容：

const entry = JSON.parse(line) as SessionEntry;

JSON.parse() 可能得到数组、缺字段的对象、未知 type，或一条结构残缺的 assistant message。正确边界是 parseSessionEntry(value: unknown)：从最外层开始，每验证一项事实， 才把类型收窄一层。

以固定树中的 a-read 为例，解析后的记录要完整保留这次工具请求：

entry a-read
  id: 非空字符串
  parentId: "u-1"
  timestamp: 有限数
  type: "message"
  message.role: "assistant"
  message.content[0].type: "toolCall"
  message.content[0].id: "call-1"
  message.content[0].name: "read"
  message.content[0].arguments: { path: "README.md" }

解析器需要逐层检查：

递归检查的目标，是让内存中的值经过 JSONL 往返后仍表示同一份数据。用固定记录做三个 小实验就能看出问题：a-read.arguments.path 若是 undefined，写入 JSON 时这个字段会 消失；metadata 中的 score: NaN 会在磁盘上变成 score: null；metadata 对象若引用 自身，序列化会直接抛错。解析器在写入前拒绝这三类结果：字段丢失、形状改变和无法 序列化。

因此 metadata 中的 object 要有普通对象的 prototype，数组中的每个位置都有实际值， 数值保持有限，并且嵌套值能继续通过同一检查。Lab 10.2 的测试证据再覆盖完整的非法值 矩阵；正文先用上面三个可观察结果说明这条边界为何存在。

解析成功后返回新对象。这样 parseSessionEntry() 同时完成两件事：证明形状符合协议， 并切断外部对象对内部记录的可变引用。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 10.2" \
  packages/pi-course/dist/test/10-*.test.js

#3. Store 在 append() 调用时取得快照

把固定树先放进内存，可以暂时排除文件系统，只观察所有权和顺序：

const first = store.append(u1);
const second = store.append(aRead);

// 两次调用以后，外部代码立刻修改原对象。
u1.message.content[0].text = "被改写";

await Promise.all([first, second]);

可靠的 Store 保存的仍应是调用 append() 那一刻的 u-1 与 a-read。如果等 Promise 真正排到队首才复制，调用者在等待期间的修改就会改变待提交事实。

因此 append() 分为两个时刻：

调用发生
  parseSessionEntry(entry) → 得到 snapshot
  snapshot 加入本实例 FIFO

任务轮到执行
  检查 snapshot.id 是否重复
  检查 snapshot.parentId 是否已经存在
  通过后提交 snapshot

parent 检查必须在队列中执行。a-read 调用时，u-1 的 Promise 可能还没完成；但只要 两次调用顺序是 u-1、a-read，FIFO 就应让 child 在 parent 提交后通过。

一个任务失败也不能毒死队列。缺 parent 的 entry 失败以后，下一条合法 root 仍应执行。 entries() 则先等待当前队列结算，再交出内部数组的深副本。

Promise FIFO 的关键不是某个库，而是把公开操作与内部 tail 分开：

const operation = this.tail.then(async () => {
  // 在这里按顺序检查并提交本次 snapshot
});

this.tail = operation.catch(() => undefined);
return operation;

调用者拿到原来的 operation，所以本次错误不会丢；内部 tail 把错误结算掉，下一项才能 继续排队。snapshot 必须在创建 operation 之前取得。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 10.3" \
  packages/pi-course/dist/test/10-*.test.js

#4. JSONL 用换行标记一条记录已经提交

内存中的六条记录落盘后，每行一个 JSON 对象：

{"id":"u-1",...}\n
{"id":"a-read","parentId":"u-1",...}\n
{"id":"r-read","parentId":"a-read",...}\n

本课程为 JSONL 规定一个明确边界：只有以 \n 结束的行才算 committed record。

若进程在写 r-read 时中断，文件可能停在：

{"id":"u-1",...}\n
{"id":"a-read","parentId":"u-1",...}\n
{"id":"r-read","parentId":"a-read"

前两行完整且已提交；最后一段含有非空白内容却没有换行，只是 unterminated tail。 即使尾部碰巧是一段可以单独 JSON.parse() 的完整 JSON，只要没有换行，本章仍把它 视为未提交。恢复结果返回前两条和结构化 warning：

{ code: "unterminated_tail", line: 3 }

若最后一段只有空白字符，它按空行忽略，不产生 warning。

另一种情况是坏内容后面已有换行：

{"id":"r-read","parentId":}\n

这是一条已提交的坏记录，recoverJsonl() 必须失败并报告物理行号，不能把它伪装成可 忽略尾部。空行可以跳过，但仍占用物理行号。

recoverJsonl(value) 是纯函数：切分文本，只遍历 committed lines，每行先 JSON.parse()，再交给 parseSessionEntry()。它报告恢复事实，不截断或改写文件。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 10.4" \
  packages/pi-course/dist/test/10-*.test.js

#5. JSONL writer 只在确定安全时继续追加

JsonlSessionStore.open(file) 先确保文件存在，再用 recoverJsonl() 读取 committed prefix。正常文件进入 ready；发现 unterminated tail 的文件仍可读取完整前缀，但进入 needs-repair，拒绝追加。本章不会擅自截断用户历史。

恢复出来的行还要按文件顺序重放树约束：每个 id 全局唯一，每个非 root 的 parent 必须 已经出现在更早的 committed line。否则 open() 立即失败。能通过 schema 不等于能组成 一棵可追加的历史。

正常追加仍沿用内存 Store 的两条规则：调用时快照、单实例 FIFO。不同之处是 snapshot 要立刻序列化为固定字符串：

append(entry) 调用时
  parseSessionEntry(entry)
  JSON.stringify(snapshot) + "\n"
  固定 line 加入 FIFO

任务轮到执行
  检查 writer 状态、重复 id、parent
  io.appendFile(file, line)
  成功后把 snapshot.id 加入 committed id set

这样即使调用者随后修改 a-final，排队等待的 line 也不会变化。每次成功追加后，旧文件 的全部 bytes 都应是新文件的前缀。

底层写入失败有更强的后果。appendFile() 抛错时，无法证明它一个字节都没有写；文件 可能已经留下半行。若当前 writer 继续把 meta-cwd 接在半行后面，原本可识别的断尾会 变成一条以换行结束的坏记录。因此状态是：

ready
├── 调用时校验/序列化失败 → 当前 append 失败，仍 ready
├── appendFile 成功         → 仍 ready
└── appendFile 失败         → tainted
                              ├── 后续 append 不再调用 I/O
                              ├── read/entries 抛最初的错误
                              └── 已排队任务也抛同一个错误对象

open 时发现断尾 → needs-repair
                   ├── read/entries 返回 committed prefix + warning
                   └── append 拒绝，不调用 I/O

tainted 描述当前实例可能刚造成了半写；它无法再相信自己的内存状态。重新 open() 同一个文件会重新检查磁盘：完整前缀仍可读，非空白无换行尾部进入 needs-repair。自动修复、文件锁和多进程写入都不属于本章。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 10.5" \
  packages/pi-course/dist/test/10-*.test.js

#6. active path 最终投影为完整消息

磁盘层已经能保存固定树，现在回到开头的输出。messagesOnPath() 的数据流很短：

entries + "meta-cwd"
  → pathTo()
  → [u-1, a-read, r-read, a-final, meta-cwd]
  → 只选择 type === "message"
  → [user, assistant(toolCall), toolResult, assistant]

“只选择 message”不等于“只取文本”。a-read 必须保留 toolCall.id、name、结构化 arguments 和 raw 参数；r-read 必须保留 toolCallId、toolName、isError 与 details。若先调用有损的 textOf()，下一次模型调用就无法知道 call-1 的请求和结果 如何配对。

pathTo() 已经返回 entry 深副本，messagesOnPath() 仍应保证公开结果不与输入共享嵌套 对象。测试会修改返回的 tool arguments 和 result details，再次投影时仍应得到原值。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 10.6" \
  packages/pi-course/dist/test/10-*.test.js
node --test packages/pi-course/dist/test/10-*.test.js

#用一次故障确认 writer 的边界

正常路径已经闭合：固定树可以追加、重开并投影。现在临时删除 JsonlSessionStore 在 I/O 失败后设置或检查 tainted 的分支。

#14 项测试证明到哪里

这些测试证明：单个 Store 实例按调用顺序工作；输入与输出使用深副本；指定路径能诊断 重复 id、缺 parent 与环；JSONL 能区分 committed bad line 和非空白 unterminated tail；一次 可能半写的 I/O 失败会让当前 writer 停止。

这些证据把 Store 固定在三个范围内：

• JSONL writer 面向单实例、单 writer 使用。appendFile() 完成表示操作系统接受了写入， 不增加跨进程锁、整行原子追加或 fsync 保证。
• 恢复函数保留已提交前缀，并把非空白断尾报告给调用者。tainted 只让当前 writer 停止 追加；备份、截断和修复仍是调用者的恢复决策。
• pathTo() 验证指定 leaf 的祖先链，不扫描所有未选分支，也不承担超大文件的资源治理。 Agent 接线、compaction 与 token budget 会在后续章节加入。

#本章验收

npm run build -w @pi/course
node --test packages/pi-course/dist/test/10-*.test.js

结果应为 14/14。随后用开头那棵树逐项说明：

1. 为什么追加 a-alt 不会覆盖 a-read → r-read → a-final。
2. 为什么 meta-cwd 在 active path 上，却不进入 AgentMessage[]。
3. call-1 经过写入、重开和投影后，哪些字段必须仍然存在。
4. 输入对象、Store 内部记录和公开返回值分别在哪一刻取得副本。
5. 为什么非空白无换行尾部可只读恢复，而换行结束的坏行必须失败。
6. 为什么一个 append I/O 失败后，当前 writer 不能继续尝试。

#小结

一份 session 同时有两种顺序：JSONL 保存追加顺序，parentId 保存逻辑关系。调用者给出 leaf，pathTo() 才能恢复 active path；messagesOnPath() 再跳过 metadata，保留完整的 user、assistant 与 toolResult。

外部 JSON 要从 unknown 逐层收窄。Store 在 append() 调用时取得快照，在公开读取时 返回新副本，并用 FIFO 让 parent 先于 child 提交。JSONL 的换行是提交标记：非空白的 无换行尾部只读恢复，换行结束的坏行立即失败。一次底层 append 失败可能已经写出半行，所以当前 writer 进入 tainted，不再碰文件。

下一章会把 pathTo() 返回的 active path 交给 buildContext()。它读取路径上最新的 compaction，把摘要转换成一条合成消息；metadata 与 compaction entry 本身不进入模型 消息。随后函数按完整 interaction 选择原始 message entries，返回消息的深副本，并在 keptEntryIds 中记录这些消息对应的 source entry id。整个投影只读 active path，原始 session 仍是 append-only，不会为了缩短上下文而改写过去。