读一个会话文件及其树
把会话看成 JSONL:一个表头、按 id 与 parentId 相连的条目、一个算出来的目录名,以及一条只掩藏不删除的 context_edit。
一个持久的 Pi 会话是一个你能在任何编辑器中打开的普通 JSONL 文件。
第一行是一个头部,之后每一行都是一个带 id 和 parentId 的树条目,
而模型永远只看到活动分支。这是一条示意性的记录,加上一次目录名
计算,以第 5 章的测试为依据;它是形状的一幅画,不是来自你机器的一份
转录记录。
第一行是一个头部
条目构成一棵树。对于一段线性对话,每个条目的父条目是它前面那一个 条目,而头部不是树的一部分:
{"type":"session","version":3,"id":"<session-id>"}
{"type":"message","id":"a1b2c3d4","parentId":null,"timestamp":"2026-10-01T09:00:00.000Z","message":{"role":"user","content":"question A"}}
{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"2026-10-01T09:00:01.000Z","message":{"role":"assistant","content":"answer A"}}
{"type":"message","id":"c3d4e5f6","parentId":"b2c3d4e5","timestamp":"2026-10-01T09:00:02.000Z","message":{"role":"user","content":"question B"}}测试在真实文件上断言这一点:头部在前,然后按顺序每个消息一个条目,
id 唯一,并且第一个条目的 parentId 是 null。它也展示了
已存储不等于已发送:model_change、thinking_level_change 和
appendCustomEntry 条目坐在文件里,而从不抵达 provider。
目录名是一次计算
默认位置是
~/.pi/agent/sessions/--<path>--/<timestamp>_<session-id>.jsonl。Pi 丢掉
工作目录的前导分隔符,然后把 /、\ 和 : 替换成 -:
| 工作目录 | 目录组成部分 |
|---|---|
C:\Projects\pi |
--C--Projects-pi-- |
/home/u/app |
--home-u-app-- |
驱动器字母保留;没有任何分隔符、也没有任何冒号能活下来。会话 id 默认 是一个 UUID,这一点由测试中的文件名模式确认。
一次上下文编辑只掩藏,不删除
追加一条 replacement 为 null 的 context_edit,会把目标从未来的请求
中省略掉,并让该条目留在文件里:
{"type":"context_edit","id":"g6h7i8j9","parentId":"f6g7h8i9","timestamp":"2026-10-01T09:00:03.000Z","targetId":"a1b2c3d4","replacement":null}编辑是分支相对的:导航到它之前的某一点(助手对 A 的回答),会再次揭示
原始的贡献。一个诸如 { "content": "REDACTED" } 的替换对象为模型改写这条
消息,并让存储的条目原样不动;替换必须是一个带 content 的对象,不是
裸字符串。
机制与局限
**有文档记载:**锁定的 session-format.md 中的会话文件格式与位置公式,
以及在 examples/ch27-session-entries/declared.ts 中声明的基础条目字段
(type、id、parentId、timestamp)。那份声明是第 27 章的主题,
这里只是引用,不复现。
已观察:disk.test.ts 读取由共享历史写下的真实文件,并断言头部顺序、
树链接、已存储但未发送的条目、分支相对的编辑,以及在随附二进制文件上的
目录名。
这条记录是示意性的,并且它的 id 被缩短了;它展示的是条目的形状,不是 一个完整的文件。已存储不等于已发送,两个方向都成立:文件中的一个条目不是 模型见过它的证明,而一次请求所包含的是活动分支——在压缩与编辑之后。第 24 章 涵盖分支,第 27 章涵盖完整格式。
完整源码与测试 。
Understand this example
Copy this prompt into your AI tool. No code runs here.
Apply this example
Copy this prompt into your AI tool. No code runs here.