RTK（Rust Token Killer）官方指南：Hook 拦截、输出过滤与 Token 节省度量的完整工作流

本篇技术文章以 RTK 官方文档指南首页（docs/guide/index.md）为骨架展开：先讲清 RTK「CLI 代理 + Hook 透明重写」的核心机制，再覆盖从安装初始化、命令过滤到 rtk gain / rtk discover / rtk session 节省度量与采用率分析的完整流程。读完后，你将能在自己的 AI 编程助手中接入 RTK，理解它压缩 bash 输出的底层策略，并会用分析命令量化与追踪 Token 节省效果。

一、RTK 是什么：站在 LLM 与开发工具之间的输出过滤器

RTK（Rust Token Killer）是一个 CLI 代理，部署在 AI 助手与开发工具之间。它在命令输出到达 LLM 之前进行过滤：只保留有信息量的内容，丢弃样板文本、进度条和噪音。

文档给出的量化结论是：每条命令到达 LLM 的 bash 输出字节最多减少 90%，且不改变你的任何工作流。以 git status 为例——你照常运行它，RTK 的 Hook 拦截该命令、过滤其输出，LLM 最终看到的是一份 3 行的紧凑摘要，而不是 40 行原始输出。

从源码结构看，这个「代理」的定位在 主入口文件 中体现得很直接：RTK 通过 clap 子命令路由（Commands::Git、Commands::Go、Commands::Pytest 等）按生态组织命令模块，每个命令模块独立实现「执行原命令 → 捕获输出 → 过滤压缩 → 记录节省量」的完整闭环。

二、How it works：Hook 拦截与透明重写流程

官方文档给出的端到端流程图是理解 RTK 的第一块拼图：

Your AI assistant runs:  git status
                              ↓
              Hook intercepts (PreToolUse)
                              ↓
              rtk git status  (transparent rewrite)
                              ↓
     Raw output: 40 lines     →     Filtered: 3 lines
                              ↓
              LLM sees the compact output

整个流程对你零配置——Hook 自动完成拦截与改写。其运行机制可拆解为三步：

1. 拦截：AI 助手（如 Claude Code）的 PreToolUse Hook 在命令执行前拿到原始命令字符串；
2. 改写：Hook 调用 RTK 二进制内置的 rtk rewrite 决策逻辑，将 git status 改写为 rtk git status。从 支持代理文档 可以确认，所有改写逻辑集中在 RTK 二进制（rtk rewrite）中，各 Agent 的 Hook 只是解析 Agent 专有 JSON 格式的薄委托层；
3. 过滤执行：被改写后的命令由 RTK 执行原始工具、捕获 stdout/stderr，按策略过滤后再输出。

[ARCHITECTURE.md](https://gitcode.com/GitHub_Trending/rtk4/rtk/blob/e8541d1e1180f7ef4c736322cedc8e834f2f8f77/docs/contributing/ARCHITECTURE.md?utm_source=gitcode_repo_files) 进一步将单次命令的执行拆解为六个阶段：

Phase 1: PARSE    — clap 解析子命令与参数（如 verbose、ultra_compact 标志）
Phase 2: ROUTE    — main.rs 按子命令分发到对应模块（git::run 等）
Phase 3: EXECUTE  — std::process::Command 执行原始命令，捕获 stdout/stderr/exit_code
Phase 4: FILTER   — 按该命令类型的过滤策略压缩输出
Phase 5: PRINT    — 输出彩色紧凑结果（-v 系列标志可逐级输出调试信息）
Phase 6: TRACK    — tracking::track() 将输入/输出字节数换算为估算 token 并写入 SQLite

其中 Phase 6 是后文 rtk gain 度量的数据来源。此外架构文档还强调四条设计原则，对使用者很重要：退出码保真（CI/CD 依赖的失败信号不被代理吞掉）、Fail-Safe（过滤失败时回退原始输出）、透明可调试（-v/-vv/-vvv 逐级显示调试信息、执行命令与过滤前原始输出）、最小开销（每条命令约 5–15ms 的代理开销）。

三、What the savings mean：90% 到底省的是什么

这是官方指南中特意单列一节澄清的概念边界，使用 RTK 时应准确理解：

• RTK 减少的是 bash 输出字节——shell 命令回传给 Agent 之前发送的输出；
• bash 输出只是 input tokens 的贡献者之一，与你的提示词、系统提示词、对话历史并列；
• input tokens 又只是账单的一部分，账单还计 output tokens；
• 因此压缩比例在每一层都被稀释——「bash 输出减少 90%」不等于「账单减少 90%」。

在 token 估算的实现上，RTK 按设计不内置任何真实分词器（嵌入分词器会增加启动耗时，且每个模型/会话都需要对应的 tokenizer）。从 token 跟踪实现 可以看到估算函数：

/// tokens = ceil(chars / 4)
(text.len() as f64 / 4.0).ceil() as usize

即 estimate_tokens(text) = ceil(bytes / 4)。由于同一估算器同时应用于原始输出与过滤后输出，百分比是可靠的，但绝对 token 数是近似值，不会与服务商账单逐一对应。这也是 Token Savings Analytics 中反复强调「Save% 是 bash 输出字节比例，不是账单占比」的原因。

四、What RTK optimizes：覆盖的命令生态

RTK 覆盖主流生态的数十条命令。从 src/cmds 的目录结构可以核对各生态的模块划分：

生态	模块目录	代表命令与过滤机制
Git / GitHub	git	git status（紧凑 stat 分组）、git diff（削减上下文）、git log（仅 hash/作者/标题）、gh pr list、glab
Rust	rust	cargo test/build/clippy（失败聚焦），rtk err、rtk test 通用失败过滤器
JS/TS	js	lint（按规则/文件分组）、tsc（按文件分组）、vitest/playwright（仅失败）、next build、pnpm list、prettier、prisma
Python	python	pytest（状态机解析、traceback 裁剪）、ruff check（JSON 按规则分组）、mypy、pip、uv run
Go	go	go test（NDJSON 逐行解析、仅失败）、golangci-lint run（JSON 按 linter 分组）
Ruby	ruby	rake test（minitest 状态机）、rspec、rubocop
.NET / JVM	dotnet、jvm	dotnet build/test、TRX 解析、mvn/mvnd、sbt、gradlew
PHP	php	phpunit、pest、ecs、phpstan、pint、artisan
云与容器	cloud	aws（STS/EC2/Lambda/S3 等）、docker/kubectl/oc（紧凑列表 + 日志去重）、curl/wget（截断 + 进度条剥离）、psql
系统通用	system	ls/tree（目录树 + 文件计数）、read（签名式智能读文件）、grep（截断 + 按文件分组）、find、json（只留结构）、log（重复行折叠计数）、env、deps

按架构文档的口径，各生态的 bash 输出压缩率大致为：Git 85–99%、JS/TS 70–99%、Python 70–90%、Go 75–90%、Ruby 60–90%、.NET 70–85%、云 60–80%、Rust 60–99%、系统命令 50–90%。

这些压缩由一整套过滤策略支撑。架构文档归纳了 12 类策略（统计提取、仅错误、模式分组、去重、仅结构、代码过滤、失败聚焦、树压缩、进度过滤、JSON/文本双模式、状态机解析、NDJSON 流式解析），Token Savings Analytics 给出了几条典型命令的机制对照：git status 77–93%（紧凑 stat）、eslint 84%（按规则分组）、jest/vitest 94–99%（仅显示失败）、find 75%（树形格式）、grep 70%（截断 + 分组）。

五、快速开始：安装、验证与初始化

官方指南的 Get started 三步为：安装 → 5 分钟接入 AI 助手 → 确认 Agent 支持。以下是结合仓库文档的完整操作路径。

1. 安装

安装方式详见 Installation：

# Quick Install（Linux/macOS，安装到 ~/.local/bin）
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh

# 或 Homebrew
brew install rtk-ai/tap/rtk

# 或 Cargo（必须显式指定 Git URL）
cargo install --git https://github.com/rtk-ai/rtk --branch master rtk

重名冲突警告（安装文档专门强调）：crates.io 上存在另一个同名项目 Rust Type Kit（reachingforthejack/rtk），cargo install rtk 可能装错包。最可靠的判别方式是运行 rtk gain——它应显示节省量看板；若报 command not found，说明装错了包或未装成功。

2. 验证

rtk --version   # 应输出 rtk x.y.z
rtk gain        # 应显示节省量看板

3. 初始化：为 Agent 安装 Hook

Quick Start 给出的核心步骤：

# Claude Code（全局，应用到所有项目）
rtk init --global

# 仅当前项目
cd /your/project && rtk init

# 其他 Agent（--agent 指定目标）
rtk init -g --gemini            # Gemini CLI
rtk init -g --codex             # Codex (OpenAI)
rtk init -g --agent cursor      # Cursor
rtk init -g --agent windsurf    # Windsurf
rtk init --agent cline          # Cline / Roo Code
rtk init --agent kilocode       # Kilo Code
rtk init --agent antigravity    # Google Antigravity
rtk init -g --agent pi          # Pi
rtk init --agent hermes         # Hermes
rtk init -g --agent droid       # Factory Droid

安装后重启 AI 助手。此后你照常使用工具：例如 Claude Code 执行 cargo test 时，Hook 在执行前将其改写为 rtk cargo test，LLM 收到的只有失败用例，而不是 500 行通过的测试输出——你始终不会看到或手打 rtk 前缀。

两个实用细节：

• --dry-run 预演：rtk init --global --dry-run 会以 [dry-run] would ... 前缀打印所有将要创建/修改/打补丁的文件，然后以 [dry-run] Nothing written. 结束，磁盘零改动，且跳过遥测同意提示；配合 -v 还能查看将要写入的完整内容。所有 init 变体（含 --uninstall）均支持，但不能与 --show 组合。
• Hook 的作用域限制：Hook 只对 Bash 类工具调用生效。Claude Code 的内置 Read、Grep、Glob 工具不经过 Bash Hook，不会被自动改写；若希望这些工作流也走 RTK 过滤，应使用 shell 命令（cat/rg/find）或直接调用 rtk read、rtk grep、rtk find。
• 不支持的命令走 passthrough：输出原样透传但用量仍被记录，可显式用 rtk proxy <cmd>。

六、Measure your savings：用 rtk gain 量化节省

官方指南给出的三个核心命令：

rtk gain           # 所有会话的累计节省
rtk gain --daily   # 按天拆分
rtk gain --weekly  # 按周聚合

Token Savings Analytics 文档给出了完整的命令行参考：

# 时间维度拆分
rtk gain --daily          # 从开始追踪以来的所有天
rtk gain --weekly         # 按周聚合（周日-周六）
rtk gain --monthly        # 按月聚合
rtk gain --all            # 一次性输出所有拆分

# 经典标志
rtk gain --graph          # ASCII 图（最近 30 天）
rtk gain --history        # 最近 10 条命令
rtk gain --quota          # 月度配额节省估算（默认 20x 档）
rtk gain --quota -t pro   # 使用 pro 档 token 预算做估算

# 导出
rtk gain --all --format json > savings.json
rtk gain --all --format csv  > savings.csv

--daily 的输出示例（数字为示例值，实际取决于你运行了哪些命令）：

Date            Cmds      Input     Output      Saved   Save%
────────────────────────────────────────────────────────────────
2026-01-28        89     380.9K      26.7K     355.8K   93.4%
2026-01-29       102     894.5K      32.4K     863.7K   96.6%
────────────────────────────────────────────────────────────────
TOTAL            196       1.3M      59.2K       1.2M   95.6%

各列含义：Cmds 为执行的 RTK 命令数；Input/Output 分别为原始输出与过滤后输出按 bytes / 4 估算的 token 数；Saved = Input − Output；Save% = Saved / Input × 100，是bash 输出字节比例。

这些数据背后的存储与计算链路可以从源码核实：

• 每次命令执行后，tracking::track() 将 timestamp、original_cmd、rtk_cmd、input_tokens、output_tokens、saved_tokens、savings_pct、exec_time_ms 写入 SQLite，库文件位于 ~/.local/share/rtk/history.db（Linux/macOS），跨项目与跨 Claude 会话全局共享，保留 90 天并自动清理；
• 可用 sqlite3 ~/.local/share/rtk/history.db "SELECT COUNT(*) FROM commands" 直接检查原始数据，也可 cp 备份或在删除该文件后重置（下次命令执行时自动重建）。

分析工作流方面，文档提供了三类可直接套用的模板：每周一生成 CSV 周报（rtk gain --weekly --format csv > reports/week-$(date +%Y-%W).csv）、cron 每日 JSON 快照供仪表盘消费（0 0 * * * rtk gain --all --format json > /var/www/dashboard/rtk-stats.json）、以及 GitHub Actions 每周提交统计 JSON 的完整 workflow。此外 --quota 将估算节省量表达为某订阅档月度 token 预算的占比（pro/5x/20x 档位），但由于其分母同样来自 bytes / 4 估算，应视为数量级参考而非账单预测。

七、Analyze your usage：rtk discover 与 rtk session

指南的第二个度量维度是「没省到的部分」与「采用率」，对应 Discover and Session 文档中的两条命令。

rtk discover：找出漏掉的节省机会

rtk discover 分析 Claude Code 的命令历史，识别未经过 RTK 过滤就执行过的命令，并估算 RTK 本可压缩掉的 bash 输出量：

rtk discover                    # 分析当前项目的历史
rtk discover --all              # 所有项目
rtk discover --all --since 7    # 最近 7 天，所有项目

输出示例（数字为示例）：

Missed savings analysis (last 7 days)
────────────────────────────────────
Command              Count   Est. lost
cargo test              12     ~48,000 tokens
git log                  8     ~12,000 tokens
pnpm list                3      ~6,000 tokens
────────────────────────────────────
Total missed:           23     ~66,000 tokens

同样注意：~N tokens 是估算的 bash 输出字节除以 4，不是服务商计费的 token 数。若安装 RTK 后命令仍出现在漏省清单里，通常说明该 Agent 的 Hook 未激活。

rtk session：按会话统计采用率

rtk session

输出每个近期 Claude Code 会话中经 RTK 执行的 shell 命令数与原始命令数的比值：

Session                         Total   RTK   Coverage
2026-04-06 14:32  (45 cmds)       45    43      95.6%
2026-04-05 09:14  (38 cmds)       38    38     100.0%
─────────────────────────────────────────────────────
Average coverage: 96.6%

某个会话覆盖率偏低，通常意味着该时段 RTK 被 RTK_DISABLED=1 临时禁用，或某个子 Agent 的 Hook 未生效。

八、配置速览：config.toml、环境变量与 Tee 恢复

Configuration 文档对应指南 Further reading 中提到的「config.toml、全局标志、环境变量、tee 恢复」四项能力。配置文件位置：Linux 为 ~/.config/rtk/config.toml，macOS 为 ~/Library/Application Support/rtk/config.toml。可用 rtk config 查看当前配置、rtk config --create 生成带默认值的配置模板。

完整配置结构：

[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（字节）
# directory = "/custom/tee/path"  # 可选覆盖

[telemetry]
enabled = true              # 匿名每日上报——详见 Telemetry & Privacy

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

环境变量覆盖：

变量	作用
RTK_DISABLED=1	对单条命令禁用 RTK（RTK_DISABLED=1 git status 执行原始命令）
RTK_TEE_DIR	覆盖 tee 目录
RTK_TELEMETRY_DISABLED=1	禁用遥测（无视同意状态）
RTK_HOOK_AUDIT=1	启用 Hook 审计日志
SKIP_ENV_VALIDATION=1	跳过环境校验（配合 Next.js 时有用）

Tee 恢复机制值得单独说明：命令失败时，RTK 将完整未过滤输出保存到本地文件并在摘要中打印路径（见 tee 实现）：

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

这样 AI 助手需要更多细节时可直接读取该文件，而无需重新执行命令——在「压缩输出」与「不丢现场」之间取得平衡。全局标志方面，所有命令支持 -u/--ultra-compact（ASCII 图标 + 单行内联格式，进一步压缩）与 -v/--verbose（-v/-vv/-vvv 三级调试）。

九、支持的 Agent 与集成层级

RTK 支持 16 款 AI 编码工具。从仓库结构看，各 Agent 的接入实现分别位于 hooks 目录（claude/、cursor/、copilot/、hermes/、opencode/、pi/、openclaw/ 等），OpenClaw 插件 则是独立的 TypeScript 插件包。

Supported Agents 文档将集成划分为三个层级：

层级	机制	改写方式
Full hook	Shell 脚本或 Rust 二进制，经 Agent API 拦截	透明——Agent 永远看不到原始命令（Claude Code、Cursor、Gemini CLI、Copilot、Factory Droid、Mistral Vibe 等）
Plugin	Agent 插件系统中的 TS/JS/Python	Agent 允许时原位改写（OpenCode tool.execute.before、Pi tool_call、Hermes 终端命令改写）
Rules file	提示词级指令	仅引导——告知 Agent 优先使用 rtk <cmd>（Cline、Windsurf、Codex、Kilo Code、Antigravity）

各 Agent 的安装命令速查（完整卸载与升级说明见该文档）：

rtk init --global                  # Claude Code（Hook + 补丁 settings.json）
rtk init --global --agent cursor  # Cursor（preToolUse + updated_input）
rtk init --copilot                 # Copilot 项目级（.github/hooks/）
rtk init --global --copilot        # Copilot 用户级（~/.copilot/hooks/，尊重 $COPILOT_HOME）
rtk init --global --gemini         # Gemini CLI（BeforeTool）
rtk init --global --opencode       # OpenCode 插件（~/.config/opencode/plugins/rtk.ts）
rtk init --agent pi --global       # Pi 扩展（~/.pi/agent/extensions/rtk.ts）
rtk init --codex                    # Codex（AGENTS.md 指令）
rtk init --agent hermes            # Hermes Python 插件适配器（hooks/hermes/）
rtk init -g --agent droid          # Factory Droid（~/.factory/hooks.json，matcher Execute）
rtk init -g --agent vibe            # Mistral Vibe（~/.vibe/hooks.toml）

两个工程化细节：

• 优雅降级：Hook 永远不会阻塞命令执行。RTK 二进制缺失、JSON 输入非法、版本过旧或过滤逻辑出错时，Hook 干净退出（exit 0）或回退，原始命令照常运行；
• 单命令覆盖：RTK_DISABLED=1 git status 可临时跳过改写；也可在 [hooks] exclude_commands 中永久排除特定命令（如 ["git rebase", "git cherry-pick"]）。

十、Further reading：继续深入的路径

沿着官方指南首页的 Further reading 线索，结合仓库中的对应文档与源码，推荐的深入路径如下：

• 配置：Configuration —— config.toml 全量字段、环境变量、tee 恢复的完整语义；
• 节省原理：Token Savings Analytics —— 从 bytes / 4 估算到数据库 schema 的完整推导；
• 架构设计：ARCHITECTURE.md —— 六阶段命令生命周期、12 类过滤策略矩阵、SQLite 追踪系统、退出码保真策略，面向贡献者的系统级参考；
• 遥测与隐私：TELEMETRY.md —— 采集字段清单、GDPR 依据与退出机制（rtk telemetry status/enable/disable/forget）；
• 源码入口：主路由 查看命令分发与 AgentTarget 枚举（10 种 Agent 目标）；core 基础设施 中的 tracking.rs、tee.rs、config.rs、toml_filter.rs 分别对应追踪、失败恢复、配置解析与自定义 TOML 过滤器；
• 测试验证：tests 目录 收录了大量真实命令输出的 fixture（mvn、gradlew、ctest、sbt、glab、tsc 等）与对应的过滤逻辑测试，如 guard_integration_test.rs、grep_faithful_format_test.rs，可作为理解各过滤器边界行为的参照。

小结：RTK 的价值链路可以概括为——Hook 透明改写（rtk init）→ 按命令类型过滤 bash 输出（12 类策略）→ 本地 SQLite 记录每次的输入/输出字节（bytes / 4 估算）→ 用 rtk gain 看总节省、用 rtk discover 查漏网之鱼、用 rtk session 盯采用率。理解「压缩的是 bash 输出字节而非账单比例」这一边界后，你即可把它作为 AI 编程工作流中一套可量化、可配置、可优雅降级的输出治理层来使用。