🧠 HeadRoom-Wrap

LLM 上下文压缩工具 — 基于 headroom v0.23.0 的 Python/TypeScript 双SDK封装，节省 60-95% token，零代码改造接入。

上游版本：v0.23.0（2026-06-04）|⭐ 主要更新：GitHub Copilot 订阅模式支持、CCR 工作空间隔离修复、Python 3.13/debian13 基础镜像升级

✨ 核心特性

• 零改造嵌入：一条命令将 HeadRoom 注入任意 Python/TypeScript 应用
• 60-95% token 节省：智能压缩 prompts、工具输出、RAG 结果、文件内容
• 双向兼容：Python pip install + TypeScript npm install
• 跨 Agent 记忆：Claude / Codex / Cursor / Gemini 共享压缩上下文
• 可逆压缩 (CCR)：压缩前自动备份原始内容，按需还原
• Copilot 订阅模式：v0.23.0 新增 — 支持 GitHub Copilot 订阅认证直传

📦 安装

# Python
pip install headroom-ai

# TypeScript / Node.js
npm install headroom-ai

🚀 快速开始

Python Demo

from headroom import compress

messages = [
    {"role": "user", "content": "帮我分析这份代码库的架构..."},
    {"role": "system", "content": "工具输出日志 (10000 tokens)..."},
    {"role": "assistant", "content": "好的，让我先探索代码结构..."}
]

# 压缩前：约 10,144 tokens
# 压缩后：约 1,260 tokens — 节省 87%！
compressed = compress(messages, model="auto")
print(f"节省: {compressed.savings:.1f}%")

TypeScript Demo

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 模式（零代码改造）

# 启动本地代理，所有请求自动压缩
headroom proxy --port 8787

# 然后配置 LLM 客户端指向 localhost:8787 即可

MCP Server

# 安装为 MCP 工具
headroom mcp install

# 自动注册 headroom_compress / headroom_retrieve / headroom_stats

📊 压缩效果实测

场景	压缩前	压缩后	节省率
代码搜索（100结果）	17,765 tokens	1,408 tokens	92%
SRE 故障排查	65,694 tokens	5,118 tokens	92%
GitHub Issue 分类	54,174 tokens	14,761 tokens	73%
代码库探索	78,502 tokens	41,254 tokens	47%

所有场景答案质量保持不变（基于 GSM8K / TruthfulQA / SQuAD v2 / BFCL 基准测试）

🔧 API 参考

Python SDK

from headroom import compress, HeadroomChatModel, withHeadroom

# 方式1：直接压缩
compressed = compress(messages, model="kompress-base")

# 方式2：包装现有 LLM
llm = withHeadroom(Anthropic())  # 自动压缩所有输入输出

# 方式3：LangChain 集成
from langchain.chat_models import HeadroomChatModel
chain = HeadroomChatModel(your_llm)

TypeScript SDK

import { compress, headroomMiddleware, HeadroomAgnoModel } from 'headroom-ai';

// 方式1：直接压缩
const result = await compress(messages, { model: 'kompress-base' });

// 方式2：Vercel AI SDK 中间件
const wrappedModel = wrapLanguageModel({
  model,
  middleware: headroomMiddleware()
});

// 方式3：Agno 集成
const model = new HeadroomAgnoModel(your_model);

🏗️ 架构

用户请求 (prompts / tool outputs / RAG / files)
         ↓
┌─────────────────────────────────────────┐
│           HeadRoom 压缩层                │
│  ┌────────────┐  ┌─────────────────┐   │
│  │ SmartCrusher│  │ Kompress-base   │   │
│  │ (JSON压缩)  │  │ (HF文本压缩模型)  │   │
│ └────────────┘  └─────────────────┘   │
│  ┌────────────┐  ┌─────────────────┐   │
│  │CodeCompressor│ │ CacheAligner    │   │
│  │ (AST压缩)   │  │ (KV缓存优化)    │   │
│  └────────────┘  └─────────────────┘   │
└─────────────────────────────────────────┘
         ↓
  压缩后内容 → LLM Provider

🎯 适用场景

• 日均 API 调用量大的 AI 应用（客服、知识库、代码助手）
• 多 Agent 协作项目（跨 Agent 共享上下文节省 token）
• 长上下文窗口受限的场景（压缩历史对话）
• 成本敏感项目（token 费用直接减半）

⚠️ 注意事项

• Python 3.10+ required
• 需要本地运行环境（暂不支持纯远程 API 场景）
• Windows Credential Manager 支持实验性，请谨慎用于生产

📄 许可证

基于 Apache 2.0，欢迎商业使用。

🔗 链接

• 原始项目：https://github.com/chopratejas/headroom
• 官方文档：https://headroom-docs.vercel.app/docs
• Kompress-base 模型：https://huggingface.co/chopratejas/kompress-base