• 教程
• 文档

本文围绕 Pi Agent 上下文压缩（compaction）展开，基于教程项目 how-pi-agent-works，拆解真实 Pi 压缩系统中三个教学版没有展开的复杂边界：reserveTokens输出预算、turn boundary 切分规则与 branch summary 分支摘要。读完你会明白：压缩不是“删旧消息”，而是在 token 预算、对话协议和会话树分支之间做工程权衡。

📌 如果你还没看过基础版压缩（摘要旧消息 + 保留最近消息），建议先读 Demo 4：上下文压缩，本文是它的进阶篇。

1. reserveTokens：压缩触发看的不是消息条数

很多第一版实现用“消息数量”或“字符串长度”判断是否压缩。真实 Pi 的做法不同：它从模型返回的 usage 里读取真实 token，加上新消息的估算值，得到contextTokens，再与一条预算线比较：

contextTokens > contextWindow - reserveTokens

关键点在于：Agent 不是“输入塞得下”就行。如果压缩后上下文贴着窗口上限，模型刚开始输出就可能撞墙。reserveTokens就是提前给“输出”留出的安全垫。

💡 对比教学版：sessionStore.ts 中的compactIfNeeded()用近似字符数模拟触发点，参数是maxApproxTokens和keepRecentMessages，刻意保持可预测、方便观察 JSONL 文件。

2. firstKeptEntryId：摘要为什么必须带“恢复指针”

只存一个summary字段的压缩，恢复上下文时会立刻卡住：摘要后面到底从哪条原文接上？

Pi 的CompactionEntry不止有摘要：

于是压缩后模型看到的上下文变成三段式：

system prompt compaction summary messages from firstKeptEntryId to current leaf

注意 JSONL 文件里的旧消息一条都没删，firstKeptEntryId只是告诉运行时“下次喂模型时从哪里接回原文”。完整链路说明见 会话格式、分支与压缩链路。

3. turn boundary：为什么压缩不能随便切

工具调用让切分变复杂了。一次完整的工具交互至少包含：assistant 发出toolCall→ tool 执行生成toolResult→ assistant 读取结果继续回答。

如果 cut point 恰好落在toolResult前后，模型会看到两种“孤儿”：

• 没有来源的工具结果（调用被摘要掉了）
• 没有结果的工具调用（结果被划进旧上下文）

两者都会破坏对话协议。官方 cut point 规则因此限定：切点可以落在用户消息、assistant 稳定输出点、branch summary 等位置，但不会切在 toolResult 上。这就是 turn boundary 的意义——在“一轮对话”的语义边界上切，而不是在任意消息边界上切。

🔧 教学版练习方向：给compactIfNeeded()加一条规则——选firstKeptEntryId时，若保留段第一条是toolResult，就把它前面的 assistant toolCall 一起保留。

4. split turn：一个 turn 自己就超过保留预算

理想情况是压缩切在 turn 边界：旧 turn 摘要掉，新 turn 保留原文。但代码 Agent 经常遇到超长 turn——一次“修复失败测试”可能串起读文件、跑测试、改代码、看 diff 好几轮工具输出，单 turn 就超过了keepRecentTokens。

这时 Pi 会把 cut point 放进 turn 内部，形成split turn：

超长 turn ├─ 前半段（turnPrefixMessages）→ 单独摘要 └─ 后半段 → 原文保留

这样模型既知道这个巨大 turn 前面做了什么，又不会把整段工具输出塞进下一轮请求。split turn 保护的是“连续工作现场”，而不是机械地整段保留或整段丢弃。

5. 重复压缩：摘要也会成为历史

长会话不会只压缩一次。第二次压缩时，Pi 不会简单地从上一个 compaction entry 后面开始算，而是从上一次firstKeptEntryId的保留边界附近继续。

原因很实在：上次被“保留原文”的消息，这次可能已经变旧了，也应该有机会进入新的 summary。否则最近上下文会越滚越大，压缩效果越来越差——这也是 上下文、技能与压缩 里强调的两个风险的工程解法。

6. branch summary：它不是压缩，是“换路带经验”

branch_summary和compaction都用摘要，但触发场景完全不同：

一个常见误区：切分支时直接把旧分支全丢掉。你可能在 A 分支里读过关键文件、验证过失败假设，切到 B 分支后这些经验就没了。branch summary 的价值，就是把“走过的弯路”变成可携带经验。

🌳 分支与/tree导航的背景见 会话、树与分支，教学版把 branch summary 作为扩展方向，因为它需要会话树 UI 支撑，适合二阶段练习。

7. 对照真实源码与教学版

真实实现集中在官方仓库的packages/coding-agent/src/core/compaction/（触发条件、cut point、branch summary、文件操作追踪）。本仓库把主线整理在 进阶：真实 Pi 为什么压缩更复杂，源码阅读路线见 源码阅读地图。

参考最小实现：04-compaction.ts 中的compactMessages()，运行npm run demo:04即可看到tokensBefore、summary 和“模型下一轮看到什么”。

8. 小练习：给教学版补一个真实边界

1. 给 compactIfNeeded() 增加reserveApproxChars参数，模拟“输出空间预留”。
2. 选firstKeptEntryId时不按条数，而是从最新消息向前累加近似字符数，直到达到keepRecentApproxChars。
3. 遇到toolResult时保证它前面的 toolCall 一起保留，避免出现孤儿结果。
4. 在 compaction event 里展示tokensBefore、firstKeptEntryId和keptMessageCount。

做完你会发现：压缩不是字符串裁剪，而是一个同时保护协议边界、上下文预算和工程恢复能力的独立模块——这正是真实 Pi 把它拆成compaction/单独目录的原因。

• 教程
• 文档