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

#你将得到什么

第 10 章已经把完整消息保存成一棵追加式历史树。它可以一直增长，但模型窗口不会一起 增长。如果为了省 token 直接删除旧记录，分支、恢复和审计都会失去事实依据。

本章只增加一种复杂性：从不改写的历史中，派生本次模型真正要看的有限上下文。 完成后，你会得到：

• CompactionSessionEntry：把一份结构化摘要追加到 session；
• groupInteractions()：按用户回合和工具 callId 组成不可拆分的交互；
• buildContext()：先扣除 system、输出预留和安全余量，再选择最近的完整交互；
• createCompactionEntry()：只创建一条新的摘要记录，不修改历史，也不偷偷写 Store；
• 可重复的恢复规则：只使用活动路径上最新摘要，再接上它要求保留的消息后缀。

本章只有一个总原则：

历史回答“发生过什么”；上下文回答“这次模型需要看到什么”。压缩改变后者，不改写 前者。

#为什么第 11 章放在这里

上下文压缩必须晚于 session。没有第 10 章的稳定身份和活动路径，所谓“删掉旧消息” 既无法说明删的是哪条分支，也无法在重启后得到同一结果。

它又必须早于资源和扩展。第 12 章会把项目说明、Skill 和扩展提供的提示加入 system prompt；这些内容同样占模型窗口。先把预算入口固定下来，后续资源才能作为明确输入接 进来，而不是在各处自行裁剪消息。

第 10 章：选中一条真实、可恢复的历史路径
        ↓
第 11 章：从这条路径派生有限上下文
        ↓
第 12 章：把本轮资源提示加入同一个预算入口

#开始动手

仍然在教学历史仓库中生成隔离练习：

cd <你的工作区>/pi-course
npm run practice -w @pi/course -- 11 <新目录>
cd <新目录>
npm install

本章只修改：

packages/pi-course/src/session.ts
packages/pi-course/src/context.ts

session.ts 保留第 10 章的完整实现，只把 compaction 的类型和运行时解析留给你。 context.ts 已固定分组、预算、创建摘要和恢复所需的公共签名。不要复制旧版 safeTail()、compact() overload 或自动 summarizer；它们不属于本章契约。

#先建立全景

先分清历史和上下文。

一次请求的数据流是：

SessionEntry 全集
  → pathTo(entries, leafId)
  → active path                       历史层在这里结束
  → 最新 compaction + 保留后缀
  → 完整 interaction 分组
  → system / output / margin 预算
  → BuildContextResult                本轮模型输入

Session Store 拥有写入权。buildContext() 只有读取权；它不选择 leaf，也不把结果写回 session。相同历史可以针对不同模型窗口生成不同上下文，只要过程确定且来源可追踪， 这并不表示历史互相矛盾。

调试时也按这条边界排查：

1. 事实不在 active path：检查写入或分支选择；
2. 事实在 active path、没有进入结果：检查 compaction 或预算；
3. 事实已经进入结果、模型仍答错：再检查模型行为。

#第一步：让摘要成为可持久化事实

课程只保留一套结构化摘要：

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

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

每个字段都有单一含义。firstKeptEntryId 指向摘要之后仍要原样保留的第一个 interaction；tokensBefore 记录创建摘要时的估算规模，用于诊断，不参与树结构。

compaction 必须有 parent，因为它总结的是一条已经存在的活动路径。tokensBefore 必须是非负有限数。七个摘要字段全部必填；不要接受旧版 files、nextSteps、 invariants，也不要保留两套 schema 再相互转换。

parseSessionEntry() 继续承担外部数据边界。实现顺序如下：

1. 增加严格的 summaryAt()，拒绝缺字段、多余字段和非字符串数组；
2. 在 entry 判别分支中加入 type === "compaction"；
3. 复用第 10 章的非空字符串、有限数和普通 JSON 对象检查；
4. 返回新对象，不与输入 summary 数组共享引用。

两种 Store 不需要新增特殊逻辑。它们都通过 parseSessionEntry() 取得快照，所以 union 和解析器正确后，内存与 JSONL 自然能够保存新记录。

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

#第二步：预算不能拆开一次完整交互

按“最后 N 条消息”裁剪会留下孤立工具结果：

user(u)
assistant(call c1, call c2)
toolResult(c2)             完成顺序可以反过来
toolResult(c1)
assistant(done)

这五条属于同一个 interaction。判断依据不是数组相邻，而是：

• user 开始新组；
• assistant 中的每个 tool call id 在本组唯一；
• toolResult 用 toolCallId 找到本组内的 call；
• 到下一个 user 或路径结束时，每个 call 都有且只有一个 result。

因此要拒绝四类损坏：第一个 user 之前出现消息、孤立 result、重复 call/result、缺失 result。错误必须带上相关 entry 或 callId，否则预算层只会在更晚的位置报出难懂 错误。

groupInteractions() 返回记录副本，而不是直接引用输入。后面的预算选择和测试故障 注入都不能改写 session 历史。

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

#第三步：先扣固定成本，再选择最近的完整组

本章不假装实现某家模型的精确 tokenizer。调用者注入同一个 estimateTokens(value)，测试用确定性数字固定选择结果。预算公式是：

messages 可用额度
  = maxTokens
  - system prompt
  - reservedOutput
  - safetyMargin

reservedOutput 给本轮回答留空间，safetyMargin 吸收估算误差。三者都必须是非负 有限数，估算器返回负数或非有限数也要拒绝。

选择算法从最新 interaction 向前累加：

先完整保留最新组
  → 它单独超限：仍完整返回，reason=single_group_overflow
  → 没超限：继续尝试加入前一组
  → 下一组放不下：停在组边界，reason=trimmed
  → 全部放下：reason=within_budget

单组超限时不能从中间切开工具往返。显式返回 overflow，让上层决定是否生成摘要、压缩 超大工具结果或换模型。

结果必须同时返回 systemPrompt 和 messages。system prompt 既然计入预算，就不能 只用于统计后丢掉；第 12、13 章会把这份完整投影直接交给模型。

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

#第四步：创建摘要记录，不替调用者写入

createCompactionEntry(activePath, input) 只做一件事：返回一条经过验证、可以交给 Store 的新记录。

activePath 最后一条 id
  → 新 compaction.parentId

input.firstKeptEntryId
  → 必须是 activePath 中某个 interaction 的第一条 user message

函数不能接受组内的 assistant 或 toolResult 作为切点。它也不调用 Store： SessionStore.append() 是唯一写入者，上层可以先展示摘要、请求确认或记录审计，再决定 是否追加。

创建过程可以复用已经写好的边界：

1. 用 groupInteractions() 找出所有合法组首；
2. 用 active path 最后一项推导 parent，不让调用者另传一份可能冲突的 parent；
3. 构造候选 compaction；
4. 交给 parseSessionEntry() 完成严格校验与深复制。

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

#第五步：恢复时只认活动路径上的最新摘要

追加 compaction 后，旧消息仍在历史中：

u1 → a1 → u2 → a2 → cmp1 → u3 → a3
                 ↑
          firstKeptEntryId=u2

构建上下文时：

1. 从 active path 末尾向前找到最新 compaction；
2. 把它的结构化 summary 转成格式固定的 synthetic user message；
3. 从 firstKeptEntryId 开始收集原消息，跳过 metadata 和 compaction 记录；
4. 再按 interaction 分组和预算选择；
5. 返回摘要消息加选中的完整后缀。

如果路径还有更早的 compaction，只使用最新一条。最新摘要已经承担了接续更早事实的 责任；同时塞入多份摘要会重复甚至冲突。

重复调用 buildContext() 必须得到深相等结果。修改第一次返回的摘要或工具参数， 不能影响第二次构建。再次压缩也只会创建新的 compaction entry，旧摘要和原消息仍留在 session。

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

#故意把它弄坏

临时把 Lab 11.3 的组选择替换成按消息数量取尾部，例如 messages.slice(-3)。

#本章没有证明什么

14 项测试没有规定：

• 某家 provider tokenizer 的精确计数；
• tool schema、图片、缓存或网络层的额外 token 成本；
• 真实模型怎样生成高质量摘要；
• 摘要是否完整保留了所有业务事实；
• 单个超大 interaction 应该压缩工具输出、换模型还是停止；
• 何时自动触发 compaction；
• Store 是否应该自动写入 createCompactionEntry() 的结果；
• 多个并发压缩任务如何协调。

课程使用结构化摘要和确定性格式，是为了测试恢复规则，不是宣称摘要质量已经解决。

#本章验收

#可选迁移练习

#小结

Session 保存不可改写的事实，context 是每次请求前重新计算的临时视图。先用 callId 把消息组成完整 interaction，再扣除 system、输出预留和安全余量，从最近的 完整组向前选择。

Compaction 是一条新历史记录，不是删除动作。它保存结构化摘要、first kept 和创建时 规模；恢复只使用活动路径上的最新摘要，再接保留后缀。下一章会把项目资源和受信扩展 生成的提示接入同一个 systemPrompt，而不会创建第二套 context builder。