Headroom Phase B 深度解析：Live-Zone 定向压缩引擎的七 PR 重构蓝图与落地实现

本文基于 Headroom 仓库的重构规划文档 Phase B — Live-Zone-Only Compression Engine 展开，系统讲解"只压缩 live zone（活动区）消息块、绝不触碰缓存热区"这一新压缩架构的设计动机、七个 PR 的拆分逻辑（B1 大删除到 B7 CCR 加固），并结合当前仓库中已经落地的 Rust 调度器、内容类型检测器、CCR 持久化后端与 TOIN/Memory 改造源码，说明该规划如何转化为可运行、可验证的实现。读完后你可以掌握：如何在不破坏 LLM 提供商 prompt cache 的前提下对请求体做"字节级外科手术"式压缩，以及 token 校验门、阈值门、可检索原始数据（CCR）标记注入的完整工程链路。

一、问题背景：为什么必须"只在 live zone 压缩"

Phase B 的目标在文档中一句话概括：删除约 10K LOC 的架构过度设计（ICM、scoring、relevance、rolling-window、progressive-summarizer、tool-crusher），建立正确的架构——只针对 live zone 做按块压缩，配合类型感知调度、token 校验与 CCR 加固。

理解这个目标的关键是 live zone 的边界定义。结合 live_zone.rs 模块头的注释，Anthropic /v1/messages 请求的 live zone 由三条边界划定：

• 下界（Floor）：frozen_message_count——由 cache_control 显式标记计算得到（仓库中该函数经 headroom-core lib.rs 以 compute_frozen_count 导出）。索引低于下界的消息已经在 prompt cache 中，必须字节级不变；
• 上界（Ceiling）：最新的 user 消息。最新的 assistant 消息（若存在）同样属于缓存热区——它是下一次响应的接续点，永远不碰；
• 最新 user 消息内部：每个块都是压缩候选，其中 tool_result 是最典型的压缩目标（工具输出占据 token 预算的大头），text 块同样合格（例如用户粘贴的长日志）。

而"压缩结果如何不破坏缓存"这一正确性核心，源码注释给出了明确答案——字节区间手术（byte-range surgery）：

out = body[..block_start] || replacement || body[block_end..]

重写块以外的一切字节都从原始输入直接拷贝，而非"反序列化 → 修改 → 重新序列化"。因为 JSON 重序列化无法保留原始空白、键序细节和数字格式，而这些都可能是提供商已经按缓存过的内容。这正是 Phase B 文档反复强调的 RawValue 字节拷贝策略：只有被改写的块才是新字节，前后缀的 SHA-256 与原始请求保持恒等，并有 Phase A 的 SHA-256 测试在 CI 中钉死这一不变量。

二、整体形态：7 个 PR 的依赖关系

Phase B 规划为 7 个 PR，周期约 2 周：

PR-A1 (Phase A)
   └──► PR-B1 (大删除) ──► PR-B2 (调度骨架) ──► PR-B3 (类型感知压缩器)
                                                      │        │
                                                      ▼        ▼
                                                  PR-B4     PR-B7 (CCR 加固)
                                                      │
                                                      ▼
                                                  PR-B5 (TOIN 观察模式)
PR-A2 + PR-B4 ──► PR-B6 (Memory live-zone 尾部注入)

即 B1 独立；B2..B5 依赖 B1；B6、B7 叠加在 B2 之上。每个 PR 都单独给出风险评级、LOC 预算、验收标准、回滚方式（均为 git revert），这是该文档工程化程度很高的地方。

三、PR-B1：大删除——退役 ICM 及其依赖

风险 MEDIUM，LOC：-10,000 / +50。 这是"错误的心智模型"的整体制除。由于 Phase A 的 PR-A1 已把代理在 /v1/messages 上变为透传，这些代码在运行时已经不可达；B1 删除源码是为了让后来的贡献者无法重新接线。

删除清单（Python 侧）：

文件	规模
headroom/transforms/intelligent_context.py	1077 LOC
headroom/transforms/rolling_window.py	395 LOC
headroom/transforms/progressive_summarizer.py	508 LOC
headroom/transforms/scoring.py	459 LOC
headroom/transforms/tool_crusher.py	338 LOC

删除清单（Rust 侧）：crates/headroom-core/src/context/ 下的 manager.rs、config.rs、workspace.rs、candidate.rs、ccr_drop.rs、strategy/（含 drop_by_score.rs），以及整个 scoring/（约 1500 LOC）、relevance/（约 1600 LOC）目录、.fastembed_cache/ 中的 bge-small-en-v1.5 ONNX 产物（约 50 MB）。

一个精妙的处理是保留正确逻辑：crates/headroom-core/src/context/safety.rs 被移动到 crates/headroom-core/src/transforms/safety.rs——其中的"工具对原子性"（tool-pair atomicity）逻辑被文档明确评价为"正确且 live-zone 代码需要它"，逐字保留，只更新 use 路径。

验收标准非常硬核：cargo build --workspace、cargo test --workspace、make ci-precheck、pytest -x 全绿，且

git grep -i "IntelligentContextManager\|MessageScorer\|RollingWindow\|ProgressiveSummarizer\|ToolCrusher\|DropByScoreStrategy"

在 crates/、headroom/、tests/ 中除删除说明性注释外无命中。回滚安全性也论证清楚：git revert 使约 10K LOC 回滚，但"缓存杀手 bug 不会回来"，因为 PR-A1 已移除调用点，被删代码本就不可达。

文档还留了一个审慎的例外：anchor_selector.py 疑似仅被 ICM 消费，需用 git grep AnchorSelector 确认——Rust 侧的 anchor_selector.rs 被 SmartCrusher 消费而保留，Python 侧若仅 ICM 调用则删除。这个"删除前先验证消费方"的动作值得借鉴。

四、PR-B2：Rust live-zone 块调度器骨架

风险 MEDIUM-HIGH（新架构的核心件），LOC：+800。 B2 的边界划得很清楚：只搭调度骨架，不接入真实压缩器（B3）、不做 token 校验（B4）、不注入 CCR（B7）。

规划中的公共 API：

pub fn compress_live_zone(
    body_raw: &serde_json::value::RawValue,
    frozen_message_count: usize,
    auth_mode: AuthMode,
) -> Result<LiveZoneOutcome>;

pub enum LiveZoneOutcome {
    NoChange,
    Modified { new_body: Box<serde_json::value::RawValue>, manifest: CompressionManifest },
}

实现骨架五步：最小解析（只取 messages 字段，其余保留 RawValue）→ 对索引 ≥ frozen_message_count 的消息识别"最新 user 消息"→ 逐块分发（tool_result/text 进压缩器，image 等 no-op）→ 重组 messages 数组（未修改的消息做 RawValue 字节拷贝）→ 仅在确实有块被改写时返回 Modified，否则 NoChange 且调用方转发原始字节。

落到当前仓库，该骨架已演进为 compress_anthropic_live_zone（签名多了一个 model 参数用于按模型路由 tokenizer 后端），并新增 CCR 版本入口：

pub fn compress_anthropic_live_zone(
    body_raw: &[u8],
    frozen_message_count: usize,
    auth_mode: AuthMode,
    model: &str,
) -> Result<LiveZoneOutcome, LiveZoneError>

pub fn compress_anthropic_live_zone_with_ccr(
    body_raw: &[u8],
    frozen_message_count: usize,
    _auth_mode: AuthMode,
    model: &str,
    ccr_store: Option<&dyn CcrStore>,
) -> Result<LiveZoneOutcome, LiveZoneError>

见 live_zone.rs。与规划相比有两个值得注意的实现事实：

1. LiveZoneOutcome 的两个变体都携带 manifest: CompressionManifest（含 messages_total、messages_below_frozen_floor、latest_user_message_index、block_outcomes），NoChange 也返回诊断信息，便于可观测性；
2. 热区块类型被显式列举而非字符串前缀匹配，源码注释说明这是为了让"缓存安全面可 grep"：

const HOT_ZONE_BLOCK_TYPES: &[&str] = &["tool_use", "thinking", "redacted_thinking", "compaction"];

文档还前瞻性地说明了为什么"一个调度器不够"：OpenAI Chat Completions 的 tool 结果在独立 role: "tool" 消息里、OpenAI Responses 用 input 而非 messages、Gemini 用 contents/parts/function_response——各需专属 walker，但共享 LiveZoneOutcome、BlockAction、CompressionManifest 这些 provider-agnostic 类型。这一点在当前代码中得到印证：live_zone_anthropic.rs、live_zone_openai.rs、live_zone_responses.rs 三套入口并存。

B2 的验收标准中"Phase A 的 SHA-256 测试全部仍通过"是关键：live-zone 加上 no-op 压缩器时，请求体必须逐字节恒等。

五、PR-B3：类型感知压缩器接线

风险 MEDIUM（既有压缩器久经考验），LOC：+600。 把 SmartCrusher、LogCompressor、SearchCompressor、DiffCompressor、CodeCompressor 接入调度器，由按块的内容类型检测驱动分发。规划的调度逻辑：

fn compress_block(block: &mut Block, content_type: ContentType) -> Result<Option<CompressionResult>> {
    match content_type {
        ContentType::JsonArrayOfDicts => smart_crusher::crush(block),
        ContentType::Logs => log_compressor::compress(block),
        ContentType::SearchResults => search_compressor::compress(block),
        ContentType::Diff => diff_compressor::compress(block),
        ContentType::SourceCode => code_compressor::compress(block),
        ContentType::PlainText => Ok(None), // PR-B4 加 Kompress；暂时不动
        ContentType::Image | ContentType::Unknown => Ok(None),
    }
}

当前仓库的内容类型定义在 content_detector.rs 中，与规划高度一致但命名略有差异（字符串标签与 Python 侧 1:1 对齐）：

pub enum ContentType {
    JsonArray,      // → SmartCrusher
    SourceCode,    // → CodeAwareCompressor（Rust 移植后续）
    SearchResults, // grep/ripgrep 输出（file:line:content）
    BuildOutput,   // 编译/测试/lint 日志 → LogCompressor
    GitDiff,       // unified diff → DiffCompressor
    Html,          // 网页（需提取而非压缩）
    PlainText,     // 兜底
}

检测是纯正则——无 ML、无模型加载、无 I/O，且"正则模式、分发顺序、置信度公式、行数上限与 Python 源码逐字节相等"，由 tests/parity/fixtures/content_detector/ 的录制 fixture 跨语言桥锁死。这与 PR-B1 删掉的 relevance 子系统（依赖 fastembed ONNX 嵌入）形成鲜明对比：新的检测路径零模型依赖。

实现细节上，live_zone.rs 用 OnceLock 持有每个压缩器的进程级单例——SmartCrusher 持有评分基础设施，每请求新建既浪费又违背 builder 设计意图。B3 的验收还包括一条端到端指标："一个携带 50KB JSON tool_result 的 /v1/messages 请求过代理后，压缩块内 >2× 尺寸缩减，块外 SHA-256 恒等"。

六、PR-B4：token 校验门与按类型字节阈值

风险 LOW，LOC：+250，目标：消除 P3-33 / P3-34。 这一 PR 解决"压缩反而膨胀 token"的经典陷阱——两个门叠加：

门 1：按类型字节阈值（低于阈值不尝试压缩）。规划给出的阈值表：

内容类型	阈值
SourceCode	2 KB (2048 B)
JsonArrayOfDicts	1 KB (1024 B)
Logs	500 B (512 B)
PlainText	5 KB (5120 B)
Diff	1 KB
SearchResults	1 KB

门 2：token 校验回退。每次按块压缩后对 original 和 compressed 各跑一次 tokenizer：

let original_tokens = tokenizer.count(&original_bytes)?;
let compressed_tokens = tokenizer.count(&compressed_bytes)?;
if compressed_tokens >= original_tokens {
    metrics::compression_rejected_by_token_check(compressor_name);
    return Ok(None); // 回退到原始内容
}

即"压缩后 token 数不小于原文 → 放弃压缩并打点"。从当前源码看，阈值常量确实以 THRESHOLD_* 命名存在于 live_zone.rs，且通过 threshold_for(content_type) 统一查表——规划稿中的分档阈值（代码 2KB、纯文本 5KB 等）在最终实现里收敛为各类型 512 B 的统一基线，属于实现阶段的参数校准，具体取值以仓库当前代码为准。

B4 的验收标准包含一条病态输入测试：已最小化的 JSON、致密 base64 应回退到原文而不是膨胀 token；Prometheus 侧要求发出 compression_rejected_by_token_check_total{strategy=...} 计数器。测试矩阵覆盖 below_threshold_no_compression_attempted、compressed_more_tokens_falls_back 等场景，并配 proptest 性质测试"压缩后 token 数单调不增"。

七、PR-B5：TOIN 观察模式重构

风险 MEDIUM，LOC：-300 / +400，目标：消除 P2-27 / P5-56。 规划的原则是"保留 TOIN 这个原语，去掉危险的请求时变更"：学习价值完整保留，请求时的 hint 注入被剥离。

改造要点（对照当前 toin.py 可验证）：

• 聚合键升级为三元组 (auth_mode, model_family, structure_hash)。当前源码中模式库即以此为键（_make_pattern_key 构造，auth_mode ∈ {unknown, payg, oauth, subscription}），Pattern 数据结构携带 auth_mode、model_family 字段；
• 剥离请求时 hint API：移除 get_recommendation() 对压缩决策的直接影响，压缩路径改为确定性；
• 推荐改为部署间发布：新 CLI headroom/cli/toin_publish.py 聚合磁盘上的 TOIN 存储、生成 recommendations.toml，由 Rust 侧 recommendations.rs 在启动时加载，recommendations::get(auth_mode, model, structure_hash) -> Option<Recommendation> 只用于"先尝试哪个压缩器变体"的确定性偏置，绝不逐请求变更；
• 优雅降级：删掉 recommendations.toml 后，压缩行为如同 TOIN 从未观察过任何东西。

验收包含"确定性性质测试"（同一输入两次压缩结果相等）与"record_compression 调用点仍可用（记录保留）"。这一 PR 同时解锁 Phase F 的 PR-F3（auth-mode 聚合键依赖 TOIN 重构）。

八、PR-B6：Memory 子系统改为 live-zone 尾部注入

风险 MEDIUM-HIGH，目标：消除 P2-24。 核心变更：记忆检索从请求生命周期中的"自动前置到 system"位置，移入 live zone。两种模式：

1. Auto-tail 模式（默认）：检索在请求入口执行，结果追加到最新 user 消息尾部（live zone）——同样的内容永远出现在同样的位置，同 query 结果确定性字节恒等；
2. Tool 模式（长期推荐）：模型显式调用 memory_search 工具，检索发生在工具执行路径而非 prompt 构造路径——记忆变为 opt-in 且对模型可见。

规划明确删除 _inject_to_system_or_instructions、替换为 _append_to_latest_user_tail，并新增 MemoryMode 枚举（AutoTail | Tool，默认 AutoTail）。这一改造在当前仓库中已完成：memory_handler.py 中的 MemoryMode 枚举 docstring 直接引用了本规划文档作为依据，且明确声明"缓存热区（system prompt / instructions / frozen prefix）永不被修改——PR-A2 的不变量 I2"，_append_to_latest_user_tail 实现在第 946 行附近。验收标准要求向量搜索结果确定性（验证或设种子），避免注入字节在多次运行间漂移。

九、PR-B7：CCR 加固——持久化后端 + 工具常驻注册

风险 MEDIUM，LOC：-150 / +600，目标：消除 P2-25 / P2-26。 CCR（Compressed Content Retrieval，可检索压缩内容）是这套架构的"安全网"：压缩是有损的，但原始字节必须可找回。B7 包含两个变更：

1. 持久化 CCR 后端。 CcrStore trait 获得 SqliteCcrStore（默认）与 RedisCcrStore（多 worker 可选），内存版留作测试。SQLite schema 在规划中为 ccr_entries(hash TEXT PRIMARY KEY, original BLOB, created_at INTEGER, ttl_seconds INTEGER)，读取时自动过期清理。当前实现位于 ccr/backends/sqlite.rs、ccr/backends/redis.rs、ccr/backends/in_memory.rs——CREATE TABLE IF NOT EXISTS ccr_entries 与规划一致，且实现还追加了 last_accessed 列的在线迁移，说明实现比规划更进一步。

2. ccr_retrieve 工具常驻。 一旦某会话执行过任何 CCR 压缩，该工具在此后每个请求的 body["tools"] 中注册，且永不关闭（规划把 if has_compressed_content: 的翻转逻辑改为 if session.has_done_ccr:），避免工具列表在请求间抖动破坏工具定义的前缀缓存。会话 ID 直接复用既有 session_tracker_store 的 session_id，无需新增持久化。

标记机制在 live_zone.rs 的文档中有精确描述：当 ccr_store 为 Some(_) 且压缩器产出严格更小的块时，调度器 (1) 计算 hash = compute_key(original_bytes)（BLAKE3 → 24 位十六进制），(2) 把原始块内容存入后端，(3) 以换行分隔追加 <<ccr:HASH>> 标记到压缩块内容末尾，模型之后可调用 headroom_retrieve(hash="HASH") 恢复原始字节。规划特别强调：标记格式不变——此 PR 之前已存在于任何缓存前缀中的旧标记依然可解析。验收要求"模拟代理重启（kill + 以 SqliteCcrStore 重启）后仍能解析重启前的 CCR 标记"，且工具定义字节稳定（快照测试钉死）。

十、Phase B 验收总览与代码印证

七个 PR 全部落地后，文档声明的终态：

• ICM + RollingWindow + ProgressiveSummarizer + scoring + relevance + ToolCrusher 删除（约 10K LOC 退役），MessageScorer 的 Rust 移植（PR #338/#343）随之退役；
• live-zone 块调度器运行中；类型感知压缩器接线（SmartCrusher、LogCompressor、SearchCompressor、DiffCompressor、CodeCompressor）；
• token 校验门 + 按类型字节阈值 + 回退；TOIN 观察模式 + 每租户聚合键；Memory 路由到 live-zone 尾部（不碰 system）；CCR 持久化后端 + 工具常驻注册。

Phase B 共关闭缺陷清单中的 P0-4、P1-13、P2-18~P2-27、P3-33、P3-34、P5-56、P6-70。文档结尾的判断是：Phase B 之后，Headroom 的压缩价值"重新上线"——并且这次是正确的。

从当前仓库源码结构看，该规划已基本兑现：调度器与三套 provider 入口（Anthropic/OpenAI Chat/Responses）已就位，字节区间手术与 SHA-256 不变量由 crates/headroom-core/tests/live_zone_dispatch.rs、live_zone_thresholds.rs、live_zone_token_validation.rs、live_zone_ccr.rs 及代理侧集成测试钉死，TOIN 三元组聚合键与 Memory MemoryMode 双模式均能在源码中找到对应实现。对希望深入验证的读者，可直接从 REALIGNMENT/00-overview.md 与 REALIGNMENT/01-bug-list.md 了解缺陷编号（P0-4 等）的完整背景，以及 RUST_DEV.md 中多 worker 部署下 CCR 的最新说明。