你用 AI 编程时有没有发现工具输出、日志、搜索结果占了大量 token但真正有用的信息只需要一两条Headroom 专门解决这个问题。读完本文你将了解操作步骤 | 技术原理 | 架构设计 | 适用场景 这个项目解决什么问题上个月我在排查一个线上事故用 Claude Code 查了一堆日志和监控数据。半天下来问题倒是定位到了但看看用量报告光那次调试就烧了 65,694 个 token。不是代码对话是把整个日志 dump 喂进了上下文。这事儿不只发生在我身上。AI 编程助手在做代码搜索、日志排查、GitHub Issue 分析时真正需要 LLM 理解的信息可能不到 5%但你得把完整上下文送进去token 费跟着一起涨。现有方案无非两个要么截断上下文可能丢失关键信息要么多花钱买更长的上下文窗口。两个都不理想。Headroom 走了第三条路把上下文先压缩再送进 LLM需要的时候再按需取回原文——既省了 token又不丢信息。具体多省在代码搜索结果上省 92%事故排查省 92%Issue 分析省 73%代码库探索省 47%。关键后续的 benchmark 测试显示准确率没有任何下降。 快速上手安装Python 3.10一条命令pipinstallheadroom-ai[all]最简使用三行代码体验压缩fromheadroomimportcompress# 假设这是你 Agent 收到的 100 条代码搜索结果messages[{role:user,content:search results: ...}]# 实际数据可能 10000 tokensresultcompress(messages)print(f压缩前:{result.original_tokens}tokens)print(f压缩后:{result.compressed_tokens}tokens)print(f节省:{result.savings_pct:.0f}%)直接包一个 Claude Code 体验不用改任何代码直接包装现有的 Agentheadroom wrap claude这时候你的 Claude Code 就自动走 Headroom 的压缩管道了。等对话结束后查看用量headroom stats启动独立代理零代码接入如果你不想依赖 Python SDKHeadroom 还提供了一个 HTTP 代理模式headroom proxy--port8787然后设置OPENAI_BASE_URLhttp://localhost:8787/v1或者配到你的 Agent 里。所有请求自动走压缩管道不需要改任何代码。⚠️ 注意代理模式默认基于/tmp/headroom/ccr存储原文索引重启后原文映射会清空。生产环境建议配 SQLite 或 Redis 后端参见下文架构部分。作为 MCP 工具集成如果你是 MCP 客户端用户比如 OpenClaw、Cursor MCP直接配{mcpServers:{headroom:{command:headroom,args:[mcp]}}}之后你的 Agent 就能用headroom_compress、headroom_retrieve、headroom_stats三个工具非常方便。⚙️ 技术原理核心机制不是压缩是缓存检索Headroom 的核心思路跟你想象的压缩可能不太一样。它不是像gzip那样把文本做无损压缩后再解压——那样 LLM 根本看不懂。它的策略是把大部分内容移出上下文窗口仅保留信息密度最高的部分然后在 LLM 需要的时候把完整内容按需取回。具体实现上Headroom 分为三步流水线第一步内容检测器判断输入是什么类型日志、JSON、代码、搜索摘要、自然语言、diff。不同类型用不同策略能更精准地识别什么该删、什么该留。第二步三级压缩器各司其职SmartCrusherJSON 压缩自动识别字段的可压缩性。比如一条 JSON 日志有 30 个字段它只保留最关键的那几个其余用统计摘要替代“其他字段共 27 个值范围…”。对错误日志特别敏感——错误关键词附近的字段自动保留不会误删关键信息。CodeCompressor代码压缩基于 AST 分析删掉重复的函数签名、注释、import 语句。不碰逻辑代码。第三步可恢复压缩CCR压缩后的内容塞进本地 SQLite/RedisLLM 注意到这里可能不完整时调用headroom_retrieve取回完整原文。这个设计是整个系统的关键假设LLM 不需要看到所有细节但它需要知道哪些细节我可能缺少并有权主动取回。为什么选这个方案而不是更激进的方案如果说 Headroom 选了分层缓存架构那是因为更激进的方案——比如直接用一个小模型做摘要——有两个致命问题信息保真度不可控。用 7B 模型做摘要50% 的案例会把警告信息压缩成正常这在事故排查场景中等于灾难。延迟叠加。摘要模型的推理时间又叠在原有 LLM 调用之上对用户体验不友好。Headroom 的方案更像 CDN 的缓存策略不改变原始内容只是在最前面的压缩缓存层留下索引。需要的时候原文触手可及。这个设计的代价是存储空间需要本地存原文但在磁盘价格面前几乎可以忽略不计。另一个关键设计是 CacheAlignerKV Cache 对齐器。LLM 服务商的 KV Cache 对前缀顺序极其敏感——如果你前一个请求的前缀和当前请求的前缀不同cache 全部 miss。Headroom 会刻意把压缩后的输出排列成固定前缀格式让服务端的 KV Cache 命中率大幅提升。这意味着不仅省了 token还省了推理延迟。竞品对比不是所有省 token的方案都是竞品。真正的对比维度是要不要改变 LLM 看到的原始信息方案做法信息保真度额外推理恢复能力截断上下文丢掉超出窗口的部分❌ 丢信息无无法恢复小模型摘要跑 7B 摘要→送 LLM⚠️ 不可控有无法恢复LLMLingua 类删除低重要度 token⚠️ 语法离散无不可逆Headroom缓存原文压缩索引✅ LLM 按需取回无完全可逆Headroom 不走摘要路线走的是索引缓存按需取回路线。这个取舍意味着它不适用那些LLM 必须看到每一个标点的高精度场景比如法律合同审阅但对 99% 的 Agent 工作流——代码搜索、日志排查、Issue 分析——正好命中。️ 架构分析模块划分Headroom 的核心架构由四个 Rust crate 构成全部用 Rust 实现Python/TypeScript SDK 是通过 FFI 和 WASM 分别暴露的薄封装层┌─────────────────────────────────────────┐ │ 接入层任意语言 │ │ Python SDK │ TypeScript SDK │ HTTP Proxy │ ├─────────────────────────────────────────┤ │ headroom-proxy │ │ HTTP 代理 MCP 工具端点 │ ├─────────────────────────────────────────┤ │ headroom-core │ │ ┌───────────────────────────────────┐ │ │ │ ContentDetector → Pipeline │ │ │ │ ├─ SmartCrusher (JSON) │ │ │ │ ├─ CodeCompressor (AST) │ │ │ │ ├─ LogCompressor │ │ │ │ ├─ SearchCompressor │ │ │ │ └─ DiffCompressor │ │ │ ├───────────────────────────────────┤ │ │ │ Relevance (BM25 / Embedding) │ │ │ ├───────────────────────────────────┤ │ │ │ CCR Store (In-Memory / SQLite) │ │ │ └────────────────────────────────────┘ │ ├─────────────────────────────────────────┤ │ headroom-py / headroom-parity │ │ Python 扩展模块 兼容测试 │ └─────────────────────────────────────────┘三个核心角色headroom-core一切压缩逻辑的引擎压缩器流水线、CCR 存储、相关性评分headroom-proxyHTTP 代理层支持 OpenAI 兼容 API、MCP 工具端点headroom-py / SDKPython 扩展模块和 TypeScript SDK 的绑定层设计亮点压缩器的流水线编排SmartCrusher 是整个架构中最精妙的部分。它不是简单的压缩 JSON而是一整套可插拔的分析压缩管道Analyzer先对 JSON 做 schema 推断给每个字段打分值域、变异系数、语义类型Classifier基于分数决定字段级别保真/摘要/删除/占位符Compactor执行压缩生成紧凑 JSON 元数据Observer把压缩过程和原文映射一起写入 CCR Store这种多阶段管道让压缩决策变得透明和可控。如果你想调压缩强度改的是配置参数而不是代码。不够好的地方目前 Headroom 的压缩策略选择是硬编码的——根据内容类型预设算法不能根据用户的使用模式动态调整。比如你在做安全审计时可能需要比做代码搜索更保守的压缩设置但目前没有这个灵活性。另外CCR 的取回依赖 LLM 主动调用工具如果 LLM 没意识到这里信息不全就不会去取——这在新模型没适配的场景下可能漏信息。✅ 优缺点 适用场景优点省钱效果明显。实测代码搜索结果省 92% token事故排查省 92%。按 Claude Sonnet 的定价算每天用 Agent 8 小时的用户一个月能省 30-50 美元。信息可逆。CCR 存储让 LLM 在需要时能取回原文。不像摘要或截断方案那样丢信息。接入方式多样。可以包装命令行工具、启动 HTTP 代理、集成 MCP 服务对团队内不同技术栈都能覆盖。缺点压缩策略不可动态调整。在安全审计和代码搜索之间压缩激进程度应该不同但目前是硬编码的。严重依赖 LLM 自己判断该取回原文。如果 LLM 漏判压缩引入的信息损失就跟摘要方案一样了。适合谁立刻试试每天用 Claude Code / Codex / Cursor 的重度用户。如果你在排查 bug 时经常扔大量日志进上下文Headroom 的回本速度以天计。再等等如果你的工作场景以精细文本生成为主文案、翻译、法律文档上下文中有价值信息的密度天然很高压缩的收益不大。竞品一句话跟 LLMLingua 等 token 级压缩工具比Headroom 的差异化在于它不是压缩后扔掉原文而是缓存按需取回。代价是需要本地存储空间和额外的取回调用——但磁盘便宜取回调用也比直接送原文便宜。
AI 编程一天烧掉 50 块 token 费？一个开源项目把我救回来了
你用 AI 编程时有没有发现工具输出、日志、搜索结果占了大量 token但真正有用的信息只需要一两条Headroom 专门解决这个问题。读完本文你将了解操作步骤 | 技术原理 | 架构设计 | 适用场景 这个项目解决什么问题上个月我在排查一个线上事故用 Claude Code 查了一堆日志和监控数据。半天下来问题倒是定位到了但看看用量报告光那次调试就烧了 65,694 个 token。不是代码对话是把整个日志 dump 喂进了上下文。这事儿不只发生在我身上。AI 编程助手在做代码搜索、日志排查、GitHub Issue 分析时真正需要 LLM 理解的信息可能不到 5%但你得把完整上下文送进去token 费跟着一起涨。现有方案无非两个要么截断上下文可能丢失关键信息要么多花钱买更长的上下文窗口。两个都不理想。Headroom 走了第三条路把上下文先压缩再送进 LLM需要的时候再按需取回原文——既省了 token又不丢信息。具体多省在代码搜索结果上省 92%事故排查省 92%Issue 分析省 73%代码库探索省 47%。关键后续的 benchmark 测试显示准确率没有任何下降。 快速上手安装Python 3.10一条命令pipinstallheadroom-ai[all]最简使用三行代码体验压缩fromheadroomimportcompress# 假设这是你 Agent 收到的 100 条代码搜索结果messages[{role:user,content:search results: ...}]# 实际数据可能 10000 tokensresultcompress(messages)print(f压缩前:{result.original_tokens}tokens)print(f压缩后:{result.compressed_tokens}tokens)print(f节省:{result.savings_pct:.0f}%)直接包一个 Claude Code 体验不用改任何代码直接包装现有的 Agentheadroom wrap claude这时候你的 Claude Code 就自动走 Headroom 的压缩管道了。等对话结束后查看用量headroom stats启动独立代理零代码接入如果你不想依赖 Python SDKHeadroom 还提供了一个 HTTP 代理模式headroom proxy--port8787然后设置OPENAI_BASE_URLhttp://localhost:8787/v1或者配到你的 Agent 里。所有请求自动走压缩管道不需要改任何代码。⚠️ 注意代理模式默认基于/tmp/headroom/ccr存储原文索引重启后原文映射会清空。生产环境建议配 SQLite 或 Redis 后端参见下文架构部分。作为 MCP 工具集成如果你是 MCP 客户端用户比如 OpenClaw、Cursor MCP直接配{mcpServers:{headroom:{command:headroom,args:[mcp]}}}之后你的 Agent 就能用headroom_compress、headroom_retrieve、headroom_stats三个工具非常方便。⚙️ 技术原理核心机制不是压缩是缓存检索Headroom 的核心思路跟你想象的压缩可能不太一样。它不是像gzip那样把文本做无损压缩后再解压——那样 LLM 根本看不懂。它的策略是把大部分内容移出上下文窗口仅保留信息密度最高的部分然后在 LLM 需要的时候把完整内容按需取回。具体实现上Headroom 分为三步流水线第一步内容检测器判断输入是什么类型日志、JSON、代码、搜索摘要、自然语言、diff。不同类型用不同策略能更精准地识别什么该删、什么该留。第二步三级压缩器各司其职SmartCrusherJSON 压缩自动识别字段的可压缩性。比如一条 JSON 日志有 30 个字段它只保留最关键的那几个其余用统计摘要替代“其他字段共 27 个值范围…”。对错误日志特别敏感——错误关键词附近的字段自动保留不会误删关键信息。CodeCompressor代码压缩基于 AST 分析删掉重复的函数签名、注释、import 语句。不碰逻辑代码。第三步可恢复压缩CCR压缩后的内容塞进本地 SQLite/RedisLLM 注意到这里可能不完整时调用headroom_retrieve取回完整原文。这个设计是整个系统的关键假设LLM 不需要看到所有细节但它需要知道哪些细节我可能缺少并有权主动取回。为什么选这个方案而不是更激进的方案如果说 Headroom 选了分层缓存架构那是因为更激进的方案——比如直接用一个小模型做摘要——有两个致命问题信息保真度不可控。用 7B 模型做摘要50% 的案例会把警告信息压缩成正常这在事故排查场景中等于灾难。延迟叠加。摘要模型的推理时间又叠在原有 LLM 调用之上对用户体验不友好。Headroom 的方案更像 CDN 的缓存策略不改变原始内容只是在最前面的压缩缓存层留下索引。需要的时候原文触手可及。这个设计的代价是存储空间需要本地存原文但在磁盘价格面前几乎可以忽略不计。另一个关键设计是 CacheAlignerKV Cache 对齐器。LLM 服务商的 KV Cache 对前缀顺序极其敏感——如果你前一个请求的前缀和当前请求的前缀不同cache 全部 miss。Headroom 会刻意把压缩后的输出排列成固定前缀格式让服务端的 KV Cache 命中率大幅提升。这意味着不仅省了 token还省了推理延迟。竞品对比不是所有省 token的方案都是竞品。真正的对比维度是要不要改变 LLM 看到的原始信息方案做法信息保真度额外推理恢复能力截断上下文丢掉超出窗口的部分❌ 丢信息无无法恢复小模型摘要跑 7B 摘要→送 LLM⚠️ 不可控有无法恢复LLMLingua 类删除低重要度 token⚠️ 语法离散无不可逆Headroom缓存原文压缩索引✅ LLM 按需取回无完全可逆Headroom 不走摘要路线走的是索引缓存按需取回路线。这个取舍意味着它不适用那些LLM 必须看到每一个标点的高精度场景比如法律合同审阅但对 99% 的 Agent 工作流——代码搜索、日志排查、Issue 分析——正好命中。️ 架构分析模块划分Headroom 的核心架构由四个 Rust crate 构成全部用 Rust 实现Python/TypeScript SDK 是通过 FFI 和 WASM 分别暴露的薄封装层┌─────────────────────────────────────────┐ │ 接入层任意语言 │ │ Python SDK │ TypeScript SDK │ HTTP Proxy │ ├─────────────────────────────────────────┤ │ headroom-proxy │ │ HTTP 代理 MCP 工具端点 │ ├─────────────────────────────────────────┤ │ headroom-core │ │ ┌───────────────────────────────────┐ │ │ │ ContentDetector → Pipeline │ │ │ │ ├─ SmartCrusher (JSON) │ │ │ │ ├─ CodeCompressor (AST) │ │ │ │ ├─ LogCompressor │ │ │ │ ├─ SearchCompressor │ │ │ │ └─ DiffCompressor │ │ │ ├───────────────────────────────────┤ │ │ │ Relevance (BM25 / Embedding) │ │ │ ├───────────────────────────────────┤ │ │ │ CCR Store (In-Memory / SQLite) │ │ │ └────────────────────────────────────┘ │ ├─────────────────────────────────────────┤ │ headroom-py / headroom-parity │ │ Python 扩展模块 兼容测试 │ └─────────────────────────────────────────┘三个核心角色headroom-core一切压缩逻辑的引擎压缩器流水线、CCR 存储、相关性评分headroom-proxyHTTP 代理层支持 OpenAI 兼容 API、MCP 工具端点headroom-py / SDKPython 扩展模块和 TypeScript SDK 的绑定层设计亮点压缩器的流水线编排SmartCrusher 是整个架构中最精妙的部分。它不是简单的压缩 JSON而是一整套可插拔的分析压缩管道Analyzer先对 JSON 做 schema 推断给每个字段打分值域、变异系数、语义类型Classifier基于分数决定字段级别保真/摘要/删除/占位符Compactor执行压缩生成紧凑 JSON 元数据Observer把压缩过程和原文映射一起写入 CCR Store这种多阶段管道让压缩决策变得透明和可控。如果你想调压缩强度改的是配置参数而不是代码。不够好的地方目前 Headroom 的压缩策略选择是硬编码的——根据内容类型预设算法不能根据用户的使用模式动态调整。比如你在做安全审计时可能需要比做代码搜索更保守的压缩设置但目前没有这个灵活性。另外CCR 的取回依赖 LLM 主动调用工具如果 LLM 没意识到这里信息不全就不会去取——这在新模型没适配的场景下可能漏信息。✅ 优缺点 适用场景优点省钱效果明显。实测代码搜索结果省 92% token事故排查省 92%。按 Claude Sonnet 的定价算每天用 Agent 8 小时的用户一个月能省 30-50 美元。信息可逆。CCR 存储让 LLM 在需要时能取回原文。不像摘要或截断方案那样丢信息。接入方式多样。可以包装命令行工具、启动 HTTP 代理、集成 MCP 服务对团队内不同技术栈都能覆盖。缺点压缩策略不可动态调整。在安全审计和代码搜索之间压缩激进程度应该不同但目前是硬编码的。严重依赖 LLM 自己判断该取回原文。如果 LLM 漏判压缩引入的信息损失就跟摘要方案一样了。适合谁立刻试试每天用 Claude Code / Codex / Cursor 的重度用户。如果你在排查 bug 时经常扔大量日志进上下文Headroom 的回本速度以天计。再等等如果你的工作场景以精细文本生成为主文案、翻译、法律文档上下文中有价值信息的密度天然很高压缩的收益不大。竞品一句话跟 LLMLingua 等 token 级压缩工具比Headroom 的差异化在于它不是压缩后扔掉原文而是缓存按需取回。代价是需要本地存储空间和额外的取回调用——但磁盘便宜取回调用也比直接送原文便宜。
