跳转到内容

会话文件解剖

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)。按条数看,工具结果与助手响应占了大头:

本机快照的条数:toolResult 718、assistant 631、user 114、model_change 89、thinking_level_change 27、session header 20、system 12、context_edit 11、compaction 1。工具结果与助手响应合计占 83.1%。
条数分布,不是 token 或体积占比;这里只代表这份快照。打开 SVG ↗
查看这份快照的原始计数表
entry 类型条数说明
message(assistant)631每次模型响应一条
message(toolResult)718每次工具执行一条,常是最大的行
message(user)114只有真正提交的输入
model_change89中途切换模型,切得很勤
thinking_level_change27Shift+Tab 或 /thinking 的落点
message(system)12提示词与工具的增量补丁
context_edit11/edit 或扩展对历史消息的改写
compaction1自动或手动压缩
session20每个文件开头一行 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 / toolResult6 / 105 / 173
context_edit / compaction6 / 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 都有这四个字段:

字段含义注意
typeentry 类型决定它是否进上下文
id8 位十六进制,偶尔是完整 UUID从旧版本迁移过来的会话可能是长 ID
parentId父 entry 的 id,根为 null分支全靠它
timestampISO 字符串entry 用的是字符串,内层 message.timestamp 是毫秒数

两个时间戳不一致是正常的:entry 时间是条目创建时刻,message.timestamp 来自消息本身,不能一概解释成“模型返回时间”。做时间线时先统一采用哪一层;要分析请求耗时,另看 durationMs。

message 的四种 role

role关键字段是否进模型上下文
systemsections + toolsAdded / toolsRemoved是,但按增量 patch 回放
usercontent(字符串或 block 数组)是
assistantcontent、usage、stopReason、responseId是
toolResulttoolCallId、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 与“恢复会话”看哪一行

写盘顺序是 A、B、C、D,但 C 和 D 的 parentId 都指向 B。恢复时最后写入的 D 是 leaf;统计扫描所有条目的有效 usage,上下文只沿 A 到 B 到 D 的路径构建。
写盘是顺序追加,分支关系由 parentId 决定。打开 SVG ↗
  • 追加:新 entry 的 parentId 指向当时的 leaf;同一父节点出现多个子节点,就形成分支。
  • 恢复:对有效的 v3 文件,_buildIndex() 取最后一个 entry 作为 leaf。它不是从所有“无子节点的节点”中推选出来的。
  • 导航:/tree 单纯跳转只改内存指针;提交消息或生成分支摘要才追加条目。只回退、不追加就退出,恢复时仍会落在文件末尾。

本机这 20 个样本恰好都是线性的,不能据此假设所有会话都没有分支。

从条目到上下文:五条规则

这五条规则可以串成一条管线:回溯路径 → 最新压缩点 → 保留区 → system 检查点与摘要 → edit 覆盖。

示例活动路径 A、B、S、C、D、E 中,C 是最新压缩点,保留点为 B,E 要隐藏 B。裁剪得到 C、B、D、E;投影输出 C 的完整 system、摘要和 D,A 被摘要替代,旧 system S 丢弃,B 被 edit 隐藏,E 本身不生成消息。
压缩决定保留范围,context_edit 决定保留消息怎样进入模型。打开 SVG ↗
  • 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 条↑↓RWCH$
20↑15↓660R28kW10.0k93.8%$0.186
60↑66↓5.8kR800kW53k98.3%$1.760
81↑81↓9.2kR1.1MW58k98.6%$2.255
120↑132↓19kR2.2MW77k99.8%$4.124
160↑683↓24kR3.7MW99k90.7%$6.150
161↑683↓24kR3.7MW99k(不显示)$6.150
200↑2.0k↓27kR4.8MW112k99.2%$7.579
250↑2.3k↓42kR6.5MW203k99.6%$11.135

第 160 → 161 条只多了一条 stopReason: "error" 的空响应:累计值一点没变,CH 直接整项消失。

常见误读

  • “删会话”就是删文件。 /resume 里 Ctrl+D 也是删 .jsonl;装了 trash 命令时进回收站,否则可能不可恢复。
  • 顺序历史不等于当前上下文。 想知道“模型看到了什么”,必须重建 leaf 路径、压缩边界与 edit 投影。
  • 正常运行以追加为主,但不能假设永不重写。 旧版本会话(v1/v2)加载时会迁移到 v3,并重写文件。
  • 会话里几乎有你所有的敏感内容:提示词、仓库文件、命令输出、密钥片段。/export、/share、/bug 之前都要先看一遍。
  • 页脚数字不能对账。 它们包含所有分支和工具用量,价格可能来自本地估算;真实账单要看供应商后台。

下一步