9 会话

会话的自动保存、恢复、命名、树状分支结构与常用管理命令。

Pi 会把对话保存为会话，让你可以继续之前的工作、从更早的回合分叉，或者回顾之前走过的路径。

会话存储

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

pi -c                  # Continue most recent session
pi -r                  # Browse and select from past sessions
pi --no-session        # Ephemeral mode; do not save
pi --name "my task"    # Set session display name at startup
pi --session <path|id> # Use a specific session file or partial session ID
pi --fork <path|id>    # Fork a session file or partial session ID into a new session

在交互模式下使用 /session 可以查看当前会话文件、会话 ID、消息数、token 数和费用。

关于 JSONL 文件格式和 SessionManager API，请参阅会话格式。

会话命令

命令	说明
`/resume`	浏览并选择之前的会话
`/new`	开始一个新会话
`/name <name>`	设置当前会话的显示名称
`/session`	显示会话信息
`/tree`	在当前会话树中导航
`/fork`	从之前的某条用户消息创建新会话
`/clone`	把当前活动分支复制为一个新会话
`/compact [prompt]`	汇总较早的上下文；见上下文压缩
`/export [file]`	将会话导出为 HTML
`/share`	上传为私有 GitHub gist，并生成可分享的 HTML 链接

恢复和删除会话

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

在选择器中你可以：

输入内容进行搜索
用 Ctrl+P 切换路径显示
用 Ctrl+S 切换排序方式
用 Ctrl+N 只显示命名会话
用 Ctrl+R 重命名
用 Ctrl+D 删除，然后确认

可用时，pi 会使用 trash CLI 执行删除，而不是永久移除文件。

命名会话

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

/name Refactor auth module

也可以在启动时用 --name 或 -n 设置名称：

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

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

使用 `/tree` 进行分支

会话以树的形式存储。每个条目都有 id 和 parentId，当前位置就是活动叶子。/tree 让你跳到之前的任意节点并从那里继续，而不必创建新文件。

树状视图

示例结构：

├─ user: "Hello, can you help..."
│  └─ assistant: "Of course! I can..."
│     ├─ user: "Let's try approach A..."
│     │  └─ assistant: "For approach A..."
│     │     └─ user: "That worked..."  ← active
│     └─ user: "Actually, approach B..."
│        └─ assistant: "For approach B..."

树状视图操作

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

过滤模式包括：default、no-tools、user-only、labeled-only 和 all。可在设置中通过 treeFilterMode 配置默认值。

选择行为

选中一条用户消息或自定义消息时：

把叶子移动到所选消息的父节点。
把所选消息的文本放入编辑器。
让你编辑并重新提交，从而创建一个新分支。

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

把叶子移动到该条目。
编辑器保持为空。
让你从该位置继续。

选中根用户消息会把叶子重置为空对话，并把原始提示词放入编辑器。

`/tree`、`/fork` 与 `/clone`

功能	`/tree`	`/fork`	`/clone`
输出	同一个会话文件	新会话文件	新会话文件
视图	完整树	用户消息选择器	当前活动分支
典型用途	在原位探索不同方案	从较早的提示词开启新会话	在继续之前复制当前工作
摘要	可选的分支摘要	无	无

当你想把不同方案保留在同一个会话中时，使用 /tree。当你想要一个独立的会话文件时，使用 /fork 或 /clone。

分支摘要

当 /tree 从一个分支切换到另一个分支时，pi 可以对被放弃的分支生成摘要，并把该摘要附加到新位置。这样既保留了你所离开路径上的重要上下文，又不必重放整个分支。

出现提示时，从以下选项中选择：

不生成摘要
使用默认提示词生成摘要
使用自定义侧重点指令生成摘要

关于分支汇总的内部机制和扩展钩子，请参阅上下文压缩。

会话格式

会话文件为 JSONL 格式，包含消息条目、模型变更、思考级别变更、标签、压缩记录、分支摘要和扩展条目。

关于解析器、扩展、SDK 用法和完整的 SessionManager API，请参阅会话格式。