历史不动，上下文按预算重建

#同一段历史会产生一份更短的模型输入

第 10 章最后得到的是一条 active path。这里沿用这个输入接口，但换成一组便于手算预算 的九条 message entries。表中最后一列是测试估算器给每条消息返回的 token 数，不是真实 provider 的 tokenizer 结果。

calls 先声明 read-1，随后声明 test-1。测试先完成，所以 r-test 在路径中排在 r-read 前面。每个 result 仍可通过 toolCallId 找回自己的 call。

groupInteractions() 以 user 消息为起点，把这九条记录分成三组：

group 1 = [u1, a1]
group 2 = [u2, a2]
group 3 = [u3, calls, r-test, r-read, a3]

第三组包含 user、两个 tool call、两个 result 和最终 assistant。它是预算可以整体保留 或整体丢弃的最小单位。result 的出现顺序不影响配对，也不会把这一组拆开。

现在把这条活动路径交给 buildContext()。例子中的 maxTokens 是 31；system prompt 占 3，回答预留 4，安全余量占 2。消息还剩 22。三组成本依次为 7、7、15，所以函数从 最新一组向前选择，结果正好保留第二、三组：

{
  systemPrompt: "sys",
  keptEntryIds: [
    "u2", "a2",
    "u3", "calls", "r-test", "r-read", "a3",
  ],
  reason: "trimmed",
  tokens: {
    maxTokens: 31,
    system: 3,
    messages: 22,
    reservedOutput: 4,
    safetyMargin: 2,
    availableForMessages: 22,
    total: 31,
  },
}

u1 和 a1 仍在 session 中，只是没有进入这次模型请求。这里的有限消息数组叫 context projection，也就是从历史派生出的临时视图。换一个模型窗口或预留量，同一段 历史可以得到另一份视图。

#摘要先成为 session 中的一条普通事实

当较早的消息以后不再原样进入模型窗口，session 需要留下它们的结构化摘要。摘要不是 对原记录的覆盖；它是一条追加到当前 leaf 后面的 CompactionSessionEntry：

interface CompactionSessionEntry {
  id: string;
  parentId: string;
  timestamp: number;
  type: "compaction";
  summary: CompactionSummary;
  firstKeptEntryId: string;
  tokensBefore: number;
}

继续使用开篇路径，可以创建 compact-1，让它的 parentId 指向当前末尾 a3。 firstKeptEntryId: "u2" 表示恢复时从第二组开始保留原消息。tokensBefore 由调用者 写入，用来记录压缩前的估算规模；parser 只检查它是非负有限数，不会重新估算并核对该值。

summary 的七个字段分别保存目标、约束、已完成事项、决策、变更文件、未解决事项和 下一步：

interface CompactionSummary {
  goal: string;
  constraints: string[];
  completed: string[];
  decisions: string[];
  changedFiles: string[];
  unresolved: string[];
  next: string[];
}

parseSessionEntry() 逐字段读取外部对象。goal、parentId 和 firstKeptEntryId 不能为空；数组中的每一项都是字符串；tokensBefore 是非负有限数。 解析器返回新对象，因此调用者之后修改 summary 数组也不会改动 Store 中的记录。

第 10 章的两个 Store 已经统一通过 parseSessionEntry() 获取写入快照。union 和解析 分支补齐后，InMemorySessionStore 与 JsonlSessionStore 不需要新增 compaction 专用 写入代码。JSONL 重新打开时，同一条解析路径会恢复 compact-1。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 11.1" \
  packages/pi-course/dist/test/11-*.test.js

#两个 tool result 仍属于 u3 开始的同一组

groupInteractions() 接收活动路径中的 message entries。它遇到 u1 时创建第一组， 遇到 u2 时结束第一组并创建第二组，遇到 u3 时做同样的事。路径结尾再结算第三组。

组内的工具事实靠 id 核对。处理 calls 时，函数记录 read-1 和 test-1；处理 r-test、r-read 时，它读取各自的 toolCallId。所以结果反序出现仍然合法，返回的 entries 保持原路径顺序：

[u3, calls, r-test, r-read, a3]

分组函数保留 r-test、r-read 的原路径顺序，同时在这个 user group 内核对四个对象 关系：每个 call.id 只声明一次；每条 result 的 toolCallId 都能在组内找到对应 call； 一个 call 至多对应一条 result；group 结束时，所有 call 都已经配齐 result。这些关系只 依赖 id 集合，所以反序完成的两个 result 仍能组成同一组。a3 是这个 fixture 的终态 回答，也按原位置留在组中。

预算层之所以使用 group，而不是直接使用 message，是因为裁剪位置只能落在 a1/u2 或 a2/u3 之间。落在 calls/r-test、r-test/r-read 或 r-read/a3 之间都会丢掉一次 工具往返的一部分。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 11.2" \
  packages/pi-course/dist/test/11-*.test.js

#31 个 token 怎样留下第二、三组

buildContext() 不负责从整棵 session tree 选择 leaf。调用者先用第 10 章的 pathTo() 得到活动路径，再把这条路径和预算选项传进来：

buildContext(activePath, {
  maxTokens: 31,
  systemPrompt: "sys",
  reservedOutput: 4,
  safetyMargin: 2,
  estimateTokens,
});

这个例子的扣除过程可以直接列成表：

reservedOutput 给本轮 assistant 回复留空间，safetyMargin 吸收估算误差。四个配置数值 和估算器的每次返回值都要是非负有限数。固定成本超过总窗口时，消息额度降到 0，不会 变成负数。

剩下的 22 从最新组向前使用。第三组成本 15，放得下；加上第二组正好是 22；再加第一 组会变成 29，于是选择停在 u2。keptEntryIds 记录原始 entry 的来源，返回的 messages 则是这些 entry 中消息的深副本。计入预算的 systemPrompt 也随结果返回， 第 13 章可以把两者一起交给模型。

另一个边界仍使用开篇第三组。假设消息额度只有 10，而第三组单独需要 15，函数仍返回 完整的 [u3, calls, r-test, r-read, a3]，并把 reason 设为 single_group_overflow。结果允许超过 maxTokens，因为当前函数不能安全地从组内剪掉 call、result 或终态回答。上层看到这个 reason 后再决定摘要、缩短工具输出或换模型。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 11.3" \
  packages/pi-course/dist/test/11-*.test.js

#compact-1 记录摘要与保留起点

开篇的预算结果丢弃了第一组，但 buildContext() 只读，不会自动生成摘要。调用者准备好 结构化 summary 后，再调用：

const compact1 = createCompactionEntry(activePath, {
  id: "compact-1",
  timestamp: 100,
  summary,
  firstKeptEntryId: "u2",
  tokensBefore: 29,
});

函数从 activePath.at(-1) 得到 parentId: "a3"。parent 不由调用者重复传入，因而不会 出现“记录追加在 a3 后面，字段却指向另一条 leaf”的两份答案。

firstKeptEntryId 的含义和 parent 不同。它是恢复上下文时保留原消息的起点，只能指向 一组的首条 user message。u2 合法；a2、calls、r-test 都位于组内，不能成为 切点。函数复用 groupInteractions() 找到这些组首，再把候选对象交给 parseSessionEntry() 做最后一次运行时校验和复制。

返回 compact1 以后，active path 仍保持原样。函数也不接收 Store。调用者可以展示 summary、记录审计或请求确认，最后再显式调用 store.append(compact1)。写入权仍由 Session Store 持有。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 11.4" \
  packages/pi-course/dist/test/11-*.test.js

#恢复时把最新摘要接在保留后缀前面

compact-1 追加以后，九条原消息一条也没有删除：

u1 → a1 → u2 → a2 → u3 → calls → r-test → r-read → a3 → compact-1
              ↑                                           │
              └──── firstKeptEntryId = u2 ────────────────┘

新的 u4 → a4 可以继续追加在 compact-1 后面。下一次调用 buildContext() 时，函数从 活动路径末尾向前找到最新 compaction，然后完成三件事：

1. 把七字段 summary 按固定顺序转换成一条 synthetic user message；
2. 从 u2 收集原消息，并继续收集 compaction 之后的 u4、a4；
3. 跳过 metadata 与 compaction entry，再对消息后缀分组并应用预算。

合成的摘要消息位于返回 messages 的最前面，它有自己的 token 成本。这个成本先从消息 额度中扣除，余量才交给完整 groups。keptEntryIds 只列原 session 中保留的 message entries，不为合成消息制造虚假 id。

路径中若已经有 compact-2，恢复只读取它。compact-1 及更早消息仍在 session 中， 但不会再生成第二份摘要消息。最新摘要负责接续此前事实；把所有摘要同时放入模型窗口会 重复内容，也可能让旧决策和新决策互相冲突。

第二次 compaction 使用同一个创建函数。假设 compact-2 保留 u3，它会追加在当时的 leaf 后面。后续 buildContext() 先读取 compact-2，再从 u3 收集原消息。预算选择 仍从最新组向前进行，工具组仍不会被拆开。

在确定性、无状态的估算器下，相同 active path 与 options 应得到深相等结果。每次结果 又是独立副本：修改第一次返回的摘要文字或工具参数，不会影响第二次构建，也不会改写 session entries。

npm run build -w @pi/course
node --test --test-name-pattern="Lab 11.5" \
  packages/pi-course/dist/test/11-*.test.js
node --test packages/pi-course/dist/test/11-*.test.js

#损坏记录在进入预算前就会被拒绝

正常路径已经闭合以后，再看输入边界会更清楚。

先破坏 compact-1 的一个字段。正常 summary 使用 changedFiles；若把它换成早期草案中的 files，输入会变成：

compact-1.summary.changedFiles  被移除
compact-1.summary.files         = ["context.ts"]
  → parseSessionEntry(compact-1) 报 schema 错误
  → Store 写入和 token 选择都没有开始

这里的 parser 只生成前文定义的七字段 CompactionSummary。旧记录需要先在边界外迁移成 当前形状；缺少当前字段或加入旧别名时，错误停在 compact-1，不会延后成预算差异。

再回到开篇的第三组。把 r-test.toolCallId 从 test-1 改成 unknown-1：

[u3, calls(read-1, test-1), r-test(unknown-1), r-read(read-1), a3]
  → groupInteractions() 找不到 unknown-1 对应的 call
  → 第三组不进入预算选择

若只把正常的 r-test(test-1) 移到 calls 前面，函数仍返回这一组。它先用 user 划定 interaction，再核对上一节的四个 id 关系；result 的数组位置、toolName 与终态 assistant 不参与这次配对。错误信息携带 entry id 或 call id，读者可以在历史边界定位第一处偏差。

#14 项测试固定到哪里

这些测试固定了课程实现的确定性规则：严格 compaction schema、两个 Store 的重开、 user 分组、call/result 配对、固定成本、完整组裁剪、最新组超限、纯创建、最新摘要恢复、 二次压缩和公开副本隔离。

这 14 项测试把 compaction 固定在四个范围内：

• 预算使用调用者提供的确定性估算器，并扣除本章列出的固定成本。真实 tokenizer、tool schema、图片和缓存成本需要由 Provider 层给出另一套估算。
• createCompactionEntry() 校验七字段 summary 的形状；summary 正文与 tokensBefore 由 调用者提供，函数不重新判断业务事实是否完整，也不重算压缩前规模。
• groupInteractions() 以 user 边界和四个 call/result id 关系组成不可拆分组。Result 位置、toolName 和终态 assistant 不属于这层配对规则。
• single_group_overflow 只报告最新一组无法放入当前窗口。截短工具输出、生成专用摘要、 换模型、自动触发时机和并发摘要写入都由上层生命周期选择。

#本章验收

npm run build -w @pi/course
node --test packages/pi-course/dist/test/11-*.test.js

#可选迁移练习

#小结

开篇九条消息始终留在 session 中。groupInteractions() 把它们分成三个 user interactions，第三组完整保存两个 call、反序到达的两个 result 和终态 assistant。 buildContext() 扣除固定成本后，从最新组向前选择，因此 31 token 的例子只把第二、 三组交给模型。

compaction 把摘要、first kept 和压缩前规模追加成一条新记录。恢复读取活动路径上的 最新摘要，再接上完整消息后缀；第二次压缩仍然只追加，不删除旧事实。第 12 章会把项目 资源产生的提示加入这里返回的 systemPrompt，继续使用同一个上下文入口。