Headroom

Headroom 是给 agent 发给模型的那部分流量做压缩的一层。它有三种形态——库，整个 API 就是 Python 或 TypeScript 里的一个 compress() 调用；FastAPI 代理，任何 OpenAI 兼容的客户端把地址指过来就行；以及一个 MCP server，对外提供 headroom_compress、headroom_retrieve 与 headroom_stats——再加一条包装命令，负责起代理并替十五种具名的编码 agent 配好。里面是一个 ContentRouter 判断每一块内容是什么，再把它交给唯一一个压缩器：数组型 JSON 记录交给 SmartCrusher，另有搜索压缩器、日志压缩器、diff 压缩器、HTML 抽取器、表格与配置压缩器、文本压缩器，以及一个按需开启、基于 ModernBERT、名叫 Kompress 的模型专门处理散文。最重的那几个跑在通过 PyO3 装载的 Rust 扩展里，Kompress 走 ONNX Runtime。只有最新的内容块会被压缩，更早的轮次逐字节原样转发，好让服务商的前缀缓存活下来；而每一次压缩都可逆——原文会写进本地存储，模型可以取回。

谁做的仓库属于 headroomlabs-ai——一个组织账号而不是个人账号：提交邮箱用的是 headroomlabs.ai 域名，README 除了开源内核之外还在卖带支持或全托管的部署。单一提交最多的是 chopratejas（Tejas Chopra），在抽样到的 3,000 次提交里占 1,234 次；其次是 JerrettDavis 的 373 次、abhay-codes07 的 169 次、gglucass 的 139 次与 rodboev 的 102 次，dependabot 另有 76 次。贡献者名单列了五十个账号，3,000 次提交里有 2,984 次关联到了 GitHub 账号。

1. 01

   一个九个月大的仓库和 74,192 个星，而材料里没有任何东西解释它

   仓库建于 2026-01-07，样本里最新一次提交是 2026-10-01；中间的样本收录了 3,000 次提交，而 pull request 的编号已经过了 #3896。2026-10-01 的 GitHub API 报告：74,192 个星、5,734 个 fork、219 个 watcher、529 个未关闭 issue、85 MB 仓库体积、Apache-2.0 许可。材料里没有任何东西解释这个数字是怎么来的。它能显示的是围着它的那一整套机器：一个文档站、一个 Discord、一个 PyPI 包、一个只发 TypeScript SDK 的 npm 包、一个发在 HuggingFace 上的模型、一个 Docker 镜像、一个挂着 Trendshift「#1 Repository Of The Day」徽章的 README、一份 533 KB 的 changelog，以及一段把两个节省百分比放在最前面、而不是先讲这工具干什么的简介。唯一跟星数摆在一起显得反常的计数是 watcher：219 个，对着 5,734 个 fork。

2. 02

   一个路由、每种内容一个压缩器，以及一批没有交代方法的节省数字

   三个入口喂同一条流水线：Python 与 TypeScript 的 compress()；一个 FastAPI 代理，按服务商分开的 handler 各自跑同一条流水线再转发；以及给 LangChain、Vercel AI SDK、Agno、Strands、LiteLLM 和 MCP 用的适配层。每个请求都跑一条很短的顺序流水线——一个按需开启的工具结果拦截器，一个只报告前缀漂移的 CacheAligner，然后是干了几乎全部活儿的 ContentRouter。它判断每一块的类型，分派给唯一一个压缩器，而项目自己的架构文档在每个压缩器旁边都印了一个「typical savings」：数组型 JSON 用 SmartCrusher 是 70–90%，搜索结果 80–95%，构建与测试日志 85–95%，diff 40–80%，HTML 70–90%，表格 60–90%，结构化配置 40–70%，纯文本 30–60%。这些数字是项目自述的；文档把它们标为「typical」而不是实测，并且没有给出任何语料、运行过程或方法。所有 transform 都 fail open：出错时内容原样返回，请求照样发出去。

3. 03

   Proof 那张表交代了方法，Accuracy 那张表带着作者自己写下的保留意见

   README 里有一节 Proof，由四个场景组成，而且跟上面那张表不同，它说明了数字怎么来的：真实的 MCP server 输出格式、服务商的分词器、仓库自带的 compress()，固定随机种子并离线，命令是 uv run python benchmarks/index_proof_table.py --seed 20260902。代码搜索 17,199 → 13,597 token（21%），SRE 事故排查 55,957 → 24,340（57%），代码库探索 58,801 → 33,895（42%），GitHub issue 分诊 46,067 → 32,429（30%）——每一个数字都是项目自述的。同一节还说：节省幅度跟着重复度走，重复的 JSON 数组和日志行在 benchmarks/bench_latency.py 里能过 90%，散文和本来就很密的内容几乎压不动，而在一个 10K token 的 JSON 搜索结果上压缩耗时的中位数是 0.21 ms。精度数字来自 python -m headroom.evals suite --tier 1，每个基准 N=100，然后这一节开始反驳自己那张表：「At N=100 a delta of ±0.03 falls inside the confidence interval, so TruthfulQA shows no detectable difference rather than an improvement.」

4. 04

   issue 区里记下来的保真度问题

   这套压缩有写在案上的失败，最清楚的一条是 #3880，标题是「Severity: silent data loss」：Kompress 会把单行 JSON 工具输出里的整条记录删掉，留下的仍是合法 JSON，「so no parser, log line or model can tell」。报告者描述了自己部署里的后果——一个 agent 反复且笃定地告诉用户某个数据集合不存在，而它存在——并点名当时唯一的缓解办法 HEADROOM_DISABLE_KOMPRESS=1，而那会把散文压缩也一起关掉。修法是凡是带记录结构的 JSON 都不再进那个散文模型，所有能走到它的路径都堵上；顺带把一段反复走同一批字节的扫描器换成一次线性遍历：在一个 58.8 KB、括号密集的块上，3.43 秒变成 0.011 秒，并用 4,000 个随机字符串跟旧实现逐一对过。另两条较小的报告是同一个主题：#3881 发现有一处代码拿词数去和 token 数比，于是一个原样未动的代码块看起来像省了 55%；#3893 发现外部压缩器返回的 passthrough 被当成了结果采纳，那一块于是未经压缩就发了出去。

5. 05

   作者自己的审计：错的思维模型，以及大约两万五千行要删掉

   一个叫 REALIGNMENT 的目录装了十四份文档、193 KB 的项目自我诊断，而执行摘要开门第一句就是指控：Headroom「is built on the wrong mental model」，也就是把压缩理解成「从对话历史里挑东西丢掉」。IntelligentContextManager 会把整个 messages 数组分词、给每条消息打分、一路删旧消息直到预算够用，而它被接进 Rust 代理时 frozen_message_count: 0 是硬编码的，「so every compression event drops messages from index 0, busting the Anthropic prompt cache for every customer that triggers it」。审计列出这个模型带来的五个顶级缓存杀手 bug、约一万行架构上的过度建设、被它称为虚假的 Bedrock 与 Vertex 对齐、算出来却从没注入到发出请求里的 CCR 标记，以及上游会看到的 X-Headroom-* 请求头泄漏。方案分九个阶段、四十个 pull request、大约十三周。同一批材料也记下了结果：context manager 那一级被删掉，打分相关的类从 Python 包里消失了，而 TypeScript SDK 仍然导出那些字段名——「wired to nothing」。

6. 06

   发版节奏、那套评审机器，以及靠录制夹具对齐的两种语言

   样本里的二十个 release 从 2026-06-16 的 v0.26.0 到 2026-09-26 的 v0.39.1，八月那一周就能看出节奏：20 日 0.36.0，21 日 0.36.1、0.36.2、0.36.3，22 日 0.36.4、0.36.5。按月提交数是 135、68、165、676、334、433、581、324、276、8。旁边是一整套评审机器：二十三个 workflow 文件，包括 28 KB 的 ci.yml、50 KB 的 release.yml，以及 eval.yml、rust.yml、security.yml 和一个 pr-health.yml，另有生成 changelog、同步版本、管 pull request 治理的脚本。机器人会在必填小节留空的 pull request 下面留言提醒；维护者会对着一个精确的 head commit 做评审，报出本地跑过多少个针对性测试，旁边是 ruff、mypy 与 diff 检查，并说明他已经授权了那些需要维护者放行的托管 workflow。两种语言靠录制下来的夹具保持一致——tests/parity/ 下 231 个文件，覆盖 cache aligner、CCR、代码感知压缩、内容检测、diff、Kompress、日志压缩、SmartCrusher、文本压缩、分词器以及 Codex 与 OpenAI 的契约——而共同作者尾注本身也是一段记录：1,168 条里约 466 条写的是一个 Claude 模型名，129 条写 Copilot。