Headroom：AI 代理的上下文压缩层
在到达 LLM 之前压缩工具输出、日志、文件和 RAG 分块，为编码代理节省 15-20% 的标记，为 JSON 节省 60-95%，同时不影响答案质量。
证据显示：代理以本地优先运行，数据留在本机；有passthrough模式，敏感内容默认不处理；有安全策略文档，说明不存储API密钥；依赖有CVE修复和约束。扣分：未明确最小权限原则，代理可能以用户权限运行；用户确认机制不明确，wrap操作可能自动修改配置；外部影响（如修改用户配置文件）未充分说明；发布者身份未验证，来源归属不明确。
证据显示：README和pyproject.toml描述一致，功能列表清晰；依赖有版本约束和CVE修复；有CI测试和错误处理说明。扣分：未提供失败消息的具体示例，依赖可用性未完全验证（如模型下载依赖外部服务）。
证据显示：明确目标用户（开发者、团队），提供多种使用场景（库、代理、MCP）；能力边界清晰（支持多种代理和框架）；触发条件明确（wrap、proxy等命令）；环境适配良好（支持Python 3.10+，多种操作系统）。扣分：未详细说明所有环境限制（如Windows支持有限）。
证据显示：信息架构清晰，有文档、llms.txt；安装说明详细；命名稳定（headroom-ai）；有示例和FAQ；已知限制部分提及（如sandbox环境）；许可证为Apache-2.0；有版本号和changelog；维护责任有说明（社区支持）。扣分：发布者身份未验证，维护责任不明确。
证据显示：输出可用性高（压缩后仍可检索原始内容）；边际价值明确（节省token）；成本效益有数据支持（节省百分比）。扣分：未提供独立验证，成本效益数据可能来自内部测试。
证据显示：README中的性能数据有基准测试和复现命令；有多个来源（README、pyproject、CI）相互印证；事实和推断区分清晰（如输出节省是估计值）。扣分：跨来源验证有限，未提供第三方独立验证。
- 代理会修改用户配置文件（如CLAUDE.local.md），请确保备份或了解撤销方法。
- 依赖外部模型下载（如HuggingFace），在离线或受限网络环境中可能无法正常工作。
- 发布者身份未验证，请谨慎使用，并检查代码和依赖的安全性。
这个 Agent 能做什么，适合哪些场景？
Headroom 是一个本地优先的上下文压缩层，用于 AI 代理，减少发送到 LLM 的标记数量，而不改变答案。它提供 Python 和 TypeScript 库、零代码代理、MCP 服务器以及跨代理共享内存。核心管道使用 ContentRouter 检测内容类型，然后使用 SmartCrusher 处理 JSON，基于 AST 的 CodeCompressor 处理代码，以及 Kompress-v2-base 模型处理文本。压缩是可逆的，通过 CCR 机制缓存原始内容，LLM 可按需检索。该项目支持通过代理与 Claude Code、Codex、Copilot、Cursor 等编码代理集成，并可透明地处理 Anthropic 和 OpenAI 兼容的 API。它还提供 headroom learn 工具，用于从失败会话中挖掘经验并写入 CLAUDE.md 等文件。
Headroom 在内容到达 LLM 之前运行多种操作。作为库，它提供了 compress() 函数，可直接处理消息。作为代理，它验证了 headroom proxy --port 8787 可为任何客户端提供一个兼容的代理。作为包装器，headroom wrap claude 启动一个本地代理，安装语义代码导航工具（如 Serena），并配置编码代理以路由流经 Headroom。它使用 ContentRouter 对输入进行分类，然后使用 SmartCrusher（JSON）、CodeCompressor（AST）或 Kompress-v2-base（文本）进行压缩。输出端的优化包括在需要时生成简洁的提示和减少推理努力的机制，由 HEADROOM_OUTPUT_SHAPER 控制。它启动一个 MCP 服务器，提供 headroom_compress、headroom_retrieve 和 headroom_stats 工具。它通过 headroom learn 从失败会话中挖掘经验，并将纠正记入 CLAUDE.md、AGENTS.md 或 GEMINI.md。
- 在日常开发中使用 Claude Code 或 Cursor 的编码员，希望减少 15-20% 的上下文标记，而不改变答案质量。
- 处理包含大量 JSON 数据的 SRE 或数据分析师，利用 SmartCrusher 实现 60-95% 的压缩。
- 负责 RAG 流程的开发者，希望在将大块文档发送给 LLM 之前压缩它们。
- 同时管理多个代理（如 Claude、Codex、Gemini）的工程师，希望通过跨代理内存实现共享上下文。
- 在 CI 环境中运行代理的团队，希望在此类工作负载上节省成本。
- 希望透明地与 Anthropic 或 OpenAI API 集成的开发者，通过 API 客户端适配器或代理。
这个 Agent 有哪些优点和局限？
- 本地优先且可逆：数据保留在机器上，通过 CCR 恢复原始内容。
- 内容感知压缩：为 JSON、代码和文本使用专门的压缩器（SmartCrusher、CodeCompressor、Kompress-v2-base）。
- 与流行代理无关：支持 Claude Code、Codex、Copilot、Cursor 等，通过代理模式提供 OpenAI 兼容。
- 输出端优化：减少模型写回的标记，包括说服力的语气引导和思考预算的减少。
- 跨代理共享内存：跨多个代理上下文共享，自动去重。
- 设置复杂性：包装代理时需要本地代理和配置，可能需要调试。
- Python 版本要求：对 Python 3.13+ 有需求，LiteLLM 需要 Python 3.13。
- 性能损失：压缩过程增加延迟。
- X86 平台需要 AVX2：一些没有 AVX2 的旧 CPU 无法获得节省收益，依赖 ONNX Runtime。
- 与托管压缩服务相比，提供分层功能需要额外设置。
如何安装或部署这个 Agent？
Headroom 可通过 pip 或 uv 安装为 Python 工具，并提供类型脚本 SDK。Python CLI 提供所有功能，TypeScript SDK 仅提供库功能。
如何使用这个 Agent？
安装后，您可以以不同模式运行 Headroom。 headroom proxy --port 8787 启动一个零代码代理。 headroom wrap claude 包装编码代理。 headroom deploy 提供一键部署。 headroom doctor 验证设置。