RTK 实战指南：让 LLM Agent 少读 90% 命令行输出的 Rust CLI 代理

RTK（Rust Token Killer）是一个高性能 CLI 代理，它在 shell 命令的输出抵达 LLM 上下文之前，先对输出进行过滤与压缩，最高可削减 Agent 读取的 bash 输出达 90%。本文基于仓库日文版 README（README_ja.md）的完整骨架展开，并结合当前仓库源码（入口 src/main.rs、追踪模块 src/core/tracking.rs、配置文档 docs/guide/getting-started/configuration.md），系统讲解 RTK 的压缩机制、安装方式、核心命令、统计分析与配置体系。读完后你可以独立完成 RTK 的安装、把自动重写 Hook 接入 AI 编码工具，并理解每条 rtk 命令背后的过滤策略与 token 统计原理。

RTK 是什么：在输出进入上下文之前压缩它

RTK 的定位是命令输出的中间人：它拦截 shell 命令，先执行原始命令捕获输出，再按命令类型应用相应的过滤策略，只把压缩后的结果交给终端（以及阅读该终端的 AI Agent）。它是单个 Rust 二进制，零运行时依赖，代理开销低于 10ms。

从 Cargo.toml 可以看到其工程属性：当前版本 0.42.4，Rust edition 2021、要求 rust-version = "1.91"，Apache 2.0 许可；release 构建启用了 opt-level = 3、lto = true、codegen-units = 1 与符号剥离，并且 unsafe_code = "deny"——这些配置支撑了“单二进制、低开销”的主张。

RTK 对各类操作所做的具体压缩，日文 README 用一张表概括得很清楚，这里完整继承：

操作	RTK 对输出做的事
ls / tree	不逐行列出条目，而是带文件计数的树形结构
cat / read	智能读取文件：优先保留签名（函数/类型声明）与结构，而非整个文件正文
grep / rg	截断超长行，按文件分组匹配结果
git status	紧凑的 stat 格式，按状态分组
git diff	减少上下文行，去除头部信息
git log	只保留哈希、作者与提交主题
git add/commit/push	用一行确认信息替代整个进度输出
cargo test / npm test	只报失败项，通过的测试折叠为计数
ruff check	按规则与文件分组
pytest	只报失败项，缩短 traceback
go test	解析 NDJSON，只保留失败项
docker ps	只保留必要字段

对应的过滤实现按命令族组织在 src/cmds/ 目录下：git/、rust/、js/、python/、go/、ruby/、php/、jvm/、cloud/（含 docker/curl/psql）、system/（ls、find、grep、read、log 等）各是一个独立模块，符合 ARCHITECTURE 文档中“单一职责：每个模块只处理一类命令”的设计原则（见 docs/contributing/ARCHITECTURE.md）。

节约的口径：压缩的是 bash 输出，不是账单

这一点日文 README 专门辟了一节（“節約の仕組み”），必须准确理解，避免误读宣传数字：

1. RTK 削减的是 Agent 读取的 bash 输出，最高 90%。这是 RTK 实际测量的对象，并不等价于账单减少 90%。
2. bash 输出只是输入 token 的构成要素之一，与你的 prompt、系统提示词、对话历史并列；而输入 token 本身也只是账单的一部分（账单还包含输出 token）。因此削减效果在每一级传递中都会被稀释。
3. token 数是按 字节数 / 4 估算的。RTK 不内置 tokenizer，所以百分比可靠，但绝对 token 数是近似值。

第 3 点在源码中可以直接验证。src/core/tracking.rs 中的估算函数采用 tokens = ceil(chars / 4) 的规则，文档注释里给出了精确的断言示例：空串为 0 token，4 个字符为 1 token，5 个字符为 2 个 token（即 ceil(1.25) = 2）。每次命令执行后，原始输出与过滤后输出的字节数都会以 input_tokens = ceil(原始字节/4)、output_tokens = ceil(过滤字节/4) 的形式记录进本地 SQLite 数据库（Linux 下为 ~/.local/share/rtk/tracking.db），并计算 savings_pct——这正是 rtk gain 看板的数据来源。

因此，当你看到 rtk gain 报告“节省了 85%”时，正确的解读是：这类命令的 bash 输出体积被压缩了 85%；它对整体 API 费用的实际贡献，取决于 bash 输出在你输入 token 中所占的比重。

安装与验证

日文 README 给出三种安装方式，以下完整继承并补充仓库内的佐证文件。

方式一：Homebrew（推荐）

brew install rtk

仓库中附带 Homebrew formula 文件 Formula/rtk.rb，其中按架构从 Releases 下载 rtk-x86_64-apple-darwin.tar.gz / rtk-aarch64-apple-darwin.tar.gz，与上述命令对应。

方式二：一键安装脚本（Linux/macOS）

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

安装脚本为仓库根目录的 install.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 gain        # 显示 token 节约统计看板

需要注意版本口径：日文 README 中示例写作 rtk 0.27.x，而当前仓库 Cargo.toml 中声明的版本是 0.42.4，以仓库实际内容为准即可。

快速开始：自动重写 Hook

RTK 最有效的用法是让 AI 工具的 Hook 在执行 Bash 命令前透明地把命令改写成 rtk 等价命令，Agent 无需显式调用 rtk：

# 1. 安装 Claude Code 用 Hook（推荐）
rtk init --global      # 等价于 rtk init -g

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

rtk init 支持多种 Agent 目标，目标枚举定义在 src/main.rs 的 AgentTarget 中，包括 Claude（默认）、Cursor、Windsurf、Cline、Kilocode、Antigravity、Kimi、Pi、Hermes、Droid、Vibe 等。

从源码结构看，Hook 机制本身有独立的实现模块 src/hooks/（含 init.rs 负责安装、hook_check.rs 负责状态检查、rewrite_cmd.rs 负责命令改写），各 Agent 的安装脚本与规则文件则放在 hooks/ 目录下（claude/、cursor/、copilot/、opencode/ 等子目录），并附有针对性测试（如 hooks/claude/test-rtk-rewrite.sh）。

一个作用域细节需要注意（英文版 README 同样强调）：Hook 只对 Bash 工具调用生效。Agent 的内置工具（如 Read、Grep、Glob）不经过 Bash Hook，不会被自动改写；这类场景应直接使用 shell 命令（cat/rg/find）或显式调用 rtk read、rtk grep、rtk find。

工作原理：代理模式与四种过滤策略

日文 README 用一张 ASCII 图展示了有/无 RTK 的区别：

  无 rtk：                                    有 rtk：

  Claude  --git status-->  shell  -->  git     Claude  --git status-->  RTK  -->  git
    ^                                   |        ^                      |         |
    |        ~2,000 tokens（原始输出）    |        |   ~200 tokens        | 过滤    |
    +-----------------------------------+        +-------（压缩后）-----+---------+

即 RTK 在 Agent 与真实命令之间插了一层过滤代理。按命令类型应用四种策略：

1. 智能过滤（Smart Filtering）——去噪：注释、空白、样板文本；
2. 分组（Grouping）——聚合同类项：按目录聚合文件、按类型聚合错误；
3. 截断（Truncation）——保留相关上下文，砍掉冗余；
4. 去重（Deduplication）——把重复的日志行合并为带计数的单行。

从源码结构看，每条命令走一个六阶段生命周期（详见 docs/contributing/ARCHITECTURE.md）：PARSE（clap 解析子命令与全局标志）→ ROUTE（main.rs 按 Commands 枚举路由到对应模块，如 git::run(args, verbose)）→ EXECUTE（std::process::Command 执行原始命令并捕获 stdout/stderr/exit_code）→ FILTER（按命令类型格式化输出）→ PRINT（按 verbose 级别打印）→ TRACK（把输入/输出字节数写入 SQLite）。

入口 src/main.rs 中的 Cli 结构体定义了两个全局标志，与日文 README 的命令区呼应：

-u, --ultra-compact    # 超紧凑模式：ASCII 图标、行内格式（进一步压缩输出）
-v, --verbose          # 提高详细级别（-v、-vv、-vvv）

此外还有一个面向子进程环境校验的 --skip-env 标志（为 Next.js、tsc、lint、prisma 等设置 SKIP_ENV_VALIDATION=1）。

核心命令详解

以下命令输出中标注的百分比是 bash 输出字节数的削减率，按 RTK 的 字节数 / 4 估算器测量，参见上文“节约的口径”一节。

文件类

rtk ls .                        # 优化的目录树
rtk read file.rs                # 智能文件读取
rtk find "*.rs" .               # 紧凑的查找结果
rtk grep "pattern" .           # 按文件分组的搜索

rtk read 在 src/main.rs 的 Commands::Read 中定义了完整参数：支持多文件（类似 cat）、-l/--level 过滤级别（none/minimal/aggressive，默认 none 即全量内容）、-m/--max-lines 与 --tail-lines（保留最后 N 行，二者互斥）、-n 显示行号。即 rtk read file.rs -l aggressive 只保留签名、剥离函数体。

Git 类

rtk git status                  # 紧凑状态
rtk git log -n 10               # 单行提交
rtk git diff                    # 压缩后的 diff
rtk git push                    # 输出形如 "ok main"

写操作类命令（add/commit/push/pull）被压缩为一行确认信息（如 ok abc1234、ok 3 files +10 -2），实现位于 src/cmds/git/git.rs。

测试类

rtk jest                        # Jest 紧凑输出（仅失败项）
rtk vitest                      # Vitest 紧凑输出（仅失败项）
rtk pytest                      # Python 测试（-90%）
rtk go test                    # Go 测试（-90%）
rtk test <cmd>                 # 通用测试包装器，仅显示失败（-90%）

rtk test <cmd> 是一个泛化包装器：对任意测试命令只保留失败内容；go test 的过滤器会直接解析 Go 1.24+ 的 NDJSON 输出（见 src/cmds/go/go_cmd.rs）。

构建与 Lint 类

rtk lint                        # ESLint 按规则/文件分组
rtk tsc                         # TypeScript 错误按文件分组
rtk cargo build                 # Cargo 构建（-80%）
rtk ruff check                  # Python lint（-80%）

分析类（token 经济学看板）

rtk gain                        # 节约统计
rtk gain --graph                # ASCII 图形（近 30 天）
rtk discover                    # 发现被遗漏的节约机会

rtk gain 的参数面比日文 README 更广，从 src/main.rs 的 Commands::Gain 定义可以看到完整参数列表：

参数	作用
-p, --project	只统计当前项目（当前工作目录）的记录
-g, --graph	显示每日节约的 ASCII 图
-H, --history	显示最近的命令历史
-q, --quota	显示月度配额节约估算（可配合 --tier pro/5x/20x，默认 20x）
--daily / --weekly / --monthly / --all	按日/周/月/全维度拆分
-f, --format	输出格式：text（默认）、json、csv
-F, --failures	显示解析失败日志（回退为原始执行的命令）
--reset（配 --yes 跳过确认）	将统计清零

数据存储在本地 SQLite（~/.local/share/rtk/tracking.db，macOS 为 ~/Library/Application Support/rtk/tracking.db，Windows 为 %APPDATA%\rtk\tracking.db），保留期默认 90 天自动清理（src/core/tracking.rs）。rtk discover 的实现则在 src/discover/ 模块，用于扫描历史中未被压缩或压缩率低的命令，提示“还有哪些命令可以接入 RTK”。

配置与故障排查

RTK 的配置文件为 ~/.config/rtk/config.toml（macOS：~/Library/Application Support/rtk/config.toml），完整的配置参考见 docs/guide/getting-started/configuration.md，核心结构如下：

[tracking]
enabled = true              # 开关 token 追踪
history_days = 90           # 保留天数（自动清理）
database_path = "/custom/path/history.db"   # 可选覆盖

[display]
colors = true               # 彩色输出
emoji = true                # 输出中使用 emoji
max_width = 120             # 最大输出宽度

[filters]
# 作用于文件读取类命令（ls、find、grep、cat/rtk read）
ignore_dirs = [".git", "node_modules", "target", "__pycache__", ".venv", "vendor"]
ignore_files = ["*.lock", "*.min.js", "*.min.css"]

[tee]
enabled = true              # 命令失败时保存原始输出
mode = "failures"           # "failures"（默认）、"always"、"never"
max_files = 20              # 轮转：保留最近 N 个文件
max_file_size = 1048576     # 单文件上限 1 MB（字节）

[telemetry]
enabled = true              # 匿名每日上报

[hooks]
exclude_commands = []       # 永不自动改写的命令

其中两个机制值得注意：

• Tee 系统：命令失败时，RTK 会把完整原始输出存到本地文件并打印路径，例如 FAILED: 2/15 tests 后附 [full output: ~/.local/share/rtk/tee/1707753600_cargo_test.log]。AI 助手可以直接读取该文件获得细节，无需重跑命令——这保证了“压缩输出”与“可恢复完整现场”之间的平衡。
• 排除改写：[hooks] exclude_commands 支持前缀与正则（^ 开头）匹配，例如 exclude_commands = ["^curl", "git rebase"]；对单次执行可用环境变量绕过：RTK_DISABLED=1 git rebase main。相关环境变量还有 RTK_TEE_DIR（覆盖 tee 目录）、RTK_TELEMETRY_DISABLED=1（禁用遥测）、RTK_HOOK_AUDIT=1（启用 Hook 审计日志）。

配置解析的实现在 src/core/config.rs，Hook 侧的排除规则匹配在 src/hooks/ 模块中处理。

延伸阅读与许可

围绕本文主题，仓库内还有几份值得深入阅读的文档：

• INSTALL.md——详细安装参考（含预构建二进制与 Windows/WSL 说明）；
• docs/contributing/ARCHITECTURE.md——系统架构、过滤分类学、六阶段命令生命周期与构建优化；
• docs/TELEMETRY.md——遥测字段、数据边界与贡献者指引；
• docs/usage/FEATURES.md 与 docs/usage/TRACKING.md——功能清单与追踪系统的使用视角；
• DISCLAIMER.md——免责声明；
• 许可：Apache 2.0，见 LICENSE。

总结：RTK 的价值主张非常克制且可验证——它压缩的是命令行输出这一种输入 token 来源，口径是 bytes / 4 的估算百分比，数据全部保存在本地 SQLite。理解了这套口径之后，你就可以放心地用 rtk gain --all --format json 之类的命令，在自己的 Agent 工作流里量化每一条过滤策略的真实收益。