Pi Agent 会话管理
Pi Agent 的会话管理系统是其最强大的特性之一。
本章详细介绍会话的保存、恢复、分支和导出。
会话存储机制
每次对话会自动保存为一个会话文件，以 JSONL 格式存储在 ~/.pi/agent/sessions/ 中，按项目路径分类。
目录名由项目的绝对路径转换而来：斜杠替换为连字符，并在前后各包裹一个 --。
文件名由创建时间戳和会话 UUID 拼接而成。
每个会话内部以树状结构组织——这意味着你可以在任意历史节点分叉，而不会丢失之前的对话内容。
~/.pi/agent/sessions/
└── --Users-runoob-projects-runoob-demo--/ # 目录名为项目路径，斜杠已替换为连字符
├── 2026-08-31T02-40-11-000Z_019fc2a1-93b4-7c22-8d5e-2b3c4d5e6f7a.jsonl # 时间戳_UUID.jsonl
├── 2026-08-31T04-12-38-000Z_2c8f71ba-4a19-4e63-9d02-7f5a6b8c9d0e.jsonl
└── 2026-08-31T08-55-02-000Z_5e3d92f4-8b26-47ac-a174-9c0d1e2f3a4b.jsonl
会话文件的内部结构
会话文件的第一行是一条固定的元数据，记录会话格式版本、会话 ID、创建时间与工作目录。
这条元数据没有 id 和 parentId 字段，不参与对话树。
从第二行开始每行一个条目，都带有 id 与 parentId 字段，二者共同构成树状结构。
条目类型包括 message、compaction、branch_summary、label、custom 等。
由 /fork 或 /clone 创建的会话，首行元数据还会多一个 parentSession 字段，指向原会话文件。
{"type":"session","version":3,"id":"019fc2a1-93b4-7c22-8d5e-2b3c4d5e6f7a","timestamp":"2026-08-31T02:40:11.000Z","cwd":"/Users/runoob/projects/runoob-demo"}
{"type":"message","id":"m1","parentId":null,"message":{"role":"user","content":[{"type":"text","text":"帮我实现登录功能"}]}}
{"type":"message","id":"m2","parentId":"m1","message":{"role":"assistant","content":[{"type":"text","text":"好的，我用 JWT 来实现"}]}}
会话目录也可以自定义，优先级从高到低依次为：--session-dir 参数、环境变量 PI_CODING_AGENT_SESSION_DIR、settings.json 中的 sessionDir。
启动时的会话选项
通过命令行参数在启动时控制会话行为：
$ pi -c Resumed session abc123-def456 (42 messages, model claude-sonnet-4-5) $ pi -r ┌ 选择要恢复的会话： │ > abc123 快速审查 3 分钟前 │ def456 重构认证模块 2 小时前 └ $ pi --session ~/.pi/agent/sessions/--Users-runoob-projects-runoob-demo--/2026-08-30T09-15-04-000Z_019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f.jsonl Resumed session 019fbb5d-7a2e-7f31-b5c4-1a2b3c4d5e6f $ pi --session abc123 Resumed session abc123-def456 $ pi --fork abc123 Forked to session 9f2e7a01-5c48 $ pi --name "重构认证模块" Session renamed: 重构认证模块 $ pi --no-session Temporary session (will not be saved)
会话管理命令
进入交互模式后，以下命令覆盖了会话的日常管理工作。
| 命令 | 功能 | 使用场景 |
|---|---|---|
| /resume | 浏览并恢复历史会话 | 切换到之前的对话继续工作 |
| /new | 开始新会话 | 开始一个与历史无关的全新任务 |
| /name 名称 | 设置会话名 | 给会话取一个易记的名称 |
| /session | 查看会话信息 | 查看文件路径、消息数、token 用量和费用 |
| /tree | 打开会话树浏览器 | 在对话树中跳转到任意节点 |
| /fork | 分叉会话 | 从之前的用户消息创建新会话 |
| /clone | 克隆会话 | 复制当前活动分支到新会话文件 |
| /export 文件 | 导出为 HTML 或 JSONL 文件 | 本地归档或离线分享 |
| /share | 分享会话 | 上传为 GitHub Gist，生成可分享链接 |
/resume 会话选择器
输入 /resume 或用 pi -r 启动，会打开当前项目的会话选择器。
在列表中直接输入字符即可过滤会话，其余操作按键如下：
| 操作 | 按键 | 说明 |
|---|---|---|
| 过滤会话 | 直接输入字符 | 按输入内容实时过滤当前项目的会话列表 |
| 切换路径显示 | Ctrl+P | 显示或隐藏会话的工作目录路径 |
| 切换排序 | Ctrl+S | 在排序方式之间切换 |
| 仅显示已命名会话 | Ctrl+N | 过滤出设置过名称的会话 |
| 重命名 | Ctrl+R | 修改选中会话的名称 |
| 删除 | Ctrl+D | 确认后执行；系统有 trash 命令时移入回收站而非直接删除 |
会话树（/tree）
这是 Pi Agent 最独特的特性——会话以树状结构存储，你可以在任意历史节点分叉。
树的结构
以下是一个典型的会话树结构：
├─ user: "帮我实现一个登录功能..." │ └─ assistant: "好的，我来实现..." │ ├─ user: "用 JWT 方案..." │ │ └─ assistant: "使用 JWT 实现..." │ │ └─ user: "测试通过了" ← 当前活跃分支 │ └─ user: "还是用 Session 方案..." │ └─ assistant: "使用 Session 实现..."
在这个例子中，你从同一个起点出发，分别探索了 JWT 和 Session 两个方案，每个方案的对话都被完整保留。
树浏览器操作
打开 /tree 后，用以下按键在树中移动和选择。
| 操作 | 快捷键 | 说明 |
|---|---|---|
| 上下移动 | ↑/↓ | 在可见的条目中移动光标 |
| 翻页 | ←/→ | 向上/向下翻页 |
| 折叠/展开 | Ctrl+←/Ctrl+→ 或 Alt+←/Alt+→ | 折叠/展开分支段或跳转 |
| 设置标签 | Shift+L | 为选中节点设置标签 |
| 切换时间戳 | Shift+T | 显示/隐藏条目标签的时间戳（标签用 Shift+L 设置） |
| 确认选择 | Enter | 选中当前节点 |
| 取消 | Escape / Ctrl+C | 退出树浏览器 |
| 切换过滤模式 | Ctrl+O | 在过滤模式间循环（仅 /tree 浏览器内生效） |
过滤模式
过滤模式决定树浏览器中显示哪些条目，按 Ctrl+O 循环切换。
| 模式 | 显示内容 |
|---|---|
| default | 默认视图，折叠工具调用细节 |
| no-tools | 隐藏所有工具调用和结果 |
| user-only | 仅显示用户消息 |
| labeled-only | 仅显示有标签的条目 |
| all | 显示所有条目 |
选中用户消息会将其文本填入编辑区，让你可以重新编辑并提交，创建新的分支。
选中 AI 回复或工具调用则会直接跳转到那个位置，让你可以从那里继续对话。
/tree 与 /fork 与 /clone 的区别
三者都能回到历史位置，差别在于是否产生新的会话文件，以及能看到多大范围的对话。
| 命令 | 输出 | 视图 | 典型用途 | 分支摘要 | 一句话记忆 |
|---|---|---|---|---|---|
| /tree | 同一个会话文件 | 完整对话树 | 在同一会话中探索备选方案 | 可选的摘要 | 多条思路放在一起管理，方便对比 |
| /fork | 新建会话文件 | 仅显示用户消息 | 从早前提示开始新会话 | 无 | 从某个历史点重新开始，完全独立 |
| /clone | 新建会话文件 | 当前活动分支 | 复制当前工作再继续 | 无 | 在继续之前先做个副本，保留退路 |
分支摘要
当你通过 /tree 从一个分支跳到另一个分支时，Pi Agent 可以为你生成被放弃分支的摘要。
这个摘要会附加到新的位置，让你知道之前的分支做了什么：
| 模式 | 行为 | 适用场景 |
|---|---|---|
| 不生成摘要 | 直接跳转，不保留被放弃分支的任何信息 | 被放弃的尝试没有保留价值 |
| 默认摘要 | 使用默认提示让 AI 总结被放弃的分支 | 只想大致了解之前做了什么 |
| 自定义摘要 | 指定关注重点，AI 按你的需求总结 | 需要带走特定结论，例如踩过的坑 |
你可以在 ~/.pi/agent/settings.json 中控制摘要行为：
实例
"branchSummary": {
"reserveTokens": 16384,
"skipPrompt": false
}
}
设置 skipPrompt 为 true 可以在 /tree 导航时跳过「是否生成摘要」的提问。
跳过提问后默认不生成摘要，直接跳转到目标位置。
导出与分享会话
会话可以导出为本地文件，也可以直接上传生成分享链接。
导出为 HTML
导出会生成一个可直接在浏览器打开的单文件页面，适合离线查看。
# 导出到默认位置 /export # 导出到指定文件 /export ~/Desktop/my-session.html
分享为 GitHub Gist
不想传文件时，用 /share 一条命令生成在线链接。
/share
执行后会创建一个私有 GitHub Gist，并生成可分享的 HTML 链接。
命令行导出
不进入交互模式也可以导出已有会话。
$ pi --export session.jsonl output.html Exported to output.html (128 KB)
如果你做开源项目并希望将会话发布用于研究目的，可以查看 pi-share-hf 工具，它可以将会话发布到 Hugging Face 数据集。