上下文压缩机制对比：PI / OpenClaw / Codex / WorkBuddy

最后修改时间：2026-10-10 21:43

一句话定义：上下文压缩是 harness /ˈhɑːnɪs/ （运行外壳）的"内存管理"——进上下文之前瘦身、组装时裁剪、超窗时摘要续命；四家实现细节不同，骨架高度一致。

关联阅读：压缩方法论与预算分配见 ../AI知识库/09-RAG与上下文/02-上下文工程.html；harness 是什么见 ../AI编程范式/AI辅助编程范式/09-harness-engineering.html；执行隔离层见 sandbox沙箱.html；Agent 侧的"选 / 压 / 层 / 淘"见 ../Agent开发知识/13-进阶与工程化/02-上下文工程.html。

1. 为什么压缩是 harness 的第一等问题

LLM /ˌel el ˈem/ （ Large Language Model /lɑːdʒ ˈlæŋɡwɪdʒ ˈmɒdl/ ，大语言模型）能力固定、窗口有限，而 Agent 的输入只增不减：每一轮工具调用都会往上下文里灌进命令日志、文件内容、 API /ˌeɪ piː ˈaɪ/ （ Application Programming Interface /ˌæplɪˈkeɪʃn ˈprəʊɡræmɪŋ ˈɪntəfeɪs/ ，应用编程接口）返回、搜索结果。 膨胀的来源不是对话，是工具结果。

所以压缩不是"聊天记录太长时删一点"，它是 harness 四件事里的一件：

一句话铁律，四家都遵守： 窗口是 RAM /ræm/ （ Random Access Memory ，随机存取存储器）， 磁盘才是真相。 压缩只改变"模型下一轮看到什么"，完整历史一律落盘——可恢复、可回放、可审计。

落地示例 ：本文写作过程中抓取某开源仓库 README（113 KB）。工具层没有把 113 KB 塞进上下文，而是返回 截断视图 并提示 truncated output，原文留在临时文件；模型拿到的是可读片段 + 一个指针。这就是最廉价、收益最大的一层压缩。

2. 三层压缩框架

把四家做法抽象出来，压缩固定在三个层次上， 顺序就是从便宜到昂贵 ：

flowchart LR
    subgraph L1["① 工具层：进上下文之前"]
      A1["截断 / 外部化<br/>只留摘要 + 指针"] --> A2["完整内容落盘"]
    end
    subgraph L2["② 组装层：每次调用前"]
      B1["token 预算裁剪"] --> B2["按需加载 / 渐进披露"]
    end
    subgraph L3["③ 会话层：超窗时"]
      C1["结构化摘要"] --> C2["保留近端原文"]
      C2 --> C3["写入 compaction entry"]
    end
    L1 --> L2 --> L3

为什么顺序不能颠倒 ：摘要是有损的（会丢路径、丢精确标识符、丢错误堆栈），而工具层压缩可以做到无损或可控损失。 能用①解决的，不要用③解决。

落地示例 ：同一个"读完 200 个文件再回答"的任务：

3. 四家总览

表中"未公开"表示没有任何一手来源能证实，本文不猜测。

4. PI：压缩是会话树里的一个 entry

PI（earendil-works/pi，官网 pi.dev）是开源编码 Agent harness；社区教学仓库 cellinlab/how-pi-agent-works 把它的压缩链路完整拆了出来。

4.1 机制

PI 把会话建模为 会话树（Session Tree） ，消息以只追加的 JSONL 落盘。压缩不是外部旁路，而是 往树里追加一个 compaction entry ：

1. 估算当前路径上的 token 用量，超阈值（或用户敲 /compact）触发；
2. 选 cut point /kʌt pɔɪnt/ （切点），把"旧范围"与"保留近端"分开；
3. 用模型把旧范围压成 结构化摘要 ；
4. 追加 CompactionEntry，记录 summary + firstKeptEntryId + tokensBefore；
5. 后续组装上下文 = 摘要 + firstKeptEntryId 之后的原文 。

flowchart TB
    A["完整历史消息"] --> B["估算 token"]
    B --> C{"超过阈值?"}
    C -->|"否"| D["正常请求"]
    C -->|"是"| E["选切点 cut point"]
    E --> F["结构化摘要旧消息"]
    F --> G["追加 CompactionEntry"]
    G --> H["上下文 = summary + 近端原文"]

4.2 四条关键不变式

摘要内容同样是结构化的：官方实现包含 <read-files>、<modified-files> 这类 文件操作追踪 ，以及 details 字段—— details 给程序读，自然语言 summary 给模型读。

落地示例 ：仓库里有 README.md 与 src/api.ts。

4.3 落地示例：最小 compaction 模块

主示例用 TS /ˌtiː ˈes/ （ TypeScript /ˈtaɪpskrɪpt/ ）。下面这段把四条不变式都实现出来，summarize 换成真实模型调用即可上线：

/** 会话条目：与 PI / OpenClaw 的 transcript entry 同构 */
export type EntryType = "user" | "assistant" | "toolResult" | "compaction";

export interface Entry {
  id: string;
  type: EntryType;
  text: string;
  /** assistant 发起工具调用时的 callId；toolResult 用同一 callId 回指 */
  callId?: string;
  toolName?: string;
}

export interface CompactionDetails {
  readFiles: string[];
  modifiedFiles: string[];
}

export interface CompactionEntry extends Entry {
  type: "compaction";
  summary: string;
  /** 保留原文的起始 entry id；下次压缩从这个边界附近续算 */
  firstKeptEntryId: string | null;
  tokensBefore: number;
  details: CompactionDetails;
}

/**
 * 粗略 token 估算：CJK 字符约 1 字 1 token，其余约 4 字符 1 token。
 * OpenClaw 同样按 CJK 的近似权重计数；生产环境应改为读 provider 的 usage。
 */
export function estimateTokens(text: string): number {
  let cjk = 0;
  for (const ch of text) {
    if (/[\u3000-\u9fff\uff00-\uffef]/.test(ch)) cjk += 1;
  }
  return Math.ceil(cjk + (text.length - cjk) / 4);
}

export const tokensOf = (entries: Entry[]): number =>
  entries.reduce((sum, e) => sum + estimateTokens(e.text), 0);

/**
 * 选切点（不变式 ①②）：从尾部向前累加直到超过 keepRecentTokens；
 * 若切点落在 toolResult 上，把它配对的 assistant 调用一起保留。
 */
export function pickCutPoint(entries: Entry[], keepRecentTokens: number): number {
  let kept = 0;
  let cut = entries.length;
  for (let i = entries.length - 1; i >= 0; i--) {
    kept += estimateTokens(entries[i].text);
    if (kept > keepRecentTokens) break;
    cut = i;
  }
  while (cut > 0 && entries[cut]?.type === "toolResult" && entries[cut - 1]?.type === "assistant") {
    cut -= 1;
  }
  return cut;
}

/** 续算边界（不变式 ③）：找不到 firstKeptEntryId 时，退回上一个 compaction 之后 */
export function resumePoint(entries: Entry[]): number {
  const last = [...entries].reverse().find((e): e is CompactionEntry => e.type === "compaction");
  if (!last) return 0;
  const idx = entries.findIndex((e) => e.id === last.firstKeptEntryId);
  return idx >= 0 ? idx : entries.indexOf(last) + 1;
}

export interface CompactionOptions {
  /** 模型上下文窗口 */
  contextWindow: number;
  /** 预留：给输出与摘要本身留空间（OpenClaw 内嵌默认 20 000） */
  reserveTokens: number;
  /** 保留近端原文（OpenClaw 默认 20 000） */
  keepRecentTokens: number;
  summarize: (older: Entry[]) => Promise<{ summary: string; details: CompactionDetails }>;
}

/** 超窗才压缩；返回「摘要 entry + 保留的近端原文」 */
export async function compactIfNeeded(
  entries: Entry[],
  opts: CompactionOptions,
): Promise<Entry[]> {
  const used = tokensOf(entries);
  if (used + opts.reserveTokens <= opts.contextWindow) return entries;

  const cut = pickCutPoint(entries, opts.keepRecentTokens);
  const older = entries.slice(0, cut);
  const tail = entries.slice(cut);
  // 单个 turn 就超窗：真实实现走 split turn（前缀摘要 + 后缀保留）
  if (older.length === 0) return entries;

  const { summary, details } = await opts.summarize(older);
  const entry: CompactionEntry = {
    id: `cmp-${older[older.length - 1].id}`,
    type: "compaction",
    text: summary,
    summary,
    firstKeptEntryId: tail[0]?.id ?? null,
    tokensBefore: used,
    details,
  };
  return [entry, ...tail];
}

代入数字 （contextWindow = 128 000、reserveTokens = 20 000）：

5. OpenClaw：compaction 与 pruning 分工最清楚

OpenClaw（github.com/openclaw/openclaw，文档 docs.openclaw.ai）是本文 公开资料最细 的一家，设计最值得直接照抄。

5.1 两套机制，职责不重叠

心法： 摘要治"对话"，剪枝治"工具输出"。 两者互补——剪枝让工具输出在两个压缩周期之间保持精简。

5.2 compaction 的分层预算采样

内置压缩 一次模型请求 处理完旧历史，但单次请求输入被限制在 160 000 字符（约 40 000 token） ；超了按固定分层填充：

每个空档都标注"漏了多少条"，并明确指示摘要器 "不要猜测被省略的内容，且要继承上一版摘要里的事实" 。中 / 日 / 韩（ CJK /ˌsiː dʒeɪ ˈkeɪ/ ， Chinese Japanese Korean /ˌtʃaɪˈniːz ˌdʒæpəˈniːz kəˈriːən/ ，中日韩字符）按近似 token 权重计数。

为什么这样采样而不是简单截断 ：用户消息是 纠正与决策 的载体（"改成只看华东区""按同比口径"），所以单独给 1/4 份额；简单截断会把中途改过的口径丢掉。

5.3 safeguard 质量门：摘要不合格就不写

现在默认开启 safeguard /ˈseɪfɡɑːd/ （安全护栏）模式，摘要必须过质量审计：

1. 生成的正文里必须有 规定的标题 ；
2. 即将落盘的确切文本里必须保留 待办诉求 与 精确标识符 （文件名、路径、ID、数字）；
3. 不合格只允许有限次纠正重试； 全部不通过就不写 entry、保留原历史 ——而不是写入一段坏摘要。

5.4 pruning：软剪、硬清除、服务端清除

服务端路径的参数是 推导出来 的，不需要额外配置：

两条容易忽略的细节：

• TTL /ˌtiː tiː ˈel/ （ Time To Live /taɪm tuː lɪv/ ，存活时间）门控：客户端剪枝要等缓存 TTL 过期才动手（默认 5 分钟，Anthropic 插件播种为 1 小时）， 避免打碎 prompt cache /prɒmpt kæʃ/ （提示缓存）前缀——否则省下的输入 token 还不够付缓存重建的钱。
• 图片清理 ：至少保留最近 3 个完整 turn 逐字节不变，之后每 8 个 turn 推进一次边界，旧图替换为已处理标记，防止图片负载反复打爆 prompt cache。

5.5 保留量与触发路径

触发三条路：

1. 阈值 ：接近上限时自动压缩；
2. 溢出恢复 ：provider 报上下文超限 → 压缩后重试 ，保留原请求、不重放已完成的动作；
3. 手动 ：/compact，可聚焦话题（如 /compact Focus on <topic>）。

另外，压缩前还会做一次 memory flush /ˈmeməri flʌʃ/ （记忆刷新）：用静默 turn 把要点写进长期记忆，避免摘要把关键约束丢掉。

落地示例 ：数据分析类会话的调参取舍。

6. Codex：原生压缩归 app-server

6.1 机制

⚠️ 来源说明：本文写作时本机网络对 developers.openai.com、platform.openai.com 一律返回 403，官方文档抓取脚本同样被拒。因此本节以 产品实际行为 为准，并引用 OpenClaw 对其集成路径的观察作为交叉验证。

• 压缩归 app-server 所有 ：OpenClaw 的 Codex harness 运行时文档明确写"token 压力压缩与手动线程压缩由 Codex app-server 原生负责"，压缩完成会发出 contextCompaction 完成项。
• 两条入口 ：自动的 token 压力压缩，以及手动 /compact（集成方通过 thread/compact/start 请求，并等待对应完成项）。
• 原生线程是唯一真相 ：集成方只能维护 只读镜像 ，不能改写 Codex 的原生线程记录。
• 集成方兜底 ：当集成方自身镜像字节数超阈值时，会先做一次它的语义压缩；若不成功，则退化为"最近整 turn 的有界投影"，并 明确提示用户重发关键细节 （被省略的历史无法再回到上下文）。

6.2 可观测的三层（本会话实证）

6.3 明确的不确定项

以下问题 没有一手来源 ，本文不下结论：切点如何与工具调用配对、摘要模板长什么样、keepRecent 具体阈值、是否支持分支摘要。

这条"不透明"本身与 OpenClaw 文档相互印证：它记录原生压缩的起止状态，但 不暴露人类可读的压缩摘要，也不暴露 Codex 保留了哪些条目 ——说明这些细节没有公开接口。

7. WorkBuddy：闭源，但"记忆外置"是主线

7.1 先说证据边界

WorkBuddy 属腾讯 CodeBuddy 家族， 闭源、无公开压缩规范 。因此本节只写两类可验证材料：

1. 本仓库可观测配置 ：.workbuddy/memory/MEMORY.md + 按日期笔记 + .workbuddy/rules/*.mdc（与 .cursor/rules/、.codebuddy/rules/ 三端同步）；
2. 社区 clean-room 教学仓库 adongwanai/learn-workbuddy（明确声明是教学复刻、非源码提取）。

不做机制臆测：凡是它内部怎么切分、摘要模板如何，本文一律留白。

7.2 公开可验证的三条主线

教学仓库把心法写成一句话： 上下文窗口是 RAM，JSONL、SQLite、记忆文件和 tool-results 是磁盘。 它还专门为"压缩不变量"和"压缩后能否 fresh-process 恢复"设计了评测用例——这一点比多数 harness 更工程化。

7.3 落地示例：文件式记忆注入

WorkBuddy 的规则 / 记忆是 磁盘文件 ，所以注入时同样是"索引 + 预算"，而不是全文搬运：

export interface MemorySource {
  path: string;
  /** 命中相关性 0~1，由检索或规则匹配给出 */
  score: number;
  /** 单文件注入上限，防单文件吃光预算 */
  maxChars: number;
}

export interface MemorySlot {
  path: string;
  text: string;
  truncated: boolean;
}

/**
 * 记忆注入：按分数排序 + 逐条限长 + 总预算封顶。
 * 全文始终留在磁盘，模型只看到"命中片段 + 路径指针"。
 */
export function buildMemoryContext(
  sources: MemorySource[],
  read: (path: string) => string,
  budgetChars = 12_000,
): { slots: MemorySlot[]; usedChars: number; omitted: string[] } {
  const slots: MemorySlot[] = [];
  const omitted: string[] = [];
  let used = 0;

  for (const src of [...sources].sort((a, b) => b.score - a.score)) {
    const full = read(src.path);
    const cap = Math.min(src.maxChars, budgetChars - used);
    if (cap <= 0) {
      omitted.push(src.path);
      continue;
    }
    const text = full.length > cap ? full.slice(0, cap) : full;
    slots.push({ path: src.path, text, truncated: text.length < full.length });
    used += text.length;
  }

  return { slots, usedChars: used, omitted };
}

代入数字 ：3 条规则文件 + 1 份 MEMORY.md，单文件上限 4 000 字符、总预算 12 000 字符。命中 4 条时实际注入 ≈ 11 400 字符（约 3 000 token）， 超预算的第 5 条只留路径 由模型按需读——和 OpenClaw 的"分层预算"是同一个思路。

8. 三条可复用结论

1. 先做工具层，再谈摘要。 四家都在"进上下文之前"动手（截断 / 外部化 / 只留指针），摘要只是兜底。你的大数据（图表 JSON、明细表）就应该走这条。
2. 摘要必须结构化 + 保标识符 + 可校验。 OpenClaw 的 safeguard 模式（必留标题 / 待办 / 精确标识符 + 质量审计 + 不合格不写）是现成的模板。
3. 压缩要能"续算"。 PI 的 firstKeptEntryId 规则解决一个隐藏坑：被保留的原文下一轮该有机会重新进摘要，否则近端越滚越大。

9. 自建 harness 落地清单

工具栈速查：

10. 常见坑

11. 学习要点

• 压缩分三层： 工具层（最赚）→ 组装层 → 会话层（兜底） ，顺序不能颠倒。
• 铁律： 窗口是 RAM，磁盘是真相 ；压缩只改"下一轮看到什么"。
• 两条必须写进代码的不变式： 工具调用与结果配对 、 摘要续算边界 。
• 摘要要结构化并保留精确标识符；不合格宁可不写。
• 三家开源实现给出的默认值（keepRecentTokens 20 000、reserveTokens 20 000、单次摘要输入 ≤ 40 000 token）可以直接当起点。

12. 资料来源与可信度

13. 本文缩写