Pi 的会话与上下文管理

Pi Coding Agent 的会话用于保存任务交互，使用户能够继续工作或从历史位置探索另一种做法。上下文则是某次模型请求实际收到的信息。会话保存得很完整，并不意味着每次调用都把全部历史发送给模型。

以下按 2026 年 9 月 17 日的会话文档说明。

会话保存与恢复

默认会话保存在 ~/.pi/agent/sessions/，按工作目录组织。常用入口是：

pi -c
pi -r
pi --no-session

它们分别用于继续最近会话、选择历史会话，以及不保存会话的临时运行。交互模式中的 /name 可为会话命名，/session 可查看会话信息。恢复会话主要恢复交互记录及相关状态，不应理解为自动恢复过去某一刻的整个开发环境。

历史为什么是一棵树

会话采用 JSONL：一个文件中的每行是一个 JSON 对象。历史记录通过 id 和 parentId 表达前后关系，允许一个历史位置向不同方向延伸。模型调用时需要沿当前分支组织信息，而不是把所有分支混在一起。

记录除消息外，还可以包含模型切换、压缩摘要、标签和扩展记录。具体结构见会话格式说明。

例如，用户先讨论“在调用方处理空输入”，随后返回之前的位置，改为讨论“让函数本身接受空输入”。两条思路可以保存在同一个会话树里；后续沿哪条思路继续，由当前活动位置决定。

tree、fork 与 clone

这类分支操作改变的是会话路径。代码已经写入磁盘、命令已经产生的外部效果，不会因为对话切回历史位置就自然消失。文件版本与工作区恢复仍需要单独管理。

压缩怎样节省上下文

模型的上下文窗口有限。Pi 可以自动压缩，也可以通过 /compact 手动触发。其基本方式是为较早内容生成摘要，并保留一部分近期消息，用“摘要加近期消息”构造后续请求。

这改变的是后续模型看到的信息组织方式，原始历史仍可存在于会话文件中。树导航还有分支摘要，用来带入离开分支时的重要信息；它与因上下文长度触发的压缩用途不同。机制见压缩与分支摘要文档。

摘要是有损的。例如，一长段失败日志可能被缩写为失败原因；若之后需要逐字检查日志，应重新读取原始证据。不能把压缩等同于模型永久记住全部细节。

项目指令、历史与记忆的区别

项目指令描述长期适用的约定，历史记录已经发生的对话和操作，当前上下文则受分支选择与长度预算影响。三者协同工作，但不会自动形成跨所有任务的用户画像或长期知识库。

因此，评价会话功能时，应分别问：能否找回历史、能否恢复有效上下文、能否重新核实环境状态。仅仅“存在一个会话文件”不足以回答后两个问题。

用同一任务理解分支操作

假设当前会话依次发生：

1. 用户要求定位分页错误；
2. Agent 读取实现和测试；
3. 用户选择“修改调用方”方案；
4. Agent 完成修改。

后来用户想从第 2 步改试“修改分页函数本身”。三种操作的差别是：

• 在 /tree 中回到第 2 步继续，会在同一 JSONL 会话文件中形成另一条分支；
• 用 /fork 从较早的用户消息创建新会话，会把新方案保存到另一个会话文件；
• 用 /clone 复制当前活动分支，会得到包含当前路径的新会话，再从这个副本继续。

这些操作管理对话历史。第 4 步已经写入工作区的代码仍然存在，除非用户另外恢复文件。官方对三者的对照见会话分支说明。

压缩前后模型看到什么

可以把长会话简化成：

压缩前：系统提示 + 早期讨论 + 多次工具输出 + 最近消息
压缩后：系统提示 + 早期内容摘要 + 保留的最近消息

自动压缩会在上下文接近模型窗口限制时触发，也可以使用 /compact 手动触发。Pi 选择一个边界，概括较早内容并保留近期消息，后续请求使用摘要和保留消息构造上下文。详细步骤见压缩机制。

例如，一份很长的测试日志在摘要中可能只剩“集成测试因数据库连接失败”。如果下一步需要判断具体错误码，应重新读取原始日志或重新运行命令，不能依赖摘要还原逐字细节。

分支摘要与上下文压缩

两者都生成摘要，但触发原因不同：

分支摘要不会把两条完整历史同时塞给模型。它只把离开路径的重点附到新的活动位置，因此仍然可能遗漏细节。

恢复会话时应重新确认什么

恢复会话后，历史可以回来，但外部世界可能已经改变。继续工作前通常要重新核实：

• 当前工作目录与 Git 分支；
• 文件是否被其他工具或用户修改；
• 依赖、服务和测试环境是否仍可用；
• 当前模型和已加载扩展是否与之前一致。

会话是任务记录和上下文来源，不是工作区快照、进程快照或数据库事务。