headroom_retrieve工具注入原理LLM如何按需取回Headroom压缩掉的原始数据【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroomHeadroom 是一个开源的 LLM 上下文压缩项目它在工具输出、日志、文件进入大模型之前先做压缩为编码 Agent 节省约 20% tokenJSON 类内容可节省 60%–95%。它的核心秘密是 CCRCompress-Cache-Retrieve架构——压缩永远可逆。本文将带你拆解headroom_retrieve工具注入的完整原理Headroom 如何把一个取回工具偷偷塞进 LLM 的工具列表让模型在压缩数据不够用时自己按需取回原始数据全程对客户端透明。为什么压缩可以不丢数据传统压缩面临一个两难压缩太狠→ 可能丢掉 LLM 真正需要的数据压缩太保守→ 省不下 tokenHeadroom 的 CCR 架构消除了这个权衡压缩时把原始数据缓存在本地并留下取回凭证hash。如果模型需要完整数据随时可以取回。方案风险节省比例不压缩无0%传统有损压缩数据丢失70–90%CCR 可逆压缩无可取回70–90%四步走从压缩到取回的完整链路CCR 的完整流程分为四个阶段全部在代理层自动完成客户端零感知。第 1 步压缩 缓存Compression Store当 SmartCrusher 压缩工具输出比如 1000 条 JSON 压到 20 条时原始内容存入本地 LRU 缓存生成一个 hash 作为取回凭证在压缩结果里留下标记例如[1000 items compressed to 20. Retrieve more: hashabc123]这个标记就是模型日后兑换原始数据的钥匙。第 2 步工具注入Tool Injection——本文主角代理在转发请求前会扫描消息里的压缩标记一旦发现就执行两件事向 tools 数组注入headroom_retrieve工具定义OpenAI、Anthropic、Google 三种格式自适应向系统消息追加取回说明告诉模型有哪些可用 hash核心实现在 headroom/ccr/tool_injection.py 中的CCRToolInjector类。注入的工具定义长这样{ name: headroom_retrieve, description: Retrieve original uncompressed content that was compressed to save tokens..., parameters: { properties: { hash: { type: string } } } }两个精巧的设计细节归属校验verify_ownership()会先确认缓存中真的存在该 hash 才注入工具——避免别的上下文工具留下的相似标记误导模型去取一个必然落空的数据见 tests/test_ccr_golden_policy.py会话粘性一旦某会话用过 CCR该工具会持续保留在后续所有请求的工具列表中。看似多余实则是为了保护提示词缓存——工具列表字节级变化会导致 prompt cache 失效详见 REALIGNMENT/04-phase-B-live-zone.md第 3 步响应拦截Response Handler当 LLM 决定调用headroom_retrieve(hashabc123)时神奇的一幕发生了——代理自己接管了这个工具调用Response Handler 在响应中检测到 CCR 工具调用从本地缓存取回原始数据约1 毫秒把结果作为工具返回追加到对话自动发起下一次 API 调用直到 LLM 产出不再含 CCR 调用的最终响应才返回给客户端也就是说你的应用代码从头到尾看不到这次工具调用。默认最多循环 3 轮取回max_retrieval_rounds防止死循环。实现在 headroom/ccr/response_handler.py 的CCRResponseHandler类。第 4 步跨轮次追踪Context Tracker更聪明的能力追踪器会记住每一轮被压缩的内容并分析后续问题与缓存内容的相关性在模型开口问之前就主动展开相关数据。Turn 1: 文件搜索返回 500 个文件 → 压缩到 15 个hashabc123 Turn 5: 用户问auth 中间件呢 → 追踪器判断 auth 可能就在 abc123 里 → 主动展开压缩内容 → 模型直接在完整列表里找到 auth_middleware.py实现见 headroom/ccr/context_tracker.py它防的正是上下文失忆——早期被压缩的数据被后来的对话遗忘。一个完整的例子工具输出 100 条文件记录7,059 字符 ↓ SmartCrusher 压缩到 8 条633 字符节省 91% ↓ 原始数据缓存标记 hashabc123 ↓ headroom_retrieve 工具注入 LLM 先用 8 条尝试回答 ↓ 不够用 → 调用 headroom_retrieve(hashabc123) ↓ 代理拦截 → 本地取回 100 条 → 自动续跑 ↓ LLM 基于完整数据给出准确答案跑一下官方演示就能看到全过程python examples/ccr_demo.py官方演示如下不经过代理也能用MCP 模式headroom_retrieve不止存在于代理路径。Headroom 还把它作为 MCP 工具对外暴露Claude Code、Cursor、Codex 等任意 MCP 客户端都能直接使用。MCP 服务器提供三个工具工具作用headroom_compress按需压缩内容返回压缩文本 hashheadroom_retrieve凭 hash 取回原始内容支持 query 参数在原文中过滤headroom_stats查看会话压缩统计注册一次即可headroom mcp install。源码在 headroom/ccr/mcp_server.py无需运行代理即可本地压缩取回。实用配置速查缓存保留时长代理模式下原始数据默认保留 1800 秒30 分钟。长时 Agent 运行可用环境变量延长如HEADROOM_CCR_TTL_SECONDS7200 headroom proxy关闭响应处理headroom proxy --no-ccr-responses关闭主动展开headroom proxy --no-ccr-expansion查询缓存状态访问/v1/retrieve/stats查看当前 TTL 与条目数小结为什么这个设计值得学习headroom_retrieve的本质是把**压缩从一次性决策变成了可逆操作**缓存原始数据 hash 标记 取回凭证工具注入让模型知道可以取回响应拦截让取回过程对客户端完全透明跨轮次追踪甚至让展开先于需求发生更妙的是取回行为本身还会通过 TOIN 反馈机制反哺未来的压缩决策——模型取回过的内容模式下次会被更谨慎地对待。想深入阅读推荐这两份仓库内置文档CCR 架构详解wiki/ccr.md官方 CCR 指南docs/content/docs/ccr.mdx工具注入实现headroom/ccr/tool_injection.py响应拦截实现headroom/ccr/response_handler.py用激进的压缩省 token用透明取回兜住正确性——这就是 Headroom 给 LLM 工程的一个完整答案。【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
