深入理解 pi/第 03 章
为什么不是「一个消息数组」
最简单的会话存储是一个数组:往后面 push,读的时候整个读出来。pi 不用这个方案,因为有三件事它做不到:
| 需求 | 数组方案的困境 | 树方案的解 |
|---|---|---|
| 回到某一步重来 | 要么复制整个前缀,要么丢掉后面 | 把 leafId 指回旧条目,下一条自然长在那里 |
| 压缩后仍能查原始消息 | 摘要一旦写入,原文就没了 | 摘要是新条目,原条目仍在文件里 |
| 崩溃后不丢数据 | 整文件重写有窗口期 | 一次追加一行,写多少算多少 |
代价也很明确:读的时候要重建。数组是 O(1) 读,树是 O(深度) 回溯。 pi 接受了这个代价,换来的是「历史不可变、状态可分支」。
条目:11 种类型,全都是事件
会话文件里的每一行是一个 SessionEntry,而它是 11 种类型的联合:
export type SessionEntry = | SessionMessageEntry // 一条对话消息 | ThinkingLevelChangeEntry // 思考档位变更 | ModelChangeEntry // 换模型 | UsageEntry // 用量记账 | CompactionEntry // 压缩摘要 | BranchSummaryEntry // 分支摘要 | CustomEntry // 扩展自定义状态 | CustomMessageEntry // 扩展自定义消息 | ContextEditEntry // 上下文编辑 | LabelEntry // 打标签 | SessionInfoEntry; // 会话元信息
注意里面没有一个是「当前状态」字段。当前用什么模型、思考档位多高,都不是存在某个可变字段里, 而是由历史事件推导出来的:
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(推导当前设置)
生长:四行代码定义的树
树的全部生长逻辑就在 _appendEntry 里,而它的核心只有一行 this.leafId = entry.id:
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,形成一条直线。文件里看不出树,因为退化成了链。leafId 设回第 3 条。下一条消息的 parentId 就是第 3 条——不需要复制任何历史,分支自然出现。parentId 链条走向哪里。文件是纯追加的,旧分支一个字都没改。读:回溯 + 反转
读一条路径的逻辑简单到有点朴素——从叶子开始沿 parentId 往回走,然后反转:
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 失效(旧文件、被删条目)时退回最后一条,不报错——容错优先 |
一个迁移里的关键决定:索引 → ID
这是本篇最想让你注意的一处。会话格式从 v1 升到 v2 时加了 id/parentId,
同时把压缩条目里的 firstKeptEntryIndex 换成了 firstKeptEntryId。
/** 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 串起来——不需要推断任何分支结构。
落盘:排他创建 + 惰性补写
append-only 只是逻辑模型,物理写入还有个首次写的特殊情况:
_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 | 可流式读、可断点续、坏一行不影响前面 |
一句话记住它
这套结构的本质是:文件是日志,树是日志的读法,状态是历史的函数。
| 你以为它是 | 实际上是 | 推论 |
|---|---|---|
| 一个可变的消息数组 | 只追加的 JSONL 日志 | 永远不需要「保存」——每一步都已经是保存 |
| 一个有分支的树对象 | 一批带 parentId 的条目 | 分支是「把叶子指针挪一下」,零拷贝 |
| 一份当前设置 | 一串变更事件 | 回放旧分支拿到旧设置,不会串味 |
下一章要讲的压缩,正是这套结构最重要的使用者——因为压缩必须在不破坏历史的前提下,改变「模型看到什么」。 如果历史是可变的,压缩就变成了「删掉旧消息」;而在这里,压缩只是追加一条新的摘要条目。