Headroom – AI智能體的上下文壓縮層

Headroom 是一個開源的上下文壓縮層，專為 AI 智能體設計。它能在智能體讀取工具輸出、日誌、RAG 塊、文件和對話歷史之前進行壓縮，顯著減少發送給大語言模型的 token 數量，同時保持答案的準確性和完整性。根據實際測試，壓縮率可達 60-95%，例如在代碼搜索場景中，token 從 17,765 降至 1,408（節省 92%）；在 SRE 事故調試中，從 65,694 降至 5,118（節省 92%）。

Headroom 提供多種使用模式，以適應不同的開發環境：

• 庫模式：在 Python 或 TypeScript 應用中直接調用 compress(messages) 函數。
• 代理模式：通過 headroom proxy --port 8787 啓動一個 HTTP 代理，無需修改代碼即可集成。
• 智能體封裝：支持 headroom wrap claude|codex|cursor|aider|copilot 等命令，一鍵包裝常用 AI 智能體。
• MCP 服務器：提供 headroom_compress、headroom_retrieve、headroom_stats 工具，供任何 MCP 客户端使用。

Headroom 的核心機制包括內容路由器（ContentRouter），它能自動檢測內容類型並選擇最佳壓縮器（如 SmartCrusher 處理 JSON、CodeCompressor 進行 AST 感知壓縮、Kompress-base 處理文本）。緩存對齊器（CacheAligner）穩定前綴以利用供應商的 KV 緩存，可逆壓縮（CCR）將原始數據本地存儲，LLM 可在需要時通過 headroom_retrieve 檢索。

此外，Headroom 還支持輸出 token 縮減（Output Token Reduction），通過向系統提示添加簡潔指令和降低例行步驟的思考深度，減少模型生成的冗餘內容。該功能默認關閉，可通過環境變量 HEADROOM_OUTPUT_SHAPER=1 啓用。Headroom 還能智能學習用户的偏好，通過 headroom learn --verbosity 自動設定合適的簡潔程度。

Headroom 與多種主流框架和工具集成，包括 Anthropic SDK、OpenAI SDK、Vercel AI SDK、LiteLLM、LangChain、Agno 等。對於 GitHub Copilot CLI 訂閲用户，Headroom 提供了專門的認證和路由支持。

項目已在 GitHub 開源，擁有超過 45,000 個星標和 3,200 個分叉。安裝簡單，支持 pip 和 npm，需要 Python 3.10+ 或 Node.js 環境。