AI 編碼工具都在省 token？我找到了一個「無感壓縮」開源方案，省了 92%

AI 編碼工具都在省 token？我找到了一個「無感壓縮」開源方案，省了 92%

背景與痛點

我最近用 Claude Code 和 Codex 寫專案的時候，越來越感覺到一個問題：token 費用會隨著專案規模指數成長。

不是因為我變笨了，而是因為每個工具輸出、每次 API 呼叫回傳的資料量都在膨脹。一個 grep 指令可能回傳上千行結果，一次 git diff 可能帶著幾十個檔案的完整差異，再加上 RAG 檢索回來的 chunk、日誌檔案的原始內容……這些都塞進 context window 裡，而 LLM 的輸入端要錢。

我算過一筆帳：一個中等規模的 Python 專案，每天用 Claude Code 工作 8 小時，token 用量輕易突破 50 萬。以 Claude Sonnet 的輸入價格計算，一個月大概要燒掉幾百美金。如果用的是 Opus，這個數字會再翻五倍。

更討厭的是，很多內容其實「 compressible」。JSON 格式的工具輸出有重複的欄位名稱，AST 結構的程式碼有可預測的縮排模式，日誌檔案有大量標準化的時間戳和等級前綴。人類可以一眼看出這些是浪費，但 LLM 看不到。

所以當我看到 Headroom 這個專案的時候，我的第一反應是：這是不是又一個「吹得很厲害但實際上沒有差那麼多」的東西？

看完文檔和 benchmark 之後，我改變了想法。

Headroom 是什麼

Headroom 是一個開源的上下文壓縮層（context compression layer），專門針對 AI agent 和 LLM 應用設計。它的核心理念很直接：在資料送達 LLM 之前，把它壓縮到最小，但保持資訊不失真。

專案目前 58,746 stars，Apache 2.0 授權，Python 和 TypeScript 雙語言支援。由前 Anthropic 工程師建立，2026 年 1 月發布，不到半年就達到五萬星，成長速度非常驚人。

Headroom 提供三種使用模式：

1. Library：直接在你的程式碼裡呼叫 compress()，適合嵌入你自己的應用
2. Proxy：一個本地代理伺服器，零程式碼改動就能串接任何 LLM 客戶端
3. MCP Server：透過 Model Context Protocol 服務任何支援 MCP 的客戶端

它是怎麼做的

Headroom 的核心架構有三層：

ContentRouter 是入口。它先判斷資料的類型——是 JSON、程式碼、日誌、還是自然語言文本——然後選擇對應的壓縮器。

SmartCrusher 負責 JSON 資料。它能識別陣列、巢狀物件、混合類型，然後移除重複的欄位名稱、壓縮鍵值對。一個包含 100 筆資料庫查詢結果的 JSON，壓縮後可以小到只剩關鍵欄位和值。

CodeCompressor 處理程式碼。它會解析 AST（抽象語法樹），然後移除不必要的縮排、合併相似的程式碼片段、壓縮 import 語句。對 Python、JavaScript/TypeScript、Go、Rust 等語言都有支援。

還有一個 Kompress-v2-base 模型，這是 Headroom 自己訓練的壓縮模型，專門針對 agent 工作負載的文本優化。它不是簡單的 tokenizer 壓縮，而是理解語意的「語意壓縮」——同樣的意思可以用更少的 token 表達。

最後是 CacheAligner。這東西很聰明——它穩定化 prefix 部分，確保provider 的 KV cache 能命中。這意味著不僅壓縮後省 token，連 cache 命中帶來的速度提升和費用節省也一併拿到了。

整個流程是這樣的：

你的 agent → Headroom（本地運行，資料不出機器）→ 壓縮後的 prompt → LLM provider

而且壓縮是可逆的（CCR — Compressed Context Retrieval）。原始資料會緩存在本地，LLM 如果需要查證某個細節，可以透過 headroom_retrieve 工具找回原始內容。

Benchmark 數據

Headroom 的 benchmark 數據很有意思。他們在真實的 agent 工作負載上測試：

• 程式碼搜尋（100 筆結果）：從 17,765 token 壓縮到 1,408 token，節省 92%
• SRE 事故除錯：從 65,694 token 壓縮到 5,118 token，節省 92%
• GitHub issue 分類：從 54,174 token 壓縮到 14,761 token，節省 73%
• 程式碼庫探索：從 78,502 token 壓縮到 41,254 token，節省 47%

準確性方面也很不錯：GSM8K 數學測試前後都是 0.870（零落差），TruthfulQA 事實性測試從 0.530 提升到 0.560。SQuAD v2 和 BFCL 在 19-32% 壓縮率下保持 97% 的準確率。

這不只是理論數字。一個真實的場景是：10,144 token 的工具輸出，壓縮後變成 1,260 token，但 LLM 仍然能找到其中標示的 FATAL 錯誤。

如何開始使用

安裝

# 透過 uv 安裝（推薦）
uv tool install "headroom-ai[all]"

# 或者透過 pip
pip install "headroom-ai[all]"

需要 Python 3.10 以上。[all] 套件包含所有功能：代理伺服器、MCP 服務、ML 模型、程式碼壓縮器等。

第一種方式：Proxy（推薦新手）

Proxy 模式是最簡單的開始方式。它會啟動一個本地代理伺服器，攔截所有發往 LLM provider 的請求，在送達前進行壓縮：

# 啟動代理，port 8787
headroom proxy --port 8787

# 設定 LLM 客戶端使用代理
# Anthropic Claude SDK
export ANTHROPIC_BASE_URL=http://localhost:8787/v1

# 或者 OpenAI SDK
export OPENAI_BASE_URL=http://localhost:8787/v1

這樣你的所有 LLM 請求都會自動經過 Headroom 壓縮。不需要改任何程式碼。

第二種方式：Agent Wrap（推薦進階用戶）

如果你使用 Claude Code、Codex 或 Cursor 等編碼代理，可以用 wrap 命令一鍵設定：

# 包裝 Claude Code
headroom wrap claude

# 包裝 Codex
headroom wrap codex

# 包裝 Cursor（手動設定部分）
headroom wrap cursor

# 包裝 Copilot CLI
headroom wrap copilot --subscription

Wrap 命令會啟動本地代理、設定 MCP 服務、配置代理客戶端，然後啟動編碼代理。一次搞定。

第三種方式：Library（推薦整合到自己應用）

如果你有自己的 AI 應用，可以直接匯入壓縮函數：

from headroom import compress

# 壓縮 messages
compressed_messages = compress(messages, model="claude-sonnet-4-20250514")

# 壓縮後送給 LLM
response = anthropic_client.messages.create(
    model="claude-sonnet-4-20250514",
    messages=compressed_messages
)

TypeScript 版本：

import { compress } from 'headroom-ai';

const compressed = await compress(messages, { model: 'claude-sonnet-4-20250514' });

驗證壓縮效果

安裝完成後，可以用以下命令驗證：

# 健康檢查
headroom doctor

# 效能測試
headroom perf

# 即時節省儀表板
headroom dashboard

進階功能：Output Token 減少

Headroom 不只有輸入壓縮。它還能減少模型輸出的 token。這對使用 Opus 等昂貴模型的用戶特別重要——輸出價格通常是輸入的五倍。

啟用方法：

export HEADROOM_OUTPUT_SHAPER=1
headroom proxy --port 8787

它會做兩件事：

1. 冗餘引導：在系統提示詞末尾加上「精簡回答、不要重複內容」的指示（確保 prompt cache 命中）
2. effort 路由：當一個回合只是模型在工具執行後繼續（如讀取檔案、通過測試），自動降低模型的「思考程度」

支援的框架

Headroom 支援非常廣泛的框架：

| 框架 | 支援方式 |

|------|----------|

| Anthropic SDK | 內建 |

| OpenAI SDK | 內建 |

| LangChain | HeadroomChatModel |

| LiteLLM | HeadroomCallback |

| Agno | HeadroomAgnoModel |

| Vercel AI SDK | wrapLanguageModel middleware |

| FastAPI | ASGI 中間件 |

| 任何 MCP 客戶端 | headroom mcp install |

| Claude Code / Codex / Cursor / Copilot | headroom wrap |

限制與注意事項

什麼時候不適合用 Headroom：

• 如果你只用單一 provider 的原生壓縮功能，且不需要跨代理記憶體共享
• 如果你在沙箱環境中，本地進程無法運行
• 對壓縮率要求極度嚴格的工作負載——某些高度結構化的資料可能壓縮空間有限

需要注意的技術限制：

• 壓縮是「有損」的：雖然 benchmark 顯示準確性幾乎不受影響，但在極端情況下，壓縮後可能遺漏一些邊緣案例的細節
• CCR 可逆壓縮有 TTL 限制：原始資料會緩存一段時間，超時後就無法找回
• x86 處理器需要 AVX2 指令集才能使用完整的 ONNX 功能（ARM64 / Apple Silicon 無此限制）
• 企業網路如果用了 SSL 檢查（MITM proxy），可能需要額外的 TLS 設定

成本方面：

Headroom 本身是免費開源軟體（Apache 2.0）。但使用 Kompress-v2-base 模型需要下載 ONNX Runtime（約幾百 MB），以及壓縮模型本身。本地運行不需要額外費用，但如果用他們的企業託管服務則有費用。

我的判斷

我為什麼認為 Headroom 值得關注？

因為它解決了一個真實且日益嚴重的問題。隨著 AI agent 變得越來越強大，它們需要處理的上下文也越來越多。一個 agent 一天可能讀取數百個檔案、執行數十次 shell 指令、處理無數的 API 回應。這些都是 token 成本。

Headroom 的聰明之處在於，它不是「簡單地截斷」上下文——那樣會丟失重要資訊。它是理解內容結構後進行智慧壓縮。JSON 壓縮會保留欄位結構但移除重複，程式碼壓縮會理解語法但移除不必要的空白，文本壓縮會保留語意但精簡表達。

而且它的可逆設計很重要。壓縮後的資料不是「丟掉了」，而是「暫時藏起來了」。LLM 如果需要，隨時可以找回原始內容。這是一個非常務實的工程決策。

從生態系的角度看，Headroom 也展現了強大的網路效應。從它的周邊項目可以發現：已經有人為它寫了 Zed 擴展、Swift 封裝、Go 實作、Web 儀表板、甚至日本語版本的規則重實作。這表示它正在成為這個領域的基礎設施。

結論

如果你每天都在使用 Claude Code、Codex、Cursor 或其他 AI 編碼工具，Headroom 可能是你今年最需要安裝的工具之一。

它不需要你改程式碼（Proxy 模式），不需要你改工作流程（Agent Wrap 模式），也不需要你理解壓縮原理（它自動處理）。你只需要安裝、啟動、然後繼續工作。省下來的就是真金白銀。

58,746 顆星不是白來的。

參考資料

• Headroom GitHub 倉庫
• Headroom 官方文件
• Kompress-v2-base 模型（HuggingFace）
• Headroom 代理伺服器文件
• CCR 可逆壓縮說明
• Headroom Benchmark 頁面