headroom_retrieve工具注入原理：LLM如何按需取回Headroom压缩掉的原始数据-育师

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/headroom

Headroom 是一个开源的 LLM 上下文压缩项目：它在工具输出、日志、文件进入大模型之前先做压缩，为编码 Agent 节省约 20% token，JSON 类内容可节省 60%–95%。它的核心秘密是 CCR（Compress-Cache-Retrieve）架构——压缩永远可逆。本文将带你拆解headroom_retrieve工具注入的完整原理：Headroom 如何把一个"取回工具"偷偷塞进 LLM 的工具列表，让模型在压缩数据不够用时，自己按需取回原始数据，全程对客户端透明。

为什么压缩可以"不丢数据"？

传统压缩面临一个两难：

压缩太狠→ 可能丢掉 LLM 真正需要的数据
压缩太保守→ 省不下 token

Headroom 的 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: hash=abc123]

这个标记就是模型日后"兑换"原始数据的钥匙。

第 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(hash=abc123)时，神奇的一幕发生了——代理自己接管了这个工具调用：

Response Handler 在响应中检测到 CCR 工具调用
从本地缓存取回原始数据（约1 毫秒）
把结果作为工具返回追加到对话，自动发起下一次 API 调用
直到 LLM 产出不再含 CCR 调用的最终响应，才返回给客户端

也就是说，你的应用代码从头到尾看不到这次工具调用。默认最多循环 3 轮取回（max_retrieval_rounds），防止死循环。实现在 headroom/ccr/response_handler.py 的CCRResponseHandler类。

第 4 步：跨轮次追踪（Context Tracker）

更"聪明"的能力：追踪器会记住每一轮被压缩的内容，并分析后续问题与缓存内容的相关性，在模型开口问之前就主动展开相关数据。

Turn 1: 文件搜索返回 500 个文件 → 压缩到 15 个（hash=abc123） Turn 5: 用户问"auth 中间件呢？" → 追踪器判断 "auth" 可能就在 abc123 里 → 主动展开压缩内容 → 模型直接在完整列表里找到 auth_middleware.py

实现见 headroom/ccr/context_tracker.py，它防的正是"上下文失忆"——早期被压缩的数据被后来的对话遗忘。

一个完整的例子

工具输出 100 条文件记录（7,059 字符） ↓ SmartCrusher 压缩到 8 条（633 字符，节省 91%） ↓ 原始数据缓存，标记 hash=abc123 ↓ headroom_retrieve 工具注入 LLM 先用 8 条尝试回答 ↓ 不够用 → 调用 headroom_retrieve(hash="abc123") ↓ 代理拦截 → 本地取回 100 条 → 自动续跑 ↓ LLM 基于完整数据给出准确答案

跑一下官方演示就能看到全过程：python examples/ccr_demo.py，官方演示如下：

不经过代理也能用：MCP 模式

headroom_retrieve不止存在于代理路径。Headroom 还把它作为 MCP 工具对外暴露，Claude Code、Cursor、Codex 等任意 MCP 客户端都能直接使用。MCP 服务器提供三个工具：

工具	作用
`headroom_compress`	按需压缩内容，返回压缩文本 + hash
`headroom_retrieve`	凭 hash 取回原始内容（支持 query 参数在原文中过滤）
`headroom_stats`	查看会话压缩统计

注册一次即可：headroom mcp install。源码在 headroom/ccr/mcp_server.py，无需运行代理即可本地压缩+取回。

实用配置速查

缓存保留时长：代理模式下原始数据默认保留 1800 秒（30 分钟）。长时 Agent 运行可用环境变量延长，如HEADROOM_CCR_TTL_SECONDS=7200 headroom proxy
关闭响应处理：headroom proxy --no-ccr-responses
关闭主动展开：headroom proxy --no-ccr-expansion
查询缓存状态：访问/v1/retrieve/stats查看当前 TTL 与条目数