[Bug]: HEadroom guardrail compress nothing

快速结论：该问题实际不是 LiteLLM 的 Bug，而是 headroom 的默认行为所致。当请求中 user 类型消息占多数或消息带有 cache_control 标记时，headroom 会保护这些消息不压缩，导致 requests_compressed: 0。优先检查 HEADROOM_COMPRESS_USER_MESSAGES 环境变量是否为 1，以及请求中是否包含缓存控制标记。

问题场景

用户在 LiteLLM 中集成 headroom 作为 guardrail 进行消息压缩，观察到 /v1/compress 端点被调用，但最终 requests_compressed 始终为 0，没有任何消息被压缩。该问题在使用 Claude Code 等大量发送 user 类型消息的客户端时尤为明显。

报错原文

router.route_counts: {user_msg: 10, system_msg: 7}
# 实际表现：compress endpoint 被调用但没有任何压缩发生
# 在 spend logs 中 guardrail_information 为 null（仅在请求失败时才填充）

原因分析

可能原因有两个，均为 headroom 的既定保护机制而非 Bug：

默认不压缩 user 类型消息：headroom 的 content_router.py（第2533-2545行）默认保护 user 角色的消息，除非显式设置环境变量 HEADROOM_COMPRESS_USER_MESSAGES=1。Claude Code 等客户端发送的请求中 user_msg 占绝大多数，因此零压缩发生。
带 cache_control 标记的消息被保护：当启用了 Anthropic 的提示缓存（Claude Code 重度依赖此功能，90%+ 的 prompt_tokens 来自 cached_tokens）时，headroom 检测到 cache_control 标记后会保护这些消息，以避免破坏提示缓存的字节匹配。

此外，Issue 中确认了一个相关的日志问题：metadata.guardrail_information 在成功请求的 spend logs 中为 null，仅在请求失败时才填充。这使得通过 spend logs 排查 guardrail 是否运行变得困难。

环境排查

确认 headroom 服务的运行状态和可达性
检查 HEADROOM_COMPRESS_USER_MESSAGES 环境变量是否设置（默认为 0）
确认请求中消息的 role 分布（user_msg / system_msg 计数）
检查请求中是否包含 cache_control 标记（使用 Anthropic 提示缓存时常见）
查看 spend logs 中 guardrail_information 字段是否为空

解决步骤

检查是否需要压缩 user 消息：如果希望 headroom 也压缩 user 角色的消息，设置环境变量 HEADROOM_COMPRESS_USER_MESSAGES=1。
检查缓存的保护状态：通过 headroom 的 /guardrails/usage/logs 端点查看实际运行日志，确认 cache_control_protected 计数。如果缓存保护导致了不期望的行为，需要在 headroom 层面调整保护策略。
验证 guardrail 是否被调用：不要仅依赖 spend logs 中的 guardrail_information 字段（成功时可能为 null），应直接查看 headroom 的日志。
（可优先尝试）确认 LiteLLM 文档已更新：官方已更新文档以明确 headroom 的压缩行为，建议对照最新文档检查配置。