以下是翻译后的中文内容，已按照要求保留原文结构、代码块、技术术语和专有名词，并忽略无关文本：
chopratejas headroom
██╗ ██╗███████╗ █████╗ ██████╗ ██████╗ ██████╗ ██████╗ ███╗ ███╗ ██║ ██║██╔════╝██╔══██╗██╔══██╗██╔══██╗██╔═══██╗██╔═══██╗████╗ ████║ ███████║█████╗ ███████║██║ ██║██████╔╝██║ ██║██║ ██║██╔████╔██║ ██╔══██║██╔══╝ ██╔══██║██║ ██║██╔══██╗██║ ██║██║ ██║██║╚██╔╝██║ ██║ ██║███████╗██║ ██║██████╔╝██║ ██║╚██████╔╝╚██████╔╝██║ ╚═╝ ██║ ╚═╝ ╚═╝╚══════╝╚═╝ ╚═╝╚═════╝ ╚═╝ ╚═╝ ╚═════╝ ╚═════╝ ╚═╝ ╚═╝
面向 AI 智能体的上下文压缩层，减少 60–95% 的 token · 库 · 代理 · MCP · 6 种算法 · 本地优先 · 可逆
文档 · 安装 · 验证 · 智能体 · Discord · llms.txt
AI 智能体 / LLM：在此处阅读 /llms.txt，或获取实时索引 / 完整文档 blob。
Headroom 在你 AI 智能体读取的所有内容（工具输出、日志、RAG 块、文件和对话历史）到达 LLM 之前对其进行压缩。答案不变，token 数量大幅减少。
实时示例：10,144 → 1,260 个 token —— 相同的 FATAL 错误被找到。
功能
- 库 —— 在 Python 或 TypeScript 中调用
compress(messages)，内联到任何应用中 - 代理 ——
headroom proxy --port 8787，零代码改动，支持任何语言 - 智能体封装 ——
headroom wrap claude|codex|cursor|aider|copilot，一条命令搞定 - MCP 服务器 ——
headroom_compress、headroom_retrieve、headroom_stats，适用于任何 MCP 客户端 - 跨智能体记忆 —— 在 Claude、Codex、Gemini 之间共享存储，自动去重
- headroom learn —— 挖掘失败的会话，将修正写入
CLAUDE.md/AGENTS.md - 可逆（CCR） —— 原始数据永不删除；LLM 按需检索
工作原理（30 秒）
你的智能体 / 应用（Claude Code、Cursor、Codex、LangChain、Agno、Strands、你自己的代码…）
│ 提示词 · 工具输出 · 日志 · RAG 结果 · 文件
▼
┌────────────────────────────────────────────────────┐
│ Headroom（本地运行 —— 你的数据保留在此处） │
│ ──────────────────────────────────────────────── │
│ CacheAligner → ContentRouter → CCR │
│ ├─ SmartCrusher（JSON） │
│ ├─ CodeCompressor（AST） │
│ └─ Kompress-base（文本，HF） │
│ │
│ 跨智能体记忆 · headroom learn · MCP │
└────────────────────────────────────────────────────┘
│ 压缩后的提示词 + 检索工具
▼
LLM 提供商（Anthropic · OpenAI · Bedrock · …）- ContentRouter —— 检测内容类型，选择正确的压缩器
- SmartCrusher / CodeCompressor / Kompress-base —— 压缩 JSON、AST 或散文
- CacheAligner —— 稳定前缀，使提供商的 KV 缓存真正命中
- CCR —— 本地存储原始数据；LLM 在需要时调用
headroom_retrieve
→ 架构 · CCR 可逆压缩 · Kompress-base 模型卡
快速开始（60 秒）
# 1 — 安装
pip install "headroom-ai[all]" # Python
npm install headroom-ai # Node / TypeScript
# 2 — 选择模式
headroom wrap claude # 封装一个编码智能体
headroom proxy --port 8787 # 即时代理，零代码改动
# 或：from headroom import compress # 内联库
# 3 — 查看节省效果
headroom perf额外组件：[proxy]、[mcp]、[ml]、[agno]、[langchain]、[evals]。需要 Python 3.10+。
验证
在真实智能体工作负载上的节省效果：
| 工作负载 | 压缩前 | 压缩后 | 节省比例 | | --- | --- | --- | --- | | 代码搜索（100 个结果） | 17,765 | 1,408 | 92% | | SRE 故障调试 | 65,694 | 5,118 | 92% | | GitHub issue 分类 | 54,174 | 14,761 | 73% | | 代码库探索 | 78,502 | 41,254 | 47% |
在标准基准测试上保持准确率：
| 基准测试 | 类别 | N | 基线 | Headroom | 差异 | | --- | --- | --- | --- | --- | --- | | GSM8K | 数学 | 100 | 0.870 | 0.870 | ±0.000 | | TruthfulQA | 事实性 | 100 | 0.530 | 0.560 | +0.030 | | SQuAD v2 | 问答 | 100 | — | 97% | 19% 压缩 | | BFCL | 工具 | 100 | — | 97% | 32% 压缩 |
复现：python -m headroom.evals suite --tier 1 · 完整基准测试与方法论
智能体兼容性矩阵
| 智能体 | headroom wrap | 备注 | | --- | --- | --- | | Claude Code | ● | --memory · --code-graph | | Codex | ● | 与 Claude 共享记忆 | | Cursor | ● | 打印配置 —— 粘贴一次即可 | | Aider | ● | 启动代理 + 启动 | | Copilot CLI | ● | 启动代理 + 启动 | | OpenClaw | ● | 作为 ContextEngine 插件安装 |
任何兼容 OpenAI 的客户端均可通过 headroom proxy 使用。MCP 原生：headroom mcp install。
GitHub Copilot CLI 订阅模式
Headroom 可以通过本地代理路由 GitHub Copilot CLI 订阅流量：
headroom wrap copilot --subscription -- --model gpt-4o这使 Headroom 能够拦截兼容 OpenAI 的 Copilot CLI 请求，在转发到 GitHub Copilot 托管 API 之前应用相同的代理压缩管道。该封装器会解析账户特定的 Copilot API 端点，并在启动时将其打印为 COPILOT_PROVIDER_API_URL=...。
平台支持说明：通过 Copilot CLI Keychain 存储进行 macOS 认证复用已通过冒烟测试。Windows Credential Manager、Linux Secret Service / secret-tool 以及 Docker/CI token 注入路径已实现或计划作为认证发现路径，但在被认为完全可靠之前仍需真实操作系统验证。对于 Docker 和 CI，建议显式传递 GITHUB_COPILOT_TOKEN 或 GITHUB_COPILOT_GITHUB_TOKEN，而不是依赖主机 keychain 访问。
何时使用 · 何时跳过
非常适合你，如果…
- 你每天运行 AI 编码智能体，希望在不修改代码的情况下节省 token
- 你在多个智能体之间工作，需要共享记忆
- 你需要可逆压缩 —— 通过 CCR 始终可检索原始数据
跳过它，如果…
- 你只使用单一提供商的原生压缩功能，不需要跨智能体记忆
- 你在沙盒环境中工作，无法运行本地进程
集成 —— 将 Headroom 放入任何技术栈
| 你的设置 | 接入方式 | | --- | --- | | 任何 Python 应用 | compress(messages, model=…) | | 任何 TypeScript 应用 | await compress(messages, { model }) | | Anthropic / OpenAI SDK | withHeadroom(new Anthropic()) · withHeadroom(new OpenAI()) | | Vercel AI SDK | wrapLanguageModel({ model, middleware: headroomMiddleware() }) | | LiteLLM | litellm.callbacks = [HeadroomCallback()] | | LangChain | HeadroomChatModel(your_llm) | | Agno | HeadroomAgnoModel(your_model) | | Strands | Strands 指南 | | ASGI 应用 | app.add_middleware(CompressionMiddleware) | | 多智能体 | SharedContext().put / .get | | MCP 客户端 | headroom mcp install |
内部组件
- SmartCrusher —— 通用 JSON：字典数组、嵌套对象、混合类型。
- CodeCompressor —— 基于 AST，支持 Python、JS、Go、Rust、Java、C++。
- Kompress-base —— 我们的 HuggingFace 模型，基于智能体轨迹训练。
- 图像压缩 —— 通过训练的 ML 路径实现 40–90% 的压缩率。