在模型入口前压缩工具输出：Headroom v0.37.0 离线测试记录

项目地址：headroom

9 月 3 日核验时，仓库已有 68,507 stars，代码许可证为 Apache-2.0，最新稳定版是 v0.37.0。

代码 Agent 的上下文里，真正占空间的往往不是问题本身，而是代码搜索、测试日志和接口结果。一条异常藏在上百行重复输出里，模型需要先把整包读进去再找证据，慢且容易被噪声干扰。

Headroom 的做法很直接：工具输出进入模型之前，先按内容类型压缩；之后需要原文时，通过检索标识取回对应片段。

1 处理的不只是 token 成本

代码 Agent 常读取三类大块头内容：重复字段多的 JSON、成功项远多于异常项的日志、一次返回多个文件片段的代码搜索。

简单截断最危险，真正有用的报错往往在尾部。Headroom 先识别内容类型，再分别走结构化数据、代码或文本压缩路径。项目还提供本地缓存与按需取回机制，路径是：先让首轮上下文变轻，但不把暂时不读伪装成永久可丢。

2 安装与基础验证

固定 v0.37.0 做隔离安装。系统自带 Python 3.9 因新依赖版本不足未能跑通，切换到 Python 3.12 后官方包装成功，headroom --version 正确返回 0.37.0。

CLI 的 doctor、inspect、proxy、savings、wrap 等入口均存在。另有需要注意的一点：CLI 来自 Python 包，只安装同名的脚本语言 SDK 不会得到这个命令行工具。

随后跑了三组定向测试：离线证据保真、紧凑 JSON 路由、中文搜索压缩，共 9 项通过、0 失败，用时 0.75 秒。

3 四组真实样例的压缩结果

仓库自带四组金标数据，分别模拟内存溢出、支付异常、延迟异常和持续集成失败。共同点是正常记录占多数，真正能决定答案的异常只有少数几条。

用项目的纯离线压缩路径重放，文本体积从 9,203 字符降至 2,752 字符，四组分别减少 66.9%、72.9%、72.4%、68.3%，合计约 70.1%。四组预先标注的回答证据全部保留，关键证据召回率 100%。这只能证明固定样例通过门槛，不能外推为任何日志都不丢信息。

可逆取回是比压缩比例更关键的设计：第一轮不必吃下全部原文，发现细节不足时仍有回头路。

4 接入建议：从低风险输出开始旁路对比

第一批适合接入的是重复 JSON、长测试日志、大批代码搜索结果。这三类结构明确，且关键字段是否被误删容易人工判断。

不要直接追求 README 里的节省数字。上下文变短不意味着答案更准，不同模型、任务和代理配置都会改变最终效果。

一个可行的验证方式是旁路对比：同一批任务同时保留原始输出、压缩输出和正确答案，再比较节省率、关键证据召回与处理延迟。

本轮验证范围有限：没有调用真实模型、没有启动后台代理、没有改写本机 Agent 配置，因此不把结果写成完整生产验证。可以拿自己的 20 条输出做小样本：10 条长日志、10 条结构化结果，先标注每条答案必须保留的事实，再跑压缩。只有当更短、证据还在、延迟可接受三项同时成立，才值得接入日常 Agent；任何一项不稳定，都应先停在旁路模式。

结论

Headroom 值得上下文经常被工具输出塞满的技术团队试跑。适合能准备可复现样例、并愿意同时检查节省率和正确率的人。本轮只验证安装、CLI 与离线金标门槛，完整代理效果需要在各自任务上灰度确认。