RTK 系统架构设计解析：零开销 CLI 代理的过滤器扩展决策框架

本篇基于 RTK 仓库中为贡献者定义的系统架构师角色规范（.claude/agents/system-architect.md），系统讲解 RTK（Rust Token Killer）的架构决策框架：从"零开销 CLI 代理"的四维评估准则、Commands 枚举路由的模块地图，到新增过滤器模块、子枚举命令族、TOML 过滤 DSL、共享工具层等四大设计模式，并结合 src/ 源码与构建配置逐条印证其性能预算（<10ms 启动、<5MB 二进制）如何落实到工程约束中。读完本文，你能够掌握在 RTK 中新增一个过滤模块的完整决策流程、TOML 与 Rust 实现的取舍标准，以及各模块的职责边界。

一、架构决策的触发场景与评估准则

RTK 项目为"系统架构师"角色（由 system-architect.md 定义，指定 sonnet 模型、配备 Read/Grep/Glob/Write/Bash 工具）明确了六类必须介入的触发场景：

• 新增命令族（command family）或过滤器模块；
• 架构模式变更（引入新抽象、共享工具）；
• 性能约束分析（启动时间、内存、二进制体积）；
• 横切功能设计（配置系统、TOML DSL、token 跟踪）；
• 可能影响启动时间的新依赖引入；
• 模块边界重定义或重构。

文档确立了 RTK 的核心定位——零开销 CLI 代理（zero-overhead CLI proxy），并规定每一个架构决策都必须对照四个维度评估：

1. 启动时间：这个变更是否增加 <10ms 的启动预算开销？
2. 可维护性：贡献者能否在不理解整个代码库的前提下添加新过滤器？
3. 可靠性：如果该组件失败，用户是否仍能得到命令的原始输出？
4. 可组合性：这套设计能否在不做结构性修改的情况下扩展到 50+ 过滤器模块？

文档还强调了一条思维准则："以过滤器家族（filter families）而非单个命令来思考"——每个新的 *_cmd.rs 都必须落入同一个模式，保证结构同构。这一准则在仓库中可以得到直接印证：src/main.rs 中用 clap derive 定义的 Commands 枚举已有 50 多个变体（Git、Cargo、Gh、Grep/Rg、Go、Ruff、Pytest、Phpunit、Mvn、Sbt 等），每个变体都路由到 cmds/<ecosystem>/*_cmd.rs 中的统一入口函数，且绝大多数入口共享相同的"执行 → 过滤 → 跟踪 → 退出码传播"骨架，正是"同一模式"的规模化体现。

二、RTK 架构地图：Commands 枚举与四层模块结构

文档给出的架构地图是理解 RTK 全局结构的最佳入口：

src/main.rs
├── Commands enum (clap derive)
│   ├── Git(GitArgs)      → cmds/git/git.rs
│   ├── Cargo(CargoArgs)  → cmds/rust/runner.rs
│   ├── Gh(GhArgs)        → cmds/git/gh_cmd.rs
│   ├── Grep(GrepArgs)    → cmds/system/grep_cmd.rs
│   ├── ...               → cmds/<ecosystem>/*_cmd.rs
│   ├── Gain              → analytics/gain.rs
│   └── Proxy(ProxyArgs)  → passthrough
│
├── core/
│   ├── tracking.rs       ← SQLite, token metrics, 90-day retention
│   ├── config.rs         ← ~/.config/rtk/config.toml
│   ├── tee.rs            ← Raw output recovery on failure
│   ├── filter.rs         ← Language-aware code filtering
│   └── utils.rs          ← strip_ansi, truncate, execute_command
├── hooks/                ← init, rewrite, verify, trust, integrity
└── analytics/            ← gain, cc_economics, ccusage, session_cmd

结合当前源码，这张地图的实际落地情况是：

• 路由层：src/main.rs 顶部 use cmds::cloud::... 等 import 块覆盖了 git、rust、js、python、go、php、ruby、jvm、scala、dotnet、system、cloud 等全部生态目录；Cli 结构体除 command: Commands 外还定义了三个全局标志：verbose（-v/-vv/-vvv 计数）、ultra_compact（超紧凑输出模式）和 skip_env（为子进程注入 SKIP_ENV_VALIDATION=1）。这些全局标志贯穿所有过滤模块，是"可组合性"的具体表现。
• core/ 层：从源码结构看，core 是一个"叶子模块"——被所有其他组件消费，但不反向依赖任何具体命令模块。src/core/README.md 明确规定其职责范围：配置加载、token 跟踪持久化、TOML 过滤引擎、tee 原始输出恢复、显示格式化、遥测与共享工具；而命令特定的过滤逻辑归 cmds/，钩子生命周期归 src/hooks/，分析面板归 analytics/。
• 关键基础设施逐一对应：src/core/tracking.rs 确实实现了基于 SQLite（~/.local/share/rtk/tracking.db）的 token 节省度量与 90 天自动清理（保留期常量 DEFAULT_HISTORY_DAYS = 90 定义于 src/core/constants.rs）；src/core/config.rs 定义了包含 tracking、display、filters、tee、telemetry、hooks、limits 七个配置段的结构体，从 ~/.config/rtk/config.toml 读取；src/core/tee.rs 在过滤失败时保留原始输出供 LLM 恢复；src/core/filter.rs 提供语言感知的代码过滤。

值得注意的是，文档地图中 Grep → cmds/system/grep_cmd.rs 的写法与当前实现略有演进：从 src/main.rs 的 Grep/Rg 变体注释可见，rtk grep 与 rtk rg 现已共享 src/cmds/system/search.rs 这一底层过滤器，并且 rtk 自有的短选项会刻意避开（如不占用 -l、-m、-t），以免截获原生 grep/rg 的同名参数——这是一个典型的"路由层细节必须与过滤层协同"的架构决策实例。

三、模式一：新增过滤器模块的标准骨架

文档给出所有 *_cmd.rs 必须遵循的标准结构：

// Standard structure for *_cmd.rs
pub struct NewArgs {
    // clap derive fields
}

pub fn run(args: NewArgs) -> Result<()> {
    let output = execute_command("cmd", &args.to_cmd_args())
        .context("Failed to execute cmd")?;

    // Filter
    let filtered = filter_output(&output.stdout)
        .unwrap_or_else(|e| {
            eprintln!("rtk: filter warning: {}", e);
            output.stdout.clone() // Fallback: passthrough
        });

    // Track
    tracking::record("cmd", &output.stdout, &filtered)?;

    print!("{}", filtered);

    // Propagate exit code
    if !output.status.success() {
        std::process::exit(output.status.code().unwrap_or(1));
    }
    Ok(())
}

这个骨架浓缩了 RTK 的三条可靠性设计原则：

1. Fail-safe 回退：过滤失败时打印警告并直通原始输出，绝不让用户丢失命令结果；
2. 必达跟踪：无论成败都要记录 token 指标；
3. 退出码保真：底层工具的非零退出码必须原样传播（git 的 128、linter 的 1），这对 CI/CD 管线判定成败至关重要。

从源码结构看，这一骨架在当前实现中已进一步收敛为共享的 runner 抽象。以 src/cmds/go/go_cmd.rs 为例，其 run_test 导入并使用 crate::core::runner::run_filtered、crate::core::stream::exec_capture，以及 crate::core::guard::never_worse 守卫——即"过滤结果永远不会比原始输出更差"这一 fail-safe 原则被提取为 core/guard.rs 中的通用契约。src/core/README.md 还定义了消费方契约：TimedExecution 的 timer.track() 必须在所有代码路径（成功、失败、回退）上调用，因为在 track() 之前执行 std::process::exit() 会丢失指标；解析结构化输出的消费方应在退出前调用 tee::tee_and_hint() 保存原始输出。这些契约正是文档"Pattern 1"骨架的工程化升级。

四、模式二：命令族的子枚举（Sub-Enum）

当目标工具拥有多个输出格式各异的子命令时（如 go test、go build、go vet），文档推荐使用子枚举而非扁平参数：

// Like Go, Cargo subcommands
#[derive(Subcommand)]
pub enum GoSubcommand {
    Test(GoTestArgs),
    Build(GoBuildArgs),
    Vet(GoVetArgs),
}

文档给出了三条明确的判定标准——满足其一即应考虑子枚举：

• 3 个及以上输出格式不同的子命令；
• 每个子命令需要独立的过滤逻辑；
• 输出格式在结构上不同（NDJSON vs 纯文本 vs JSON）。

仓库中的实际案例与文档描述一致：src/cmds/go/go_cmd.rs 以 GoCommands 子枚举路由到 run_test/run_build/run_vet，其中 go test 走 NDJSON 流式解析（逐行解析 go test -json 的交错包事件，聚合成 "2 packages, 3 failures" 式摘要），go build/go vet 走文本过滤（仅保留 file:line:message 诊断）。src/main.rs 中同样采用子枚举的还有 GitCommands（diff/log/status/add/commit/push 等十余个变体）、PnpmCommands、DotnetCommands、DockerCommands、KubectlCommands、PrismaCommands 等；src/cmds/rust/cargo_cmd.rs 与 src/cmds/dotnet/dotnet_cmd.rs 亦各自维护子命令路由。第三方的 golangci-lint 则被刻意保持为独立命令（第三方工具、JSON API 输出、独立使用场景），这一取舍逻辑在 docs/contributing/ARCHITECTURE.md 中有专门论证。

五、模式三：TOML 过滤 DSL——免 Rust 代码的轻量扩展

对于简单的输出变换，文档推荐使用 TOML DSL 而非完整的 Rust 模块。文档给出的示意配置（v0.25.0+）：

# .rtk/filters/my-cmd.toml
[filter]
command = "my-cmd"
strip_lines_matching = ["^Verbose:", "^Debug:"]
keep_lines_matching = ["^error", "^warning"]
max_lines = 50

文档规定的选择准则是：

• 用 TOML DSL：简单的 grep/strip 型变换；
• 用 Rust 模块：复杂解析、结构化输出（JSON/NDJSON）、token 节省率 >80% 的场景。

当前实现中，TOML 引擎位于 src/core/toml_filter.rs，其模块注释给出了比文档示意更完整的真实约束：

三层查找优先级（首个命中生效）：

1. .rtk/filters.toml — 项目本地，可随仓库提交（需要 rtk trust 信任）；
2. ~/.config/rtk/filters.toml — 用户全局，作用于所有项目；
3. 内置 TOML — src/filters/ 目录下的 60 多个 *.toml 文件，由 build.rs 在编译期拼接并以 include_str! 嵌入二进制；
4. 无匹配则直通（passthrough），由调用方处理。

八阶段流水线（按序应用）：strip_ansi → replace（逐行可链式正则替换，支持 $1 反向引用）→ match_output（整块匹配即短路返回消息，unless 字段防止吞掉错误输出）→ strip_lines_matching/keep_lines_matching → truncate_lines_at（逐行截断，unicode 安全）→ head_lines/tail_lines → max_lines（绝对行数上限）→ on_empty（结果为空时返回兜底消息）。调试可用环境变量 RTK_NO_TOML=1 整体绕过、RTK_TOML_DEBUG=1 打印命中的过滤器与行数统计。

一个真实的内置过滤器 src/filters/jq.toml 展示了当前 schema 的完整写法（注意实际字段名是 match_command 与 [filters.<name>] 段，且所有字段受 deny_unknown_fields 严格校验）：

[filters.jq]
description = "Compact jq output — truncate large JSON results"
match_command = "^jq\\b"
strip_ansi = true
strip_lines_matching = [
  "^\\s*$",
]
max_lines = 40
truncate_lines_at = 120

[[tests.jq]]
name = "short output passes through"
input = """
{
  "name": "test",
  "version": "1.0"
}
"""
expected = "{\n  \"name\": \"test\",\n  \"version\": \"1.0\"\n}"

这里值得强调的是 [[tests.<name>]] 内联测试机制：每个 TOML 过滤器都随附输入/期望输出用例，可由 rtk verify 命令统一执行（rtk verify --require-all 是 CI 模式，要求所有过滤器都有内联测试）。这让"轻量扩展"不牺牲正确性——新增一条 TOML 规则等于新增一组可回归测试，与 src/core/README.md 的三层查找契约、src/hooks/verify_cmd.rs 的验证实现相衔接。

六、模式四：共享工具层——"绝不重复实现"

文档 Pattern 4 要求：在模块中新增代码前，先检查 src/core/utils.rs 是否已有现成工具：

• strip_ansi(s: &str) -> String — ANSI 转义码剥离；
• truncate(s: &str, max: usize) -> String — 字符串截断（超出时追加 ...）；
• execute_command(cmd, args) -> Result<Output> — 命令执行；
• 包管理器检测（pnpm/yarn/npm/npx）。

"Never re-implement these in individual modules" 是硬性规定。源码层面可以验证这些工具确实存在并被广泛复用：src/core/utils.rs 中的 strip_ansi 用 LazyLock<Regex> 缓存了 ANSI 正则（\x1b\[[0-9;]*[a-zA-Z]），truncate 以字符计数而非字节计数保证多语言安全；此外还包含文档未列出的防御性工具，如 strip_leading_bom（剥离人类/编辑器写入 JSON 时可能携带的重复 UTF-8 BOM）与 format_tokens（K/M 后缀格式化）。src/core/README.md 的工具清单还列出了 resolved_command(name)（PATH 解析）、tool_exists(name)、detect_package_manager() / package_manager_exec(tool)（按 pnpm-lock.yaml → yarn.lock → npx 顺序检测）、ruby_exec(tool)（存在 Gemfile 时自动加 bundle exec）、count_tokens(text)（按 ceil(chars / 4.0) 估算 token，与跟踪数据库的估算口径一致）。

包管理器检测之所以被提升为"关键基础设施"，是因为它同时解决了 CWD 保持、monorepo 嵌套 package.json、免全局安装与 CI 一致性四个问题，并影响 lint、tsc、next、prettier、playwright、prisma、vitest 等全部 JS/TS 模块。

七、模块边界、性能预算与可扩展性

模块边界

文档以单行清单形式划定了四个关键模块的职责边界：

模块	边界约定
每个 *_cmd.rs	一个命令族、一个过滤关注点
utils.rs	仅共享助手，禁止业务逻辑
tracking.rs	仅指标，禁止过滤逻辑
config.rs	仅配置读写，禁止过滤逻辑

这与 src/core/README.md 对 core 的"叶子模块"定位一致：core 不得引用任何具体命令名、钩子或 agent；任何出现 "git"、"cargo"、"claude" 字样的模块都不属于 core。

性能预算

文档给出四项硬性预算：

• 二进制体积：<5MB（stripped）；
• 启动时间：<10ms（命令执行前不做任何 I/O）；
• 内存：<5MB 常驻；
• 禁用异步运行时（tokio 会带来 5-10ms 启动开销）。

这些预算在仓库中有三重证据支撑：

1. Cargo.toml 的 release profile 精确对应了体积/启动优化：opt-level = 3、lto = true、codegen-units = 1、panic = "abort"、strip = true；且整个依赖列表（clap、anyhow、rusqlite bundled、regex、serde、toml 等）中没有 tokio 或任何异步运行时，与"no async runtime"约束直接吻合。同时 [lints.rust] 将 unsafe_code = "deny"、warnings = "deny"，把可靠性约束固化到编译门禁。
2. docs/contributing/ARCHITECTURE.md 给出的实测参考值：stripped release 二进制约 4.1MB、冷启动约 5-10ms、典型内存 2-5MB，代理开销约 +5~20ms/命令（Clap 解析 ~2-3ms、SQLite 跟踪 ~1-3ms、过滤 2-8ms），与预算留有安全余量。
3. 依赖选型本身即架构决策：SQLite 采用 rusqlite 的 bundled feature 以保证单二进制零外部依赖；HTTP 仅用同步的 ureq；无异步框架，全进程单线程执行（tracking 使用 Mutex<Option<Tracker>> 仅作未来预留）。

可扩展性

文档要求：新增第 N+1 个过滤器不得改动既有模块；新命令族只需加入 Commands 枚举而不触发架构变更；简单场景由 TOML DSL 承接而不需要 Rust 代码。当前 src/filters/ 下 60+ 内置 TOML 过滤器（make、terraform-plan、shellcheck、xcodebuild 等）与 src/main.rs 中 50+ 命令变体并存，正是这三条可扩展性承诺的既成事实。

八、架构师的工作流：关键动作、交付物与职责边界

文档定义了架构师介入后的五步动作流：

1. 分析影响：这个变更触及哪些模块？涟漪效应是什么？
2. 评估性能：是否增加启动开销、新 I/O、新分配？
3. 界定边界：该模块的责任在哪里终止？
4. 记录权衡：TOML DSL vs Rust 模块？子枚举 vs 扁平参数？
5. 指导实现：提供结构性骨架，而非完整实现。

对应的交付物形态包括：架构决策（模块落点、接口设计、责任边界）、结构骨架（pub fn run() 签名、枚举变体、类型定义）、权衡分析、性能评估（启动/内存/体积影响）、以及针对既有模块重构的分步迁移路径。

职责边界（Will / Will not）同样被显式写出：

• 会做：设计过滤器模块结构与接口；评估架构选择的性能权衡；定义模块边界与共享工具契约；为新过滤器推荐 TOML 还是 Rust 方案；设计横切功能（新配置字段、跟踪指标）。
• 不做：实现完整过滤逻辑（交给 rust-rtk 实现类 agent）、编写具体正则模式（属实现细节）、决定 token 节省目标（已固定为 ≥60%）、突破 <10ms 启动约束（不可谈判）。

这种"决策者不写实现、实现者不改架构"的分工，配合 src/core/README.md 中的消费方契约（track() 全路径调用、tee 先于退出），共同保证了 RTK 在模块数量持续增长时架构不变形。

九、扩展决策速查表

综合文档四个模式与仓库证据，RTK 中新增一条输出压缩能力的决策路径可以浓缩为：

决策点	选择标准	落点
输出变换复杂度	简单 strip/keep/截断 → TOML；复杂解析、JSON/NDJSON、节省 >80% → Rust	src/filters/ 加 .toml（含 [[tests.*]] 内联测试）vs 新建 cmds/<eco>/<name>_cmd.rs
子命令数量	≥3 个子命令且输出格式结构不同 → 子枚举	Commands::<Family> 内嵌 #[derive(Subcommand)] 枚举，参照 src/cmds/go/go_cmd.rs
工具复用	截断/ANSI/执行/包管理器 → 一律用 core	src/core/utils.rs，禁止模块内重写
失败路径	过滤失败必须回退原始输出	unwrap_or_else 直通 + guard::never_worse + tee 留存
指标与退出码	所有路径必记录、退出码原样传播	TimedExecution::track() + exit(status.code())
性能门禁	不得突破 <10ms 启动、<5MB 二进制、零异步	Cargo.toml release profile 与依赖清单

结语

.claude/agents/system-architect.md 的价值在于把 RTK 的架构约束从隐性知识变成了可执行的决策协议：四维评估准则保证每个变更先过"零开销"体检，四大模式（模块骨架、子枚举、TOML DSL、共享工具）覆盖全部扩展形态，性能预算与模块边界则以 Cargo.toml 的构建门禁、core 叶子模块契约和 60+ 内置过滤器为现实注脚。对贡献者而言，遵循这套框架新增一个过滤器，就是在 Commands 枚举加一个变体、按骨架实现 run()、复用 core 工具、并用内联测试或单元测试守住正确性——而不需要重新思考架构。