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 服务器 —— 为任何 MCP 客户端提供 headroom_compress、headroom_retrieve、headroom_stats
跨智能体记忆 —— 在 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]、[code]、[memory]、[relevance]、[image]、[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=...。

平台支持说明：macOS 通过 Copilot CLI Keychain 存储的身份验证重用已通过冒烟测试。Windows Credential Manager、Linux Secret Service / secret-tool 以及 Docker/CI token 注入路径已实现或计划作为身份验证发现路径，但在被视为完全验证之前仍需真实的 OS 验证。对于 Docker 和 CI，建议传递显式的 GITHUB_COPILOT_TOKEN 或 GITHUB_COPILOT_GITHUB_TOKEN，而不是依赖主机密钥链访问。

何时使用 · 何时跳过

非常适合你如果……

每天使用 AI 编码智能体，希望在不改动代码的情况下获得节省
在多个智能体之间工作，需要共享记忆
需要可逆压缩——通过 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 —— 针对 Python、JS、Go、Rust、Java、C++ 的 AST 感知压缩。
Kompress-base —— 我们的 HuggingFace 模型，在智能体轨迹上训练。