把 Headroom 研究透

# 1) 先起 Python proxy(压缩管线在 Python)
pip install "headroom-ai[proxy]" && headroom proxy --port 8787
# 2) JS/TS 项目
npm install headroom-ai

import { compress } from 'headroom-ai';
const r = await compress(messages, { model:'gpt-4o', baseUrl:'http://localhost:8787' });
// camelCase: r.tokensSaved / r.compressionRatio

headroom proxy --port 8787
# 把客户端指向 proxy —— 零改代码
ANTHROPIC_BASE_URL=http://localhost:8787 claude       # 无 /v1
OPENAI_BASE_URL=http://localhost:8787/v1 cursor       # 有 /v1
curl http://localhost:8787/stats

docker pull ghcr.io/chopratejas/headroom:latest
docker run -p 8787:8787 ghcr.io/chopratejas/headroom:latest   # proxy
docker run -p 8787:8787 ghcr.io/chopratejas/headroom:code     # 带代码压缩

plan = client.chat.completions.simulate(model="gpt-4o", messages=[...])
print(plan.tokens_before, "->", plan.tokens_after, plan.savings_percent)
print(plan.waste_signals)  # json_bloat/whitespace/dynamic_date/repetition —— 诊断金矿

import { withHeadroom } from 'headroom-ai/openai';
const client = withHeadroom(new OpenAI(), { model:'gpt-4o', baseUrl:'http://localhost:8787' });
// create() 自动压缩; embeddings/responses.create() 原样透传

import litellm
from headroom.integrations.litellm_callback import HeadroomCallback
litellm.callbacks = [HeadroomCallback()]   # 一次注册,覆盖 100+ provider
litellm.completion(model="bedrock/claude-sonnet", messages=[...])  # 任意 provider 串都自动压

pip install "headroom-ai[agno]" agno
from headroom.integrations.agno import HeadroomAgnoModel, HeadroomPostHook
model = HeadroomAgnoModel(OpenAIChat(id="gpt-4o"))
agent = Agent(model=model, post_hooks=[HeadroomPostHook(token_alert_threshold=10000)])
# ⚠️ 多会话服务器必须 model.reset() 否则 metrics 跨对话泄漏; async 方法名 aresponse

# 两层可叠加(正交,同用最省)
model = HeadroomStrandsModel(wrapped_model=model)      # 压全对话
hooks = HeadroomHookProvider(compress_tool_outputs=True)  # SmartCrusher 压单个 tool 结果
agent = Agent(model=model, hooks=[hooks])

// ⚠️ 硬依赖本地 Python proxy(#1 坑),先 headroom proxy
import { withHeadroom } from 'headroom-ai/vercel-ai';
const model = withHeadroom(openai('gpt-4o'));   // === wrapLanguageModel + headroomMiddleware()