RTK 技术实战指南：Rust 单二进制 CLI 代理如何把 LLM 读取的 Bash 输出压缩 60%–90%

RTK（Rust Token Killer）是一个高性能的 CLI 代理：它拦截 AI 编码代理（Claude Code、Copilot 等）执行的 shell 命令，在输出进入 LLM 上下文之前对其进行过滤与压缩，据称可削减代理读取的 bash 输出达 60%–90%。整项目编译为单一 Rust 二进制，零运行时依赖，代理开销低于 10ms。读完本文，你将掌握 RTK 的安装与 Hook 初始化流程、各命令类别的压缩行为、rtk gain 节省统计的正确读法，以及从源码层面确认其 token 估算与过滤机制的实现依据。

一、RTK 解决什么问题

在 AI 代理驱动的开发流程中，代理执行的每条 shell 命令（git status、cargo test、pytest 等）的原始输出都会被读入模型上下文，成为输入 token 的一部分。这些输出中大量是噪声：进度条、重复日志行、样板代码、冗长的 diff 头。RTK 的核心做法就一句话：

rtk 在命令输出到达你的 LLM 上下文之前，对其进行过滤和压缩。单一 Rust 二进制、零依赖、开销低于 10ms。

工作模式上，RTK 位于代理与 shell 命令之间。代理执行命令时，RTK 负责执行该命令、压缩其输出、再把压缩后的版本返回给代理：

  无 rtk:                                       有 rtk:

  Claude  --git status-->  shell  -->  git         Claude  --git status-->  RTK  -->  git
    ^                                   |            ^                      |          |
    |        ~2,000 tokens (原始)        |            |   ~200 tokens        | 过滤     |
    +-----------------------------------+            +------- (过滤后) -----+----------+

同一份 git status 输出，原始约 2,000 tokens，经 RTK 过滤后约 200 tokens。

二、各类命令的压缩行为对照

RTK 针对不同类型的命令实现了专门的过滤器，下表完整列出其压缩策略：

操作	RTK 对输出的处理
ls / tree	目录树格式 + 文件计数，而非每个条目一行
cat / read	智能读取：优先输出签名与结构，而非完整函数体
grep / rg	截断过长行，按文件聚合匹配结果
git status	紧凑 stat 格式，按状态分组
git diff	缩减上下文行数，移除头部信息
git log	只保留 hash、作者与 commit 标题
git add/commit/push	一行确认信息，替代完整的进度输出
cargo test / npm test	只保留失败项，通过的测试折叠为一个计数
ruff check	按规则与文件分组
pytest	只保留失败项，缩短 traceback
go test	解析 NDJSON，只保留失败项
docker ps	只保留关键字段

这些策略背后是四类通用压缩手段：

1. 智能过滤——剔除噪声（注释、空行、样板代码）；
2. 聚合——归并相似项（文件按目录聚合、错误按类型聚合）；
3. 截断——保留相关上下文，删除冗余；
4. 去重——将重复的日志行折叠为带计数的单行。

三、"节省 90%" 到底在度量什么

RTK 声称削减最多 90% 的 bash 输出，但必须明确一点：这是 RTK 实际度量的对象，并不等于"账单降低 90%"。

bash 输出只是输入 token 的贡献者之一，与你的 prompt、系统提示词、会话历史并列；而输入 token 又只是账单的一部分，账单同样计入输出 token。因此缩减在每一层都被稀释：

账单 (Cost)
├─ 输入 tokens
│  ├─ Bash 输出           <- RTK 唯一能过滤的部分
│  ├─ 你的 prompt
│  ├─ 系统提示词
│  └─ 会话历史
└─ 输出 tokens            <- 模型生成的内容

一条命令的输出字节减少 90%，不会让整场会话便宜 90%。这正是 RTK 选择汇报"bash 输出缩减率"而非成本数字的原因：bash 输出是 RTK 能控制的部分，其余取决于你的 prompt、所用模型、代理写回的内容以及每次调用回放多少历史。完整推导见仓库内的 RTK 节省机制详解。

另一个必须理解的细节：RTK 报告的 token 数按 bytes / 4 估算。RTK 有意不内置任何 tokenizer，因此百分比可靠，但绝对 token 数是近似值。这一点可以直接在源码中得到证实——src/core/tracking.rs 中的估算实现就是：

(text.len() as f64 / 4.0).ceil() as usize

其后果是：由于原始输出与过滤后输出使用同一个估算器，二者之比（即节省百分比）不受估算精度影响；但 rtk gain 里显示的绝对 token 数只能当作量级参考，不会与你的服务商账单完全对齐。如需精确值，请用对应模型自己的 tokenizer 分别统计原始与过滤后的输出。

rtk gain 各列的真实含义：

列	实际含义
Input	原始命令输出按 bytes / 4 估算的 token 数
Output	过滤后输出按 bytes / 4 估算的 token 数
Saved	Input 减 Output，单位为估算 token
Save%	bash 输出字节的缩减率（有意义的数字）

其中 Save% 是有意义的指标——它本质是字节比值，作为比例是准确的。此外，RTK 不削减模型输出 token、不触及你的 prompt/系统提示/历史，也没有匹配过滤器的命令会原样透传并以 0% 节省被记录（可用 rtk gain --history 查看）。

四、安装

Homebrew（推荐）

brew install rtk

Homebrew 配方可直接参考仓库中的 Formula/rtk.rb。

快速安装（Linux/macOS）

curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

该脚本的仓库内源文件为 install.sh，详细安装指南见 INSTALL.md。

Cargo

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

验证

rtk --version   # 显示版本号
rtk gain        # 显示节省统计

注意：原文档中的 rtk --version 示例预期显示 rtk 0.28.2，而当前仓库 Cargo.toml 中的版本已是 0.42.4，请以实际安装后输出的版本为准。

五、快速上手：一条命令接入 Claude Code

# 1. 为 Claude Code 安装 hook（推荐）
rtk init --global

# 2. 重启 Claude Code，然后测试
git status  # 会被自动重写为 rtk git status

rtk init 会写入 hook 配置与 RTK 感知文件（如 ~/.claude/CLAUDE.md），使代理把 shell 命令自动重写为 rtk 前缀形式。Hook 的初始化逻辑位于 src/hooks/init.rs，其中也包含用户全局过滤器模板 ~/.config/rtk/filters.toml 的生成逻辑。更多 Agent（Copilot、Cursor、Windsurf 等）的 hook 集成说明见 hooks/README.md。

六、命令参考

以下百分比均为bash 输出字节的缩减率，由 RTK 的 bytes / 4 估算器度量，度量口径见 第三节的说明。

文件类

rtk ls .                        # 优化后的目录树
rtk read file.rs                # 智能读取（签名与结构优先）
rtk find "*.rs" .               # 紧凑结果
rtk grep "pattern" .            # 按文件聚合的搜索

Git

rtk git status                  # 紧凑状态
rtk git log -n 10               # 每个 commit 一行
rtk git git diff                # 精简 diff
rtk git push                    # -> "ok main"

测试

rtk jest                        # 紧凑的 Jest 输出
rtk vitest                      # 紧凑的 Vitest 输出
rtk pytest                      # Python 测试（-90%）
rtk go test                     # Go 测试（-90%）
rtk cargo test                  # Rust 测试（-90%）
rtk test <cmd>                  # 通用：只保留失败项（-90%）

构建与 Lint

rtk lint                        # 按规则聚合的 ESLint
rtk tsc                         # 聚合的 TypeScript 错误
rtk cargo build                 # Cargo 构建（-80%）
rtk ruff check                  # Python Lint（-80%）

分析

rtk gain                        # 节省统计
rtk gain --graph                # ASCII 图表（30 天）
rtk discover                    # 发现被浪费的节省机会

七、从源码看实现：过滤策略与执行生命周期

结合仓库源码，可以确认 RTK 的代理遵循六阶段生命周期（详见 docs/contributing/ARCHITECTURE.md）：

1. PARSE——clap 解析器提取子命令与参数；
2. ROUTE——main.rs 中按命令分派到对应模块（如 git::run）；
3. EXECUTE——std::process::Command 执行真实命令，捕获 stdout/stderr 与退出码；
4. FILTER——调用该命令的格式化函数压缩输出（如 git::format_git_output）；
5. PRINT——输出过滤结果，-v 可显示调试信息。

关键设计原则包括：退出码保真（保证 CI/CD 可靠性）、Fail-Safe（过滤失败时回退到原始输出）、透明（-v 随时可看原始输出）。从源码结构看，命令处理器按语言/领域分目录组织于 src/cmds/（git/、rust/、python/、go/、js/ 等），通用过滤规则则以 TOML 声明式定义存放于 src/filters/，核心基础设施（追踪、截断、流处理等）位于 src/core/。其中 src/core/tracking.rs 负责节省追踪，其数据库字段注释明确写着 input_tokens 与 output_tokens 均按 "bytes / 4, no tokenizer" 估算，与第三节的说明完全一致。

八、延伸阅读与许可

• INSTALL.md——详细安装指南
• docs/contributing/ARCHITECTURE.md——技术架构深参考
• docs/guide/resources/savings-explained.md——节省机制的完整推导
• hooks/README.md——各 AI 代理的 Hook 集成
• CONTRIBUTING.md——贡献指南
• DISCLAIMER.md——法律免责声明

RTK 采用 Apache License 2.0 许可，详见 LICENSE。