AI agent 的上下文压缩层——same answers, fraction of the tokens
更新于 2026-09-01 · 数据来源：GitHub API（采集于 2026-09-01）
← 返回汇总上下文窗口是账单，Headroom 是对账单动刀的人
在工具输出、日志、RAG 块、文件、对话历史到达 LLM 之前压缩它们：JSON 省 60-95%、编码 agent 省 15-20%，答案质量在标准基准上不掉（GSM8K ±0、BFCL 97%）。库 / 代理 / MCP / agent wrap / 内联五种接入，本地优先、可逆（原文缓存按需取回）。适合一切「上下文成本开始疼」的 agent 团队——编码代理、RAG 应用、SRE 机器人。
2026-01-07 创建 · 昨日仍在推送 · v0.37.0（月级多版）· PyPI + npm 双包 · 自研 Kompress-v2-base 模型上 HuggingFace · CI + codecov + 可复现 evals（python -m headroom.evals）
一次编码 agent 会话动辄吞几十万 token——其中大头是工具输出：文件内容、命令输出、搜索结果、堆栈日志。这些内容大量冗余，但没人管它进窗口前的样子。
Opus 级模型输出单价是输入的 5 倍——而输出里满是废话：「Great, let me…」开场白、复述你刚给它看的代码、读个文件也要深度思考一遍。浪费是双向的。
「砍掉一半上下文」谁都会，但砍什么不伤答案是技术活——需要按内容类型分治：JSON 有 JSON 的压法，AST 有 AST 的压法，散文要语义压缩。
headroom_retrieve 工具，发现信息不够时自己按需取回原始片段reasoning_effort，Anthropic 走 thinking.budget_tokens，两边同一个 clamp-only 不变量人不会「说」自己想要多简洁——人会用行为「展示」（打断长回复、没读完就翻页）。headroom learn --verbosity 读历史会话自动定档；还能挖掘失败会话把修正写进 CLAUDE.local.md。
代理的 runtime 配置支持热同步（POST /admin/runtime-env）——改开关不用重启、不丢缓存。
| 工作负载 | 前 → 后 | 省 |
|---|---|---|
| 代码搜索（100 结果） | 17,765 → 1,408 | 92% |
| SRE 事故调试 | 65,694 → 5,118 | 92% |
| GitHub issue 分诊 | 54,174 → 14,761 | 73% |
| 代码库探索 | 78,502 → 41,254 | 47% |
| 基准 | 类别 | 基线 vs 压缩后 |
|---|---|---|
| GSM8K | 数学 | 0.870 → 0.870（±0.000） |
| TruthfulQA | 事实 | 0.530 → 0.560（+0.03） |
| SQuAD v2 | 问答 | 97% 精度 · 压缩 19% |
| BFCL | 工具调用 | 97% 精度 · 压缩 32% |
全部可复现：python -m headroom.evals suite --tier 1——敢把方法学放文档里的压缩工具，这个品类里不多见。
| 方式 | 一句话 | 适合 |
|---|---|---|
| Agent wrap | headroom wrap claude|codex|grok|copilot|cursor|aider|opencode|cline|…（16 种）一键包住，unwrap 撤销 | 个人编码 agent 立刻省钱 |
| Proxy | headroom proxy --port 8787，任何语言零改码 | 存量应用 / 任意技术栈 |
| Library | Python compress(messages) / TS SDK（npm） | 自研 agent 深度集成 |
| MCP server | headroom_compress / retrieve / stats 三工具 | 任意 MCP 客户端 |
| deploy | headroom deploy 交钥匙本地部署 + agent 配置 | 团队快速起步 |
wrap 会顺带装 Serena（语义代码导航，注册在用户作用域，--code-memory none 可跳过）。自检体系完整：doctor（健康检查）· perf（性能）· dashboard（实时节省面板）。
$ uv tool install --python 3.13 "headroom-ai[all]" # 或 pip install "headroom-ai[all]" $ headroom wrap claude # 包住你的编码 agent（本地代理 + Serena） $ headroom doctor # 确认路由在工作 $ headroom dashboard # 实时节省面板（代理运行时） # 输出侧（默认关）： $ export HEADROOM_OUTPUT_SHAPER=1 && headroom proxy --port 8787
Playground 复刻 ContentRouter + 分治压缩的语义：粘贴工具输出/日志/JSON（或用预设），看引擎判型分流——JSON 列式化压缩（键值全保留）、日志重复折叠（×N）、散文紧凑化——实时显示 token 前后对比与压缩率。
纯前端实现，零网络依赖 · 判型 7 类 / JSON 信息保全 / 折叠单调性 均经真值表对拍验证
「上下文工程」正在成为 agent 技术栈的独立层——窗口成本随 agent 自主化只增不减，而模型厂商自己不会替你压工具输出。Headroom 用 8 个月 68k stars 确立了品类心智：分治压缩 + 可逆回收 + 双侧省钱 + 五路接入的完整度目前无对手。天花板在于模型厂商若原生内置类似能力（长上下文降价 + 原生压缩），中间层价值会被挤压——但在那之前，它是这个赛道最硬的资产。