AI agent 的 context 成本问题，Headroom从工程层面认真解决了。

Headroom是一个 context 压缩层，插在你的应用和 LLM provider 之间，压缩率 60-95%，精度基本不变。

核心思路：大部分 token 浪费在结构性冗余上，而不是信息本身。

工具输出、日志、RAG 结果里，真正有信息量的内容是少数。Headroom 的任务是在不丢语义的前提下把它们变小。

1. 三阶段 pipeline
请求进来之后依次经过：
1）CacheAligner：把 system prompt 里的动态内容（日期、session token、UUID）提取出来放到末尾，让 static prefix 保持稳定。这是为了让 Anthropic 的 cache_control 和 OpenAI 的 prefix caching 真正命中。否则每次 prompt 里有个日期变化，cache 就全失效了。开销：亚毫秒级。

2）ContentRouter + SmartCrusher：ContentRouter 用 Magika（Google 开源的 ML 内容识别模型）自动判断内容类型，再路由到对应的压缩器：
- JSON 数组 → SmartCrusher（字段级统计分析 + Kneedle 算法选代表子集）
- 源代码 → CodeAwareCompressor（tree-sitter AST 级，只保留函数签名、import、类型定义，压缩函数体和注释）
- 搜索结果 → SearchCompressor
- 构建/测试日志 → LogCompressor（保留 error、stack trace，压缩重复模式）
- Diff → DiffCompressor
- HTML → 基于 trafilatura 的 article 提取

SmartCrusher 的关键设计：item 保留策略是 30% 头部（schema 代表）+ 15% 尾部（最近数据）+ 55% 按重要性分数。错误类 item 无条件保留，不受 token budget 限制。

3）IntelligentContext：对消息列表按六个维度打分（recency、semantic similarity、TOIN importance、error indicators、forward references、token density），低分的先丢。被丢掉的内容存进 CCR，不是真的删了。

2. CCR：可逆压缩
这是 Headroom 和其他压缩工具最大的区别。

压缩后的原始内容存在本地 SQLite，hash 索引。如果 LLM 后续需要完整数据，可以调用 headroom_retrieve("hash") 取回。
- 压缩前：1000 条 JSON items
- 压缩后：15 条（代表性子集）
- 存储：原始 1000 条在本地 SQLite
- 恢复：LLM 调用 ccr_retrieve → 取回完整 1000 条

3. TOIN：工具输出智能网络
Headroom 会跨 session 学习每个工具的压缩模式。哪些字段被 LLM 真正用到、哪些 item 被检索过、哪种压缩策略效果好——这些统计数据会反过来优化 SmartCrusher 和 IntelligentContext 的权重。冷启动时用统计启发式，用多了变成经验驱动。

4. KV cache 优化有多值钱
CacheAligner 解决的问题比看起来重要。真实场景里，同一个 Claude Code session 发几十次请求，每次 system prompt 里有个时间戳，cache 全部 miss。Anthropic 的 cache_control 可以节省最多 90% 的缓存 token 成本，但前提是 prefix 稳定。

压缩省 token 是一笔账，让 cache 真正命中又是另一笔账，Headroom 两笔都算了。

访问：github.com/chopratejas/headroom

#HOW I AI# #程序员#