11  会话管理

11.1 概述

Pi 将对话保存为会话，使你可以继续之前的工作、从早期轮次创建分支，以及回溯之前探索过的路径。

11.2 会话存储

Pi 自动将会话保存到 ~/.pi/agent/sessions/ 目录，按工作目录组织。每个会话是一个具有树形结构的 JSONL 文件。

pi -c                  # 继续最近的会话
pi -r                  # 浏览并选择历史会话
pi --no-session        # 临时模式，不保存
pi --name "my task"    # 启动时设置会话名称
pi --session <path|id> # 使用特定会话文件或部分 UUID
pi --fork <path|id>    # 将会话分叉为新文件

在交互模式中使用 /session 命令查看当前会话文件、会话 ID、消息数量、Token 用量和费用。

Note

会话文件采用 JSONL（JSON Lines）格式，每行一个 JSON 对象。文件包含消息条目、模型变更、思考级别变更、标签、压缩记录、分支摘要和扩展条目。关于文件格式的完整文档，请参阅 Session Format 参考。

11.3 会话命令

命令 描述
/resume 浏览并选择历史会话
/new 开始新会话
/name <name> 设置当前会话显示名称
/session 显示会话信息
/tree 导航当前会话树
/fork 从之前的用户消息创建新会话
/clone 复制当前活跃分支到新会话
/compact [prompt] 压缩旧上下文
/export [file] 导出会话为 HTML
/share 上传为私有 GitHub Gist

11.4 恢复和删除会话

/resume 打开当前项目的交互式会话选择器。pi -r 在启动时打开同样的选择器。

在选择器中你可以：

操作 快捷键
搜索 直接输入文字
切换路径显示 Ctrl+P
切换排序模式 Ctrl+S
过滤命名会话 Ctrl+N
重命名 Ctrl+R
删除 Ctrl+D，然后确认
Tip

当可用时，Pi 使用 trash CLI 来删除会话文件，而不是永久移除。这意味着你可以在系统回收站中找回被删除的会话。

11.5 命名会话

使用 /name <name> 设置人类可读的会话名称：

/name Refactor auth module

也可以在启动时设置：

pi --name "Refactor auth module"
pi --name "CI audit" -p "Review this build failure"

命名会话在 /resume 和 pi -r 中更容易找到。

11.6 分支机制详解

11.6.1 会话的树形结构

Pi 的会话以树形结构存储，而不是线性序列。每个条目都有 id 和 parentId，当前位置是活跃的叶子节点。

├─ user: "Hello, can you help..."
│ └─ assistant: "Of course! I can..."
│   ├─ user: "Let's try approach A..."
│   │   └─ assistant: "For approach A..."
│   │     └─ user: "That worked..." ← 当前活跃位置
│   └─ user: "Actually, approach B..."
│       └─ assistant: "For approach B..."
Note

这种树形结构意味着你不需要为”尝试不同方案”而创建新文件——你可以在同一个会话中探索多条路径，随时切换。

11.6.2 /tree 命令

/tree 让你跳转到会话中的任意先前节点，并从那里继续对话——无需创建新文件。这是一种原地探索替代方案的方式。

11.6.3 树控件

按键 操作
↑/↓ 导航可见条目
←/→ 上/下翻页
Ctrl+←/Ctrl+→ 或 Alt+←/Alt+→ 折叠/展开或跳转分支段
Shift+L 设置或清除选中条目的标签
Shift+T 切换标签时间戳
Enter 选择条目
Escape/Ctrl+C 取消
Ctrl+O 循环过滤模式

过滤模式包括：default、no-tools（隐藏工具结果）、user-only（仅用户消息）、labeled-only（仅标记条目）和 all（所有条目）。

Tip

使用设置中的 treeFilterMode 可以配置 /tree 的默认过滤模式。

11.6.4 选择行为

选择用户消息或自定义消息时：

  • 将叶子节点移动到所选消息的父节点
  • 将所选消息文本放入编辑器
  • 允许你编辑并重新提交，创建一个新分支

选择助手消息、工具消息、压缩消息或其他非用户条目时：

  • 将叶子节点移动到该条目
  • 编辑器保持为空
  • 允许你从该点继续

选择根用户消息：

  • 重置叶子节点为空对话
  • 将原始提示放入编辑器

11.6.5 /tree、/fork 和 /clone 对比

特性 /tree /fork /clone
输出 同一会话文件 新会话文件 新会话文件
视图 完整树 用户消息选择器 当前活跃分支
典型用途 原地探索替代方案 从早期提示开始新会话 继续前复制当前工作
摘要 可选分支摘要 无 无
Note
  • 使用 /tree 当你想将替代方案保留在同一个会话中
  • 使用 /fork 当你想要一个基于早期提示的独立会话文件
  • 使用 /clone 当你想在继续之前复制当前工作到新文件

11.7 分支摘要

当 /tree 从一个分支切换到另一个分支时，Pi 可以对被放弃的分支进行摘要，并将该摘要附加到新位置。这保留了离开路径中的重要上下文，而无需重放整个分支。

当 Pi 提示时，你可以选择：

  1. 不生成摘要：直接切换，不保留被放弃分支的信息
  2. 使用默认提示摘要：Pi 使用标准摘要格式生成总结
  3. 使用自定义指令摘要：你指定摘要的重点和方向
Tip

分支摘要是上下文管理的有力工具。当你探索了某个方案但最终选择了另一方案时，摘要可以保留关键发现和决策，避免这些信息在切换分支后丢失。

关于分支摘要的内部实现机制和扩展钩子，请参阅上下文压缩章节。

11.8 会话格式

会话文件是 JSONL 格式，包含以下类型的条目：

  • 消息条目：用户消息、助手响应、工具调用、工具结果
  • 模型变更：记录模型切换
  • 思考级别变更：记录思考级别调整
  • 标签：用户设置的节点标签
  • 压缩记录（CompactionEntry）：上下文压缩摘要
  • 分支摘要（BranchSummaryEntry）：分支切换时的摘要
  • 扩展条目：扩展写入的自定义数据
Note

关于 JSONL 文件格式解析、扩展使用、SDK 集成和完整的 SessionManager API，请参阅 Session Format 参考文档。