一次排障少烧 57% token：Headroom 先压缩 Agent 读到的日志

本文基于 GitHub 项目 headroomlabs-ai/headroom 的 README 整理。

摘要：给编码 Agent 装上本地压缩层，一场 SRE 事故排查的输入从 55,957 token 压到 24,340，同一个 FATAL 行一字不差地留了下来。项目今日新增 474 星，star 总数 77,289。

---

Agent 的成本结构里有个容易被忽略的部分：真正花在”思考”上的 token 并不多，大头是它读进去的东西——命令回显、日志、检索到的代码片段、RAG 召回块。Headroom 就是冲着这块来的。

项目今日登顶 Trendshift 当日榜单，GitHub 上累计 77,289 星、单日新增 474 星。它的定位一句话说清：在工具输出、日志、文件和对话历史进入 LLM 之前，先压缩一遍，答案不变，token 只留一小部分。

压缩在本地完成

这是 Headroom 最关键的设计取舍：压缩跑在你自己的机器上，prompt 和文件内容不会被送到任何地方去做压缩。对处理私有代码库的团队来说，这一条往往比压缩率更重要。

它提供四种接入形态，覆盖不同粒度：

• 库：Python 里 compress(messages)，TypeScript 里 await compress(messages, { model })，直接内联进应用。
• 代理：headroom proxy --port 8787，零代码改动，任何语言都能走。
• Agent 包装：headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|continue|goose|openhands|kimi|zcode，一条命令接管；headroom unwrap <tool> 可撤销。
• MCP server：暴露 headroom_compress、headroom_retrieve、headroom_stats 三个工具。

除此之外还有两个附加能力值得单独提：跨 Agent 记忆，Claude、Codex、Gemini、Grok 共用一个存储并自动去重；以及 headroom learn，它会挖掘失败的会话，把纠正写进 CLAUDE.local.md（默认，已 gitignore）、CLAUDE.md、AGENTS.md、GEMINI.md 或 GROK.md。

官方数字：省多少，代价是什么

README 给了一组可复现的基准（用 --seed 20260902 跑 benchmarks/index_proof_table.py，基于四类真实 MCP 服务输出格式）：

场景	压缩前	压缩后	节省
代码搜索（100 条结果）	17,199	13,597	21%
SRE 事故排查	55,957	24,340	57%
代码库探索	58,801	33,895	42%
GitHub issue 分诊	46,067	32,429	30%

规律很清楚：节省比例取决于载荷有多重复。重复的 JSON 数组和日志行在 bench_latency.py 里能压掉 90% 以上；散文和本身已经很紧凑的输出则几乎压不动。作者也直说，短对话、叙述性文本、高密度载荷的收益接近于零，长度低于 min_input_words 的块会原样返回。

开销方面，压缩本身耗时 0.21 ms（10K token 的 JSON 搜索结果，p50），10 万 token 时 1.4 ms——在 Agent 的延迟账上基本看不见。

准确率用 python -m headroom.evals suite --tier 1 测：GSM8K 从 0.870 到 0.870，零差异；TruthfulQA 从 0.530 到 0.560；SQuAD v2 在 19% 压缩下保持 97%，BFCL 在 32% 压缩下保持 97%。值得注意的是作者自己给 TruthfulQA 那条加了注解：N=100 时 ±0.03 落在置信区间内，所以这属于”没有可测差异”，而不是”有提升”。这种主动降调的写法在 README 里并不常见。

顺手把输出侧也削一刀

输入省了，输出还在烧钱——在 Opus 级模型上，输出 token 的单价是输入的 5 倍，而其中相当一部分是仪式性内容：”好的，让我来……”式的开场、把代码原封不动复述一遍、以及为读个文件而展开的长推理。

Headroom 从代理层做两件事：verbosity steering 在 system prompt 的末尾追加一句”简洁、不要复述上下文”的提示，这样 prompt cache 依然能命中；effort routing 在”只是工具返回后继续”的回合降低思考预算，遇到新问题或报错则恢复满额。两者同时作用于 Anthropic 的 /v1/messages 和 OpenAI 兼容的 /v1/chat/completions、/v1/responses。

输出侧的节省是反事实的——没人知道模型本来会写多少——所以 Headroom 只报区间估计：headroom output-savings 会给出类似”31.7%（95% CI 27.7%…35.7%）”并明确标注 [estimated]。想要实测数字，可以留 10% 的会话作为未施加干预的对照组（export HEADROOM_OUTPUT_HOLDOUT=0.1），仪表盘上的卡片就会从 estimated 变成 measured。

兼容性与适用边界

支持列表相当长：Claude Code、Codex、Grok CLI、Aider、Copilot CLI、VS Code Copilot、OpenClaw、OpenCode、Cline、Continue、Goose、OpenHands、Mistral Vibe、Oh My Pi、Kimi CLI、ZCode 均可 wrap，Cursor 需要手工配置代理地址，Cortex Code 只支持库模式。框架侧有 Anthropic/OpenAI SDK 包装、Vercel AI SDK 中间件、LiteLLM 回调、LangChain、Agno、ASGI 中间件等入口。

README 也写清了什么时候别用：只用单一厂商原生压缩、且不需要跨 Agent 记忆的；或者运行环境不允许启动本地进程的沙箱。压缩是可逆的，原文在配置的 TTL 内可以通过 CCR 回捞——这是它区别于”摘要式压缩”的地方：不是丢信息，而是把冗余挪到一边，需要时还能拿回来。

项目地址：https://github.com/headroomlabs-ai/headroom

🔁 重复度：低 — 未检索到 Headroom 的同项目既往报道，可正常发布