深入理解 pi 04 / 06 目录 单页全本 学习手册 对比站

深入理解 pi/第 04 章

4.1

什么时候压:一个不等式

压缩的触发条件只有一行,但它包含两个可调参数:

packages/coding-agent/src/core/compaction/compaction.ts:269
contextTokens > contextWindow - settings.reserveTokens
参数默认含义
reserveTokens16,384给「下一轮回复」预留的空间。不留就会压完立刻再溢出
keepRecentTokens20,000压缩后保留的近期原文量。太少会丢细节,太多压了等于没压

两个数解决的是不同问题:reserveTokens 是为了能继续说话,keepRecentTokens 是为了还记得刚才在干什么。 注意它们是同一个方向上的拉扯——保留越多,能留的对话轮次越少。

compaction.ts:269(触发)· :128-129(默认值)

4.2

切点算法:从末尾倒着走

决定「从哪条开始保留」的算法是压缩的核心。它的方向很关键——从最新往回数,而不是从最旧往前数。

packages/coding-agent/src/core/compaction/compaction.ts:431-478(简化)
/**
 * Algorithm: Walk backwards from newest, accumulating estimated message sizes.
 * Stop when we've accumulated >= keepRecentTokens. Cut at that point.
 *
 * Can cut at user OR assistant messages (never tool results). When cutting at an
 * assistant message with tool calls, its tool results come after and will be kept.
 */
const cutPoints = findValidCutPoints(entries, startIndex, endIndex);
let accumulatedTokens = 0;
let cutIndex = cutPoints[0];

for (let i = endIndex - 1; i >= startIndex; i--) {
  const messageTokens = sessionEntryToContextMessages(entries[i])
    .reduce((sum, message) => sum + estimateTokens(message), 0);
  if (messageTokens === 0) continue;
  accumulatedTokens += messageTokens;

  if (accumulatedTokens >= keepRecentTokens) {
    cutIndex = cutPoints.find((candidate) => candidate >= i) ?? cutPoints[cutPoints.length - 1];
    break;
  }
}

为什么必须倒着走?因为要保证的是「最近 N token 一定在」,而不是「最旧 N token 一定被压」。 正着走会让你不知道该在哪里停——你不知道后面还剩多少。

三个约束同时生效:

约束实现防的是
不能切在工具结果上findValidCutPoints 只给合法位置调用与结果被拆开,轨迹结构损坏
切点取「最近的合法位置」cutPoints.find(c => c >= i)为了凑整而切到很远的地方,多压了一大段
兜底不越过首个合法点?? cutPoints[last]找不到时退化成「什么都不压」的失控
一句注释的信息量:When cutting at an assistant message with tool calls, its tool results come after and will be kept. 这说明作者考虑过「切在 assistant 上会不会把它的工具结果丢掉」——答案是「结果在后面,所以会被保留」。 这种把边界情形写进注释的习惯,比多写十个测试更有用。

compaction.ts:431-478

4.3

split turn:切在一轮中间怎么办

倒着数到 keepRecentTokens 时,很可能正好落在**一个 turn 的中间**——用户说了话、模型回了、工具跑了,但这一轮还没结束。 这时切下去会留下一段「没有开头的对话」。

pi 的解法是记录两个额外信息,而不是硬切:

返回字段作用
firstKeptEntryIndex保留区从哪条开始
turnStartIndex若是 split,这一轮起头的那条用户消息在哪
isSplitTurn是否切在轮次中间

于是 turnPrefixMessages 出现了——被切掉的那半轮单独摘要,而不是混进主摘要:

packages/coding-agent/src/core/compaction/compaction.ts:890-900
const historyEnd = cutPoint.isSplitTurn
  ? cutPoint.turnStartIndex
  : cutPoint.firstKeptEntryIndex;

const messagesToSummarize = projectedEntries
  .slice(boundaryStart, historyEnd)
  .flatMap(getMessagesFromProjectedEntryForCompaction);

const turnPrefixMessages = cutPoint.isSplitTurn
  ? projectedEntries.slice(cutPoint.turnStartIndex, cutPoint.firstKeptEntryIndex)
      .flatMap(getMessagesFromProjectedEntryForCompaction)
  : [];

为什么要分开?因为两者的语义不同:

段落性质摘要方式
主历史已完成的多轮对话正常摘要,讲清「做过什么」
turnPrefix未完成的那半轮开头要明确标出「这一轮还没结束」,否则摘要会说成已完成

compaction.ts:890-900

4.4

投影:为什么不能「摘要的摘要」

如果一份会话被压过三次,第四次压缩时该拿什么当输入?直觉答案是「上次的摘要 + 之后的新消息」。 但那样会有一个隐蔽的问题:上次摘要自己也是被压过的,再算 token 预算就会算错。

pi 的处理叫 projection——先把所有压缩条目「投影」成消息形态,再做切点计算:

packages/coding-agent/src/core/compaction/compaction.ts:867-882
const projection = buildSessionProjection(pathEntries);
const projectedEntries = projection.entries;
const sourceEntries = projectedEntries.map((entry) => entry.sourceEntry);

// The newest compaction is projected first. Older compaction entries can still
// occur in its retained raw range, but their projected contribution is empty.
const prevCompactionIndex = projectedEntries.findIndex(
  (entry) => entry.sourceEntry.type === "compaction" && entry.messages.length > 0,
);

let previousSummary: string | undefined;
let boundaryStart = 0;
if (prevCompactionIndex >= 0) {
  previousSummary = (projectedEntries[prevCompactionIndex].sourceEntry as CompactionEntry).summary;
  // The canonical projection has already selected the previous compaction's retained tail.
  boundaryStart = prevCompactionIndex + 1;
}

两个机制配合起来才成立:

① 投影让「嵌套压缩」退化成一个平面序列
无论历史上压过几次,投影后的 projectedEntries 都只有一个压缩边界有效—— 最新的那个。更早的压缩条目即使还留在保留区里,投影贡献也为空(注释直说了:their projected contribution is empty)。
② 旧摘要被 carry forward,不是被重新摘要
previousSummary 直接传给下一次压缩,让它「在新摘要里带上旧摘要」。 这样信息不会随压缩次数指数衰减——这是长篇会话能一直跑下去的关键。
这是一个很容易做错的点。如果每次压缩都只把「上次摘要 + 新消息」重新摘要一遍, 那么第 N 次压缩后,第 1 次的内容会被压 N 遍——细节以指数速度流失。 previousSummary 的 carry-forward 正是因为意识到这件事。

compaction.ts:867-882

4.5

摘要本身就是一次模型调用

压缩不是本地算法,它要花一次完整的模型调用。这就带来一个必须防的问题:摘要模型可能在摘要时调用工具。

packages/coding-agent/src/core/compaction/compaction.ts:742-748
const failure = getSummarizationFailure(response, "Summarization");
if (failure) { throw new Error(failure); }
if (response.content.some((block) => block.type === "toolCall")) {
  throw new Error("Summarization attempted to call a tool");
}

为什么这算错误而不是「忽略工具调用取文本」?因为摘要调用不该有工具—— 如果模型调了工具,说明它误解了任务(以为自己在继续干活),此时它输出的文本很可能不是摘要。 宁可失败重来,也不要拿一段莫名其妙的文本当摘要写进历史。

而系统提示词的第二句正是在防这件事:

Do NOT continue the conversation. Do NOT respond to any questions in the conversation. ONLY output the structured summary.
不要继续对话。不要回答对话里的任何问题。只输出结构化摘要。
— compaction/utils.ts:163 · SUMMARIZATION_SYSTEM_PROMPT

「不要回答对话里的问题」这句看起来多余,其实是最容易犯的错:历史里往往有用户提问, 摘要模型很容易顺手就答了——答完就不是摘要了。

compaction.ts:747(工具调用护栏)· utils.ts:161-163(系统提示)

4.6

压缩的四个决定

#决定取值 / 做法为什么
1 何时压 tokens > window − 16,384 预留回复空间;提前压而不是等溢出报错
2 保留多少 倒着数到 20,000 token 保证「最近发生了什么」还在原文里
3 切在哪 只在合法切点(永不切工具结果) 保住调用/结果配对,轨迹结构不坏
4 旧摘要怎么办 carry forward,不重新摘要 避免信息随压缩次数指数衰减

可以看到,压缩真正的难点不在「怎么总结」——那是模型的事。 难点全在「切在哪」「旧信息怎么带上」「切坏了怎么办」这三个结构问题上。 这也是为什么 compaction.ts 有近千行,而摘要提示词只有三句。

本章学习记录

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