前言¶
长对话、工具回传和大段 RAG 结果会把单次请求的 token 撑满，费用和窗口上限都会成为瓶颈。常见做法是手工截断历史或改 prompt，维护成本高，也容易丢关键信息。Headroom Wrap 是 SkillHub 上的社区 Skill（坐标 @user_922b1001/headroom-wrap），把基于 headroom 的上下文压缩能力封装成 Agent 可读的 SKILL.md 说明，便于在 Cursor、Claude Code 等环境里让模型按统一步骤调用 Python/TypeScript SDK、本地代理或 MCP。下面介绍它是什么、如何安装，以及上游项目提供的可复现用法。
这是什么¶
Headroom Wrap 当前版本为 1.0.0，来源为 community，发布者为 user_922b1001，在 SkillHub 分类为 design-media。Skill 包内的描述为：面向 LLM 的上下文压缩封装，配套 Python/TypeScript SDK；作者标注为 q15004040209-creator，上游开源仓库为 q15004040209-creator/headroom-wrap。标签 requires_api_key=false，表示 Skill 本身不要求额外 API Key 配置项。
需要区分两层对象：
- SkillHub Skill：主要是
SKILL.md与元数据，告诉 Agent「何时、如何」使用 Headroom 相关命令与 API。 - headroom-ai 运行时：实际上下文压缩由上游 headroom 生态提供（
pip install headroom-ai/npm install headroom-ai），Skill 不替代 SDK 安装。
截至资料抓取时，SkillHub 页面显示评分 100000，下载 812 次，安装计数为 0（以 SkillHub 统计为准）。
核心功能¶
以下能力来自 Skill 描述与上游 headroom-wrap README，安装 Skill 后 Agent 应引导你在本地执行对应步骤。
- 消息级压缩：对 prompts、工具输出、RAG 结果、文件内容等做压缩；README 宣称典型节省区间为 60–95% token（实际比例取决于内容与模型参数）。
- 双语言 SDK：Python 与 TypeScript/Node 均可通过
headroom-ai包调用compress等接口。 - Proxy 模式：
headroom proxy启动本地代理，将 LLM 客户端指向代理端口，在不大改业务代码的情况下压缩请求路径上的上下文。 - MCP：
headroom mcp install可注册headroom_compress、headroom_retrieve、headroom_stats等工具供支持 MCP 的客户端使用。 - 可逆压缩（CCR）：README 说明压缩前会备份原始内容，可按需还原。
- 框架集成：README 列出 LangChain、
withHeadroom包装、Vercel AI SDK 中间件、Agno 等集成示例。
上游 README 还提到基于 headroom v0.23.0 的封装，并列出 SmartCrusher、Kompress-base、CodeCompressor、CacheAligner 等组件名称；详细行为以 headroom 官方文档 为准。
安装与启用¶
1. 安装 SkillHub CLI（若尚未安装）¶
先检查是否已有 CLI：
command -v skillhub && skillhub --version
未安装时可按 SkillHub 官方说明执行完整安装（含默认 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. 将 Headroom Wrap 装进当前 Agent 的 skills 目录¶
SkillHub 要求用 --dir 指向当前客户端识别的 skills 目录；装到默认 ./skills/ 可能不会被 Agent 加载。常用路径示例：
| 客户端 | skills 目录 |
|---|---|
| Cursor | ~/.cursor/skills/ |
| Claude Code | ~/.claude/skills/ |
| Codex | ~/.codex/skills/ 或项目下 .agents/skills/ |
安装命令（将 <skills 目录> 换成你的实际路径）：
skillhub install @user_922b1001/headroom-wrap --dir <skills 目录>
官方页面亦支持把下面提示交给 AI 执行（内容与上一致）：
请根据 https://skillhub.cn/install/skillhub.md，安装 `@user_922b1001/headroom-wrap`。
安装完成后，按你所用客户端的要求重启或重新加载 Agent，使新 Skill 生效。
3. 安装 headroom-ai 运行时（执行压缩时必需）¶
Skill 只提供操作指引；真正压缩需在项目或本机安装 SDK：
# Python
pip install headroom-ai
# TypeScript / Node.js
npm install headroom-ai
上游 README 要求 Python 3.10+，并说明需要本地运行环境，暂不支持「纯远程 API、无本地进程」的场景。
典型用法¶
Python：直接压缩消息列表¶
对 messages 调用 compress，可用 model="auto" 或指定如 kompress-base：
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}%")
TypeScript：异步压缩¶
import { compress } from 'headroom-ai';
const messages = [
{ role: 'user', content: '帮我分析这份代码库的架构...' },
{ role: 'system', content: '工具输出日志 (10000 tokens)...' },
];
const result = await compress(messages, { model: 'auto' });
console.log(`节省: ${result.savings}%`);
Proxy：零改造接入¶
在本机启动代理（示例端口 8787）：
headroom proxy --port 8787
将 LLM 客户端的 API 地址指向 localhost:8787，由代理层处理压缩。
MCP¶
headroom mcp install
安装后可在支持 MCP 的环境中使用 README 所列的 compress / retrieve / stats 类工具。
在 Agent 对话中，启用 Headroom Wrap Skill 后，可直接描述场景（例如「压缩这段工具输出再发给模型」），由 Agent 按 SKILL.md 与上游 README 选择 SDK、Proxy 或 MCP 路径。
适用场景与注意¶
适合：
- 工具链回传大、RAG 片段多、多轮对话历史长的 Agent 或应用。
- 希望在 Python 与 TypeScript 栈中复用同一套压缩思路的团队。
- 已使用 Cursor、Claude Code、Codex 等，并希望通过 Skill 统一「压缩上下文」的操作说明。
注意：
- SkillHub 上的 Skill 包体很轻（主要为
SKILL.md），复杂 API 与架构说明以上游 GitHub README 与 headroom 文档为准。 - README 中的压缩比例、场景对比表来自上游项目自述，落地前应在你的真实数据上做一次验证。
- README 写明 Windows Credential Manager 支持为实验性，生产环境需谨慎。
- 分类为 design-media 是 SkillHub 侧标签，与「多媒体设计」无必然关系，以功能描述为准。
结尾¶
Headroom Wrap 的价值在于：把 LLM 上下文压缩的安装、SDK 调用、Proxy 与 MCP 等步骤固化成 Agent Skill，降低在编码助手里反复解释「怎么省 token」的成本；运行时仍依赖 headroom-ai 与本地环境。官方 Skill 入口：
- API 坐标：https://api.skillhub.cn/user_922b1001/headroom-wrap
- SkillHub 页面：https://www.skillhub.cn/skills/user_922b1001/headroom-wrap
- 上游仓库：https://github.com/q15004040209-creator/headroom-wrap
