Headroom：你的 AI Agent 迫切需要的上下文壓縮層

Token 的問題是真實的——而且越來越嚴重

如果你曾經在生產環境中構建或運行過 AI Agent，你一定懂那種感覺。Agent 呼叫搜尋工具，拿回 500 筆結果。讀取一個日誌檔案，拿回 10,000 行內容。查詢資料庫，拿回一個小說大小的 JSON 資料塊。所有這些都被塞進 LLM 的上下文視窗——你眼睜睜看著 token 數量爆炸、延遲膨脹，API 帳單悄悄失控。

這不是什麼邊緣案例，這是 2025–2026 年 AI Agent 的日常現實。工具輸出冗長，日誌充滿雜訊，RAG 檢索不夠精準。而 LLM，儘管才華橫溢，卻出奇地不擅長忽略無關資訊——你給它什麼，它就讀什麼，不管重不重要。

GitHub 上 chopratejas/headroom 這個開源專案，由 Tejas Chopra 所創建的 Headroom，正是專門為了解決這個問題而生。而且它的解法，在技術上既優雅，在實踐上又出奇地務實。

---

Headroom 是什麼？

Headroom 將自己定位為**「AI Agent 的上下文壓縮層」**。用白話說：它坐落在你的應用程式與 LLM 供應商之間，攔截所有流入模型上下文視窗的內容，智慧地壓縮它，然後轉發一個更精簡、更乾淨的提示詞。LLM 獲得的是相同的語義——只是用了少得多的 token。

數字令人印象深刻：

更關鍵的是——準確性得以保留。在 GSM8K 等標準基準測試上，Headroom 壓縮後的提示詞與未壓縮版本產生相同的正確答案。

---

它究竟如何運作

這才是 Headroom 真正有趣的地方。它不只是「去掉空白行、刪除重複內容」那麼簡單。壓縮管道是多階段、感知內容類型的。

第一階段：CacheAligner（快取對齊器）

在任何壓縮發生之前，Headroom 先穩定你的系統提示詞。它偵測動態內容——時間戳記、Session Token、UUID——並將它們移到提示詞的末尾，而非嵌在中間。為什麼？因為 Anthropic 和 OpenAI 等供應商使用前綴快取——如果你的提示詞開頭在多次呼叫間保持一致，供應商就能重用已快取的 KV 計算，大幅降低費用。一個嵌在系統提示詞中間、每天都在變動的時間戳記，正在悄悄讓你的每一次 API 呼叫都快取失效。CacheAligner 以毫秒以下的開銷修復了這個問題。

第二階段：SmartCrusher（智慧壓碎器）

這是最重要的核心。當你的 Agent 返回一個包含 1,000 筆日誌的 JSON 陣列時，SmartCrusher 不會隨機抽取 20 筆。它對每個欄位進行統計分析——衡量方差、唯一性和變化點。它使用 Kneedle 演算法在二元組覆蓋率上選取具代表性的子集。最關鍵的是，它無條件保留錯誤、異常值和分佈邊界——這些正是 LLM 診斷問題時最需要的項目。

保留策略設計得很周到：30% 來自陣列開頭（用於理解資料結構），15% 來自末尾（用於時效性），55% 按計算出的重要性分數選取。錯誤項目無論預算如何，永遠會被保留。

對於程式碼，它使用 AST 感知壓縮——保留函式簽名、折疊函式主體。對於 HTML，使用文章提取。對於日誌，使用模式聚類。每種內容類型都有對應的最佳工具。

第三階段：Context Manager（上下文管理器）

對於可能超出上下文視窗的長對話，Headroom 提供兩種模式。預設的滾動視窗模式優先丟棄最舊的訊息（保留系統提示詞和最近的對話輪次）。進階的智慧上下文模式則從六個維度對每條訊息評分——時效性、語義相似度、錯誤指標、前向引用、token 密度，以及一個名為 TOIN 的學習型重要性訊號——然後優先丟棄得分最低的訊息。

---

殺手級功能：CCR（壓縮-快取-檢索）

Headroom 最具哲學意義的部分，是它對一個顯而易見質疑的回答：「如果 LLM 需要你壓縮掉的那些資料怎麼辦？」

答案是 CCR——Compress-Cache-Retrieve（壓縮-快取-檢索）。每次 Headroom 壓縮某些內容時，它都會將原始資料儲存在本地的 SQLite 快取中，並在壓縮後的輸出中注入一個檢索標記：

[1000 items compressed to 20. Retrieve more: hash=abc123]

它同時向 LLM 的可用工具中注入一個 headroom_retrieve 工具。如果模型判斷需要完整資料，只需用該 hash 呼叫這個工具——約 1 毫秒後就能取回原始資料。客戶端應用程式對此完全無感，一切透明處理。

更聰明的是：LLM 不必取回全部資料。它可以傳入一個可選的 query 參數，Headroom 就會在快取項目上執行 BM25 搜尋，只返回相關的子集。壓縮因此不僅是激進的，更是真正可逆且可查詢的。

這優雅地消除了傳統壓縮的兩難困境。你不再需要在「節省 token」和「保留資訊」之間做選擇——你可以兩者兼得。

---

四種使用方式

Headroom 設計為在任何場景下都能無縫接入：

• 函式庫模式 — 在 Python 或 TypeScript 中直接呼叫 compress(messages)，兩行程式碼搞定。
• 代理模式 — headroom proxy --port 8787，零程式碼修改，只需將現有 LLM 客戶端指向新的 base URL。
• Agent 包裝模式 — headroom wrap claude 或 headroom wrap cursor，一個命令包裝整個程式碼 Agent。
• MCP 伺服器模式 — 將 headroom_compress、headroom_retrieve、headroom_stats 作為 MCP 工具暴露給任何 MCP 相容客戶端。

它也原生整合了 LangChain、Agno、Strands、LiteLLM 和 Vercel AI SDK。

---

為何重要

Headroom 的意義遠不止於節省 API 費用（儘管 73–92% 的 token 節省確實相當可觀）。有三個更深層的原因讓這個專案值得重視：

一、讓 Agent 更可靠。

嘈雜、臃腫的上下文是 LLM 推理錯誤的主要原因之一。當你把 65,000 個 token 的日誌餵給模型，而其中只有 500 個 token 真正重要，你是在讓它大海撈針。Headroom 直接把針遞給它。

二、有效提升上下文天花板。

128K 的上下文視窗聽起來很大，直到你的 Agent 開始做真正的工作。有了 90% 的壓縮率，同樣的視窗在實踐中等效於 128 萬 token 的視窗。Agent 可以處理更長的任務、更深的程式碼庫、更豐富的歷史記錄。

三、本地優先，保護隱私。

所有壓縮和快取都在你自己的機器上完成。你的資料在到達 LLM 之前，不會離開你的基礎設施——只有壓縮後的輸出才會被發送出去。對於資料敏感性至關重要的企業使用場景，這一點意義重大。

---

結語

Headroom 是那種解決了一個如此根本性問題、讓你不禁想問「為什麼這麼晚才出現」的專案。上下文視窗不是免費的——每一個 token 都有時間、金錢和注意力的代價。Headroom 將其視為一個值得嚴肅對待的工程問題，用統計方法、AST 解析、學習型模式和可逆快取來解決它——而不是幾行正則表達式了事。

在 GitHub 上已獲得超過 23,400 顆星並持續增長，社群的眼光顯然是準確的。如果你在 2026 年正在構建任何涉及 AI Agent 的東西，Headroom 值得你認真研究一番。