AI编程实践第14节：Headroom代理，帮我省下Token 的-隐形管家-

公众号名称：无处不在的技术

作者名称：爱海贼的无处不在

发布时间：2026-06-21 14:33

持续内容输出，点击蓝字关注我吧

前言

来看一段AI大模型对它的介绍

大家好，最近一段时间很多AI大模型厂商和工具都更改了计费模式，例如我最近使用的Github Copilot来说，从以前的按次数收费更改为了按积分token收费，适应这种新的计费模型有些不舒服，在这个过程中我们感觉Token消耗的非常快，自己的场景持续在消耗人民币。

同时我也相信很多人有过这样的瞬间——

凌晨一点，自己打开了Claude Code，准备让它帮你重构一段陈年老代码。你敲下回车，看着它一行行 Read、一次次 grep、一遍遍 Bash，屏幕上的 token 计数器像水龙头一样哗哗作响。

等到天亮，问题没解决，账单先涨了七十块。

自己又揉揉眼睛，叹了口气：「大模型胃口真大，不是我懒，是它太能’吃’了。」

是的，我们都知道：大模型是个胃口惊人的孩子。你给它一份 grep 出来的 500 条搜索结果，它要”嚼”500 条；你贴一份 65,000 token 的日志，它就老老实实地”咽”下 65,000 个。它从不挑食，但也从不告诉你——其实它只需要那 5% 的关键信息，剩下的 95%，是它陪你一起”被迫加班”的成本。

更心酸的是，第二天你换到 Cursor，它把所有上下文都忘了；你切到 Codex，又得从头解释一遍项目结构。AI 们彼此孤立、记忆短暂、各自烧钱，像一群刚入职的实习生，每天都在重复昨天的开场白。

在这样的一个背景的情况下，我们多数人常见的痛点如下：

🔥 痛点 1：成本失控

现象

某 AI 创业公司 3 月 LLM 账单 $2 万，4 月直接 $7 万，没人说得清为什么涨
根本原因

Agent 在长会话中累积工具输出、错误的重试、调试日志被无脑塞进上下文

🔥 痛点 2：合规焦虑

现象

金融/医疗/政企客户拒绝使用 SaaS 化压缩服务（担心数据出境）
根本原因

云端压缩 = 数据离开内网 = 合规违规

最近在Github开源网站上，一个叫 Headroom的小家伙，悄悄地站了出来。它没有惊天动地的宣言，没有让你”颠覆”工作流。它只说了一句话

「你只管写代码，剩下的 token，我帮你抠回来。」

截至2026年6月21日，目前项目42K，项目地址为：https://github.com/chopratejas/headroom![[raw/assets/e4bef3cbfeac910dc7a4a00e32dea8b6_MD5.png]]

Headroom 是一个位于 LLM 应用与上游 Provider 之间的上下文压缩层。Headroom 在企业 AI 资产组合中扮演AI 成本与上下文治理层的角色，位于业务应用与 LLM 厂商之间。

战略价值如下：

这个开源组件的目标用户是：

这是一篇关于 Headroom 的故事。它不仅仅是一个开源工具——它是一封写给所有”被 token 账单刺痛过”的开发者的情书。

在最近使用2个小时的日常工作过程中，帮我省下了1M的Token，感觉效果还可以：

Headroom基本用法

首先我们还是从5W2H的角度来来看这样的东西，首先看看：

What —— Headroom 是什么？

Headroom 是一个开源的 AI Agent 上下文压缩层（Context Compression Layer）。

说人话就是：它站在你的应用和大模型之间，把所有要”喂”给 LLM 的东西先嚼一嚼、抠掉冗余，再递过去。

它不改变你的代码，不修改你的提示词，更不会偷看你的隐私（它跑在你本地）。它只做一件事：让同样的答案，少花 60%～95% 的 token。

📦 它有 4 种”分身”：Python 库、TypeScript 库、HTTP 代理、MCP 服务
🧠 它内置 6 种压缩算法：SmartCrusher、CodeCompressor、Kompress-base、CacheAligner、CCR、IntelligentContext
🔁 它是可逆的：原数据从不丢，LLM 想要随时取回
🏠 它是本地优先的：你的数据，永远不离开你的机器
🪪 它的开源协议是 Apache 2.0，商用、二开、随便玩

核心能力如下：

Headroom 的核心业务能力可分为 5 大类、18 个子能力：

🎯 Why —— 为什么需要 Headroom？

来看一组真实的数据，这是 Headroom 在生产环境中实测的”减肥成绩单”：

但你可能会担心：「省了这么多，模型还能答对吗？」

Headroom 把标准 Benchmark 也跑了一遍：

准确率纹丝不动，甚至偶尔还能微微上涨——因为 Headroom 帮模型滤掉了噪声，它反而能更专注地”思考”。

👥 Who —— 谁需要 Headroom？

每天和 Claude Code / Cursor / Codex 厮混的程序员

—— 让 API 账单瘦身一半
正在搭建 Agent 应用的工程师

—— 让多轮对话不再被上下文窗口”卡脖子”
跑 SRE / 数据分析的同学

—— 把 6 万行日志压成 5 千行精华
正在做 RAG / 多 Agent 协作的团队

—— 让 Agent 之间的”交接班”瘦身 80%
企业内部用 LLM 的团队

—— 它跑在本地，数据合规无忧

📍 Where —— 在哪儿能用到 Headroom？

只要有 LLM 调用的地方，就有它的舞台：

⏰ When —— 什么时候该想起 Headroom？

🔥 你的工具调用动辄返回上万 token 的 JSON
🔥 你的 Agent 跑着跑着就 context_length_exceeded
🔥 你切换 AI 工具时不得不重新解释一遍项目
🔥 你的 API 账单月底像股票一样飘红
🔥 你想给 LLM 加”长期记忆”，但又怕引爆窗口

只要你心里冒出过任何一个上面的念头，就该试试 Headroom 了。

🛠️ How —— 怎么用 Headroom？

针对部署形态，总结4种如下：

方式1：执行Python命令的方式安装，个人倒不是推荐这种，这种感觉上手比较难：

这种模式下是属于本地代理（个人开发者）

相关命令如下：

# 第 1 步：使用Python环境安装+清华镜像地址
pip install "headroom-ai"  -i https://pypi.tuna.tsinghua.edu.cn/simple
或全量安装
pip install "headroom-ai[all]"  -i https://pypi.tuna.tsinghua.edu.cn/simple
# 第 2 步：挑一种方式让它上岗
headroom wrap claude
# 一键包裹 Claude Code
headroom proxy --port 8787
# 启代理，零代码改造
# 第 3 步：看看它帮你省了多少
headroom perf

方式二：Docker的形式安装，个人推荐使用这种共享代理（团队），这里我已经提前安装好了Docker的环境：

这里我使用的命令如下所示：

docker run -d \
--name headroom \
--restart unless-stopped \
-p 8787:8787 \
-e ANTHROPIC_TARGET_API_URL="https://api.minimaxi.com/anthropic" \
-e ANTHROPIC_API_KEY="xxxxxxxxx" \
-v headroom-data:/home/nonroot/.headroom \
ghcr.io/chopratejas/headroom:latest

针对怎么选择适合自己的部署方式，这里分享一个决策判断：

接下来，继续看看我个人的安装操作和使用，安装完成后，看看启动日志是否成功：

接下来，我们使用cc switch设置下这个新的AI模型地址：

接下来开始我们日常的测试或者工作，这里我发现可能对于一些常规性的人物不会触发压缩，当某些任务匹配了具备压缩业务性质的时候，就出现了压缩，我们可以访问浏览器看当前的监控数据，headroom部署后，会出现如下地址：

http://127.0.0.1:8787/dashboard

页面如下所示：

由于我测试的任务比较简单，很多接口没有触发压缩，当前目前看有一次节省了96K的token，如果未来我们的任务比较复杂，挂载了各种工具，可能会进行压缩整理。

针对我测试的这个现象，我通过ClaudeCode和headroom源码一起结合的方式，问了下AI，什么时候会触发压缩机制：

等待一会儿后，AI结合源码设计，给出了结果，可以作为后续参考的资料，这个资料可以在后续的过程中我们测试一下：

同时，AI告诉我们了几个 一定不会压缩的场景（最容易踩的坑），看看用的过程中再看看结果吧：

明白了这个事情后，我又让他来基于headroom的源码来整理架构设计文档，这个时候，可以从监控面板中，可以看到累计节省了306K的Token：

每次的对话请求，都省了一点点：

Headroom架构设计

Headroom 是一个位于 LLM 应用与上游 Provider 之间的上下文压缩层。核心图：

从语言的架构设计上，它采用了Python + Rust 混合架构：这种语言分工是刻意的设计：

🐍 Python —— 集成与编排层

负责所有需要”触碰 LLM 调用信封”的工作：

FastAPI Proxy 服务器
LLM Provider 适配（Anthropic / OpenAI / Gemini / Bedrock）
Provider 特定的 message block 处理
MCP 工具定义与 tool 注入
TOIN 遥测
CLI、Memory 系统、Learn 流程
Cache / Metrics / Cost 集成

🦀 Rust —— 高频数值路径

headroom-core 纯 Rust 库负责确定性、按字节运算的”硬数字”工作：

SmartCrusher 数组分析（analyzer / classifier / crushers / compaction）
日志 / 搜索 / diff 压缩器
内容检测（Magika + unidiff + 纯文本链）
Tokenizer 数学
Live-zone 压缩（Anthropic / OpenAI / Responses API）
Rust CCR 存储

Headroom 是一个经过精心设计的混合 Python + Rust 压缩层：Python 做编排（HTTP/Provider/MCP/CLI），Rust 做硬数字（数组分析/Token 数学）。

目前支持的压缩策略矩阵为：

业务边界规则：

接下来再看下这个项目的业务架构（BA）与应用架构（AA）两个维度，对 Headroom 进行系统化的企业级分析。

从业务架构中的端到端流程泳道图看：

从图上看应该给更好理解：

从headroom的应用架构角度上看Headroom 是一个横切关注点（Cross-Cutting Concern）中间件，而非独立的业务应用：

应用的边界包含的范围（In-Scope）

✅ LLM 请求 / 响应的转换与压缩
✅ 可逆压缩存储（CCR）
✅ 持久化记忆
✅ 跨 Agent 上下文共享
✅ 失败学习
✅ 成本与可观测性

不包含的范围（Out-of-Scope）

❌ LLM 模型训练 / 微调
❌ 业务应用本身的实现
❌ LLM Provider 替换（Headroom 不做多 Provider 路由选优）
❌ 用户身份认证 / 授权（应由企业 IAM 系统处理）
❌ 计费与结算（应由财务系统处理）

从应用架构的角度来看与外部系统的关系：

层次间的通信协议如下：

Headroom 能在哪些战场上发光：「5 个场景，告诉你它能做什么。」

🌃 场景一：凌晨的 SRE 救火

人物：小李，刚被 oncall 叫醒的 SRE

剧情：生产环境告警，他用 Claude Code 排查。

没有 Headroom：

Claude → grep nginx 日志 → 返回 65,694 tokens
→ 上下文炸了
→ 小李手动剪贴 → 三轮才发现根因 → 账单 $4.2

有了 Headroom：

Claude → grep nginx 日志 → Headroom 介入 →
压到 5,118 tokens →
SmartCrusher 自动保留所有 ERROR 和异常
→ Claude 一次定位 502 根因 → 账单 $0.4

小李伸了个懒腰，又躺回去睡了。

🔍 场景二：百万行代码库的”考古”

人物：阿强，新入职的后端工程师

剧情：要在 30 万行 Java 代码里找一个被多处调用的工具方法。

用 Cursor 普通搜索：78,502 tokens，上下文窗口告急

走 Headroom 代理：41,254 tokens，47% 节省，搜索结果 100% 保留关键命中

阿强笑了：“这下我能多问几个’为什么’了。”

🤝 场景三：多 Agent 团队作战

人物：一位正在搭建研究型 Agent 的 AI 工程师

剧情：Researcher Agent 调研 → Planner Agent 规划 → Coder Agent 编码

没有 Headroom：每个 Agent 都要把上下文完整传给下一个，token 像滚雪球

有了 Headroom（SharedContext）：

ctx.put("research_report", huge_report, agent="researcher")
# Planner 拿到的是 80% 压缩版
plan = planner.run(ctx.get("research_report"))
# Coder 也是
code = coder.run(ctx.get("research_report"), plan)

整条 pipeline 的 token 消耗，砍掉了三分之二。

接下来再看看Headroom 和其他类似竞品比，到底特别在哪里？

「它不是市场上唯一一个压缩工具，但可能是最’体贴’的那一个。」

这并不是要否定别人——RTK 是个出色的工具，事实上 Headroom 把它作为默认依赖一起发布。但 Headroom 想给你提供一种全栈式、可逆、本地优先、跨 Agent 共享的选择。

这个时候，有些人觉得headroom这个工具到底适不适合自己的环境呢？通过30 秒决策树来看下

「不要为了用而用——只在真正需要时才请它上门。」

简单决策法则（任选其一即可上车）：

✅ 你每天调用 LLM 工具超过 50 次
✅ 你跑过 context_length_exceeded 错误
✅ 你的工具输出动辄超过 200 tokens（一份 grep 结果、一次 API 响应、一段日志）
✅ 你同时使用 2 个以上 AI 助手（Claude + Cursor、Codex + Gemini…）
✅ 你公司有数据合规要求，不能用 SaaS 压缩服务

从技术架构上看headroom的技术选型也是非常值得借鉴的：

装上之后，怎么”眼见为实”地看到 Headroom 在工作？：「省钱不是口号，是数字。让你亲眼看到。」

📊 实时监控：4 个内置端点

启动代理后，Headroom 会自动暴露 4 个 HTTP 端点供你查询：

/health健康检查：curl http://localhost:8787/health/stats

实时统计快照：curl http://localhost:8787/stats/stats-history

历史滚动数据（按时/天/周/月）：curl http://localhost:8787/stats-history/metrics

Prometheus 格式指标：curl http://localhost:8787/metrics

🎛️ 命令行一键看板

不想写脚本？Headroom 提供一键命令：

headroom perf
# 跑一遍 benchmark，看看在你机器上能压缩到多少
headroom learn
# 看看从过去会话能学到什么（dry-run）
headroom learn --apply
# 应用学习结果，写入 CLAUDE.md

Headroom 也有”做不好”的地方——坦诚的限制清单：「最好在装它之前就知道：哪些场景它无能为力。」

它可以省你很多 token，但没有一个工具是万能的。下面是 Headroom 老老实实承认的局限：

🚫 它不会压缩这些内容

用户消息用户的意图必须 100% 保留，碰都不碰短消息（< 300 tokens）压缩开销大于收益，不划算源代码（默认）代码经常需要”原汁原味”，强压可能改变语义grep / 搜索结果已经是紧凑的结构化格式，进一步压缩收益微小图片按固定 token 成本计费（约 1,600 tokens），无法压缩系统提示词内容仅重排位置以稳定缓存前缀，内容不变

🐌 这些场景它收益较小

短对话（单轮问答）中位数 4.8%不必引入它，开销不值纯代码会话（读/写文件）0%它会让代码通过，但 IntelligentContext 仍能丢弃旧上下文单次请求无累积上下文< 10%等你累积多轮再用它纯文本（文章/文档）43%～46%（仅省钱，不省时间）适合成本敏感场景

接下来在分享下企业落地的一些建议：