Headroom 示例目录实战指南：从 compress() 单函数 API 到 LangChain、MCP 与 Strands+Bedrock 集成演示

本文以 examples/README.md 为主线，系统讲解 Headroom 仓库示例目录中每一类演示脚本的用途、运行方式与预期结果，并结合 headroom/compress.py 等核心源码，说明这些示例背后调用的压缩管线、CompressConfig 关键参数以及 LangChain、MCP、AWS Strands Agents 三种集成模式的实际工作原理。读完后，你可以直接运行无 API Key 依赖的本地压缩演示，也能理解带 Key 的完整 Agent 对比评测是如何组织断言与成本核算的。

1. examples 目录总体结构

examples/ 目录存放 Headroom 的各类演示与评测脚本。根据当前仓库目录树，实际存在的可运行脚本包括：

文件/目录	类型	是否需要 API Key
tabular_compression_demo.py	表格/电子表格压缩演示	否
context_compression_demo.py	RAG 检索结果压缩演示	否
strands_bedrock_demo.py	Strands + Bedrock 双模式演示	是（AWS）
strands_bundle_demo.py、strands_via_proxy_demo.py、strands_mcp_dispatch_test.py	Strands 其他集成演示	视场景
langchain_demo/	LangChain Agent 完整对比	部分需 Key
mcp_demo/	MCP 工具输出压缩演示	部分需 Key
test_ccr.py	CCR 机制脚本	—
deployment/macos-launchagent/	macOS LaunchAgent 部署代理配置	否
grafana/headroom-dashboard.json	Grafana 监控面板	否

需要说明的是，examples/README.md 中列出的部分快速上手脚本（如 basic_usage.py、anthropic_example.py、smart_vs_naive_eval.py 等）在当前目录树中并不存在，README 保留的是历史命令说明；上文表格中的脚本是仓库里当前实际存在的、可直接运行的入口。下文以实际存在的脚本为主展开。

2. 无 Key 演示：表格与电子表格压缩（tabular_compression_demo.py）

tabular_compression_demo.py 是一个完全本地运行的演示，用于展示 Headroom 的表格压缩器「在哪里有效、在哪里正确地什么都不做」：

python examples/tabular_compression_demo.py            # 运行全部场景
python examples/tabular_compression_demo.py --write DIR # 同时把生成的样例文件写入 DIR

从源码看，该脚本构造了三类代表性数据并走两条压缩路径（examples/tabular_compression_demo.py#L29-L52）：

1. compact_unique.csv：60 行、每行都唯一的极简 CSV，没有可安全移除的冗余，预期约 0 节省（正确直通）；
2. redundant.csv：120 行高度重复的 EMEA,widget-A,shipped，SmartCrusher 可去重，节省显著；
3. verbose_table.md：40 行填充过的 Markdown 表格，走无损压缩获得收益。

两条压缩路径分别对应两种 API（examples/tabular_compression_demo.py#L58-L89）：

• 字符级路由：直接调用 ContentRouter().compress(content)（headroom.transforms.content_router），输出 strategy_used 策略名与字符数变化；
• 完整管线：调用 headroom.compress(messages, compress_user_messages=True)，使用真实 tokenizer 记账，输出 token 级 tokens_before → tokens_after；
• 二进制电子表格：调用 headroom.compress_spreadsheet(path) 压缩双工作表（Unique + Redundant）的 .xlsx 工作簿，该场景依赖 openpyxl，需要安装 pip install headroom-ai[spreadsheet]，否则脚本会打印 skip 提示并跳过（examples/tabular_compression_demo.py#L136-L144）。

脚本结尾给出的核心结论是：冗余/冗长的表格会被压缩，而紧凑的全唯一数据会正确直通（lossless-only——没有可安全移除的内容），这体现了「先判断是否有信号可压、再动手」的压缩策略设计。

3. 示例背后的一函数压缩 API：compress()

上述演示（以及 README 中提到的 OpenAI/Anthropic 快速上手脚本）最终都归结为同一个入口：headroom/compress.py 中的 compress(messages, model=...)。其模块文档（headroom/compress.py#L1-L54）明确定位为「最简单的 Headroom 用法——无代理、无配置，直接压缩」，并给出 Anthropic SDK、OpenAI SDK、LiteLLM 与任意 HTTP 客户端四种接法：

from headroom import compress

result = compress(messages, model="claude-sonnet-4-5-20250929")
result.messages          # 压缩后的消息（格式不变，token 更少）
result.tokens_saved      # 节省的 token 数
result.compression_ratio # 例如 0.35 表示节省 65%

compress() 的行为由 CompressConfig 数据类控制（headroom/compress.py#L77-L120），关键参数与默认值如下：

参数	默认值	含义
compress_user_messages	False	是否压缩用户消息；RAG 管线或用户消息内嵌大段工具输出时设为 True（tabular_compression_demo.py 正是这样用的）
compress_system_messages	True	是否压缩系统消息；语音等要求指令原样保留的场景设为 False
protect_recent	4	不压缩最后 N 条消息（它们是活跃对话）；设为 0 表示全部可压
protect_analysis_context	True	检测 analyze/review 意图，保护代码不被压缩
frozen_message_count	0	已被提供商 prompt cache 锚定的前缀消息数，变换不会重写冻结前缀内的消息

文档中给出的典型用法档位是：编码代理用默认配置；金融文档压缩用 compress_user_messages=True, target_ratio=0.5, protect_recent=0；日志/搜索结果等可激进压缩用 target_ratio=0.2。

4. RAG 上下文压缩演示（context_compression_demo.py）

context_compression_demo.py 是「无 mock、无 API Key」的真实压缩测试：它构造一个由 12 个文档 chunk 组成的向量检索器 JSON 输出（含 source、chunk_id、content、relevance_score 字段，examples/context_compression_demo.py#L17-L44），组装成 OpenAI 格式的 user/assistant(tool_calls)/tool 三条消息，然后调用真实的 compress()（examples/context_compression_demo.py#L332-L346）：

PYTHONPATH=. python examples/context_compression_demo.py

脚本会打印 token 前后值、压缩率与压缩耗时，并执行一组可验证的断言：压缩确实发生（tokens_saved > 0）、消息条数不变、用户消息未被修改、tool 消息仍然存在，以及关键术语（reward、hacking、sycophancy、specification）在压缩后保留。最后输出一张与「上下文处理技术」对比的表格（RAG 基线、基于 GPT-4o-mini 的上下文裁剪、摘要，以及 Headroom 压缩——后者无需额外 LLM 调用、额外成本为 $0）。

5. LangChain 集成演示（langchain_demo/）

langchain_demo/ 是完整的 LangChain Agent 集成演示，包含 mock_tools.py（仿真工具输出生成器）、show_compression.py（独立压缩演示）、verify_errors_kept.py（ERROR 保留校验）与 run_comparison.py（完整 Agent 前后对比）。运行方式（摘自 examples/langchain_demo/README.md）：

# 演示压缩效果（无需 API Key）
PYTHONPATH=. python -m examples.langchain_demo.show_compression

# 校验 100% ERROR 保留
PYTHONPATH=. python -m examples.langchain_demo.verify_errors_kept

# 完整 Agent 前后对比（需要 OPENAI_API_KEY）
export OPENAI_API_KEY='your-key-here'
PYTHONPATH=. python -m examples.langchain_demo.run_comparison

该演示 README 给出了实测 token 节省数据（100% ERROR 保留前提下）：

工具	压缩前	压缩后	节省
search_users（100 条）	15,453	2,014	87%
search_logs（200 条）	25,679	3,213	87%
get_metrics（100 条）	11,517	8,425	27%
search_docs（50 条）	6,912	2,127	69%
fetch_api_data（75 条）	15,786	3,622	77%
合计	75,347	19,401	74%

其压缩策略（SmartCrusher）在文档中归纳为五条：100% 保留 ERROR 条目（绝不丢弃错误项）、保留首尾条目以维持分页上下文、统计检测并保留异常项（CPU/内存尖峰）、按与用户查询的相关性打分、保留数据中的显著变化点。按 gpt-4o $2.50/1M 计价，单次请求成本从 $0.19 降至 $0.05，日 1000 请求约每月节省 $4,196。演示目录还提供了评测套件入口：PYTHONPATH=. pytest tests/test_integrations/test_langchain_evals.py -v，覆盖错误保留、异常检测、相关性匹配、压缩效率、Schema 保留与边界情况共 12 项。

6. MCP 集成演示（mcp_demo/）

mcp_demo/ 演示 MCP（Model Context Protocol）工具输出的压缩，文件包括 mock_mcp_servers.py（仿真 MCP 服务端）、show_compression.py、show_before_after.py（压缩前后对照）与 run_agent_eval.py（Agent 评测）。按 examples/README.md 的说明：

export OPENAI_API_KEY='your-key'
PYTHONPATH=. python -m examples.mcp_demo.run_agent_eval

README 给出的 MCP 工具输出预期节省区间为 60–80%。

7. AWS Strands Agents + Bedrock 演示（strands_bedrock_demo.py）

strands_bedrock_demo.py 演示 Headroom 与 AWS Strands Agents 的两种集成模式（examples/strands_bedrock_demo.py#L2-L24）：

1. HeadroomHookProvider——通过 Strands hooks 实时拦截工具结果，对大 JSON 输出应用 SmartCrusher 压缩，并展示逐工具压缩指标；
2. HeadroomStrandsModel——包装 BedrockModel，在每次 API 调用前应用消息级变换，并跨会话累计节省量。

两类组件均来自 headroom.integrations.strands 模块（examples/strands_bedrock_demo.py#L53-L59）。运行方式与参数：

# 配置 AWS 凭证（三选一：环境变量 / AWS_PROFILE / ~/.aws/credentials）
export AWS_ACCESS_KEY_ID='your-access-key'
export AWS_SECRET_ACCESS_KEY='your-secret-key'
export AWS_DEFAULT_REGION='us-west-2'   # 可选，默认 us-west-2

python examples/strands_bedrock_demo.py          # 运行两种模式
python examples/strands_bedrock_demo.py --hook   # 仅 Hook Provider 演示
python examples/strands_bedrock_demo.py --model  # 仅 Model Wrapper 演示
python examples/strands_bedrock_demo.py --region us-east-1  # 指定 AWS 区域

演示使用 Bedrock 上的 Claude 3 Haiku 以控制成本，创建带 4 个返回冗长 JSON（搜索结果、日志、数据库记录、指标）的工具的 Agent，并展示压缩统计与可视化对比。依赖要求：pip install strands-agents headroom-ai[strands]，且账号需开通 Bedrock 并在目标区域有 Claude 3 Haiku 模型访问权限。脚本开头的 check_dependencies() / check_aws_credentials() 会在缺失依赖或凭证时直接打印可操作的安装/配置提示（examples/strands_bedrock_demo.py#L41-L108）。

此外，仓库还提供了三个相关 Strands 脚本供延伸验证：strands_bundle_demo.py、strands_via_proxy_demo.py（经代理集成的路径）与 strands_mcp_dispatch_test.py。

8. 预期结果与运行方式

examples/README.md 给出的各演示预期节省区间（文档口径，实际因数据形态而异）：

示例	Token 节省	说明
basic_usage	50–70%	简单工具输出压缩
langchain_demo	70–85%	多工具真实 Agent
mcp_demo	60–80%	MCP 工具输出
strands_bedrock_demo	60–85%	Strands + Bedrock，冗长工具
real_world_eval	50–90%	随场景变化

所有示例均可从仓库根目录运行，统一安装方式为：

# 安装依赖
pip install -e ".[dev]"

# 运行任意示例
python examples/<example_name>.py

9. 故障排查

以下内容继承自 examples/README.md 的 Troubleshooting 一节：

ModuleNotFoundError: No module named 'headroom'——从仓库根目录带 PYTHONPATH 运行，或改用开发模式安装：

PYTHONPATH=. python examples/basic_usage.py
# 或
pip install -e .

API Key 报错——确认对应提供商的 Key 已设置：

export OPENAI_API_KEY='sk-...'
export ANTHROPIC_API_KEY='sk-ant-...'

AWS 凭证报错（Strands 演示）——确认已通过环境变量、AWS_PROFILE 或 ~/.aws/credentials 文件任一方式配置凭证，并且 AWS 账号已开通 Bedrock 及 Claude 3 Haiku 模型访问；strands_bedrock_demo.py 内置的凭证检查（见第 7 节）会给出具体缺失项。

小结

examples 目录呈现了 Headroom 的三层使用姿势：无 Key 的本地压缩演示（tabular_compression_demo.py、context_compression_demo.py）适合快速验证压缩行为与「无损优先」策略；compress() 单函数 API 及其 CompressConfig 参数是接入任意 LLM 客户端的最小单元；而 LangChain、MCP、Strands+Bedrock 三个演示目录则展示了在真实 Agent 框架中如何同时拿到 60–85% 的工具输出 token 节省与 100% ERROR 保留等可断言的安全保证。