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 環境。