会话文件格式
一行一个 JSON 对象、一棵条目树,以及那次三遍遍历——它把一个被存储的会话变成一次模型请求恰好包含的那些消息。
你打开一个会话文件,想弄清那个智能体实际看到了什么。里面有四百行。在其中的某处是系统提示词、一段已被摘要掉的大半段对话、你上周放弃的一条分支,以及一个来自扩展、存着它自己计数器的 custom 条目。
其中哪些到达过模型,从文件上并不显然。本章讲的是这个文件,以及做出判断的那条规则。
容器
“会话被存储为 JSONL(JSON Lines)文件。每一行是一个带 type 字段的 JSON 对象。会话条目通过 id/parentId 字段构成一棵树结构,从而能在不创建新文件的情况下就地分支。”
一句话里装着三个性质。只追加的行格式、带类型的对象,以及一棵完全由文件自身承载的树。没有单独的索引,分支时也不会重写历史。
位置:
~/.pi/agent/sessions/--<path>--/<timestamp>_<session-id>.jsonl
“对于 <path>,Pi 会去掉开头的路径分隔符,并把 /、\ 和 : 替换成 -。“所以 C:\work\api 会变成 --C-work-api--。sessions.md 补充说会话"按工作目录分组”,并且 sessionDir、PI_CODING_AGENT_SESSION_DIR 和 --session-dir 会改变根目录,其中命令行选项优先。
删除被刻意做得平淡无奇。“会话可以通过删除它们的 .jsonl 文件来移除”,而选择器里的 /resume 做的也是同一件事,在可用时优先使用 trash CLI。
版本
头里带着一个版本号,而一共有三个:
- 版本 1 — 线性的条目序列(遗留格式,加载时自动迁移)
- 版本 2 — 带
id/parentId链接的树结构 - 版本 3 — 把
hookMessage角色改名为custom
“已存在的会话在加载时会被自动迁移到当前版本(v3)。”
版本 3 是最小的改动,也最容易绊人:如果你的扩展用旧的 hookMessage 类型名去读条目,它在任何由当前版本 Pi 创建的会话上都会毫无声息地什么也看不到。
文件头
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
“文件的第一行。只有元数据,不是树的一部分(没有 id/parentId)。”
带父会话时:
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}
parentSession 出现在"有父会话的会话上(通过 /fork、/clone 或 newSession({ parentSession }) 创建)。“这是一个被分叉的会话从何而来的唯一耐久记录——那个分叉的分支摘要并不存在于那里,因为新会话没有任何关于它离开了什么的记录。
其他每一个条目都扩展自:
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
}
注意"通常是 8 个字符的十六进制 ID;也可能回退成一个完整的 UUID。“不要假定一个固定的 id 长度。
条目类型
有十一种。下面讲的是每一种是做什么用的,不是字段清单的复述。
message — 一条对话消息。message 字段持有一个 AgentMessage。这些当中的系统消息携带提示词与工具配置,而那正是有意思的情况:“会话的第一次请求会持久化其中一条,带着每一个提示词节和工具声明,而后来的变化持久化为一些系统消息,它们按名字给 sections 打补丁(null 移除一个),并列出 toolsAdded/toolsRemoved。按顺序重放它们就能得出当前的提示词与工具;不存在单独的提示词状态条目。”
model_change — “当用户在会话中途切换模型时发出。最新的那条条目就是被选中的模型,它可能是一个虚拟模型;助手消息随后会指名实际回答了问题的那个物理模型。”
thinking_level_change — 推理级别同理。那个示例携带 "thinkingLevel":"high"。
usage — “记录模型归属的用量,它不是一条助手消息,也不参与 LLM 上下文。"kind 是"一个标识该操作的任意字符串;例如,缓存预热用 "cache_warm"。“两条规则:“用量条目计入会话的 token 与费用总计。Pi 把它们从对话树中隐藏起来。“以及:“消费者应当把未知的 kind 值当作正常用量,而不是拒绝它们。“第二句话是一条兼容性指令——不要写一个封闭的枚举。
compaction — 来自第 23 章。必需 firstKeptEntryId,外加可选的 systemMessage、usage、details、fromHook。
context_edit — “对一个更早的、产生上下文的条目的只追加式编辑。它只改变未来的模型上下文;目标条目及其元数据在原始历史、UI、导出和会话核算中保持不变。“第 5 章介绍过这个想法并展示了那个条目。格式补充的规则是:“目标可以是 user、assistant、tool-result 或 custom-message 条目。““assistant 和 tool-result 条目的字符串替换会被规范化成一个文本块,因为那些角色要求内容数组。“以及:当若干编辑瞄准同一个条目时,活动分支上最新的那个编辑胜出。
branch_summary — 来自第 24 章。
custom — 扩展状态,”不参与 LLM 上下文。”
{"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}
“用 customType 在重载时标识你的扩展的条目。“还有一句值得知道的题外话:“Pi 把虚拟模型路由器状态存为带 customType pi.virtual-model-state 的自定义条目。“所以一个你没有选择的命名空间可能占据你的条目类型。给你的加上前缀。
custom_message — 确实会到达模型的扩展内容。content、display,以及"可选的扩展特定元数据(不发送给 LLM)。”
custom / custom_message 这一对是要内化于心的。两个名字容易混淆、可见性却正好相反的扩展条目类型:
| 在 LLM 上下文中 | 在 TUI 中渲染 | |
|---|---|---|
custom |
否 | 是,通过 registerEntryRenderer |
custom_message |
是 | display: true 显示它,false 隐藏它 |
label — “用户定义的、加在一个条目上的书签/标记。"targetId 加 label。“把 label 设为 undefined 以清除一个标签。”
session_info — 会话的显示名称,通过 /name、--name / -n 或 pi.setSessionName() 设置。“设置后,会话名会代替第一条消息显示在会话选择器(/resume)里。”
通往一次模型请求的三遍
这部分回答你开头那个问题。buildContextEntries() 从当前叶子走向根,并在尊重压缩的前提下产出活动条目列表:
- 收集该路径上的所有条目。
- 如果路径上有一个或多个
CompactionEntry值,使用最新的那个,先包含那个压缩条目,包含自firstKeptEntryId起、到但不包括该压缩条目为止的非系统条目,并包含该压缩条目之后的条目。 - 保留所选范围内的非消息条目,好让交互模式能渲染它们。
然后 buildSessionProjection() “对每一个所选目标应用最新的 context_edit。它把模型可见的消息连同它们的源条目一起返回。被省略的目标不产生消息;替换保留源条目的角色与元数据,只改变内容。原始的被选条目不被修改。”
然后 buildSessionContext() 在这个投影之上构建。它先"从完整路径中提取当前的模型与思考级别设置”——注意是完整路径,不是压缩后的范围——然后把被选条目转换成消息。
flowchart TD
F["session.jsonl 条目树"] --> A["活动路径:从叶子到根"]
A --> B["buildContextEntries:最新的压缩选出范围"]
B --> C["buildSessionProjection:每个目标最新的 context_edit"]
C --> D["buildSessionContext:设置取自完整路径,然后条目转消息"]
D --> E["被发送给模型的消息"]
F -.-> X["从未到达的条目"]
C -.-> X
错误:“一个被存储的条目就是一条被发送给模型的消息。”
**正确:**文件是记录。三个有序的阶段把它归约为那次请求,而那些阶段中有两个在磁盘上完全没有表示。
这个顺序有一个后果:因为编辑应用在压缩选出范围之后,一次编辑可以瞄准一个已被压缩排除的条目。这样的编辑对那次请求无从下手,但那个原始条目仍留在文件里。
另一条:“压缩前的系统消息会被折进那个完整的检查点,而不是从被保留的范围内重放。“所以一次压缩之后,提示词来自压缩的 systemMessage,而不是你在文件里仍然看得见的那些系统条目。
自己读一个会话
import { readFileSync } from "fs";
const lines = readFileSync(process.argv[2] ?? "session.jsonl", "utf8").trim().split("\n");
for (const line of lines) {
const entry = JSON.parse(line);
switch (entry.type) {
case "session":
console.log(`Session v${entry.version ?? 1}: ${entry.id}`);
break;
case "message":
console.log(`[${entry.id}] ${entry.message.role}: ${JSON.stringify(entry.message.content)}`);
break;
case "compaction":
console.log(`[${entry.id}] Compaction: ${entry.tokensBefore} tokens summarized`);
break;
case "branch_summary":
console.log(`[${entry.id}] Branch from ${entry.fromId}`);
break;
case "usage":
console.log(`[${entry.id}] Usage (${entry.kind}): ${entry.usage.totalTokens} tokens`);
break;
case "custom":
console.log(`[${entry.id}] Custom (${entry.customType}): ${JSON.stringify(entry.data)}`);
break;
case "custom_message":
console.log(`[${entry.id}] Extension message (${entry.customType}): ${entry.content}`);
break;
case "label":
console.log(`[${entry.id}] Label "${entry.label}" on ${entry.targetId}`);
break;
case "model_change":
console.log(`[${entry.id}] Model: ${entry.provider}/${entry.modelId}`);
break;
case "thinking_level_change":
console.log(`[${entry.id}] Thinking: ${entry.thinkingLevel}`);
break;
}
}
这走的是文件,不是分支。要看到模型看到了什么,请自己过滤到活动分支并应用压缩与编辑规则,或者通过 RPC 去问——get_entries 用一个游标给你一切,而 get_messages 给你那段对话如同会话所持有的那样——即应用过压缩与编辑条目之后的活动分支。
那与 provider 收到的请求并不是同一回事,而这个差别并不小。第 39 章那个"请求之前"分组里的一切都跑在那两点之间:transformContext 可以为一次请求丢弃或改写消息,convertToLlm 把它们转换成 provider 自己的形状,而一个提示词节可以改变系统消息。所以 get_messages 回答的是"这个会话相信发生了什么”,而只有一次请求级别的观察——即 provider 实际收到的提示词,也就是第 18 章的测试所做的——才回答"模型看到了什么”。审计状态时用前者,而当你问的是一个表现得像是忘了某件事的模型时,用后者。
给任何写这种格式的代码的实用规则
追加,绝不重写。SessionManager 拥有这棵树,而文件是它的记录;SDK 是受支持的路径,手工编辑不是。
用一个带命名空间的 customType。Pi 已经占有了 pi.virtual-model-state,而你的类型是其他一切东西所匹配的那个键。
预料到版本 1 的会话。一个线性的遗留文件在加载时迁移,所以一个假定它是树的解析器可能在旧文件上失败、而在新文件上正常。
文件是记录,而它是唯一的副本。会话告诉模型的一切都可能被摘要掉、或被从下一个请求里编辑掉——但本章所讲的没有任何一样会在 Pi 重启时被从零重建,而这正是下一章的主题。