手册/第 06 章
会话与上下文:一棵树,三段算法
这是 pi 最值得抄走的设计。多数 agent 把会话存成「消息数组」, pi 存成一棵可分支的树,于是「回到某个节点重新试一次」不需要复制文件, 只需要在同一个文件里长出一个新分支。
存储形态:一行一个 entry 的 JSONL
{"type":"session", "version":3, "id":"...", "parentId":null}
{"type":"message", "id":"a1", "parentId":"...", "role":"user", ...}
{"type":"message", "id":"a2", "parentId":"a1", "role":"assistant", ...}
{"type":"model_change", "id":"a3", "parentId":"a2", ...}
{"type":"usage", "id":"a4", "parentId":"a3", ...}
{"type":"compaction", "id":"a5", "parentId":"a4", "firstKeptEntryId":"a2", ...}
只有十二种 entry 类型:session、message、model_change、
thinking_level_change、usage、compaction、context_edit、
branch_summary、custom、custom_message、label、session_info。
注意其中有一半根本不是消息:换模型、改思考等级、花销统计、压缩、手动改上下文都是显式条目。
这就是作者说的「cleanly documented session format」——
你能精确知道某个 turn 为什么用了那个模型、花了多少 token。
树结构:分支与 leaf
- [user]← 当前 leaf(active branch 末端)
- [branch_summary]─[user]← 另一条分支,文件里一直保留
切分支不是「回退删除」,而是把 leaf 移到另一个节点。 被放弃的分支仍在文件里,随时可以切回去。这一点和 git 的心智模型几乎一致。
三段算法:从文件到「要发给模型的 messages」
firstKeptEntryId 到压缩条目之间的非系统条目,
最后放压缩条目之后的全部条目。非消息条目被保留,因为 UI 还要渲染它们。context_edit:被省略的目标不产生消息,
被替换的目标只改内容、保留原有 role 与元数据。原始条目永不被修改。message → 原样;compaction → 完整 checkpoint + 摘要;
branch_summary → branchSummary;context_edit / usage / custom → 不产生上下文消息。context 事件里改写投影,
而不破坏磁盘上的历史。
两种摘要机制,别混用
| 机制 | 触发 | 目的 |
|---|---|---|
| Compaction | 上下文超过阈值,或手动 /compact | 把旧消息压缩成摘要,腾出上下文窗口 |
| Branch summarization | 用 /tree 切换分支时 | 保留旧分支的要点,避免切过去后完全失忆 |
两者共享同一套结构化格式,并且都会累积追踪文件操作。 一个很细但重要的实现细节:摘要请求会禁用 prompt-cache 写入, 因为这是一次性 prompt,写缓存纯属浪费。
消息排队:steering 与 follow-up
这是交互体验的关键差异点,也是很多人第一次用 pi 会困惑的地方:
- Steering message:你在 agent 干活时插话,它会在当前 assistant turn 之后立刻进入上下文,用来中途纠偏
- Follow-up message:排队等 agent 把手头的事做完再进来
- Abort:停止当前 run,并把还没消费的排队消息退回编辑器——不丢你的输入
用 jq 直接读会话
因为格式就是 JSONL,你可以不写一行代码就做分析:
# 最近一个会话文件 f=$(ls -t ~/.pi/agent/sessions/*/*.jsonl | head -1) # 这次会话用了哪些模型、什么时候换的 jq -r 'select(.type=="model_change") | "\(.timestamp) \(.provider)/\(.modelId)"' "$f" # 每个 turn 的 token 花销 jq -r 'select(.type=="usage") | "\(.input) in / \(.output) out"' "$f" # 统计工具调用次数 jq -r 'select(.type=="message" and .role=="assistant") | .content[]? | select(.type=="toolCall") | .name' "$f" | sort | uniq -c | sort -rn
docs/session-format.md docs/compaction.md session-manager.ts:1187