Headroom Realignment 目标架构解析Rust-only 代理的请求生命周期、十大缓存安全不变量与 Auth-Mode 策略矩阵【免费下载链接】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本文围绕 REALIGNMENT/02-architecture.md 展开完整继承该文档定义的目标架构骨架Phase H 之后的 Rust-only 代理请求生命周期11 步管线、I1–I10 十条缓存安全不变量、压缩器模块布局、Auth-Mode 策略矩阵以及 TOIN / CCR / Kompress 三个保留原语。在此基础上结合当前仓库crates/headroom-core与crates/headroom-proxy的实际源码与测试印证每个不变量的落地方式与 CI 测试门禁帮助读者既读懂设计意图又能沿源码与测试逐条验证其实现。1. 总体定位Phase H 之后的 Rust-only 代理REALIGNMENT 系列的总入口是 REALIGNMENT/INDEX.md其目标概括为把整个代码库迁移到 Rust、保留 prefix cache、维持压缩价值、端到端集成 RTK并以认证模式PAYG / OAuth / Subscription门控压缩策略。02-architecture.md 回答的是“迁移完成后的目标形态长什么样”每个子系统的职责边界、不变量、文件布局以及它明确不做的事情。配套的阶段文档03-phase-A-lockdown.md 到 11-phase-I-test-infra.md以 PR 粒度给出执行计划本文聚焦架构文档本身。2. 请求生命周期Rust 侧的 11 步管线文档 2.1 节给出的完整生命周期如下原文继承Client request │ ▼ ┌──────────────────────────────────────────────┐ │ headroom-proxy (axum) │ │ │ │ 1. classify_auth_mode(headers) │ ← Phase F │ → payg | oauth | subscription │ │ │ │ 2. strip x-headroom-* from upstream-bound │ ← Phase A (PR-A5) │ │ │ 3. byte-buffer body via RawValue │ ← Phase A (PR-A4) │ (numeric precision preserved) │ │ │ │ 4. honor cache_control markers │ ← Phase A (PR-A4) │ → frozen_message_count │ │ │ │ 5. live_zone_compress(body, frozen_count, │ ← Phase B │ auth_mode) │ │ ├─ identify live-zone blocks │ │ ├─ per-block content-type detection │ │ ├─ dispatch to type-aware compressor │ │ ├─ token-validate; fallback to original │ │ ├─ CCR: hash-key, store, marker │ │ └─ replace block bytes in-place │ │ │ │ 6. tool_def_normalize(body) │ ← Phase E (PR-E1, E2) │ ├─ alpha-sort tools[] │ │ └─ recursive-sort JSON Schema keys │ │ │ │ 7. cache_control_auto_place(body) │ ← Phase E (PR-E3) │ (Anthropic; up to 4 ephemeral) │ │ │ │ 8. prompt_cache_key_inject(body) │ ← Phase E (PR-E4) │ (OpenAI; only if not customer-set) │ │ │ │ 9. forward via reqwest with original bytes │ │ for unmodified envelope (RawValue diff) │ │ │ │ 10. SSE response: byte-level state machine │ ← Phase C (PR-C1) │ ├─ track blocks/items by id │ │ ├─ all delta types handled │ │ ├─ mid-stream error/ping/drop surfaced │ │ └─ pure passthrough to client │ │ │ │ 11. usage telemetry (cache_read, │ ← Phase G │ cache_creation, output_tokens, etc.) │ └──────────────────────────────────────────────┘ │ ▼ Upstream provider这 11 步在当前仓库中可以找到清晰的落点步骤 1auth-mode 分类由 auth_mode.rs 中的classify纯函数实现见下文第 5 节。步骤 4frozen_message_count由 cache_control.rs 的compute_frozen_count计算——从cache_control标记推出“前 N 条消息已进 provider 前缀缓存”的下界。步骤 5live-zone 压缩入口在 live_zone.rs其模块头注释完整描述了“live zone”的心智模型与边界规则。步骤 6–8Phase E 缓存稳定化对应 cache_stabilization/ 目录下的tool_def_normalize.rs、anthropic_cache_control.rs、openai_cache_key.rs等文件。步骤 10SSE 字节级状态机对应 sse/ 目录anthropic.rs、openai_chat.rs、openai_responses.rs、framing.rs。步骤 11usage 遥测对应 observability/ 目录cache_hit_rate.rs、compression_ratio.rs、prometheus.rs。2.1 字节区间手术为什么不用“反序列化 → 修改 → 再序列化”这是整个架构中最关键的工程决策。live_zone.rs 的文档注释给出了明确解释重写块通过serde_json::value::RawValue借用切片上的指针算术定位然后把替换内容拼接进输出out body[..block_start] || replacement || body[block_end..]被重写范围之外的字节是从输入直接拷贝的绝不重新序列化。之所以不能走“反序列化成Value→ 修改 → 序列化”的路径是因为重新序列化无法保留原始空白、键序细节与数字格式——而这些恰恰是 provider 已经针对它计算过缓存的字节。文档 I1 不变量要求的“SHA-256 字节相等”只能靠这种字节级直拷保证。该决策在工作区 Cargo.toml 中固化serde_json同时启用了preserve_order、arbitrary_precision、raw_value三个特性——arbitrary_precision保留源文件中的数字字面量 tokenraw_value暴露未解析的 JSON 字节视图。对应的 CI 测试门禁在 live_zone_dispatch.rs 的byte_fidelity_outside_compressed_block用例断言被压缩块之外的前缀/后缀字节与输入完全一致。3. 十条缓存安全不变量I1–I10文档 2.2 节声明“每个 PR 都必须遵守”这十条不变量与 INDEX.md 的 Cross-cutting invariants 一一对应。逐条继承原文档内容并附仓库证据I1 — 未修改字节的字节级忠实透传对每个请求发往上游的字节SHA-256必须与从客户端收到的字节除 transform 显式修改的字节区间外完全相等。不允许经过Value类型重新序列化不允许 JSON 美化器插入空白不允许对 UTF-8 用户内容做\uXXXXASCII 转义。实现messages[*]条目使用serde_json::value::RawValue被修改的消息走全新序列化保留的消息作为精确字节拷贝转发。测试门禁proxy_byte_faithful_anthropic_sha256—— 录制一个真实 Anthropic/v1/messages载荷关闭压缩走一遍代理在上游 mock 处断言 SHA-256 字节相等。仓库中 fixtures/anthropic_messages_request_real.json 与 integration_body.rs 即承载此类真实字节级回归。I2 — 缓存热区永不被修改以下内容 Headroom 永不触碰system字符串或块列表、tools[*]Phase E 的字母排序与 JSON Schema 键排序除外两者都是确定性的、索引小于frozen_message_count的任何消息、带encrypted_content的 reasoning 项、带signature的 thinking 块、redacted_thinking.data、compaction 项。实现live_zone_compress从尾部遍历messages识别 live-zone 块最新 user 消息、最新 tool_result、最新 function_call_output、最新 local_shell_call_output、最新 apply_patch_call_output只修改这些块内部的字节。live_zone.rs 的注释进一步明确了上下界下界是frozen_message_count下界以下必须逐字节一致上界是“最新 user 消息”——最新 assistant 消息也属于热区因为它正是下一轮响应继续的位置永远不碰。测试门禁cache_hot_zone_unchanged_under_compression—— 含 system tools 5 轮历史 新 tool_result 的 fixture断言上游处 system、tools 与前 5 轮字节相等。I3 — Append-only一旦某条消息出现在任何一次历史请求中它的字节即被冻结。压缩只作用于 live zone最新一轮。实现frozen_message_count是硬性下限任何试图触碰index frozen_message_count的压缩器会在编译期Rust trait 约束或运行期Python assertion被拒绝。测试门禁append_only_invariant_under_recompression—— 相同输入字节两次过压缩器产生字节相等输出保留消息在两次运行间字节相等。I4 — 确定性对相同的(input bytes, frozen_count, auth_mode)压缩器产生字节相等的输出。无时间戳、无随机种子、无时间相关决策。实现TOIN 是纯观察Phase B PR-B5永不改变请求期决策所有哈希使用 BLAKE3 / SHA-256 且输入顺序稳定排序顺序显式化输出用BTreeMap绝不HashMap任何压缩代码路径中不出现Instant::now()。测试门禁property test —— 对任意合法输入验证幂等性compress(input) compress(compress(input).original)与运行间确定性compress(input) compress(input)。I5 — Token 感知而非字节感知每次压缩后都要用 tokenizer 验证若compressed.tokens original.tokens则转发原文。实现Phase B PR-B4。按内容类型设字节阈值code 2KB、JSON 1KB、logs 500B、纯文本 5KB低于阈值直接不尝试压缩开销超过收益。测试门禁文档给出的 proptest 门禁proptest_compression_token_count_non_increasing在仓库中对应的实际实现是 live_zone_token_validation.rs 的live_zone_compression_token_count_non_increasing属性测试——对 strategy 生成的任意合法输入断言tokens(output) ≤ tokens(input)。I6 — 位置保持压缩从不重排 content 数组内的块从不把一个块拆成多个从不在既有块上添加内联元数据字段。实现压缩器签名为fn(block: mut Block) - Result()——原地操作。块类型、tool_use_id/call_id、is_error、所有兄弟字段全部保留。旁路元数据CCR 检索指令放在一个独立的 marker 块text 类型、兄弟节点中绝不作为原块上的额外字段。I7 — 工具定义只归一化不压缩工具按 name 字母序排序JSON Schema 键递归排序description 空白归一化除此之外每个工具input_schema.properties[*].description的字节原样保留。实现Phase E PR-E1、PR-E2。仓库中可见对应测试 integration_tool_sort.rs 与 integration_schema_sort.rs。I8 —signature、encrypted_content、redacted_thinking.data神圣不可侵犯这些字段只透传永不检查、永不解码、永不变换。实现压缩器的块类型分派对这些类型有显式的 no-op 分支。Bedrock/Vertex 原生路径Phase D保留它们——这一点与旧的 LiteLLM 转换器不同。对应仓库 bedrock/ 与 vertex/ 目录。I9 — TOIN 只观察绝不修改请求字节TOIN 的模式统计跨请求增长推荐在部署间隙发布到磁盘压缩器只在启动时读取推荐不在请求期读取。实现Phase B PR-B5。TOIN 的内存态写入是 append-only读取永不阻塞压缩。I10 — Auth 模式门控压缩策略PAYG激进完整 live-zone 压缩、CCR、工具注入、Phase 3 稳定化OAuth透传优先仅 live-zone 无损不自动加cache_control、不自动加prompt_cache_key、不加X-Forwarded-*;Subscription隐身优先OAuth 全部行为外加保留accept-encoding、永不上游注入X-Headroom-*、永不改写User-Agent。实现Phase F PR-F1、PR-F2。4. 压缩器模块布局Phase B 之后文档 2.3 节给出的目标布局如下原文继承crates/headroom-core/src/ ├── lib.rs # public surface ├── tokenizer/ # KEEP (HF tiktoken impls) │ ├── mod.rs │ ├── hf_impl.rs │ ├── tiktoken_impl.rs │ ├── estimator.rs │ └── registry.rs ├── ccr.rs # KEEP, hardened (persistent backend) ├── signals/ # KEEP — drives live-zone consumers │ ├── mod.rs │ ├── line_importance.rs │ ├── keyword_detector.rs │ └── tiered.rs ├── transforms/ # the compressors │ ├── mod.rs │ ├── safety.rs # MOVED from context/safety.rs (Phase B) │ ├── live_zone.rs # NEW — live-zone block dispatcher (Phase B) │ ├── content_detector.rs # KEEP │ ├── detection.rs # KEEP │ ├── magika_detector.rs # KEEP │ ├── unidiff_detector.rs # KEEP │ ├── adaptive_sizer.rs # KEEP │ ├── anchor_selector.rs # KEEP │ ├── tag_protector.rs # KEEP │ ├── log_compressor.rs # KEEP │ ├── search_compressor.rs # KEEP │ ├── diff_compressor.rs # KEEP │ ├── kompress_compressor.rs # NEW — Phase H Rust port via ort crate │ ├── smart_crusher/ # KEEP (25 files, correctly scoped) │ └── pipeline/ # SHRUNK — only the live-zone orchestrator │ ├── mod.rs │ ├── orchestrator.rs # rewrite to live-zone-only │ ├── traits.rs # LosslessTransform / LossyTransform │ └── offloads/ # KEEP — JSON, log, search, diff offloads └── auth_mode.rs # NEW — Phase F (classify_auth_mode helper) # DELETED in Phase B: # context/ ← except safety.rs which moved # scoring/ # relevance/crates/headroom-proxy/src/ ├── lib.rs ├── main.rs ├── config.rs ├── error.rs ├── proxy.rs # Phase A: pure passthrough on /v1/messages # Phase C: /v1/chat/completions, /v1/responses ├── headers.rs # Phase F: conditional X-Forwarded-* ├── websocket.rs # Phase C: WS Codex flow ├── sse/ # NEW — Phase C │ ├── mod.rs │ ├── parser.rs # byte-level state machine │ ├── anthropic.rs # 4-event dance delta types │ ├── openai_chat.rs # tool_call accumulation │ └── openai_responses.rs # output items reasoning summary ├── compression/ │ ├── mod.rs # routing by path × auth_mode │ ├── live_zone_anthropic.rs # NEW (Phase B) │ ├── live_zone_openai.rs # NEW (Phase C) │ ├── tool_def_normalize.rs # NEW (Phase E) │ ├── cache_control.rs # NEW (Phase E) │ └── model_limits.rs # KEEP ├── bedrock/ # NEW — Phase D │ ├── mod.rs │ ├── sigv4.rs │ ├── invoke.rs │ └── eventstream.rs ├── vertex/ # NEW — Phase D │ ├── mod.rs │ ├── adc.rs │ └── stream_raw_predict.rs └── observability/ # NEW — Phase G ├── mod.rs ├── prometheus.rs ├── cache_hit_rate.rs └── compression_ratio.rs # DELETED: # compression/icm.rs ← Phase A PR-A1 # compression/anthropic.rs ← Phase A PR-A1 (replaced with live_zone_anthropic.rs in Phase B)对照当前仓库可以确认这份布局已基本落地且与文档标注一致crates/headroom-core/src/ 下确实存在tokenizer/、signals/、ccr/、transforms/live_zone.rs、transforms/safety.rs、transforms/smart_crusher/约 25 个文件、transforms/pipeline/offloads/JSON、log、search、diff offloads以及auth_mode.rsKompress 的 Rust 端口落在 transforms/kompress.rs文档树中标记为kompress_compressor.rs同 crate 另有onnx_cpu.rs支撑 ONNX 会话。crates/headroom-proxy/src/ 下存在proxy.rs、headers.rs、websocket.rs、sse/、compression/live_zone_anthropic.rs、compression/live_zone_openai.rs、bedrock/、vertex/、observability/Phase E 的tool_def_normalize与cache_control归一化逻辑实际收敛在cache_stabilization/目录中与compression/各司其职。布局文档的价值在于它同时是删除清单context/safety.rs 除外、scoring/、relevance/、旧compression/icm.rs全部退役——这与 INDEX.md 中“Retired (~25K LOC)”一节相互印证ICM、RollingWindow、ProgressiveSummarizer、scoring.py、tool_crusher.py以及 MessageScorer 的 Rust 移植PR #338、#343被判为无用功都被删除。5. Auth-Mode 策略矩阵Phase F文档 2.4 节的完整策略矩阵如下原文继承策略维度PAYGOAuthSubscriptionLive-zone 压缩aggressivelossless-onlylossless-onlyCCR 启用是是是长会话工具定义字母排序是是是JSON Schema 键排序是是是自动放置cache_control是否会使 scope 失效否自动注入prompt_cache_key是OpenAI否否修改anthropic-beta否否否上游发送X-Headroom-*否否否上游发送X-Forwarded-*是是否改写User-Agent否否否剥离accept-encoding可可否保留有损压缩器LLMLingua可否否Memory 注入live-zone 尾部live-zone 尾部门控live-zone 尾部门控TOIN 聚合键(mode, model)(mode, model)(mode, model)Authorization日志脱敏前 12 字符前 12 字符前 12 字符从源码结构看该矩阵的执行点在 auth_mode.rs 的分类函数上。AuthMode枚举定义为三个变体auth_mode.rsPayg激进压缩可开启、OAuth透传优先不自动cache_control、不自动prompt_cache_key、不启用有损压缩器、Subscription隐身OAuth 全部行为 保留accept-encoding、绝不注入X-Headroom-*、绝不改写User-Agent。分类的判定顺序最具体信号优先值得注意Subscription UA 前缀→Subscription。模块级常量SUBSCRIPTION_UA_PREFIXESauth_mode.rs列出claude-cli/、claude-code/、codex-cli/、cursor/、github-copilot/等用 lowercasedstr::contains匹配——CLI 的 auth-mode 优先于它恰好携带的 bearer token 形态Claude Code 会话用的是sk-ant-oat*token但它是订阅客户端而非 OAuth。Authorization: Bearer sk-ant-oat*→OAuthClaude Pro/Max OAuth必须先于更宽的sk-PAYG 规则检查因为sk-ant-oat同样以sk-开头。Bearer sk-*/ API key 类→Payg。分类器是纯函数无 I/O、无 panic 路径非 UTF-8 头值落回安全默认Payg并记一条tracing::warn!让运维在日志流中发现问题客户端而不拖垮代理。该矩阵背后的业务逻辑在 auth_mode.rs 的文档注释中写得很直白PAYG 用户按 token 付费激进压缩直接省钱OAuth 用户的每次成本不透明且 OAuth scope 绑定(account, model, session)beta-header 漂移会使 scope 失效因此缓存安全压倒一切Subscription 用户的 provider 按请求数限速程序化指纹检测意味着必须“看起来就是上游 agent 本人”。6. 保留原语细节TOIN、CCR、Kompress文档 2.5 节定义了三个必须保留的底层原语用户指令保留逐条继承6.1 TOINPhase B PR-B5 之后// Strict observation-only. pub trait Telemetry { fn record_compression( self, auth_mode: AuthMode, model: ModelFamily, structure_hash: StructureHash, outcome: CompressionOutcome, ); // No request-time hint API. Period. } // Recommendations published between deploys via: // $ cargo run -p headroom-toin-publish -- --auth-mode payg --model claude-3-7-sonnet // Output: recommendations.toml committed to repo, loaded by compressor at startup.要点接口上不存在任何请求期 hint API。TOIN 的统计跨请求增长但推荐只在部署间隙经headroom-toin-publish工具离线生成recommendations.toml由压缩器启动时加载——这就是 I4确定性与 I9只观察的共同落点。仓库中 transforms/recommendations.rs 与 recommendations_loader.rs 测试承载启动期加载逻辑。6.2 CCRPhase B PR-B7 之后pub trait CcrStore: Send Sync { fn put(self, hash: ContentHash, original: Bytes, ttl: Duration) - Result(); fn get(self, hash: ContentHash) - ResultOptionBytes; fn purge_expired(self) - usize; } pub struct SqliteCcrStore { ... } // primary backend pub struct RedisCcrStore { ... } // optional, for multi-worker // ccr_retrieve tool registered on every request for sessions that ever did CCR. // Marker injection format: ccr:HASH appended to compressed block content. // Markers are deterministic (hash is content-addressed); replay-safe.CCRCompress-Cache-Retrieve的语义是“线上有损、端到端无损”变换丢掉行或替换不透明字符串时原文按进入 prompt 的哈希键存入 store运行期通过检索工具调用按哈希取回原文。当前仓库 ccr/mod.rs 中CcrStoretrait 已落地为put/get/len契约三个后端齐备InMemoryCcrStorein_memory.rs进程内分片DashMap测试默认SqliteCcrStoresqlite.rs生产默认WAL 模式、预编译语句、读时惰性 TTL 清理跨 worker 重启持久化RedisCcrStoreredis.rs多 worker 可选feature redis门控。源码中还有两个与文档“标记确定、可重放”直接对应的参数默认 TTL 为 30 分钟ccr/mod.rs且它是空闲窗口而非墙钟——每次成功get重置计时使长会话中持续被引用的条目能存活同时以 8 倍 TTL 的绝对上限防止常量访问把条目永久钉住DEFAULT_MAX_LIFETIME_MULTIPLIER 8。端到端验证见 ccr_roundtrip.rs 与 live_zone_ccr.rs。6.3 Kompress-basePhase H PR-H4 Rust 端口之后// Plain-text §8.6 compressor. Used only as a last resort, only on live-zone // user-message text exceeding 5KB. pub struct KompressCompressor { // ONNX runtime via ort crate. Model deterministic for fixed weights. session: ort::Session, threshold_bytes: usize, } impl LossyTransform for KompressCompressor { ... }定位非常克制纯文本压缩器只作为最后手段、只用于超过 5KB 的 live-zone 用户消息文本权重固定时输出确定。当前仓库对应 transforms/kompress.rs并有 kompress_parity.rs 做 Python/Rust 双端一致性验证。7. 架构“明确不做”的清单文档 2.6 节的负面清单是这套架构区别于“什么都压一点”型中间件的关键逐条继承不丢弃历史消息。永远。ICM 已消失。不修改system、tools或任何旧轮次。不把 Headroom 自己的工具注入客户 prompt——除非本会话已经触发过 CCR且一旦注入就恒常存在绝不抖动。不在请求期查询 TOIN。推荐只在启动时加载。代理不 shell out 到 RTK。RTK 位于 wrap-CLI 一侧2026-05-01 项目决议。不做 Anthropic ↔ OpenAI 形状互转。每个 provider 有自己的原生 handlerBedrock 与 Vertex 走原生信封Phase D。不在/v1/responses/compact或/v1/conversations上压缩形状不同仅透传。不改写请求头除了剥离上游方向的x-headroom-*、以及按模式条件添加X-Forwarded-*仅 PAYG/OAuth。不添加User-Agent。客户的 UA 原样透传。不压缩图片、base64 块或音频本次 realignment 范围外。不改tool_use.input的 JSON 键序、tool_calls.function.arguments字符串内容、phase字段、V4A patch、local_shell_call.action.command的 argv 数组以及任何加密/脱敏/compaction 内容。这份清单与第 3 节的 I1–I10 互为表里不变量回答“必须保证什么”负面清单回答“哪些诱惑明确拒绝”。8. 小结如何用这套架构阅读当前代码库如果你要在本仓库中验证 REALIGNMENT 架构文档的每一项主张最短路径是字节忠实读 live_zone.rs 的字节区间手术说明跑 live_zone_dispatch.rs 的byte_fidelity_outside_compressed_blockfrozen 边界读 cache_control.rs 的compute_frozen_countauth-mode 门控读 auth_mode.rs 的分类顺序与AuthMode枚举CCR 无损端到端读 ccr/mod.rs 的 TTL 语义与 ccr_roundtrip.rstoken 不减门禁读 live_zone_token_validation.rs 的属性测试。整体而言02-architecture.md 的价值在于把“压缩工具输出”这件看似可以随意发挥的事收敛为一组可测试的不变量压缩只发生在 live zone热区字节逐位冻结输出确定性可复现节省以 token 而非字节度量且一切策略最终由 auth mode 一维门控。这是当前 Rust 代码库headroom-coreheadroom-proxy实际组织方式的设计依据也是后续阅读 03-phase-A-lockdown.md 等阶段文档的前提。【免费下载链接】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），仅供参考