Pi 会话管理:存储、分支与克隆

badlogic 发布于 2026-05-30 阅读 8

本文介绍了Pi(一个AI编程代理)的会话管理功能,包括会话的自动存储、恢复、命名、分支(/tree)、分叉(/fork)和克隆(/clone)操作,以及会话树形结构的使用。详细说明了通过命令行和交互模式管理会话,如继续最近会话、浏览历史、设置名称、导出HTML、分享为GitHub Gist等。还涵盖分支摘要功能,帮助保留上下文。会话文件采用JSONL格式,包含消息、模型更改、标签、压缩等条目。

Pi 将会话保存为 session(会话),因此你可以继续工作、从更早的轮次分支,以及重新访问之前的路径。

会话存储

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

pi -c                  # 继续最近的会话
pi -r                  # 浏览并选择过去的会话
pi --no-session        # 临时模式:不保存
pi --name "my task"    # 在启动时设置会话显示名称
pi --session <path|id> # 使用特定的会话文件或部分会话 ID
pi --fork <path|id>    # 将会话文件或部分会话 ID 分支到新会话

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

关于 JSONL 文件格式和 SessionManager API,请参阅 Session Format

会话命令

命令 描述
/resume 浏览并选择之前的会话
/new 开始新会话
/name <name> 设置当前会话的显示名称
/session 显示会话信息
/tree 导航当前会话树
/fork 从之前的用户消息创建新会话
/clone 将当前活动分支复制到新会话
/compact [prompt] 汇总较旧的上下文;见 Compaction
/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"

已命名的会话在 /resumepi -r 中更容易找到。

使用 /tree 分支

会话以树结构存储。每个条目都有 idparentId,当前位置是活动叶子节点。/tree 允许你跳转到之前的任意点,并从那里继续,而无需创建新文件。

<p align="center"><img src="images/tree-view.png" alt="Tree View" width="600"></p>

示例形状:

├─ 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 循环筛选模式

筛选模式为:默认、无工具、仅用户、仅标签和全部。通过在 Settings 中设置 treeFilterMode 来配置默认值。

选择行为

选择用户或自定义消息:

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

选择助手、工具、压缩或其他非用户条目:

  1. 将叶子节点移动到该条目。
  2. 编辑器保持空白。
  3. 让你从该点继续。

选择根用户消息会将叶子节点重置为空对话,并将原始提示放入编辑器。

/tree/fork/clone

特性 /tree /fork /clone
输出 同一会话文件 新会话文件 新会话文件
视图 完整树 用户消息选择器 当前活动分支
典型用途 在原地探索替代方案 从较早的提示开始新会话 在继续之前复制当前工作
摘要 可选的分支摘要

当你希望将替代方案保留在一起时,请使用 /tree。当你想要一个单独的会话文件时,请使用 /fork/clone

分支摘要

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

当出现提示时,请选择以下之一:

  1. 无摘要
  2. 使用默认提示汇总
  3. 使用自定义焦点指令汇总

关于分支摘要的内部机制和扩展 hook,请参阅 Compaction

会话格式

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

关于解析器、扩展、SDK 使用和完整的 SessionManager API,请参阅 Session Format

  • 原文链接: github.com/badlogic/pi-m...
  • 登链社区 AI 助手,为大家转译优秀英文文章,如有翻译不通的地方,还请包涵~

相关文章

0 条评论