一句話總結
在內容送入 LLM 之前，用 6 種算法壓縮。Token 減 60-95%，答案質素不變。支援四種部署模式：Library / Proxy / Agent Wrap / MCP Server。
核心問題
AI Agent 每次調用工具都會產生大量冗餘數據：
| 場景 | 原始 Tokens | 壓縮後 | 節省 |
|---|---|---|---|
| JSON 返回 | 10,144 | 1,260 | 87.6% |
| Build Log | 65,694 | 5,118 | 92.2% |
| 100 條搜索結果 | 17,765 | 1,408 | 92.1% |
| GitHub Issue 分類 | 54,174 | 14,761 | 72.8% |
| 代碼庫探索 | 78,502 | 41,254 | 47.5% |
🔑 壓縮後答案質素不變：GSM8K 數學推理 0.870→0.870，TruthfulQA 甚至從 0.530 提升到 0.560。
六層壓縮流水線
原始內容 → Stage 1: CacheAligner → Stage 2: ContentRouter → Stage 3: 壓縮算法 → CCR Store → LLM
Stage 1: CacheAligner
穩定 message prefix，令 Anthropic/OpenAI 的 KV cache 真正命中。
- Claude cache hit 有 90% 折扣
- 這一步本身就可以大幅降低成本
Stage 2: ContentRouter
自動偵測內容類型（JSON / 代碼 / 日誌 / 搜索結果 / diff / HTML / 純文本），分發到最佳壓縮器。
Stage 3: 六種專業壓縮器
| 壓縮器 | 適用場景 | 原理 | 壓縮率 |
|---|---|---|---|
| SmartCrusher | JSON（通用） | 統計分析，保留 errors/anomalies/boundaries，丟棄重複模式 | 80-92% |
| CodeCompressor | Python/JS/Go/Rust/Java/C++ | AST 感知（tree-sitter），保留 function signatures，壓縮 bodies | 50-70% |
| Kompress-base | 純文本 | HuggingFace 訓練的 ModernBERT token 分類模型 | 60-80% |
| LogCompress | 日誌/CI 輸出 | 保留 failures 和 errors，丟棄 passing noise | 80-95% |
| SearchCompress | 搜索結果 | 按相關性排序，只保留 top matches | 60-80% |
| Image ML Router | 圖片 | 自動選擇最佳 resize/quality | 40-90% |
CCR（可逆壓縮）， 核心設計
壓縮 ≠ 丟棄
壓縮後的內容存入 CCR Store（Compress-Cache-Retrieve），LLM 獲得 headroom_retrieve 工具，如果需要完整原文，可以隨時取回。
「先給摘要，需要時再取原文。」不是丟棄資訊，是分層提供。
四種部署模式
| 模式 | 命令 | 適用場景 | |
|------|------|---------- | |
| Proxy | headroom proxy --port 8787 | 零代碼修改，任何語言，指向 proxy URL 即可 | |
| Library | from headroom import compress | Python/TypeScript 內聯，精細控制 | |
| Agent Wrap | headroom wrap claude\|codex\|cursor | 壓縮後再交給 Agent | 一條命令包裝整個 Agent |
| MCP Server | headroom_compress / headroom_retrieve / headroom_stats | 任何 MCP 客戶端，包括 OpenClaw | |
對我哋的價值
我們每天大量使用 LLM，每個港股調研流水線調研 session 燒 100K+ tokens：
| 維度 | 現狀 | 用 Headroom 後 |
|---|---|---|
| Token 成本 | DeepSeek V4 Pro ~$1.74/1M input | 壓縮後預計節省 60-80% |
| 回應速度 | 大量 input tokens 拖慢 | 少 80% input = 快 80% |
| Context 壽命 | 無效內容佔用 context window | 實際可用量倍增 |
| Cache 命中 | 無優化 | CacheAligner 提升 cache hit |
額外功能
headroom learn， 挖掘失敗 session，自動寫入CLAUDE.md/AGENTS.md修正- Cross-agent memory ， Claude、Codex、Gemini 共享壓縮存儲，自動去重
- IntelligentContext ， 超出 context limit 時按重要性（recency、references、density）智能裁剪
安裝
pip install "headroom-ai[all]" # 完整安裝（推薦）
npm install headroom-ai # TypeScript/Node.js
docker pull ghcr.io/chopratejas/headroom:latest
技術棧： Python 78.6% + Rust 16.8% + TypeScript 2.4% 授權： Apache 2.0 | Repo： chopratejas/headroom | 文檔： headroom-docs.vercel.app