# 会话

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

---

LLMS 索引： [llms.txt](/llms.txt)

---

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

## 会话存储 {#session-storage}

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

```bash
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，请参阅[会话格式](/book/pi/session-format/)。

## 会话命令 {#session-commands}

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

## 恢复和删除会话 {#resuming-and-deleting-sessions}

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

在选择器中你可以：

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

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

## 命名会话 {#naming-sessions}

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

```text
/name Refactor auth module
```

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

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

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

## 使用 `/tree` 进行分支 {#branching-with-tree}

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

<p align="center"><img src="/book/images/tree-view.png" alt="树状视图" width="600"></p>

示例结构：

```text
├─ 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..."
```

### 树状视图操作 {#tree-controls}

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

过滤模式包括：default、no-tools、user-only、labeled-only 和 all。可在[设置](/book/pi/settings/)中通过 `treeFilterMode` 配置默认值。

### 选择行为 {#selection-behavior}

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

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

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

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

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

## `/tree`、`/fork` 与 `/clone` {#tree-fork-and-clone}

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

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

## 分支摘要 {#branch-summaries}

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

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

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

关于分支汇总的内部机制和扩展钩子，请参阅[上下文压缩](/book/pi/compaction/)。

## 会话格式 {#session-format}

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

关于解析器、扩展、SDK 用法和完整的 SessionManager API，请参阅[会话格式](/book/pi/session-format/)。

---

反链：

- [扩展](/book/pi/extensions/)
- [使用 Pi](/book/pi/usage/)