Headroom 从吸收到使用的完整方案

Headroom 从吸收到使用的完整方案

结论

Headroom 在本机体系中的最佳定位不是“CPA 前置插件”，而是 provider-agnostic 的运行时上下文压缩层：所有现有 provider 和之后新增 provider，都应该具备“可选择走 Headroom 压缩层”的统一入口。

但它仍然不替代 Hermes / gateway / provider router / Hindsight / wiki。正确边界是：Headroom 只负责在请求进入具体 provider 之前压缩 input context，provider 选择、fallback、认证、模型路由、记忆治理仍归现有 Hermes/provider 体系。

最终决策：Sidecar + Partial Absorb。默认目标不是只服务 CPA，而是形成统一的“所有 provider 可接入”的压缩网关层；上线节奏仍是先试点、可回退、再扩大默认覆盖。

重新锚定：CPA 不是主力 provider

前版方案把 CPA 当成主要上游，这是不准确的。CPA 只是当前本机已有的一个 provider/proxy endpoint，不应成为 Headroom 方案的中心。

新的中心原则：

1. provider 无关：不管上游是 CPA、自定义 OpenAI-compatible provider、Anthropic-compatible provider、JUN shim、Krill、Codex CLI alias，还是未来新增 provider，都按同一压缩接入规范管理。
2. 路由权不下放：Headroom 不决定选哪个 provider，也不做业务 fallback；它只处理已经选定 provider 的请求压缩。
3. 新增 provider 默认纳入评估：以后每新增 provider，都必须回答“是否支持 Headroom 压缩路径、如何回退、哪些模型/任务默认不开”。
4. 直连路径永久保留：每个 provider 都必须有 direct route 和 headroom route 两条路径，方便 A/B、排障和回退。

总体架构

推荐形态：统一压缩层 + 多上游映射

逻辑拓扑：

这意味着 Headroom 的位置不是“CPA 前面”，而是“provider router 之后、具体 upstream 之前”。

两种可落地实现

#### 方案 A：多 Headroom sidecar，每个 upstream 一个端口

适合最小改动试点。

优点：

• 不改 Hermes 主路由；
• 每个 provider 可独立开关；
• 故障隔离强；
• 最容易验证和回退。

缺点：

• provider 多时端口和 service 增多；
• 需要统一命名和配置治理。

#### 方案 B：一个 Headroom gateway，动态选择 upstream

适合后续正式化。

优点：

• 统一入口；
• 后续新增 provider 更干净；
• 便于统一 metrics。

缺点：

• 需要确认 Headroom 当前是否原生支持 per-request upstream；
• 若不支持，需要 Hermes 侧或轻量 wrapper 做 upstream dispatch；
• 故障域更集中。

当前推荐：先用方案 A 试点，形成 provider onboarding contract；如果 provider 数量和收益证明值得，再升级到方案 B。

Provider 接入规范

每个 provider 必须登记两条路径：

命名建议：

例子：

注意：如果某个 provider 不是 OpenAI-compatible API，需要先确认 Headroom 是否支持对应协议；不支持时不能硬套，应在 Hermes/provider adapter 层前做压缩，或暂时只保留 direct route。

新增 provider 的准入流程

以后每新增 provider，固定走 6 步：

1. 识别 API mode

• OpenAI-compatible / Anthropic-compatible / custom / CLI shim。

1. 确认是否可被 Headroom 代理

• 如果是 OpenAI-compatible，优先走 sidecar。
• 如果不是，评估是否需要 adapter 或暂不接。

1. 创建 direct route

• 先确保不经 Headroom 能稳定跑。

1. 创建 headroom route

• 不替换 direct route，只新增压缩路径。

1. 跑 4 类验证

• JSON tool result；
• logs / RAG text；
• code / patch 保护；
• direct vs headroom 输出质量和延迟对照。

1. 登记策略

• 哪些任务默认可走；
• 哪些任务禁用；
• 回退命令；
• 观测指标。

吸收清单

P0：必须吸收

1. 统一压缩策略层

• 按任务类型和消息类型决定是否压缩，而不是按 provider 写死。

1. ContentRouter / SmartCrusher 思路

• JSON、API 返回、搜索结果、列表型 tool output 优先压缩。

1. CCR 可逆压缩

• 被压缩内容必须能按需 retrieve。

1. exclude tools / sensitive boundary

• read_file、headroom_retrieve、write_file、patch、secret-like 输出默认排除或保护。

1. code-aware 保护

• 代码、diff、patch、配置、路径、标识符宁可不压缩，也不能损坏。

1. direct/headroom 双路径

• 每个 provider 必须保留直连路径。

P1：参考吸收

1. CacheAligner：稳定 prompt 前缀，提高 provider cache 命中。
2. verbosity dial：低风险例行任务降低输出冗余。
3. effort routing：routine task 降 effort，新问题/错误/full debug 保持高 effort。
4. savings metrics：统一记录 token、latency、质量、fallback。

不吸收

1. Headroom memory：不替代 Hindsight / session_search / LCM / wiki。
2. headroom learn：不允许自动写 AGENTS.md / CLAUDE.md。
3. dashboard 壳：只参考指标，不引整套 UI。
4. agent wrap 全家桶：不包主入口，不改变 Hermes 控制面。
5. Copilot OAuth：暂不纳入统一 provider 方案。

使用情景

默认应该走 Headroom 的场景

1. 大 JSON / API 返回分析；
2. GitHub issue / PR / commit / tree 批量读取；
3. 日志诊断；
4. RAG / 网页抽取 / 多文档总结；
5. 大型测试输出总结；
6. cron 批处理 / 多 agent 批量读取；
7. 长工具链任务里的历史 tool outputs。

谨慎走 Headroom 的场景

1. 论文、法律、政策等需要逐字引用的内容；
2. 复杂代码 review；
3. provider 行为排障；
4. 模型输出差异 A/B；
5. 涉及私密路径、凭证、token、密钥片段的工具结果。

不走 Headroom 的场景

1. 小任务、普通聊天；
2. 精确 patch / config / SQL / migration；
3. 密钥、凭证、认证头；
4. 最终发布内容生成，比如 Decision Trace / wiki / 飞书正文；
5. Hindsight、session_search、LCM 等记忆治理主链路；
6. 任何还没验证过 direct route 的新 provider。

部署建议

端口规划

不要用 8787。8787 是 WebUI tunnel 预留。

建议：

正式化后可以用一个 registry 文件管理：

安装形态

统一独立 venv：

不装 [memory] / [all]。

单 provider sidecar 示例

每个 provider 的 systemd user service 单独命名：

验证方案

每个 provider 必测

关键测试纪律

必须使用 role=tool + tool_call_id 格式测试。用普通 role=user 发送大 JSON 得到 0% 压缩，不能说明 Headroom 无效。

上线前还要查：

日常使用方法

方式 1：显式指定 headroom provider

用户或任务明确说“高 token / 大日志 / 大 JSON / 走压缩”时，选择 <provider>-headroom。

方式 2：策略自动选择

后续可在 Hermes/provider routing 增加 policy：

自动选择必须保留 override：

方式 3：cron / batch 专用

cron 适合优先走 headroom，因为输入通常长、格式稳定、可回退。

cron prompt 应明确：

• provider route；
• 压缩路径；
• 原文路径保留；
• 失败切 direct；
• 输出短摘要。

回退策略

每个 provider 的回退都是把：

切回：

不能让 Headroom 故障影响：

• Hermes gateway；
• Feishu；
• wiki；
• Hindsight；
• session_search；
• provider direct route。

治理与观测

每次真实使用记录：

• provider / model；
• direct route；
• headroom route；
• prompt tokens before / after；
• saved ratio；
• latency delta；
• compression strategy；
• fallback 是否发生；
• retrieve 是否发生；
• 质量判断。

复评门槛：

• 单 provider 平均节省 <20%：不默认启用；
• 稳定 30%+ 且质量无下降：纳入推荐场景；
• 稳定 40%+ 且延迟可接受：纳入自动策略候选；
• 出现事实丢失、patch 损坏、provider 行为异常：立即切 direct，并把该任务类型加入禁用清单。

最终执行清单

第 0 步：修正方案口径

• 不再写成 CPA 专属。
• Headroom 定位为所有 provider 可接入的压缩层。
• CPA 只是一个被接入 provider，不是中心。

第 1 步：建立 provider onboarding contract

• direct route；
• headroom route；
• support matrix；
• fallback；
• benchmark；
• disable list。

第 2 步：先挑 1–2 个 provider 试点

优先选：

1. 当前真实高频 provider；
2. OpenAI-compatible endpoint；
3. 大 tool output 场景多的 provider。

不要一开始全局替换。

第 3 步：扩展到所有 provider

每个新增/已有 provider 都补齐：

第 4 步：纳入长期治理

把 Headroom 接入状态做成 provider registry 的一部分，而不是散落在临时 shell env 里。

最终判断

修正后的完整方案是：Headroom 不围绕 CPA 建，而是围绕“所有 provider 的统一上下文压缩入口”建。实现上先用多 sidecar 试点，保证每个 provider 都有 direct/headroom 双路径；治理上把 Headroom 变成 provider onboarding contract 的固定字段。只有这样，之后新增 provider 才不会每次重新讨论压缩层怎么接，也不会把 CPA 错误固化成主力前提。