Headroom 实战：给 Agent 装上上下文压缩层

Q: 「Headroom 实战：给 Agent 装上上下文压缩层」包含多少篇文档？

本文集目前收录 49 篇已发布文档，可在文集目录逐篇阅读。

Q: 「Headroom 实战：给 Agent 装上上下文压缩层」可以免费阅读吗？

本文集公开免费，无需登录即可阅读已发布文档。

文集信息
目录大纲
最新文档
知识宇宙

文集详情

文集导读

教程总纲 · Headroom 实战：给 Agent 装上上下文压缩层

讲什么、怎么学、怎么跳读，一页说清。本书面向 Agent 开发者：把工具输出、日志、文件、检索片段、会话历史在到达模型之前压小——同样的答案，一小部分 token。

一、这本书讲什么

一句话：教你给 Agent 装上一个本地运行的上下文压缩层（Headroom），并把它调对、看清、算清账。

展开成三句：

三层分工——上下文工程管「选什么进窗口」，缓存机制管「同前缀不重复付费」，压缩层管「进来的字节怎么压小」；Headroom 只做第三层，但与上两层各有接缝（第 0.1 节、第 6 章）。
按内容类型压——JSON 按字段方差、代码按语法树、日志按重复折叠、无结构文本交给自训模型、原件可存可取（CCR 可逆压缩）；压缩发生在内容到达 LLM 之前，本地运行、数据不出机器（官方口径）。
诚实核算——收益数字全部带口径（官方自测口径 / 社区口径 / 示意值），星标约 76.9k 需甄别（社区口径、增速需甄别），引入决定建立在自建账本而非宣传页上。

二、两张总图

第一张，三层分工——每层回答一个问题，三层叠加才是完整的省钱结构：


┌──────────────────────────────────────────────────────────────────┐
│                        模型上下文窗口（贵的）                      │
└──────────────────────────────────────────────────────────────────┘
     ▲                  ▲                    ▲
     │ 第三层：压缩      │ 第二层：复用        │ 第一层：选择
     │ 进来的字节        │ 同前缀不重复        │ 什么内容有资格
     │ 怎么压小          │ 付费                │ 进窗口
     │ （本书）          │ 《LLM 缓存机制      │ 《上下文工程》
     │                  │ 从零到一入门教程》   │
     │ Headroom：       │ KV / prompt cache  │ 检索式供给、
     │ 到达 LLM 之前    │ （平台机制）        │ 预算与驱逐
     │ 压缩内容         │                    │

第二张，Headroom 流水线——内容进来、对齐缓存、按类型分诊、压缩后组装，原件落入本地缓存以备取回：


 工具输出 / 日志 / 文件 / RAG 片段 / 会话历史
        │
        ▼
 ┌──────────────┐    ┌────────────────┐    ┌──────────────┐    ┌───────────┐
 │ CacheAligner │ ─▶ │ ContentRouter  │ ─▶ │ 各路压缩器    │ ─▶ │ 压缩后的   │
 │ 前缀对齐：    │    │ 按内容类型分诊  │    │ SmartCrusher │    │ 上下文     │
 │ 冻结已缓存    │    │                │    │ Code/Log/…   │    │ ──▶ LLM   │
 │ 只压新增字节  │    │                │    │ Kompress…    │    │           │
 └──────────────┘    └────────────────┘    └──────┬───────┘    └───────────┘
                                                  │ 原件存本地
                                                  ▼
                                          ┌──────────────┐
                                          │ CCR 本地缓存  │
                                          │ 可逆：随时    │
                                          │ headroom_     │
                                          │ retrieve 取回 │
                                          └──────────────┘

三、章节目录

第 0 章导览
　0.1 三层分工与本书位置：选择、复用与压缩
　0.2 60 秒跑通：第一次压缩调用

第 1 章问题与全景
　1.1 上下文的三笔账：输入、输出与缓存
　1.2 内容类型决定策略：为什么单一截断是错的
　1.3 四形态接入地图：库、代理、wrap 与 MCP

第 2 章架构拆解
　2.1 三大组件与数据流：CacheAligner、ContentRouter 与 CCR
　2.2 生命周期与扩展点：管道与三层定制
　2.3 本地优先与安全模型：数据边界与遥测

第 3 章压缩器专题 I：JSON、代码与日志
　3.1 SmartCrusher：JSON 的方差统计压缩
　3.2 CodeCompressor：AST 感知的代码压缩
　3.3 日志与 diff：重复的才是可压的

第 4 章压缩器专题 II：文本、文档与图像
　4.1 Kompress 模型压缩：无结构文本的兜底
　4.2 HTML、表格与配置：结构化文档的三种剥法
　4.3 ML 图像压缩：什么时候值得开 ML

第 5 章 CCR 可逆压缩
　5.1 Compress-Cache-Retrieve：可逆压缩的原理
　5.2 headroom-retrieve：把证据取回来
　5.3 压缩与检索的边界：取回与找回

第 6 章缓存协同
第 7 章接入实战
第 8 章记忆与学习
第 9 章输出侧治理
第 10 章评测与收益核算
第 11 章工程化与诚实边界

附录
　附录 A 术语表
　附录 B 命令与配置速查
　附录 C 练习题

四、逐章简介

第 0 章导览：把「上下文治理」拆成选择、复用、压缩三层，说明本书站在第三层；随后一条安装命令、一次 compress 调用、一眼 savings 统计，把压缩层跑起来。
第 1 章问题与全景：算清输入、输出、缓存交互三笔账；论证为什么单一截断是错的、内容类型决定策略；给出库、代理、wrap、MCP 四形态接入地图与从试用到生产的路径。
第 2 章架构拆解：CacheAligner、ContentRouter、CCR 三大组件与一次请求的完整旅程；十二个生命周期阶段与 transforms、pipeline extensions、proxy extensions 三层扩展点；本地优先安全模型与匿名遥测开关。
第 3 章压缩器专题 I：JSON 的方差统计（SmartCrusher，官方自测口径收益 60~95%）、代码的 AST 感知压缩（保签名去函数体）、日志与 diff 的重复折叠——结构化内容按结构压。
第 4 章压缩器专题 II：无结构文本的模型兜底（Kompress-v2-base）与 HuggingFace、ONNX 排坑；HTML 剥壳、表格列筛选、配置键值压缩；ML 图像压缩的收益与取舍（官方自测口径 40~90%）。
第 5 章 CCR 可逆压缩：压缩件进上下文、原件存本地的可逆原理；模型发现信息不足时主动调 headroom_retrieve 取回；取回（刚压掉的）与找回（库里的）的边界及组合架构。
第 6 章缓存协同：压缩改字节会打断 KV/prompt cache 前缀命中，CacheAligner 的 Live-zone 机制如何在「压小」与「不破坏缓存」间取衡（后半本）。
第 7 章接入实战：代理、wrap、MCP 三种形态的落地细节与灰度路径（后半本）。
第 8 章记忆与学习：压缩层与 Agent 记忆系统的协作边界（后半本）。
第 9 章输出侧治理：模型回写内容这一笔账的治理手段（后半本）。
第 10 章评测与收益核算：可复现基准的口径、复跑方法与自建账本——官方文档站基准总表压缩约 56%（126.4K 降至 55.1K token，官方口径）（后半本）。
第 11 章工程化与诚实边界：上线清单、依赖治理与官方数字的批判性阅读（后半本）。
附录：A 术语表、B 命令与配置速查、C 练习题（后半本）。

五、按需跳读

只想马上省钱：第 0.2 节跑通 ──▶ 第 1.3 节选形态 ──▶ wrap 你的 Agent ──▶ 第 2.3 节确认数据边界。
被日志和 JSON 胀死：第 1.2 节 ──▶ 第 3.1 节与第 3.3 节（JSON 与日志是最高收益区，官方自测口径）。
做编码智能体：第 3.2 节代码压缩 ──▶ 第 5 章 CCR ──▶ 第 7 章接入实战（后半本）。
担心压坏答案：第 1.2 节质量约束 ──▶ 第 5 章可逆压缩 ──▶ 第 10 章评测（后半本）。
架构评估：第 0.1 节 ──▶ 第 2 章全章 ──▶ 第 10 章与第 11 章（后半本）。

六、参考来源

Headroom 官方文档站（docs.headroomlabs.ai）：定位口号、安装与 extras、四形态接入、压缩器矩阵、基准与 Limitations 页（官方口径；官方自测口径数字均出于此或官方仓库说明）
GitHub 仓库 headroomlabs-ai/headroom：Apache-2.0 许可、Python 与 TypeScript SDK、Rust 组件、release 时间线（社区口径，星标增速需甄别）
《上下文工程》第 05 章《检索式上下文》、第 06 章《压缩与可观测》（概念层对口章）
《LLM 缓存机制从零到一入门教程》第 03 章《平台级Prompt缓存》（缓存协同的原理层）
《语义代码检索》第 01 章《为什么grep不够》、第 03 章《代码切分》（tree-sitter 与 AST 概念层）

目录大纲

知识宇宙

正在加载知识图谱...