📊 页面导航

    适用角色与上手难度

    角色推荐度上手难度
    🛠️ 开发★★★★★★★★☆☆
    🧪 测试★★★☆☆★★★☆☆
    📦 产品★★☆☆☆★★★★☆

    🎯 学习产出： 掌握 Pi 的会话恢复、分支、压缩和分享能力，能管理长时间、多分支的复杂工作

    🚀 AI 能力提升： 上下文管理

    会话管理

    预计阅读时间: 4 分钟

    Pi 的会话以 JSONL 文件存储，内部是树状结构：每条消息有 id 和 parentId，可以在同一个文件里原地分支，无需新建文件。会话默认保存在 ~/.pi/agent/sessions/，按工作目录组织。

    恢复与继续

    pi -c               # 继续最近的会话
pi -r               # 浏览并选择过去的会话
pi --session <id>   # 用指定会话文件或部分 UUID
pi --fork <id>      # 把某个会话复制为新的会话
pi --no-session     # 临时模式，不保存
pi -n "my task"     # 启动时设置会话显示名称

    在会话内可以用 /session 查看当前会话 ID，再用 --session <id> 或 --fork <id> 复用。

    分支

    Pi 的会话是树状的，历史记录全部保存在一个文件里，可以随时回到任意节点。

    命令/参数说明
    /tree就地浏览会话树：选中任意历史节点继续，或在分支间切换
    /fork从活跃分支的某条用户消息创建新会话文件，选中后可在编辑器里改提示词
    /clone把当前活跃分支完整复制到新会话文件，编辑器为空，历史保留
    pi --fork <id>从 CLI 直接分叉某个会话文件到当前项目的新会话

    /tree 里的常用操作：

    • 输入搜索，Ctrl+←/Ctrl+→ 或 Alt+←/Alt+→ 在分支间跳转，←/→ 翻页
    • Ctrl+O 切换过滤模式：默认 → 仅工具 → 仅用户 → 仅标签 → 全部
    • Ctrl+X 复制选中消息
    • Shift+L 给条目打标签做书签，Shift+T 切换标签时间戳

    上下文压缩（Compaction）

    长会话会耗尽上下文窗口。压缩会把较早的消息总结掉，保留最近的内容。

    手动压缩：

    /compact                # 压缩
/compact 请聚焦新需求    # 带自定义指令压缩

    自动压缩： 默认开启。在上下文溢出时触发（可恢复并重试），或在接近上限时主动触发。可通过 /settings 或 settings.json 配置。

    压缩是有损的

    压缩会丢失细节。完整历史仍保留在 JSONL 文件里，可以用 /tree 回溯。

    导出、导入与分享

    命令说明
    /export [file]导出当前会话为 HTML 或 JSONL 文件
    pi --export <in> [out]从 CLI 导出会话为 HTML
    /import <file>从 JSONL 文件导入并恢复会话
    /share上传为私有 GitHub gist，生成可分享的 HTML 链接
    /copy复制最后一条助手消息到剪贴板

    会话信息

    /session 会显示：会话文件路径、会话 ID、消息数量、token 用量和累计花费，方便你在需要恢复或分叉时拿到准确 ID。

    下一步