← Pi Agents

会话文件格式

一行一个 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() 从当前叶子走向根,并在尊重压缩的前提下产出活动条目列表:

  1. 收集该路径上的所有条目。
  2. 如果路径上有一个或多个 CompactionEntry 值,使用最新的那个,先包含那个压缩条目,包含自 firstKeptEntryId 起、到但不包括该压缩条目为止的非系统条目,并包含该压缩条目之后的条目。
  3. 保留所选范围内的非消息条目,好让交互模式能渲染它们。

然后 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 重启时被从零重建,而这正是下一章的主题。