Skip to main content

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

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

第 10 章最后得到的是一条 active path。这里沿用这个输入接口，但换成一组便于手算预算 的九条 message entries。表中最后一列是测试估算器给每条消息返回的 token 数，不是真实 provider 的 tokenizer 结果。 calls 先声明 read-1，随后声明 test-1。测试先完成，所以 r-test 在路径中排在 r-read 前面。每个 result 仍可通过 toolCallId 找回自己的 call。 groupInteractions() 以 user 消息为起点，把这九条记录分成三组：
第三组包含 user、两个 tool call、两个 result 和最终 assistant。它是预算可以整体保留 或整体丢弃的最小单位。result 的出现顺序不影响配对，也不会把这一组拆开。 现在把这条活动路径交给 buildContext()。例子中的 maxTokens 是 31；system prompt 占 3，回答预留 4，安全余量占 2。消息还剩 22。三组成本依次为 7、7、15，所以函数从 最新一组向前选择，结果正好保留第二、三组：
u1 和 a1 仍在 session 中，只是没有进入这次模型请求。这里的有限消息数组叫 context projection，也就是从历史派生出的临时视图。换一个模型窗口或预留量，同一段 历史可以得到另一份视图。
Checkpoint 11 · 从固定 transcript 派生有限上下文模式： 重建起终点： parent 555162636bf0a8fd6e667e366d0103891cef1d6c 是第 10 章完成后的起点； target 5fb517c2012d8e6227c0e17ee65e530e18ac13e6 是 compaction 记录、上下文投影和 14 项聚焦测试完成后的终点。教学文件： packages/pi-course/src/session.ts、 packages/pi-course/src/context.ts学习脚手架： parent 中还没有 context.ts。practice 会加入 starters/11-context.ts，并用 starters/11-session.ts 保留第 10 章能力。公共类型和 函数签名已经固定；五个 Lab 的分支分别抛出明确异常。动手前只需知道： user message 开始一个 interaction，直到下一条 user message； 组内每个 tool call 都由 toolCallId 找到唯一 result。预算只在这些完整组之间裁剪。第一步： 先不看 target diff，让 parseSessionEntry() 收窄一条正常的 compaction 记录，并让两种 Store 写入、读回它。预算选择留到后面的 Lab。第一次红灯： 初始 build 可以通过。只运行 Lab 11.1 时，三项测试都停在 Lab 11.1 compaction entry 尚未实现。聚焦测试： packages/pi-course/test/11-context-compaction.test.ts定位命令： npm run checkpoint -w @pi/course -- 11练习目录： npm run practice -w @pi/course -- 11聚焦运行： npm run build -w @pi/course，然后运行 node --test packages/pi-course/dist/test/11-*.test.js通过证据： 14 项测试按 3/3 → 3/3 → 3/3 → 2/2 → 3/3 覆盖记录解析、 交互分组、预算投影、摘要创建和重复恢复。

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

当较早的消息以后不再原样进入模型窗口，session 需要留下它们的结构化摘要。摘要不是 对原记录的覆盖；它是一条追加到当前 leaf 后面的 CompactionSessionEntry：
继续使用开篇路径，可以创建 compact-1，让它的 parentId 指向当前末尾 a3。 firstKeptEntryId: "u2" 表示恢复时从第二组开始保留原消息。tokensBefore 由调用者 写入，用来记录压缩前的估算规模；parser 只检查它是非负有限数，不会重新估算并核对该值。 summary 的七个字段分别保存目标、约束、已完成事项、决策、变更文件、未解决事项和 下一步：
parseSessionEntry() 逐字段读取外部对象。goal、parentId 和 firstKeptEntryId 不能为空；数组中的每一项都是字符串；tokensBefore 是非负有限数。 解析器返回新对象，因此调用者之后修改 summary 数组也不会改动 Store 中的记录。 第 10 章的两个 Store 已经统一通过 parseSessionEntry() 获取写入快照。union 和解析 分支补齐后，InMemorySessionStore 与 JsonlSessionStore 不需要新增 compaction 专用 写入代码。JSONL 重新打开时，同一条解析路径会恢复 compact-1。
实践 11.1 · 保存并重开一条 compaction 记录目标： 让结构化摘要经过运行时收窄后进入两种 Store，并保持副本隔离。文件： packages/pi-course/src/session.ts动作：
  1. 确认 CompactionSummary、CompactionSessionEntry 和 SessionEntry union 的形状。
  2. 为七个 summary 字段实现严格解析。
  3. 在 parseSessionEntry() 中读取非空 parent、first kept 和非负有限 tokens。
  4. 让解析结果与输入的 summary、数组都不共享引用。
  5. 用测试中的正常记录检查内存写入、JSONL 写入和重新打开。
  6. 删除 Lab 11.1 的显式异常，只运行本段测试。
运行：
预期： 3/3。第三项确实关闭并重新打开 JSONL Store，不只检查 TypeScript 类型。

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

groupInteractions() 接收活动路径中的 message entries。它遇到 u1 时创建第一组， 遇到 u2 时结束第一组并创建第二组，遇到 u3 时做同样的事。路径结尾再结算第三组。 组内的工具事实靠 id 核对。处理 calls 时，函数记录 read-1 和 test-1；处理 r-test、r-read 时，它读取各自的 toolCallId。所以结果反序出现仍然合法，返回的 entries 保持原路径顺序：
分组函数保留 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 之间都会丢掉一次 工具往返的一部分。
实践 11.2 · 用 user 边界和 callId 组成 interaction目标： 把开篇 transcript 分成三个可整体选择的组，同时保留工具结果的实际顺序。文件： packages/pi-course/src/context.ts动作：
  1. user message 到达时结算上一组并开始新组。
  2. 从 assistant content 中收集本组的 tool call id。
  3. 用 toolCallId 配对 result，不依赖相邻位置或完成顺序。
  4. 组结束时确认 call/result 完整且唯一。
  5. 通过 parseSessionEntry() 或等价严格边界返回深副本。
  6. 删除 Lab 11.2 的显式异常，只运行本段测试。
运行：
预期： 3/3。正常分组与反序 result 各有一项；第三项集中检查损坏的工具事实。

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

buildContext() 不负责从整棵 session tree 选择 leaf。调用者先用第 10 章的 pathTo() 得到活动路径，再把这条路径和预算选项传进来：
这个例子的扣除过程可以直接列成表： 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 后再决定摘要、缩短工具输出或换模型。
实践 11.3 · 在完整 group 边界选择消息后缀目标： 让固定成本和消息选择都能从返回值中核对，最新超限组仍保持完整。文件： packages/pi-course/src/context.ts动作：
  1. 收窄 max、输出预留、安全余量和估算器返回值。
  2. 计算 system 成本与 availableForMessages。
  3. 调用 groupInteractions()，从最新组向前累加成本。
  4. 最新组单独超限时完整保留，并返回 single_group_overflow。
  5. 返回 system prompt、消息副本、来源 id、reason 和各项 token 数。
  6. 确认估算器收到的是消息副本，返回结果也不引用 active path。
  7. 删除 Lab 11.3 的显式异常，只运行本段测试。
运行：
预期： 3/3。三项分别固定预算扣除、最新单组超限和多组裁剪边界。

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

开篇的预算结果丢弃了第一组，但 buildContext() 只读，不会自动生成摘要。调用者准备好 结构化 summary 后，再调用：
函数从 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 持有。
实践 11.4 · 创建记录，但不替调用者写 Store目标： 从活动路径推导唯一 parent，并只允许 interaction 起点成为 first kept。文件： packages/pi-course/src/context.ts动作：
  1. 拒绝空路径，以及与路径中现有 entry 重复的新 id。
  2. 从路径最后一项推导 parentId。
  3. 复用分组结果，只接受每组第一条 message 的 id。
  4. 用 parser 校验 summary、timestamp 和 tokensBefore。
  5. 修改输入 summary 或返回记录，active path 都应保持不变。
  6. 删除 Lab 11.4 的显式异常，只运行本段测试。
运行：
预期： 2/2。第一项观察 parent 和副本；第二项检查空路径、重复 id 与组内切点。

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

compact-1 追加以后，九条原消息一条也没有删除：
新的 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。
实践 11.5 · 从最新摘要恢复并再次压缩目标： 让重启、重复构建和第二次 compaction 遵循同一条确定路径。文件： packages/pi-course/src/context.ts动作：
  1. 从活动路径末尾向前找到最新 compaction。
  2. 确认 first kept 位于该 compaction 之前，并且是完整组的 user 起点。
  3. 按固定字段顺序生成 synthetic user message。
  4. 从 first kept 收集消息，跳过 metadata 和所有 compaction entries。
  5. 先扣摘要消息成本，再复用分组和预算选择。
  6. 重复调用并修改第一次结果，第二次结果与 active path 都应不变。
  7. 在恢复后的路径上创建第二条 compaction，再验证完整组边界。
  8. 删除 Lab 11.5 的显式异常，运行本段和全章测试。
运行：
预期： 本段 3/3，全章 14/14。

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

正常路径已经闭合以后，再看输入边界会更清楚。 先破坏 compact-1 的一个字段。正常 summary 使用 changedFiles；若把它换成早期草案中的 files，输入会变成：
这里的 parser 只生成前文定义的七字段 CompactionSummary。旧记录需要先在边界外迁移成 当前形状；缺少当前字段或加入旧别名时，错误停在 compact-1，不会延后成预算差异。 再回到开篇的第三组。把 r-test.toolCallId 从 test-1 改成 unknown-1：
若只把正常的 r-test(test-1) 移到 calls 前面，函数仍返回这一组。它先用 user 划定 interaction，再核对上一节的四个 id 关系；result 的数组位置、toolName 与终态 assistant 不参与这次配对。错误信息携带 entry id 或 call id，读者可以在历史边界定位第一处偏差。
预期失败 · 按三条消息截取工具组临时把 Lab 11.3 的组选择改成 messages.slice(-3)，然后只运行 Lab 11.3。开篇第三组会 被截成 r-test、r-read、a3；u3 和声明两个 call 的 calls 消失。聚焦测试期望最新超限组完整返回五条记录，因此 keptEntryIds 和角色序列都会立即失败。 恢复“从最新 group 向前选择”后，Lab 11.3 应回到 3/3，全章回到 14/14。

​
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 只报告最新一组无法放入当前窗口。截短工具输出、生成专用摘要、 换模型、自动触发时机和并发摘要写入都由上层生命周期选择。
与上游 Pi 的固定提交对照固定提交 8479bd8 的 coding-agent 也把 compaction 作为 session entry 追加，记录 firstKeptEntryId 和 tokensBefore。buildContextEntries() 沿当前 leaf 取最新 compaction，把摘要消息与保留后缀交给模型；早期摘要和已概括前缀仍留在 session。上游该提交的 summary 主体是字符串，并且产品压缩代码还能为超大 turn 生成前缀摘要。 课程使用七字段对象，并把整个 user interaction 设为不可拆分单位。课程的严格 parser、 确定性估算器和 single_group_overflow 是教学契约，不能当作上游实现的逐行复刻。

​
本章验收

Checkpoint 11 · 固定 transcript 能被分组、裁剪和恢复在隔离 practice 目录运行：
结果应为 14/14。随后用开篇九条记录说明以下四段数据流：
  1. groupInteractions() 为什么得到 [u1,a1]、[u2,a2] 和包含完整工具往返的第三组；
  2. 31 token 预算怎样先扣 system、输出预留和安全余量，再保留第二、三组；
  3. compact-1 为什么以 a3 为 parent、以 u2 为 first kept，并且不修改旧记录；
  4. 恢复为什么只生成最新摘要消息，再从 first kept 接上原消息后缀。
还要修改一次 buildContext() 返回的工具参数，证明 active path 不变；再创建第二条 compaction，证明下一次恢复只使用最新摘要。重新定位可运行 npm run checkpoint -w @pi/course -- 11；重做时新建 practice 目录，不复用已改过的 脚手架。

​
可选迁移练习

陪练迁移 · 记录每个 group 的预算去向在不改变 BuildContextResult 的前提下，先写一个纯函数，输入 InteractionGroup[] 和同一个估算器，返回每组的 entry ids、token 成本和 kept | trimmed | overflow 状态。至少覆盖开篇三组、最新工具组超限和没有工具的单组路径。函数只读输入，不能重新定义 buildContext() 的选择规则。

​
小结

开篇九条消息始终留在 session 中。groupInteractions() 把它们分成三个 user interactions，第三组完整保存两个 call、反序到达的两个 result 和终态 assistant。 buildContext() 扣除固定成本后，从最新组向前选择，因此 31 token 的例子只把第二、 三组交给模型。 compaction 把摘要、first kept 和压缩前规模追加成一条新记录。恢复读取活动路径上的 最新摘要，再接上完整消息后缀；第二次压缩仍然只追加，不删除旧事实。第 12 章会把项目 资源产生的提示加入这里返回的 systemPrompt，继续使用同一个上下文入口。