会话文件解剖
Pi 默认把会话保存在 ~/.pi/agent/sessions/ 下的 JSONL 文件中,一行一个 JSON 对象。header 之后的 entry 用 id / parentId 连成树;文件保存全部历史,模型只接收当前路径的投影。用 --no-session 启动的临时会话不落盘。
本页按 Pi 1.5.0 的 session-manager.ts 核对,数值与片段来自本机真实会话快照(长行已截断)。只想写读取脚本,直接看高效读取会话数据。
文件在哪、长什么样
~/.pi/agent/sessions/--Users-yuuki-codex-pi-book--/ └─ cwd:/Users/yuuki/codex/pi-book 2026-11-05T22-35-50-281Z_01a1adda-a689-….jsonl └ 时间戳 ┘ └ 会话 ID- 目录名把 cwd 的
/、\、:换成-,所以同一目录的会话总在同一个文件夹。 - 文件名是
<ISO 时间戳>_<session id>.jsonl;时间戳里的:和.也换成了-。 - 换目录只是换文件夹,不会移动或重写已有文件。
- 用
--session-dir、PI_CODING_AGENT_SESSION_DIR或sessionDir设置可以整体换位置。
这份本机快照有 20 个文件、8.6 MB、1,623 行(含 20 行 header)。按条数看,工具结果与助手响应占了大头:
查看这份快照的原始计数表
| entry 类型 | 条数 | 说明 |
|---|---|---|
message(assistant) | 631 | 每次模型响应一条 |
message(toolResult) | 718 | 每次工具执行一条,常是最大的行 |
message(user) | 114 | 只有真正提交的输入 |
model_change | 89 | 中途切换模型,切得很勤 |
thinking_level_change | 27 | Shift+Tab 或 /thinking 的落点 |
message(system) | 12 | 提示词与工具的增量补丁 |
context_edit | 11 | /edit 或扩展对历史消息的改写 |
compaction | 1 | 自动或手动压缩 |
session | 20 | 每个文件开头一行 header |
user、assistant、toolResult、system 都是 message 的角色,其他名称才是独立 entry 类型。工具结果常有大段正文,条数少不等于体积小。
一份真实会话的形状
样例:2026-11-05T22-35-50-281Z_01a1adda-….jsonl,也就是状态栏页里那张截图的会话。
| 指标 | 值 |
|---|---|
| 文件体积 | 3.5 MB |
| entry 条数(不含 header) | 295 |
| 单条最大 | 364 KB(一次工具输出) |
| user / assistant / toolResult | 6 / 105 / 173 |
context_edit / compaction | 6 / 0 |
| 模型切换 | deepseek-v4-pro → thinking=high → openai/gpt-6-astra → thinking=max |
105 条 assistant 对 173 条 toolResult:平均每条助手响应对应约 1.6 条工具结果,而 user 只有 6 条。消息条数不能直接当作用户对话轮数。
逐行看开头
第 1 行是 header:它的 id 是会话 ID,不是树节点 ID;没有 parentId,不属于 entry 树:
{"type":"session","version":3,"id":"01a1adda-a689-70dd-8450-928f47a44827","timestamp":"2026-11-05T22:35:50.281Z","cwd":"/Users/yuuki/codex/pi-book"}接下来两行是设置快照,它们不参与上下文,只记录“当时用的是哪个模型、哪个思考档位”:
{"type":"model_change","id":"46d919af","parentId":null,"timestamp":"…","provider":"deepseek","modelId":"deepseek-v4-pro"}{"type":"thinking_level_change","id":"94d2c165","parentId":"46d919af","timestamp":"…","thinkingLevel":"high"}注意第一个 parentId 是 null:根 entry 是 model_change,不是 user 消息。
然后是第一条 system 消息(截断):
{"type":"message","id":"33ae2b3c","parentId":"4d13d1d8", "message":{"role":"system","content":"", "sections":{"preamble":"You are a coding assistant running inside pi,…", "tools":"<tools>…","rules":"…","docs":"…","skills":"…","cwd":"/Users/yuuki/codex/pi-book"}, "toolsAdded":[{"name":"read",…},{"name":"bash",…},{"name":"edit",…},{"name":"write",…}], "timestamp":1793918243180}}用户消息和模型响应:
{"type":"message","id":"4441583e","parentId":"33ae2b3c","timestamp":"2026-11-05T22:37:23.184Z", "message":{"role":"user","content":[{"type":"text","text":"我刚看了下,在移动端体验太烂了…"}],"timestamp":1793918243179}}{"type":"message","id":"0bb9db57","parentId":"4441583e","timestamp":"2026-11-05T22:37:31.819Z", "message":{"role":"assistant", "content":[{"type":"thinking","thinking":""},{"type":"toolCall","name":"read","arguments":{"path":"…/SKILL.md"}}], "api":"openai-responses","provider":"openai","model":"gpt-6-astra","providerThinkingLevel":"high", "usage":{"input":3,"output":237,"cacheRead":0,"cacheWrite":4964,"reasoning":148,"totalTokens":5204, "cost":{"input":0.00003,"output":0.01185,"cacheRead":0,"cacheWrite":0.06205,"total":0.07393,"totalFromProvider":false}}, "stopReason":"stop","rawStopReason":"completed","durationMs":8618,"thinkingLevel":"high", "responseId":"resp_0a134b28…","timestamp":1793918243201}}工具结果单独成条,用 toolCallId 对上前面那次调用:
{"type":"message","id":"a7601db5","parentId":"c5925023", "message":{"role":"toolResult","toolCallId":"call_DHvLI2…","toolName":"read", "content":[{"type":"text","text":"---\nname: build\n…"}],"isError":false,"durationMs":1203,"timestamp":1793918259274}}公共字段与两个时间戳
除 header 外,所有 entry 都有这四个字段:
| 字段 | 含义 | 注意 |
|---|---|---|
type | entry 类型 | 决定它是否进上下文 |
id | 8 位十六进制,偶尔是完整 UUID | 从旧版本迁移过来的会话可能是长 ID |
parentId | 父 entry 的 id,根为 null | 分支全靠它 |
timestamp | ISO 字符串 | entry 用的是字符串,内层 message.timestamp 是毫秒数 |
两个时间戳不一致是正常的:entry 时间是条目创建时刻,message.timestamp 来自消息本身,不能一概解释成“模型返回时间”。做时间线时先统一采用哪一层;要分析请求耗时,另看 durationMs。
message 的四种 role
| role | 关键字段 | 是否进模型上下文 |
|---|---|---|
system | sections + toolsAdded / toolsRemoved | 是,但按增量 patch 回放 |
user | content(字符串或 block 数组) | 是 |
assistant | content、usage、stopReason、responseId | 是 |
toolResult | toolCallId、toolName、content、isError | 是 |
system 是补丁,不是快照
第一条 system 消息携带完整提示词和工具清单。之后如果加载了新 skill、改了工具集,Pi 只追加一条补丁:
{"type":"message","id":"d4e5f6a7","parentId":"…", "message":{"role":"system","content":"","sections":{"skills":"<skills>…</skills>"}, "toolsRemoved":[{"name":"write"}],"timestamp":…}}sections 按名字覆盖,值为 null 表示移除;toolsAdded / toolsRemoved 增量增删。顺序回放才能得到当时的真实提示词,只读第一条 system 会漏掉后来的变化。这也是缓存命中率会突然掉一截的常见原因:提示词变了,缓存前缀就作废了。
assistant 的 usage 与 cost
usage 里 input 是扣掉缓存后的净输入,所以经常只有个位数;cacheRead、cacheWrite 单列。cost.totalFromProvider: false 表示这个价格是 Pi 用模型价格表估的,不是供应商账单。字段细节见状态栏页。
失败的响应也会写进文件,只是 usage 全零、content 为空:
{"type":"message","id":"c0d4da2f","parentId":"16636426", "message":{"role":"assistant","content":[],"api":"openai-responses","provider":"openai","model":"gpt-6-astra", "usage":{"input":0,"output":0,"cacheRead":0,"cacheWrite":0,"totalTokens":0,"cost":{…}}, "stopReason":"error","errorMessage":"terminated","durationMs":110898,"timestamp":1793918318233}}这条会话里有 6 条这样的 entry(用户按 Escape 中止)。它们不改变累计 token 和费用,但会让页脚的 CH 整个消失——因为最后一条 assistant 消息没有可用的 prompt 计数。
toolResult 可能非常大
上面那个 364 KB 的单条是工具结果。会话保存工具返回的内容,但工具自身可能已经截断输出,不能据此还原完整终端输出。文件还保留旧分支、已压缩内容和被 edit 隐藏的原文,所以磁盘体积与当前上下文占用不是同一个量。
其他 entry 类型
compaction:压缩点
{"type":"compaction","id":"b4406ae6","parentId":"d6d186da","timestamp":"2026-11-05T17:41:27.280Z", "summary":"## Goal …(7,116 字符)","firstKeptEntryId":"ea4b6cac","tokensBefore":256386, "details":{"readFiles":["…/CHANGELOG.md","…/agent-session.js"],"modifiedFiles":[…]}, "usage":{…}}tokensBefore:压缩前的上下文规模。firstKeptEntryId:从哪条 entry 开始保留。只留摘要不留原文时,这里指向 compaction 自己。summary:摘要正文;生成摘要消耗的模型用量记在usage,计入会话成本。systemMessage:压缩点当时的完整提示词与工具清单(旧会话可能没有)。
context_edit:改写历史,但不改历史
{"type":"context_edit","id":"d1edce00","parentId":"c0d4da2f","timestamp":"…","targetId":"c0d4da2f","replacement":null}它只影响之后的模型请求:replacement: null 表示这条不进上下文,非 null 则替换内容。被指向的原始 entry 一个字都不改,UI、导出、统计都还是原样。多条 edit 指向同一条时,取路径上最后一条。
本机没出现,但格式里有
| 类型 | 作用 |
|---|---|
usage | 不属于消息的模型用量(如 kind: "cache_warm"),计入统计,不进上下文 |
branch_summary | /tree 换分支时对离开路径的摘要,带 fromId |
custom | 扩展自己的状态,不进上下文 |
custom_message | 扩展注入的上下文消息,display 控制是否显示 |
label | 给 entry 打书签,label 为空即清除 |
session_info | /name 设置的会话名 |
树、leaf 与“恢复会话”看哪一行
- 追加:新 entry 的
parentId指向当时的 leaf;同一父节点出现多个子节点,就形成分支。 - 恢复:对有效的 v3 文件,
_buildIndex()取最后一个 entry 作为 leaf。它不是从所有“无子节点的节点”中推选出来的。 - 导航:
/tree单纯跳转只改内存指针;提交消息或生成分支摘要才追加条目。只回退、不追加就退出,恢复时仍会落在文件末尾。
本机这 20 个样本恰好都是线性的,不能据此假设所有会话都没有分支。
从条目到上下文:五条规则
这五条规则可以串成一条管线:回溯路径 → 最新压缩点 → 保留区 → system 检查点与摘要 → edit 覆盖。
buildSessionPath:从 leaf 沿parentId回到根,再反转。buildContextEntries:只取最新压缩点,将它放在首位;接上从firstKeptEntryId开始的保留区(不含旧 system),以及压缩后的所有条目。buildSessionProjection:压缩点生成前置 system 检查点(若有)与摘要,再应用路径上最新的 edit;replacement: null不生成消息。
上下文和账目分开算。 路径外的分支不进本次请求,但其中的有效 usage 仍计入累计。usage entry 只计用量;custom、label 既不进模型上下文,也不直接贡献用量。
页脚的 ↑ ↓ R W $ 到底扫了什么
页脚一次性遍历整个文件的所有 entry(不是当前分支、不是压缩后的上下文),累加 assistant 消息、toolResult.usage、usage entry、compaction.usage、branch_summary.usage。只有 CH 例外:它只看最后一条 assistant 消息。
同一份会话在不同时刻的快照,可以看出两件事:累计值只增不减,CH 会跳甚至消失。
| 读到第 N 条 | ↑ | ↓ | R | W | CH | $ |
|---|---|---|---|---|---|---|
| 20 | ↑15 | ↓660 | R28k | W10.0k | 93.8% | $0.186 |
| 60 | ↑66 | ↓5.8k | R800k | W53k | 98.3% | $1.760 |
| 81 | ↑81 | ↓9.2k | R1.1M | W58k | 98.6% | $2.255 |
| 120 | ↑132 | ↓19k | R2.2M | W77k | 99.8% | $4.124 |
| 160 | ↑683 | ↓24k | R3.7M | W99k | 90.7% | $6.150 |
| 161 | ↑683 | ↓24k | R3.7M | W99k | (不显示) | $6.150 |
| 200 | ↑2.0k | ↓27k | R4.8M | W112k | 99.2% | $7.579 |
| 250 | ↑2.3k | ↓42k | R6.5M | W203k | 99.6% | $11.135 |
第 160 → 161 条只多了一条 stopReason: "error" 的空响应:累计值一点没变,CH 直接整项消失。
常见误读
- “删会话”就是删文件。
/resume里Ctrl+D也是删.jsonl;装了trash命令时进回收站,否则可能不可恢复。 - 顺序历史不等于当前上下文。 想知道“模型看到了什么”,必须重建 leaf 路径、压缩边界与 edit 投影。
- 正常运行以追加为主,但不能假设永不重写。 旧版本会话(v1/v2)加载时会迁移到 v3,并重写文件。
- 会话里几乎有你所有的敏感内容:提示词、仓库文件、命令输出、密钥片段。
/export、/share、/bug之前都要先看一遍。 - 页脚数字不能对账。 它们包含所有分支和工具用量,价格可能来自本地估算;真实账单要看供应商后台。
下一步
- 想自己统计、做时间线或分析多会话:高效读取会话数据。
- 想理解这些数字在界面上的含义:状态栏与 statusline。
- 想在程序里用受支持的 API 而非自己扫文件:SDK 与 Vue 最小集成。