深入理解 pi 03 / 06 目录 单页全本 学习手册 对比站

深入理解 pi/第 03 章

3.1

为什么不是「一个消息数组」

最简单的会话存储是一个数组:往后面 push,读的时候整个读出来。pi 不用这个方案,因为有三件事它做不到:

需求数组方案的困境树方案的解
回到某一步重来要么复制整个前缀,要么丢掉后面把 leafId 指回旧条目,下一条自然长在那里
压缩后仍能查原始消息摘要一旦写入,原文就没了摘要是新条目,原条目仍在文件里
崩溃后不丢数据整文件重写有窗口期一次追加一行,写多少算多少

代价也很明确:读的时候要重建。数组是 O(1) 读,树是 O(深度) 回溯。 pi 接受了这个代价,换来的是「历史不可变、状态可分支」。

3.2

条目:11 种类型,全都是事件

会话文件里的每一行是一个 SessionEntry,而它是 11 种类型的联合:

packages/coding-agent/src/core/session-manager.ts:183-194
export type SessionEntry =
  | SessionMessageEntry          // 一条对话消息
  | ThinkingLevelChangeEntry     // 思考档位变更
  | ModelChangeEntry             // 换模型
  | UsageEntry                   // 用量记账
  | CompactionEntry              // 压缩摘要
  | BranchSummaryEntry           // 分支摘要
  | CustomEntry                  // 扩展自定义状态
  | CustomMessageEntry           // 扩展自定义消息
  | ContextEditEntry             // 上下文编辑
  | LabelEntry                   // 打标签
  | SessionInfoEntry;            // 会话元信息

注意里面没有一个是「当前状态」字段。当前用什么模型、思考档位多高,都不是存在某个可变字段里, 而是由历史事件推导出来的:

packages/coding-agent/src/core/session-manager.ts:418-430
function getSessionContextSettings(path: SessionEntry[]): Pick<SessionContext, "thinkingLevel" | "model"> {
  let thinkingLevel = "off";
  let model: { provider: string; modelId: string } | null = null;

  for (const entry of path) {
    if (entry.type === "thinking_level_change") {
      thinkingLevel = entry.thinkingLevel;
    } else if (entry.type === "model_change") {
      // ...
    }
  }
}

这是「事件溯源」(event sourcing)的标准形态,好处很实际:回放到任意一步,得到的就是当时真实的模型与档位。 如果用可变字段,切到旧分支时你会带着新分支的模型设定,那是错的。

session-manager.ts:183(11 种条目)· :418(推导当前设置)

3.3

生长:四行代码定义的树

树的全部生长逻辑就在 _appendEntry 里,而它的核心只有一行 this.leafId = entry.id:

packages/coding-agent/src/core/session-manager.ts:1191-1196
private _appendEntry(entry: SessionEntry): void {
  this.fileEntries.push(entry);
  this.byId.set(entry.id, entry);
  this.leafId = entry.id;      // ← 下一次 append 的 parentId 就是它
  this._persist(entry);
}

配合 appendMessage 里那行 parentId: this.leafId,就有了完整的生长规则:

正常对话
每条新消息的 parentId = 上一条的 id,形成一条直线。文件里看不出树,因为退化成了链。
想回到第 3 条重来
把 leafId 设回第 3 条。下一条消息的 parentId 就是第 3 条——不需要复制任何历史,分支自然出现。
两条分支的区别
只在于从第 3 条之后的 parentId 链条走向哪里。文件是纯追加的,旧分支一个字都没改。
这就是为什么必须 append-only:如果允许改旧条目,「回到第 3 条」就得原地修改,旧分支会消失。 而追加型结构让「分支」变成零成本操作——它只是一个指针的赋值。
3.4

读:回溯 + 反转

读一条路径的逻辑简单到有点朴素——从叶子开始沿 parentId 往回走,然后反转:

packages/coding-agent/src/core/session-manager.ts:408-417
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;

有两个细节值得注意:

细节意图
index.get(parentId) 先建一次 Map 索引,否则每次回溯都要线性搜,深度一深就退化
leaf ??= entries[entries.length - 1] 叶子 ID 失效(旧文件、被删条目)时退回最后一条,不报错——容错优先

session-manager.ts:407

3.5

一个迁移里的关键决定:索引 → ID

这是本篇最想让你注意的一处。会话格式从 v1 升到 v2 时加了 id/parentId, 同时把压缩条目里的 firstKeptEntryIndex 换成了 firstKeptEntryId。

packages/coding-agent/src/core/session-manager.ts:286-302
/** Migrate v1 → v2: add id/parentId tree structure. Mutates in place. */
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") { /* ... */ }

为什么必须换?因为索引在分支结构下会失效。

表示含义出错场景
firstKeptEntryIndex: 42 文件里第 42 行开始保留 分支后「第 42 行」可能属于另一条分支,压缩边界指向错误位置
firstKeptEntryId: "a3f9" 从 id 为 a3f9 的条目开始保留 不成立——id 全局唯一,永远指向同一条

同一个迁移里还有一句注释揭示了 v1 的真实形状:entry.parentId = prevId。 旧文件是纯线性的,所以迁移时可以直接把 prevId 串起来——不需要推断任何分支结构。

这条经验可以推广:任何「在可变序列里记录位置」的设计,一旦引入分支或重排,位置表示就会失效。 用稳定 ID 替换下标,是让日志结构能长期演进的前提。

session-manager.ts:286-302

3.6

落盘:排他创建 + 惰性补写

append-only 只是逻辑模型,物理写入还有个首次写的特殊情况:

packages/coding-agent/src/core/session-manager.ts: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`);
  }
}
行为为什么
没有对话就不建文件避免「打开-退出」留下一堆空会话,污染列表
"wx" 而不是 "w"文件已存在则失败,永不覆盖别人的会话
首次遍历 fileEntries恢复/另存时要补写已解析的历史;之后才转为纯追加
一行一个 JSON+\n可流式读、可断点续、坏一行不影响前面

session-manager.ts:1172-1189

3.7

一句话记住它

这套结构的本质是:文件是日志,树是日志的读法,状态是历史的函数。

你以为它是实际上是推论
一个可变的消息数组只追加的 JSONL 日志永远不需要「保存」——每一步都已经是保存
一个有分支的树对象一批带 parentId 的条目分支是「把叶子指针挪一下」,零拷贝
一份当前设置一串变更事件回放旧分支拿到旧设置,不会串味

下一章要讲的压缩,正是这套结构最重要的使用者——因为压缩必须在不破坏历史的前提下,改变「模型看到什么」。 如果历史是可变的,压缩就变成了「删掉旧消息」;而在这里,压缩只是追加一条新的摘要条目。

本章学习记录

记录仅保存在当前浏览器。