--- title: "研究与知识参考：headroom - 研究与知识 | 思行致远" canonical: "https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/skill-library-research-headroom/" dateModified: "2026-06-30" datePublished: "2026-06-30" --- 打开 AI·外脑目录 AI·外脑 [返回专栏首页](https://siyuanailab.com/knowledge/) × 站内搜索 ⌕ 主要栏目 - [AI 核心概念](https://siyuanailab.com/knowledge/ai-core/) - [工作流](https://siyuanailab.com/knowledge/workflows/) - [工具配置与选型](https://siyuanailab.com/knowledge/toolkits/) - [信源与标准](https://siyuanailab.com/knowledge/sources/) - [场景案例 待开发](https://siyuanailab.com/knowledge/scenarios/) - [职业与能力](https://siyuanailab.com/knowledge/career/) 专题 - [从这里开始](https://siyuanailab.com/knowledge/start/) - [获取与安装](https://siyuanailab.com/knowledge/install/) - [建设日志](https://siyuanailab.com/knowledge/ops/) [工作流子目录](https://siyuanailab.com/knowledge/workflows/) 基础设施层 - [浏览器自动化 **5**](https://siyuanailab.com/knowledge/workflows/infrastructure/browser-automation/) - [MCP 工具 **5**](https://siyuanailab.com/knowledge/workflows/infrastructure/mcp-tools/) - [文件系统与本地执行 **5**](https://siyuanailab.com/knowledge/workflows/infrastructure/filesystem-local/) - [API 网关与工具路由 **5**](https://siyuanailab.com/knowledge/workflows/infrastructure/api-tool-routing/) Skill 生产线 - [目标明确 **5**](https://siyuanailab.com/knowledge/workflows/skill-forge/goal-definition/) - [Skill 设计 **5**](https://siyuanailab.com/knowledge/workflows/skill-forge/skill-design/) - [代码实现 **5**](https://siyuanailab.com/knowledge/workflows/skill-forge/implementation/) - [测试评估 **5**](https://siyuanailab.com/knowledge/workflows/skill-forge/testing-evaluation/) Skill 参考库 - [写作与内容 **5**](https://siyuanailab.com/knowledge/workflows/skill-library/writing-content/) - [研究与知识 **5**](https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/) - [WF-046 研究与知识参考：arxiv sanity bot](https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/skill-library-research-arxiv-sanity-bot/) - [WF-047 研究与知识参考：headroom](https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/skill-library-research-headroom/) - [WF-048 研究与知识参考：knowledge base builder](https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/skill-library-research-knowledge-base-builder/) - [WF-049 研究与知识参考：llmwiki](https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/skill-library-research-llmwiki/) - [WF-050 研究与知识参考：paper2md](https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/skill-library-research-paper2md/) - [沟通与协作 **5**](https://siyuanailab.com/knowledge/workflows/skill-library/communication-collaboration/) - [产品与项目 **5**](https://siyuanailab.com/knowledge/workflows/skill-library/product-project/) - [数据与分析 **5**](https://siyuanailab.com/knowledge/workflows/skill-library/data-analysis/) - [创意与设计 **5**](https://siyuanailab.com/knowledge/workflows/skill-library/creative-design/) - [商业与营销 **5**](https://siyuanailab.com/knowledge/workflows/skill-library/business-marketing/) Agent Building 只收录有多步工作流、工作标准、Loop、Harness、工具链或通信机制的真 Agent；不收纯 persona、profile、curated list 或只有 system prompt 的仓库。 - [多 Agent 框架 **5**](https://siyuanailab.com/knowledge/workflows/agent-building/multi-agent-frameworks/) - [工作流编排 **5**](https://siyuanailab.com/knowledge/workflows/agent-building/workflow-orchestration/) - [Sub-agent 模式 **5**](https://siyuanailab.com/knowledge/workflows/agent-building/sub-agent-patterns/) - [Harness 与评估 **5**](https://siyuanailab.com/knowledge/workflows/agent-building/harness-evaluation/) Skill 参考库 · 研究与知识 · Skill 解读 · WF-047 # 研究与知识参考：headroom 思行致远 · 2026/6/30 · 置信度：高 研究知识库摘要RAG 一个本地优先的 Agent 上下文压缩层，在工具输出、日志、RAG chunk 和文件进入 LLM 前做内容感知压缩，并可按需找回原文。 # headroom > 一个本地优先的 Agent 上下文压缩层，在工具输出、日志、RAG chunk 和文件进入 LLM 前做内容感知压缩，并可按需找回原文。 ## 这个能力解决什么问题 Agent 工具输出常常是长 JSON、日志、代码搜索结果或网页文本。Headroom 解决的是“如何减少进入模型的 token，同时保留后续推理所需信息”。输入是 messages、tool outputs、RAG chunks、files 或 conversation history；输出是压缩后的 prompt，以及可通过 retrieval 工具取回的原始片段。 ## 核心逻辑 Headroom 在本地代理或库中拦截上下文，先用 `CacheAligner` 稳定 prompt 前缀，提高 KV cache 命中；再由 `ContentRouter` 判断内容类型，把 JSON 交给 `SmartCrusher`，代码交给 AST-aware `CodeCompressor`，普通文本交给 HuggingFace `Kompress-v2-base`；最后 CCR 把原文缓存在本地，模型看到压缩内容，需要细节时调用 `headroom_retrieve`。 ## 技术结构 - 关键模块：Library `compress()`、OpenAI-compatible proxy、`headroom wrap`、MCP server、cross-agent memory、`headroom learn`、dashboard/doctor/perf。 - 调用链路：Agent/app -> Headroom proxy/library/wrap -> content router/compressor/CCR -> LLM provider -> 可选 retrieve。 - 输入输出：输入是聊天消息和工具结果；输出是压缩 prompt、统计、retrieval handle 和节省报告。 - 核心依赖：Python 3.10+、TypeScript SDK、ONNX/HF model、可选 ML/code/vector/memory extras、MCP。 ## 为什么值得参考 它不是摘要工具，而是 Agent 中间件。最有价值的是把压缩做成多种接入形态：库、代理、wrap、MCP；并且通过 CCR 保留“压缩后可找回”的审计路径。对长上下文工作流来说，这比简单截断更可控。 ## 为什么不建议直接套用 项目依赖较重，`[all]` 会拉多类额外能力，部分向量后端还需要 C++ 工具链。压缩策略会改变模型看到的上下文，不适合对原文完整性要求极高的法律、医疗、财务材料。代理和 wrapper 会影响多个 Agent 的运行环境，团队共享时要明确全局配置和缓存 TTL。 ## 如何改造成自己的版本 先做一个小型“工具输出压缩器”，只处理三类最常见输入：JSON 搜索结果、日志、网页正文。输出必须带 `dropped_fields`、`retention_reason`、`retrieve_key`。先用离线样本测任务完成率，再考虑接 proxy 或 MCP；不要一开始包装所有 Agent。 ## 适用场景 - 代码搜索、日志排障、RAG 返回过长。 - 多 Agent 共享上下文和记忆。 - 需要本地缓存原文并可回查。 ## 不适用场景 - 上下文很短，压缩成本高于收益。 - 必须逐字保留原文的高风险文档。 - 不允许本地代理或 wrapper 改写请求的环境。 ## 参考信息 - 原项目：[headroom](https://github.com/headroomlabs-ai/headroom) - 作者：headroomlabs-ai - 相关概念：[[上下文压缩]]、[[可逆压缩]] - 相关卡片：保守留空 ## 参考对象信息 **名称：**headroom **作者：**headroomlabs-ai **链接：**[https://github.com/headroomlabs-ai/headroom](https://github.com/headroomlabs-ai/headroom) ## 适用场景与行动 **场景：**Skill 参考库 / 研究与知识 **适合谁：**关注 AI 工作流、Skill 生产和 Agent Building 的读者 **下一步：**先阅读边界说明，再判断它是否适合改造成自己的研究与知识流程。 当前内容按公开来源和已审核草稿整理，只作为工作流理解与方法论参考。 涉及客户数据、外部平台、会议记录和业务系统的场景，必须保留人工确认与授权边界。 [上一张：研究与知识参考：arxiv sanity bot](https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/skill-library-research-arxiv-sanity-bot/) [下一张：研究与知识参考：knowledge base builder](https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/skill-library-research-knowledge-base-builder/) [返回当前分类](https://siyuanailab.com/knowledge/workflows/skill-library/research-knowledge/) [返回工作流专栏](https://siyuanailab.com/knowledge/workflows/)