Headroom：在智慧體讀取的工具輸出、日誌和檔案進入大模型之前先做本地壓縮，並可按需取回原文

headroomlabs-ai/headroom 是一個用 Python 寫的開源專案，採用 Apache-2.0 許可，建立於 2026 年 1 月 7 日，最近一次推送是 10 月 13 日，截至發稿約有 75,257 個星標和 5,838 個分叉。它的定位只有一句話：在智慧體讀到的一切內容進入大模型之前先壓縮，包括工具輸出、日誌、檢索片段、檔案和對話歷史，“答案不變，詞元只剩一小部分”。README 還強調壓縮在本機進行，沒有提示或檔案內容會被髮到別處去壓縮。它要解決的是智慧體使用中很常見的一種浪費：一次搜尋返回上百條結果，一段日誌裡同一行重複上千次，這些內容進入上下文後既佔視窗，又按詞元計費。 它的架構由三個環節組成。ContentRouter 先判斷內容型別並選擇壓縮器：SmartCrusher 處理 JSON，CodeCompressor 基於語法樹處理原始碼，Kompress-v2-base 處理普通文字；CacheAligner 則只負責標出會破壞供應商 KV 快取字首的易變內容，README 說它從不改寫提示。最關鍵的是 CCR，即可逆壓縮：原文快取在本地，模型需要完整文字時可以呼叫 headroom_retrieve 取回。這個設計回應了壓縮最常見的擔憂，資訊丟了怎麼辦。接入也靈活：既可以在程式碼裡呼叫 compress(messages)，也可以用 headroom proxy 起一個代理，不用改應用程式碼，或者直接 headroom wrap claude、codex、cursor、aider 等一長串程式設計智慧體，甚至作為 MCP 伺服器暴露三個工具。

專案還提供幾項相關功能。其一是跨智慧體的共享記憶：在 Claude、Codex、Gemini 和 Grok 之間共用一個儲存並自動去重。其二是 headroom learn，它會分析失敗的會話，把糾正寫到 CLAUDE.local.md（預設，且不入庫）、CLAUDE.md、AGENTS.md、GEMINI.md 或 GROK.md 裡。其三是輸出詞元削減：除了壓縮發出去的內容，還從代理側削減模型寫回的內容，辦法是“冗長度引導”，即在系統提示末尾加一小段“請簡潔，不要重複上下文”的說明，使提示快取仍能命中；以及“推理強度路由”，當某一輪只是模型在工具結果後繼續工作時，降低思考強度，而新問題和錯誤保持完整強度。README 提到在 Opus 級模型上輸出成本是輸入的 5 倍，所以這一塊有實際意義。 資料方面，README 的基準用四個由真實 MCP 伺服器輸出格式構造、種子固定的場景：程式碼搜尋（100 個結果）17,199 降到 13,597，節省 21%；SRE 故障排查 55,957 降到 24,340，節省 57%；程式碼庫探索 58,801 降到 33,895，節省 42%；GitHub 議題分診 46,067 降到 32,429，節省 30%。專案說明節省比例取決於內容的重複程度：重複的 JSON 陣列和日誌行在延遲基準中可超過 90%，而文章和本來就很密的輸出幾乎壓不動。壓縮耗時很短，10K 詞元的 JSON 搜尋結果中位數 0.21 毫秒，100K 詞元為 1.4 毫秒。準確率方面，樣本數 100 的 GSM8K 基線和使用後都是 0.870，TruthfulQA 從 0.530 到 0.560，專案自己指出這在置信區間內，應理解為沒有檢測到差異。SQuAD v2 達到 97%（壓縮 19%），BFCL 達到 97%（壓縮 32%）。

怎麼用才穩妥？第一，所有數字都是專案自述的基準，樣本也不大，應當先用 headroom savings 在自己的真實流量上看節省比例，再決定是否上線；對已經很緊湊的輸出，不要期待大的收益。第二，headroom wrap 並不只是“包一層”：它會啟動本地代理，並給被包裝的專案安裝 Serena 做語義程式碼導航，對 Claude Code 是在 ~/.claude.json 裡登記一個本地範圍的 MCP 伺服器；要撤銷用 headroom unwrap，若不想要可以用引數跳過。第三，原文雖然在本地快取，但壓縮過的內容才是模型看到的，除錯智慧體行為時要記得這一點。總體上，它是一個思路清楚、可逆、容易試的成本最佳化工具，適合先在測試環境裡評估。 再補充幾個選型時容易忽略的點。一是快取的取捨：壓縮會改變發給模型的文字，如果你的供應商按字首快取計費，需要確認壓縮結果在多輪對話裡是穩定的，否則可能省了詞元卻丟了快取命中，這正是專案專門設計 CacheAligner 的原因，但效果仍應以自己的賬單為準。二是可觀測性：先用 headroom perf 和 headroom dashboard 看幾天真實的節省資料，再決定是否把代理放進團隊共用的環境。三是適用範圍：它最擅長處理大段重複的結構化輸出，比如搜尋結果、日誌和事故排查；如果你的智慧體主要讀短小的自然語言，收益會明顯變小。把這三點想清楚，再去試，會少走很多彎路。 最後值得一提的是資料去向與可審計性。README 強調壓縮在本機完成，不會把提示或檔案內容送去別處，這對處理內部程式碼和日誌的團隊很重要；同時，因為可以用 headroom_stats 檢視節省統計、用 headroom_retrieve 取回原文，出了問題時能追溯模型當時看到的到底是什麼。把這兩點和前面的基準結合起來看，Headroom 更像一個可以先小範圍接入、再逐步放開的基礎設施元件。