rtk 架构深解六阶段命令生命周期、12 类过滤策略与 SQLite 级 Token 节省追踪【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtk本文基于 rtk 的官方架构文档 docs/contributing/ARCHITECTURE.md 与当前仓库源码撰写系统讲解 rtkRust 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零运行时依赖。架构文档确立了五条设计原则单一职责每个模块只处理一类命令如src/cmds/ruby/rake_cmd.rs只负责 rake最小开销每次代理约 5–15ms 额外开销退出码保留底层工具的退出码必须原样传播保障 CI/CD 可靠性Fail-Safe过滤失败时回退到原始输出绝不吞掉信息透明可调试-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.rsCli结构体声明了verbose: u8ArgAction::Count与全局ultra_compact: bool。Phase 2 — ROUTE路由。main()中match cli.command分发到git::run(args, verbose)。当前仓库的路由入口在 src/main.rs 第 1648 行附近的match cli.commandCommands::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、gt85–99%src/cmds/js/lint、tsc、next、prettier、playwright、prisma、vitest、pnpm、npm70–99%src/cmds/python/ruff、pytest、mypy、pip、uv70–90%src/cmds/go/go test/build/vet、golangci-lint75–90%src/cmds/ruby/rake、rspec、rubocop60–90%src/cmds/dotnet/dotnet build/test、binlog70–85%src/cmds/cloud/aws、docker/kubectl、curl、wget、psql60–80%src/cmds/system/ls、tree、read、grep、find、json、log、env、deps50–90%src/cmds/rust/cargo test/build/clippy、err60–99%文档给出的总量口径是64 个模块42 个命令模块 22 个基础设施模块当前仓库中已进一步扩展出 jvmgradlew/mvn、php、scalasbt等生态目录。基础设施层分为四块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 list90–99%2仅错误 (Error Only)只保留 stderrrunner (err 模式)、测试失败60–80%3按模式分组 (Grouping)按规则/文件分组计数lint、tsc、grep80–90%4去重 (Deduplication)唯一化 出现次数log_cmd[ERROR] ... (×5)70–85%5仅结构 (Structure Only)JSON 抽 key 类型、抹掉值json_cmd80–95%6代码过滤 (Code Filtering)按等级剥离注释/函数体read、smart0–90%7失败聚焦 (Failure Focus)隐藏通过项、只留失败vitest、playwright、runner94–99%8树压缩 (Tree Compression)平铺列表 → 目录树 计数ls50–70%9进度过滤 (Progress)剥离 ANSI 进度条留最终结果wget、pnpm install85–95%10JSON/文本双模式有 JSON 走结构化否则回退文本ruff、pip80%11状态机解析跟踪测试生命周期状态pytest90%12NDJSON 流式逐行解析 JSON 事件并聚合go test90%代码过滤的三级开关在 src/core/filter.rs 中实现为FilterLevel枚举None/Minimal/AggressiveNone保留全部0% 削减Minimal仅剥离注释20–40%Aggressive剥离注释 函数体60–90%。同文件中的Language枚举覆盖 Rust、Python、JavaScript、TypeScript、Go、C、C、Java、Ruby、Shell、DataJSON/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 → SUMMARYruff 在 check 模式走 JSON、format 模式走文本pip 使用list --formatjson/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. 否则 → npmnpx --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 行写入 timestampRFC3339、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 头。线程安全执行模型是单线程MutexOptionTracker为未来的并发访问预留了安全边界。选择 SQLite 的理由文档 ADR 节零配置开箱即用、90 天历史仅约 100KB、ACID 保证完整性、可直接 SQL 查询做分析。八、全局标志与错误处理全局标志架构-v/-vv/-vvv#[arg(short, long, action clap::ArgAction::Count)] verbose: u8逐级增加 stderr 调试输出-uultra_compact#[arg(long, global true)]ASCII 图标替代文字、单行内联格式面向 LLM 上下文的最大压缩从源码看还有一个文档未重点展开的--skip-env全局标志为子进程Next.js、tsc、lint、prisma设置SKIP_ENV_VALIDATION1避免 Next.js 环境变量校验噪音src/main.rs 第 84–85 行。错误传播与退出码保留错误处理采用anyhow::Result传播链Command::new(...).output()?→.context(Failed to execute git)逐层附加上下文 → 气泡到main()显示Error: {:#}。比错误信息更重要的是退出码保留CI/CD 的命脉。当前源码中各命令run()统一返回Resulti32失败时原样返回底层退出码例如 src/cmds/git/git.rslet result exec_capture(mut cmd).context(Failed to run git diff)?; if !result.success() { eprintln!({}, result.stderr); return Ok(result.exit_code); // 底层工具的退出码原样透传 }退出码语义0成功1rtk 内部错误解析、过滤失败等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 的配置分两层用户设置~/.config/rtk/config.toml路径由 src/core/config.rs 通过dirs::config_dir()拼接注释明确该文件由用户拥有rtk init -g重跑不会覆盖它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.1MBstripped冷启动 5–10ms内存 2–5MBrtk git status约 8ms、rtk grep约 12ms、rtk read约 5ms、rtk lint约 15ms开销构成Clap 解析 ~2–3ms、命令执行 ~1–2ms、过滤/压缩 ~2–8ms、SQLite 追踪 ~1–3ms。十一、架构决策记录ADR文档最后固定了四条为什么是理解项目取舍的关键为什么 Rust5–15ms 的低开销、无空指针/数据竞争类运行时错误、单二进制分发、跨 macOS/Linux/Windows为什么 SQLite零配置、轻量90 天历史约 100KB、ACID 可靠、可 SQL 分析为什么 anyhow.context()沿调用链附加语义、?传播简洁、错误展示包含完整上下文链为什么 Clapderive 宏减少样板、自动生成--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 原文属于文档标注的估算/基准数据实际表现随命令与输出规模变化。【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtk创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考