会话文件格式

会话以 JSONL（JSON Lines）文件存储。每行是一个包含 type 字段的 JSON 对象。会话条目通过 id/parentId 字段形成树形结构，支持在不创建新文件的情况下进行原地分支。

文件位置

~/.pi/agent/sessions/--<路径>--/<时间戳>_<uuid>.jsonl

其中 <路径> 是工作目录，将 / 替换为 -。

删除会话

可以通过删除 ~/.pi/agent/sessions/ 下的 .jsonl 文件来移除会话。

Pi 还支持从 /resume 交互式删除会话（选择一个会话并按 Ctrl+D，然后确认）。当可用时，pi 使用 trash CLI 来避免永久删除。

会话版本

会话在头部包含版本字段：

版本 1：线性条目序列（旧版，加载时自动迁移）
版本 2：通过 id/parentId 关联的树形结构
版本 3：将 hookMessage 角色重命名为 custom（扩展统一）

现有会话在加载时会自动迁移到当前版本（v3）。

源文件

GitHub 上的源码（pi）：

packages/coding-agent/src/core/session-manager.ts - 会话条目类型和 SessionManager
packages/coding-agent/src/core/messages.ts - 扩展消息类型（BashExecutionMessage、CustomMessage 等）
packages/ai/src/types.ts - 基础消息类型（UserMessage、AssistantMessage、ToolResultMessage）
packages/agent/src/types.ts - AgentMessage 并集类型

要在项目中查看 TypeScript 定义，请检查 node_modules/@earendil-works/pi-coding-agent/dist/ 和 node_modules/@earendil-works/pi-ai/dist/。

消息类型

会话条目包含 AgentMessage 对象。了解这些类型对于解析会话和编写扩展至关重要。

内容块

消息包含类型化的内容块数组：

typescript

interface TextContent {
  type: "text";
  text: string;
}

interface ImageContent {
  type: "image";
  data: string;      // base64 编码
  mimeType: string;  // 例如 "image/jpeg"、"image/png"
}

interface ThinkingContent {
  type: "thinking";
  thinking: string;
}

interface ToolCall {
  type: "toolCall";
  id: string;
  name: string;
  arguments: Record<string, any>;
}

基础消息类型（来自 pi-ai）

typescript

interface UserMessage {
  role: "user";
  content: string | (TextContent | ImageContent)[];
  timestamp: number;  // 毫秒 Unix 时间戳
}

interface AssistantMessage {
  role: "assistant";
  content: (TextContent | ThinkingContent | ToolCall)[];
  api: string;
  provider: string;
  model: string;
  usage: Usage;
  stopReason: "stop" | "length" | "toolUse" | "error" | "aborted";
  errorMessage?: string;
  timestamp: number;
}

interface ToolResultMessage {
  role: "toolResult";
  toolCallId: string;
  toolName: string;
  content: (TextContent | ImageContent)[];
  details?: any;      // 工具特定的元数据
  isError: boolean;
  timestamp: number;
}

interface Usage {
  input: number;
  output: number;
  cacheRead: number;
  cacheWrite: number;
  totalTokens: number;
  cost: {
    input: number;
    output: number;
    cacheRead: number;
    cacheWrite: number;
    total: number;
  };
}

扩展消息类型（来自 pi-coding-agent）

typescript

interface BashExecutionMessage {
  role: "bashExecution";
  command: string;
  output: string;
  exitCode: number | undefined;
  cancelled: boolean;
  truncated: boolean;
  fullOutputPath?: string;
  excludeFromContext?: boolean;  // !! 前缀命令为 true
  timestamp: number;
}

interface CustomMessage {
  role: "custom";
  customType: string;            // 扩展标识符
  content: string | (TextContent | ImageContent)[];
  display: boolean;              // 是否在 TUI 中显示
  details?: any;                 // 扩展特定的元数据
  timestamp: number;
}

interface BranchSummaryMessage {
  role: "branchSummary";
  summary: string;
  fromId: string;                // 我们分支的条目
  timestamp: number;
}

interface CompactionSummaryMessage {
  role: "compactionSummary";
  summary: string;
  tokensBefore: number;
  timestamp: number;
}

AgentMessage 并集

typescript

type AgentMessage =
  | UserMessage
  | AssistantMessage
  | ToolResultMessage
  | BashExecutionMessage
  | CustomMessage
  | BranchSummaryMessage
  | CompactionSummaryMessage;

条目基础

所有条目（除了 SessionHeader）都扩展 SessionEntryBase：

typescript

interface SessionEntryBase {
  type: string;
  id: string;           // 8 位十六进制 ID
  parentId: string | null;  // 父条目 ID（第一条为 null）
  timestamp: string;    // ISO 时间戳
}

条目类型

SessionHeader

文件的第一行。仅包含元数据，不属于树形结构（无 id/parentId）。

json

{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}

对于有父会话的会话（通过 /fork、/clone 或 newSession({ parentSession }) 创建）：

json

{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project","parentSession":"/path/to/original/session.jsonl"}

SessionMessageEntry

对话中的一条消息。message 字段包含一个 AgentMessage。

json

{"type":"message","id":"a1b2c3d4","parentId":"prev1234","timestamp":"2024-12-03T14:00:01.000Z","message":{"role":"user","content":"Hello"}}
{"type":"message","id":"b2c3d4e5","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:00:02.000Z","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}],"provider":"anthropic","model":"claude-sonnet-4-5","usage":{...},"stopReason":"stop"}}
{"type":"message","id":"c3d4e5f6","parentId":"b2c3d4e5","timestamp":"2024-12-03T14:00:03.000Z","message":{"role":"toolResult","toolCallId":"call_123","toolName":"bash","content":[{"type":"text","text":"输出"}],"isError":false}}

ModelChangeEntry

当用户在会话中途切换模型时发出。

json

{"type":"model_change","id":"d4e5f6g7","parentId":"c3d4e5f6","timestamp":"2024-12-03T14:05:00.000Z","provider":"openai","modelId":"gpt-4o"}

ThinkingLevelChangeEntry

当用户更改思考/推理级别时发出。

json

{"type":"thinking_level_change","id":"e5f6g7h8","parentId":"d4e5f6g7","timestamp":"2024-12-03T14:06:00.000Z","thinkingLevel":"high"}

CompactionEntry

上下文压缩时创建。存储早期消息的摘要。

json

{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"用户讨论了 X、Y、Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}

可选字段：

details：实现特定的数据（例如，默认值为 { readFiles: 字符串数组，modifiedFiles: 字符串数组 }，或扩展的自定义数据）
fromHook：true 表示由扩展生成，false/undefined 表示 pi 生成（旧字段名）

BranchSummaryEntry

通过 /tree 切换分支时创建，由 LLM 生成从左分支到共同祖先的摘要。捕获被放弃路径的上下文。

json

{"type":"branch_summary","id":"g7h8i9j0","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:15:00.000Z","fromId":"f6g7h8i9","summary":"分支探索了方法 A..."}

可选字段：

details：文件追踪数据（默认 { readFiles: 字符串数组，modifiedFiles: 字符串数组 }，或扩展的自定义数据）
fromHook：true 表示由扩展生成，false/undefined 表示 pi 生成（旧字段名）

CustomEntry

扩展状态持久化。不参与 LLM 上下文。

json

{"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}

使用 customType 在重新加载时识别扩展的条目。交互模式可以通过 pi.registerEntryRenderer(customType, renderer) 渲染自定义条目，但它们仍然不参与 LLM 上下文。

CustomMessageEntry

扩展注入的消息，参与 LLM 上下文。

json

{"type":"custom_message","id":"i9j0k1l2","parentId":"h8i9j0k1","timestamp":"2024-12-03T14:25:00.000Z","customType":"my-extension","content":"注入的上下文...","display":true}

字段：

content：字符串或 (TextContent | ImageContent)[]（与 UserMessage 相同）
display：true 表示在 TUI 中以独特样式显示，false 表示隐藏
details：可选的扩展特定元数据（不发送给 LLM）

LabelEntry

用户在条目上的自定义书签/标记。

json

{"type":"label","id":"j0k1l2m3","parentId":"i9j0k1l2","timestamp":"2024-12-03T14:30:00.000Z","targetId":"a1b2c3d4","label":"checkpoint-1"}

将 label 设为 undefined 可清除标记。

SessionInfoEntry

会话元数据（例如用户定义的显示名称）。通过 /name、--name / -n 或在扩展中调用 pi.setSessionName() 设置。

json

{"type":"session_info","id":"k1l2m3n4","parentId":"j0k1l2m3","timestamp":"2024-12-03T14:35:00.000Z","name":"重构认证模块"}

设置会话名称后，在会话选择器（/resume）中将显示该名称，而不是第一条消息。

树形结构

条目形成一棵树：

第一条的 parentId 为 null
后续每条通过 parentId 指向其父
分支从较早的条目创建新子条目
"叶子"是当前树中的位置

[用户消息] ─── [助手] ─── [用户消息] ─── [助手] ─┬─ [用户消息] ← 当前叶子
                                                 │
                                                 └─ [分支摘要] ─── [用户消息] ← 替代分支

上下文构建

buildContextEntries() 从当前叶子遍历到根，生成活动条目列表，同时尊重压缩：

收集路径上的所有条目
如果路径上有 CompactionEntry：
- 首先包含压缩条目
- 然后从 firstKeptEntryId 到压缩的条目
- 然后是压缩之后的条目
在选定范围内保留非消息条目，以便交互模式可以渲染它们

buildSessionContext() 在此基础上生成给 LLM 的消息列表：

从完整路径提取当前模型和思考级别设置
将选定的条目转换为消息：
- message → 存储的 AgentMessage
- compaction → compactionSummary
- branch_summary → branchSummary
- custom_message → CustomMessage
- custom → 无上下文消息

解析示例

typescript

import { readFileSync } from "fs";

const lines = readFileSync("session.jsonl", "utf8").trim().split("\n");

for (const line of lines) {
  const entry = JSON.parse(line);

  switch (entry.type) {
    case "session":
      console.log(`会话 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}] 压缩：${entry.tokensBefore} 个 token 总结`);
      break;
    case "branch_summary":
      console.log(`[${entry.id}] 从 ${entry.fromId} 分支`);
      break;
    case "custom":
      console.log(`[${entry.id}] 自定义 (${entry.customType})：${JSON.stringify(entry.data)}`);
      break;
    case "custom_message":
      console.log(`[${entry.id}] 扩展消息 (${entry.customType})：${entry.content}`);
      break;
    case "label":
      console.log(`[${entry.id}] 标签 "${entry.label}" 在 ${entry.targetId}`);
      break;
    case "model_change":
      console.log(`[${entry.id}] 模型：${entry.provider}/${entry.modelId}`);
      break;
    case "thinking_level_change":
      console.log(`[${entry.id}] 思考：${entry.thinkingLevel}`);
      break;
  }
}

SessionManager API

用于编程方式操作会话的关键方法。

静态创建方法

SessionManager.create(cwd, sessionDir?) - 新会话
SessionManager.open(path, sessionDir?) - 打开现有会话文件
SessionManager.continueRecent(cwd, sessionDir?) - 继续最近或创建新会话
SessionManager.inMemory(cwd?) - 无文件持久化
SessionManager.forkFrom(sourcePath, targetCwd, sessionDir?) - 从另一个项目分叉会话

静态列表方法

SessionManager.list(cwd, sessionDir?, onProgress?) - 为目录列出会话
SessionManager.listAll(onProgress?) - 列出所有项目的所有会话

实例方法 - 会话管理

newSession(options?) - 启动新会话（选项：{ parentSession?: 字符串 }）
setSessionFile(path) - 切换到不同的会话文件
createBranchedSession(leafId) - 提取分支到新会话文件

实例方法 - 追加（都返回条目 ID）

appendMessage(message) - 添加消息
appendThinkingLevelChange(level) - 记录思考变更
appendModelChange(provider, modelId) - 记录模型变更
appendCompaction(summary, firstKeptEntryId, tokensBefore, details?, fromHook?) - 添加压缩
appendCustomEntry(customType, data?) - 扩展状态（不在上下文中）
appendSessionInfo(name) - 设置会话显示名称
appendCustomMessageEntry(customType, content, display, details?) - 扩展消息（在上下文中）
appendLabelChange(targetId, label) - 设置/清除标签

实例方法 - 树导航

getLeafId() - 当前位置
getLeafEntry() - 获取当前叶子条目
getEntry(id) - 按 ID 获取条目
getBranch(fromId?) - 从条目到根的遍历
getTree() - 获取完整的树结构
getChildren(parentId) - 获取直接子项
getLabel(id) - 获取条目的标签
branch(entryId) - 将叶子移动到较早的条目
resetLeaf() - 将叶子重置为 null（在任意条目之前）
branchWithSummary(entryId, summary, details?, fromHook?) - 带上下文摘要的分支

实例方法 - 上下文和信息

buildContextEntries() - 获取应用压缩的活跃分支条目
buildSessionContext() - 获取 LLM 所需的消息、思考级别和模型
getEntries() - 所有条目（不包括头部）
getHeader() - 会话头部元数据
getSessionName() - 从最新的 session_info 条目获取显示名称
getCwd() - 工作目录
getSessionDir() - 会话存储目录
getSessionId() - 会话 UUID
getSessionFile() - 会话文件路径（内存会话为 undefined）
isPersisted() - 会话是否保存到磁盘

会话文件格式 ​

文件位置 ​

删除会话 ​

会话版本 ​

源文件 ​

消息类型 ​

内容块 ​

基础消息类型（来自 pi-ai） ​

扩展消息类型（来自 pi-coding-agent） ​

AgentMessage 并集 ​

条目基础 ​

条目类型 ​

SessionHeader ​

SessionMessageEntry ​

ModelChangeEntry ​

ThinkingLevelChangeEntry ​

CompactionEntry ​

BranchSummaryEntry ​

CustomEntry ​

CustomMessageEntry ​

LabelEntry ​

SessionInfoEntry ​

树形结构 ​

上下文构建 ​

解析示例 ​

SessionManager API ​

静态创建方法 ​

静态列表方法 ​

实例方法 - 会话管理 ​

实例方法 - 追加（都返回条目 ID） ​

实例方法 - 树导航 ​

实例方法 - 上下文和信息 ​

会话文件格式

文件位置

删除会话

会话版本

源文件

消息类型

内容块

基础消息类型（来自 pi-ai）

扩展消息类型（来自 pi-coding-agent）

AgentMessage 并集

条目基础

条目类型

SessionHeader

SessionMessageEntry

ModelChangeEntry

ThinkingLevelChangeEntry

CompactionEntry

BranchSummaryEntry

CustomEntry

CustomMessageEntry

LabelEntry

SessionInfoEntry

树形结构

上下文构建

解析示例

SessionManager API

静态创建方法

静态列表方法

实例方法 - 会话管理

实例方法 - 追加（都返回条目 ID）

实例方法 - 树导航

实例方法 - 上下文和信息