Headroom 教程：给 Coding Agent 加一层上下文压缩，少花 token 还要不掉准

Coding Agent 的 token 浪费，很多时候不是模型太贵，而是上下文太脏。终端输出、测试日志、重复文件、RAG 片段、工具结果，全都原样塞回去，模型不但花钱，还更容易被噪音带偏。

Headroom 做的是上下文优化层。它可以包装常见 coding agent，也可以作为代理放在应用和模型之间，对消息、工具输出、日志和文本做压缩与路由。

重点不是盲目压缩，而是在不损失任务信息的前提下，把上下文变干净。

安装：

pip install "headroom-ai[all]"

包装不同工具：

headroom wrap claude
headroom wrap codex
headroom wrap cursor
headroom wrap aider
headroom wrap copilot

这类包装适合个人和团队试用。先选一个最常用的 coding agent，观察压缩后是否影响代码修改质量，不要一开始全线替换。

Python 里可以直接压缩消息：

from headroom import compress

result = compress(messages, model="claude-sonnet-4-5")
response = client.messages.create(
    model="claude-sonnet-4-5",
    messages=result.messages,
)

print(result.tokens_saved)
print(result.compression_ratio)

TypeScript 也可以接：

import { compress } from 'headroom-ai';

const result = await compress(messages, {
  model: 'gpt-4o'
});

这适合你自己控制应用逻辑的情况。你可以决定哪些消息压缩，哪些消息保留原样。

如果不想改代码，可以跑代理：

headroom proxy --port 8787

把应用的模型 base url 指向本地代理：

ANTHROPIC_BASE_URL=http://localhost:8787 your-app
OPENAI_BASE_URL=http://localhost:8787/v1 your-app

代理模式很方便，但上线前一定要做评测。因为你把压缩层放到了所有请求前面，影响面更大。

适合压缩的内容：

长测试日志
重复终端输出
RAG 检索片段
大段文档摘录
工具返回的 JSON 列表
代码搜索结果

不适合随便压缩的内容：

用户明确要求
安全策略
系统指令
最终要执行的命令
补丁 diff
错误栈顶部关键行
法律或财务原文

这点很关键。压缩层如果把关键约束压没了，省下来的 token 都会用来填坑。

Headroom 官方强调可评测，你自己的项目也要评测。准备一批真实 Agent 任务：修复测试、解释报错、改配置、生成迁移脚本、阅读长日志。

每个任务跑两遍：原始上下文一遍，压缩上下文一遍。记录：

是否完成任务
是否误删信息
是否多跑无关命令
最终 diff 是否正确
token 节省比例
耗时变化
人工复核结论

如果只是看 tokens_saved，很容易被漂亮数字骗。上下文压缩不是压缩软件，不能只看压缩率。

在 coding agent 里，不同工具输出的重要性不一样。

高保真：用户指令、待应用补丁、失败测试断言
中保真：错误栈、相关代码片段、配置差异
低保真：完整安装日志、重复警告、无关文件列表

压缩策略应该按等级来。高保真尽量保留，中保真做摘要，低保真压缩或只保留统计。

不要把压缩层做成不可绕过。每个团队成员都应该知道怎么关闭 Headroom，怎么用原始上下文复跑。

建议保留两个环境变量：

HEADROOM_ENABLED=true
HEADROOM_MODE=safe

safe 模式只压缩低风险内容。等评测稳定后，再扩大范围。

Headroom 这类工具的意义，不是让上下文越短越好，而是让模型看到更少噪音、更多关键信息。

如果压缩后任务成功率不降、成本下降、响应更快，那就是好东西。如果省了 token 但让 Agent 多犯错，那就是假省钱。

Coding Agent 时代，上下文已经变成工程资源。会组织上下文的团队，比单纯会买更大模型的团队走得更远。这事不玄乎，挺实在。

不要把所有消息丢给压缩器。先按来源分层。

instruction：系统和用户要求，默认不压缩
state：任务状态，可以摘要
artifact：文件、日志、搜索结果，按类型处理
decision：关键判断，保留原文或结构化记录
noise：重复输出，强压缩或丢弃

有了分层，Headroom 才能发挥价值。没有分层，压缩器只能在一团乱麻里猜重点。

Coding Agent 最关键的证据是 diff、测试失败断言和用户目标。完整安装日志可以压缩，最终补丁不能随便压缩。

保留：用户需求、失败测试、补丁 diff、关键配置
摘要：长日志、依赖安装输出、搜索结果
丢弃：重复 warning、无关文件列表、成功安装流水

这能减少 token，同时避免把真正要修改的部分压没。

别只看单次请求省了多少 token。Agent 往往会多轮调用。应该按任务统计：从用户发起到最终完成，一共省了多少，成功率有没有变化。真实成本是 token、时间和人工复核加起来。