OmniRoute Prompt Compression 完全指南：从 15% 到 95% 的自动 Token 节省管线

导读：OmniRoute 将提示词压缩内建于请求路由管线中，在请求发送到上游 Provider 之前透明执行，无需改动客户端工作流。本文以 docs/compression/COMPRESSION_GUIDE.md 为核心，逐层拆解 Off / Lite / Standard / Aggressive / Ultra / RTK / Stacked 七种模式的选择逻辑、上游节省率数学、Output Styles 输出风格目录、缓存感知压缩与渐进式老化等高级子系统，并结合 open-sse/services/compression/ 源码与单元测试验证关键行为。读完你将掌握：压缩模式如何被 resolveCompressionPlan 决策、x-omniroute-compression 请求头如何逐请求覆盖、以及如何在 Dashboard 与 REST API 两套界面下完成精细配置。

压缩管线总览：Proactive 压缩如何工作

OmniRoute 的压缩是一套模块化、在请求到达上游 Provider 之前主动运行的管线。所谓"主动"，指压缩不是靠用户手工把提示词变短，而是网关在转发前按既定策略自动改写上下文，让 Token 节省发生在工作流无感知的层面。

从源码结构看，策略决策集中在 open-sse/services/compression/resolveCompressionPlan.ts 与 open-sse/services/compression/deriveDefaultPlan.ts：两者负责把"优先级链"收敛成最终执行计划。官方文档将完整决策流描述如下：

Client Request
  → Compression Strategy Selector
    → Combo override? → Use combo setting
    → Auto-trigger threshold? → Use auto mode
    → Default mode? → Use global setting
    → Off? → Skip compression
  → Selected Compression Mode
    → Off: No compression
    → Lite: Safe whitespace/formatting cleanup (~15%)
    → Standard: Caveman-speak filler removal (~30%)
    → Aggressive: History aging + summarization (~50%)
    → Ultra: Heuristic pruning + code-block thinning (~75%)
    → RTK: Command-aware terminal/tool-output filtering (60-90% upstream range)
    → Stacked: Ordered multi-engine pipeline, usually RTK then Caveman (78-95% eligible range)
  → Compressed Request → Provider

关键点在于优先级是分层覆盖的：某个请求命中的 Routing Combo 若显式指定了压缩 Combo，则以 Combo 设置优先；否则检查是否超过 Auto-Trigger 阈值；再退回全局默认；最后才是关闭压缩。无论哪种来源，最终模式都会被记录在压缩统计中（见下文 "Compression Stats" 的 source 字段）。

七种压缩模式详解

Off：零改动直通

不应用任何压缩，所有消息原样透传。适用于需要绝对字节级一致性的调试、审计场景，也是全局主开关关闭时所有请求的兜底。

Lite 模式（约 15% 节省，<1ms 延迟）

最安全的模式——零语义变化，只做格式清理。官方文档给出的技术清单如下：

技术	说明
collapseWhitespace	合并连续空行与行尾空格
dedupSystemPrompt	去除重复的 system 消息
compressToolResults	压缩冗长的工具/函数输出
removeRedundantContent	去除重复指令
replaceImageUrls	缩短 base64 图片 data URI

适用场景：长期常开、安全关键的工作流。从 Compression Stats 的示例 JSON 可见，Lite 命中时 techniquesUsed 会如实记录例如 ["collapseWhitespace","dedupSystemPrompt"]。

Standard 模式（约 30% 节省）

灵感来自开源项目 Caveman（"why use many token when few token do trick"）。该模式通过 30+ 条针对编码提示词调优的正则规则去除虚词、压缩啰嗦表达：

• 移除填充词（"please"、"I think"、"basically"、"actually"）；
• 压缩繁复短语（"in order to" → "to"、"as a result of" → "because"）；
• 剥离礼貌性修饰（"Would you mind..."、"If you could possibly..."）。

适用场景：日常编码工作流、成本敏感团队。Caveman 规则的工程实现位于 open-sse/services/compression/caveman.ts 与 open-sse/services/compression/cavemanRules.ts，并支持语言包扩展（参见 COMPRESSION_LANGUAGE_PACKS.md）。

Aggressive 模式（约 50% 节省）

面向长会话的智能历史管理：

• Message Aging——越老的会话消息被渐进式压缩；
• Tool Result Summarization——长工具输出被替换为摘要；
• Structural Integrity Guards——保证 tool_use 与 tool_result 配对不被破坏；
• Context Window Awareness——尊重每个模型各自的 Token 上限。

适用场景：长时间调试会话、大型代码库。

Ultra 模式（约 75% 节省）

Token 临界场景下的最大压缩，且包含 Aggressive 全部特性：

• Heuristic Pruning——移除低于相关度阈值的历史消息；
• Code Block Thinning——压缩重复的代码示例；
• Binary Search Truncation——二分查找上下文窗口的最优截断点。

适用场景：反复撞上上下文上限时。

RTK 模式（上游 60-90% 区间）

RTK（Rust Token Killer 思路的命令感知引擎）专门处理编码 Agent 会话中体积最大的噪音来源：shell、构建、测试、git、grep 与文件输出转录。仓库内 RTK 的完整设计见 RTK_COMPRESSION.md，本文先提炼它在主管线中的职责：

• 识别命令/输出类别，如 git status、git diff、git log、测试运行器、TypeScript/Vite/Webpack 构建、ESLint/Biome/Prettier、npm audit/install、Docker 日志、基础设施输出与通用 shell 输出；
• 应用位于 open-sse/services/compression/engines/rtk/filters/ 的 JSON filter 包；
• 支持导入项目级或全局 filters.toml（RTK TOML schema v1），带内联测试校验与项目文件信任门控；
• 内置过滤器附带 inline verify 样例——按当前仓库实际文件统计，filters/ 目录下的 JSON 过滤器已超过 49 个（现有 55 个，覆盖 aws、biome、docker-logs、git-diff、terraform-plan、test-vitest、uv-sync 等）；
• 移除 ANSI 控制序列、进度条、重复行与无行动价值的噪音；
• 保留失败信息、错误、警告、变更文件列表、摘要以及长输出的尾部；
• 支持受信任的项目过滤器、全局过滤器，以及可选的脱敏 raw-output 恢复。

输出类别判定的核心逻辑在 open-sse/services/compression/engines/rtk/commandDetector.ts。值得注意的是，从 open-sse/services/compression/engines/rtk/index.ts 的 SHELL_TOOL_NAME_RE 可以看出：RTK 过滤器只作用于 bash/shell 类工具结果（bash、shell、terminal、run_command、execute_command 等），普通读取类工具（read、glob、grep、edit、write）会跳过过滤器匹配，以避免内容型误判（例如一个 .ts 文件内容误命中 build-typescript 过滤器）。

适用场景：包含 shell、构建、测试、git、grep、文件输出转录的 Agent 会话。

Stacked 模式（78-95% 可节省区间）

Stacked 以确定性顺序串联多个压缩引擎，默认管线为：

RTK -> Caveman

该顺序先把终端/工具输出压紧凑，再用 Caveman 对剩余的自然语言做语义压缩。Stacked 管线既可全局配置，也可通过分配给路由 Combo 的 Compression Combo 指定。

适用场景：大型工具日志 + 人类指令/助手摘要并存的混合上下文。

上游节省率数学与 "eligible" 的真实含义

OmniRoute 文档中的节省率来自两个来源：上游项目基准数据 + OmniRoute 自身引擎组合计算。

来源	采用的上游 README 数据
Caveman	输出 Token 减少约 75%，基准测试平均输出节省 65%，区间 22-87%，输入压缩工具约 46%
RTK	命令输出节省 60-90%；示例会话 ~118,000 → ~23,900 Token，即节省 79.7%（约 80%）

对于重叠的工具/上下文载荷，默认 Stacked 组合把节省率按乘法而非加法叠加：

combined = 1 - (1 - RTK savings) * (1 - Caveman input savings)
average  = 1 - (1 - 0.80) * (1 - 0.46) = 89.2%
range    = 1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%

即：78-95% 这个数字只在 RTK 与 Caveman 能同时削减同一输入/上下文载荷时成立。Caveman 的响应输出模式是另一条独立路径：启用后应参照 Caveman 自己的输出节省（平均 65%、主打 75%、区间 22-87%）。实际账单节省取决于你的提示词/输出混合比例。

"eligible"（可节省）到底指什么

标题中的 15-95% 是真实存在但有条件的：它只适用于冗余或啰嗦的内容——重复的错误行、反复刷屏同一条警告的构建日志、超大的 grep/文件读取转储。并非每个请求都能省这么多。

这一点在仓库中有实测佐证：测试 tests/unit/compression/stacked-compression-tool-result-savings.test.ts 对一段包含 300 行完全相同的错误行的 Anthropic 结构 tool_result 块运行 stacked（RTK + Caveman），得到 95.93% Token 节省 / 96.26% 字符节省，正好落在宣传区间内。而同样的管线跑在正常、非冗余的工具输出上（干净的 grep 命中列表、短文件读取、普通对话文本），则会正确地产生接近零的节省——因为没有可去重的内容，且 open-sse/services/compression/validation.ts 中的 validateCompression() 会拒绝发布会删除或篡改代码块、URL、标题、版本号或全大写常量标识符的重写结果。

这是预期且安全的行为，不是 bug：一个以读文件/grep 干净内容为主的编码会话即使完全开启压缩，总节省也可能很有限；而命中失败循环或话痨型 linter 的会话，在那段流量上能看到完整的 78-95%。不要用某一次会话的低聚合节省率断言"压缩配置错误"——先检查底层工具输出是否真的冗余。

Token 节省可视化示例

以 47K Token 的原始请求为例，各模式的效果对比：

Without compression: 47K tokens sent to LLM
With Lite:           40K tokens sent          (15% saved — safe, always-on)
With Standard:       33K tokens sent          (30% saved — caveman-speak rules)
With Aggressive:     24K tokens sent          (50% saved — aging + summarization)
With Ultra:          12K tokens sent          (75% saved — heuristic pruning)
With RTK:            19K-5K tokens sent       (60-90% saved on command/tool output)
With Stacked:        10K-2.5K tokens sent     (78-95% eligible RTK+Caveman range)

这份对比的价值在于建立直觉：越靠后的模式节省越大，但对应地也只该在真正需要时使用——RTK 与 Stacked 的高额数字来自对命令/工具输出的压缩，而不是对普通对话的"无中生有"式削减。

Output Styles：让模型自己产出更便宜的输出

Output Styles 通过注入一段 system prompt 指令来引导模型的写作风格，定义在 Output Style 目录中，支持多种语言与三档强度（lite、full、ultra）。这是传统 Caveman 输出模式的目录化泛化（Phase 4）：open-sse/services/compression/outputStyles/catalog.ts 中的 OUTPUT_STYLE_CATALOG 就是注册表本体——添加一种风格只需在此增加一个条目，注入器与设置面板都会自动枚举它。

风格	说明	支持语言	档位
terse-prose	去除填充词/冠词/模棱两可，保持技术内容精确	en, pt-BR, ja, id, vi	lite, full, ultra
less-code	YAGNI 阶梯：最小可用改动，不做未要求的抽象	en, pt-BR, vi, ja, id	lite, full, ultra
ponytail	懒惰资深工程师纪律：爬 YAGNI 阶梯、修根因、最小可用 diff	en, pt-BR, vi, ja, id	lite, full, ultra
i-have-adhd	行动优先输出：下一步动作先行、步骤编号、一个具体下一步、无开场白	en, pt-BR, vi, ja, id	lite, full, ultra
terse-cjk	古典中文极致简洁风格（按区域锁定 zh）	zh	lite, full, ultra

每个档位都会追加一段共享边界条款，确保代码块、URL、文件路径、命令和标识符保持逐字不变（该常量在 open-sse/services/compression/outputMode.ts 中导出）。

注入机制

applyOutputStyles()（open-sse/services/compression/outputStyles/apply.ts）把选中项对照目录解析——未知 id 与语言不匹配的风格会被静默丢弃而非报错——按目录顺序拼接指令文本，只追加一次边界条款，并在单条幂等标记 [OmniRoute Output Styles] 之后把结果前置到 system prompt 中；重复应用是 no-op。当检测到请求语言存在译文时，注入的是本地化指令而非英文。由于注入文本对每个 (id, level, language) 是静态确定的，系统前缀能保持 prompt-cache 稳定。

如何启用

Dashboard 路径为 Context → Settings → Compression，每种风格一行，含开关与档位选择器。程序化层面，压缩配置以如下结构持久化：

{
  "outputStyles": [
    { "id": "i-have-adhd", "level": "full" },
    { "id": "less-code", "level": "lite" }
  ]
}

向后兼容：遗留的 outputMode: "caveman" Combo 设置仍然可用，且会映射到 terse-prose——在四种遗留语言中与旧注入逐字节一致（由 open-sse/services/compression/outputStyles/backCompat.ts 负责）。风格 × 语言矩阵由测试 tests/unit/compression/output-styles-i18n-matrix.test.ts 钉死：新风格至少要有 pt-BR 译文（或明确的受跟踪例外）才能发布，已有风格也不能悄悄丢失某个 locale。

高级压缩系统（自动生效）

主文档在七种模式之外还说明了四类"基于上下文自动工作"的高级系统。

缓存感知压缩（Cache-Aware Compression）

Anthropic 等 Provider 的 prompt caching 会缓存提示词前缀以降低成本与延迟。缓存开启时，激进压缩反而会伤害性能——它改变了已缓存的 Token，导致缓存失效。

cachingAware.ts 模块通过检测缓存上下文并调整策略来解决这一问题：

1. 检测缓存上下文——扫描请求体中的 cache_control 标记（实现上会递归检查 system、tools、messages、input、contents、request.contents 等字段）；
2. 识别缓存型 Provider——检查目标 Provider 是否支持缓存（借助 open-sse/src/utils/cacheControlPolicy.ts 中的 providerSupportsCaching）；
3. 调整策略——对缓存型 Provider 把 aggressive/ultra 降级为 standard；
4. 跳过 system prompt——system prompt 通常被缓存，不做压缩；
5. 仅使用确定性变换——保证输出一致、可复现。

源码级的接口示例（文档原样给出，调用面与仓库 open-sse/services/compression/cachingAware.ts 导出一致）：

import {
  detectCachingContext,
  getCacheAwareStrategy,
} from "@omniroute/open-sse/services/compression/cachingAware";

const body = {
  model: "anthropic/claude-sonnet-4.5",
  messages: [{ role: "user", content: "Hello" }],
  cache_control: { type: "ephemeral" }, // ← Cache marker
};

const ctx = detectCachingContext(body, { provider: "anthropic" });
// → { hasCacheControl: true, provider: "anthropic", isCachingProvider: true }

const strategy = getCacheAwareStrategy("aggressive", ctx);
// → { strategy: "standard", skipSystemPrompt: true, deterministicOnly: true }

RTK 引擎内部也遵循同一原则：从 open-sse/services/compression/engines/rtk/index.ts 的注释与 hasCacheControlMarker 守卫可见，任何携带 cache_control 的块都会被逐字节保留——因为改写它等价于每轮强制缓存未命中。相关回归测试见 tests/unit/compression/rtk-cache-control-preserve.test.ts 与 tests/unit/compression/cache-aware-preserve-mode.test.ts。

何时生效：缓存感知压缩始终开启、无需配置。仅当请求带 cache_control 标记且目标 Provider 支持提示词缓存（Anthropic、OpenAI 等）时才会介入。

渐进式老化（Progressive Aging）

长对话越老的轮次相关性越低。progressiveAging.ts 的 applyAging 按轮次距离降级消息：

• 近期轮次（0-3）：逐字保留（完整细节）；
• 中等轮次（4-8）：Lite 压缩（空白与格式清理）；
• 较老轮次（9+）：Caveman 压缩（去填充词、摘要化）；
• 很老轮次（20+）：重度摘要或丢弃。

文档给出的接口示例：

import { applyAging } from "@omniroute/open-sse/services/compression/progressiveAging";

const messages = [
  { role: "system", content: "You are a helpful assistant" },
  { role: "user", content: "What is 2+2?" },
  { role: "assistant", content: "4" },
  // ... 50 more turns ...
];

const { messages: aged, saved } = applyAging(messages, {
  verbatim: 3,  // First 3 turns: verbatim
  light: 8,     // Turns 4-8: lite compression
  moderate: 20, // Turns 9-20: caveman compression
  // Turns 21+: heavy summarization
});

// saved = number of tokens saved

实现上（对照 open-sse/services/compression/progressiveAging.ts 源码），老化结果会打上 [COMPRESSED:aging:<tier>] 前缀作为幂等与递归守卫——再次运行时是 no-op。纯 JSON 载荷会保持逐字且不加标签（保持可被 JSON.parse），围栏代码块则把标签放在围栏之前单独成行以保证块结构合法。默认阈值来自 DEFAULT_AGGRESSIVE_CONFIG.thresholds（定义于 open-sse/services/compression/types.ts）。单元测试见 tests/unit/compression/progressiveAging.test.ts。

何时生效：对 aggressive 与 ultra 模式始终开启。对长时编码会话、跨天对话、含大量工具调用的 Agent 工作流尤其有效。

Tool Result 压缩（Tool Result Compression）

open-sse/services/compression/toolResultCompressor.ts 为工具结果（函数调用、Agent 输出、搜索结果等）提供 5 种专用压缩策略：

1. 搜索结果压缩——去除冗余结果，保留 Top-N；
2. 文件读取压缩——截断大文件，保留头部/导入区；
3. 代码执行压缩——仅保留关键 stdout/stderr；
4. 数据库查询压缩——限制行数，去除冗长元数据；
5. API 响应压缩——剥离 null 字段、压缩数组。

何时生效：存在工具调用时始终开启，无需配置。

Stacked 管线原理

Stacked 模式按序运行多个引擎——通常先用 RTK（对工具输出省 60-90%），再对剩余文本用 Caveman（再省约 30%），合计 78-95%：

Input (1000 tokens)
  → RTK (command-aware filter) → 200 tokens
    → Caveman (filler removal) → 140 tokens
  → Output (140 tokens, 86% savings)

适用场景：工具密集型工作流（Agentic 编码、研究）、成本敏感批处理、需要极限 Token 节省时。通过 Combo 配置启用：

{
  "strategy": "auto",
  "config": {
    "auto": {
      "modePack": "stacked"
    }
  }
}

三层配置体系

① Dashboard 全局配置

导航至 Dashboard → Context & Cache：

• Caveman——模式选择、语言包、预览与全局默认；
• RTK——命令过滤器预览、RTK 安全设置与过滤器目录；
• Compression Combos——命名引擎管线，可分配给路由 Combo；
• Auto-Trigger Threshold——当 Token 数超过阈值时自动启用压缩。

② Per-Combo Override（每路由 Combo 覆盖）

在 Dashboard → Context & Cache → Compression Combos 中把压缩 Combo 分配给某个路由 Combo：

Combo: "free-tier-fallback"
  Compression Combo: "coding-agent-stack"
  Pipeline: RTK -> Caveman
  Targets:
    1. if/kimi-k2.7-code
    2. if/qwen3.8-max-preview

这样可以在免费/编码 Provider 上使用 Stacked 压缩，同时在付费订阅上保持 Lite。

需要特别区分的是：这里的 "Per-Combo Override" 与路由 Combo 的压缩模式覆盖（Default/Off/Lite/Standard/Aggressive/Ultra）是两个不同的控制项——后者不选择命名压缩管线，只是设置 compressionMode 字段供 resolveCompressionPlan 读取。它既可以在 Combo 卡片（Dashboard → Combos）上设置，也可以自某次更新起在 Compression Combos 页面的 "Assign to routing" 列表中、紧挨着上面文档化的管线分配复选框旁逐路由设置。两个界面最终都通过同一个 PUT /api/combos/{id} 端点持久化。

③ Per-request override（逐请求覆盖）

发送 x-omniroute-compression 请求头即可覆盖单个请求的压缩计划。它拥有最高优先级——胜过路由 Combo 覆盖、活动 Profile、Auto-Trigger 与面板默认值。未知值会被忽略（请求绝不会被拒绝），且全局主开关仍然闸控一切：当压缩全局关闭时，该请求头无法把它打开。取值：

值	效果
off	该请求不做压缩
default	使用面板派生的 Default profile（忽略活动 Profile）
engine:<id>	启用单个引擎，例如 engine:rtk
<combo>	具名 Combo，先按名称（不区分大小写）再按 id 匹配

实际应用的计划会通过响应头 X-OmniRoute-Compression: <mode>; source=<source> 回显，其中 <source> 为 request-header、routing-override、active-profile、auto-trigger、default 或 off 之一。该回显便于你调试"这个请求到底命中了哪一层策略"。

REST API 配置

压缩相关 API 挂在网关本地端口（示例为 localhost:20128）：

# Get compression settings
curl http://localhost:20128/api/settings/compression

# Update compression settings
curl -X PUT http://localhost:20128/api/settings/compression \
  -H "Content-Type: application/json" \
  -d '{"defaultMode":"stacked","autoTriggerMode":"stacked","autoTriggerTokens":32000}'

# Preview a specific RTK/stacked payload
curl -X POST http://localhost:20128/api/compression/preview \
  -H "Content-Type: application/json" \
  -d '{"mode":"rtk","messages":[{"role":"tool","content":"npm test output here"}]}'

# List RTK filter packs
curl http://localhost:20128/api/context/rtk/filters

# Test RTK directly with optional command metadata
curl -X POST http://localhost:20128/api/context/rtk/test \
  -H "Content-Type: application/json" \
  -d '{"command":"npm test","text":"FAIL tests/example.test.ts\nError: boom"}'

/api/context/rtk/* 系列的管理路由需要 Dashboard 管理认证或匹配的 API-key 策略。更多端点（/api/context/rtk/config 的 GET/PUT、/api/context/rtk/import 校验或安装 RTK TOML schema v1 文件、/api/context/rtk/raw-output/[id] 读取脱敏原始输出等）见 RTK_COMPRESSION.md 的 API 章节。

RTK 专项配置要点

RTK 模式还有一组独立配置项，官方主文档之外可在 RTK_COMPRESSION.md 查全。典型配置 JSON（含 rtkConfig 子对象）会持久化到 SQLite key_value 表（namespace="compression", key="rtkConfig"，读写见 src/lib/db/compression.ts），因此全部字段都能跨重启保留：

{
  "defaultMode": "stacked",
  "autoTriggerMode": "stacked",
  "autoTriggerTokens": 32000,
  "stackedPipeline": [
    { "engine": "rtk", "intensity": "standard" },
    { "engine": "caveman", "intensity": "full" }
  ],
  "rtkConfig": {
    "enabled": true,
    "intensity": "standard",
    "applyToToolResults": true,
    "applyToCodeBlocks": false,
    "applyToAssistantMessages": false,
    "enabledFilters": [],
    "disabledFilters": [],
    "maxLinesPerResult": 120,
    "maxCharsPerResult": 12000,
    "deduplicateThreshold": 3,
    "customFiltersEnabled": true,
    "trustProjectFilters": false,
    "rawOutputRetention": "never",
    "rawOutputMaxBytes": 1048576,
    "enableGrouping": false,
    "groupingThreshold": 3,
    "stripCodeComments": false,
    "preserveDocstrings": true
  }
}

enabledFilters / disabledFilters 使用过滤器 id（如 test-vitest、git-diff）。完整 rtkConfig 形状由 open-sse/services/compression/types.ts 中的 RtkConfig / DEFAULT_RTK_CONFIG 定义，读取时经 normalizeRtkConfig 归一化。

值得留意的去重与分组设计（源码均可在 RTK 引擎目录下交叉验证）：

• 两层行去重：先是单过滤器内可选的 deduplicate（默认 false，在 filterSchema.ts 中以 z.boolean().default(false) 声明，在 lineFilter.ts 内截断前执行）；再是引擎级的 deduplicateThreshold（默认 3，取值范围 2–100，在 index.ts 的 deduplicateRepeatedLines 中对整段结果做收尾去重）。先内后外，不会重复计数。
• 相似行分组：rtkConfig.enableGrouping（默认 false）开启后，grouper.ts 的 groupSimilarLines 会折叠"形态相近但非逐字节相同"的连续行；groupingThreshold（默认 3）为触发分组的最小连续行数。
• 代码注释剥离：applyToCodeBlocks 启用后，stripCodeComments（默认 false，需显式开启）可移除 JS/TS 围栏代码块内的注释，由 codeStripper.ts 基于 TypeScript parser 实现（非正则，避免把字符串/模板/正则字面量误判为注释），检测到 JSX 时整体退出；preserveDocstrings（默认 true）保留 /** … */ JSDoc 块。当前仅适用于 JavaScript 与 TypeScript。
• 强度档位：RTK 支持 minimal / standard（默认）/ aggressive 三档（对应约 20-40% / 50-70% / 70-90% Token 节省）。截断阈值在 index.ts 中按 config.intensity === "aggressive" ? 16 : 24 决定（每个 section 的 head 与 tail 均保留，中段在截断时丢弃）。无论哪一档，错误、测试失败与栈追踪都保留；minimal 档对原始内容基本是 no-op。

什么内容永远不会被压缩

压缩引擎始终保留：

• ✅ 代码块（围栏式与行内式）
• ✅ URL 与文件路径
• ✅ JSON 结构与结构化数据
• ✅ 标识符与受保护的技术 Token
• ✅ 数学表达式
• ✅ 工具/函数调用定义
• ✅ system prompt（Lite 模式下）

RTK 的 raw-output 恢复机制在任何内容被持久化前，会脱敏常见的 API key、bearer token、Slack token、AWS access key、密码、token 与 secret。这保证了"压缩后无法直观看到原文"的场景下，安全底线仍在。

Compression Stats：压缩统计

每个被压缩的请求都会在服务端日志中产生统计块，rtkRawOutputPointers[] 可关联到脱敏保留的原始输出：

{
  "originalTokens": 47200,
  "compressedTokens": 40120,
  "savingsPercent": 15.0,
  "techniquesUsed": ["collapseWhitespace", "dedupSystemPrompt"],
  "mode": "lite",
  "engine": "caveman",
  "compressionComboId": "coding-agent-stack",
  "durationMs": 0.8,
  "rtkRawOutputPointers": []
}

建议在监控/审计时同时关注 source（策略来源）与 techniquesUsed（实际命中的技术），它们能帮你判断节省来自计划决策还是具体规则，而不是仅看 savingsPercent 一个数字。

Compression Combo Overrides：面向多场景的精细粒度

可以在全局压缩模式之上按路由 Combo 覆盖，为不同使用场景定制行为：

{
  "id": "coding-combo",
  "strategy": "priority",
  "config": {
    "auto": {
      "weights": { "taskFit": 0.5 },
      "modePack": "quality-first"
    }
  },
  "compressionOverride": {
    "mode": "aggressive",
    "stackedPipelines": ["rtk", "caveman"],
    "preserveToolDefinitions": true
  }
}

推荐的落地组合：

• 编码 Combo：长会话用 aggressive；
• 快速问答 Combo：追求响应速度用 lite；
• 工具密集 Combo：要极限节省用 stacked；
• 生产 Combo：对缓存型 Provider 使用 cache-aware 行为。

阶段路线图

Phase	模式	状态
Phase 1	Off, Lite	✅ 已发布
Phase 2	Standard, Aggressive, Ultra	✅ 已发布
Phase 3	RTK, Stacked, Compression Combos	✅ 已发布
Phase 4	Output Styles, SLM-tier Ultra, eval harness	✅ 已发布
Phase 4C	自适应上下文预算（"dial"）——计算引擎 + API（PUT /api/settings/compression 的 contextBudget）	✅ 已发布（API 可配置；Dashboard 控件尚未构建）

从源码目录看，Phase 4C 的实现位于 adaptiveCompression/，包含 computeTarget.ts、ladder.ts、resolveAdaptivePlan.ts 与 types.ts 四个模块；围绕它的单元测试（如 adaptive-resolve-plan.test.ts、adaptive-compute-target.test.ts）进一步印证了自适应目标推导与计划解析的调用关系。此外 engines/registry.ts 是内置引擎注册表，引擎间的配置更新应通过 updateEngineConfig("rtk", { intensity: "aggressive" }) 这类注册表辅助方法进行。

致谢与上游渊源

Standard 模式压缩规则受开源项目 Caveman 启发（其口号可概括为 "why use many token when few token do trick"），上游数据为：输出 Token 减少约 75%、基准平均输出节省 65%、输出区间 22-87%、输入压缩工具约 46%。

RTK 模式受 RTK（Rust Token Killer） 项目启发，上游报告命令输出节省 60-90%，其示例会话约省 80%。

OmniRoute 的贡献是把两者接入统一管线、用 validateCompression() 守住代码/URL/标识符不被破坏，并让"何时、对什么内容、用什么模式压缩"的决策完全可配置、可观测。若需了解引擎注册与内置引擎清单，可继续阅读 COMPRESSION_ENGINES.md；自定义 JSON 规则包的字段格式见 COMPRESSION_RULES_FORMAT.md。

延伸阅读

• 环境变量配置——压缩相关环境变量；
• 架构指南——压缩管线内部结构；
• 用户指南——压缩的快速上手；
• RTK 压缩详解——RTK 过滤器、信任模型、verify gate、raw-output 恢复；
• 压缩引擎——Caveman、RTK、Stacked、API、MCP、Dashboard；
• 压缩规则格式——JSON rule-pack 格式；
• 压缩语言包——Caveman 的多语言规则。