附录 A 术语表

附录 A 术语表

本表收录全书后半本（第 06 至 11 章）的高频术语，按主题分组，每条给出一句话定义与出处章节。定义以本书用法为准，产品细节基于 v0.41.0，以官方文档为准。

一、压缩与缓存协同（第 06 章）

• 上下文压缩：把进入模型的长上下文替换为更短的等价表示，以降低输入 token 成本的整套技术。（第 01、06 章）
• 压缩层：独立于应用与 provider、在请求链路中间完成压缩的组件，Headroom 的本体。（第 02 章）
• CacheAligner：Headroom 的易变内容标记器——标记会破坏缓存前缀的时间戳、会话号等片段，但从不改写 prompt 一个字节。（第 6.2 节）
• live-zone：缓存协同的字节布局纪律——新增字节在入场前先压缩，冻结前缀只增不改，压缩只咬新增。（第 6.2 节）
• 冻结前缀：已进入历史请求、此后逐字节复现不再改写的 prompt 前段，是缓存命中的资产。（第 6.2 节）
• 缓存击穿：前缀被改写导致缓存全部失效、整条 prompt 按写价重算的现象，天真压缩的必然结局。（第 6.1 节）
• 天真压缩：每轮把全部历史重新总结再拼接的压缩方式，压缩率好看、缓存命中归零。（第 6.1 节）
• 净收益公式：净收益 = 压缩节省 − 缓存损失；评估压缩方案只看这一行总账。（第 6.1、6.3 节）

二、压缩器族（第 03 至 05 章，后半本回指）

• CCR：可逆压缩路线，压缩体可还原回原始内容，为冻结前缀提供信息底账。（第 05 章）
• 可逆压缩：保证解码还原的压缩，与「有损摘要」相对，审计与回滚场景的刚需。（第 05 章）
• AST 感知压缩：按代码抽象语法树结构做取舍的压缩器，保结构砍冗余。（第 03、04 章）
• SmartCrusher：面向高冗余内容（日志、样文）的粉碎式压缩器。（第 03、04 章）
• Kompress：通用压缩入口的统称式叫法，内部按内容类型分派。（第 03、04 章）
• 字段方差：结构化内容中各字段的取值变化度，方差低的字段是压缩优先目标。（第 04 章）
• 首尾项保留：列表与序列压缩时保留开头与结尾、压缩中段的策略。（第 04 章）
• ContentRouter：按内容类型把请求分派给对应压缩器的路由组件。（第 02、04 章）

三、接入形态（第 07 章）

• wrap / unwrap：一键包装/还原 Agent 启动过程的接入与撤销动作，覆盖 18 个 Agent（官方口径），Cursor 需手动。（第 7.1 节）
• Serena：wrap 默认联装的语义代码导航 MCP，可关闭，与压缩层互补不互赖。（第 7.1 节）
• headroom proxy：本地转发进程形态的零代码接入——应用只改一个接入地址。（第 7.2 节）
• ASGI CompressionMiddleware：给自研 ASGI 服务在框架层挂载压缩的中间件。（第 7.2 节）
• withHeadroom：SDK 集成的包装函数，包住模型客户端后调用代码零改动。（第 7.3 节）
• LiteLLM 单 callback：在 LiteLLM 网关注册一次即全站生效的集成形态。（第 7.3 节）

四、记忆与学习（第 08 章）

• 共享记忆：多个 Agent（Claude、Codex、Gemini、Grok 等）共用一份本地存储，写入一次全体可见。（第 8.1 节）
• 自动去重：共享记忆按语义指纹归并条目，使存储规模近似等于事实数量而非写入次数。（第 8.1 节）
• SharedContext：多 Agent 间以压缩形态传递任务上下文的接力机制，官方口径称传递量约降 80%。（第 8.2 节）
• failure learning：从失败会话的纠正回合里学习项目知识的机制，headroom learn 的学名。（第 8.3 节）
• 项目记忆文件：CLAUDE.local.md、CLAUDE.md、AGENTS.md、GEMINI.md 等 Agent 开局自动加载的规则文件。（第 8.3 节）

五、输出侧治理（第 09 章）

• verbosity steering：在系统提示尾部追加简明指令以减少冗余输出的机制，位置在尾部是为保缓存前缀。（第 9.1 节）
• effort routing：识别工具回读回合并自动降低 thinking 档位的机制。（第 9.2 节）
• 工具回读回合：上一条消息为工具结果、只需消化续读的回合，高挡位思考在此是纯浪费。（第 9.2 节）

六、评测与观测（第 10 章）

• holdout：留出不接受新配置的对照流量或题目子集，用作质量与收益的常驻对照组。（第 9.2、10.2 节）
• simulation 模式：不发真实 LLM 调用、只演示压缩形态的预演模式，零成本看「会压成什么样」。（第 6.3、10.1 节）
• headroom_retrieve：MCP 工具族中的检索工具，供 Agent 查回收纳的压缩内容（工具族全名单以官方文档为准）。（第 07 章）
• 四场景基准：seed 20260902 的可复现压缩基准——代码搜索、SRE 调试、代码库探索、issue 分诊，数字为官方自测口径。（第 10.1 节）
• 观测四件套：savings（累计节省）、dashboard（面板）、perf（性能开销）、doctor（环境体检）四个 CLI 入口。（第 10.3 节）

七、工程化与口径（第 11 章）

• 版本锁定：对 0.x 项目精确 pin 版本、快照配置、常驻冒烟的依赖管理策略。（第 11.1 节）
• API 漂移：高速迭代项目在 Python、TS、CLI 三层悄悄改变接口与行为的现象。（第 11.1 节）
• 遥测开关：HEADROOM_BEACON 环境变量，off 可关默认开启的匿名遥测。（第 11.2 节）
• 官方自测口径：数字由 Headroom 官方在自己的环境测得的标注，引用须注明、复现才算数。（第 10、11 章）
• 社区口径：星数、fork 数等社区侧数字的标注，增速需甄别，只用于判断社区活跃度。（第 11.3 节）
• 示意值：本书为演示量级关系而构造的数字标注，不代表任何实测结果。（全书）
• 方向性测量：只声称方向与量级、不声称精确收益的测量姿态，官方 Limitations 页的现状。（第 11.3 节）

八、三口径对照速查

一张表看懂全书为何反复强调标注：口径决定了数字的法定效力——同一串百分比，换一个口径，价值从「验收标准」跌到「广告词」。

提示：术语按章分组便于回读；口径类术语（第 8 组与速查表）建议新人入组第一天先学。