rtk 架构深解：六阶段命令生命周期、12 类过滤策略与 SQLite 级 Token 节省追踪

本文基于 rtk 的官方架构文档 docs/contributing/ARCHITECTURE.md 与当前仓库源码撰写，系统讲解 rtk（Rust Token Killer）作为 LLM Token 代理的核心设计：六阶段命令生命周期、12 类输出过滤策略、SQLite 追踪体系、全局标志架构、退出码保留机制与构建优化。读完后，你将理解 rtk 如何在每次代理调用中保持 5–15ms 的极低开销，并能按源码级细节评估或扩展一个新的命令过滤模块。

一、系统总览与设计原则

rtk 是一个高性能 CLI 代理（proxy）：它站在 LLM Agent（如 Claude Code）与开发工具之间，先执行原始命令，再对输出做过滤、统计提取或错误聚焦，把 60–90% 的冗余 Token 拦在模型上下文之外。最终分发形式是单个 Rust 二进制（当前仓库版本 0.42.4，要求 Rust ≥ 1.91，见 Cargo.toml），零运行时依赖。

架构文档确立了五条设计原则：

1. 单一职责：每个模块只处理一类命令（如 src/cmds/ruby/rake_cmd.rs 只负责 rake）；
2. 最小开销：每次代理约 5–15ms 额外开销；
3. 退出码保留：底层工具的退出码必须原样传播，保障 CI/CD 可靠性；
4. Fail-Safe：过滤失败时回退到原始输出，绝不吞掉信息；
5. 透明可调试：-v/-vv/-vvv 逐级暴露原始输出。

Hook 架构（v0.9.5+）

除了手动加 rtk 前缀，rtk 还通过 Agent Hook 拦截命令重写，分为两种策略：

Auto-Rewrite (默认)              Suggest (非侵入)
─────────────────────            ────────────────────────
Hook 拦截命令                    Hook 仅输出 systemMessage 提示
执行前重写                       由 Agent 自主决定是否采纳
100% 采纳率                      约 70–85% 采纳率
零上下文开销                     最小上下文开销
适用: 生产环境                   适用: 学习 / 审计

对应实现位于 src/hooks/（init、rewrite、permissions、verify、trust、integrity 等模块），面向 Agent 的配置模板存放在 hooks/ 目录下，覆盖 Claude、Cursor、Windsurf、Cline、Codex、Copilot、OpenCode、Pi 等多个 Agent，详见 hooks/README.md。

二、命令生命周期：从 rtk git log 到 SQLite 记录

架构文档以 rtk git log --oneline -5 -v 为例，将一次代理调用拆成六个阶段：

Phase 1 — PARSE（解析）。Clap Parser 从命令行提取出：命令枚举 Commands::Git、参数 ["log", "--oneline", "-5"]、全局标志 verbose = 1、ultra_compact = false。对应源码在 src/main.rs：Cli 结构体声明了 verbose: u8（ArgAction::Count）与全局 ultra_compact: bool。

Phase 2 — ROUTE（路由）。main() 中 match cli.command 分发到 git::run(args, verbose)。当前仓库的路由入口在 src/main.rs 第 1648 行附近的 match cli.command，Commands::Git 分支最终调用 src/cmds/git/git.rs 的 run()（第 86 行）。

Phase 3 — EXECUTE（执行）。通过 std::process::Command::new("git").args([...]).output()? 捕获 stdout、stderr 与退出码。

Phase 4 — FILTER（过滤）。例如 git log 采用"统计提取"策略：数提交、抽 +/− 行数，压缩为 5 commits, +142/-89 之类的摘要（文档示例中 500 字符 → 20 字符，96% 压缩）。

Phase 5 — PRINT（输出）。按 verbose 等级选择性打印调试信息到 stderr，最终彩色输出到 stdout。

Phase 6 — TRACK（追踪）。调用 tracking::track(original_cmd, rtk_cmd, raw, filtered)，按"每 4 字符 ≈ 1 Token"估算并写入 SQLite，落盘到 ~/.local/share/rtk/history.db。

详细度等级

-v   (Level 1): 调试消息，如 eprintln!("Git log summary:")
-vv  (Level 2): 显示实际执行的命令
-vvv (Level 3): 显示过滤前的原始输出

典型守卫写法（架构文档 Common Patterns 一节）：

if verbose > 0 {
    eprintln!("Debug: Processing {} files", count);
}
if verbose >= 2 {
    eprintln!("Executing: {:?}", cmd);
}
if verbose >= 3 {
    eprintln!("Raw output:\n{}", raw);
}

三、模块组织：按生态划分的命令模块 + 基础设施层

从源码结构看，代码按"生态 → 工具"两级组织：

生态目录	覆盖工具	文档标注的 Token 节省区间
src/cmds/git/	status、diff、log、add、commit、push、gh、glab、gt	85–99%
src/cmds/js/	lint、tsc、next、prettier、playwright、prisma、vitest、pnpm、npm	70–99%
src/cmds/python/	ruff、pytest、mypy、pip、uv	70–90%
src/cmds/go/	go test/build/vet、golangci-lint	75–90%
src/cmds/ruby/	rake、rspec、rubocop	60–90%
src/cmds/dotnet/	dotnet build/test、binlog	70–85%
src/cmds/cloud/	aws、docker/kubectl、curl、wget、psql	60–80%
src/cmds/system/	ls、tree、read、grep、find、json、log、env、deps	50–90%
src/cmds/rust/	cargo test/build/clippy、err	60–99%

文档给出的总量口径是 64 个模块（42 个命令模块 + 22 个基础设施模块）；当前仓库中已进一步扩展出 jvm（gradlew/mvn）、php、scala（sbt）等生态目录。基础设施层分为四块：

• src/core/：utils、filter、tracking、tee、config、toml_filter、display_helpers、telemetry 等；
• src/hooks/：hook 安装、命令重写、权限、完整性校验；
• src/analytics/：gain、cc_economics、ccusage、session 报告；
• src/filters/：大量 TOML 声明式过滤器（如 bundle-install.toml、golangci.json 对应 gcc），以声明式规则覆盖长尾命令。

每个生态目录都带 README（如 src/cmds/python/README.md），说明其模块清单与过滤策略，是理解单个生态的最佳入口。

四、过滤策略分类学：12 种策略与各自适用场景

架构文档的核心贡献是一份"过滤策略分类表"，它解释了不同工具为何采用不同的压缩手段：

#	策略	手段	典型模块	压缩率
1	统计提取 (Stats Extraction)	计数/聚合，丢弃细节	git status/log/diff、pnpm list	90–99%
2	仅错误 (Error Only)	只保留 stderr	runner (err 模式)、测试失败	60–80%
3	按模式分组 (Grouping)	按规则/文件分组计数	lint、tsc、grep	80–90%
4	去重 (Deduplication)	唯一化 + 出现次数	log_cmd（[ERROR] ... (×5)）	70–85%
5	仅结构 (Structure Only)	JSON 抽 key + 类型、抹掉值	json_cmd	80–95%
6	代码过滤 (Code Filtering)	按等级剥离注释/函数体	read、smart	0–90%
7	失败聚焦 (Failure Focus)	隐藏通过项、只留失败	vitest、playwright、runner	94–99%
8	树压缩 (Tree Compression)	平铺列表 → 目录树 + 计数	ls	50–70%
9	进度过滤 (Progress)	剥离 ANSI 进度条，留最终结果	wget、pnpm install	85–95%
10	JSON/文本双模式	有 JSON 走结构化，否则回退文本	ruff、pip	80%+
11	状态机解析	跟踪测试生命周期状态	pytest	90%+
12	NDJSON 流式	逐行解析 JSON 事件并聚合	go test	90%+

代码过滤的三级开关在 src/core/filter.rs 中实现为 FilterLevel 枚举（None / Minimal / Aggressive）：

• None：保留全部（0% 削减）；
• Minimal：仅剥离注释（20–40%）；
• Aggressive：剥离注释 + 函数体（60–90%）。

同文件中的 Language 枚举覆盖 Rust、Python、JavaScript、TypeScript、Go、C、C++、Java、Ruby、Shell、Data（JSON/YAML/TOML 等数据格式不做注释剥离）与 Unknown，语言识别以文件扩展名为准、辅以启发式回退。文档示例：

// FilterLevel::None —— 保留注释与全部代码
// FilterLevel::Minimal —— 仅剥离注释
// FilterLevel::Aggressive —— 注释 + 函数体都剥离，只留签名

格式策略决策树

面对一个新工具，文档给出固定的选型顺序：工具是否提供 JSON flag → 是否需要结构化数据（是则走 JSON API）→ 是否 NDJSON 流式事件 → 纯文本时是否需要状态机（如 pytest 的测试生命周期）→ 最后是简单文本过滤。该决策树与 src/cmds/README.md 中"新增命令过滤"的清单互相印证。

五、Python 与 Go 模块的两种架构范式

文档专门对比了 Python 与 Go 两套模块的组织方式：

Python（独立命令模式）：Commands::Ruff、Commands::Pytest、Commands::Pip 各自独立，对应 ruff_cmd.rs、pytest_cmd.rs、pip_cmd.rs，与 lint/prettier 的独立命令模式一致。其中 pytest 采用文本状态机（IDLE → TEST_START → PASSED/FAILED → SUMMARY），ruff 在 check 模式走 JSON、format 模式走文本，pip 使用 list --format=json / show 的 JSON 元数据。

Go（子枚举路由模式）：go test / build / vet 语义相关，聚合为子枚举 GoCommand 路由到 go_cmd.rs 的 run_test（第 48 行）、run_build（第 85 行）、run_vet（第 106 行）；而 golangci-lint 是第三方工具、输出格式不同，因此独立为 golangci_cmd.rs。go test 的输出是 NDJSON 流（{"Action": "run", "Package": "pkg1", "Test": "TestAuth"} 逐行事件、包间交错），rtk 逐行解析后聚合成 2 packages, 3 failures (pkg1::TestAuth, ...)。选择子枚举而非 rtk gotest 的理由：与 git/cargo 的现有模式保持一致，且 rtk go test 是更自然的 CLI 表达。

Ruby 模块沿用独立命令模式（rake/rspec/rubocop），并共享 src/core/utils.rs 中第 307 行的 ruby_exec()：当目录存在 Gemfile 时自动用 bundle exec <tool>，保证版本隔离。rubocop 在 autocorrect 模式（-a/-A）下跳过 JSON 注入；src/filters/bundle-install.toml 这类 TOML 过滤器则把 bundle install 的 "Using" 噪音短路成 ok bundle: complete。

文档给出的基准开销（估算值）：ruff check +12ms、pytest +10ms、go test +20ms、golangci-lint +20ms，开销主要来自 serde_json 解析（5–10ms）、正则状态机（3–8ms）与逐行 NDJSON 解析（8–15ms）。

六、共享基础设施：包管理器检测

JS/TS 模块的关键基础设施是包管理器检测。源码实现位于 src/core/utils.rs 的 detect_package_manager() 与 package_manager_exec()（第 333–370 行）：

// 检测顺序（源码 utils.rs::detect_package_manager）
// 1. pnpm-lock.yaml 存在 → pnpm
// 2. yarn.lock 存在     → yarn
// 3. 否则               → npm（npx --no-install）

// package_manager_exec 构造实际命令：
// pnpm → pnpm exec -- <tool>
// yarn → yarn exec -- <tool>
// npm  → npx --no-install -- <tool>

该机制影响 lint、tsc、next、prettier、playwright、prisma、vitest、pnpm 等全部 JS/TS 模块。它的价值在于：CWD 保持正确、支持 monorepo 嵌套 package.json、不依赖全局安装、跨环境行为一致。值得注意的是，从源码看 package_manager_exec 还会先检查工具二进制是否已存在（存在则直接 resolved_command(tool)），仅在缺失时才走包管理器 exec。

七、Token 追踪系统：SQLite 度量闭环

追踪子系统是 rtk 的"记账层"，源码在 src/core/tracking.rs，流程为估算 → 计算 → 落库 → 清理 → 报告五步：

1. 估算：estimate_tokens()（第 1321 行）实现为 (text.len() as f64 / 4.0).ceil() as usize，即"每 4 字符 ≈ 1 Token"的 GPT 风格启发式。文件内附测试用例可验证：estimate_tokens("abcd") == 1、estimate_tokens("abcde") == 2。

2. 计算：input_tokens 基于原始输出、output_tokens 基于过滤后输出，savings_pct = (saved / input) × 100。

3. 落库：INSERT INTO commands（第 435 行）写入 timestamp（RFC3339）、original_cmd、rtk_cmd、project_path、input/output/saved tokens、savings_pct、exec_time_ms。

4. 存储与保留期：数据库位于 ~/.local/share/rtk/history.db（路径常量 RTK_DATA_DIR/HISTORY_DB 定义于 src/core/constants.rs，保留期常量 DEFAULT_HISTORY_DAYS = 90 亦在此）。每次 INSERT 后自动执行 DELETE FROM commands WHERE timestamp < ?1（第 455–461 行）清理 90 天前的记录，同时清理 parse_failures 表。schema 如下：

commands
├─────────────────────────────────────────┤
│ id              INTEGER PRIMARY KEY     │
│ timestamp       TEXT NOT NULL           │
│ original_cmd    TEXT NOT NULL           │
│ rtk_cmd         TEXT NOT NULL          │
│ input_tokens    INTEGER NOT NULL        │
│ output_tokens   INTEGER NOT NULL        │
│ saved_tokens    INTEGER NOT NULL        │
│ savings_pct     REAL NOT NULL           │
│ exec_time_ms    INTEGER DEFAULT 0      │

（exec_time_ms 自 v0.7.1 加入，历史记录默认 0；从源码看实际 INSERT 还包含 project_path 字段。）

5. 报告：rtk gain 由 src/analytics/gain.rs 实现，聚合 total_commands、total_saved、avg_savings_pct 与执行时间统计，并支持 CSV/周维度导出（源码中可见 date/week 两种 CSV 头）。

线程安全：执行模型是单线程，Mutex<Option<Tracker>> 为未来的并发访问预留了安全边界。

选择 SQLite 的理由（文档 ADR 节）：零配置开箱即用、90 天历史仅约 100KB、ACID 保证完整性、可直接 SQL 查询做分析。

八、全局标志与错误处理

全局标志架构

• -v/-vv/-vvv：#[arg(short, long, action = clap::ArgAction::Count)] verbose: u8，逐级增加 stderr 调试输出；
• -u（ultra_compact）：#[arg(long, global = true)]，ASCII 图标替代文字、单行内联格式，面向 LLM 上下文的最大压缩；
• 从源码看还有一个文档未重点展开的 --skip-env 全局标志，为子进程（Next.js、tsc、lint、prisma）设置 SKIP_ENV_VALIDATION=1，避免 Next.js 环境变量校验噪音（src/main.rs 第 84–85 行）。

错误传播与退出码保留

错误处理采用 anyhow::Result 传播链：Command::new(...).output()? → .context("Failed to execute git") 逐层附加上下文 → 气泡到 main() 显示 Error: {:#}。

比错误信息更重要的是退出码保留（CI/CD 的命脉）。当前源码中各命令 run() 统一返回 Result<i32>，失败时原样返回底层退出码，例如 src/cmds/git/git.rs：

let result = exec_capture(&mut cmd).context("Failed to run git diff")?;

if !result.success() {
    eprintln!("{}", result.stderr);
    return Ok(result.exit_code);   // 底层工具的退出码原样透传
}

退出码语义：0 成功；1 rtk 内部错误（解析、过滤失败等）；N 底层工具退出码（git 常见 128、lint 常见 1）。文档特别指出这是 PR #5 的修复项，git、lint、tsc、vitest、playwright 等模块均已落实。src/core/utils.rs 还封装了 exit_code_from_output() / exit_code_from_status()（第 215、236 行）统一这一模式，另有 fallback_tail()（第 256 行）在过滤失败时保留输出尾部作为 fail-safe。

九、配置系统

rtk 的配置分两层：

1. 用户设置：~/.config/rtk/config.toml（路径由 src/core/config.rs 通过 dirs::config_dir() 拼接，注释明确该文件"由用户拥有"，rtk init -g 重跑不会覆盖它）；
2. LLM 集成：通过 rtk init 写入项目 CLAUDE.md 的提示模板。

rtk init 的工作流：检查目标 CLAUDE.md（--global 时对应 ~/.claude/CLAUDE.md，本地项目为 ./CLAUDE.md）→ 已存在则警告询问 → 提示 Initialize rtk for LLM usage? [y/N] → 写入"使用 rtk 前缀执行命令"的模板。实现位于 src/hooks/init.rs，源码注释中的用法示例：

rtk init                # 将 RTK 指令写入项目 CLAUDE.md
rtk init --global       # 写入 ~/.claude/CLAUDE.md

更多格式细节（tee 设置、TOML 过滤器分层、追踪库路径）见 src/core/README.md。

十、构建优化与性能特征

Cargo.toml 第 57–62 行定义了 release profile，与文档一致：

[profile.release]
opt-level = 3        # 最大优化
lto = true           # 链接期优化
codegen-units = 1    # 单代码生成单元
panic = "abort"      # 更小二进制
strip = true         # 移除调试符号

文档标注的性能画像（估算值，实际随系统、命令复杂度与输出规模变化）：

• 二进制约 4.1MB（stripped）；冷启动 5–10ms；内存 2–5MB；
• rtk git status 约 +8ms、rtk grep 约 +12ms、rtk read 约 +5ms、rtk lint 约 +15ms；
• 开销构成：Clap 解析 ~2–3ms、命令执行 ~1–2ms、过滤/压缩 ~2–8ms、SQLite 追踪 ~1–3ms。

十一、架构决策记录（ADR）

文档最后固定了四条"为什么"，是理解项目取舍的关键：

• 为什么 Rust：5–15ms 的低开销、无空指针/数据竞争类运行时错误、单二进制分发、跨 macOS/Linux/Windows；
• 为什么 SQLite：零配置、轻量（90 天历史约 100KB）、ACID 可靠、可 SQL 分析；
• 为什么 anyhow：.context() 沿调用链附加语义、? 传播简洁、错误展示包含完整上下文链；
• 为什么 Clap：derive 宏减少样板、自动生成 --help、参数直接解析为类型化结构、-v/-u 可作为 global flag 跨所有子命令生效。

十二、扩展指南：新增一个命令过滤模块

架构文档把完整的"新增命令"流程（建模块文件 → 加枚举变体 → 接入路由 → 补测试与文档）外链到 src/cmds/README.md 的 "Adding a New Command Filter" 一节，并给出新增 Python/Go 模块时的九项检查清单：

• 输出格式优先级：JSON API > NDJSON > 状态机 > 文本过滤；
• 失败聚焦：隐藏通过项、只留失败项；
• 退出码保留：为 CI/CD 传播工具退出码；
• 虚拟环境感知：Python 模块尊重激活的 venv；
• 错误分组：linter 按规则/文件分组（ruff、golangci-lint）；
• 流式支持：处理交错的 NDJSON 事件（go test）；
• 支持 -v/-vv/-vvv 调试输出；
• 接入 tracking::track() 完成 Token 记账；
• 用代表性输出写单元测试。

仓库内的 tests/fixtures/ 目录（如 golangci_v2_json.txt、pytest 相关输出、sbt_test_*.txt）即为这类解析测试的输入样本，可直接用于验证新模块的解析逻辑。

小结：从源码结构看架构一致性

纵观全仓库，rtk 的架构叙事在源码中得到了一一印证：main.rs 中的 Clap 枚举路由、按生态切分的 cmds/ 模块、core/ 中的追踪与过滤基座、hooks/ 中的 Agent 集成、analytics/ 中的 gain 报告，共同构成"解析 → 路由 → 执行 → 过滤 → 输出 → 记账"的闭环。它的核心工程判断是：把"给 LLM 看什么"当作一个独立的过滤层来设计——用策略分类学（而非单一截断）匹配每种工具的输出形态，用退出码保留保证代理层的可替换性，用 SQLite 记账把"节省了多少 Token"变成可查询、可审计的硬数据。对于需要在其上扩展或审计该项目的开发者，本文引用的 src/core/README.md、src/cmds/README.md 与 docs/contributing/TECHNICAL.md 是继续深入的最佳入口。

（文中"节省百分比""开销毫秒数"等数值均转引自 docs/contributing/ARCHITECTURE.md 原文，属于文档标注的估算/基准数据，实际表现随命令与输出规模变化。）