聊聊我给 Headroom 贡献第一个插件的三天

最近在折腾自己的 AI 基础设施时，尝试将自托管的 Hermes Agent 流量挂载到上下文压缩利器 Headroom 代理上，试图给大模型“脱水”降本。

然而刚跑起来就遇到了严重问题：Headroom 的压缩标记（如 Hash 占位符）在 Hermes 眼里成了一个完全不透明的“黑盒”。Agent 读取到被压缩的 Tool Outputs 后无法向下推导，开始疯狂幻觉并反复重试相同命令。

在 Fable 5 的全程“老司机”式协助下，我们用了 3 天时间完成了一次从排查、本地验证、开源提案到最终合并（Merge）的闭环：

痛点沉淀：除了 Hash 盲区，还顺带揪出了 Headroom 默认 300s TTL 导致 Agent 无法回溯几分钟前历史上下文的细节。

解题思路：本着“高价值、低风险”的原则，我没有去侵入和修改 Headroom 脆弱的核心路由代理，而是选择在外围利用其公开的 /v1/retrieve 端点，为 Hermes 编写了一个约 90 行、零新依赖的独立扩展插件（headroom_retrieve）。

开源反馈：在 Issue #796 提交工作实现后，项目 Owner chopratejas 给予了极高评价（“This is fantastic... Please do open the PR!”）。最终对应的 PR #824 已由维护者正式合入主分支。

一点开源心得： 给不熟悉的开源项目提贡献时，“非入侵式的外置插件”往往是最容易被社区接受的切入点。它既完美打通了 Hermes + Headroom 用户的最后一公里体验，又免去了让核心维护者进行大规模回归测试的顾虑。

GitHub Issue 讨论地址：https://github.com/chopratejas/headroom/issues/796#issuecomment-4674079469

合并后的代码拉取请求 (PR)：feat(plugins) 合并记录
https://github.com/chopratejas/headroom/pull/824#event-26650929014

Headroom 项目主页：akb4q/headroom 仓库