Headroom × context-mode 集成分析:工具边界准入控制与五款插件的落地路径

本文基于 Headroom 仓库中的集成分析文档 docs/context-mode-integration-analysis.md,系统拆解 context-mode 与 Headroom 在上下文优化上的分层关系、context-mode 可移植的知识产权清单、Headroom 已验证的扩展缝隙(entry-point 扩展机制)、五款拟议插件(P1–P5)及变体打包方案,以及必须先行解决的许可证硬阻塞与实施排序。读完后,你将掌握如何在 Headroom 现有插件架构上构建 FTS5 无损检索存储与跨 18 个 Agent 主机的工具边界准入控制,并理解其中的缓存安全与订阅安全论证。

1. 结论先行:两个系统攻击同一个成本问题,但位于不同层

分析文档开宗明义:context-mode 与 Headroom 在两个不同的层攻击同一个 token 成本问题,且在真正重要的地方互不重叠:

	context-mode	Headroom
拦截点	Agent 工具调用边界(宿主 hooks + MCP)	模型 API 边界(proxy / SDK / MCP)
相对上下文的位置	pre-context——数据根本不进入上下文	in-context——数据已进入上下文,再做挤压
机制	准入控制:阻止、重定向、沙箱、外置	压缩:crush、缓存、检索
是否触碰线上请求	从不	总是
有损性	无损(完整内容存入 FTS5,可查询)	有损挤压 + 哈希再水合(rehydrate)

Headroom 自己的重对齐文档 REALIGNMENT/00-overview.md 将其正确的压缩目标界定为 live zone(活动区):"最新一条 user 消息内容 + 最新 tool_result + 最新 function_call_output + 最新 local_shell_call_output"(Phase B)。而 Phase B 的原始问题是:ICM(IntelligentContextManager)曾对整条 messages 数组做评分删减,frozen_message_count: 0 硬编码导致每次压缩都从 index 0 丢消息,击穿 Anthropic 提示缓存——审计共发现 5 个顶级 cache-killer 缺陷。

context-mode 恰好拦截的就是 Headroom Phase B 要在 wire 之后压缩的那份 payload,只不过早了一层。 Phase B 构建 Rust 引擎来压缩"到达 wire 之后的"最新工具结果,而 context-mode 直接阻止该工具结果被生成。两者是互补而非竞争——上游位置严格更便宜:没有可压缩的东西、没有缓存失效、不需要 token 校验回退。

1.1 三个战略解锁,按价值排序

1. 缓存安全(Cache safety):Headroom 首要缺陷类别正是"请求变异导致的 prompt-cache 击穿"(5 个顶级 cache-killer,见 REALIGNMENT/00-overview.md)。context-mode 因从不触碰请求体而结构性地零缓存击穿风险。
2. 订阅安全(Subscription safety):重对齐文档标记了 X-Headroom-* header 泄漏、anthropic-beta 变异与 OAuth/订阅 CLI 上重序列化带来的"指纹级订阅吊销风险"。hook 层产品对此完全免疫——它对上游不可见。这是一种"代理到不了之处可部署"的能力。
3. 无代理部署(Proxy-free deployment):Headroom 当前价值依赖处在 API 路径上(127.0.0.1:8787)。文档实测:代理停掉后,headroom_stats 全零、headroom_compress 变成空操作。无法重定向模型流量的企业(TLS 信任、出网策略、订阅鉴权)目前什么也得不到;而 context-mode 的 hook+MCP 模式无需任何中间人。

文档同时确认:Headroom 代码树中目前零处引用 context-mode——一张干净的白纸。

2. context-mode 的可移植知识产权清单(IP 盘点)

context-mode 体量:41,617 行 TypeScript、11 个 MCP 工具、18 个宿主适配器,以 npm 分发(context-mode@1.0.169,8 个运行时依赖,esbuild 打包)。按"Headroom 重建它的难度"分层:

Tier 1 — 真正难,Headroom 无等价物

1. 跨宿主 hook 适配层(src/adapters/** 约 10K LOC、detect.ts 737 行、18 个宿主配置):把三种互不兼容范式——json-stdio(Claude Code、Gemini/Qwen、Copilot、Codex、Kimi、Cursor、Kiro、Antigravity)、ts-plugin(OpenCode、KiloCode、OpenClaw)、mcp-only(Zed、Pi、OMP)——归一到一套契约:标准化 PreToolUse / PostToolUse / PreCompact / SessionStart 事件、PlatformCapabilities 能力矩阵、五路决策(allow | deny | modify | context | ask),外加逐宿主安装、配置格式与自愈机制。难在价值全部沉淀在逐宿主的怪癖里,没有可对照的规范。
2. 工具边界策略引擎(src/security.ts,889 行):真正的策略决策点而非正则清单——glob→正则编译、链式命令拆分(&&/;/|,带转义感知)、子 shell 提取、从宿主配置文件摄入 deny/ask 模式、项目边界包含检查(evaluateProjectContainment,对应 Issue #852:已批准的 ctx_execute_file 不能借用户不可见的路径逃逸仓库),以及shell-escape 扫描器(SHELL_ESCAPE_PATTERNS、extractShellCommands):检测沙箱内非 shell 代码中嵌入的 execSync/subprocess,并把逃逸出来的命令重新提交策略评估。做错了就是 CVE。
3. 多语言沙箱执行器(executor.ts 785 行 + runPool.ts + exit-classify.ts + truncate.ts):12 种语言、stdout-only 出网、超时、后台 detach、输出上限、退出码分类,执行"Think in Code"契约——agent 用代码编程分析,只有答案进入上下文。
4. 无损外置存储(store.ts,2,071 行):双 SQLite FTS5 索引——token 化的 chunks 表,外加 chunks_trigram 三克表(BM25 分词对代码标识符/堆栈帧失效时的子串/标识符检索),配 vocabulary 表与 schema 迁移路径。任何 >100 KB 的输出自动外置进 FTS5 并返回指针;不丢弃任何东西,模型按需查询。

Tier 2 — 有价值,但与 Headroom 部分重复

5. 反事实节省核算(session/analytics.ts 3,085 行等):ContextSavings、ThinkInCodeComparison、RealBytesStats、MultiAdapterLifetimeStats、enumerateAdapterDirs()。它度量的是"本会进入上下文但实际没进入的量"——与 Headroom headroom/savings_ledger.py 记录的"实际压缩增量"是不同的、也更难的量。
6. 多厂商定价目录(pricing.ts + model-prices.json):61 个精选模型 × 4 个费率桶,未知模型返回 null 而非静默套用 Claude 价格。与 headroom/pricing/* 重度重叠,文档明确标注:不要移植。

Tier 3 — 不要移植

压缩启发式、memory/graph/relevance、遥测传输、dashboard、安装 UX、update-check——Headroom 全部已有且更成熟,Phase B/H 正在积极整合它们。

3. Headroom 的真实扩展缝隙(源码验证)

分析文档逐条核验了 Headroom 当前(本仓库 v0.37.0,见 pyproject.toml)已存在的扩展点——全部基于 importlib.metadata entry point 发现、全部 opt-in:

缝隙	Group	契约	源码位置
Proxy 扩展	headroom.proxy_extension	install(app: FastAPI, config: ProxyConfig) -> None	headroom/proxy/extensions.py
Pipeline 扩展	headroom.pipeline_extension	11 个阶段上的 on_pipeline_event(PipelineEvent)	headroom/pipeline.py
Learn 插件	headroom.learn_plugin	—	headroom/learn/registry.py
Memory 文本存储	headroom.memory_text	—	headroom/memory/config.py、headroom/memory/factory.py
Memory 向量存储	headroom.memory_vector	—	headroom/memory/config.py
Memory 存储	headroom.memory_store	—	headroom/memory/config.py
CCR 后端	headroom.ccr_backend	—	headroom/cache/compression_store.py
压缩钩子	(子类,非 entry point)	pre_compress / compute_biases / post_compress	headroom/hooks.py

两点值得特别注意:

• headroom/proxy/extensions.py 的模块 docstring 写明稳定性契约:"install(app, config) 的签名或 entry-point group 名称的任何变更都需要弃用周期"。这是受支持的公开缝隙,而非偶然。同一文档还定义了扩展的费用上报 API:record_scope_savings(scope, source, tokens, usd) 与 record_scope_timing(...),分别落到 /stats 的 savings.by_source、dashboard 卡片与 Prometheus 的 headroom_savings_attributed_usd_total{source=...};两者均有界(32 sources / 16 stages)、永不抛异常、永不改变响应——插件的遥测不能弄坏它所描述的那个请求。
• headroom/hooks.py docstring 原话:"Headroom SaaS implements position-aware compression and cross-turn deduplication via these hooks."——开放核心分层在设计时就是写好的。Pipeline 侧,PipelineStage 枚举定义了 SETUP、PRE_START、…、INPUT_COMPRESSED、PRE_SEND、POST_SEND、OUTCOME_OBSERVED 等 11 个稳定阶段(见 headroom/pipeline.py),OutcomeSnapshot 按构造只读——扩展声明它做了什么,核心记录实际发生了什么。

3.1 要抄的范本与要补的空白

范本:plugins/headroom-oauth2/ —— 自带 pyproject.toml、自带 LICENSE、自带 SPEC.md,注册在 headroom.proxy_extension 上,未启用 --proxy-extension oauth2 前处于休眠态,配置全走环境变量("zero core changes")。这就是企业插件模板。扩展的启用方式在源码 docstring 中也有明文:headroom proxy --proxy-extension myorg_ext,mypkg、环境变量 HEADROOM_PROXY_EXTENSIONS,或通配符 '*'。

现状:plugins/headroom-agent-hooks/ 已经把启动 hooks 装进 Claude Code 与 Copilot CLI(见 README,hook 调用 headroom init hook ensure)。注意本仓库 headroom/cli/wrap.py 中旧的 rtk / lean-ctx CLI 上下文工具已被移除——即分析文档中"先例"的形态在 v0.37.0 已收敛为 uninstall/迁移路径,新的宿主接入应走 plugins/ 与 entry point 而非 wrap CLI。

缺口:Headroom 没有任何工具边界拦截。 它只能在事后把 tool_use/tool_result 当作消息内容来读(headroom/parser.py、headroom/tokenizers/),PipelineStage 枚举中不存在 tool-result 阶段。context-mode 做的所有事情都发生在 Headroom 最早的 hook 之前。

4. 拟议插件与变体(按 价值÷工作量 排序)

P1 — headroom-recall:FTS5+trigram 无损存储,挂在 headroom.memory_text 上

做什么:把 context-mode 的 store.ts 移植到已存在的 headroom.memory_text 缝隙之后。

为什么排第一:这是对已存在契约的最小 diff,且修复一个真实产品限制。当前 headroom_retrieve(hash) 要求你知道哈希——MCP 工具描述原文就是 "The hash comes from headroom_compress results or from compression markers"(见 headroom/ccr/mcp_server.py 第 644 行附近)。有了 FTS5 后,retrieve-by-query 成为可能:问"那个构建日志对 OOM 说了什么",而不是"粘贴哈希 abc123"。trigram 索引尤其关键,因为 BM25 分词恰恰在标识符与堆栈帧上失效。

组合而非替换:compress → 返回挤压文本 + 哈希 → 原文存入 FTS5 → 按哈希或按查询再水合。它也是天然的 headroom.ccr_backend 实现——重对齐 Phase B 正要求 "CCR hardens: persistent backend"(REALIGNMENT/00-overview.md),而 headroom/cache/compression_store.py 中通过 entry_points(group="headroom.ccr_backend") 发现后端、HEADROOM_CCR_BACKEND 环境变量选择实现的机制已经就位。

企业变体:团队共享存储、保留/TTL 策略、按项目隔离(对应 context-mode 的 project-attribution.ts)、每次检索的审计。

工作量:中等。用 Python/Rust 按 Headroom memory 接口重写,或把 node 存储以 sidecar 形式发布。不要移植 MCP 工具面,只移植存储本身。

P2 — headroom-admission:跨 18 个宿主的工具边界准入控制

做什么:context-mode 的 adapter + hook 层,以 plugins/openclaw、plugins/opencode 的既有方式分发(plugins/ 下的 TS 包),节省量上报进 Headroom 的 savings_ledger.py JSONL,并发射 Headroom pipeline 事件。

为什么这是战略件:

• 给 Headroom 一个 pre-wire 执行点——位于 Phase B live-zone 引擎的上游,无需缓存击穿、无需 token 校验回退;
• 覆盖 18 个 agent 宿主——重对齐 Phase G 要求 "extend wrap CLIs (cline, continue, goose, openhands)",这项工作在此已做完还多;
• 提供订阅鉴权下可用的部署模式,而代理在这种场景是吊销风险。

企业价值——这是 Headroom 目前讲不了的 DLP 故事。Bash 工具调用里的 curl 根本不经过代理,Headroom 对它是盲的;context-mode 在工具边界拦截 curl/wget/WebFetch/内联 fetch()/requests.get,强制网络出网走 ctx_fetch_and_index。这把一个 token 节省特性转化为出网控制特性——不同的预算科目,不同的买家。

工作量:高,但主要是打包 + 上报桥,不是重写。保持 TypeScript;Phase H 淘汰的是 Python 代理 代码,安装器层是存活的 Python,可以 shell out。

P3 — headroom-policy(企业版,license 门控):策略决策点(PDP)

做什么:把 src/security.ts 作为 PDP,外加集中管理的组织规则集。

两个挂载点:P2 的 hook 层(工具级 allow/deny/ask),以及 headroom.pipeline_extension 的 PRE_SEND 阶段(prompt 级策略)——PRE_SEND 确实在 headroom/pipeline.py 的 PipelineStage 枚举中。策略事件喂给 headroom/audit/。

只有收费版才说得通的特性:集中策略服务、全组织 allow/deny 规则集、项目边界包含强制执行、沙箱代码内的 shell-escape 检测、防篡改审计轨迹、按团队报表。用 ELv2 license key 门控。

工作量:中等。引擎已存在且有测试(889 行 + tests/security/);要做的是控制平面。

P4 — headroom-sandbox:Think-in-Code 执行

做什么:把 executor.ts 暴露为 Headroom MCP 工具(headroom_execute),12 语言,stdout-only。

为什么:这是 context-mode 最大实测节省背后的机制——ctx_execute_file 在 315 KB 真实夹具上取得 98% 节省(BENCHMARK.md Part 1),对比 index+search 的 82%(Part 2)。编程分析胜过压缩输出。

必须与 P3 同发:shell-escape 扫描器正是防止沙箱变成逃逸口的那层。

工作量:中高。运行时隔离是难点;pyproject.toml 中已有一个 sandbox extra(torch-free 的精简代理配置,保留 tree-sitter 代码感知压缩、fastembed 相关性、HTML/表格摄入、OTel 等)可以在此基础上构建。

P5 — headroom-attribution:反事实节省 + 按项目成本

做什么:移植 session/analytics.ts 的方法论——RealBytesStats、ThinkInCodeComparison、enumerateAdapterDirs、project-attribution.ts——进 Headroom 的 savings_ledger / reporting / dashboard。

为什么:Headroom 度量的是压缩增量(挤掉了什么),context-mode 度量的是反事实(什么从未进入)。企业买家要的是后一个数字,且按团队与仓库切分。不要移植 pricing.ts——headroom/pricing/* 已用 litellm 解析做了这件事。

合并而非移植:headroom/audit/reads.py 已经是同一 Claude Code transcript 语料上的反事实度量工具(见下文第 6.3 节),机制分类更好;analytics.ts 有它缺失的多宿主覆盖与按项目归因。两者合并,而不是加第三个实现。

工作量:低-中,主要是度量定义合并。

变体(打包,不是代码)

• Headroom No-Proxy Edition —— 仅 P1+P2,零 API 中间人。卖给无法重定向模型流量的买家和所有订阅鉴权用户,移除 Headroom 最大的单一部署阻塞。
• Headroom Admission Control(企业) —— P2+P3+P4,中央策略平面 + 18 宿主的舰队注册。定位是 AI-agent DLP/治理,不是 token 节省。
• Headroom Fleet —— P5 + enumerateAdapterDirs,全组织的落地状态与成本报表。

5. 阻塞项:写代码之前必须解决

1. 许可证不兼容(硬阻塞)。 context-mode 是 Elastic License 2.0("Copyright 2026 Mert Koseoglu"),Headroom 是 Apache-2.0(本仓库 LICENSE,"Copyright 2025 Headroom Contributors")。

• ELv2 代码不能合并进 Apache-2.0 核心——不是技术细节,它会重新许可 Headroom 核心。
• ELv2 禁止把软件"作为托管或管理服务提供给第三方",直接约束 SaaS/managed 场景。
• 版权主体不同,意味着需要实体间的 IP 安排,而非工程决策。

好消息:Headroom 的插件架构正是让这件事可行的边界。一个自带 pyproject.toml 与 LICENSE、注册在 entry point 上的独立包(plugins/headroom-oauth2/ 的形态)可以承载 ELv2,核心保持 Apache-2.0。ELv2 本来就是 license-key 门控企业层的合适许可证——它明确设想这种用法。

建议:任何 context-mode 派生代码以单独许可的插件包形式放在 plugins/ 下,绝不 vendor 进 headroom/。先落笔 IP 安排。

2. 与重对齐的冲突。 Phases A–I 约 40 个 PR / 8–13 周,包含删除约 25K LOC。不要在 Phase B 中途开辟新集成战线。P1(headroom.memory_text / ccr_backend)是例外——它服务于 Phase B 的 "CCR hardens: persistent backend" 目标而非与之竞争。

3. Phase H 方向。 Python 代理代码正在退役(REALIGNMENT/00-overview.md Phase H 明确删除 headroom/proxy/server.py、transforms/* 等,保留 CLI wrappers、RTK installer、memory writers、tokenizers、TOIN)。不要新写 headroom/proxy/ 里的东西;目标是存活层:安装器、memory writers、CLI wrappers、Rust。

6. 排序与后续验证

6.1 实施顺序

顺序	项目	门禁
0	IP/许可证安排	任何代码之前
1	P1 headroom-recall — memory_text/ccr_backend 上的 FTS5 存储	落在 Phase B 之内,服务它
2	P2 headroom-admission — plugins/ 下的 18 宿主 hook 层	Phase A 稳定之后
3	变体:No-Proxy Edition = P1+P2	P2 在 3+ 宿主可用即可
4	P3 headroom-policy(企业,ELv2,key 门控)	P2 之后
5	P4 headroom-sandbox	与 P3 同发,绝不在其前
6	P5 headroom-attribution	机会主义推进

6.2 headroom-managed/ 是 SaaS 分支,且无许可证

分析文档核验:headroom-managed 包(name = "headroom-managed", description = "Headroom SaaS Platform - Managed context window optimization")有 app/auth.py、中间件、routes、services、alembic 迁移与 pilot/,但没有 license 字段也没有 LICENSE 文件——即默认专有。这收紧而非缓解 §5 的阻塞:ELv2 禁止"作为托管服务提供给第三方"的那类代码,恰恰不能进入名为 Managed 的产品,除非拿到版权方的明确商业授权。规划插件边界时,让 headroom-managed 只消费 Apache-2.0 核心接口,绝不消费 ELv2 实现。

6.3 headroom/audit/reads.py 独立验证了整个论点

它不是审计轨迹,而是度量工具:流式读取 Claude Code *.jsonl transcript,为每种 Read 压缩机制量化"可寻址字节",让默认值"来自流量而非理论"。其 docstring 中两句话是整个仓库最有用的佐证:

• "context residency — each Read 在上下文中停留多少个 assistant 回合(其前缀缓存读成本的乘数;即 compress-before-cache-entry 的论据)" —— Headroom 已经在用自己的流量论证往管道上游移动。context-mode 正是这个论证的终点:在 context 进入之前压缩,而不仅仅在缓存进入之前。
• "identical repeat — 某去重机制曾做原型后被移除:在真实流量上只占 Read 字节的 0.1%" —— Headroom 已用实证确立了消息历史级去重毫无价值,可寻址字节在工具边界而非历史里。这与重对齐从缓存侧独立得出的结论一致。

它确实与 P5 重叠:audit/reads.py 与 context-mode 的 session/analytics.ts 是同一 transcript 语料上两个独立的反事实度量实现——合并,而不是移植;前者机制分类更好,后者有它缺失的多宿主覆盖与按项目归因。

6.4 基准与证据:先跑,再宣称

context-mode 的 BENCHMARK.md:21 个场景、376 KB 原始 → 16.5 KB 上下文,总体 96%,夹具全部来自真实工具调用(Context7、Playwright、gh、vitest、tsc、nginx 日志、git log、analytics CSV);对自己弱项也诚实——0.4 KB Playwright 网络 dump 上只有 13%,Part 2 公开解释 index+search 为何只到 50–93%(按设计返回精确代码块而非摘要)。

Headroom 不发布基准结果:benchmarks/results/ 下仅有一份 index_proof_table.txt,没有可与 96% 对标的数字。但 harness 在关键维度上异常强大:benchmarks/ 下有 prefix_cache_benchmark.py、cache_bust_trace_report.py、cache_validation_bundle.py、synthetic_token_cache_bust_report.py、proxy_mode_benchmark.py、agent_cost_benchmark.py、real_world_agent_benchmark.py。文档的建议是:用它来实证第 1 节的缓存安全论断,而不是断言——一次"零缓存击穿事件"的测量结果是 No-Proxy Edition 最强的佐证工件。

6.5 附带发现:平台轴正交

docs/platform-feature-matrix.json(schema v1,updated 2026-07-06)追踪的平台轴是 ["linux", "macos", "windows"]——Headroom 的平台轴是操作系统;context-mode 的平台轴是agent 宿主(18 个)。Headroom 完全不追踪宿主覆盖矩阵,因此 P2 填的是一个在 Headroom 自身特性核算中尚不存在的维度——它需要第二张矩阵,而不是在这张上加行。

7. 小结

这份集成分析的核心判断是:context-mode 与 Headroom 互补而非竞争,上游拦截严格便宜于下游压缩。落地路径完全沿着 Headroom 已存在的公开缝隙——headroom.memory_text / ccr_backend(P1,服务 Phase B)、plugins/ 目录下的 TS 包(P2,补齐 Headroom 目前完全缺失的工具边界维度)、headroom.pipeline_extension 的 PRE_SEND(P3)、既有 sandbox extra(P4)、以及 savings_ledger + audit/reads.py 合并(P5)。前置条件只有两条:实体间 IP/许可证安排先落笔,以及不在重对齐 Phases A–I 的关键路径上开辟平行战线。

适用前提与限制:本分析以 context-mode v1.0.169 与 Headroom main(分析日期 2026-07-29)为准;文中对 src/*.ts、BENCHMARK.md、headroom-managed/ 的描述均来自该分析文档对 context-mode 仓库与 Headroom 当时工作区的核验,本仓库 v0.37.0 中 rtk/lean-ctx CLI 工具已被移除,实际代码路径与行号可能随版本演进变化,落地前应对照当前仓库状态重新核对。