前言¶
长对话、工具输出和 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
