rtk（Rust Token Killer）使用指南：用 CLI 代理把 LLM 读取的 Shell 输出压缩至多 90%

rtk 是一个高性能的 CLI 代理，它拦截开发命令、过滤并压缩其输出，再把这些"瘦身"后的结果交给 LLM 编码代理读取，从而把代理读取的 bash 输出削减最高 90%。本文基于仓库的西班牙语 README（README_es.md）展开，结合源码印证其命令体系、节省原理、安装方式、自动重写 hook 与节省量分析机制，帮助你把 rtk 接入 Claude Code 等 AI 工具并量化实际收益。

rtk 做了什么：按命令类型压缩输出

rtk 的核心行为可以概括为一句话：在命令输出进入 LLM 上下文之前，先做过滤和压缩。它是单个 Rust 二进制文件、零运行时依赖，代理开销小于 10ms（见 ARCHITECTURE.md 中对 ~5-15ms 代理开销的说明）。

不同命令类型对应的压缩策略如下（继承自 README_es.md 的操作表）：

操作	RTK 对输出做了什么
ls / tree	输出带文件计数的目录树，而不是每个条目一行
cat / read	智能读取：优先保留签名和结构，而非完整函数体
grep / rg	截断超长行，按文件分组匹配结果
git status	紧凑的 stat 格式，按状态分组
git diff	减少上下文行数，去掉文件头信息
git log	只保留 hash、作者和标题
git add/commit/push	输出一行确认信息，而不是完整进度输出
cargo test / npm test	只显示失败的测试，通过的测试折叠成计数
ruff check	按规则和文件分组
pytest	只显示失败项，traceback 被裁剪
go test	解析 NDJSON 事件流，只显示失败
docker ps	只保留关键字段

从 ARCHITECTURE.md 的"过滤策略分类"看，上述行为背后是一套更完整的策略体系，例如：统计提取（Stats Extraction）、失败聚焦（Failure Focus）、日志去重（Deduplication，将重复行折叠为 "[ERROR] ... (×5)"）、树压缩（Tree Compression）、进度条过滤（Progress Filtering）、状态机解析（pytest 文本解析）以及 NDJSON 流式解析（go test）。这些策略与 src/cmds/ 下按生态系统组织的命令模块一一对应（git、rust、js、python、go、ruby、cloud、system 等）。

节省量是怎么算的：读懂 90% 这个数字

README_es.md 特别强调了一个容易被误解的点：

1. rtk 削减的是"代理读取的 bash 输出"，不是你的账单。bash 输出只是输入 token 的一个组成部分，与你的 prompt、系统提示词和对话历史并列；而输入 token 也只是账单的一部分，账单还要计入输出 token。因此"削减 90% 的 bash 输出"不等于"账单下降 90%"，每经过一个环节折损都会被稀释。
2. token 数按 bytes / 4 估算。rtk 不捆绑任何 tokenizer，所以百分比是可靠的，但绝对 token 数是近似值。

这一点在源码中有直接对应：estimate_tokens 函数实现为 ceil(字节数 / 4)，注释明确说明这是"~4 字符 = 1 token"的快速启发式（约 4 chars per token），适合跟踪用途，若需精确计数应接入 LLM 的 tokenizer API。

// src/core/tracking.rs
pub fn estimate_tokens(text: &str) -> usize {
    // ~4 chars per token on average
    (text.len() as f64 / 4.0).ceil() as usize
}

对应文件：estimate_tokens 实现。

安装

Homebrew（推荐）

brew install rtk

快速安装（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

当前仓库 Cargo.toml 中的版本号为 0.42.4（version = "0.42.4"，Rust edition 2021），而 README_es 中"应显示 rtk 0.27.x"的版本说明落后于代码实际版本，实际以 rtk --version 输出为准。

提示：英文 README 中提到 crates.io 上存在另一个同名项目 "rtk"（Rust Type Kit）。如果 rtk gain 报错，大概率是装错了包，此时应改用上面的 cargo install --git 方式。

验证安装

rtk --version   # 应显示 rtk x.y.z
rtk gain        # 应显示节省量统计面板

从源码结构看，release 构建启用了 opt-level = 3、LTO、codegen-units = 1、panic = "abort" 和 strip（见 Cargo.toml 的 [profile.release] 段），目的是产出小体积、低启动开销的二进制。

快速上手：一条命令接入 AI 工具

# 1. 为你的 AI 工具安装 hook（以 Claude Code 为例，推荐全局）
rtk init --global

# 2. 重启 Claude Code，然后直接运行普通命令测试
git status  # 会被自动重写为 rtk git status

这里的"自动重写"是 rtk 的关键机制：hook 拦截 Bash 命令，在执行前将其改写为对应的 rtk 等价命令（例如 git status -> rtk git status），代理无需显式调用 rtk。命令重写逻辑的单一来源是 rtk rewrite 子命令（源码注释中给出用法示例：REWRITTEN=$(rtk rewrite "$CMD") || exit 0），各 AI 工具的 hook 实现位于 hooks/ 目录，覆盖 claude、copilot、cursor、gemini、codex、windsurf、cline 等多种代理，集成细节可参考 hooks/README.md。

需要注意的作用域限制：hook 只对 Bash 工具调用生效。像 Claude Code 内建的 Read、Grep、Glob 工具不经过 Bash hook，因此不会被自动重写；这类场景请直接用 shell 命令（cat/head/rg/find）或显式调用 rtk read、rtk grep、rtk find。

工作原理：四阶段压缩

rtk 在命令与 LLM 之间充当一个"过滤器层"：

  无 rtk：                                       有 rtk：

  Claude  --git status-->  shell  -->  git       Claude  --git status-->  RTK  -->  git
    ^                                   |           ^                      |          |
    |        ~2,000 tokens（原始）       |           |   ~200 tokens        | 过滤     |
    +-----------------------------------+           +-------（已过滤）----+----------+

针对每个命令类型，rtk 依次应用四种策略：

1. 智能过滤（Filtrado inteligente） — 去掉噪声（注释、空行、样板输出）；
2. 分组（Agrupación） — 聚合相似项（文件按目录、错误按类型）；
3. 截断（Truncamiento） — 保留相关上下文，砍掉冗余；
4. 去重（Deduplicación） — 将重复的日志行折叠为带计数的单行。

从源码看，一次 rtk <cmd> 的执行大致经历"解析参数 -> 路由到对应命令模块 -> 执行底层命令并捕获 stdout/stderr/exit code -> 按策略过滤 -> 打印并记录跟踪"的生命周期，详见 ARCHITECTURE.md 的六阶段执行流。所有路由入口集中在 src/main.rs 的 Commands 枚举中，可以从中看到 rtk 支持的完整命令面：ls、tree、read、smart、git、gh、aws、cargo、pytest、ruff、go、docker、kubectl、sbt、mvn、gradlew、gain、discover、rewrite、proxy 等。

两个全局参数值得注意（对应 src/main.rs 中 Cli 结构体的参数定义）：

-u, --ultra-compact    # ASCII 图标 + 单行内联格式，进一步压缩输出
-v, --verbose          # 逐级提高详细度（-v 调试信息 / -vv 显示执行的命令 / -vvv 显示过滤前的原始输出）

-v 系列同时是"透明性"保障：随时可以看到过滤前的原始输出。

常用命令速查

以下百分比均为 bash 输出字节数的削减比例（按 bytes/4 估算器测量），不是账单削减比例。

文件类

rtk ls .                        # 紧凑的目录树（带文件计数）
rtk read file.rs                # 智能读取：签名与结构优先
rtk find "*.rs" .               # 紧凑的查找结果
rtk grep "pattern" .            # 按文件分组的搜索结果

rtk grep 在 src/main.rs 中有专门的参数设计：--max-len（默认 80）控制单行最大长度，--max（默认 200）控制最多显示的匹配数；源码注释解释了为什么不使用短参数形式——因为 -l、-m、-t 分别是原生 grep/rg 的 --files-with-matches、--max-count、--type，若被 rtk 截获会静默改变原生工具行为。

Git

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

测试

rtk jest                        # Jest 紧凑输出
rtk vitest                      # Vitest 紧凑输出
rtk pytest                      # Python 测试（约 -90%）
rtk go test                     # Go 测试（NDJSON，约 -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（JSON，约 -80%）

分析类

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

节省量跟踪：rtk gain 的底层机制

rtk gain 之所以能展示节省统计，是因为每次 rtk <cmd> 执行后都会把指标写入本地 SQLite 数据库。从 src/core/tracking.rs 的实现看：

• 数据库位置：Linux 为 ~/.local/share/rtk/，macOS 为 ~/Library/Application Support/rtk/，数据库文件名常量为 history.db（见 src/core/constants.rs 中的 RTK_DATA_DIR 与 HISTORY_DB）；
• 每次记录：原始命令、rtk 命令、输入/输出 token 估算值、节省比例和执行耗时；
• 保留策略：默认 90 天（DEFAULT_HISTORY_DAYS: i64 = 90），每次插入时自动清理过期记录；
• 报告：rtk gain 汇总 total_commands、total_saved、avg_savings_pct 以及按命令、按天聚合的数据，GainSummary 结构体（src/core/tracking.rs）即为 rtk gain 的数据模型，支持 text/json 等导出格式。

相关文档可参考 docs/guide/analytics/gain.md。

失败时保留原始输出（tee 机制）与配置

当命令失败时，rtk 会把未过滤的完整输出保存下来，让 LLM 无需重新执行命令即可读取原始信息，输出形如：

FAILED: 2/15 tests
[full output: ~/.local/share/rtk/tee/1707753600_cargo_test.log]

行为由 config.toml 中的 [tee] 段控制（默认开启，仅失败时保存）。用户配置位于 ~/.config/rtk/config.toml（macOS：~/Library/Application Support/rtk/config.toml）：

[hooks]
exclude_commands = ["curl", "playwright"]  # 这些命令不参与自动重写

[tee]
enabled = true          # 失败时保存原始输出（默认 true）
mode = "failures"       # "failures"、"always" 或 "never"

配置项在 src/core/config.rs 中定义为完整的 Config 结构体，除 [hooks]（exclude_commands、transparent_prefixes）和 [tee] 外，还有 tracking（开关、history_days、数据库路径）、display（颜色、emoji、最大宽度）、filters（忽略目录/文件）、telemetry 和 limits 等段。更完整的配置说明见 docs/guide/getting-started/configuration.md。

其他实用子命令

围绕"接入 AI 工具"这个主线，还有几个与日常使用直接相关的命令（均在 src/main.rs 的 Commands 枚举中定义）：

rtk init --show               # 查看当前 hook/集成安装状态
rtk init -g --uninstall       # 卸载 hook、RTK.md 与 settings.json 条目
rtk proxy <command>           # 不做过滤地透传执行，但仍记录使用量
rtk run <command>             # 经 sh -c 执行任意 shell 命令（无过滤无跟踪）
rtk session                   # 查看近期会话中 RTK 的采用情况
rtk telemetry status          # 遥测同意状态（默认关闭，需显式开启）

关于遥测：README.md 说明遥测默认禁用，需要显式 opt-in，且可用环境变量 RTK_TELEMETRY_DISABLED=1 无条件阻断；字段清单与数据处理说明见 docs/TELEMETRY.md。

文档索引、许可与免责声明

• INSTALL.md — 详细安装参考；
• docs/guide/getting-started/quick-start.md — 快速上手；
• docs/guide/getting-started/installation.md — 安装指南；
• docs/guide/getting-started/supported-agents.md — 受支持的 AI 代理；
• docs/contributing/ARCHITECTURE.md — 系统架构、过滤策略分类、token 跟踪与配置系统设计；
• docs/contributing/TECHNICAL.md — 端到端技术流程导览。

许可：Apache License 2.0，详见 LICENSE。免责声明见 DISCLAIMER.md。