Architecture架构

Headroom sits between your application and the LLM provider. It intercepts messages, compresses them intelligently, and forwards the optimized request. The response comes back unchanged.Headroom 位于您的应用程序与 LLM 提供商之间。它会拦截消息，进行智能压缩，并转发优化后的请求。返回的响应内容保持不变。

High-Level Flow高层级流程

+---------------------------------------------------------------+
|                       YOUR APPLICATION                        |
+---------------------------------------------------------------+
                               |
                               v
+---------------------------------------------------------------+
|                      HEADROOM CLIENT                          |
|  +-----------+   +------------+   +---------+                 |
|  |  ANALYZE  | > |  TRANSFORM | > |  CALL   |                 |
|  |  (Parser) |   |  (Pipeline)|   |  (API)  |                 |
|  +-----------+   +------------+   +---------+                 |
|       |                |                |                     |
|       v                v                v                     |
|  Count tokens    Apply compressions   Send to LLM provider   |
|  Detect waste    Preserve meaning     Log metrics             |
+---------------------------------------------------------------+
                               |
                               v
+---------------------------------------------------------------+
|                  OPENAI / ANTHROPIC / GOOGLE                  |
+---------------------------------------------------------------+

Entry Points接入点

Headroom can be used in three ways, all feeding into the same pipeline:Headroom 可通过三种方式使用，它们最终都会进入同一条流水线：

The Transform Pipeline转换流水线

Messages flow through a sequence of transforms. Each transform is independent, safe to skip, and fails gracefully (returns original content unchanged).消息会流经一系列转换器。每个转换器都是独立的，可以安全跳过，并且具备优雅降级机制（即直接返回原始内容，不做任何修改）。

Stage 1: Cache Aligner第一阶段：缓存对齐器 (Cache Aligner)

Extracts dynamic content (dates, UUIDs, session tokens) from your system prompt and moves it to the end. This stabilizes the prefix so provider caches (Anthropic cache_control, OpenAI prefix caching) can hit on repeated calls.从系统提示词中提取动态内容（如日期、UUID、会话令牌）并将其移至末尾。这能稳定前缀，从而使提供商缓存（如 Anthropic 的 cache_control 或 OpenAI 的前缀缓存）在重复调用时能够命中。

Before: "You are helpful. Current Date: 2024-12-15"
         ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
         Changes daily = cache miss every day

After:  "You are helpful."                          [stable prefix]
        "[Context: Current Date: 2024-12-15]"       [dynamic tail]

Overhead: sub-millisecond.开销：亚毫秒级。

Stage 2: Smart Crusher第二阶段：智能压缩器 (Smart Crusher)

Analyzes tool output content and compresses it using statistical methods. This is where the bulk of token savings come from.利用统计方法分析并压缩工具输出内容。这是节省 Token 的主要来源。

What it does:功能说明：

1. Parses JSON arrays in tool outputs解析工具输出中的 JSON 数组
2. Runs field-level statistical analysis (variance, uniqueness, change points)执行字段级的统计分析（方差、唯一性、变化点）
3. Selects a representative subset using the Kneedle algorithm on bigram coverage基于二元语法 (bigram) 覆盖率，使用 Kneedle 算法选择具有代表性的子集
4. Preserves errors, anomalies, and distribution boundaries unconditionally无条件保留错误信息、异常数据和分布边界
5. Factors out constant fields shared by all items提取所有项共有的常量字段

Strategies by content type:按内容类型的处理策略：

Item retention split: 30% from array start (schema), 15% from end (recency), 55% by importance score. Error items are always kept regardless of budget.项保留拆分：数组开头保留 30%（模式），结尾保留 15%（时效性），其余 55% 按重要性评分保留。错误项无论预算如何都会被保留。

Overhead: 1--50ms for typical payloads. Scales linearly with input size.开销：典型负载下为 1-50 毫秒。随输入大小线性扩展。

Stage 3: Context Manager第三阶段：上下文管理器 (Context Manager)

Ensures the final message array fits within the model's context window.确保最终的消息数组符合模型的上下文窗口限制。

Rolling Window (default): Drops oldest messages first, preserving system prompt and recent turns. Tool calls and their responses are dropped as atomic units.滚动窗口（默认）：优先丢弃最旧的消息，保留系统提示词和最近的对话轮次。工具调用及其响应会作为原子单元被丢弃。

Intelligent Context (advanced): Scores every message on six dimensions (recency, semantic similarity, TOIN importance, error indicators, forward references, token density) and drops the lowest-scored messages first. Dropped messages are stored in CCR for potential retrieval.智能上下文（高级）：从六个维度（时效性、语义相似度、TOIN 重要性、错误指标、前向引用、Token 密度）对每条消息进行评分，并优先丢弃得分最低的消息。被丢弃的消息会存储在 CCR 中以便后续检索。

Overhead: sub-millisecond for Rolling Window; depends on scoring config for Intelligent Context.开销：滚动窗口为亚毫秒级；智能上下文取决于评分配置。

Provider Cache Optimization提供商缓存优化

After the pipeline, Headroom applies provider-specific cache hints:流水线处理完成后，Headroom 会应用特定于提供商的缓存提示：

CCR: Compress-Cache-RetrieveCCR：压缩-缓存-检索 (Compress-Cache-Retrieve)

When SmartCrusher compresses a tool output or Intelligent Context drops messages, the original content is stored in a local compression cache. If the LLM needs the full data, it can request retrieval via a ccr_retrieve tool call. This makes compression reversible.当 SmartCrusher 压缩工具输出或智能上下文丢弃消息时，原始内容会被存入本地压缩缓存。如果 LLM 需要完整数据，可以通过 ccr_retrieve 工具调用请求检索。这使得压缩过程可逆。

Compress:  1000 items  ->  15 items  (stored original in CCR)
Cache:     Hash-indexed local store (SQLite)
Retrieve:  LLM calls ccr_retrieve("abc123")  ->  original 1000 items

TOIN: Tool Output Intelligence NetworkTOIN：工具输出智能网络 (Tool Output Intelligence Network)

TOIN learns compression patterns across sessions and users. When a tool is used repeatedly, TOIN builds up statistics about which fields matter, which items get retrieved, and what compression strategies work best. These learned patterns feed back into SmartCrusher and Intelligent Context scoring.TOIN 会跨会话和用户学习压缩模式。当工具被重复使用时，TOIN 会积累关于哪些字段重要、哪些项会被检索以及哪种压缩策略效果最好的统计数据。这些学习到的模式会反馈给 SmartCrusher 和智能上下文评分系统。

Cold start: For new tool types, TOIN falls back to statistical heuristics. Patterns build up over time as tools are used.冷启动：对于新的工具类型，TOIN 会回退到统计启发式方法。随着工具的使用，模式会逐渐建立。

What Headroom Does NOT TouchHeadroom 不会触碰的内容

• User messages: Never compressed (the user's intent must be preserved exactly)用户消息：从不压缩（必须精确保留用户的意图）
• System prompts: Content preserved; only dynamic parts are relocated for caching系统提示词：保留内容；仅为缓存目的重定位动态部分
• Code: Passes through unchanged unless tree-sitter AST compression is explicitly enabled代码：原样通过，除非显式启用了 tree-sitter AST 压缩
• Model responses: Returned unchanged from the provider模型响应：从提供商处原样返回
• Short content: Tool outputs under 200 tokens pass through (overhead exceeds savings)短内容：200 Token 以下的工具输出直接通过（开销会超过节省的价值）