Pi Agent 会话管理
Pi Agent 的会话管理系统是其最强大的特性之一。本章详细介绍会话的保存、恢复、分支和导出。
会话存储机制
每次对话会自动保存为一个会话文件，以 JSONL 格式存储在 ~/.pi/agent/sessions/ 中，按工作目录分类。
每个会话内部以树状结构组织——这意味着你可以在任意历史节点分叉，而不会丢失之前的对话内容。
~/.pi/agent/sessions/
└── my-project/
├── abc123.jsonl # 会话 1
├── def456.jsonl # 会话 2
└── ghi789.jsonl # 会话 3
启动时的会话选项
通过命令行参数在启动时控制会话行为：
实例
# 继续最近的会话
pi -c
# 浏览并选择历史会话
pi -r
# 使用指定会话文件
pi --session ~/.pi/agent/sessions/my-project/abc123.jsonl
# 使用会话 ID（支持部分匹配）
pi --session abc123
# 从指定会话分叉出新会话
pi --fork abc123
# 设置会话显示名称
pi --name "重构认证模块"
# 临时会话模式（不保存）
pi --no-session
pi -c
# 浏览并选择历史会话
pi -r
# 使用指定会话文件
pi --session ~/.pi/agent/sessions/my-project/abc123.jsonl
# 使用会话 ID（支持部分匹配）
pi --session abc123
# 从指定会话分叉出新会话
pi --fork abc123
# 设置会话显示名称
pi --name "重构认证模块"
# 临时会话模式（不保存）
pi --no-session
会话管理命令
| 命令 | 功能 | 使用场景 |
|---|---|---|
| /resume | 浏览并恢复历史会话 | 切换到之前的对话继续工作 |
| /new | 开始新会话 | 开始一个与历史无关的全新任务 |
| /name 名称 | 设置会话名 | 给会话取一个易记的名称 |
| /session | 查看会话信息 | 查看文件路径、消息数、token 用量和费用 |
| /tree | 打开会话树浏览器 | 在对话树中跳转到任意节点 |
| /fork | 分叉会话 | 从之前的用户消息创建新会话 |
| /clone | 克隆会话 | 复制当前活动分支到新会话文件 |
| /export 文件 | 导出会话 | 保存为 HTML 文件便于分享 |
| /share | 分享会话 | 上传为 GitHub Gist，生成可分享链接 |
会话树（/tree）
这是 Pi Agent 最独特的特性——会话以树状结构存储，你可以在任意历史节点分叉。
树的结构
以下是一个典型的会话树结构：
├─ user: "帮我实现一个登录功能..." │ └─ assistant: "好的，我来实现..." │ ├─ user: "用 JWT 方案..." │ │ └─ assistant: "使用 JWT 实现..." │ │ └─ user: "测试通过了" ← 当前活跃分支 │ └─ user: "还是用 Session 方案..." │ └─ assistant: "使用 Session 实现..."
在这个例子中，你从同一个起点出发，分别探索了 JWT 和 Session 两个方案，每个方案的对话都被完整保留。
树浏览器操作
| 操作 | 快捷键 | 说明 |
|---|---|---|
| 上下移动 | ↑/↓ | 在可见的条目中移动光标 |
| 翻页 | ←/→ | 向上/向下翻页 |
| 折叠/展开 | Ctrl+←/Ctrl+→ | 折叠/展开分支段或跳转 |
| 设置标签 | Shift+L | 为选中节点设置标签 |
| 确认选择 | Enter | 选中当前节点 |
| 取消 | Escape / Ctrl+C | 退出树浏览器 |
| 切换过滤模式 | Ctrl+O | 在过滤模式间循环 |
过滤模式
| 模式 | 显示内容 |
|---|---|
| default | 默认视图，折叠工具调用细节 |
| no-tools | 隐藏所有工具调用和结果 |
| user-only | 仅显示用户消息 |
| labeled-only | 仅显示有标签的条目 |
| all | 显示所有条目 |
选中用户消息会将其文本填入编辑区，让你可以重新编辑并提交，创建新的分支。选中 AI 回复或工具调用则会直接跳转到那个位置，让你可以从那里继续对话。
/tree 与 /fork 与 /clone 的区别
| 特性 | /tree | /fork | /clone |
|---|---|---|---|
| 输出 | 同一个会话文件 | 新建会话文件 | 新建会话文件 |
| 视图 | 完整对话树 | 仅显示用户消息 | 当前活动分支 |
| 典型用途 | 在同一会话中探索备选方案 | 从早前提示开始新会话 | 复制当前工作再继续 |
| 分支摘要 | 可选的摘要 | 无 | 无 |
简单来说：
- /tree：多条思路放在一起管理，方便对比
- /fork：从某个历史点重新开始，完全独立的会话
- /clone：在继续之前先做个副本，保留退路
分支摘要
当你通过 /tree 从一个分支跳到另一个分支时，Pi Agent 可以为你生成被放弃分支的摘要。
这个摘要会附加到新的位置，让你知道之前的分支做了什么：
- 不生成摘要：直接跳转，不保留被放弃分支的任何信息
- 默认摘要：使用默认提示让 AI 总结被放弃的分支
- 自定义摘要：指定关注重点，AI 按你的需求总结
你可以在设置中控制摘要行为：
实例
{
"branchSummary": {
"reserveTokens": 16384,
"skipPrompt": false
}
}
"branchSummary": {
"reserveTokens": 16384,
"skipPrompt": false
}
}
设置 skipPrompt 为 true 可以在 /tree 导航时跳过「是否生成摘要」的提问。
导出与分享会话
导出为 HTML
# 导出到默认位置 /export # 导出到指定文件 /export ~/Desktop/my-session.html
分享为 GitHub Gist
/share
执行后会创建一个私有 GitHub Gist，并生成可分享的 HTML 链接。
命令行导出
$ pi --export session.jsonl output.html
如果你做开源项目并希望将会话发布用于研究目的，可以查看 pi-share-hf 工具，它可以将会话发布到 Hugging Face 数据集。