把完成的历史追加成一棵树

#你将得到什么

第 09 章结束后，Agent 能把多次运行的消息留在内存里。进程一关，这些消息仍会 消失；如果把历史只当成一个可以随时截短的数组，用户回到旧消息重试时，另一条尝试 还可能被永久删掉。

本章只增加一种复杂性：给已经完成的消息一个不会改变的身份，并把它追加到磁盘。 完成后，你会得到：

• pathTo()：从指定叶子沿 parentId 找回一条分支；
• parseSessionEntry()：把磁盘里的 unknown 收窄成可信的记录；
• InMemorySessionStore：先在没有文件系统干扰的环境中固定副本与顺序；
• recoverJsonl()：只接受以换行提交的完整记录，并报告未提交的尾部；
• JsonlSessionStore：在单个 writer 内按调用顺序追加；一次写入可能半途失败后， 不再继续碰文件；
• messagesOnPath()：从选中的分支取回完整消息，不丢工具调用和工具结果。

本章的核心约定是：

已经提交的记录不原地修改，也不删除。要从旧位置继续，就在旧记录下面追加一个新 孩子。

#为什么第 10 章放在这里

持久化不能早于消息协议和 Agent 生命周期。

如果还没有第 03 章的完整消息结构，你只能保存纯文本，工具调用、工具结果和错误 状态都会丢失。如果还没有第 09 章的运行边界，你也不知道该保存完成消息，还是正在 变化的流式文本、取消控制器和临时队列。

持久化又必须早于第 11 章的上下文压缩。压缩要从一条真实历史中派生较短的模型输入； 如果原始历史会被覆盖，压缩就变成不可逆的数据改写，无法重新计算，也无法审计。

因此顺序是：

第 03、07、09 章：什么是一条完成消息，一次运行在哪里结束
          ↓
第 10 章：把完成消息保存为不可改写的历史
          ↓
第 11 章：从历史派生有限大小的模型输入

这也是本章暂时不加入 compaction entry 的原因。先把“保存事实”做稳，再学习“怎样 派生更短的上下文”。两个问题放在同一章，会让你无法判断错误发生在磁盘历史，还是 上下文选择。

#先建立全景

运行中的事件、模型消息和磁盘记录属于三层：

运行事件
  text_delta、tool_start、进度、界面刷新
          │ 运行结束后只留下完整结果
          ▼
完整消息
  user / assistant / toolResult
          │ 加上 id、parentId、timestamp
          ▼
会话记录
  message / metadata

第一层可以很频繁，也可能只完成一半，不适合直接当长期历史。第二层保留模型再次 推理所需的完整结构。第三层再给每条事实加上身份和父节点，让同一段历史可以长出 多条分支。

#开始动手：先进入正确的仓库

练习命令在教学历史仓库 pi-course 中运行，不是在教材站点目录，也不是原始 pi 仓库：

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

确认 pwd 的最后一段是你刚创建的练习目录。生成器会保留第 09 章实现，加入第 10 章 测试，并用无答案脚手架创建：

packages/pi-course/src/session.ts

本章只修改这一个源文件。不要切换到 target，也不要从后续章节复制 compaction 类型。

#第一步：用 parentId 找回一条分支

本章只有两种记录：

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

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

id 回答“这是哪条记录”，parentId 回答“它接在哪条记录后面”。数组下标不能代替 id：追加新分支、导出或迁移文件时，下标都会变化。

pathTo(entries, leafId) 的职责要写窄：

1. 所有 id 必须唯一。即使两个不同对象使用同一个 id，也要拒绝；
2. leafId 必须存在；
3. 只沿选中 leaf 的祖先链检查缺失 parent 和环；
4. 返回从根到 leaf 的新数组，而且其中的记录也不能与输入共享可变引用。

本章允许多个 root，也不检查未选中分支的缺失 parent。那属于“检查整座树”的另一项 能力。pathTo() 只回答一个问题：这条指定路径能否安全恢复？

回溯过程可以写成：

先扫描 entries
  → 建立 byId
  → 遇到重复 id 立即失败

从 leaf 开始
  → 把 current.id 放进 seen
  → 把 current 放进 reversePath
  → parentId 为 null 时到达根
  → 否则查找 parent
  → 查不到：报告 child id 与 parent id
  → seen 已包含该 id：报告形成环的 id

最后 reversePath.reverse()

错误消息要包含相关 id。只有“missing parent”而没有孩子与父节点，调试真实文件时 仍然不知道该找哪一行。

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

#第二步：磁盘读出的对象仍然是 unknown

TypeScript 的 SessionEntry 只约束已经通过类型检查的代码。下面这句不会让磁盘 内容自动变安全：

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

JSON.parse() 的结果来自进程外。它可能缺字段、使用错误的 type，也可能把 message 写成完全不同的对象。as SessionEntry 只让编译器闭嘴，没有检查任何 运行时事实。

先写一个很小的边界。这里要检查“普通 JSON 对象”，不能只检查“不是数组的对象”； Map、Date 和类实例也满足 typeof value === "object"，却不是课程允许的 JSON 对象：

function jsonObjectAt(
  value: unknown,
  path: string,
): Record<string, unknown> {
  if (value === null || typeof value !== "object" || Array.isArray(value)) {
    throw new Error(`${path} 必须是 object`);
  }
  const prototype = Object.getPrototypeOf(value);
  if (prototype !== Object.prototype && prototype !== null) {
    throw new Error(`${path} 必须是普通 JSON object`);
  }
  return value as Record<string, unknown>;
}

然后逐层收窄。不要先把整个对象强转，再从里面取字段。至少要检查：

“JSON-safe”表示 null、布尔、字符串、有限数、上述值组成的数组或普通对象。函数、 undefined、BigInt、Map、非有限数和循环引用都不应进入持久层。这个检查也要 覆盖工具调用的 arguments 与工具结果的 details，否则 JSON.stringify() 可能 静默丢字段，或把 Infinity 写成 null。

递归检查需要同时携带字段路径和当前祖先集合。最小控制流如下：

jsonValueAt(value, path, ancestors)
  ├─ null / boolean / string：直接返回
  ├─ number：只接受有限数
  ├─ array 或普通 object：
  │    ├─ 已在 ancestors：报告 path 形成循环
  │    ├─ 加入 ancestors
  │    ├─ 递归检查每个孩子
  │    │    array 使用 path[index]
  │    │    object 使用 path.key
  │    └─ 在 finally 中移出 ancestors
  └─ 其他类型：报告 path 不能写入 JSON

ancestors 只记录当前递归路径，不是全局“见过的对象”。同一个普通对象可以在两个 并列字段中出现；只有沿当前路径再次遇到自己才是环。

不要一次写完整棵解析器。按下面的顺序施工：

1. 先完成普通对象、非空字符串、有限数和 jsonValueAt()；
2. 再完成 entry base 与 metadata，让最小合法记录通过；
3. 依次加入文本块、user、assistant、toolResult，最后由 type 和 role 分派；
4. 最后检查未知字段，并确认返回值是新对象。

解析成功后返回新对象。这样 parseSessionEntry() 同时完成运行时验证和所有权交接： 调用者后续修改原始输入，不会改变返回结果。

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

#第三步：先在内存中固定数据所有权

Store 收到一条记录时，不能把调用者的对象引用直接塞进内部数组：

const pending = store.append(entry);
entry.message.content[0].text = "调用后又被改了";
await pending;

落入 Store 的必须是调用 append() 那一刻的内容。读取也一样：

const first = await store.entries();
first[0].id = "外部修改";
const second = await store.entries();
// second 仍应保存原 id

这形成两条所有权边界：

调用者对象 ──调用时深复制──▶ Store 内部
Store 内部 ──每次读取深复制──▶ 调用者

InMemorySessionStore 不需要模拟磁盘故障。它负责把三件事做清楚：

1. append 在调用时验证并取得快照；
2. 多次 append 保持调用顺序；
3. 每次读取返回独立副本。

追加式并不等于“什么都能 push”。同一个 Store 中的 id 仍要唯一；非 root 记录的 parent 必须已经存在。先写孩子、后写父亲会让中间状态无法恢复，本章直接拒绝。

这里有两个不同的检查时机：

• 调用 append() 时，立即检查记录结构并取得深副本；JSONL Store 还会立即序列化；
• 轮到该 FIFO 任务执行时，再根据 Store 当时已经提交的 id 检查重复和 parent。

因此可以连续调用 append(parent)、append(child) 而不逐个 await。child 排在 parent 后面，轮到它时能看到已经成功提交的 parent。不要在调用 child 的瞬间读取旧 Store 状态并误报 parent 缺失。

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

#第四步：把换行当成提交标记

JSONL 一行保存一个 JSON 对象。本课程再增加一条明确规则：

只有以换行结束的记录才算提交。

这条规则让恢复不必猜测“末尾看起来完整的 JSON”是否真的写完。结果表如下：

空行不产生 entry，也不报错，但仍占一个物理行号。例如 "\nBAD\n" 中的坏记录必须 报告第 2 行。这样人工排版不会产生伪记录，错误行号仍能直接对应编辑器中的文件位置。

最后一项很重要。跳过中间坏行后，后面的 parentId 可能指向已经被吞掉的记录。继续 返回“尽量恢复”的数组，会把损坏伪装成一棵健康的树。

warning 是结构化数据：

type SessionWarning = {
  code: "unterminated_tail";
  line: number;
};

调用者可以据此提示用户、进入只读模式或发起修复。不要只打印一句日志后继续写。

recoverJsonl(text) 是纯函数。它只解析字符串，不删除尾部，也不改文件。可以先找出 文本是否以 \n 结束，再只遍历已经提交的行。每一行先 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

#第五步：一次可能半写的失败会让 writer 失效

appendFile() 返回失败，不代表磁盘一个字节都没写。它可能已经留下：

{"id":"a",...}\n
{"id":"b","parent

如果同一个 writer 随后继续追加 c，文件会变成：

{"id":"b","parent{"id":"c",...}\n

原本可识别的未提交尾部被拼成了一条以换行结束的坏记录。下次恢复只能把它当作已提交 损坏，连此前可读的前缀也无法正常打开。

因此 writer 需要一个很小的状态机：

ready
  ├─ 调用时校验或序列化失败
  │     → 只拒绝当前 append，仍是 ready
  ├─ 底层 append 成功
  │     → 回到 ready
  └─ 底层 append 失败，可能已经半写
        → tainted
             ├─ 后续 append 不再调用底层写入
             └─ read/entries 返回最初的写入错误

三种状态的公开行为如下：

needs-repair 描述打开文件时已经观察到的断尾；tainted 描述当前实例可能刚刚造成的 半写。前者仍允许只读恢复，后者连重新读取都不能假装可靠，必须创建新实例重新检查 文件。

序列化失败和 I/O 失败必须分开。前者尚未碰文件，下一条合法记录仍可以写；后者无法 知道写了多少，当前 writer 必须停下。

为了让测试控制因果顺序，JsonlSessionStore 接收一个很窄的文件 I/O 接口。测试可以 让第一次 append 写入半行后抛错，并记录第二次 append 是否还调用了底层方法。不要用 大文件、sleep 或“通常谁更快”证明 FIFO。

每次 append() 的顺序是：

调用时
  → parseSessionEntry(entry)
  → JSON.stringify(snapshot) + "\n"
  → 把固定字符串加入单实例 FIFO

轮到本次写入时
  → 若 writer 已 tainted，直接返回原错误
  → 调用 io.appendFile()
  → 失败则保存原错误并进入 tainted

Promise FIFO 只需要一种形状。下面是排队骨架，不是完整 Store 答案：

const operation = this.tail.then(async () => {
  // 先检查 writer 状态和当前已提交 id
  // 再执行本次 io.appendFile(file, line)
});

// 内部队列继续结算后续任务；调用者仍拿到原 operation 的成功或失败。
this.tail = operation.catch(() => undefined);
return operation;

固定的 line 必须在创建 operation 之前算好。任务真正执行时再检查依赖 Store 当前内容的重复 id 与 parent；底层 I/O 失败则保存第一次错误，后续任务开始时先读 这个状态。

打开已有文件时，如果 recoverJsonl() 报告未提交尾部，Store 可以读取此前的完整 记录，但必须拒绝继续追加，并提示先修复文件。本章不自动截断用户历史。

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

#第六步：只把选中分支的完整消息交回 Agent

磁盘的物理行顺序不是模型上下文。假设文件中依次写入：

a user
b assistant(toolCall c1)  parent=a
r toolResult(c1)          parent=b
d assistant(text)         parent=a
m metadata                parent=d

选择 r 时，消息是 a、b、r；选择 m 时，路径是 a、d、m，但交给模型的消息 只有 a、d。两条分支不能混在一起，metadata 也不是模型消息。

messagesOnPath(entries, leafId) 可以复用 pathTo()，再筛出 type === "message"。关键是保留整个 AgentMessage：

• assistant 中的 toolCall.id/name/arguments 不能只剩一段文本；
• toolResult 的 toolCallId、isError 和 details 不能丢；
• 返回消息不能与输入 entry 共享嵌套对象。

不要先调用 textOf()。它本来就是有损的界面投影，只保留文本块，无法重建工具往返。

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

#故意把它弄坏

先找到 JsonlSessionStore 在底层 append 失败后记录 tainted 的分支。临时改成 “当前 Promise 失败，但队列仍可继续写”，或删除后续任务开始前的 tainted 检查。

#本章没有证明什么

14 项测试只规定本章明确拥有的边界。它们没有证明：

• 多个 JsonlSessionStore 实例或多个进程能安全写同一个文件；
• appendFile() 完成后，字节已经通过 fsync 刷到物理介质；
• 任意文件系统都能原子追加一整行；
• 未提交尾部会被自动备份、截断或修复；
• 多个 root 或未选中分支已经通过整库完整性检查；
• BOM、CRLF、旧格式 header 或版本迁移已经处理；
• session 已经自动接到 Agent.run_end；本章只提供持久层和消息恢复函数；
• compaction、摘要、token budget 或上下文裁剪已经实现；
• 恶意超大文件、深度耗尽和磁盘配额已经受到资源限制。

“同一文件只有一个 writer”是调用者必须满足的前置条件，不是这个类实现了文件锁。 tainted 也不是自动修复；它只是阻止当前实例在不知道文件状态时继续扩大损坏。

#本章验收

#可选迁移练习

更进一步的练习是设计显式的 repairUnterminatedTail()。先写授权和失败测试：保存 原文件备份、只截断最后一个未提交尾部、已有完整行逐字节不变、替换失败不覆盖原文件。 在这些条件写清之前，不要给 open() 增加自动修复。

#小结

会话文件不是 transcript 数组的磁盘副本。每条完成事实拥有唯一 id，parentId 把它接到上一条记录；从旧节点继续时只追加新孩子，所以过去的另一条尝试仍然存在。

外部 JSON 必须逐层收窄，Store 在调用时取得输入快照，并在读取时交出新副本。行末 换行是提交边界：换行结束的坏行立即失败，无换行尾部只读恢复。一次底层写入失败可能 已经留下半行，因此当前 writer 进入 tainted，不能继续追加。

下一章会从 messagesOnPath() 得到的真实分支派生有限大小的模型输入。原始 session 仍保持追加式，不会为了节省上下文而改写过去。