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会话管理命令命令功能使用场景/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→折叠/展开分支段或跳转设置标签ShiftL为选中节点设置标签确认选择Enter选中当前节点取消Escape / CtrlC退出树浏览器切换过滤模式CtrlO在过滤模式间循环过滤模式模式显示内容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}}设置 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 数据集。