OmniRoute RTK 压缩引擎实战：命令感知的终端输出压缩、过滤 DSL、信任门控与三层强度策略

RTK 是 OmniRoute 面向终端与工具输出的命令感知压缩引擎，专门处理编码代理会话中由测试日志、构建输出、包管理器噪音、shell 转录、Docker/git 输出和堆栈跟踪造成的上下文膨胀。本篇结合 RTK_COMPRESSION.md 的完整文档骨架与仓库源码实现，讲透 RTK 的压缩原理、过滤规则 DSL、TOML 兼容层、信任门控、配置持久化、原始输出恢复与验证门禁，读完你可以直接配置、扩展并用测试验证 RTK 的压缩行为。

一、RTK 压缩什么：内置过滤器目录与命令检测

RTK 的设计前提是：在 coding-agent 会话里，绝大多数上下文增长来自机器输出而非自然语言。内置过滤器目录 open-sse/services/compression/engines/rtk/filters/ 目前包含 55 个过滤 JSON 文件（文档写作时为 49 个，持续扩充），覆盖以下类别：

类别	示例
git	git status、git branch、git diff、git log
test	Vitest、Jest、Pytest、Playwright、Go 测试、Cargo 测试
build	TypeScript、ESLint、Biome、Prettier、Vite、Webpack、Turbo、Nx
package	npm install、npm audit、pip、uv sync、Poetry、Bundler
shell	ls、find、grep、通用 shell 日志
docker	docker ps、Docker logs
infra	Terraform、OpenTofu、systemctl status
generic	JSON 输出、堆栈跟踪、通用输出兜底

过滤器选型前，commandDetector.ts 先对输出做分类。从源码看，它维护一个 COMMAND_PREFIXES 前缀表（覆盖 git、npm、pnpm、vitest、pytest、cargo、docker、kubectl、terraform 等约 50 个命令前缀），每个 detector 同时声明 commandPatterns（匹配命令行）与 contentPatterns（匹配输出特征），返回类型、置信度与类别。过滤器还可以通过命令模式或输出正则直接匹配——当命令类别粒度不够时用得上。

引擎入口 index.ts 中有一个重要细节：命令感知过滤只对 shell 类工具结果生效（工具名匹配 bash|shell|terminal|run_command|execute_command|exec|command），非 shell 工具（read、glob、grep、edit、write 等）会跳过过滤匹配，避免内容误伤——例如一个 .ts 文件不会因内容相似而被 build-typescript 过滤器压缩。

二、RTK 与 Caveman 的叠加管线及节省率

RTK 可以以 defaultMode: "rtk" 直接运行，也可以作为叠加管线的第一步，典型顺序为 rtk -> caveman：先用 RTK 压缩噪音机器输出，再让 Caveman 引擎压缩剩余散文。仓库默认叠加管线即如此定义，见 types.ts 中 DEFAULT_COMPRESSION_CONFIG.stackedPipeline：

stackedPipeline: [
  { engine: "rtk", intensity: "standard" },
  { engine: "caveman", intensity: "full" },
],

上游 RTK 报告命令输出可节省 60-90% token，其样例会话从 ~118,000 标准 token 降到 ~23,900 RTK token（约 79.7%）。OmniRoute 用该上游均值计算与 Caveman 叠加后的节省率：

RTK average:    80% saved
Caveman input: 46% saved
Stacked:       1 - (1 - 0.80) * (1 - 0.46) = 89.2% saved
Range:         1 - (1 - 0.60..0.90) * (1 - 0.46) = 78.4-94.6%

三、过滤器解析顺序与项目级信任门控

RTK 按以下顺序加载过滤器：

1. 项目级：.rtk/filters.toml 与 .rtk/filters.json，仅在通过信任校验时加载；
2. 全局级：DATA_DIR/rtk/filters.toml 与 DATA_DIR/rtk/filters.json；
3. 内置级：open-sse/services/compression/engines/rtk/filters/。

同一作用域内，RTK TOML schema v1 过滤器优先于 OmniRoute JSON 过滤器；TOML 的 match_command 表达式先于命令类型匹配检查，因此导入的命令专用过滤器可以在同一作用域内覆盖更宽泛的过滤器。项目作用域始终优先于全局作用域，与文件格式无关。

项目过滤器被刻意设为信任门控，因为正则过滤器会改变工具输出呈现给 agent 的方式。filterLoader.ts 中 projectFiltersTrusted() 的实现确认：当满足以下任一条件时项目过滤器文件被接受——

• rtkConfig.trustProjectFilters 为 true；
• 环境变量 OMNIROUTE_RTK_TRUST_PROJECT_FILTERS=1 已设置；
• .rtk/trust.json 中包含与过滤器文件匹配的 SHA-256 哈希。

信任文件示例：

{
  "filtersSha256": "0123456789abcdef...",
  "filtersTomlSha256": "fedcba9876543210..."
}

两个哈希相互独立：filtersSha256 信任 .rtk/filters.json，filtersTomlSha256 信任 .rtk/filters.toml。修改任一文件只会使对应条目失效（源码中还兼容了旧字段名 trustedFiltersSha256，哈希变化时返回 "changed" 状态供诊断上报）。全局文件由管理员安装，沿用既有的全局过滤器信任行为。自定义过滤器可以是单个过滤对象或对象数组；无效自定义过滤器被跳过并由 /api/context/rtk/filters 的诊断接口报告，而无效内置过滤器会快速失败。

四、RTK TOML schema v1 兼容层

OmniRoute 可以解析、校验、测试并安装 RTK TOML schema v1 声明式过滤器文件。支持字段为：description、match_command、strip_ansi、filter_stderr、strip_lines_matching、keep_lines_matching、replace、match_output、truncate_lines_at、head_lines、tail_lines、max_lines、on_empty，以及 [[tests.<filter>]] 内联测试。以下情况会被拒绝：未知字段、无效或不安全的正则、同时存在 strip/keep 规则、超过 1 MiB 的文件、引用未知过滤器。内联测试未通过的文件可以校验查看，但不能安装或加载。自定义文件加载失败保持 fail-open：无效文件被跳过，其余过滤器继续工作。

一个关键差异：OmniRoute 收到工具输出时客户端已完成捕获，因此 filter_stderr = true 无法改变进程捕获行为——该字段被接受为 no-op，校验时返回警告。文档明确将此定位描述为 RTK TOML schema v1 兼容性，而非与 RTK 可执行程序、shell 钩子、Rust 命令实现或信任库布局的完整兼容。

仪表盘的 RTK 高级视图支持粘贴或上传 TOML，校验为只读操作；安装动作原子写入 DATA_DIR/rtk/filters.toml 并施加严格权限，免重启刷新实时过滤器目录；覆盖已有文件需要显式 overwrite 确认，且会先创建 DATA_DIR/rtk/filters.toml.bak 备份。

五、过滤器 DSL 与运行时执行阶段

过滤器使用 JSON schema，完整格式见 COMPRESSION_RULES_FORMAT.md。运行时按以下顺序应用各阶段：

stripAnsi -> filterStderr -> replace -> matchOutput -> drop/include lines
  -> truncateLineAt -> head/tail/maxLines -> onEmpty

关键字段：

字段	用途
rules.stripAnsi	匹配前去除终端颜色/控制序列
rules.filterStderr	匹配/过滤前归一化常见 stderr 前缀
rules.replace	按顺序应用正则替换
rules.matchOutput	输出匹配已知条件时返回紧凑摘要
rules.matchOutput[].unless	存在错误/失败模式时跳过快捷摘要
rules.dropPatterns	删除噪音行
rules.includePatterns	保留可操作行
rules.collapsePatterns	折叠重复的匹配行
rules.deduplicate	过滤器级开关：折叠连续重复行
rules.truncateLineAt	每行 Unicode 安全截断
rules.onEmpty	全部行被过滤后的兜底消息
tests[]	供验证门禁使用的内联样例

内置过滤器要求附带内联 tests[] 样例；自定义过滤器（尤其跨项目共享的）也应包含。

六、行去重与行分组：两层独立机制

RTK 在两个独立层面折叠重复行：

1. 过滤器级 deduplicate（默认 false，opt-in）：过滤器设置 rules.deduplicate: true 后，会在截断之前折叠该过滤器匹配输出内的连续重复行，逻辑在 lineFilter.ts 内。对遗留过滤器，若定义了 collapsePatterns 则自动启用。schema 见 filterSchema.ts：deduplicate: z.boolean().default(false)。
2. 引擎级 deduplicateThreshold（默认 3）：所有过滤器执行完后，引擎对整体结果中连续 >= deduplicateThreshold 条完全相同的行做折叠（deduplicateRepeatedLines，实现在 deduplicator.ts，在引擎入口应用）。该值在归一化时被限定到 2–100。

过滤器级先运行（在过滤器内部），引擎级最后运行（作用于合并后的输出），两层叠加而不会重复计数。

行分组是去重的结构互补：rtkConfig.enableGrouping 为 true 时（默认 false），RTK 在去重结果之后追加一轮 groupSimilarLines 处理（实现于 grouper.ts），折叠近似等价（非字节级相同）的连续行；rtkConfig.groupingThreshold（默认 3）是触发分组的最小连续行数。去重处理完全相同的重复，分组处理"同形状但有小差异"的行。两个标志都随 rtkConfig JSON 持久化在 key_value 表中，重启后保留。

七、代码块注释剥离（stripCodeComments / preserveDocstrings）

启用 rtkConfig.applyToCodeBlocks 后，RTK 还可以剥离围栏代码块中的注释：

• stripCodeComments（默认 false，opt-in）：true 时移除 JavaScript/TypeScript 围栏块中的注释。该标志历史上只被读取但从未实际生效，因此默认值保持"保留"，避免生产环境的隐性变更；
• preserveDocstrings（默认 true）：剥离注释时保留 JSDoc//** … */ 块注释（其承载的 API 文档价值高于字节成本），设为 false 则一并剥离。

注释移除实现在 codeStripper.ts，使用 TypeScript 解析器而非正则，保证字符串、模板字符串、正则字面量不会被误认为注释；检测到 JSX 时整体放弃剥离，避免破坏 JSX 表达式容器内的注释。注释剥离目前仅适用于 JavaScript 与 TypeScript——CodeLanguage 集合中的其他语言（Python、Rust、Go、Ruby、Java）只有空行与空白折叠，没有注释移除。被处理的代码块会在 rulesApplied 中标记 rtk:code-strip。

注意 —— GCF/表格编码是另一个引擎：RTK 不包含 "GCF"（Graph Compact Format）表格/列式 JSON 编码器。该编码器（替代了更早的 omni-tabular 编码器）位于 headroom 引擎中（open-sse/services/compression/engines/headroom/，内嵌 codec 在 headroom/gcf/），与本文档描述的 RTK 过滤管线无关。

八、强度等级（Intensity）：压缩激进度与安全性的权衡

RTK 支持 3 档强度，通过引擎配置的 config.intensity 设置，在压缩激进度与安全性之间权衡：

等级	截断阈值	Token 节省	风险	适用场景
minimal	每节 24 行	~20-40%	极低	关键上下文的生产环境
standard	每节 24 行	~50-70%	低	日常编码会话
aggressive	每节 16 行	~70-90%	中	长会话、追求最大节省

截断阈值作用于 lineFilter.ts，aggressive 档把 head/tail 各保留 16 行，其余档为 24 行；每个 section 的头部和尾部都被保留，触发截断时丢弃的是中间内容。仓库中 DEFAULT_RTK_CONFIG 的初始强度为 minimal（见 types.ts 第 465 行起的定义），即出厂默认最保守，日常使用建议显式切到 standard。

不同强度下内容的保留策略：

内容	minimal	standard	aggressive
错误 / 堆栈跟踪	保留	保留	保留
测试失败	保留	保留	保留
构建错误	保留	保留	保留
测试通过（冗长）	保留	折叠	折叠
常规输出（info 日志）	折叠	折叠	丢弃
进度条	折叠	丢弃	丢弃
Banner / ASCII 艺术	折叠	丢弃	丢弃

按 combo 配置（combo config 中）：

{
  "combo": "my-coding-combo",
  "routing": {
    "/* ... */": null
  },
  "compression": {
    "engine": "rtk",
    "intensity": "aggressive"
  }
}

编程式配置：rtkEngine 是一个 CompressionEngine，没有 updateConfig 方法，需通过注册表助手更新引擎配置：

import { updateEngineConfig } from "@omniroute/open-sse/services/compression/engines/registry";

updateEngineConfig("rtk", { intensity: "aggressive" });

九、完整配置：rtkConfig 字段、默认值与持久化

全局设置通过 /api/settings/compression 提供，RTK 专属设置通过 /api/context/rtk/config 提供：

{
  "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 的完整类型由 types.ts 中的 RtkConfig / DEFAULT_RTK_CONFIG 定义。整个对象作为单个 JSON 值持久化在 SQLite key_value 表中（namespace = "compression"、key = "rtkConfig"，见 compression.ts 的写入分支），读取时经 normalizeRtkConfig 归一化——包括 enableGrouping、groupingThreshold、stripCodeComments、preserveDocstrings 在内的每个字段都经同一存储往返，重启后保留。

键	默认值	用途
deduplicateThreshold	3	引擎级：触发折叠的最小连续相同行数（限定 2–100）
enableGrouping	false	opt-in：折叠近似等价的连续行
groupingThreshold	3	触发分组的最小连续相似行数
stripCodeComments	false	opt-in：移除围栏代码块注释（需配合 applyToCodeBlocks）
preserveDocstrings	true	剥离注释时保留 JSDoc//** … */ 块

从 mergeRtkConfig（index.ts）的归一化逻辑还可以确认一些取值边界：rawOutputMaxBytes 下限 1024，maxLinesPerResult/maxCharsPerResult 下限 0 且取整，rawOutputMaxFiles 默认 100000、rawOutputMaxAgeDays 默认 30 等——这些隐藏字段同样参与配置往返。

十、API 路由与测试载荷

路由	方法	用途
/api/context/rtk/config	GET	读取 RTK 配置
/api/context/rtk/config	PUT	更新 RTK 配置
/api/context/rtk/filters	GET	列出过滤器目录与加载诊断
/api/context/rtk/import	POST	校验或安装 RTK TOML schema v1 文件
/api/context/rtk/test	POST	预览单条文本载荷的 RTK 压缩
/api/context/rtk/raw-output/[id]	GET	读取保留的已脱敏原始输出
/api/compression/preview	POST	预览任意压缩模式

管理路由需要仪表盘管理认证或匹配的 API-key 策略。

RTK 测试载荷示例：

{
  "command": "npm test",
  "text": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed",
  "config": {
    "intensity": "standard"
  }
}

压缩预览载荷示例：

{
  "mode": "stacked",
  "messages": [
    {
      "role": "tool",
      "content": "FAIL tests/example.test.ts\nAssertionError: expected true\nTest Files 1 failed"
    }
  ],
  "config": {
    "rtkConfig": {
      "rawOutputRetention": "failures"
    }
  }
}

TOML 校验载荷：

{
  "action": "validate",
  "content": "schema_version = 1\n\n[filters.my-tool]\nmatch_command = \"^my-tool\\\\b\"\nmax_lines = 20\n"
}

使用 "action": "install" 可安装已校验文件到全局；仅在审阅并确认替换既有全局文件后，才追加 "overwrite": true。

十一、原始输出恢复（Raw Output Recovery）

RTK 通常只返回压缩后文本。为调试目的，rawOutputRetention 可以保留脱敏后的原始输出：

取值	行为
never	不保留原始输出
failures	仅保留疑似失败的输出
always	保留每次压缩后的 RTK 原始输出（脱敏后）

保留文件写入 DATA_DIR/rtk/raw-output/。持久化前会进行密钥脱敏，涵盖常见 bearer token、API key、Slack token、AWS access key，以及 token=...、secret=...、password=... 形式的赋值。分析数据只存储指针 id、大小与哈希元数据。

流程示意：

Original output (10K tokens)
        │
        ▼
RTK compress (with rawOutput.enabled=true)
        │
        ├─▶ Compressed output (2K tokens)  ──▶ to LLM
        │
        └─▶ Original output (10K tokens)   ──▶ stored in DB
                                                  (linked by request_id)

编程式读取（pointerId 来自压缩后 CompressionStats.rtkRawOutputPointers[]）：

import { readRtkRawOutput } from "omniroute/compression/engines/rtk/rawOutput";

const raw = readRtkRawOutput(pointerId);
if (raw) {
  console.log("Original output:", raw);
}

函数签名见 rawOutput.ts；文档建议仅为调试会话或抽样审计启用原始输出，而不建议常驻开启（1MB 上限下 1000 请求/天约产生 50-500MB/天存储）。

十二、验证门禁（Verify Gate）与测试命令

RTK 的过滤器验证逻辑在 verify.ts 中：runRtkFilterTests() 加载全部过滤器（refresh: true），逐条执行 tests[]，对比期望输出，并按类别统计平均节省率，返回 passed、outcomes、filtersWithoutTests、benchmark 与 diagnostics。它验证以下不变量：

1. 每个过滤器加载并通过 schema 校验；
2. 每个 tests[] 条目产生期望输出；
3. minimal 强度基本无操作（仅应用结构化过滤，保留原文）；
4. aggressive 强度保留错误、测试失败与堆栈跟踪；
5. 压缩输出永不小于原始输入。

针对性验证门禁运行内置内联过滤器测试，不 shell out 到外部命令：

node --import tsx/esm --test tests/unit/compression/rtk-verify.test.ts

更完整的 RTK 门禁：

node --import tsx/esm --test \
  tests/unit/compression/rtk-*.test.ts \
  tests/unit/compression/pipeline-integration.test.ts \
  tests/unit/compression/context-compression-api.test.ts

发布前运行广义压缩门禁：

node --import tsx/esm --test \
  tests/unit/compression/*.test.ts \
  tests/golden-set/*.test.ts \
  tests/integration/compression-pipeline.test.ts \
  tests/unit/api/compression/compression-api.test.ts

仓库中 tests/unit/compression/ 下有 30 余个 RTK 相关测试文件，覆盖强度行为（rtk-intensity）、去重（rtk-deduplicator、rtk-filter-deduplicate）、分组（rtk-grouping）、注释剥离（rtk-strip-comments）、原始输出保留（rtk-raw-output-retention）、TOML 兼容（rtk-toml-compatibility）、REDoS 防护（rtk-filter-redos-guard、rtk-discover-redos）、Anthropic tool_result 处理与 cache_control 保留（rtk-anthropic-tool-result、rtk-cache-control-preserve）等。编程式调用示例：

import { runRtkFilterTests } from "open-sse/services/compression/engines/rtk/verify";

const result = runRtkFilterTests();
console.log(`Passed: ${result.outcomes.filter((o) => o.passed).length}`);
console.log(`Failed: ${result.outcomes.filter((o) => !o.passed).length}`);
if (!result.passed) {
  result.outcomes
    .filter((o) => !o.passed)
    .forEach((o) =>
      console.error(`  - ${o.filterId} / ${o.testName}: expected "${o.expected}", got "${o.actual}"`)
    );
}

建议在以下时点运行：合并过滤器变更之前（确保测试通过）、升级 RTK 引擎之后（schema 可能变化）、监控中周期性运行（防 fixture 漂移）、新增工具/命令族时（证明新过滤器有效）。

十三、自定义过滤器开发

engines/rtk/filters/ 目录包含 55 个内置过滤 JSON 文件，你可以为自己的工具添加过滤器。过滤器 schema（Zod 校验）结构如下：

{
  "id": "string",                      // 必填。过滤器标识（kebab-case，如 "python-traceback"）
  "label": "string",                   // 必填。人类可读名称
  "description": "string",             // 可选（默认 ""）。过滤器用途简述
  "category": "git|test|build|shell|docker|package|infra|cloud|generic",
  "priority": number,                  // 可选（0-100，默认 50）。执行顺序（越大越先）
  "match": {
    "commands": ["string"],            // 要匹配的命令名（如 "python"、"pytest"）
    "patterns": ["string"],            // 匹配输出的正则
    "outputTypes": ["string"]          // 检测到的输出类别（如 "test-failure"）
  },
  "rules": {
    "stripAnsi": boolean,              // 可选（默认 false）。剥离 ANSI 颜色码
    "replace": [
      { "pattern": "regex", "replacement": "..." }
    ],
    "matchOutput": [                   // 匹配时短路（默认 []）
      { "pattern": "regex", "message": "short summary", "unless": "regex" }
    ],
    "includePatterns": ["string"],     // 要保留的行（正则，默认 []）
    "dropPatterns": ["string"],        // 要丢弃的行（正则，默认 []）
    "collapsePatterns": ["string"],    // 折叠为单次出现的行（默认 []）
    "deduplicate": boolean,            // 可选（默认 false）。去除重复行
    "truncateLineAt": number,          // 可选（默认 0）。按最大字符数截断行
    "maxLines": number,                // 可选（默认 0）。总行数硬上限
    "headLines": number,               // 可选（默认 20）。保留匹配输出的前 N 行
    "tailLines": number,               // 可选（默认 20）。保留匹配输出的后 N 行
    "onEmpty": "string",               // 可选（默认 ""）。全部行被过滤后的兜底消息
    "filterStderr": boolean            // 可选（默认 false）。同时过滤 stderr 输出
  },
  "preserve": {
    "errorPatterns": ["string"],       // 必须始终保留的模式（默认 []）
    "summaryPatterns": ["string"]      // 最终汇总行模式（默认 []）
  },
  "tests": [                           // 验证用内联测试（默认 []）
    {
      "name": "string",               // 必填。测试名
      "input": "sample output",        // 必填。样例输入
      "expected": "expected output",   // 必填。期望压缩输出
      "command": "optional command"    // 可选。命令上下文
    }
  ]
}

完整示例：Python Traceback 过滤器

{
  "id": "python-traceback",
  "label": "Python Traceback Filter",
  "description": "Compresses Python tracebacks to essential file/line locations and error type",
  "category": "test",
  "priority": 60,
  "match": {
    "commands": ["python", "python3", "pytest", "uv", "poetry"],
    "patterns": ["Traceback \\(most recent call last\\)", "Error", "Exception"],
    "outputTypes": ["error-traceback"]
  },
  "rules": {
    "stripAnsi": true,
    "includePatterns": [
      "Traceback \\(most recent call last\\)",
      "^\\s*File \".+\", line \\d+",
      "^\\s*[A-Z][a-zA-Z]+Error:",
      "^\\s*[A-Z][a-zA-Z]+Exception"
    ],
    "dropPatterns": ["site-packages/", "^\\s+[a-z_]+\\([^)]*\\)$"],
    "headLines": 5,
    "tailLines": 3,
    "maxLines": 25,
    "filterStderr": true
  },
  "preserve": {
    "errorPatterns": ["Error:", "Exception:", "Traceback"],
    "summaryPatterns": ["^[A-Z][a-zA-Z]+(?:Error|Exception):"]
  },
  "tests": [
    {
      "name": "preserves-error-type-and-location",
      "input": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n    do_thing()\n  File \"lib/utils.py\", line 17, in helper\n    return 1 / 0\nZeroDivisionError: division by zero",
      "expected": "Traceback (most recent call last):\n  File \"app.py\", line 42, in main\n  File \"lib/utils.py\", line 17, in helper\nZeroDivisionError: division by zero",
      "command": "python app.py"
    }
  ]
}

加载位置与校验

将文件放入受识别的位置：

~/.omniroute/rtk/filters/my-filter.json     # 用户级
<project>/.rtk/filters/my-filter.json      # 项目级

过滤器在启动时由 filterLoader.ts 的 loadRtkFilters() 自动加载，发现来源依次为内置目录、用户目录、项目目录。编程加载：

import { loadRtkFilters } from "@omniroute/open-sse/services/compression/engines/rtk/filterLoader";

// 选项：customFiltersEnabled（加载用户/项目过滤器，默认开）、trustProjectFilters、refresh
const filters = loadRtkFilters({ customFiltersEnabled: true });

过滤器加载时按 Zod schema 校验；结构不合法的过滤器加载失败并记录错误（如 rules.replace.0.pattern: Invalid regex）。用 runRtkFilterTests() 可校验所有已安装过滤器。

最佳实践

1. 始终包含 tests[] —— 证明过滤器有效并防止回归；
2. 用 matchOutput 做短路 —— 如果一行就能讲清楚，就替换整个块；
3. 优先"保留"而非"删除" —— 显式的"始终保留"规则比"始终删除"更安全；
4. 在 3 档强度下都测试 —— minimal 应近似无操作，aggressive 仍须保留错误；
5. 善用 unless 字段 —— 为短路摘要加"存在 X 时不触发"的保护。

十四、扩展 RTK 的完整流程

1. 新增或更新一个过滤器 JSON 文件；
2. 至少包含一个 tests[] 样例，证明关键行为；
3. 新命令族在 tests/unit/compression/fixtures/rtk/ 下添加 fixture；
4. 引入新输出类别时补充命令检测覆盖；
5. 运行验证门禁与广义 RTK 门禁；
6. 若过滤器仅限项目内使用，在审阅之后提交 .rtk/filters.json 并刷新 .rtk/trust.json。

RTK 引擎源码位于 open-sse/services/compression/engines/rtk/（63 个文件，约 70KB），核心模块一览：index.ts（引擎入口与配置合并）、commandDetector.ts（命令分类）、filterLoader.ts（三层加载与信任校验）、filterSchema.ts（Zod schema）、lineFilter.ts（行级 DSL 执行）、deduplicator.ts/grouper.ts（去重与分组）、codeStripper.ts（TS 解析器注释剥离）、tomlCompatibility.ts（TOML v1 解析）、rawOutput.ts（原始输出保留）、verify.ts（验证门禁）。

延伸阅读：

• COMPRESSION_GUIDE.md —— 完整压缩管线总览
• COMPRESSION_ENGINES.md —— 引擎注册表与内置引擎
• EXTENDING_COMPRESSION.md —— 自定义引擎、语言包、叠加管线
• COMPRESSION_RULES_FORMAT.md —— 过滤器 JSON schema 详解