1. RTK 核心工作原理

1.1 系统架构概览

RTK（Rust Token Killer）是一个高性能 CLI 代理工具，采用**代理模式（Proxy Pattern）**架构设计。其核心定位是在 LLM（如 Claude Code）与 Shell 命令之间充当智能过滤器，通过减少传递给 LLM 的 token 数量来降低使用成本。

1.1.1 代理模式架构图

┌────────────────────────────────────────────────────────────────────────┐
│                      rtk - Token Optimization Proxy                    │
└────────────────────────────────────────────────────────────────────────┘

用户输入          CLI 层              路由层            模块层
──────────          ─────────           ──────            ────────────

$ rtk git log    →  Clap 解析器    →   Commands    →   git::run()
  -v --oneline       (main.rs)          enum match
                     • 解析参数                         执行：git log
                     • 提取标志                         捕获输出
                     • 路由命令                               ↓
                                                        过滤/压缩
                                                               ↓
$ 3 commits      ←  终端着色       ←   格式优化     ←   紧凑统计
  +142/-89           colored            optimized         (90% 压缩率)
                     output                                     ↓
                                                        tracking::track()
                                                               ↓
                                                        SQLite INSERT
                                                        (~/.local/share/rtk/)

1.1.2 核心组件职责

1.2 六阶段命令生命周期

RTK 的每个命令执行都经过六个阶段：

阶段 1：解析（PARSE）

$ rtk git log --oneline -5 -v

Clap 解析器提取：
  • 命令：Commands::Git
  • 参数：["log", "--oneline", "-5"]
  • 标志：verbose = 1（-v 计数）
          ultra_compact = false

阶段 2：路由（ROUTE）

// main.rs 中的路由逻辑
match cli.command {
    Commands::Git { args, .. } => git::run(&args, verbose)?,
    Commands::Lint { args, .. } => lint_cmd::run(&args, verbose)?,
    // ... 34 个命令分支
}

阶段 3：执行（EXECUTE）

// 执行底层命令
std::process::Command::new("git")
    .args(["log", "--oneline", "-5"])
    .output()?;

// 捕获输出：
//   • stdout: "abc123 Fix bug\ndef456 Add feature\n..." (500 字符)
//   • stderr: "" (空)
//   • exit_code: 0

阶段 4：过滤（FILTER）

// 应用过滤策略
git::format_git_output(stdout, "log", verbose)

// 策略：统计信息提取
//   • 计算提交数：5
//   • 提取统计：+142/-89
//   • 压缩输出："5 commits, +142/-89"

// 过滤后：20 字符（96% 压缩率）

阶段 5：打印（PRINT）

// 根据 verbose 级别输出
if verbose > 0 {
    eprintln!("Git log summary:");  // 调试信息
}
println!("{}", colored_output);     // 用户输出

阶段 6：追踪（TRACK）

// 记录 token 节省指标到 SQLite
tracking::track(
    original_cmd: "git log --oneline -5",
    rtk_cmd: "rtk git log --oneline -5",
    input: &raw_output,    // 500 字符
    output: &filtered      // 20 字符
)

// SQLite INSERT:
//   • input_tokens: 125 (500 / 4)
//   • output_tokens: 5 (20 / 4)
//   • savings_pct: 96.0
//   • timestamp: now()
// 数据库路径：~/.local/share/rtk/history.db

1.3 Hook 架构（推荐部署模式）

RTK v0.9.5+ 引入了 Claude Code PreToolUse Hook，实现 100% 透明的命令重写。

Hook 工作原理

┌────────────────────────────────────────────────────────────────────────┐
│                    Hook-Based Command Rewriting                        │
└────────────────────────────────────────────────────────────────────────┘

Claude Code             settings.json        rtk-rewrite.sh        RTK 二进制
     │                       │                     │                    │
     │  Bash: "git status"   │                     │                    │
     │ ─────────────────────►│                     │                    │
     │                       │  PreToolUse hook    │                    │
     │                       │ ───────────────────►│                    │
     │                       │                     │  检测：git         │
     │                       │                     │  重写：            │
     │                       │                     │  rtk git status    │
     │                       │◄────────────────────│                    │
     │                       │  updatedInput        │                    │
     │                       │                                          │
     │  execute: rtk git status ────────────────────────────────────────►
     │                                                                  │  运行 git
     │                                                                  │  过滤
     │                                                                  │  追踪
     │◄──────────────────────────────────────────────────────────────────
     │  "3 modified, 1 untracked ✓"    (~10 tokens vs ~200 raw)
     │
     │  Claude 从未看到重写过程——它只看到优化后的输出。

文件:
  ~/.claude/hooks/rtk-rewrite.sh  ← 薄委托器（调用 `rtk rewrite`，约 50 行）
  ~/.claude/settings.json         ← Hook 注册表（PreToolUse 注册）
  ~/.claude/RTK.md                ← 最小上下文提示（10 行）

两种 Hook 策略对比

1.4 设计原则

RTK 遵循五大设计原则：

1. 单一职责：每个模块只处理一种命令类型（如 git.rs 仅处理 Git 命令）
2. 最小开销：代理 overhead 约 5-15ms/命令（Rust 单二进制，零依赖）
3. 退出码保留：正确传播底层工具的退出码，确保 CI/CD 可靠性
4. 故障安全：如果过滤失败，回退到原始输出
5. 透明性：用户始终可以通过 -v 标志查看完整输出

1.5 模块组织（57 个模块）

命令模块（34 个）

基础设施模块（19 个）

utils.rs, filter.rs, tracking.rs, tee.rs, config.rs, init.rs, gain.rs, rewrite_cmd.rs 等。

1.6 配置系统

两级配置架构

1. 用户设置（config.toml）

# ~/.config/rtk/config.toml

[general]
default_filter_level = "minimal"
enable_tracking = true
retention_days = 90

[tracking]
database_path = "/path/to/custom.db"  # 默认：~/.local/share/rtk/history.db

[hooks]
exclude_commands = ["curl", "playwright"]  # 不为这些命令重写

[tee]
enabled = true          # 失败时保存完整输出（默认：true）
mode = "failures"       # "failures", "always", 或 "never"
max_files = 20          # 轮转限制

2. LLM 集成（CLAUDE.md）

# CLAUDE.md
# 位置：~/.config/rtk/CLAUDE.md（全局）或 ./CLAUDE.md（项目级）

使用 `rtk` 前缀执行命令：
- rtk git status
- rtk grep "pattern"
- rtk read file.rs

优势：60-90% token 节省

1.7 全局标志

详细程度级别（Verbosity Levels）

// main.rs:47-49
#[arg(short, long, action = clap::ArgAction::Count, global = true)]
verbose: u8,

超紧凑模式（Ultra-Compact Mode）

// main.rs:51-53
#[arg(short = 'u', long, global = true)]
ultra_compact: bool,

功能：

• ASCII 图标代替单词（✓ ✗ → ⚠）
• 内联格式化（单行摘要）
• 针对 LLM 上下文的最大压缩

1.8 错误处理架构

anyhow::Result<()> 传播链

// 错误传播链
main() → Result<()>
  ↓
  match cli.command {
      Commands::Git { args, .. } => git::run(&args, verbose)?,
      ...
  }
  ↓ .context("Git 命令失败")
git::run(args: &[String], verbose: u8) → Result<()>
  ↓ .context("执行 git 失败")
git::execute_git_command() → Result<String>
  ↓ .context("Git 进程错误")
Command::new("git").output()?
  ↓ 错误发生
anyhow::Error
  ↓ 通过 ? 向上传播
main.rs 错误显示
  ↓
eprintln!("Error: {:#}", err)
  ↓
std::process::exit(1)

退出码保留（CI/CD 关键）

// git.rs:45-48 标准模式
let output = Command::new("git").args(args).output()?;

if !output.status.success() {
    let stderr = String::from_utf8_lossy(&output.stderr);
    eprintln!("{}", stderr);
    std::process::exit(output.status.code().unwrap_or(1));
}

1.9 Token 追踪系统

SQLite 指标记录

// 估算启发式：~4 字符/token（GPT 风格分词）
fn estimate_tokens(text: &str) -> usize {
    (text.len() as f64 / 4.0).ceil() as usize
}

// 计算节省
input_tokens  = estimate_tokens(raw_output)      // 125 tokens
output_tokens = estimate_tokens(filtered_output) // 5 tokens
saved_tokens  = input_tokens - output_tokens     // 120 tokens
savings_pct   = (saved / input) × 100.0          // 96.0%

数据库 Schema

CREATE TABLE commands (
    id              INTEGER PRIMARY KEY,
    timestamp       TEXT NOT NULL,           -- RFC3339 格式
    original_cmd    TEXT NOT NULL,           -- "git log --oneline -5"
    rtk_cmd         TEXT NOT NULL,           -- "rtk git log --oneline -5"
    input_tokens    INTEGER NOT NULL,        -- 125
    output_tokens   INTEGER NOT NULL,        -- 5
    saved_tokens    INTEGER NOT NULL,        -- 120
    savings_pct     REAL NOT NULL,           -- 96.0
    exec_time_ms    INTEGER DEFAULT 0        -- 执行时长（v0.7.1+）
);

-- 自动清理：保留 90 天
DELETE FROM commands
WHERE timestamp < datetime('now', '-90 days');

报告生成（rtk gain）

$ rtk gain

┌──────────────────────────────────────┐
│ Token Savings Report (90 days)      │
├──────────────────────────────────────┤
│ Commands executed:  1,234           │
│ Average savings:    78.5%           │
│ Total tokens saved: 45,678          │
│ Total exec time:    8m50s (573ms)   │
│                                      │
│ Top commands:                       │
│   • rtk git status    (234 uses)    │
│   • rtk lint          (156 uses)    │
│   • rtk test          (89 uses)     │
└──────────────────────────────────────┘

1.10 安装与验证

安装方法

Homebrew（推荐）

brew install rtk

Quick Install（Linux/macOS）

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
# 安装到 ~/.local/bin，需添加到 PATH
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc  # 或 ~/.zshrc

Cargo

cargo install --git https://github.com/rtk-ai/rtk

验证安装

rtk --version   # 应显示 "rtk 0.27.1"
rtk gain        # 应显示 token 节省统计

# 注意：存在同名项目 "Rust Type Kit"（reachingforthejack/rtk）
# 如果 `rtk gain` 失败，说明安装了错误的包

1.11 快速开始

1. 安装 Hook（推荐）

rtk init --global
# 按照提示在 ~/.claude/settings.json 中注册

# 验证安装
rtk init --show  # 应显示 "✅ Hook: executable, with guards"

2. 重启 Claude Code

# 重启后测试
git status  # 自动重写为 rtk git status

Hook 会透明地重写命令（如 git status → rtk git status）在它们执行之前。Claude 从未看到重写过程，它只接收到压缩后的输出。

1.12 性能特征

基准测试数据

开销来源

• JSON 解析：5-10ms（serde_json）
• 状态机：3-8ms（正则 + 状态追踪）
• NDJSON 流：8-15ms（逐行 JSON 解析）
• 总代理开销：5-15ms/命令

1.13 结论

RTK 的核心工作原理是基于代理模式的 CLI 优化工具，通过六个阶段的命令生命周期（解析→路由→执行→过滤→打印→追踪），实现透明化的 token 节省。其架构设计遵循单一职责、最小开销、退出码保留等原则，模块组织清晰（57 个模块），配置系统灵活（两级配置），错误处理健壮（anyhow 传播链 + 退出码保留）。

关键技术特点：

• 单 Rust 二进制，零依赖，<10ms 开销
• Hook 架构实现 100% 透明命令重写
• SQLite 追踪记录 token 指标，支持 90 天历史
• TEE 机制在失败时保留完整输出用于故障排查
• 退出码保留确保 CI/CD 可靠性

下一章将详细分析 RTK 的 12 种过滤策略及其技术实现细节。