headroom：一种上下文压缩层，通过内容感知压缩器和本地代理降低 AI 代理的 LLM 令牌使用量

它解决了什么问题

headroom 减少了发送到 LLM 和从 LLM 接收的令牌数量，显著降低了 AI 代理的成本和延迟。它针对代理工作负载中的“浪费”——例如重复的工具输出、冗长的日志、RAG 片段以及冗余的模型前置词——在不牺牲模型答案准确性的前提下进行压缩。

工作原理

headroom 充当位于 AI 代理与 LLM 提供商之间的本地压缩层。它使用 ContentRouter 检测数据类型并应用最合适的压缩器：

• SmartCrusher：用于 JSON 数据。
• CodeCompressor：针对多种编程语言的 AST 感知压缩。
• Kompress-v2-base：专用于散文/文本的 HuggingFace 模型。

它具备 CCR（可逆压缩），在本地缓存原始内容，必要时 LLM 可通过工具调用检索完整版本。它还包含 CacheAligner，确保提示前缀在提供商 KV 缓存中保持稳定。为降低输出成本，headroom 使用冗长度引导和工作量路由来裁剪不必要的模型响应。

适用人群

• 每日使用 AI 编码代理（如 Claude Code、Cursor、Aider 或 Cline）的开发者。
• 使用多种不同 AI 代理并希望拥有共享记忆存储的团队。
• 想通过库或代理将令牌压缩集成到 Python 或 TypeScript 应用中的应用开发者。

亮点

• 多种集成模式：提供 Python/TypeScript 库、即插即用代理或 MCP 服务器。
• 代理包装：对流行代理进行一键包装（例如 headroom wrap claude）。
• 输出削减：裁剪模型前置词，减少常规步骤的“思考”工作量，从而节省输出令牌。
• 跨代理记忆：在不同 LLM 提供商之间共享、自动去重的记忆。
• 失败挖掘：headroom learn 命令分析失败的会话，并将修正写入代理配置文件。