Pi 官方文档
会话格式
会话文件格式
会话以 JSONL（JSON Lines）文件形式存储。每一行都是一个带有 type 字段的 JSON 对象。会话条目通过 id/parentId 字段形成树结构，因此可以在原地分支，而不用创建新文件。
文件位置
~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl
其中 <path> 是工作目录名，/ 会替换成 -。
删除会话
删除 ~/.pi/agent/sessions/ 下对应的 .jsonl 文件，就可以移除会话。
Pi 也支持在 /resume 里交互式删除会话（选中一个会话，按 Ctrl+D，然后确认）。如果可用，pi 会使用 trash CLI，避免永久删除。
会话版本
会话在头部包含一个 version 字段：
- Version 1：线性条目序列（旧格式，加载时会自动迁移）
- Version 2：通过
id/parentId关联的树结构 - Version 3：将
hookMessage角色重命名为custom（扩展统一）
现有会话在加载时会自动迁移到当前版本（v3）。
源文件
GitHub 上的源代码（pi-mono）：
packages/coding-agent/src/core/session-manager.ts- 会话条目类型和 SessionManagerpackages/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 对象。要解析会话并编写扩展，理解这些类型很重要。
内容块
消息包含按类型划分的内容块数组：
interface TextContent {
type: "text";
text: string;
}
interface ImageContent {
type: "image";
data: string; // base64 encoded
mimeType: string; // e.g., "image/jpeg", "image/png"
}
interface ThinkingContent {
type: "thinking";
thinking: string;
}
interface ToolCall {
type: "toolCall";
id: string;
name: string;
arguments: Record<string, any>;
}
基础消息类型（来自 pi-ai）
interface UserMessage {
role: "user";
content: string | (TextContent | ImageContent)[];
timestamp: number; // Unix ms
}
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; // Tool-specific metadata
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）
interface BashExecutionMessage {
role: "bashExecution";
command: string;
output: string;
exitCode: number | undefined;
cancelled: boolean;
truncated: boolean;
fullOutputPath?: string;
excludeFromContext?: boolean; // true for !! prefix commands
timestamp: number;
}
interface CustomMessage {
role: "custom";
customType: string; // Extension identifier
content: string | (TextContent | ImageContent)[];
display: boolean; // Show in TUI
details?: any; // Extension-specific metadata
timestamp: number;
}
interface BranchSummaryMessage {
role: "branchSummary";
summary: string;
fromId: string; // Entry we branched from
timestamp: number;
}
interface CompactionSummaryMessage {
role: "compactionSummary";
summary: string;
tokensBefore: number;
timestamp: number;
}
AgentMessage 联合类型
type AgentMessage =
| UserMessage
| AssistantMessage
| ToolResultMessage
| BashExecutionMessage
| CustomMessage
| BranchSummaryMessage
| CompactionSummaryMessage;
条目基类
所有条目（SessionHeader 除外）都继承 SessionEntryBase：
interface SessionEntryBase {
type: string;
id: string; // 8-char hex ID
parentId: string | null; // Parent entry ID (null for first entry)
timestamp: string; // ISO timestamp
}
条目类型
SessionHeader
文件的第一行。只包含元数据，不属于树结构（没有 id/parentId）。
{"type":"session","version":3,"id":"uuid","timestamp":"2024-12-03T14:00:00.000Z","cwd":"/path/to/project"}
对于有父会话的会话（通过 /fork、/clone 或 newSession({ parentSession }) 创建）：
{"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。
{"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":"output"}],"isError":false}}
模型变更条目
当用户在会话中途切换模型时触发。
{"type":"model_change","id":"d4e5f6g7","parentId":"c3d4e5f6","timestamp":"2024-12-03T14:05:00.000Z","provider":"openai","modelId":"gpt-4o"}
ThinkingLevelChangeEntry
当用户更改思考/推理级别时触发。
{"type":"thinking_level_change","id":"e5f6g7h8","parentId":"d4e5f6g7","timestamp":"2024-12-03T14:06:00.000Z","thinkingLevel":"high"}
上下文压缩条目
当上下文被上下文压缩时创建。保存较早消息的摘要。
{"type":"compaction","id":"f6g7h8i9","parentId":"e5f6g7h8","timestamp":"2024-12-03T14:10:00.000Z","summary":"User discussed X, Y, Z...","firstKeptEntryId":"c3d4e5f6","tokensBefore":50000}
可选字段：
details：实现相关数据（例如，默认情况下为{ readFiles: string[], modifiedFiles: string[] }，或者扩展的自定义数据）fromHook：如果由扩展生成则为true，如果由 pi 生成则为false/undefined（旧字段名）
分支摘要条目
通过 /tree 切换分支时创建。它包含一段由 LLM 生成的左侧分支摘要，范围到共同祖先为止。会捕获被放弃路径中的上下文。
{"type":"branch_summary","id":"g7h8i9j0","parentId":"a1b2c3d4","timestamp":"2024-12-03T14:15:00.000Z","fromId":"f6g7h8i9","summary":"Branch explored approach A..."}
可选字段：
details：文件跟踪数据（{ readFiles: string[], modifiedFiles: string[] }）用于默认情况，或者用于扩展的自定义数据fromHook：如果由扩展生成则为true，如果由 pi 生成则为false/undefined（旧字段名）
CustomEntry
扩展状态持久化。不会参与 LLM 上下文。
{"type":"custom","id":"h8i9j0k1","parentId":"g7h8i9j0","timestamp":"2024-12-03T14:20:00.000Z","customType":"my-extension","data":{"count":42}}
重载时使用 customType 来识别你的扩展条目。
CustomMessageEntry
由扩展注入、会参与 LLM 上下文的消息。
{"type":"custom_message","id":"i9j0k1l2","parentId":"h8i9j0k1","timestamp":"2024-12-03T14:25:00.000Z","customType":"my-extension","content":"Injected context...","display":true}
字段：
content：字符串或(TextContent | ImageContent)[]（与 UserMessage 相同）display：true= 在 TUI 中以不同样式显示，false= 隐藏details：可选的扩展专属元数据（不会发送给 LLM）
LabelEntry
用户为某个条目定义的书签/标记。
{"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() 设置。
{"type":"session_info","id":"k1l2m3n4","parentId":"j0k1l2m3","timestamp":"2024-12-03T14:35:00.000Z","name":"Refactor auth module"}
设置后，会话名称会显示在会话选择器（/resume）中，而不是第一条消息。
树结构
条目组成一棵树：
- 第一条条目的
parentId: null - 之后的每条条目都通过
parentId指向它的父级 - 分支会从更早的条目创建新的子节点
- “叶子”是树中当前所在的位置
[user msg] ─── [assistant] ─── [user msg] ─── [assistant] ─┬─ [user msg] ← current leaf
│
└─ [branch_summary] ─── [user msg] ← alternate branch
上下文构建
buildSessionContext() 会从当前叶子一路向上遍历到根节点，为 LLM 生成消息列表：
- 收集路径上的所有条目
- 提取当前模型和思考级别设置
- 如果路径上有一个
CompactionEntry：- 先输出摘要
- 然后输出从
firstKeptEntryId到上下文压缩点的消息 - 再输出上下文压缩后的消息
- 将
BranchSummaryEntry和CustomMessageEntry转换为对应的消息格式
解析示例
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(`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 "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;
}
}
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?: string }）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?)- 带上下文摘要创建分支
实例方法 - 上下文与信息
buildSessionContext()- 获取供 LLM 使用的 messages、thinkingLevel 和 modelgetEntries()- 所有条目（不含 header）getHeader()- 会话 header 元数据getSessionName()- 从最新的 session_info 条目获取显示名称getCwd()- 当前工作目录getSessionDir()- 会话存储目录getSessionId()- 会话 UUIDgetSessionFile()- 会话文件路径（内存中的会话为 undefined）isPersisted()- 会话是否已保存到磁盘