For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt, and this page is available as Markdown at /docs/latest/sessions.md.

会话与上下文

本页面是 Pi 官方文档 的中文翻译。仅供学习参考。

Pi 把一段对话保存为一个会话。该会话的活动分支为下一次模型请求提供对话历史。用会话命令继续工作、探索另一个分支,或减少发送给模型的历史量。

继续或切换会话

除非你用 --no-session 启动,Pi 会自动保存会话。

pi --continue
pi --resume

--continue 打开当前目录最近的会话。--resume 打开会话选择器。在交互模式下,/resume 打开同一个选择器,/new 开始新会话。

每个会话记录创建时的工作目录,并且不会改变它。Pi 在会话的工作目录中运行它,因此工具、@path 引用、项目配置和上下文文件都从那里解析。

入口工作目录
--continue当前目录
--resume、/resume、--session、/import会话的工作目录,可以与当前目录不同
--fork,或你选择 fork 的其他目录的 --session ID当前目录,在新会话中

如果会话的工作目录已不存在,例如项目文件夹被重命名,交互模式会询问如何打开它:

  • Continue 在当前目录运行该会话。Pi 不保存这个选择,所以下次打开时还会再问。
  • Fork 把会话复制到当前目录,成为带新 ID 的新会话,和 --fork 一样。原会话保持不变。启动时,副本像当前目录的其他新会话一样保存;从 /resume 或 /import 打开时,它保存在当前会话旁边,和 /new 一样。
  • Cancel 保持当前会话打开,或在启动时退出。

其他模式会报错退出。

用 /name 或 --name 给会话起一个容易识别的名字。运行 /session 查看当前会话的文件、ID、消息数、Token 用量和成本。

会话选择器可以搜索、重命名和删除会话,也可以显示路径、改变排序,并把结果限制为已命名的会话。它的快捷键见快捷键。

选择分支方式

Pi 把条目存为树,所以回到更早的点不会抹掉你离开的分支。

操作结果适用场景
/tree在当前会话文件内移动相关的几种备选方案应当放在一起
/fork从更早的用户消息创建新会话该备选方案应当成为独立的工作
/clone把活动分支复制到新会话你想要当前状态的一份独立副本

在 /tree 中,选中一条用户消息会把它的文本放回编辑器。编辑并提交它会创建另一个分支。选中一条 assistant 回复或其他条目,会从该条目之后继续,编辑器为空。

当你离开一个分支时,Pi 可以总结它,并把该摘要附加到你进入的分支上。这样能在不包含每一条消息的情况下保留被放弃路径中的相关工作。

持久化的树和条目类型见会话格式。

管理对话上下文

模型收到的是活动分支,而不是会话文件中的每个分支。Pi 把该历史与系统提示、发现的上下文文件、可用工具和已加载的 Skill 描述组合起来。Pi 的工作方式描述了这些输入如何组装。

页脚显示当前上下文用量。当活动上下文接近模型的限制时,Pi 通常会自动压缩较早的历史。压缩会添加一条摘要并保留最近的消息。它不会删除原始会话条目。

运行 /compact 手动压缩。当摘要需要保留某个特定主题或决策时,你可以附加指令。自动压缩和保留历史量可以通过设置配置。

如果 Provider 不可用或无法接受摘要请求,压缩可能失败。解决 Provider 问题后再次运行 /compact。禁用自动压缩不会禁用该手动命令。

阈值、保留边界、分支摘要行为和扩展钩子见压缩参考。

控制会话存储

默认情况下,Pi 把会话存在 ~/.pi/agent/sessions/ 下,按工作目录分组。用 --session-dir、PI_CODING_AGENT_SESSION_DIR 或 sessionDir 设置选择其他位置。CLI 选项的优先级最高。

用 --no-session 进行临时运行。临时会话在 Pi 退出后无法恢复。

导出或分享会话

用 /export 把当前会话写成 HTML 或 JSONL。用 /share 上传并获得查看链接。默认情况下,配置了 Radius 认证时 Pi 使用 Radius 产物;否则使用私有 GitHub gist。把 sessionShareDestination 设为 gist 或 radius 可以强制使用其中一个目标。

请先审阅要导出或分享的会话。它们可能包含 Prompt、模型响应、工具参数、命令输出、文件内容和扩展消息。

报告 bug

运行 /bug [description] 为 Pi 开发者准备一份私有报告。你可以附上会话转录、省略它,或让当前模型总结问题。请审阅转录或生成的摘要,因为它们可能包含敏感的对话数据。

报告包含环境与 Provider 配置(不含凭证值),以及记录的错误诊断。通过 radius.pi.dev 上传,或把同一份报告导出为 zip 自行检查与分享。上传不需要登录;Radius 认证会把报告归属到你的账号,方便开发者跟进。如果上传失败,Pi 会提示导出 zip。


法律声明:本页面是 pi.dev 官方文档的中文翻译版本,仅供学习参考。本网站与 pi.dev 及 Earendil Inc. 无任何法律关系。