前言¶
長對話、工具輸出和 RAG 檢索結果會迅速佔滿上下文窗口，帶來更高的 token 費用，也更容易觸發截斷。常見做法是手工刪歷史或改 prompt，維護成本高，也難保證壓縮後仍保留關鍵信息。
下面介紹 SkillHub 上的 Headroom Token壓縮助手（@user_922b1001/headroom-token-compress-wrap）。它把開源項目 headroom-wrap 封裝成符合通用 SKILL.md 格式的 Agent Skill，讓編碼助手在需要壓縮上下文時，能按同一套說明調用底層的 HeadRoom 能力，而不必每次從零查文檔。
這是什麼¶
Headroom Token壓縮助手 是對 headroom-wrap 的 AI Skill 封裝；Skill 包內說明其能力細節以項目 README.md 爲準，上游倉庫爲 https://github.com/q15004040209-creator/headroom-wrap。
- 維護與分發：SkillHub 社區來源（
community），發佈者user_922b1001，當前 Skill 版本 1.0.1，分類 ai-agent，標籤 requires_api_key=false（安裝 Skill 本身不要求配置 API Key）。 - 底層能力：
headroom-wrap描述自身爲「LLM 上下文壓縮工具」，基於上游 headroom 提供 Python / TypeScript 雙 SDK 封裝；實際壓縮依賴headroom-ai包與本地運行環境，而非僅安裝 Skill 文件即可完成壓縮。
核心功能¶
以下能力來自 Skill 包內 README.md 與上游項目說明，均圍繞 在送入模型前壓縮 prompts、工具輸出、RAG 結果、文件內容 展開。
- SDK 直接壓縮：對消息列表調用
compress，可選model="auto"或kompress-base等。 - 零改造代理：通過
headroom proxy啓動本地代理，將 LLM 客戶端指向代理端口，由代理側處理壓縮。 - MCP 工具：執行
headroom mcp install後，可註冊headroom_compress、headroom_retrieve、headroom_stats等工具。 - 框架集成：Python 側提供
withHeadroom、HeadroomChatModel；TypeScript 側提供headroomMiddleware、HeadroomAgnoModel等（見包內 API 示例）。 - 可逆壓縮（CCR）：壓縮前備份原始內容，支持按需還原。
- 跨 Agent 上下文：文檔中提及可與 Claude、Codex、Cursor、Gemini 等場景共享壓縮後的上下文（具體集成方式以實現爲準）。
項目 README 給出的節省區間爲 60–95% token，並附有若干場景的壓縮前後 token 對照表；是否達到相同比例取決於你的數據形態與模型配置，需自行實測。
安裝與啓用¶
1. 安裝 SkillHub CLI（若尚未安裝）¶
先檢查是否已有 CLI：
command -v skillhub && skillhub --version
未安裝時，可按 SkillHub 官方安裝說明執行完整安裝（CLI + 默認 Skill）：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash
僅安裝 CLI：
curl -fsSL https://skillhub-1388575217.cos.ap-guangzhou.myqcloud.com/install/install.sh | bash -s -- --cli-only
2. 將 Skill 裝到當前 Agent 的 skills 目錄¶
安裝時必須用 --dir 指向當前客戶端識別的 skills 目錄，否則默認落在 ./skills/ 可能無法被加載。常用路徑如下（摘自 SkillHub 安裝文檔）：
- Cursor：
~/.cursor/skills/ - Claude Code：
~/.claude/skills/ - Codex：
~/.codex/skills/或項目下的.agents/skills/
安裝命令示例（將 <skills 目錄> 換成你的實際路徑）：
skillhub install @user_922b1001/headroom-token-compress-wrap --dir <skills 目錄>
SkillHub 頁面亦支持讓 AI 按 https://skillhub.cn/install/skillhub.md 完成上述安裝。
3. 安裝底層 headroom-ai（執行壓縮所必需）¶
Skill 主要提供操作指引；真正執行壓縮需要在本機安裝 headroom-ai：
# Python
pip install headroom-ai
# TypeScript / Node.js
npm install headroom-ai
文檔要求 Python 3.10+，並說明需要本地運行環境，暫不支持純遠程 API 場景。Windows Credential Manager 相關能力爲實驗性，生產環境需謹慎評估。
安裝或更新 Skill 後，按你所用客戶端的要求重啓或重新加載 skills（以客戶端文檔爲準）。
典型用法¶
在對話中觸發 Skill¶
啓用該 Skill 後，當任務涉及「壓縮歷史對話」「縮小工具輸出體積」「在調用模型前處理 RAG 上下文」時，Agent 應參照 Skill 包內 README.md 選擇 SDK、Proxy 或 MCP 路徑。Skill 元數據中的 description 亦指向同一 GitHub 源倉庫。
Python：直接壓縮消息¶
from headroom import compress
messages = [
{"role": "user", "content": "幫我分析這份代碼庫的架構..."},
{"role": "system", "content": "工具輸出日誌 (10000 tokens)..."},
{"role": "assistant", "content": "好的，讓我先探索代碼結構..."},
]
compressed = compress(messages, model="auto")
print(f"節省: {compressed.savings:.1f}%")
Proxy：不改業務代碼¶
headroom proxy --port 8787
將 LLM 客戶端的 API 地址指向 localhost:8787，由代理層完成壓縮（端口與主機以你的部署爲準）。
MCP¶
headroom mcp install
安裝後可在支持 MCP 的 Agent 中使用 headroom_compress、headroom_retrieve、headroom_stats。
更完整的 API 與架構說明見 Skill 包內 README.md，以及上游文檔 headroom-docs.vercel.app。
適用場景與注意¶
更適合：API 調用頻繁、上下文裏堆疊工具輸出或檢索片段的應用；多 Agent 協作時需要共享壓縮後上下文；對 token 成本敏感、又希望儘量保留任務相關信息的團隊。
需要留意的限制：
- Skill 與
headroom-ai是兩層：只裝 Skill 不會自動具備壓縮運行時，須單獨安裝並配置 Python/Node 環境。 requires_api_key=false僅表示 SkillHub 側不要求爲 Skill 本身填 Key；調用各家 LLM 仍按你現有 Provider 配置。- 壓縮率與答案質量需在你的業務數據上驗證；README 中的對照表來自項目自述，不宜直接當作你的 SLA。
- 上游許可證爲 Apache 2.0（見 README 中對 headroom 原項目的說明）。
結尾¶
Headroom Token壓縮助手 把 HeadRoom 上下文壓縮工作流固化成可安裝的 Agent Skill，便於在 Cursor、Claude Code、Codex 等環境中統一引用同一套安裝與用法說明。若你正在處理上下文膨脹或 token 成本問題，可從 SkillHub 安裝該 Skill，再按文檔部署 headroom-ai。
- SkillHub 頁面：https://www.skillhub.cn/skills/user_922b1001/headroom-token-compress-wrap
- 官方 API 地址：https://api.skillhub.cn/user_922b1001/headroom-token-compress-wrap
- 上游項目：https://github.com/q15004040209-creator/headroom-wrap
