Session 格式速查

1. Session 是什么

Pi Session 是追加式 JSONL Entry Tree，不只是一个 Message Array。

Session file
├── Header
├── Entry
├── Entry
└── Entry

每行是一个独立 JSON Object，以 LF 分隔。

2. Header

Header 保存 Session 的基础身份与创建信息。不要把它误当成会随每次 Model 切换改写的 UI 状态；Model 切换通过后续 model_change Entry 表达。

精确字段以 session-manager.ts 为准。

3. Entry 公共关系

核心关系：

id
parentId
type
timestamp / payload

parentId 让 Entry 形成 Tree。当前 Branch 是从 Leaf 沿 Parent 回溯得到的路径。

4. 常见 Entry

• Message；
• Model Change；
• Thinking Level Change；
• Compaction；
• Branch Summary；
• Custom Entry；
• Session Metadata 相关记录。

具体 Union 会随版本演进，读取时以源码类型为准，不手写宽松的任意 JSON。

5. Branch

root
└── A
    ├── B
    │   └── C
    └── D
        └── E

选择 C 与选择 E 会得到不同当前 Branch。Fork/导航不删除另一条路径。

6. Current Branch 与完整 Entries

• getBranch()：当前 Leaf 的祖先路径；
• Entries 查询：完整或增量持久树；
• session.messages / RPC get_messages：当前 Agent Context，可能已经过 Compaction。

它们不是同一个数组。

7. Compaction

旧上下文
→ 选择切点
→ 生成摘要
→ append compaction entry
→ summary + retained tail 成为活动 Context

历史 Entry 仍在 Session 文件里。Compaction 是模型上下文管理，不是删除聊天历史。

8. Custom Entry

Custom Entry：

• 不自动进入模型上下文；
• 有 parentId；
• 出现在当前 Branch；
• 适合 Branch-aware 非模型状态。

跨 Session Account Config 应使用外部 Store。

9. ToolResult Details

ToolResult 的 Content 给模型；Details 可保存结构化状态。若 Tool Result Entry 位于 Branch 中， 从当前 Branch Replay Details 可以恢复该分支的 Tool 状态。

10. 临时与持久 Session

临时 Session 没有持久文件路径，因此 Bash Tool 的 PI_SESSION_FILE 也不存在。持久 Session 要处理目录权限、原子追加、损坏恢复与备份。

11. 恢复

可靠桌面恢复：

get_state
→ get_messages（当前 Context）
→ get_entries（完整历史/稳定 ID）
→ leafId/entryCursor
→ reconcile live buffer

首次全量获取，之后用 since Cursor 增量。Entry ID 负责持久去重；本地 Sequence 负责 Snapshot Barrier 与 Live Buffer 顺序。

12. Replay 原则

Replay 只重建：

• UI History；
• Extension Branch State；
• Session Metadata；
• Pending 的可恢复表示。

绝不重新执行 Tool。崩溃前未确认的副作用标为 Indeterminate，再查询 Audit/Backend。

13. Replacement

New/Resume/Fork 会替换当前 Runtime/Session：

• Shutdown 旧 Extension；
• 同步拆宿主 Bridge；
• Invalidate 旧 Session；
• 按目标 CWD 重建 Services；
• 重新订阅/绑定；
• Generation + 1；
• Snapshot Rehydrate。

14. 诊断清单

源码入口：core/session-manager.ts、core/agent-session.ts。