Headroom：headroom proxy 接入与验证

装上 Headroom 后 Token 没有下降，先别急着调整 Prompt 或更换压缩模型，先确认模型请求是否真的经过了 Headroom。现有 Coding Agent 或 CLI 如果允许修改模型请求入口，应先核对 headroom proxy 链路；支持 MCP 的客户端需要注册 Server，并分别验证内容是否进入压缩流程、headroom_retrieve 是否可见；自建 Python/TypeScript Agent 则应在消息组装前调用对应的库。无论使用哪种方式，都要用固定工作负载做原样直传与压缩后的 A/B，而不是仅凭启动日志判断。

这里需要先区分：“安装成功”不代表“所有请求已经自动被代理”。Headroom 处理的是工具输出、日志、文件和 RAG 分块进入模型上下文之前的阶段，定位更接近 Agent 与模型之间的压缩层，不是修改 system prompt，也不能直接替代模型。 代理进程能够启动，只证明程序已运行；模型端点是否切换、客户端是否支持自定义入口、流式请求是否经过同一路径，都要单独验证。

先把“节省 60%–95%”限定到具体场景。官方仓库给出的项目发布结果是：Coding Agent 少用约 20% Token，JSON 少用约 60%–95% Token，并称测试中答案保持相同。 这些数字应当作为待在自有工作负载上复现的结果，不是所有 Agent、所有 JSON 或所有日志都能达到的保证。短小输出、缺少重复结构的内容，可能根本没有足够的压缩空间。

项目材料还列出过更具体的工作负载结果，例如代码搜索从 17,765 Token 降到 1,408，SRE 故障排查从 65,694 Token 降到 5,118，GitHub Issue 分诊从 54,174 Token 降到 14,761。 它们只能说明对应样本中的结果，不能改写成“所有 Coding Agent 都能节省 92%”。单个样例与项目整体口径也不能混为一谈：验证时仍然要按 JSON、日志、代码和 RAG 分开统计。

不同内容需要走不同的压缩路径。现有资料将 JSON/API 工具输出交给 SmartCrusher，将代码文件交给基于 AST 的 CodeCompressor，将日志、错误堆栈、普通文本和 RAG 分块交给 Kompress-base 一类压缩器处理，并由内容路由选择对应路径。 对话历史也被列入可压缩范围，但它与单次工具结果的结构不同，不应直接套用同一组压缩率。压缩器名称、模型版本、语言支持范围和路由规则可能变化，最终要以当前官方仓库为准。

接入方式应按“谁控制上下文组装”来选择。资料中能确认的路径包括本地 proxy、MCP Server，以及 Python/TypeScript 库接入。 它们的区别不只是安装命令不同，还决定了客户端兼容性、原文回取方式和出现故障时由谁负责回退。

对于无法修改业务代码的现有 Agent，代理路径通常更合适，但前提是客户端确实允许修改模型请求入口。现有资料能够确认的启动入口如下：

headroom proxy

这条命令只能确认启动入口，版本仍需另行核对。运行前应从当前官方 README 确认安装方法、监听地址、上游模型地址、认证传递方式和可用参数，不要从旧文章或其他版本复制环境变量名。 如果 Agent 由 systemd、容器或其他服务管理器启动，还要检查代理与 Agent 是否使用相同的运行用户、环境变量和 PATH；终端里能启动，不代表服务进程也能找到同一个二进制。

使用 MCP 接入时，应确认 Server 真的被客户端加载，不能仅凭复制一份通用配置判断接入完成。现有资料没有给出具体配置文件路径、transport 字段和启动 JSON，无法据此给出可核验的配置片段。 接入后至少要检查四件事：Server 是否成功启动、客户端注册时是否报错、headroom_retrieve 是否出现在工具列表中、实际调用能否返回对应原文。还要确认当前 MCP 集成是否负责压缩全部上下文；如果它只提供取回能力，那么仅注册 Server 并不能让代理链路自动生效。

自建 Python/TypeScript Agent 应把接入点放在消息组装之前。文件读取返回后、工具结果写入 messages 前、RAG 检索块拼接到上下文前，都是需要检查的位置。压缩后的内容用于发送给模型，未经压缩的业务对象仍应保留给程序判断、审计和失败回退，不能用模型看到的摘要覆盖原始数据。 具体函数签名和调用参数应以当前官方 API 为准；现有资料没有提供可引用的完整代码，复制旧版本示例很容易造成接入失败。

配置核验也应限制在当前版本能够确认的范围内。安装位置与版本、模型请求入口、认证信息传递、内容路由、原文缓存与取回、日志和指标，都需要逐项对照 README。 任何缺少官方字段说明的环境变量、配置键或默认值，都应标记为“当前资料未提供”。尤其是认证信息，不要为了排查代理问题直接写入普通日志；现有资料也不足以证明所有模式在压缩组件异常时都会自动原样回退，应用侧应保留原始内容并明确回退路径。

命令找不到时，先查安装位置、运行用户、PATH 和版本，不应该立即怀疑模型。进入第二层排查后，要确认模型端点是否真的指向代理、统计是否覆盖了实际发送的请求、内容是否被路由器识别，以及流式路径是否与测试请求一致。MCP 客户端则要看注册和连接日志。代理启动日志只能证明本地进程存在，不能证明某次模型调用已经经过压缩层，更不能证明某段 JSON 使用了 JSON 压缩器。

答案质量下降时，要先把原文与压缩结果逐项对照。重点检查错误码、堆栈行号、时间戳、请求 ID、代码函数签名、文件路径和 RAG 引用是否遗漏。资料将 Headroom 描述为可逆压缩：原始内容得到保留，模型需要时可以调用 headroom_retrieve 取回。 但“可取回原文”不等于压缩表示绝对无损，也不等于模型一定能意识到自己缺少信息并主动取回；涉及关键判断时，仍应验证回取是否被触发、是否成功，以及回取增加的 Token 和延迟是否可以接受。

效果验证应使用自己的固定工作负载，而不是只跑一个演示 Prompt。可以从真实任务中准备 JSON、日志、代码文件和 RAG 四组样本，同时放入重复噪声，以及不能丢失的错误码、行号、请求 ID、函数签名和引用位置。压缩前后固定模型版本、Prompt、工具结果及能够固定的生成参数，只切换 Headroom 链路；如果模型本身存在随机性，则重复运行后再比较，避免把一次生成波动误判成压缩损失。

Token 降幅必须按内容类型分别统计。除了压缩前后输入 Token 和压缩率，还应记录任务正确率或自动测试通过率、原文回取触发率与成功率、回取产生的额外 Token、p50/p95 延迟、失败率，以及本地组件的内存、加载时间和原文存储成本。输入与输出 Token 要分开，混合后的总百分比只能用于容量估算，不能代替质量判断。

缓存收益和输出侧节省不能混入压缩收益。资料还介绍了 CacheAligner 和 Output Shaper；如果测试环境启用了相关能力，应将输入压缩、Provider 缓存命中和输出长度变化分别做实验，或者至少保证 A/B 两侧配置完全一致。 否则缓存命中改善或输出变短，都可能被误算成 Headroom 的压缩效果。

本地处理也不等于可以忽略数据治理。二手资料将 Headroom 描述为本地压缩，但实际部署仍应核对遥测、外部请求、原文缓存位置、日志内容和保留周期，尤其不要把认证信息或带凭据的工具输出直接送入调试日志。 如果某段数据受保留策略、权限或审计要求约束，模型侧的压缩副本不能替代原始数据源。

短小、低冗余、不可改写的精确值，以及仍要交给程序解析的工具结果，适合设置绕过或回退规则。审计日志、RAG 原始索引和源代码文件也应继续保存原文；压缩结果只是发给模型的投影视图，不能成为唯一数据源。对于未知客户端，以及流式协议兼容范围和失败自动回退行为，应等待当前版本官方说明，不应仅凭其他 Agent 的成功案例推断。

最终应按内容类别灰度启用：JSON 高冗余输出可以优先验证，关键错误字段较多的日志则保留直接回原文的路径，代码文件和 RAG 分块分别建立质量基线。只有 Token 降幅稳定、任务结果通过验证、原文回取可用，而且延迟与存储成本可以接受时，才适合扩大启用范围；一旦出现关键字段遗漏、检索失败或质量回退，就针对该内容类型恢复原样直传，并继续核对版本配置、客户端兼容范围与流式请求支持情况。