pi 系统学习手册 第 06 / 12 章 总目录 单页全本 架构图 GitHub

手册/第 06 章

06

会话与上下文:一棵树,三段算法

这是 pi 最值得抄走的设计。多数 agent 把会话存成「消息数组」, pi 存成一棵可分支的树,于是「回到某个节点重新试一次」不需要复制文件, 只需要在同一个文件里长出一个新分支。

存储形态:一行一个 entry 的 JSONL

~/.pi/agent/sessions/--<path>--/<timestamp>_<session-id>.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]─ [assistant]─ [user]─ [assistant]
  • [user]← 当前 leaf(active branch 末端)
  • [branch_summary]─[user]← 另一条分支,文件里一直保留

切分支不是「回退删除」,而是把 leaf 移到另一个节点。 被放弃的分支仍在文件里,随时可以切回去。这一点和 git 的心智模型几乎一致。

三段算法:从文件到「要发给模型的 messages」

1buildContextEntries()
从 leaf 向 root 回溯,得到活动路径上的条目;若路径上存在 compaction, 取最新那一个:先放压缩条目,再放 firstKeptEntryId 到压缩条目之间的非系统条目, 最后放压缩条目之后的全部条目。非消息条目被保留,因为 UI 还要渲染它们。
2buildSessionProjection()
对每个目标应用最新的 context_edit:被省略的目标不产生消息, 被替换的目标只改内容、保留原有 role 与元数据。原始条目永不被修改。
3buildSessionContext()
把选中条目转成消息:message → 原样;compaction → 完整 checkpoint + 摘要; branch_summary → branchSummary;context_edit / usage / custom → 不产生上下文消息。
这个设计的好处 「改上下文」变成了一次可审计的编辑,而不是在一个数组上原地 splice。 压缩之后你依然能回看原始条目;扩展也能在 context 事件里改写投影, 而不破坏磁盘上的历史。

两种摘要机制,别混用

机制触发目的
Compaction上下文超过阈值,或手动 /compact把旧消息压缩成摘要,腾出上下文窗口
Branch summarization用 /tree 切换分支时保留旧分支的要点,避免切过去后完全失忆

两者共享同一套结构化格式,并且都会累积追踪文件操作。 一个很细但重要的实现细节:摘要请求会禁用 prompt-cache 写入, 因为这是一次性 prompt,写缓存纯属浪费。

消息排队:steering 与 follow-up

这是交互体验的关键差异点,也是很多人第一次用 pi 会困惑的地方:

  • Steering message:你在 agent 干活时插话,它会在当前 assistant turn 之后立刻进入上下文,用来中途纠偏
  • Follow-up message:排队等 agent 把手头的事做完再进来
  • Abort:停止当前 run,并把还没消费的排队消息退回编辑器——不丢你的输入
"the loop also supports message queuing via a callback: after each turn, it asks for queued messages and injects them before the next assistant response."
循环还通过回调支持消息排队:每个 turn 之后,它去问有没有排队消息,并在下一次 assistant 回复前注入。

用 jq 直接读会话

因为格式就是 JSONL,你可以不写一行代码就做分析:

bash
# 最近一个会话文件
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

本章学习记录

记录仅保存在当前浏览器。