Headroom 完整教學 — AI Agent Context Compression Layer

1. 專案定位

Headroom 是一套 AI agent 的 context compression (上下文壓縮) layer (層)，目標是把 LLM 收到的所有輸入——tool output (工具輸出)、log (日誌)、RAG chunk (檢索增強生成區塊)、檔案內容、對話歷史——在送達 LLM provider 之前進行智慧壓縮，達成 60–95% 的 token (語元) 節省，同時維持回答品質不變。

為什麼需要 Headroom？

AI coding agent（如 Claude Code、Codex、Cursor）在工作時會大量讀取檔案、grep 結果、git log、test output 等，這些原始內容動輒數萬 token。大部分資訊是重複或低價值的（例如 100 條 search result 中可能只有 3 條相關）。Headroom 在資料進入 LLM 前壓縮，讓 agent 在相同的 context window (上下文視窗) 內能處理更多資訊，同時降低 API 費用。

核心定位

專案規模

• Stars: 10,724 · Forks: 703
• 授權: Apache License 2.0
• 版本: v0.22.4（2026-06-01）
• 架構: Python + Rust 混合（核心壓縮引擎已遷移至 Rust via PyO3）
• 檔案數: 500+ 檔案，涵蓋 benchmarks / crates / docs / e2e / examples / plugins / sdk / tests

2. 安裝指南

2.1 Python 安裝

 1# 完整安裝（推薦）
 2pip install "headroom-ai[all]"
 3
 4# 最小安裝 + 按需 extras
 5pip install headroom-ai                    # 核心 library
 6pip install "headroom-ai[proxy]"           # + FastAPI proxy server
 7pip install "headroom-ai[mcp]"             # + MCP server
 8pip install "headroom-ai[ml]"              # + Kompress-base ML 模型
 9pip install "headroom-ai[agno]"            # + Agno 整合
10pip install "headroom-ai[langchain]"       # + LangChain 整合
11pip install "headroom-ai[evals]"           # + 評估工具

系統需求: Python 3.10+。Rust extension (擴充) 以 prebuilt wheel 發佈，大部分平台直接 pip install 即可。

2.2 pipx 安裝

1# 需明確指定 Python 版本
2pipx install --python python3.13 "headroom-ai[all]"

2.3 TypeScript / Node.js 安裝

1npm install headroom-ai

2.4 Docker 安裝

1docker pull ghcr.io/chopratejas/headroom:latest
2
3# 以容器執行 proxy
4docker run -p 8787:8787 ghcr.io/chopratejas/headroom:latest proxy

2.5 從原始碼安裝（開發者）

1git clone https://github.com/chopratejas/headroom.git && cd headroom
2pip install -e ".[dev]"
3# Rust extension 需要：
4bash scripts/build_rust_extension.sh   # 內部呼叫 maturin develop
5pytest                                  # 驗證安裝

2.6 驗證安裝

1headroom --version        # 應顯示 0.22.4
2headroom perf             # 顯示 token 節省統計

3. 核心架構解析

Headroom 的架構分為三大層次：輸入層（接收來自各 agent / 框架的請求）、壓縮管線（偵測 → 路由 → 壓縮 → 快取對齊）、輸出層（送壓縮後的 prompt 至 LLM provider）。

flowchart TD
    subgraph Input["輸入層 — Agent / Framework"]
        CC[Claude Code]
        CX[Codex]
        CU[Cursor]
        AD[Aider]
        LC[LangChain]
        OA[自建 App]
    end

    subgraph Headroom["壓縮管線 — Headroom 核心"]
        CA[CacheAligner
prefix 穩定化]
        CR[ContentRouter
內容偵測 + 路由]
        SC[SmartCrusher
JSON 壓縮 — Rust]
        CodeC[CodeCompressor
AST 壓縮 — tree-sitter]
        KB[Kompress-base
文本壓縮 — HF 模型]
        CCR[CCR Store
原始內容快取]
        MEM[Cross-Agent Memory
跨 agent 記憶共享]
    end

    subgraph Output["輸出層 — LLM Provider"]
        AN[Anthropic]
        OI[OpenAI]
        BR[AWS Bedrock]
        GG[Google Gemini]
    end

    CC & CX & CU & AD & LC & OA --> CA
    CA --> CR
    CR --> SC
    CR --> CodeC
    CR --> KB
    SC & CodeC & KB --> CCR
    CCR --> MEM
    MEM --> Output

3.1 壓縮管線生命週期

Headroom 定義了一條 canonical pipeline lifecycle (標準管線生命週期)，所有模式（library / proxy / SDK）共用：

1Setup → Pre-Start → Post-Start → Input Received → Input Cached →
2Input Routed → Input Compressed → Input Remembered → Pre-Send →
3Post-Send → Response Received

每個 stage (階段) 都可透過 PipelineExtension protocol (協定) 掛載 observer (觀察者) 或 customizer (客製化器)。

3.2 核心壓縮器

3.3 CCR (Compress-Cache-Retrieve) 可逆壓縮

CCR 是 Headroom 的核心差異化特性。壓縮時，原始內容存入本地 store，壓縮後的版本附帶 hash reference。若 LLM 判斷需要原始內容，可呼叫 headroom_retrieve tool 取回。這由 proxy 自動攔截處理：

1. Tool Injection — proxy 在請求中注入 headroom_retrieve tool definition
2. Response Handler — 攔截 LLM 回應中的 CCR tool call，自動從本地 store 取回並繼續對話
3. Context Tracker — 追蹤跨 turn 的壓縮內容，支援 proactive expansion (主動展開)

3.4 跨 Agent 記憶

Headroom 的 memory 模組提供跨 agent 記憶共享。Claude Code 中學到的知識可在 Codex session 中自動取用。記憶以 SQLite 或 Qdrant 作為 backend (後端)，支援自動去重、agent provenance (來源追蹤)、budget-aware injection (預算感知注入)。

4. 使用模式詳解

4.1 Library 模式（最簡）

 1from headroom import compress
 2
 3messages = [
 4    {"role": "user", "content": "分析這段 log"},
 5    {"role": "tool", "content": huge_log_output}
 6]
 7
 8result = compress(messages, model="claude-sonnet-4-5-20250929")
 9# result.messages          → 壓縮後的 messages（格式不變）
10# result.tokens_saved      → 節省的 token 數
11# result.compression_ratio → 例：0.35 表示節省 65%

支援 Anthropic SDK、OpenAI SDK、LiteLLM 等任何框架。

4.2 Proxy 模式（零改碼）

1# 啟動 proxy
2headroom proxy --port 8787
3
4# 任何語言、任何框架，只需改 base URL
5ANTHROPIC_BASE_URL=http://127.0.0.1:8787 claude
6OPENAI_BASE_URL=http://127.0.0.1:8787/v1 your-app

Proxy 模式透過 FastAPI 實作，攔截所有 LLM API 請求，壓縮後轉發。支援 streaming (串流)、batch API、WebSocket。

4.3 Agent Wrap 模式（一鍵啟動）

 1headroom wrap claude                    # Claude Code
 2headroom wrap codex                     # OpenAI Codex
 3headroom wrap cursor                    # Cursor（印出設定指示）
 4headroom wrap aider                     # Aider
 5headroom wrap copilot                   # GitHub Copilot CLI
 6headroom wrap openclaw                  # OpenClaw plugin
 7
 8# 附加選項
 9headroom wrap claude --memory           # 啟用跨 agent 記憶
10headroom wrap claude --code-graph       # 啟用程式碼知識圖
11headroom wrap claude --port 9999        # 自訂 proxy port
12headroom wrap claude -- --model opus    # 傳遞參數給 claude

headroom wrap 自動啟動 proxy server + CLI context tool (RTK / lean-ctx) + 目標 agent。

4.4 MCP Server 模式

1headroom mcp install          # 安裝到支援 MCP 的 client
2
3# 提供三個 MCP tool：
4# - headroom_compress:   壓縮指定內容
5# - headroom_retrieve:   從 CCR store 取回原始內容
6# - headroom_stats:      查看壓縮統計

4.5 Framework 整合

5. 應用場景

5.1 AI Coding Agent 的日常使用

最典型的使用場景。開發者每天使用 Claude Code 或 Codex 時，大量 tool output（檔案內容、搜尋結果、test output）消耗 context window。Headroom wrap 一鍵啟動後，所有輸出自動壓縮。

實測數據：

5.2 多 Agent 協作

在 multi-agent workflow (多 agent 工作流) 中，不同 agent 會共用相同的 context。Headroom 的 SharedContext 模組壓縮跨 agent 傳遞的上下文，而 cross-agent memory 讓 Claude 學到的模式自動供 Codex 使用。

5.3 RAG Pipeline 最佳化

RAG 系統取回的文件 chunk 通常包含大量冗餘。Headroom 的 ContentRouter 偵測到 RAG chunk 後，用 Kompress-base 模型進行語義壓縮，保留關鍵資訊同時大幅減少 token 用量。

5.4 Production LLM Application 降本

任何呼叫 LLM API 的 production app 都可透過 Headroom proxy 降低 API 費用。以 ASGI middleware 或 SDK wrapper 的方式整合，不需改動業務邏輯。

5.5 headroom learn — 從失敗中學習

1headroom learn                           # 掃描失敗 session
2headroom learn --agent claude            # 只掃 Claude session
3headroom learn --agent codex             # 只掃 Codex session

headroom learn 挖掘 agent 的失敗 session log，分析失敗模式，自動寫入修正規則到 CLAUDE.md / AGENTS.md / GEMINI.md。支援 plugin (外掛) 架構，可擴充分析器。

6. 資安掃描報告

6.1 整體評級：🟡 中風險

Headroom 整體安全性良好，但有幾個值得注意的領域。

6.2 發現項目

🟡 中風險：Telemetry (遙測) 預設開啟

Headroom 內建匿名遙測系統（headroom/telemetry/beacon.py），預設為開啟狀態。遙測資料發送至 Supabase endpoint，包含 aggregate-only stats (僅聚合統計)：token 節省量、壓縮比率、cache hit rate、效能開銷。不含 prompt 內容、使用者資料或 PII。

Supabase anon key 硬編碼於原始碼中（透過 .join() 拼接以避免 secret scanner 誤報），但此 key 設計為 INSERT-only（透過 RLS），無法讀取或修改資料。

關閉方式：

1HEADROOM_TELEMETRY=off headroom proxy
2headroom proxy --no-telemetry

🟡 中風險：Binary 下載（RTK / code-graph / lean-ctx）

headroom/rtk/installer.py、headroom/graph/installer.py、headroom/lean_ctx/installer.py 使用 urllib.request.urlopen 從 GitHub Releases 下載 binary。下載前有 URL scheme 驗證（startswith(("http://", "https://"))），但無 checksum verification (校驗碼驗證)。

🟢 低風險：subprocess 使用

subprocess.run 用於安裝 RTK binary、MCP registry 操作、code-graph watcher。皆使用 list 形式參數（非 shell=True），降低 command injection (命令注入) 風險。

🟢 低風險：本地資料存儲

壓縮後的原始內容（CCR store）、記憶資料（SQLite / Qdrant）皆存於本地，未加密但受作業系統檔案權限保護。

🟢 低風險：eval() 使用

headroom/models/ml_models.py 中的 model.eval() 是 PyTorch 標準 API（切換模型為推論模式），非任意程式碼執行。

6.3 安全建議

1. 遙測：在企業 / 機密環境中，建議以 HEADROOM_TELEMETRY=off 關閉遙測
2. Binary 下載：注意 RTK / code-graph binary 下載來源的可信度
3. Local store：若壓縮的資料含敏感內容，考慮對 CCR store 目錄設定更嚴格的權限
4. 已知 Issue #547：社群已提交安全 vulnerability report (弱點報告)，持續追蹤中

7. FAQ

Q1: Headroom 跟 RTK 有什麼關係？

RTK (Rust Token Killer) 專注於 CLI command output 的 rewriting（如簡化 git show 輸出）。Headroom 包含 RTK 作為其 CLI context tool 的一部分，但額外提供完整的壓縮管線（JSON / AST / 文本 / 圖片）、proxy server、MCP server、跨 agent 記憶等功能。Headroom 壓縮 RTK 下游的所有內容。

Q2: 壓縮會不會讓 LLM 的回答變差？

Headroom 在標準 benchmark 上的表現：

關鍵在於 CCR：若 LLM 判斷壓縮版不夠用，可呼叫 headroom_retrieve 取回完整原始內容。

Q3: 需要 GPU 嗎？

不需要。SmartCrusher (JSON) 和 CodeCompressor (AST) 完全不用 ML 模型。Kompress-base 用 ONNX Runtime 推論，CPU 即可運行。ML extra ([ml]) 是選裝。

Q4: 支援哪些 LLM provider？

透過 proxy 模式支援所有 OpenAI-compatible API。原生支援 Anthropic、OpenAI、Google (Gemini)、AWS Bedrock、Cohere、LiteLLM。

Q5: 在 Windows 上能用嗎？

能，但有已知問題：Issue #575 報告首次呼叫 headroom_compress 時可能在 Windows 上 hang forever (永久掛起)，原因是 headroom._core 內的同步 deadlock (死鎖)。

8. 進階技巧

8.1 自訂壓縮策略

透過環境變數微調壓縮行為：

1HEADROOM_COMPRESSION_LEVEL=aggressive    # 更積極壓縮
2HEADROOM_MIN_TOKENS=100                  # 低於此 token 數不壓縮
3HEADROOM_CONTEXT_TOOL=lean-ctx           # 改用 lean-ctx 替代 RTK

8.2 效能監控

1headroom perf                            # 即時節省統計
2headroom perf --history                  # 歷史趨勢

Headroom 提供 Prometheus metrics endpoint（headroom/proxy/prometheus_metrics.py），可接入 Grafana 監控。

8.3 Observability (可觀測性)

Headroom 支援 OpenTelemetry tracing：

• Pipeline stage timing（每個階段的耗時）
• Compression strategy distribution（壓縮策略分佈）
• Cache hit/miss rates
• Token savings per request

8.4 DevContainer 開發環境

專案提供兩個 DevContainer 設定：

• default — 標準開發環境
• memory-stack — 含 Qdrant + Neo4j 的記憶系統開發環境

8.5 評估工具

1python -m headroom.evals suite --tier 1    # 跑標準 benchmark
2python -m headroom.evals suite --tier 2    # 跑進階 benchmark

9. 整合進其他工作流

9.1 與 AI-knowledge_template 搭配

Headroom 可以作為 AI-knowledge_template 的 token 節省層。在執行 paper-search、gh-tutorial-qd、research-pipeline 等 token 密集工作流時，透過 headroom wrap claude 啟動，可顯著降低每次 session 的 token 消耗。

9.2 與 CI/CD 整合

1# 在 CI 中作為 LLM 呼叫的 proxy
2headroom proxy --port 8787 --no-telemetry &
3ANTHROPIC_BASE_URL=http://127.0.0.1:8787 python run_llm_tests.py

9.3 與 Docker Compose 整合

專案提供 docker-compose.yml，可與其他服務一起編排：

1services:
2  headroom:
3    image: ghcr.io/chopratejas/headroom:latest
4    ports:
5      - "8787:8787"
6    environment:
7      - HEADROOM_TELEMETRY=off

9.4 macOS LaunchAgent 持久化

examples/deployment/macos-launchagent/ 提供 plist 模板，讓 Headroom proxy 在 macOS 開機時自動啟動。

10. 重點摘要 Checklist

• 安裝：pip install "headroom-ai[all]" 或 npm install headroom-ai
• 最快上手：headroom wrap claude — 一鍵啟動壓縮 proxy + Claude Code
• 驗證節省：headroom perf 查看即時統計
• 核心壓縮器：SmartCrusher (JSON) / CodeCompressor (AST) / Kompress-base (文本)
• CCR 可逆：壓縮不怕遺失，LLM 可用 headroom_retrieve 取回原始內容
• 跨 agent 記憶：--memory flag 啟用 Claude ↔ Codex 記憶共享
• 從失敗學習：headroom learn 挖掘失敗 session 寫入修正規則
• 隱私：遙測預設開啟，機密環境用 HEADROOM_TELEMETRY=off 關閉
• 已知限制：Windows 首次呼叫 deadlock (#575)、macOS Intel 安裝問題 (#525)
• 專案活躍度：10.7K stars，每日更新，社群活躍

11. 進一步閱讀

• 官方文件: https://headroom-docs.vercel.app/docs
• Quickstart: https://headroom-docs.vercel.app/docs/quickstart
• 架構文件: https://headroom-docs.vercel.app/docs/architecture
• CCR 可逆壓縮: https://headroom-docs.vercel.app/docs/ccr
• Cache 最佳化: https://headroom-docs.vercel.app/docs/cache-optimization
• Benchmark: https://headroom-docs.vercel.app/docs/benchmarks
• Kompress-base 模型: https://huggingface.co/chopratejas/kompress-base
• Discord 社群: https://discord.gg/yRmaUNpsPJ
• Contributing: https://github.com/chopratejas/headroom/blob/main/CONTRIBUTING.md
• llms.txt: https://headroom-docs.vercel.app/llms.txt