会话,以及它们住在哪里
会话文件是以 id 与 parentId 为键的只追加 JSONL 树;这里讲怎么读一个、怎么恢复它、怎么分叉它,以及怎么控制它存在哪里。
你想知道 Pi 实际做了什么。不是它在最后一条消息里总结成了什么——是它做了什么。那意味着打开会话文件,而事实证明那个文件是你能用任何文本编辑器读懂的普通 JSONL,并且每一行都是树中的一个节点。
那棵树就是 Pi 能提供 /tree、/fork 和 /clone 的原因,而它携带着本书重复次数最多的那个区分:一个会话是一棵树;模型的上下文是穿过它的一条路径。
flowchart TD
H["头部"] --> U1["user"]
U1 --> A1["assistant"]
A1 --> U2["user,已编辑"]
U2 --> A2["assistant"]
A2 --> U3["user"]
U3 --> A3["assistant"]
A1 --> U2b["user,原始"]
U2b --> A2b["assistant"]
当前叶子是 A3。活动分支是路径 U1, A1, U2, A2, U3, A3——唯一被读入下一条请求的那些条目。穿过 U2b 的那条路径是一个已被放弃的备选项:它还在文件里,还计入你的会话总量,而模型从未见过它。
错误:“会话就是对话。”
正确:“会话是对话加上它的每一个备选项。对话是活动分支。”
一个文件,一棵树
sessions.md:Pi 会自动保存会话,除非你用 --no-session 启动它。持久的会话是 JSONL 文件,其中每个树条目有一个 ID 并指向它的父条目,而当前条目标识出活动分支。
session-format.md 给出了位置:
~/.pi/agent/sessions/--<path>--/<timestamp>_<session-id>.jsonl
对于工作目录那一部分,Pi 会去掉前导的路径分隔符,并把 /、\ 和 : 替换成 -。所以一个在 C:\Projects\pi 中启动的会话落在 C--Projects-pi 之下:反斜杠变成连字符,驱动器冒号变成连字符,而驱动器字母本身保留。没有任何分隔符、也没有任何冒号能活下来。<session-id> 默认是一个 UUID;--session-id 或 SDK 可以提供你自己的。第 27 章展示同一个编码用于一段 POSIX 路径的情形,那是除了前导分隔符之外完全不需要任何替换的情形。
除表头之外,每个条目都扩展同一个基类:
interface SessionEntryBase {
type: string;
id: string; // Usually an 8-char hex ID; may fall back to a full UUID
parentId: string | null; // null for a root entry
timestamp: string; // ISO timestamp
}
两个时间戳,两种格式。条目时间戳是 ISO 8601 字符串。嵌套的消息时间戳是 Unix 毫秒——message-types.md 明确指出了这一点,为的是阻止一整类解析 bug。
已存储不等于已发送
每一种条目类型都要被分类两次,一次为磁盘,一次为请求,而已存储不等于已发送。 一条 message 既存储也发送。一条 custom 条目、一条 usage 条目和一个 label 被存储而从不发送。一条 compaction 条目被存储,并以一条摘要的形式到达。文件的第一行是一个头部,它不是树的一部分,并且它携带一个已经改过两次的版本号。
第 27 章是头部、那些版本、全部十一种条目类型、context_edit,以及把文件变成请求的三趟处理的参考。本章只停在理念上。
上下文编辑改写而不删除
ContextEditEntry 本身就值得理解:
{"type":"context_edit","id":"g6h7i8j9","parentId":"f6g7h8i9","timestamp":"2024-12-03T14:11:00.000Z","targetId":"c3d4e5f6","replacement":null}
replacement: null 把目标从模型上下文中省略掉。一个非空的替换只替换那条消息的内容;针对助手条目和工具结果条目的字符串替换会被规范化成一个文本块。如果有多个编辑针对同一条目,活动分支上最新的那个胜出。
重要的性质在于编辑是分支相对的:导航到编辑之前的某一点,原始的贡献就回来了。正是这一点让 Pi——以及之后的你——可以安全地藏起一次超出预算的尝试。
分支的三种方式
/tree 在当前会话文件内移动,/fork 从一条更早的用户消息创建一个新会话,/clone 把活动分支复制进一个新会话。离开一条分支可以附上一条 branch_summary 条目,总结你留下了什么。该用哪条命令、以及每一条对你抛在身后的历史做了什么,是第 24 章的主题。
控制会话住在哪里
默认是 ~/.pi/agent/sessions/,按工作目录分组。有三种方式改它,按优先级顺序:--session-dir,然后 PI_CODING_AGENT_SESSION_DIR,然后 sessionDir 设置。cli.md 确认 CLI 选项有最高优先级。
--no-session 给你一个临时的内存会话,Pi 退出后无法恢复它。environment-variables.md 指出 PI_SESSION_FILE 对临时会话是未设置的,而这就是一个脚本能检测到那一点的方式。
位置与身份
有三样东西在这里被搞混,而这种混淆表现为"Pi 恢复了错误的对话"。它们是目录、文件,以及文件里的分支。
| 问题 | 由谁回答 | 去哪里看 |
|---|---|---|
| 哪个目录存放会话 | sessionDir 设置、PI_CODING_AGENT_SESSION_DIR,或 --session-dir——旗标胜出 |
/session,或 sessionDir 设置 |
| 哪个文件是这一次运行 | 工作目录分组加上会话 id | --<path>-- 目录名,以及 PI_SESSION_FILE |
| 模型看到了哪些消息 | 那个文件的活动分支,在压缩与编辑之后 | /tree,或第 27 章的 get_entries |
| 它究竟是不是这一次运行 | 三者都对上 | 拿 /session 的文件和 id 与你预期的目录相比 |
卡住人们的是第三行。恢复给你的是一个装着整棵树的会话文件,而模型被展示的是那棵树的一个分支。第 24 章讲分叉它,第 27 章讲格式;对于调试,有用的第一步是 /tree,它回答"我在哪条分支上",而完全不用读文件。
第二卡人的是第一行。一个在不同目录中启动的会话落在不同的 --<path>-- 分组里,所以"我恢复了,可它是空的"通常是工作目录的差异,而不是会话丢了。
读你自己的会话
/session 报告当前文件、ID、消息条数、token 用量与费用。而因为文件是 JSONL,你可以直接读它:
Get-ChildItem "$env:USERPROFILE\.pi\agent\sessions" -Recurse -Filter *.jsonl |
Sort-Object LastWriteTime -Descending |
Select-Object -First 1 |
ForEach-Object { Get-Content $_.FullName -TotalCount 3 }
session-format.md 以一个解析示例收尾,它按 entry.type 分支,并为每个条目打印一行。把它抄过来并扩展它;这是回答"那次运行到底做了什么"的最快方式。
刻意地删除
会话通过删除它们的 .jsonl 文件来移除。/resume 也支持交互式删除,方法是 Ctrl+D 加上一次确认,并且 Pi 在可用时会用 trash CLI,以避免永久删除。
运行了什么
第 4、5、23、24 章是在一段共享历史上测试的,好让它们读起来像一个主题、一段随时间的状态,而不是四个。它是持久会话中的三轮:问题 A 与它的回答;问题 B,它先做一次 bash 工具调用然后回答;问题 C 与它的回答。examples/harness/history.ts 构建它,而每一章读同一次运行的不同属性。
第 5 章的问题是磁盘上有什么,以及我怎么找到并读它? examples/ch05-disk/ 在真实文件上和随附的二进制文件上检查它:
- 每一轮都实时落在磁盘上:一个头部,然后按顺序每个消息一个条目,包括系统消息和工具结果;
- 条目按
id和parentId构成一棵树,id 是唯一的,而对于一段线性对话,每个条目的父条目是它前面那一个条目; - 已存储不等于已发送:模型切换和思考级别条目,以及一条用
appendCustomEntry()写入的custom条目,都在文件里,而没有一个出现在 provider 收到的东西里; - 一条
null的context_edit把问题 A 从下一条请求中藏了起来,并让它留在文件里,而导航到助手对 A 的回答——编辑之前的某一点——又揭示了原始内容:编辑是分支相对的。一个 replacement,{ content: "REDACTED" },为模型改写了这条消息,并让存储的条目原样不动。replacement 必须是一个带content的对象,不是裸字符串; - 在随附的二进制文件上,默认位置是
--<path>--,其中/、\和:被替换成-,而文件名是<timestamp>_<session-id>.jsonl,带一个 UUID; --session-dir胜过PI_CODING_AGENT_SESSION_DIR,后者胜过sessionDir设置,三个都设着试过,然后依次各移除一个再试。
下一章
这棵树里的几乎每一样东西都是一个工具调用写下来的:文件是模型曾经能做的事的一份记录。所以下一个问题根本与存储无关,而与集合本身有关——Pi 以哪些工具起步,那个集合如何由设置组成,以及一个工具必须返回什么,模型才能知道有件事失败了。
第 6 章:内置工具。