Headroom 源码精读:给 Agent 压上下文,真正的约束是 prompt cache,不是 token 数

读 Headroom 的 Rust 核心并在 v0.41.0 上跑了 6 组实验:它为什么只压最后一条消息、SmartCrusher 怎么决定留几行、CCR 为什么像虚拟内存的缺页——以及一个实测发现:超过 256 字节的字符串会被整段换成哈希,连 FATAL 错误正文也不例外。

Headroom 是一个夹在 Agent 和模型 API 之间的压缩层:工具输出、日志、搜索结果,先过它一遍再发给模型。README 说”同样的答案,一小部分 token”,GitHub 星数 77,626(2026-10-24 用 gh api 查的)。

我读了它的 Rust 核心,又在 PyPI 版 headroom-ai 0.41.0 上跑了 6 组实验。最后留下三个结论:

  1. 它最重要的设计决定是”不压什么”:只动最新一条用户消息,历史一个字节都不碰。原因是 prompt cache 的计价方式,项目自己写过一份审计,承认第一版架构就是错在这里。
  2. 它的”有损”其实是换页:丢掉的内容按哈希存在本地,模型可以调工具取回。这和操作系统的虚拟内存是同一个结构,弱点也一样,都要看”缺页”能不能被触发。
  3. 我实测到一个坑:表格里超过 256 字节的字符串会被整段换成 <<ccr:哈希>>,FATAL 错误的正文也会被换掉,模型在 prompt 里看不到它。

名词速查

术语一句话解释
prompt cache(提示缓存)模型服务商把你上次发过的请求开头部分存起来,下次开头一字不差就按低价计费
缓存读 / 写倍率Anthropic 的标准价:命中缓存的 token 按原价 0.1 倍收,新写入缓存的按 1.25 倍收(5 分钟有效期)
tool_resultAgent 调用工具(读文件、查日志)后,工具返回给模型的那段内容,通常是上下文里最胖的部分
live zone(活区)Headroom 的术语:请求里唯一允许改写的区域,即最新一条用户消息里的内容
CCRCompress-Cache-Retrieve:压掉的原文存在本地,prompt 里留一个带哈希的标记,模型需要时调工具取回
SmartCrusherHeadroom 处理 JSON 数组的压缩器,决定留哪几行、怎么改写
Kneedle一种找曲线”拐点”的算法:曲线从陡变平的那个位置

先懂一件事:prompt cache 按”开头的字节”计价

后面所有设计都建立在这一点上,所以先用一个最小例子讲清楚。

一个 Agent 会话的第 20 轮,请求里有系统提示、工具定义、前 19 轮的对话和工具输出,一共 6 万 token。这 6 万 token 上一轮刚发过,服务商已经缓存了。这一轮新增的只是一个 1 万 token 的日志输出,接在最后。

计费时,服务商从请求开头逐字节比对缓存。开头这 6 万 token 一字不差,就按 0.1 倍价格收;新来的 1 万按 1.25 倍收,同时写进缓存供下一轮用。

关键是一处不同,后面全废。如果你在第 1 万 token 的位置改了一个字,从那里往后的 5 万 token 全部要按 1.25 倍重写。缓存只认前缀,不认”大部分一样”。

(推理侧为什么能这样复用,站内《把 LLM 推理栈当操作系统读一遍》讲过前缀缓存的引用计数机制,这里只需要记住计费规则。)

根本约束:项目自己承认第一版想错了

仓库里有个目录叫 REALIGNMENT/,是团队写给自己的架构审计。REALIGNMENT/00-overview.md 第一句话就是:

Headroom is built on the wrong mental model: “compression means choosing what to drop from conversation history.”

第一版的旗舰组件叫 IntelligentContextManager:把整个 messages 数组 tokenize,给每条消息打重要性分,从旧到新删,删到预算以内为止。直觉上很合理,旧消息最不重要,删旧的就对了。

审计里写,这个组件接进 Rust proxy 时 frozen_message_count 被硬编码成 0,于是”每一次压缩都从第 0 条消息开始删,对每个触发它的客户都打爆了 Anthropic 的 prompt cache”。审计给出的处置是删掉约 25K 行代码(Python 和 Rust 两边加起来),换成现在的 live zone 模型;live_zone.rs 开头的注释写着删消息的那套机制已经退役。

这笔账可以自己算一遍。用上一节的场景,比较两种压法:

方案做法本轮输入成本(基础价 token 数)
不压6 万缓存读 + 1 万新写18,500
A:只压新来的新来的 1 万压到 4 千11,000(−41%)
B:回头压历史把第 1 万位置的一个 2 万旧输出压到 5 千57,250(+209%)

方案 B 压掉的 token 更多(1.5 万),这一轮的账单却是原来的 3 倍,因为从第 1 万 token 往后的整个前缀都要重写。之后每轮能少读 1.5 万缓存 token,每轮只省 1,500,要再跑 25.8 轮才回本,而且前提是这 25.8 轮里缓存一直没过 5 分钟有效期。

# calc_cache.py —— 上表的验算,单位是"基础输入价下的 token 数"
READ, WRITE = 0.1, 1.25
P, T = 60_000, 10_000
turn = lambda cached, new: cached * READ + new * WRITE
base = turn(P, T)                                  # 18,500
live = turn(P, 4_000)                              # 11,000
hist = turn(10_000, (P - 10_000 - 15_000) + T)     # 57,250
print((hist - base) / (15_000 * READ))             # 25.8 轮回本

倍率我核过 Anthropic 官方定价页,和仓库里 headroom/cache_economics.py 写的一致(Anthropic 读 0.1、写 1.25;OpenAI 读 0.5、写 1.0)。

所以可以把根本约束写成一句可以被反驳的话:

Headroom 只压最新一条消息,是因为服务商的缓存按字节前缀计价、读价只有写价的 1/12.5。 反过来想:如果缓存不存在,或者读写同价,最划算的就是回头压历史里最大的旧输出,也就是它第一版的做法。OpenAI 的读价是 0.5 倍,这个约束在 OpenAI 上会弱很多(这是我按倍率推的,没有在 OpenAI 上测)。

这个约束在代码里落成了三条硬规矩:

规矩源码位置坏掉会怎样
只改活区:下界是 frozen_message_count,上界是最新一条用户消息crates/headroom-core/src/transforms/live_zone.rs:36-45改到已缓存的消息,当轮账单按上表变成 3 倍
活区外的字节原样拷贝,不做”解析→修改→再序列化”live_zone.rs:77:out = body[..block_start] || replacement || body[block_end..]重新序列化 JSON 会改空白和数字格式,前缀哈希就对不上了,虽然内容”没变”
CacheAligner 只检测、不改写:发现系统提示里有时间戳、UUID 只打警告headroom/transforms/cache_aligner.py:1-24旧版会改写系统提示,系统提示在整个前缀的最前面,改了它整个缓存都失效

还有一条容易漏的:取回工具 headroom_retrieve 现在每个请求都注册,不管这一轮有没有压缩(审计第 3 条错误假设)。工具定义也在缓存前缀里,工具列表一会儿多一个、一会儿少一个,缓存就跟着一会儿命中、一会儿失效。

库模式的 compress() 也留了同一个口子:CompressConfig.frozen_message_count(headroom/compress.py:123),默认 0,文档说明自己管理对话循环的调用方应该传上一轮的消息数。如果你用库模式又没传这个参数,就是第一版的错误又犯一次。

怎么压:先试无损,不够才挑行

活区里的内容先由 ContentRouter 判断类型(JSON、代码、日志、diff、纯文本),再分给对应的压缩器。工具输出里最常见的是 JSON 数组,归 SmartCrusher 管。它的主干在 crates/headroom-core/src/transforms/smart_crusher/crusher.rs:838-973,压缩成伪代码是这样:

# 伪代码,对应 crusher.rs 的 crush_array_with_source(),省略了观测、prose hook 等分支
def crush_array(items, query):
    k = compute_optimal_k(items)               # Kneedle 拐点,见下文
    if len(items) <= k:
        return items                            # 本来就不多,原样放行

    table = compact_to_csv_schema(items)        # 无损:键名只写一次,改成表格
    if 1 - len(table) / len(items_json) >= 0.15:
        return table                            # 省够 15% 就收工,一行不丢

    if lossless_only:
        return items                            # 严格无损模式:宁可不压

    keep = pick_rows(items, budget=k, query=query)   # 有损:挑行
    ccr_store.put(hash(items), items)           # 整份原文存起来
    return keep + [marker(hash, dropped=len(items) - len(keep))]

实验一:大多数 JSON 根本走不到”挑行”

我先按 README 的叙事造了数据:200 条服务日志,第 137 条是 FATAL,第 61 条延迟 9000ms,第 88 条用户名特殊。

$ python exp1.py      # headroom-ai 0.41.0, tokenizer = gpt-4o
tokens 12051 -> 5874  saved 6177 (51.3%)
transforms: ['router:protected:user_message', 'router:smart_crusher:0.38']

压掉 51%,200 行一行都没丢。输出长这样:

[200]{id:int,latency_ms:int,level:string,msg:string,service:string,ts:string,user:string}
0,50,INFO,request completed ok,checkout,2026-10-24T10:00:00Z,u1000
1,44,INFO,request completed ok,checkout,2026-10-24T10:00:01Z,u1001
...

这一半的节省全部来自键名去重:JSON 每一行都要重复写一遍 "latency_ms":,表格只在表头写一次。这就是 CSV 加 schema 头,数据库的列式存储也是同一个思路。挑行、拐点、异常检测这些逻辑,在这份数据上一个都没有运行。

这里我自己出过一次错。第一版实验脚本用 '"latency_ms":9000' in out 检查异常值有没有保留,结果报了 False,我还以为它把异常行丢了。其实是输出已经变成表格,里面是 61,9000,INFO,...,根本没有键名。检查压缩结果时别用原格式的字符串去匹配,换了表示法,你的断言就跟着失效了。

还有一个小细节:压完的 content 是一个 JSON 字符串字面量,开头带引号,换行是转义的 \n。这是为了让内容仍然是合法 JSON,代价我用 tiktoken 量了一下:转义版 5,833 token,解开后 5,831 token,只差 2 个。

留几行:Kneedle 找”新信息不再增长”的拐点

真正要挑行时,第一个问题是留几行。adaptive_sizer.rs:54 的 compute_optimal_k 不用固定比例。它逐行累加”到目前为止见过多少种不同的相邻词对(bigram)“,得到一条只增不减的曲线,然后找曲线从陡变平的地方。

可以把它想成翻一叠调查问卷:头几份每份都有新答案,翻到某一份之后几乎全是重复的,那一份就是拐点。

算法本身很短(adaptive_sizer.rs:111-148):横纵坐标都归一化到 0–1,算每个点”高出对角线多少”,取最高的那个。拿 10 行的小例子手算:

第 i 行累计不同 bigram纵坐标归一化横坐标归一化高出对角线
060.0000.000+0.000
1110.4170.111+0.306
2150.7500.222+0.528
3160.8330.333+0.500
4170.9170.444+0.472
6181.0000.667+0.333
9181.0001.000+0.000

(表里省略了第 5、7、8 行,它们的值都更小。)最大值在第 2 行(0.528),返回 2 + 1 = 3,即留 3 行(我用脚本逐行复现了 find_knee,结果一致)。真实流程在这之后还有三道修正:不同内容占比超过 70% 时设保底比例;乘一个 bias;再用 zlib 检查,如果留下的子集比全集好压很多(压缩率差超过 15%),说明丢了多样性,k 上调 20%(adaptive_sizer.rs:99-101)。

留哪几行:错误行可以突破预算

留哪几行由 planning.rs:169 的 plan_smart_sample 决定,按顺序收集五类候选:首尾锚点、结构离群行和带错误关键词的行、数值偏离均值超过 2σ 的行、变化点前后各一行、和用户问题相关的行。

候选太多、超出预算时,orchestration.rs:176-196 的排序很说明问题:错误行、离群行、异常值先全部放进去,再看剩多少名额给首 3 行和尾 2 行。也就是说,预算对错误行不起作用,100 条 FATAL 就留 100 条。这是一个明确的取舍:宁可压得少,也不丢错误。

但这个保证只在挑行这条路径上。下一节会看到另一条路径没有它。

CCR:这不是有损压缩,是换页

挑行丢掉的内容去了哪里?crusher.rs 的注释写得很直白:lossy 在这里的意思是”prompt 里放压缩视图,全量原文在 CCR 缓存里可取回”。

把它和操作系统的虚拟内存对一下,几乎一一对应:

虚拟内存Headroom CCR源码
物理内存里的页prompt 里保留的行—
换到磁盘的页存进本地 CompressionStore 的原文headroom/cache/compression_store.py:236,默认最多 1000 条,LRU 淘汰
页表项prompt 里的 <<ccr:6321a0f618e9 ...>> 标记SHA-256 的前 12 位十六进制
缺页中断模型调用 headroom_retrieve(hash)headroom/ccr/tool_injection.py:22
内核处理缺页、恢复执行proxy 截住这次工具调用,自己查表、把原文塞回去、再请求一次模型headroom/ccr/response_handler.py,最多 3 轮(:76)
换出页过期TTL 1800 秒后取不回compression_store.py:54
sequenceDiagram
    participant A as Agent 客户端
    participant H as Headroom proxy
    participant S as 本地 CCR 存储
    participant M as 模型 API
    A->>H: 请求(最后一条带 200 行工具输出)
    H->>S: 存原文,键 = 哈希
    H->>M: 压缩后的请求 + 标记 + headroom_retrieve 工具
    M-->>H: 调用 headroom_retrieve(哈希)
    H->>S: 按哈希查原文
    S-->>H: 原文
    H->>M: 把原文作为工具结果补上,再请求一次
    M-->>H: 最终回答
    H-->>A: 最终回答(客户端看不到中间的取回)

站内那篇操作系统类比的结论是”语义层的上下文管理对应的不是 GC,而是页面置换加有损压缩”。Headroom 往前走了一步:它让”有损”变成可撤销的,换出去的页还能换回来。

我验证了换回来的东西是否逐字节一致:从压缩结果里取出第 137 行的哈希 6321a0f618e9,去 get_compression_store().retrieve() 查,拿回的字符串和原始 msg 字段 == 比较为 True。

和操作系统不同的地方,正是 CCR 最脆弱的地方。 操作系统的缺页是硬件在访问时触发的,程序不用知道哪一页不在内存里。CCR 的缺页要靠模型自己决定去调工具,它得先知道自己缺了什么。如果标记写着类似”42 rows offloaded”的话,模型能判断出”可能有我要的东西”;如果标记什么线索都不给,模型就不会去取。

实测发现:256 字节以上的字符串整段被换成哈希

前面的实验里,键名占了大头,无损改写轻松省到 15% 以上。我想逼它走挑行路径,于是换了一份数据:200 行,每行只有 id、latency_ms 和一个 250–300 字节的长 msg,FATAL 写在第 137 行的 msg 开头。

结果它既没走无损表格、也没走挑行,走了第三条路:

$ python exp2.py
tokens 12381 -> 4472 (63.9% saved)
transforms: ['router:protected:user_message', 'router:smart_crusher:0.11']

[200]{id:int,latency_ms:int,msg:string}
0,54,<<ccr:7410edced8af,string,277B>>
...
137,55,<<ccr:6321a0f618e9,string,276B>>

200 行都在,但 199 个 msg 都变成了哈希(另一行只有 253 字节)。FATAL payment gateway connection refused 这串字在整个 prompt 里一次都没出现。 模型看到的第 137 行是”55 毫秒,内容见哈希”,和其他 198 行没有任何区别。它要想发现这次故障,只能把 199 个哈希逐个取回。

原因在 crates/headroom-core/src/transforms/smart_crusher/compaction/classifier.rs:130:字符串长度超过 opaque_min_bytes(默认 256,classifier.rs:76)就被归为”不透明大块”,然后检查是不是 base64、是不是 HTML,都不是也照样归为 LongString 卸载。我在整个 compaction/ 目录里搜 error、keyword、fatal,零命中。上一节说的”错误行可以突破预算”那条保证,在这条路径上不存在。

为了确认确实是 256 这个阈值,我只改一个变量做了边界实验:199 行都是短 msg,只把 FATAL 那行的 msg 长度从 200 调到 1000 字节:

$ python exp3.py
msg= 200B  saved 63.4%  'payment gateway' visible=True   row137=137,48,FATAL,FATAL payment gateway connection refused; xxx
msg= 256B  saved 63.3%  'payment gateway' visible=True   row137=137,42,FATAL,FATAL payment gateway connection refused; xxx
msg= 257B  saved 63.6%  'payment gateway' visible=False  row137=137,45,FATAL,<<ccr:6bf5fb297142,string,257B>>
msg= 300B  saved 63.6%  'payment gateway' visible=False  row137=137,46,FATAL,<<ccr:0d3cd3b15c15,string,300B>>
msg=1000B  saved 64.2%  'payment gateway' visible=False  row137=137,44,FATAL,<<ccr:de129ba2c4fb,string,1000B>>

256 字节可见,257 字节消失。还有一点要说清楚:这组数据里 level 是一个独立的短字段,所以 FATAL 这个级别标签一直可见,模型至少知道第 137 行出了事、值得取回。实验二没有 level 字段,错误只写在长字符串里,模型就完全没有线索。问题严不严重,取决于你的工具把错误信号放在哪个字段里。

压缩率也说明了它为什么这样设计:实验三里 FATAL 那行藏不藏,压缩率都在 63–64%,因为节省主要来自其他 199 行;实验二里那 199 个长字符串就是全部的节省。换成只允许可证明无损的 mode="agent" 再跑实验二:

$ python exp6.py
mode=None   12369->4460 (63.9% saved)  FATAL visible=False  markers=199
mode=agent  12369->12369 (0.0% saved)  FATAL visible=True   markers=0  lossless=True

在这份数据上,64% 的节省全部来自”把内容藏起来”,不藏就一分不省。这不是 bug 和正确行为的区别,是两种立场的取舍。我的判断是:默认值把这个取舍偏向了省 token,而 README 首页的演示(“FATAL line survives”)给人的印象是相反的。

软处我列一下:

  • 以上都是库模式 compress() 的实测。proxy 模式(headroom wrap claude 实际走的路)我只读了代码、没跑:live_zone.rs:568 用 SmartCrusherConfig::default() 构造 SmartCrusher,默认 enable_ccr_marker: true(config.rs:154),而 opaque_markers_enabled() 就取这个值,所以我推断行为相同。
  • 我在上游 issue 里搜了几组关键词,没找到讲这件事的;最接近的是 #1091(已关闭),讲的是关掉 marker 开关后长字符串仍被卸载,属于配置不生效,不是错误信号被藏。
  • 我没有让真模型面对这种 prompt 测”它会不会主动取回”。这是最该补的实验,下文最后一节会讲怎么做。

README 的延迟数字测的是缓存命中

README 写压缩耗时”远低于 1 毫秒,10K token 的 JSON p50 0.21 ms”。我测的结果是这样(M5 Pro,每组 30 次取中位数):

数据同一份 payload 重复压每次改一个字段
200 行短记录0.61 ms6.13 ms
200 行长 msg(实验二数据)1.72 ms24.09 ms

差了 10–14 倍。原因是 content_router.py:1561 有一个按内容哈希索引的结果缓存(默认 TTL 30 分钟),同样的内容第二次进来直接返回上次的结果。再看 README 数字的来源 benchmarks/bench_latency.py:715-726:先用同一份 messages 预热 3 次,再用同一份 messages 测 20 次,所以测量轮次大概率都是缓存命中。我想直接跑这个 benchmark 对照,但仓库 HEAD 的 Python 源码和 PyPI 0.41.0 的 Rust 扩展版本对不上,在 content_router.py:2966 报错,所以这一条是读代码得出的推断。

公平地说,24 ms 放在一次动辄几秒的模型调用前面,仍然可以忽略。我要指出的是这个数字测的东西:Agent 每一轮新来的工具输出都是新内容,碰不上这个缓存,你实际付的是右列。另外,每个进程第一次调用要加载检测器,我在实验一里单次观察到 7.3 秒冷启动,proxy 常驻时只付一次。

一个值得补的实验

上面最大的空白是:模型看到一屏 <<ccr:...>> 时,到底会不会去取?这个实验可以这样做:

  • 数据:实验二那份 200 行(FATAL 藏在第 137 行长 msg 里),再加一份对照,把 FATAL 挪进独立的 level 字段。
  • 步骤:起 headroom proxy --port 8787,用 Anthropic SDK 发”checkout 为什么失败”,两份数据各跑 10 次。
  • 记录:proxy 日志里 headroom_retrieve 的调用次数;最终回答里有没有提到 payment gateway;单次请求的总 token(取回会多一轮完整请求)。
  • 成本:API 费用不到 1 美元,半小时左右。

我预期对照组(有 level 字段)会取回,实验组多数不会,但这是猜测。做出来之后我会补到这篇。

小结

  • 根本约束:服务商按前缀字节缓存、读价是写价的 1/12.5,所以压缩只能发生在最新一条消息里。回头压历史的账单是不压的 3 倍,要 25.8 轮才回本,项目第一版就是在这里栽的。
  • 两层机制:先无损(键名去重成表格,常见 JSON 能省一半,一行不丢),不够再挑行(Kneedle 定数量、错误行可突破预算),丢掉的存进 CCR 可取回。
  • 崩点:CCR 的缺页要模型自己触发。256 字节以上的字符串会被无条件换成哈希,没有错误关键词检查,所以错误信号只在长字段里时,模型看不到它。
  • 可带走的动作:用库模式就传 frozen_message_count;检查你的工具输出把错误级别放在哪个字段;看压缩延迟时换着 payload 测。

通俗总结

把模型的上下文想象成一张办公桌,服务商的缓存是”桌上摆放没动过就打一折”的规矩。

Headroom 干的事,是在新文件放上桌之前先整理一遍。它不碰桌上已有的东西,因为挪动一样,后面所有东西都要按原价重新算钱。整理新文件时,它先试着把表格里重复的表头去掉,这一步什么都不丢;不够的话,就把不太重要的页收进抽屉,桌上留一张写着抽屉编号的便签,模型需要时可以喊人去拿。

问题在于便签上写什么。如果便签写着”这里有 42 页,含错误报告”,模型会去拿;如果便签只写一个编号,模型根本不知道抽屉里有一份事故报告。Headroom 现在会把所有超过 256 字节的段落都换成只写编号的便签,不管里面是不是事故报告。

能复述给同事的一句话:Headroom 只压最新的内容,是为了不打爆缓存;它压掉的东西都能取回,但模型得先知道该去取。

如果你正在用 headroom wrap,花 5 分钟打开最近一次的工具输出,看看错误信息是写在一个短的 level/status 字段里,还是只出现在一段很长的 message 里。如果是后者,这篇第四节的情况就会发生在你身上。

参考来源

工程实践与源码(均为仓库 commit e995eb9)

  • headroomlabs-ai/headroom:REALIGNMENT/00-overview.md(架构审计)、crates/headroom-core/src/transforms/live_zone.rs、smart_crusher/{crusher,planning,orchestration,config}.rs、smart_crusher/compaction/classifier.rs、adaptive_sizer.rs、headroom/ccr/、headroom/cache/compression_store.py、benchmarks/bench_latency.py
  • Anthropic Prompt Caching 文档:缓存写 1.25×、读 0.1× 的出处
  • 上游 issue #1091:关闭 CCR marker 后长字符串仍被卸载(已修复)

算法

  • Satopää, Albrecht, Irwin, Raghavan, Finding a “Kneedle” in a Haystack: Detecting Knee Points in System Behavior, ICDCS Workshops 2011, doi:10.1109/ICDCSW.2011.20:find_knee 的原始算法(源码没有引用它,是我对上的)

站内相关