引言“Token 不够用不一定是上下文窗口太小——更可能是里面塞了太多垃圾。”这是每日一个开源项目系列的第122篇文章。今天的主角是headroom——一个专为 AI Agent 设计的上下文压缩层。随着 Agent 越来越复杂它们的上下文越填越满工具返回的 JSON 动辄几千行、RAG 检索出的文档大量冗余、搜索结果包含无关内容、日志里充斥着无意义的噪声。最终结果是Agent 的 Token 消耗飙升成本失控有时甚至超出窗口限制。headroom 的答案是在内容进入 LLM 之前先压缩它。不是截断不是摘要会丢失信息而是保留关键信息、去掉冗余——还支持按需取回原文。你将学到什么Agent 上下文为什么会膨胀以及膨胀的代价headroom 的四种集成模式Library / Proxy / Agent Wrap / MCP ServerSmartCrusher、CodeCompressor、Kompress-base 三种压缩引擎的工作原理CCR可逆压缩检索压缩后仍然能取回原文真实基准测试数据不同工作负载下的压缩率与精度保持情况前置知识基础 Python 使用经验了解 LLM API 的基本用法Token 计费概念使用过至少一种 AI Agent 框架可选项目背景项目简介headroom 自称AI Agent 的上下文压缩层定位在用户输入与 LLM 之间。它的核心逻辑是工具输出、日志、代码片段、RAG 检索结果往往包含大量对当前问题无关的内容把这些冗余去掉LLM 反而能看得更清楚、答得更准——同时节省大量 Token。与简单的截断或摘要不同headroom 的压缩是可逆的原始内容本地保留LLM 可以通过headroom_retrieve工具按需取回不会因为压缩而丢失任何信息。作者/团队介绍作者: Tejas Choprachopratejas语言组成: Python 76.9% Rust 18.3% TypeScript 2.7%License: Apache 2.0项目数据⭐ GitHub Stars:12,800 Forks: 823 版本: v0.23.0最新 License: Apache 2.0 支持: Python 3.10Node.jsDocker主要功能核心作用headroom 在 Agent 的工具输出到达 LLM 之前拦截并压缩内容降低噪声、节省 Token、避免上下文窗口超限。整体定位是一个透明的压缩中间件——不改变 Agent 的逻辑只改变内容的密度。使用场景代码搜索与分析搜索 100 个文件返回 17,765 个 token压缩后仅 1,408 个节省 92%Agent 只看到与问题相关的代码片段SRE 事故调试系统日志、堆栈跟踪、指标数据混合输入65,694 token 压缩至 5,118节省 92%关键异常信息反而更突出GitHub Issue 分流批量处理 Issue54,174 token 压缩至 14,761节省 73%分类准确率不降RAG 检索增强生成检索出的文档块去冗余后LLM 不再被不相关内容干扰回答精度反而提升多 Agent 协作跨 Agent 共享压缩后的记忆自动去重避免同一信息被重复消耗多次快速开始# 安装完整版含所有扩展pipinstallheadroom-ai[all]# 或按需安装扩展[proxy] [mcp] [ml] [code] [memory] [langchain] 等pipinstallheadroom-ai[proxy,mcp]方式一Library 模式代码内嵌fromheadroomimportHeadroom hrHeadroom()# 压缩消息列表传给 LLM 前调用compressedhr.compress(messages)# 正常调用 LLMresponseclient.messages.create(modelclaude-opus-4-5,messagescompressed.messages,)# 查看节省了多少 Tokenprint(f压缩率:{compressed.compression_ratio:.1%})print(f节省 Token:{compressed.tokens_saved})方式二Proxy 模式零代码改动# 启动透明代理headroom proxy--port8787# 只需把 base_url 指向代理其余代码不变importanthropic# 只改一行把 API 请求打到 headroom proxyclientanthropic.Anthropic(base_urlhttp://localhost:8787)# 之后的代码完全不变responseclient.messages.create(...)方式三Agent Wrap一行命令包装现有 Agentheadroom wrap claude# 包装 Claude Codeheadroom wrap aider# 包装 Aiderheadroom wrap cursor# 包装 Cursorheadroom wrap codex# 包装 Codex CLI查看压缩统计headroom perf# 输出: 今日节省 Token: 48,392 | 累计节省: $12.40核心特性四种集成模式Library / Proxy / Agent Wrap / MCP Server按需选择无需改造已有架构CCR 可逆压缩Compressed Context Retrieval压缩后原文本地存储LLM 可通过headroom_retrieve工具按需取回压缩不等于丢弃跨 Agent 共享记忆多个 Agent 访问同一记忆存储自动去重避免重复消耗相同信息headroom learn自动学习分析失败的 Agent 会话自动将经验写入 CLAUDE.md / AGENTS.md让下次运行更聪明全内容类型覆盖JSONSmartCrusher、代码AST 级别 CodeCompressor、纯文本Kompress-base、图像均支持本地优先隐私安全所有压缩计算本地完成数据不离开本机项目优势对比对比维度headroom简单截断LLM 摘要手动过滤信息保留✅ 可逆原文可取回❌ 永久丢失⚠️ 可能失真⚠️ 依赖规则集成成本✅ 1行代码 / 0行代码✅ 简单❌ 需要额外 LLM 调用❌ 维护成本高压缩质量✅ 结构感知❌ 无感知⚠️ 通用摘要⚠️ 场景局限成本✅ 节省 API 费用✅ 无额外成本❌ 额外 Token 消耗✅ 无额外成本项目详细剖析压缩流水线架构headroom 的内部处理流程分为三个阶段用户输入 / 工具输出 ↓ CacheAligner ← 对齐缓存避免重复处理相同内容 ↓ ContentRouter ← 识别内容类型路由到对应引擎 ├── SmartCrusher (JSON / 结构化数据) ├── CodeCompressor (代码AST 级别) └── Kompress-base (纯文本HuggingFace 模型) ↓ 压缩后内容 → LLM ↓ 原文本地存储CCR 索引← 支持按需检索CacheAligner识别已经处理过的内容跳过重复压缩降低计算开销。ContentRouter分析消息内容类型JSON 结构、代码语法、纯文本路由到最适合的压缩引擎。不同类型的内容用不同策略压缩效果远好于通用方案。三种压缩引擎① SmartCrusherJSON / 结构化数据工具调用的返回值通常是 JSON包含大量与当前问题无关的字段。SmartCrusher 分析 LLM 的上一条查询提取相关字段丢弃无关结构# 原始工具返回1200 token{results:[{id:abc123,title:...,content:...,# 与查询相关metadata:{# 无关字段created_at:...,updated_at:...,author_id:42,tags:[...,...],internal_score:0.87,# ... 20 更多无关字段}}# × 99 更多结果]}# 压缩后约 80 token节省 93%# 只保留 title content剔除所有 metadata② CodeCompressor代码AST 级别代码的压缩不能靠截断——截断会破坏语法LLM 看到残缺的代码反而更困惑。CodeCompressor 解析 AST抽象语法树保留函数签名、类定义、关键注释压缩掉函数体实现细节# 原始代码片段800 tokendefprocess_payment(user_id:int,amount:float,currency:strUSD,retry_count:int3)-PaymentResult:处理支付请求支持重试机制forattemptinrange(retry_count):try:# 验证用户余额balanceget_user_balance(user_id)ifbalanceamount:raiseInsufficientFunds(...)# ... 200 行实现细节 ...exceptNetworkError:ifattemptretry_count-1:raisetime.sleep(2**attempt)# AST 压缩后约 60 tokendefprocess_payment(user_id:int,amount:float,currency:strUSD,retry_count:int3)-PaymentResult:处理支付请求支持重试机制...# [实现已压缩可通过 headroom_retrieve 取回]③ Kompress-base纯文本对于文档、日志等纯文本headroom 使用 HuggingFace 上的Kompress-base模型做语义压缩保留与当前查询最相关的句子过滤冗余。CCR可逆压缩的关键普通截断是单向的——一旦截掉信息永久丢失。headroom 的 CCRCompressed Context Retrieval机制让压缩变得可逆原文 ──────────── 压缩 ──────────→ LLM │ │ └── 存入本地 CCR 索引 │ (按 trace_id 索引) │ │ 需要更多细节时 ↓ headroom_retrieve(trace_id, 函数实现) │ ↓ 从本地索引取回原文片段在 MCP Server 模式下LLM 可以主动调用headroom_retrieve工具# LLM 决定需要查看完整实现时自动调用headroom_retrieve(trace_idabc123,queryprocess_payment 的重试逻辑实现)# → 返回原始代码的对应片段MCP Server 模式MCP 模式暴露三个工具给 LLM# Claude Code / Cursor / 任何支持 MCP 的客户端可以直接调用headroom_compress(content,content_typeauto)# → 压缩内容返回压缩后文本 trace_idheadroom_retrieve(trace_id,query)# → 按需取回原文片段headroom_stats()# → 返回当前会话的压缩统计信息配置示例claude_desktop_config.json{mcpServers:{headroom:{command:headroom,args:[mcp]}}}headroom learn从失败中自动学习这是 headroom 最独特的功能之一。当 Agent 会话失败任务未完成、LLM 多次重试、上下文超限headroom learn会分析失败原因自动将学到的规律写入CLAUDE.md或AGENTS.mdheadroom learn --session-log ./logs/session_2026-06-05.jsonl# 输出示例# 发现 3 个重复模式# 1. 在搜索 GitHub API 时总是携带过多 metadata 字段 → 已添加过滤规则到 CLAUDE.md# 2. 处理大型 JSON 响应时上下文超限 3 次 → 已添加 SmartCrusher 提示到 AGENTS.md# 3. 代码分析任务中 CodeCompressor 提升了 40% 成功率 → 已记录配置实测压缩率与精度数据headroom 提供了真实的基准测试非合成数据工作负载压缩前 Token压缩后 Token节省比例代码搜索100条结果17,7651,40892%SRE 事故调试65,6945,11892%GitHub Issue 分流54,17414,76173%代码库探索78,50241,25447%精度保持核心问题压缩会不会让 LLM 答错基准测试压缩率精度变化GSM8K数学推理-delta ±0.000完全不变SQuAD v2阅读理解19%保持97%精度关键结论对于 Agent 工作负载去掉冗余内容不会降低答案质量有时反而更好——LLM 不再被不相关内容干扰。项目地址与资源官方资源GitHub: chopratejas/headroomIssue Tracker: github.com/chopratejas/headroom/issuesPyPI:pip install headroom-ai相关资源LangChain 集成文档MCP 协议规范Kompress-base 模型HuggingFace总结headroom 解决的是一个被长期低估的问题上下文里的噪声。我们花了大量时间优化 prompt 措辞却很少关注工具输出带来的冗余。一次代码搜索返回 17,765 个 token其中 16,357 个是噪声——而这在复杂 Agent 任务中每分钟都在发生。四种集成模式Library / Proxy / Wrap / MCP让 headroom 几乎可以无侵入地接入任何现有 Agent 架构。CCR 可逆压缩确保压缩不是截断headroom learn让 Agent 从失败中自动积累经验。如果你的 Agent 正在面临成本失控或上下文超限的问题headroom 值得作为第一个尝试的方案。欢迎了解 PrimeSkills —— 精选 AI Agent 与技能的市场每一个都在真实的企业级工作流中经过验证不堆砌概念只留下真正有效的东西。欢迎来我的个人主页找到更多有用的知识和有趣的产品
每日一个开源项目（第122篇）：headroom - 给 AI Agent 装上上下文压缩层，Token 最高省 95%
引言“Token 不够用不一定是上下文窗口太小——更可能是里面塞了太多垃圾。”这是每日一个开源项目系列的第122篇文章。今天的主角是headroom——一个专为 AI Agent 设计的上下文压缩层。随着 Agent 越来越复杂它们的上下文越填越满工具返回的 JSON 动辄几千行、RAG 检索出的文档大量冗余、搜索结果包含无关内容、日志里充斥着无意义的噪声。最终结果是Agent 的 Token 消耗飙升成本失控有时甚至超出窗口限制。headroom 的答案是在内容进入 LLM 之前先压缩它。不是截断不是摘要会丢失信息而是保留关键信息、去掉冗余——还支持按需取回原文。你将学到什么Agent 上下文为什么会膨胀以及膨胀的代价headroom 的四种集成模式Library / Proxy / Agent Wrap / MCP ServerSmartCrusher、CodeCompressor、Kompress-base 三种压缩引擎的工作原理CCR可逆压缩检索压缩后仍然能取回原文真实基准测试数据不同工作负载下的压缩率与精度保持情况前置知识基础 Python 使用经验了解 LLM API 的基本用法Token 计费概念使用过至少一种 AI Agent 框架可选项目背景项目简介headroom 自称AI Agent 的上下文压缩层定位在用户输入与 LLM 之间。它的核心逻辑是工具输出、日志、代码片段、RAG 检索结果往往包含大量对当前问题无关的内容把这些冗余去掉LLM 反而能看得更清楚、答得更准——同时节省大量 Token。与简单的截断或摘要不同headroom 的压缩是可逆的原始内容本地保留LLM 可以通过headroom_retrieve工具按需取回不会因为压缩而丢失任何信息。作者/团队介绍作者: Tejas Choprachopratejas语言组成: Python 76.9% Rust 18.3% TypeScript 2.7%License: Apache 2.0项目数据⭐ GitHub Stars:12,800 Forks: 823 版本: v0.23.0最新 License: Apache 2.0 支持: Python 3.10Node.jsDocker主要功能核心作用headroom 在 Agent 的工具输出到达 LLM 之前拦截并压缩内容降低噪声、节省 Token、避免上下文窗口超限。整体定位是一个透明的压缩中间件——不改变 Agent 的逻辑只改变内容的密度。使用场景代码搜索与分析搜索 100 个文件返回 17,765 个 token压缩后仅 1,408 个节省 92%Agent 只看到与问题相关的代码片段SRE 事故调试系统日志、堆栈跟踪、指标数据混合输入65,694 token 压缩至 5,118节省 92%关键异常信息反而更突出GitHub Issue 分流批量处理 Issue54,174 token 压缩至 14,761节省 73%分类准确率不降RAG 检索增强生成检索出的文档块去冗余后LLM 不再被不相关内容干扰回答精度反而提升多 Agent 协作跨 Agent 共享压缩后的记忆自动去重避免同一信息被重复消耗多次快速开始# 安装完整版含所有扩展pipinstallheadroom-ai[all]# 或按需安装扩展[proxy] [mcp] [ml] [code] [memory] [langchain] 等pipinstallheadroom-ai[proxy,mcp]方式一Library 模式代码内嵌fromheadroomimportHeadroom hrHeadroom()# 压缩消息列表传给 LLM 前调用compressedhr.compress(messages)# 正常调用 LLMresponseclient.messages.create(modelclaude-opus-4-5,messagescompressed.messages,)# 查看节省了多少 Tokenprint(f压缩率:{compressed.compression_ratio:.1%})print(f节省 Token:{compressed.tokens_saved})方式二Proxy 模式零代码改动# 启动透明代理headroom proxy--port8787# 只需把 base_url 指向代理其余代码不变importanthropic# 只改一行把 API 请求打到 headroom proxyclientanthropic.Anthropic(base_urlhttp://localhost:8787)# 之后的代码完全不变responseclient.messages.create(...)方式三Agent Wrap一行命令包装现有 Agentheadroom wrap claude# 包装 Claude Codeheadroom wrap aider# 包装 Aiderheadroom wrap cursor# 包装 Cursorheadroom wrap codex# 包装 Codex CLI查看压缩统计headroom perf# 输出: 今日节省 Token: 48,392 | 累计节省: $12.40核心特性四种集成模式Library / Proxy / Agent Wrap / MCP Server按需选择无需改造已有架构CCR 可逆压缩Compressed Context Retrieval压缩后原文本地存储LLM 可通过headroom_retrieve工具按需取回压缩不等于丢弃跨 Agent 共享记忆多个 Agent 访问同一记忆存储自动去重避免重复消耗相同信息headroom learn自动学习分析失败的 Agent 会话自动将经验写入 CLAUDE.md / AGENTS.md让下次运行更聪明全内容类型覆盖JSONSmartCrusher、代码AST 级别 CodeCompressor、纯文本Kompress-base、图像均支持本地优先隐私安全所有压缩计算本地完成数据不离开本机项目优势对比对比维度headroom简单截断LLM 摘要手动过滤信息保留✅ 可逆原文可取回❌ 永久丢失⚠️ 可能失真⚠️ 依赖规则集成成本✅ 1行代码 / 0行代码✅ 简单❌ 需要额外 LLM 调用❌ 维护成本高压缩质量✅ 结构感知❌ 无感知⚠️ 通用摘要⚠️ 场景局限成本✅ 节省 API 费用✅ 无额外成本❌ 额外 Token 消耗✅ 无额外成本项目详细剖析压缩流水线架构headroom 的内部处理流程分为三个阶段用户输入 / 工具输出 ↓ CacheAligner ← 对齐缓存避免重复处理相同内容 ↓ ContentRouter ← 识别内容类型路由到对应引擎 ├── SmartCrusher (JSON / 结构化数据) ├── CodeCompressor (代码AST 级别) └── Kompress-base (纯文本HuggingFace 模型) ↓ 压缩后内容 → LLM ↓ 原文本地存储CCR 索引← 支持按需检索CacheAligner识别已经处理过的内容跳过重复压缩降低计算开销。ContentRouter分析消息内容类型JSON 结构、代码语法、纯文本路由到最适合的压缩引擎。不同类型的内容用不同策略压缩效果远好于通用方案。三种压缩引擎① SmartCrusherJSON / 结构化数据工具调用的返回值通常是 JSON包含大量与当前问题无关的字段。SmartCrusher 分析 LLM 的上一条查询提取相关字段丢弃无关结构# 原始工具返回1200 token{results:[{id:abc123,title:...,content:...,# 与查询相关metadata:{# 无关字段created_at:...,updated_at:...,author_id:42,tags:[...,...],internal_score:0.87,# ... 20 更多无关字段}}# × 99 更多结果]}# 压缩后约 80 token节省 93%# 只保留 title content剔除所有 metadata② CodeCompressor代码AST 级别代码的压缩不能靠截断——截断会破坏语法LLM 看到残缺的代码反而更困惑。CodeCompressor 解析 AST抽象语法树保留函数签名、类定义、关键注释压缩掉函数体实现细节# 原始代码片段800 tokendefprocess_payment(user_id:int,amount:float,currency:strUSD,retry_count:int3)-PaymentResult:处理支付请求支持重试机制forattemptinrange(retry_count):try:# 验证用户余额balanceget_user_balance(user_id)ifbalanceamount:raiseInsufficientFunds(...)# ... 200 行实现细节 ...exceptNetworkError:ifattemptretry_count-1:raisetime.sleep(2**attempt)# AST 压缩后约 60 tokendefprocess_payment(user_id:int,amount:float,currency:strUSD,retry_count:int3)-PaymentResult:处理支付请求支持重试机制...# [实现已压缩可通过 headroom_retrieve 取回]③ Kompress-base纯文本对于文档、日志等纯文本headroom 使用 HuggingFace 上的Kompress-base模型做语义压缩保留与当前查询最相关的句子过滤冗余。CCR可逆压缩的关键普通截断是单向的——一旦截掉信息永久丢失。headroom 的 CCRCompressed Context Retrieval机制让压缩变得可逆原文 ──────────── 压缩 ──────────→ LLM │ │ └── 存入本地 CCR 索引 │ (按 trace_id 索引) │ │ 需要更多细节时 ↓ headroom_retrieve(trace_id, 函数实现) │ ↓ 从本地索引取回原文片段在 MCP Server 模式下LLM 可以主动调用headroom_retrieve工具# LLM 决定需要查看完整实现时自动调用headroom_retrieve(trace_idabc123,queryprocess_payment 的重试逻辑实现)# → 返回原始代码的对应片段MCP Server 模式MCP 模式暴露三个工具给 LLM# Claude Code / Cursor / 任何支持 MCP 的客户端可以直接调用headroom_compress(content,content_typeauto)# → 压缩内容返回压缩后文本 trace_idheadroom_retrieve(trace_id,query)# → 按需取回原文片段headroom_stats()# → 返回当前会话的压缩统计信息配置示例claude_desktop_config.json{mcpServers:{headroom:{command:headroom,args:[mcp]}}}headroom learn从失败中自动学习这是 headroom 最独特的功能之一。当 Agent 会话失败任务未完成、LLM 多次重试、上下文超限headroom learn会分析失败原因自动将学到的规律写入CLAUDE.md或AGENTS.mdheadroom learn --session-log ./logs/session_2026-06-05.jsonl# 输出示例# 发现 3 个重复模式# 1. 在搜索 GitHub API 时总是携带过多 metadata 字段 → 已添加过滤规则到 CLAUDE.md# 2. 处理大型 JSON 响应时上下文超限 3 次 → 已添加 SmartCrusher 提示到 AGENTS.md# 3. 代码分析任务中 CodeCompressor 提升了 40% 成功率 → 已记录配置实测压缩率与精度数据headroom 提供了真实的基准测试非合成数据工作负载压缩前 Token压缩后 Token节省比例代码搜索100条结果17,7651,40892%SRE 事故调试65,6945,11892%GitHub Issue 分流54,17414,76173%代码库探索78,50241,25447%精度保持核心问题压缩会不会让 LLM 答错基准测试压缩率精度变化GSM8K数学推理-delta ±0.000完全不变SQuAD v2阅读理解19%保持97%精度关键结论对于 Agent 工作负载去掉冗余内容不会降低答案质量有时反而更好——LLM 不再被不相关内容干扰。项目地址与资源官方资源GitHub: chopratejas/headroomIssue Tracker: github.com/chopratejas/headroom/issuesPyPI:pip install headroom-ai相关资源LangChain 集成文档MCP 协议规范Kompress-base 模型HuggingFace总结headroom 解决的是一个被长期低估的问题上下文里的噪声。我们花了大量时间优化 prompt 措辞却很少关注工具输出带来的冗余。一次代码搜索返回 17,765 个 token其中 16,357 个是噪声——而这在复杂 Agent 任务中每分钟都在发生。四种集成模式Library / Proxy / Wrap / MCP让 headroom 几乎可以无侵入地接入任何现有 Agent 架构。CCR 可逆压缩确保压缩不是截断headroom learn让 Agent 从失败中自动积累经验。如果你的 Agent 正在面临成本失控或上下文超限的问题headroom 值得作为第一个尝试的方案。欢迎了解 PrimeSkills —— 精选 AI Agent 与技能的市场每一个都在真实的企业级工作流中经过验证不堆砌概念只留下真正有效的东西。欢迎来我的个人主页找到更多有用的知识和有趣的产品
![3分钟掌握VideoDownloadHelper：简单高效的网页视频下载插件终极指南 [特殊字符]](images/news3.jpg)
