rtk 的 Rust 设计模式手册：Newtype、Builder、状态机如何支撑 CLI 过滤模块架构

rtk（Rust Token Killer）是一个用单个 Rust 二进制实现的 CLI 代理，通过过滤、压缩和去重常见开发命令的输出，将其送入 LLM 上下文前裁剪 60–90% 的 bash 输出。本篇技术指南以仓库内置的 design-patterns SKILL 文档 为主体，系统讲解 Newtype、Builder、状态机、Trait Object、RAII、Strategy、Extension Trait 七种设计模式在 rtk 过滤模块架构中的适用边界与选型依据，并结合 pytest 输出解析、运行骨架、tee 原始输出恢复 等真实源码印证每种模式在实际代码中的落地形态，帮助你在为 rtk 设计新过滤模块或重构现有模块时做出与设计文档一致的取舍决策。

背景：命令代理架构决定了模式的选择方向

理解这些模式之前，先明确 rtk 的架构约束。CLAUDE.md 描述了 command proxy architecture：src/main.rs 通过 Clap 的 Commands enum 将 CLI 命令路由到 src/cmds/*/ 下的专用过滤模块，每个模块负责执行底层命令并压缩其输出，token 节省量由 SQLite 记录。src/main.rs 顶部可以看到这种路由的组织方式——各生态的命令模块被集中 re-export 供路由使用，例如 cmds::python::{mypy_cmd, pip_cmd, pytest_cmd, ruff_cmd, uv_cmd}、cmds::git::{diff_cmd, gh_cmd, git, ...}。

rtk 的性能与可靠性目标（启动 <10ms、<5MB 内存、同步单线程）直接决定了设计模式的使用原则：优先零开销的静态方案，拒绝为假想的未来需求过度抽象。.claude/rules/rust-patterns.md 将“禁止 async、生产代码禁止 unwrap、过滤失败必须回退到原始输出”列为不可协商的规则，本文各模式均在此约束下展开。

模式一：Newtype（类型安全）

适用场景：用类型包装原始类型以防止误用——命令名、路径、token 数等。

核心动机是消除“位置参数互换”这类静默 bug。文档给出了经典对比：

// 无 Newtype —— 参数很容易互换
fn track(input_tokens: usize, output_tokens: usize) { ... }
track(output_tokens, input_tokens);  // 静默 bug！

// 有 Newtype —— 互换会在编译期报错
pub struct InputTokens(pub usize);
pub struct OutputTokens(pub usize);
fn track(input: InputTokens, output: OutputTokens) { ... }
track(OutputTokens(100), InputTokens(400));  // 编译错误

Newtype 的第二个价值是构造时验证。文档给出的 RTK 实例是命令名校验——这是 rtk 的核心安全点，因为命令名最终会被拼进子进程调用：

// 实用 RTK 示例：命令名校验
pub struct CommandName(String);
impl CommandName {
    pub fn new(s: &str) -> Result<Self> {
        if s.contains(';') || s.contains('|') || s.contains('`') {
            anyhow::bail!("Invalid command name: shell metacharacters");
        }
        Ok(Self(s.to_string()))
    }
    pub fn as_str(&self) -> &str { &self.0 }
}

这个 CommandName 示例与 .claude/rules/rust-patterns.md 中“Newtype for validation”一节完全一致，是仓库自动加载进上下文的项目规范。注意它与 RTK 错误处理规范的配合：失败路径用 anyhow::bail! 携带明确描述，而非 panic，符合“无 unwrap + 始终 context”的仓库铁律。

选型提示：当你要为一个字符串类型新增“这个值已经被验证过”的语义时，选 Newtype 而不是裸 String（见文末选型表）。

模式二：Builder（复杂配置）

适用场景：一个结构体有 4 个以上可选字段，且大量字段带默认值。

#[derive(Default)]
pub struct FilterConfig {
    max_lines: Option<usize>,
    strip_ansi: bool,
    show_warnings: bool,
    truncate_at: Option<usize>,
}

impl FilterConfig {
    pub fn new() -> Self { Self::default() }
    pub fn max_lines(mut self, n: usize) -> Self { self.max_lines = Some(n); self }
    pub fn strip_ansi(mut self, v: bool) -> Self { self.strip_ansi = v; self }
    pub fn show_warnings(mut self, v: bool) -> Self { self.show_warnings = v; self }
}

// 使用 —— 可读性好，无位置参数混淆
let config = FilterConfig::new()
    .max_lines(50)
    .strip_ansi(true)
    .show_warnings(false);

何时不用 Builder：结构体只有 1–3 个语义明确的字段时，Builder 属于过度设计，直接用结构体字面量即可。

Builder 模式在 rtk 源码中已有真实落地。src/core/runner.rs 中的 RunOptions 就是典型的消费端 Builder：

#[derive(Default)]
pub struct RunOptions<'a> {
    pub tee_label: Option<&'a str>,
    pub filter_stdout_only: bool,
    pub skip_filter_on_failure: bool,
    pub no_trailing_newline: bool,
    pub inherit_stdin: bool,
}

impl<'a> RunOptions<'a> {
    pub fn stdout_only() -> Self { ... }
    pub fn tee(mut self, label: &'a str) -> Self { ... }
    pub fn inherit_stdin(mut self) -> Self { ... }
    // ...
}

过滤模块以链式调用组合行为，例如 src/cmds/python/pytest_cmd.rs 中 runner::run_filtered_with_exit(cmd, "pytest", &args.join(" "), ..., runner::RunOptions::stdout_only().tee("pytest"))——stdout_only() 与 tee("pytest") 两个链式方法清晰地表达了“只过滤 stdout，并启用以 pytest 为标签的原始输出落盘”。这正是文档所说“4+ 可选字段、大量默认值”场景的标准解法。

模式三：状态机（解析器/过滤器流程）

适用场景：解析多段式输出（测试结果、构建输出），且上下文会改变行为——某一行该如何处理，取决于“现在处于输出的哪一段”。

文档以 pytest 输出解析为例：

// RTK 示例：pytest 输出解析
#[derive(Debug, PartialEq)]
enum ParseState {
    LookingForTests,
    InTestOutput,
    InFailureSummary,
    Done,
}

fn parse_pytest(input: &str) -> String {
    let mut state = ParseState::LookingForTests;
    let mut failures = Vec::new();

    for line in input.lines() {
        match state {
            ParseState::LookingForTests => {
                if line.contains("FAILED") || line.contains("ERROR") {
                    state = ParseState::InFailureSummary;
                    failures.push(line);
                }
            }
            ParseState::InFailureSummary => {
                if line.starts_with("=====") { state = ParseState::Done; }
                else { failures.push(line); }
            }
            ParseState::Done => break,
            _ => {}
        }
    }
    failures.join("\n")
}

这个模式不是纸面示例——它已在 rtk 源码中大规模应用。src/cmds/python/pytest_cmd.rs 的真实实现定义了四态解析状态机：

#[derive(Debug, PartialEq)]
enum ParseState {
    Header,
    TestProgress,
    Failures,
    Summary,
}

filter_pytest_output 逐行扫描输出，依据 === 分隔线中出现的关键词（FAILURES、short test summary、passed/failed/skipped）驱动状态迁移，把冗长的 pytest 原始输出压缩为“失败详情 + 摘要行”。同类实现还有：

• src/cmds/git/git.rs 中的 GitStatusState（Rebase / MergeConflicts / CherryPick / Bisect / Am / SparseCheckout 等 8 个变体），配合 detect_status_state 识别 git status 输出中的进行中操作，将多行状态提示压缩为一行摘要（如 “merge in progress. unresolved conflicts”）；
• src/cmds/ruby/rake_cmd.rs 与 src/cmds/ruby/rspec_cmd.rs 中同样以 ParseState/State enum 解析 Ruby 生态的多段式构建与测试输出。

选型提示：多阶段输出解析一律用状态机，避免嵌套 if/else 随段落数指数级膨胀。

模式四：Trait Object（命令分发）

适用场景：不同命令族需要同一接口，可以避免巨大的 match 分支。

// 为过滤器定义统一接口
pub trait OutputFilter {
    fn filter(&self, input: &str) -> Result<String>;
    fn command_name(&self) -> &str;
}

pub struct GitFilter;
pub struct CargoFilter;

impl OutputFilter for GitFilter {
    fn filter(&self, input: &str) -> Result<String> { filter_git(input) }
    fn command_name(&self) -> &str { "git" }
}

// RTK 目前使用 main.rs 中的 match 分发（更简单，无动态分发开销）
// Trait object 在过滤器注册表变为动态时有用（例如 TOML 加载插件）

文档在此给出了一个关键的反向决策：rtk 当前的 match 分发是有意为之——静态分发、零开销、易于追踪。只有当 match 分支数量超过约 20 个命令，且注册表需要动态化（如从 TOML 文件加载过滤规则）时，才值得迁移到 trait object。

这个判断与仓库现状相互印证：一方面，src/main.rs 的 Clap enum 路由是静态的；另一方面，src/filters/ 目录下已存在大量 TOML 声明式过滤规则（cargo.toml、git.toml、make.toml 等），说明“动态过滤注册”这条演进路线已经在用数据驱动而非 trait object 的方式实现——从源码结构看，rtk 用“TOML 规则文件 + 静态代码”的组合替代了全局 trait 注册表，这与其“拒绝全局状态”的反模式立场（见下文）是一致的。

模式五：RAII（资源管理）

适用场景：管理需要清理的资源（临时文件、SQLite 连接）。

文档以 tee 原始输出恢复为例说明“RAII 思维”：

// RTK tee.rs —— 临时输出文件的 RAII
pub struct TeeFile {
    path: PathBuf,
}

impl TeeFile {
    pub fn create(content: &str) -> Result<Self> {
        let path = tee_path()?;
        fs::write(&path, content)
            .with_context(|| format!("Failed to write tee file: {}", path.display()))?;
        Ok(Self { path })
    }
    pub fn path(&self) -> &Path { &self.path }
}

// 无需显式清理——文件是有意持久化的（轮转另行处理）
// 若确实需要清理：impl Drop { fn drop(&mut self) { let _ = fs::remove_file(&self.path); } }

这里体现的 RAII 要点是：资源的生命周期由类型所有权表达，而不是散落各处的手动清理调用；并且要区分“需要 Drop 清理的资源”与“有意持久化、生命周期由外部策略（轮转）管理的资源”。

对照 src/core/tee.rs 的实际实现，可以看到该模块当前采用面向函数的组织方式：tee_raw → write_tee_file → cleanup_old_files 构成落盘、截断、轮转的完整生命周期管理，并配套严格的行为契约：

• 触发条件由 TeeMode 控制（Failures 默认 / Always / Never），且原始输出小于 MIN_TEE_SIZE（500 字节）时跳过——小输出不值得落盘；
• 容量治理：DEFAULT_MAX_FILES = 20、DEFAULT_MAX_FILE_SIZE = 1MB，cleanup_old_files 按文件名前缀（epoch 时间戳，天然时序）轮转删除最旧文件；
• 写入安全：截断点回退到 UTF-8 字符边界避免 panic，文件与目录强制 0600/0700 权限（模块内测试 test_write_tee_file_is_owner_only 验证了即使 umask 宽松也不会泄露）；
• 提示回传：tee_and_hint / force_tee_tail_hint 生成形如 [full output: ~/...] 的 shell 安全路径提示（空格、$、反引号等元字符自动加引号），让 LLM 可以按需取回被过滤掉的完整输出。

无论组织形式是 TeeFile 结构体还是函数序列，RAII 原则都落在同一处：文件何时写、何时截断、何时删、权限多严，全部内聚在模块内部并由测试锁定，调用方不感知清理细节。

模式六：Strategy（可替换过滤逻辑）

适用场景：一条命令存在多种过滤模式（如 compact 与 verbose），模式在调用点选择而非编译期写死。

pub enum FilterMode {
    Compact,    // 只显示失败/错误
    Summary,    // 显示计数 + 关键错误
    Full,       // 原样透传
}

pub fn apply_filter(input: &str, mode: FilterMode) -> String {
    match mode {
        FilterMode::Compact => filter_compact(input),
        FilterMode::Summary => filter_summary(input),
        FilterMode::Full => input.to_string(),
    }
}

枚举 + 分发的 Strategy 在 rtk 中同样有实际对应物：

• src/core/stream.rs 定义了 FilterMode 与 StdinMode，供 src/core/runner.rs 的执行骨架统一消费，各过滤模块无需重复实现 stdout/stderr 分流逻辑；
• src/core/tee.rs 的 TeeMode（Failures / Always / Never，serde 序列化为小写字符串，Failures 为默认）就是“同一落盘行为、三种可配置策略”的直接体现，且通过 TeeConfig 的 TOML 反序列化对用户提供配置入口（mode = "always" / "failures" / "never"）。

选型提示：当“行为差异由调用者意图决定”时用 Strategy 枚举；当“行为差异由输入内容阶段决定”时用模式三的状态机。两者正交，rtk 的 pytest 过滤器同时体现了这一点：行级解析用状态机，落盘策略用 TeeMode。

模式七：Extension Trait（为外部类型添加方法）

适用场景：需要为你不拥有的类型（如 &str）添加项目专属方法。

pub trait RtkStrExt {
    fn is_error_line(&self) -> bool;
    fn is_warning_line(&self) -> bool;
    fn token_count(&self) -> usize;
}

impl RtkStrExt for str {
    fn is_error_line(&self) -> bool {
        self.starts_with("error") || self.contains("[E")
    }
    fn is_warning_line(&self) -> bool {
        self.starts_with("warning")
    }
    fn token_count(&self) -> usize {
        self.split_whitespace().count()
    }
}

// 使用
if line.is_error_line() { ... }
let tokens = output.token_count();

Extension Trait 让调用点读起来像内置方法（line.is_error_line()），把 rtk 专属的行分类语义从散落各处的自由函数收拢到一个 trait 下，同时不触碰标准库类型本身。对于过滤模块这种“对每一行做语义判断”的热路径，它比一组 is_error_line(line) 自由函数更利于统一维护与测试；但注意这与 rust-patterns.md 的性能约束并不矛盾——行级判断应尽量用 starts_with/contains 这类廉价操作，固定正则则放入 LazyLock<Regex> 静态量，避免每次调用重新编译。

RTK 模式选型指南

将文档中的选型表完整继承如下，它是新增 *_cmd.rs 过滤模块时的第一张参考表：

场景	选用模式	避免做法
新建 *_cmd.rs 过滤模块	标准模块模式（见 CLAUDE.md 与 rust-patterns.md）	过度抽象
4+ 个可选配置字段	Builder	结构体字面量
多阶段输出解析	状态机	嵌套 if/else
字符串的类型安全包装	Newtype	裸 String
为 &str 添加方法	Extension Trait	自由函数
需要清理的资源	RAII / Drop	手动清理
动态过滤器注册表	Trait Object	Match 膨胀

模块层面还有一个隐含前提：.claude/rules/rust-patterns.md 规定了每个 *_cmd.rs 的六段结构——imports、参数 struct、LazyLock 正则、pub fn run 入口、私有过滤函数、必含测试——并强制回退模式：过滤器失败时原样输出原始命令结果（unwrap_or_else 打印警告后透传），绝不阻塞用户。模式选择应服务于此骨架，而非反过来。

RTK 语境下的反模式

文档最后列出的反模式清单值得作为 review 检查项，每一条都对应 rtk 的架构约束：

// ❌ 为单一命令做泛型过度工程
pub trait Filterable<T: CommandArgs + Send + Sync + 'static> { ... }

// ✅ 直接写函数
pub fn filter_git_log(input: &str) -> Result<String> { ... }

// ❌ 带全局状态的单例注册表
static FILTER_REGISTRY: Mutex<HashMap<String, Box<dyn Filter>>> = ...;

// ✅ main.rs 中的 match —— 简单、零开销、易追踪

// ❌ 为“未来扩展”引入 async trait
#[async_trait]
pub trait Filter { async fn apply(&self, input: &str) -> Result<String>; }

// ✅ 同步 —— RTK 按设计就是单线程的
pub trait Filter { fn apply(&self, input: &str) -> Result<String>; }

• 泛型 Filterable<T>：只有一个命令需要时，泛型抽象带来的是维护成本而非复用收益；
• Mutex<HashMap<...>> 全局注册表：全局可变状态在单线程 CLI 中既是并发负担也是追踪障碍，且与“过滤失败必须透传”的回退原则冲突——注册表查询本身就成了新的失败点；
• async trait “预留扩展”：CLAUDE.md 明确“No async: single-threaded by design (startup <10ms)”——rtk 作为被 LLM 频繁调用的代理，每 5–10ms 的启动延迟都被成倍放大，同步 I/O 是架构级决策而非风格偏好。

结语

rtk 的设计模式文档给出的不是教科书式的模式罗列，而是一套与“单线程、零开销、回退优先”的 CLI 代理架构强绑定的选型准则：Newtype 守命令名安全边界，Builder 组织 RunOptions 这类多默认值配置，状态机消化 pytest/git status 等分段输出，Strategy 枚举承载 TeeMode 等可配置行为，Extension Trait 收拢 &str 的行级语义判断，而 Trait Object 与全局注册表则被刻意按在“约 20 个以上分支 + 动态注册需求”的门槛之外。对照 src/cmds/ 下各生态的过滤模块与 src/core/ 的共享骨架可以看出：这些模式的实际落地形态比文档示例更丰富（如 GitStatusState 的八态识别、tee 模块的权限与轮转契约），但选型逻辑与 SKILL 文档 完全一致——先问“这个模式是否消除了真实存在的复杂度”，再决定引入。