10 分钟接入指南:给主流编程 Agent 的上下文装上压缩层,不碰一行业务代码
10 分钟接入指南:给主流编程 Agent 的上下文装上压缩层,不碰一行业务代码
用 Claude Code 或 Codex 排查一个线上问题时,你大概经历过这样的场景:Agent 先是 grep 一遍代码,再 cat 几个文件,跑一轮测试,几百条日志哗啦啦全塞进上下文——几万 token 就这么烧掉了。GitHub Trending 上爆火的 Headroom 正是冲着这个痛点来的:在内容到达 LLM 之前,先把工具输出、日志、RAG 分块压缩一遍,号称"同样的答案,1/5 到 1/20 的 token"。
但"省 token"这三个字很容易让人上头。本文不吹数字,只讲怎么落地:两种接入姿势怎么选、10 分钟怎么跑通代理模式、一次真实代码搜索任务前后 token 对比是多少,以及社区实测中暴露的误区和边界。全程不碰一行业务代码。
为什么编程 Agent 的上下文会"通胀"
先看一个数字:一段 10,144 token 的日志堆,经过 Headroom 压缩后只剩 1,260 token,而日志末尾那条 FATAL 错误被逐字节保留——这是仓库首页演示图展示的效果:
编程 Agent 的上下文膨胀主要来自三类内容:工具输出(搜索、数据库查询、API 响应)、构建与测试日志、重复度极高的 JSON 数组(文件路径列表、错误堆栈集合)。这些内容的共性是大规模重复 + 低信息密度。Headroom 的思路不是截断上下文,而是对每类内容做"结构感知"的压缩:JSON 数组按字段方差做统计抽样、日志按行去重、源码交给 AST 感知的 CodeCompressor,压缩结果可逆(CCR 机制把原文缓存到本地,模型需要时可以调用 headroom_retrieve 取回)。处理全部在本地完成,没有任何 prompt 或文件内容被送到第三方。
两种接入姿势速览:本地代理 vs 库调用
Headroom 的接入方式在 README.md 里写得很清楚,核心就两种:
| 维度 | 代理模式(Proxy) | 库调用(Library) |
|---|---|---|
| 改动量 | 零代码改动,只切环境变量 | 改一行调用代码 |
| 适用场景 | Claude Code / Codex / Cursor 等现成 Agent | 自己写的应用、LangChain / LiteLLM / Vercel AI SDK 等框架 |
| 接入方式 | headroom proxy --port 8787 或 headroom wrap <tool> |
Python from headroom import compress,TypeScript import { compress } from 'headroom-ai' |
| 语言无关性 | 任意 OpenAI / Anthropic 兼容客户端 | 需引入 Python 或 TS SDK |
代理模式适合谁:主力是 Claude Code、Codex 这类 CLI Agent,想"零侵入"接入的人。headroom wrap claude 一条命令会帮你启动本地代理、注册 MCP 服务器并直接拉起 Agent;headroom unwrap claude 一键还原配置。它同时支持 claude、codex、grok、copilot、cursor、aider、opencode、cline、goose、openhands 等十余种工具(支持列表见 headroom/cli/wrap.py 模块顶部的用法注释)。
库调用适合谁:你自己写 Agent 管道、或用 LangChain / Agno / Strands 等框架组装链路的人。压缩发生在进程内,compress(messages) 返回压缩后的消息和 token 统计,直接喂给下游 LLM 调用即可。
代理方式 10 分钟落地:环境变量、端点切换、验证压缩生效
代理模式全程三步,第一分钟装环境:
uv tool install --python 3.13 "headroom-ai[all]" # 或者 pip install "headroom-ai[all]"
第二步起代理:
headroom proxy --port 8787
第三步把 Agent 的请求端点切到本地代理。对 Anthropic 系(Claude Code)设置:
ANTHROPIC_BASE_URL=http://localhost:8787 claude
对 OpenAI 兼容系(Codex 等)设置:
OPENAI_BASE_URL=http://localhost:8787/v1 your-app
这两条命令不是文档里的演示文案,而是 headroom/cli/proxy.py 中 proxy 命令 docstring 里写明的标准用法。更省事的是直接 headroom wrap claude:它会检测 claude 是否在 PATH 中、自动启动代理、设置 ANTHROPIC_BASE_URL 路由、注册 headroom_retrieve MCP 工具,然后把参数原样透传给 Claude Code(比如 headroom wrap claude --resume <id>)。对于 Codex,wrap 除了设置 OPENAI_BASE_URL,还会向 Codex 配置文件注入 provider,确保 WebSocket 流量也走代理(Codex 默认会忽略 OPENAI_BASE_URL,见 headroom/cli/wrap.py 中的 codex 命令实现)。
怎么确认压缩真的生效了,三个手段任选:
curl http://localhost:8787/stats
# {"requests_total": 42, "tokens_saved_total": 125000, ...}
headroom doctor # 健康检查,确认路由与压缩链路正常
headroom dashboard # 实时看板,可视化每次请求的节省量
/stats 端点、headroom doctor 与 dashboard 的说明都能在 docs/content/docs/quickstart.mdx 和 headroom/cli/doctor.py 中找到对应实现。跑上一两个任务后,headroom savings 会给出累积节省统计。
首跑实测:以一次真实代码搜索任务记录前后 token 对比
社区里流传最广的一个实测数据是:100 条代码搜索结果直接塞进上下文要 17,765 token,经 Headroom 压缩后降到约 1,800 token,节省约 90%。这个数字和仓库官方 benchmark 对得上。仓库的 benchmarks/index_proof_table.py 是一个可复现的基准脚本(uv run python benchmarks/index_proof_table.py --seed 20260902),用真实 tokenizer 和真实 compress() 路径测量,不依赖网络与 API key:
| 场景 | 压缩前 | 压缩后 | 节省 |
|---|---|---|---|
| 代码搜索(100 条结果) | 17,199 | 13,597 | 21% |
| SRE 事故排查 | 55,957 | 24,340 | 57% |
| 代码库探索 | 58,801 | 33,895 | 42% |
| GitHub issue 分诊 | 46,067 | 32,429 | 30% |
注意差异:同样是"代码搜索",官方基准测得 21% 而社区实测 90%,差在哪?压缩率由内容的重复度决定。Headroom 的 ContentRouter 会先做内容类型检测,再路由到对应压缩器——JSON 字符串数组(文件路径、日志行)去重后轻松超过 90%,JSON 对象数组约 52%,数字数组可达 97%(单样本数据见 docs/content/docs/limitations.mdx)。代码搜索如果命中大量重复路径,压缩率就高;如果结果集已足够紧凑,压缩率就低。
压缩的代价几乎可忽略:README 记载 10K token 的 JSON 搜索结果 p50 延迟仅 0.21ms,100K token 也只要 1.4ms。更关键的是准确率:GSM8K 从 0.870 到 0.870 无变化,TruthfulQA 从 0.530 到 0.560,SQuAD v2 在 19% 压缩率下保持 97% 准确率。压缩并不等于信息丢失——这正是 CCR 可逆机制的底气。跑完一轮任务后,dashboard 会直观呈现这些数字:
库调用:进程内压缩,一行代码
不想起代理、希望在应用内直接压缩的场景,用 compress() 单函数即可。Python 端用法(README 原样):
from headroom import compress
from openai import OpenAI
messages = [{"role": "user", "content": "Analyze these results"}]
result = compress(messages, model="gpt-4o")
client = OpenAI()
response = client.chat.completions.create(model="gpt-4o", messages=result.messages)
print(f"Saved {result.tokens_saved} tokens ({result.compression_ratio:.0%})")
返回值里 tokens_before / tokens_after / tokens_saved / compression_ratio / transforms_applied 一应俱全,方便接入自己的埋点。TypeScript 侧则通过 await compress(messages, { model, baseUrl }) 调用,注意 TS SDK 依赖本地代理提供压缩能力(详见 docs/content/docs/quickstart.mdx 的说明)。如果你用 LangChain、LiteLLM、Vercel AI SDK 或 Agno,仓库还提供了 HeadroomChatModel(your_llm)、HeadroomCallback()、headroomMiddleware() 等框架适配器。
常见接入误区与注意事项
社区热度高,踩坑的人也不少。综合社区讨论与仓库文档,这几个误区最典型:
误区一:以为所有内容都会被压缩。 事实恰恰相反——源码默认不压缩(除非显式开启 AST 压缩),短消息低于 min_tokens_to_compress(默认 50 token)直接跳过,grep/搜索结果的紧凑结构也会被放过,系统 prompt 为了前缀缓存兼容保持原样(见 docs/content/docs/limitations.mdx)。这是刻意设计:代码是拿来改的,压缩函数体会丢掉用户真正需要的东西。
误区二:把"60–95%"当成保证值。 有社区作者基于 614M 真实 Claude Code 会话数据实测,三款压缩工具联合仅节省 3.7%,与宣传差距巨大。这个争议的根源在于收益高度依赖场景:长会话 + 重 JSON 工具输出才是 Headroom 的主场;纯代码读写、短对话、已经紧凑的文本收益极小。官方自己的基准也诚实地标了不同场景 21%~57% 的差异。接入前用 headroom savings 跑自己的真实流量,别拿别人的数字当自己的预算。
误区三:手动 proxy 模式时上游配置没接对。 headroom wrap <tool> 会自动处理好上游端点、API key 与工具搜索模式,但如果你只起 headroom proxy 再手动切环境变量,就要自己保证 API key 能被代理转发。OpenCode 接入第三方 OpenAI 兼容上游(DeepSeek、Together、OpenRouter)时尤其要注意:wrap 默认路由到 https://api.openai.com/v1,第三方 key 会被 OpenAI 以 401 拒绝,必须传 --openai-api-url 或先设 OPENAI_TARGET_API_URL(README 中有专门脚注说明)。
误区四:忽略 Agent 特有开关。 自定义 ANTHROPIC_BASE_URL 会让 Claude Code 提前加载全部工具 schema(inflating 本地上下文),wrap claude 默认通过 --tool-search 保持延迟加载;同理,自定义 base URL 会导致 1M 上下文被截到 200K,--1m 参数能保住 context-1m beta header(对应 issue #746 与 #1158 的修复,见 headroom/cli/wrap.py 中 claude 命令的选项注释)。
误区五:中英文场景的压缩率差异。 有社区作者指出 Headroom 对中英混合长文本(交接文档、中文排障说明)的压缩效果不稳定,因此出现了 headroom-zh 适配方案,实测把 14,342 字节中文上下文压到 4,200 字节,通过保留路径、命令、端口等关键锚点来维持 Agent 可执行性。接入前如果你的语料以中文为主,建议先小样本验证压缩质量。
结论
10 分钟接入的完整路径其实只有三步:装包 → 起代理(或 wrap)→ 切环境变量验证 /stats。两条路线都不碰业务代码——代理模式零改动,库调用只加一行 compress()。但请记住它的适用边界:长会话、JSON/日志密集型工具输出是收益最大的场景;纯代码会话和短对话不是它的战场。压缩是"结构性去冗余",不是"截断",靠的是内容路由 + 统计压缩 + 可逆取回的完整链路。先跑通,再对着自己的流量谈节省,这才是对 token 账单负责的态度。

