Session 会话格式

概述

Pi 会话存储为 JSONL（JSON Lines）文件，每行是一个带 type 字段的 JSON 对象。

---

文件位置

~/.pi/agent/sessions/--<path>--/<timestamp>_<uuid>.jsonl

<path> 是工作目录，/ 替换为 -。

---

会话版本

版本	说明
v1	线性条目序列（旧版，加载时自动迁移）
v2	树结构，通过 id/parentId 链接
v3	将 hookMessage 角色重命名为 custom

---

消息类型

内容块（Content Blocks）

// 文本块
{ type: "text", text: "Hello" }

// 图片块
{ type: "image", data: "base64...", mimeType: "image/png" }

// 思考块
{ type: "thinking", thinking: "让我想想..." }

// 工具调用块
{ type: "toolCall", id: "abc", name: "read", arguments: {...} }

基础消息类型

// 用户消息
{ role: "user", content: "Hello", timestamp: 1234567890 }

// 助手消息
{ 
  role: "assistant", 
  content: [...],
  api: "openai",
  provider: "openai",
  model: "gpt-4o",
  usage: { input: 100, output: 50, cost: {...} },
  stopReason: "stop"
}

// 工具结果消息
{ 
  role: "toolResult",
  toolCallId: "abc",
  toolName: "read",
  content: [{ type: "text", text: "文件内容..." }],
  isError: false,
  timestamp: 1234567890
}

---

删除会话

# 方式 1：直接删除文件
rm ~/.pi/agent/sessions/--path--/session.jsonl

# 方式 2：交互式删除（/resume 中按 Ctrl+D）

Pi 使用 trash CLI 避免永久删除。

---

相关源码

文件	说明
session-manager.ts	会话管理器
messages.ts	扩展消息类型
@mariozechner/pi-ai/types.ts	基础消息类型

---

翻译自 pi-coding-agent/docs/session.md