Headroom 再对齐工程实录：从“丢消息压缩“到“只压活跃区“的缓存安全重构（REALIGNMENT 全解）

Headroom 再对齐工程实录从丢消息压缩到只压活跃区的缓存安全重构REALIGNMENT 全解【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom本文以 Headroom 仓库中的REALIGNMENT/文档集为核心入口为 INDEX.md完整解读这次由 10 个并行深度审计子代理驱动的重构工程为什么原有的压缩 从对话历史中选择丢弃心智模型是错的、9 个阶段 40 个 PR 如何把整个代理栈迁到 Rust 并以字节忠实 只压活跃区live zone重建压缩管线以及 10 条贯穿所有 PR 的缓存安全不变量。读完后你能掌握一套可复用的方法论如何在 LLM 代理中做到压缩不减缓存命中率并用 SHA-256 字节等价、token 单调不增等属性测试把这套约束固化进 CI。一、起点一个错误的心智模型Headroom 的定位是在工具输出、日志、文件和 RAG 块到达 LLM 之前压缩它们以库、代理、MCP 服务器三种形态提供。再对齐Realignment工程源于 2026-05-01 对一份 10 代理深度审计的成文目标是引自 INDEX.mdMove the entire codebase to Rust, preserve prefix cache, retain compression value, integrate RTK end-to-end, and gate compression policy by auth mode (PAYG / OAuth / subscription).问题诊断集中在 00-overview.md。旧架构的旗舰组件IntelligentContextManagerICM会把整个messages数组分词、给每条消息打重要性分、然后删除旧消息直到预算满足——并且已被接入 Rust 代理的/v1/messages路径frozen_message_count: 0是硬编码的。这意味着每一次压缩都从索引 0 开始删消息把 Anthropic 前缀缓存打得粉碎。审计的量化发现00-overview.md5 个顶级缓存杀手缺陷全部源于同一个错误模型约 10K LOC 的架构性过度建设ICM scoring relevance rolling-window progressive-summarizer tool-crusher cache-aligner 重写路径 crates/headroom-core/src/{context,scoring,relevance}/大部分线格式缺口流式 SSE 解析器缺thinking_delta、signature_delta、citations_delta存在 UTF-8 跨包拆分损坏、回退路径按单\n切分 SSE 的 bugBedrock/Vertex 对等是假的——有损的 LiteLLM Anthropic→OpenAI 转换会丢掉thinking、redacted_thinking、document、search_result、image、server_tool_use、mcp_tool_use块没有任何工具定义归一化没有认证模式感知——PAYG、OAuth、订阅 CLI 全部拿到同一策略同样会泄露指纹的重序列化X-Headroom-*请求头泄露到上游外加anthropic-beta被篡改、OpenAI-Beta自动注入——属于指纹级的订阅吊销风险CCR 标记在 Rust 路径上计算了却从未注入出向请求体ccr_retrieve工具逐请求开/关每次状态变化都 bust 一次 tools 数组。正确的模型则是完全相反的一句话passthrough is sacred只压缩 live zone——类型感知、哈希键控、位置保持、带旁路元数据。缓存热区system prompt、tools、旧轮次、reasoning/thinking/redacted/compaction 项永远不碰。二、完整缺陷清单P0 到 P6 的 72 项01-bug-list.md 是这份文档集中信息密度最高的文件按 P0cache-killer 铁证→ P6测试基建分级每条带 file:line 证据、指南章节引用、修复方式和 ROI 估计。汇总如下优先级数量归属阶段P0cache-killer7Phase AP1线格式/流式损坏10Phase A Phase CP2架构过度建设10Phase BP3缺 Phase 3 缓存稳定化基建9Phase EP4OpenAI 长尾 Bedrock/Vertex12Phase C Phase DP5认证模式 可观测性 指纹14Phase F Phase GP6测试基建与对等10Phase I并行合计72—几个 P0 级铁证每条在源码中都有对应证据摘选最有代表性的四条P0-2所有 Python 转发器用httpx ... jsonbody重序列化。httpx 默认编码器是json.dumps(body, separators(, , : ), ensure_asciiTrue)——入站字节是,/:加原始 UTF-8出站却变成,/:加\uXXXX转义上游收到的字节永远不等于客户端发的字节。P0-3Rust 代理忽略客户的cache_control标记frozen_message_count: 0硬编码配注释TODO: detect provider prefix-cached messages...叠加 ICM 后每次压缩都从索引 0 删。P0-5数字精度经serde_json::Value往返丢失——Value::Number是i64|u64|f641.0会变成1大于 2^53 的整数丢精度。P0-6memory 工具注入逐请求开关tools列表大小在请求之间翻转同时anthropic-beta被加塞context-management-2025-06-27——典型的会话中途缓存破坏。P1 级则覆盖了流式 SSE 的字节级问题errorsignore解码会静默丢弃跨 TCP 读拆分的 emoji/CJK 字节解析器只 switch 了text_delta和input_json_deltaLiteLLM 桥在上游缺tc.id时会伪造toolu_uuid导致下一轮tool_result引用假 ID、工具配对断裂。三、九个阶段、40 个 PR工程化路线图再对齐被拆成 9 个阶段、40 个 PR串行约 13 周、2-3 人并行约 8 周INDEX.md Phase totals 表阶段PR 数LOC 变化估计日历串行内容A — Lockdown8-200 / 4001 周止血/v1/messages改纯透传、停改 system prompt、Python 转发器改contentraw_bytes、Rust 端尊重cache_control、剥x-headroom-*、anthropic-beta会话粘滞、SHA-256 字节等价往返测试B — Live-zone engine7-10,000 / 1,5002 周删除 ICM 全家桶~10K LOC建 Rust live-zone 块分发器CCR 加固持久后端 常驻ccr_retrieve工具注册C — Rust proxy paths5-2,000 / 5,0003 周字节级 SSE 解析状态机/v1/chat/completions、/v1/responsesHTTP 与流式按 item 类型的透传保持V4A patch、local_shell_call.action.commandargv、Codexphase字段、MCP 项、compactionD — Bedrock/Vertex native4-800 / 2,5002 周删除 LiteLLM 有损转换器建原生/model/.../invokeAWS SigV4与/v1beta1/projects/.../streamRawPredictGCP ADC路由E — Cache stabilization6-100 / 9001 周工具数组确定性排序、JSON Schema 键递归排序、自动放置最多 4 个cache_control断点Anthropic、自动注入prompt_cache_keyOpenAI、易变内容检测只告警不改写、cache-bust 漂移遥测F — Auth-mode policy4-50 / 6001 周classify_auth_mode(headers)→payg | oauth | subscription每模式压缩策略闸门TOIN 聚合键扩展为(auth_mode, model_family, structure_hash)条件化X-Forwarded-*G — RTK observability3-50 / 4001 周扩展 wrap CLIcline、continue、goose、openhands接通死字段tokens_saved_rtk每次调用的 RTK Prometheus 指标H — Python retirement3-15,000 / 2002 周删除headroom/proxy/server.py、全部 handlers、responses_converter.py、memory_handler.py、batch.py、semantic_cache.py及headroom/transforms/*Python 部分保留 CLI 包装器、RTK 安装器、evals、learn、memory 写器、tokenizer、TOINI — Test infra并行2,000持续SHA-256 往返测试SSE 边角用例 fixtureUTF-8 拆分、ping、全 delta 类型、[DONE]、流中断错属性测试SSE 解析不 panic、压缩 token 单调不增缓存命中率持续指标make test-parity升级为每 PR 闸门合计40~-28,000 / 13,500串行 ~13 周 / 并行 ~8 周每个阶段的 PR 在 03-phase-A-lockdown.md 到 11-phase-I-test-infra.md 中按 PR 粒度展开每个 PR 含分支名、worktree 路径、风险级别、LOC、精确到文件的改动清单、新增测试、验收标准、被阻塞/阻塞关系、回滚方式。以 03-phase-A-lockdown.md 的 8 个 PR 为例PR-A1realign-A1-icm-passthrough-180/30低风险停掉 Rust 代理对/v1/messages的 ICM 调用该端点变纯字节忠实透传删crates/headroom-proxy/src/compression/icm.rscompress_anthropic_request保留签名为 no-op 桩作为 Phase B 的唯一重写目标新增 SHA-256 往返测试compression_on_message_passes_body_unchanged_sha256。PR-A2删除_inject_system_context路径memory 上下文只走_append_context_to_latest_non_frozen_user_turn追加到最新用户消息尾部删cache_aligner重写路径、保留检测器 客户告警。PR-A3高风险最高单项收益所有 Python 转发器从httpx ... jsonbody切到httpx ... contentraw_bytes未改动则原样转发await request.body()字节改动过则用separators(,, :)ensure_asciiFalse重新序列化一次。PR-A4Rust 端遍历system/tools/messages中的客户cache_control标记计算frozen_message_countCargo.toml给serde_json加arbitrary_precisionraw_valuefeature未修改的messages[*]以精确字节副本转发。PR-A5_strip_internal_headers剥除x-headroom-*大小写不敏感前缀后再上游转发。PR-A6/A7merge_anthropic_beta确定性合并 betas_seen会话粘滞memory 工具注入会话粘滞注入过就永远注入同字节定义。PR-A8Python 线格式热修集合SSE 字节缓冲、全 delta 类型、Codexphase保留、上游request-id捕获、413 状态码修正、录制生产 fixture 的 SHA-256 往返测试。12-decisions-needed.md 记录了 15 个需要人工拍板的开放问题及推荐结论例如ICM 删除范围取 Tier 12约 10K LOCMessageScorer Rust 移植 PR #338/#343 认定为沉没成本直接删Phase H 期间用HEADROOM_PROXY_BACKEND{python|rust}环境变量做灰度切换、Rust 确认 ≥99.9% 字节等价后默认 rustPython 保留 30 天作为显式回滚目标容器镜像策略从 ~500MBPython LiteLLM ONNX降到 ~50MB 的单一 Rust 二进制FROM scratch/ distroless。四、十条贯穿不变量任何 PR 都不得违反这是整个工程的宪法性条款INDEX.md Cross-cutting invariants02-architecture.md §2.2 将其细化为 I1-I10 并给出实现方式与测试闸门代理不打算修改的字节必须**字节等价SHA-256**到达上游缓存热区——system、tools、旧轮次、reasoning/thinking/redacted/compaction 项——永不被修改压缩是append-only只有 live zone最新用户消息、最新 tool/function/shell/patch 输出可被重写压缩是确定性的同输入字节 → 同输出字节工具定义只归一化排序永不压缩signature、encrypted_content、redacted_thinking.data、compaction.encrypted_content只透传TOIN 从不改变请求时决策只观察、在两次部署之间发布建议会话只要做过 CCRCCR 标记和ccr_retrieve工具就每次请求都在——从不切换Authorization头字节忠实转发永不未脱敏地记录或持久化认证模式PAYG / OAuth / subscription门控压缩策略订阅模式运行在隐身态无X-Headroom-*上游、无 beta 漂移、不改 UA、不剥accept-encoding。目标架构02-architecture.md §2.1给出的请求生命周期是classify_auth_mode→ 剥x-headroom-*→RawValue字节缓冲 → 尊重cache_control得frozen_message_count→live_zone_compress识别 live-zone 块、逐块内容类型检测、分发给类型感知压缩器、token 校验失败即回退、CCR 哈希键控存库打标记、块内原位替换→tool_def_normalize→cache_control_auto_placeAnthropic 最多 4 个 ephemeral 断点→prompt_cache_key_injectOpenAI仅客户未设时→ 以原始字节转发 → 字节级 SSE 状态机处理响应 → usage 遥测。§2.6 还明确列出了这套架构不做的事永不丢历史消息、永不改 system/tools/旧轮次、TOIN 不参与请求时决策、代理不 shell out 到 RTK、不做 Anthropic↔OpenAI 形状互译每个 provider 自己的原生 handler、不改User-Agent、不压图片和 base64 音频、不改tool_use.input键序或function_call.arguments字符串内容等。这份负面清单和正面清单同等重要它把未来贡献者的自由度约束在了缓存安全边界内。五、源码验证计划已落地为当前代码文档是计划仓库是事实。用当前代码库交叉核对再对齐的核心产物已存在于 Rust 侧1.cache_control标记 walker 已实现。crates/headroom-core/src/cache_control.rs 中的compute_frozen_count(parsed: Value) - usize正是 PR-A4 规划的实现遍历messages[i].content[*].cache_control把冻结下限抬到i 1下限独占messages[i]本身属于缓存前缀所以冻结system/tools中的标记不抬高消息索引下限它们无条件属于热区见架构文档不变量 I2模块头注释还说明了按构建约束用解析器不用正则、以及1h标记必须前置于5m的 TTL 顺序规则违反只告警不拒绝。是否启用由Config::cache_control_auto_frozenCLI--cache-control-auto-frozen/ 环境变量HEADROOM_PROXY_CACHE_CONTROL_AUTO_FROZEN门控。2. live-zone 分发器已就位。crates/headroom-core/src/transforms/live_zone.rs 的模块文档直接对应 Phase B 的构建史PR-B2 交付识别 live-zone 块的分发器骨架PR-B3 接入按内容类型的压缩器JsonArray→ SmartCrusherBuildOutput→ LogCompressorSearchResults→ SearchCompressorGitDiff→ DiffCompressorPR-B4 加上 token 校验闸门compressed.tokens original.tokens即回退与按内容类型的字节阈值code2KB、JSON1KB、logs500B、plain text5KB。它明确声明 live zone 的边界下限是frozen_message_count上限是最新用户消息——最新 assistant 消息同样属于热区因为它是对话续接点永不触碰。3. 认证模式分类器已实现。crates/headroom-core/src/auth_mode.rs 是 Phase F PR-F1 的产物一个纯函数把入站HeaderMap映射为Payg | OAuth | Subscription三类——PAYG 按 token 付费、激进压缩省钱的逻辑全部打开OAuth 的 per-token 成本对调用方不透明缓存安全优先因为 OAuth scope 钉在(account, model, session)上、beta 头漂移会使其失效Subscription 类调用方是 UX 绑定的 CLI/IDEClaude Code、Cursor、Copilot 等必须看起来像上游 agent保留User-Agent、永不注入X-Headroom-*、永不剥accept-encoding。文档强调该分类器是纯函数、无 I/O、单次调用 10μs、对畸形头永不 panic非 UTF-8 值回落到安全的Payg默认并打tracing::warn!。4.serde_jsonfeature 已按 P0-5 修复。工作区 Cargo.toml 第 50 行serde_json { version 1, features [preserve_order, arbitrary_precision, raw_value] }——正是 PR-A4 要求的三个 feature 集注释说明arbitrary_precision用于保留源文件中的字面数字 token。5. 退役清单与仓库现状吻合。计划中 Phase B/H 要删的组件在当前仓库中已不在位headroom/transforms/目录里没有intelligent_context.py、rolling_window.py、progressive_summarizer.py、tool_crusher.py、scoring.pycrates/headroom-core/src/下没有context/、scoring/目录。而被Preserved primitives 保留的组件都在crates/headroom-core/src/transforms/ 下可看到smart_crusher/、code_compressor.rs、log_compressor.rs、search_compressor.rs、diff_compressor.rs、safety.rs、tag_protector.rs、kompress.rs以及tokenizer/、signals/、ccr/、compression_policy.rs、rollout.rs。从源码结构看02-architecture.md §2.3 规划的模块布局transforms/live_zone.rs为 NEW、safety.rs从context/移入transforms/、pipeline/收缩为 live-zone 编排器与当前目录结构基本一致说明文档与代码是同一时间轴上的计划—实现两端。六、保留什么、退役什么两条清单INDEX.md 的两条清单是理解 Headroom 当前技术债与资产分布的最快入口。保留原语按用户决策TOINTool Output Intelligence Network——重构为严格 observation-only按租户聚合键。目标形态见 02-architecture.md §2.5Telemetrytrait 只有record_compression(...)No request-time hint API. Period.建议经cargo run -p headroom-toin-publish -- --auth-mode payg --model claude-3-7-sonnet在部署间隙发布为recommendations.toml压缩器只在启动时读取CCRCompress-Cache-Retrieve——CcrStoretrait SqliteCcrStore主后端/RedisCcrStore可选多 workerccr_retrieve对做过 CCR 的会话每次请求都注册标记格式ccr:HASH追加到压缩块内容末尾内容寻址、确定性、可安全重放Kompress-base——纯文本压缩器只在 live-zone 用户消息文本 5KB 时作为最后手段使用Rust 移植走ortcrateONNXContentRouter——约 2150 LOC被审计认定为架构上正确的部分文档特意更正了早期项目记忆中53K 行的错误——差了 25 倍类型感知压缩器——SmartCrusherRust 25 文件、Code、Log、Search、Diffsignals/Rust trait 模块、tokenizer/、safety.rs工具对原子性逻辑Phase B 后移至transforms/safety.rs。退役~25K LOCICMPythonintelligent_context.py Rustcontext/manager.rs、RollingWindow、ProgressiveSummarizer、scoring.py、tool_crusher.py、crates/headroom-core/src/{scoring,relevance}/与context/大部分、crates/headroom-proxy/src/compression/icm.rs、cache_aligner.py重写路径保留检测器 告警、Phase H 达标后删除的 Python 代理全家server.py、handlers/anthropic.py、handlers/openai.py、handlers/streaming.py、handlers/gemini.py、responses_converter.py、memory_handler.py、memory_tool_adapter.py、semantic_cache.py、batch.py、LiteLLM Bedrock/Vertex 转换器被 Phase D 原生信封取代、MessageScorer Rust 移植PR #338/#343判定为浪费的工作Phase B 删除。01-bug-list.md P2 段给出了每条的 file:line 证据例如 ToolCrusher 在headroom/transforms/tool_crusher.py:106无frozen_message_count检查地遍历所有工具消息TOIN 在headroom/telemetry/toin.py:853-927于调用中变更模式状态并返回偏向同一输入字节决策的 hintCCR 标记在crates/headroom-core/src/context/manager.rs:172-185只被记录而从未写回请求体。七、工程协作约定分支、worktree 与 CI 闸门INDEX.md Conventions 一节定义了所有再对齐 PR 的协作契约值得任何做大型多 PR 重构的团队参考分支命名realign-phase-letterpr-num-slug例如realign-A1-icm-passthroughworktree 隔离每个 PR 一个独立git worktree add检出具~/claude-projects/headroom-worktrees/...避免并行 PR 相互污染提交前缀Rust 迁移阶段的提交统一用fix:而非feat:避免 semantic-release 版本号膨胀不加Co-Authored-By: Claudetrailer推送前闸门make ci-precheck不许裸推。当前仓库的 Makefile 中ci-precheck聚合了ci-precheck-rustcargo fmt --check clippy test、ci-precheck-python、ci-precheck-commitlint三道闸且test-parity作为独立 target 存在——对应 Phase I 计划中把对等测试提升为每 PR 闸门Diff失败构建、Skipped允许的路线。八、如何继续深入这份文档集按 INDEX.md 指定的阅读顺序REALIGNMENT/00-overview.md——执行摘要、错误心智模型、五大错误假设TOIN 可以影响每请求压缩决策、CCR 可以按需改缓存热区、总结历史轮次是一种策略、ToolCrusher 无冻结检查地操作所有历史工具消息等REALIGNMENT/01-bug-list.md——72 条带 file:line 的完整缺陷清单REALIGNMENT/02-architecture.md——目标架构请求生命周期、I1-I10 不变量及各自实现方式与测试闸门如 I5 的属性测试tokens(output) ≤ tokens(input)、压缩器模块布局、认证模式策略矩阵PAYG 允许激进压缩与自动cache_control放置OAuth/Subscription 禁止自动断点注入并各自收紧指纹面、保留原语的目标代码形态九个阶段文档 03 至 11每个 PR 都是可执行规格分支/文件/测试/验收/回滚俱全REALIGNMENT/12-decisions-needed.md——15 个待决策项及签核模板。源码侧对应的验证入口crates/headroom-core/src/cache_control.rs冻结下限计算、crates/headroom-core/src/transforms/live_zone.rslive-zone 分发器、crates/headroom-core/src/auth_mode.rs认证模式分类、crates/headroom-core/src/transforms/类型感知压缩器家族、Cargo.tomlserde_json 精确性 feature测试侧可关注tests/test_proxy_byte_faithful_forwarding.py、tests/test_cache_aligner_detector_only.py、tests/test_anthropic_beta_session_sticky.py、tests/test_memory_tool_session_sticky.py等与 Phase A 验收项一一对应的回归用例。这份文档集的价值不止于一次重构的档案它示范了如何用不变量 属性测试 字节等价验收把 LLM 代理的缓存安全从口号变成可执行契约——先锁死透传Phase A再在冻结边界内重建压缩Phase B最后用认证模式策略矩阵Phase F把省 token与不被上游识别为异常客户端解耦。对任何在代理层做 LLM 上下文优化的工程这套passthrough is sacred的方法论可以直接迁移复用。【免费下载链接】headroomCompress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.项目地址: https://gitcode.com/GitHub_Trending/head/headroom创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考