06 压缩 切在哪一刀，比切掉多少更重要

先记住这一句

把这条规则记住，压缩的大部分行为就都能推出来。从最新消息往回累加 token，攒够 keepRecentTokens 就想切；但切口只能落在「模型视角下的一条完整消息边界」上，于是实际切点会往前滑到最近的合法位置。只要待压缩的历史本身超过这个预算，实际保留量就总是 ≥ 目标值，而不是恰好等于。

还有两件事值得先知道：

• 压缩自己要花一次 LLM 调用去生成摘要。上下文快满的时候做压缩，等于在最贵的时刻再买一次单。
• 压缩的产物写进会话文件（一条 CompactionEntry），不是运行时的临时裁剪。这意味着压缩不可撤销，也意味着它可回放。

触发线：一个减法

export function shouldCompact(contextTokens: number, contextWindow: number, settings: CompactionSettings): boolean {
    if (!settings.enabled) return false;
    return contextTokens > contextWindow - settings.reserveTokens;
}

触发点有两个，语义不同：

threshold 这条路在 CLI 里的检查点是 一次 run 结束（agent_end）之后，以及提交下一个 prompt 之前：agent-session.ts:1952。它不在 LLM 调用中途处理，也不在 run 内部的 turn 之间处理。agent 包的 README 示例给了另一种接法——用 第 03 章 §2 的 shouldStopAfterTurn 钩子在 turn 边界停下、压缩完再继续：agent/README.md:299；锚点上的 coding-agent 没有采用它。

切点规则：toolResult 是禁区

合法切点由一个 role 白名单决定，toolResult 是唯一被排除的：compaction.ts:308–320

function isCutPointMessage(message: AgentMessage): boolean {
    switch (message.role) {
        case "user":
        case "assistant":
        case "bashExecution":
        case "custom":
        case "branchSummary":
        case "compactionSummary":
            return true;
        case "toolResult":
            return false;
    }

原因是协议级的：所有 provider 都要求 toolResult 前面必须有对应的 tool call。切在 toolResult 上会产出一个「有结果没调用」的孤儿，请求直接被拒。这是压缩实现里唯一一条不能违反的硬约束，其余都是启发式。

切点搜索：往回累加，再往前滑

findCutPoint 从最新往回累加 token 估算，攒够 keepRecentTokens 后，取第一个下标 ≥ 当前位置的合法切点。compaction.ts:403

结果里带一个 isSplitTurn 标志：切点如果不是 user 消息，说明这一刀切进了某个 turn 的中间（比如切在 assistant 上，它的 tool results 跟在后面）。此时会额外记下该 turn 的起始位置，供摘要生成时补上「这个 turn 是从哪开始的」。

换句话说：token 预算决定「大概切在哪」，消息结构决定「实际切在哪」，两者不一致时结构赢。

摘要是一次真实的 LLM 调用

prepareCompaction 算出切点与待摘要区间，compact 发起调用并把结果写成 CompactionEntry。compaction.ts:710 compaction.ts:817

上游文档补了一条实现细节，代码之外看不出来：压缩与分支摘要的请求使用全新的路由 session id，并在 provider 支持时禁用 prompt-cache 写入——这类一次性 prompt 不太可能被复用，写缓存是净亏。compaction.md:23

摘要生成时会把上一次的摘要作为迭代上下文传进去，所以多次压缩后的摘要是层层叠加而非各自独立的。代价是误差也会层层叠加：第三次压缩的摘要，是「对『对摘要的摘要』的摘要」。

同名函数，两份实现

为什么压缩要落盘，而不是每次请求临时裁剪

临时裁剪更灵活：换模型、换 window 就重算一次。pi 选择把摘要写成会话条目，换来三样东西：摘要只生成一次（省钱）、会话可精确回放、/tree 导航时摘要是树上的一个节点而不是某次请求的副产品。

代价是不可逆。CompactionEntry 一旦写入，原始消息虽然还在文件里，但重建上下文时会从 firstKeptEntryId 起算。换到一个 window 大得多的模型，也不会自动「解压」回去。

threshold 与 overflow：两条路说明了什么

有了主动阈值检查，为什么还需要溢出后的补救？因为 contextTokens 来自上一次 provider 返回的 usage，是滞后一拍的估算。一个 turn 里如果工具返回了个 200KB 的文件，这一拍的增量就足以越过窗口，而阈值检查还在用上一拍的数字。

所以 overflow 不是冗余，是承认「token 计数在客户端永远是估算」这一事实后的必要兜底。值得注意的是它只在不会重试时才触发压缩：agent-session.ts:1997–2000 注释解释了原因——如果 assistant 已经答完（stopReason === "stop"），就该压缩但不能重试，因为 agent.continue() 无法从一条 assistant 消息续跑（正是 第 03 章 里 agentLoopContinue 的那条前置约束）。

切点启发式的隐含假设

「保留最近 20000 token」假设近期消息比早期消息更有价值。对编码任务大体成立（刚读的文件、刚跑的测试最相关），但有一类情况明显不成立：任务目标写在第一条 user 消息里。pi 的对策是让摘要承载这类信息，而不是给早期消息特殊豁免——没有任何「pin 住某条消息」的机制。

• 压缩要花一次调用，而且是在上下文最满的时候。摘要请求本身也要带上待摘要的全部内容。上下文越大，这次调用越贵。
• 没有「摘要失败」的降级路径写在压缩逻辑里。如果生成摘要的那次调用失败，压缩不成立，原上下文照旧——于是下一个 turn 大概率又撞线。
• 迭代摘要会累积漂移。长会话经过 N 次压缩后，最早的信息已被摘要 N 次。没有机制检测「摘要与原文的偏离」。
• 无法固定保留某条消息。任务描述、约束、用户偏好，都可能在某次压缩中被折进摘要，能否幸存取决于摘要模型的判断。
• keepRecentTokens 是下限不是上限（在历史足够长时）。切点往前滑之后保留量只会更多；历史本身不足 20000 token 的小窗口场景是唯一例外——那时能保留的就是全部。如果一个 turn 本身就超过 20000 token（比如工具吐了个巨大文件），那一整个 turn 都保留。

检查过但未发现问题：findValidCutPoints 显式跳过 compaction 类型的 entry（compaction.ts:355–357），所以不会出现「切在上一次压缩点上」导致摘要嵌套错乱的情况。

• 先确定「哪些位置切了不会违反协议」，再谈保留多少 token。切点合法性是硬约束，token 预算是软目标；实现顺序反过来就会产出被 provider 拒绝的请求。 适用条件：所有会做上下文裁剪的 agent。toolResult 必须紧跟 tool call 是全 provider 通用的。
• 主动阈值 + 溢出兜底，两条都要。客户端的 token 计数永远滞后一拍，单靠阈值必然偶尔撞墙。 适用条件：工具可能返回不可预测大小的输出。输出规模可控时阈值就够。
• 把摘要写进持久化历史，而不是每次请求临时算。省下重复的摘要调用，换来可回放性；代价是不可逆。 代价：换到更大 window 的模型不会自动恢复被压缩的内容。如果你的用户常换模型，权衡会反过来。
• 压缩请求禁用 prompt-cache 写入。一次性 prompt 写缓存是净亏——这个细节只写在文档里，代码里看不出来。 适用条件：provider 支持显式控制 cache 写入。