Headroom v0.34.0：给AI编程Agent装上压缩引擎，JSON最高砍95% token
Headroom v0.34.0：给AI编程Agent装上"压缩引擎"，JSON最高砍95% token，Claude Code/Copilot/Cursor全支持
AI 编程 Agent 越来越强，但有一个问题越来越明显：每次对话都要往模型里塞大量上下文——工具输出、日志、文件内容、RAG 检索结果——这些内容吃 token、推成本、还容易撑爆上下文窗口。
Headroom 就是专门解决这个问题的。它是一个开源的上下文压缩层，插在 Agent 和 LLM 之间，自动识别内容类型并选择最优压缩策略。项目在 GitHub 上已经拿到 6.5 万星，支持 Claude Code、Codex、Copilot、Cursor、Aider、OpenCode、Cline 等主流编程 Agent。
8 月 5 日，Headroom 发布了 v0.34.0 版本，带来几个重要更新。
压缩效果：用数据说话
先看最核心的问题——压缩到底能省多少？
- JSON 数据：60-95% token 削减。对于 API 返回、配置文件、数据库结果这类结构化数据，效果最显著。
- 编程 Agent 整体：15-20% token 削减。这是综合了代码、日志、自然语言混合场景的实测结果。
- 官方演示：一段 10,144 token 的日志输出，压缩到 1,260 token，同样准确定位到 FATAL 错误。
关键点：压缩是可逆的。Headroom 采用 CCR（Compress-Cache-Retrieve）机制，原始内容缓存在本地，Agent 需要细节时可以随时检索还原，不会丢失信息。
v0.34.0 新功能
这次更新有几个值得关注的点：
Claude Code VS Code 扩展支持。之前 Headroom 主要支持 Claude Code 的 CLI 模式，现在可以直接在 VS Code 中的 Claude Code 扩展里使用压缩，覆盖了更多用户的使用场景。
PHP 代码压缩。CodeAwareCompressor 新增了 PHP AST 支持，PHP 项目的代码压缩质量会更好——不是简单截断，而是基于语法树的理解来压缩。
透明代理 VS Code 模型。GitHub Copilot 用户现在可以通过 Headroom 代理来压缩请求，不需要改任何代码或配置。代理模式下，Headroom 自动拦截和压缩发往模型的请求。
输出 token 削减。这是新功能里最有意思的：不只压缩你发给模型的内容，还削减模型写回来的冗余——比如仪式性的"我来帮你…"开头、不必要的代码重复、以及常规步骤上的过度"思考"。直接省输出 token 的钱。
frozen_message_count 配置。新增了控制哪些消息不参与压缩的能力，保护关键系统提示不被压缩干扰。
怎么用：三种接入方式
Headroom 提供了三种接入方式，从简单到灵活：
一行命令包装 Agent：headroom wrap claude 或 headroom wrap cursor，直接启动一个带压缩的 Agent 会话。支持十几种编程 Agent，用 headroom unwrap 可以随时还原。
代理模式：headroom proxy --port 8787，启动本地代理服务器，任何通过这个代理的请求都会被自动压缩。零代码改动，适合团队统一配置。
MCP 服务器：提供 headroom_compress、headroom_retrieve、headroom_stats 三个工具，任何支持 MCP 的客户端都能调用。
适用场景与限制
适合的场景：
- 长对话、大代码库的 Agent 工作流，上下文容易膨胀
- 需要控制 API 成本的团队，尤其是用 Claude Opus、GPT-5 等高价模型的
- 多 Agent 协作场景，Headroom 还提供跨 Agent 共享记忆和自动去重
需要注意的限制：
- 压缩层需要本地运行，会增加少量延迟
- 自然语言文本的压缩率低于 JSON 等结构化数据
- 输出 token 削减目前是可选功能，可能影响某些需要完整输出的场景
项目采用 MIT 协议开源，支持 Python 和 TypeScript 两种 SDK，可通过 pip install headroom-ai[all] 或 npm install headroom-ai 安装。
---
*基于 GitHub Release 页面和项目文档整理。Headroom v0.34.0 发布于 2026 年 8 月 5 日。*