Headroom 深读：在进模型之前先压掉一半 token

压缩点选在模型上游，而不是模型内部

Headroom 做的事情，用一句话说就是：在内容送进模型之前，先把不需要的 token 压掉。

它处理的不是模型权重，也不是推理过程，而是输入侧的数据。tool 输出、日志、文件、RAG chunk，这些东西在真实的 agent 工作流里经常非常冗长。一个 coding agent 读一个报错日志，可能日志本身两千 token，真正有用的就三行。Headroom 试图在这个环节做文章。

这个位置的选择很关键。模型内部的压缩，比如量化、蒸馏，是模型厂商的事。模型外部的压缩，比如 prompt 缓存、上下文修剪，又往往依赖具体框架。Headroom 卡在数据刚产生、还没被拼进 prompt 的那一步。

这样做的好处是：它跟模型无关，跟框架也基本无关。任何要喂给 LLM 的内容，理论上都可以先过它一遍。代价是：它必须保证压缩后的内容不丢失关键信息。一旦压错，模型给出的答案就会变。仓库自述里写的是“same answers”，这是它给自己定的及格线。

为什么是 20% 和 60-95% 两个数

README 里给了两组数字：coding agent 场景减少 20% token，JSON 场景减少 60-95% token。这两个数字放在一起，能看出它的定位。

coding agent 的 tool 输出，很多是代码 diff、文件内容、命令回显。这些内容结构松散，但每一行都可能重要。压缩空间天然就小。20% 意味着它只能做比较保守的处理：去掉空行、重复的格式符号、不改变语义的冗余。

JSON 场景完全不同。JSON 有明确的结构，字段名重复率极高。一个一百条记录的数组，字段名可能出现一百次。把字段名映射成短标识，或者直接抽取模型需要的字段，token 能大幅下降。60-95% 这个区间，说明它在 JSON 上做的是结构化压缩，不只是文本层面的删减。

这两个数字也划出了它的能力边界。它对结构化数据更有效，对非结构化文本只能做轻度处理。这跟它选择的压缩策略有关。文档没有说明具体算法，但从数字推断，它不是靠模型来压缩，而是靠规则或轻量模型。用模型压缩成本太高，延迟也不可控。

library、proxy、MCP server 三种接入的代价

Headroom 提供三种接入方式：library、proxy、MCP server。这三种方式对应三种不同的集成深度，也对应三种不同的运维负担。

library 方式最直接。开发者在自己的 Python 代码里调用它的函数，把数据压完再拼 prompt。好处是可控性最强，什么时候压、压什么，完全由代码决定。代价是要改代码。已有的 agent 项目如果已经写死了 prompt 拼装逻辑，接 library 等于要重构一部分数据流。

proxy 方式更像一个中间层。它挡在 agent 和 LLM 之间，请求先到 proxy，proxy 压缩完再转发给模型。好处是不用改业务代码，agent 只需要把 endpoint 指到 proxy。代价是多一跳网络，而且 proxy 要能正确识别哪些字段需要压缩、哪些不能动。这需要配置，配置错了就是静默的数据损坏。

MCP server 方式最有意思。MCP 是 Model Context Protocol，这两年逐渐成为 agent 工具调用的通用协议。把 Headroom 做成 MCP server，意味着它可以直接挂在支持 MCP 的 agent 上。agent 调用 tool 时，tool 输出先经过 Headroom 再返回给模型。好处是跟 agent 框架解耦，只要框架支持 MCP 就能用。代价是它只能处理走 MCP 通道的数据，不走 MCP 的日志、文件、RAG chunk 它碰不到。

三种方式没有哪个绝对更好。它反映的是同一个核心能力在不同架构位置上的投影。

它和 prompt 缓存、上下文修剪不是同一件事

要理解 Headroom 的位置，得把它跟另外两种常见的 token 优化手段分开。

prompt 缓存解决的是重复请求的问题。同样的 system prompt 发一百次，缓存能省掉九十次的重复计算。但它不改变单次请求的 token 量。Headroom 解决的是单次请求里的冗余。两者可以叠加，但解决的不是一个问题。

上下文修剪解决的是对话变长的问题。聊了五十轮，前三十轮的内容可能已经不重要了，剪掉它们省 token。但修剪的粒度是“整段要不要保留”。Headroom 的粒度更细，它在一段内容内部做压缩。一个 tool 输出可能整体都要保留，但里面 70% 的字符是冗余的。这个场景上下文修剪处理不了。

还有一个更朴素的做法：让模型自己压缩。把长内容丢给一个便宜的模型，让它总结成短内容，再喂给主模型。这个方案的问题是延迟和成本。每次压缩都是一次额外的模型调用。Headroom 的定位显然是想避开这个成本，用更轻量的方式完成压缩。但轻量意味着压缩能力有上限。这是一个明确的取舍。

边界与判断

Headroom 解决的是一个真实存在的问题：agent 工作流里，大量 token 消耗在模型并不真正需要的内容上。它把压缩点放在模型上游，用 library、proxy、MCP server 三种方式覆盖不同的集成场景。这个思路是成立的。

但它的效果高度依赖数据类型。JSON 能压 60-95%，coding agent 只能压 20%。如果你主要跑 JSON 密集的 workflow，它的价值很直接。如果你的场景是代码和自然语言混杂，省下的 token 可能不足以抵消接入成本。

还有一点要留意：压缩必然带来信息丢失的风险。仓库说“same answers”，但这是结果层面的承诺，不是机制层面的保证。文档没有说明它如何验证压缩不改变答案。在生产环境用它，需要自己建立评估，不能只看 token 数字。

我的判断是：Headroom 值得在 JSON 密集或 tool 输出冗长的 agent 项目里试用，但不要指望它在所有场景都拿到 60% 以上的节省。先拿自己的真实数据测一轮，看 token 省了多少、答案有没有变化，再决定要不要接进主流程。Star 数高只能说明关注度，不能替代你自己的评估。