RTK（Rust Token Killer）—— 安装、架构与深度使用指南

G_whang

508人浏览 · 2026-06-13 11:21:00

G_whang · 2026-06-13 11:21:00 发布

1. 概述：为什么需要 RTK

AI 编程助手（Claude Code、Cursor、Codex 等）在执行 git status、cargo test、npm test 等命令时，会将完整的原始输出送入 LLM 上下文窗口。测试框架的一次运行可能产生 5,000–10,000 tokens 的输出，而其中 90% 是冗余信息。

RTK 是一个 Rust 编写的 CLI 代理，位于 AI Agent 和 Shell 之间，自动拦截命令、压缩输出后再送入 LLM。平均节省 60–90% Token，单二进制文件，零依赖，<10ms 开销。

核心数据

指标	数值
GitHub Stars	56,000+
平均压缩率	89%
额外延迟	<10ms
支持命令	100+
二进制大小	~3.8 MB（静态链接）
支持 AI 工具	14+（Claude Code、Cursor、Copilot、Gemini CLI、Codex 等）
许可协议	MIT
最新版本	v0.38.x

实测效果

场景	原始 Token	RTK 后	节省率
`cargo test`（262 tests）	~4,823	~11	99.8%
`git status`	~3,000	~600	80%
`pytest`（33 tests）	~8,000	~256	96.8%
30 分钟完整开发会话	~150,000	~16,850	88.9%
长期统计（15,720 条命令）	—	—	83.7%（1.38 亿 Token）

2. 架构原理

2.1 整体数据流

无 RTK:                              有 RTK:

Claude --git status--> Shell --> Git   Claude --git status--> RTK --> Git
  ^                         |           ^                  |         |
  |     ~3,000 tokens 原始   |           |   ~600 tokens    | 过滤    |
  +-------------------------+           +--- (已压缩) -----+---------+

RTK 通过 PreToolUse Hook 在 Claude Code 执行命令前静默改写命令，Claude Code 完全无感知。

2.2 四步改写管线

Claude Code 执行 "git status"
       │
       ▼
  [PreToolUse Hook 拦截]          ← rtk-rewrite.sh（4 状态状态机）
       │
       ▼
  "rtk rewrite" → "rtk git status"  ← Rust 二进制改写命令
       │
       ▼
  RTK 执行 → 4 种策略过滤 → 输出压缩版  ← Rust 过滤管线
       │
       ▼
  Claude Code 看到 ~80% 更少的 Token

2.3 PreToolUse Hook——4 状态状态机

Hook 脚本通过不同退出码控制命令流转：

退出码	行为	JSON 输出
0 + JSON	允许并改写 —— `permissionDecision: "allow"` + `updatedInput`	命令已改写，自动批准
1（无 JSON）	透传 —— Hook 无操作，原命令直接执行	无
2（无 JSON）	拒绝移交 —— 交由 Claude Code 原生拒绝规则处理	无
3 + JSON	询问 —— 改写命令但省略 `permissionDecision`，提示用户确认	改写后输入，无决策

关键安全机制：

Kill Switch：touch /tmp/agentkit-ccpack-pause 即时停止所有改写
版本守卫：解析 rtk --version，版本 < 0.23.0 则优雅退出
依赖守卫：检测 jq 可用性，缺失时告警退出（fail-open，不阻塞会话）
多 Hook 协调：RTK 通过补丁化插件缓存成为唯一的 Bash PreToolUse 处理器，同时将其他插件作为子进程调用，防止 Claude Code 丢弃 updatedInput

2.4 四种过滤策略

策略	说明	示例
智能过滤	去除注释、空白、样板提示文本	去掉 git status 的 `"use git add..."` 建议
分组聚合	将相似条目按类别归组	262 个通过测试 → 一行计数
截断	保留关键结构，裁剪次要细节	保留失败堆栈，压缩日志前缀
结构化摘要	保留失败追踪原文，压缩通过输出	只展示失败用例的完整断言信息

2.5 Tee 模式——失败时保留完整输出

当命令失败时，RTK 将完整未过滤输出保存到 ~/.local/share/rtk/tee/，LLM 无需重新执行即可读取：

✓ 42 passed, 1 failed (3.2s)
FAIL: test_parse_complex_input - assertion failed at src/filter.rs:142
📄 Full output: ~/.local/share/rtk/tee/cargo-test-2026-02-12-143052.log

配置项（config.toml）：

[tee]
enabled = true        # 失败时保存原始输出（默认开启）
mode = "failures"     # "failures"、"always" 或 "never"
max_files = 20        # 轮转上限

3. 安装

3.1 方式一：Homebrew（macOS 推荐）

brew install rtk

3.2 方式二：Shell 脚本（Linux / macOS）

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

安装到 ~/.local/bin，需确保该目录在 PATH 中。

3.3 方式三：Cargo

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

3.4 方式四：预编译二进制

从 GitHub Releases 下载对应平台的二进制：

macOS：x86_64 / aarch64
Linux：musl / gnu
Windows：msvc

3.5 验证安装

rtk --version   # 应显示 "rtk 0.38.x"
rtk gain        # 应显示 Token 节省统计（区分正版的关键步骤）

⚠️ 注意：crates.io 上存在同名项目 “Rust Type Kit”，安装后务必运行 rtk gain 确认安装的是正确的 rtk-ai/rtk。

4. 配置与初始化

4.1 全局初始化（推荐）

# 安装 Hook + RTK.md + 补丁 settings.json
rtk init -g

# 非交互模式（CI/CD）
rtk init -g --auto-patch

# 仅安装 Hook，不添加 RTK.md
rtk init -g --hook-only

rtk init -g 自动完成：

在 ~/.claude/settings.json 注册 PreToolUse Hook
在 CLAUDE.md 中注入 RTK 使用指令
配置 Hook 版本标记和完整性哈希

4.2 按 AI 工具初始化

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 hermes           # Hermes
rtk init --agent antigravity      # Google Antigravity

4.3 配置文件

配置文件位于 ~/.config/rtk/config.toml（macOS: ~/Library/Application Support/rtk/config.toml）：

[hooks]
# 跳过这些命令的改写（直接透传）
exclude_commands = ["curl", "playwright"]

[tee]
enabled = true        # 失败时保存原始输出
mode = "failures"     # "failures"、"always" 或 "never"
max_files = 20        # 轮转上限

4.4 卸载

rtk init -g --uninstall  # 移除 Hook、RTK.md、settings.json 条目
brew uninstall rtk        # 如通过 Homebrew 安装
cargo uninstall rtk       # 如通过 Cargo 安装

5. Windows 支持

5.1 现状

Unix 平台上，rtk init -g 安装 OS 级别的 PreToolUse Hook，可靠性 ~100%。Windows 上原生不支持 Hook 自动改写，需采用以下替代方案：

方案	机制	可靠性
Unix `rtk init -g`	PreToolUse Hook（OS 级）	~100%
Windows 默认回退	CLAUDE.md 指令注入	~70–80%
Windows + PowerShell Hook	原生 PreToolUse Hook	~100%
Windows + Git Bash Hook	PreToolUse Hook（通过 bash.exe）	~100%
WSL（推荐）	完整的 Unix Hook 机制	~100%

5.2 推荐方案

WSL 中获得完整体验：在 WSL 中按 Unix 方式安装，所有功能完全可用。

6. 支持的命令完整列表（100+）

6.1 文件与搜索

命令	说明
`rtk ls`	Token 优化的目录树
`rtk read <file>`	智能文件读取
`rtk read <file> -l aggressive`	仅保留签名（剥离函数体）
`rtk smart <file>`	2 行启发式代码摘要
`rtk find "*.rs" .`	紧凑查找结果
`rtk grep "pattern" .`	分组搜索结果
`rtk diff <f1> <f2>`	压缩差异对比
`rtk cat / tree / rg`	别名，同上

6.2 Git

命令	说明	压缩率
`rtk git status`	紧凑状态	-80%
`rtk git log -n 10`	单行提交记录	-
`rtk git diff`	压缩 diff	-85%
`rtk git add / commit / push / pull`	返回简洁确认	-
`rtk git branch / fetch / stash / show`	紧凑输出	-

6.3 GitHub CLI

命令	说明
`rtk gh pr list`	紧凑 PR 列表
`rtk gh pr view 42`	PR 详情 + Checks
`rtk gh issue list`	Issue 列表
`rtk gh run list`	Workflow 运行状态
`rtk gh api / release`	紧凑 API 响应

6.4 测试框架

命令	说明	压缩率
`rtk cargo test`	Rust 测试	-90%
`rtk pytest`	Python 测试	-90%
`rtk go test`	Go 测试（NDJSON）	-90%
`rtk jest / vitest`	JS/TS 测试（仅失败）	-
`rtk playwright test`	E2E 结果（仅失败）	-
`rtk rspec`	Ruby RSpec（JSON）	-60%+
`rtk npm test`	npm 测试	-90%
`rtk test <cmd>`	通用测试包装器——仅失败	-90%
`rtk err <cmd>`	仅过滤错误输出	-

6.5 构建与 Lint

命令	说明	压缩率
`rtk cargo build`	Cargo 构建	-80%
`rtk cargo clippy`	Cargo Clippy	-80%
`rtk tsc`	TypeScript 编译错误（按文件分组）	-85%
`rtk next build`	Next.js 构建	-
`rtk lint`	ESLint（按规则/文件分组）	-
`rtk lint biome`	Biome linter	-
`rtk ruff check`	Python linting（JSON）	-80%
`rtk golangci-lint run`	Go linting（JSON）	-85%
`rtk rubocop`	Ruby linting（JSON）	-60%+
`rtk prettier --check .`	需要格式化的文件列表	-

6.6 包管理

命令	说明
`rtk pnpm list`	紧凑依赖树
`rtk pip list`	Python 包（自动检测 uv）
`rtk pip outdated`	过期包列表
`rtk uv pip`	UV pip 支持
`rtk bundle install`	Ruby gems（剥离 Using 行）
`rtk prisma generate`	Schema 生成（移除 ASCII 艺术）

6.7 AWS

命令	说明
`rtk aws sts get-caller-identity`	单行身份信息
`rtk aws ec2 describe-instances`	紧凑实例列表
`rtk aws lambda list-functions`	名称/运行时/内存（剥离密钥）
`rtk aws logs get-log-events`	仅时间戳消息
`rtk aws cloudformation describe-stack-events`	失败优先展示
`rtk aws dynamodb scan`	展开类型注解
`rtk aws iam list-roles`	剥离策略文档
`rtk aws s3 ls`	截断 + tee 恢复

6.8 容器

命令	说明
`rtk docker ps`	紧凑容器列表
`rtk docker images`	紧凑镜像列表
`rtk docker logs <container>`	去重日志
`rtk docker compose ps`	Compose 服务列表
`rtk docker run / build / exec`	紧凑运行/构建输出
`rtk kubectl pods`	紧凑 Pod 列表
`rtk kubectl logs <pod>`	去重日志
`rtk kubectl services`	紧凑服务列表
`rtk kubectl get / describe / apply`	紧凑操作输出

6.9 数据与分析

命令	说明
`rtk json config.json`	结构展示（不含值）
`rtk deps`	依赖摘要
`rtk env -f AWS`	过滤环境变量
`rtk log app.log`	去重日志
`rtk curl <url>`	截断 + 保存完整输出
`rtk wget <url>`	下载，剥离进度条
`rtk summary <cmd>`	启发式摘要
`rtk proxy <cmd>`	原始透传 + 追踪

7. Token 节省分析

7.1 `rtk gain`——核心分析命令

rtk gain                # 摘要统计
rtk gain --graph        # ASCII 图表（最近 30 天）
rtk gain --history      # 最近命令历史
rtk gain --daily        # 按日统计
rtk gain --all --format json  # JSON 导出（可用于仪表盘）

7.2 `rtk discover`——发现遗漏的节省机会

rtk discover                  # 扫描当天遗漏
rtk discover --all --since 7  # 所有项目，最近 7 天

7.3 `rtk session`——会话中 RTK 采纳率

rtk session   # 查看最近会话中 RTK 的使用占比

7.4 典型 30 分钟 Claude Code 会话 Token 流

操作	频率	原始 Token	RTK Token	节省
`ls` / `tree`	10×	2,000	400	-80%
`cat` / `read`	20×	40,000	12,000	-70%
`git status/diff/log`	20×	15,500	3,600	-77%
`cargo test` / `npm test`	5×	25,000	2,500	-90%
总计		~118,000	~23,900	-80%

8. 安全模型

机制	说明
Fail-Open	依赖缺失或版本不兼容时优雅退出，不阻塞会话
Kill Switch	`touch /tmp/agentkit-ccpack-pause` 即时停止所有改写
保守白名单	`docker run/exec/build` 等危险命令不改写，直接透传
原子写入	所有文件修改使用 `temp-file-then-rename`，绝不产生部分写入
版本守卫	自动检测 RTK 版本，过低版本不注入 Hook
Tee 恢复	失败时保留完整输出，LLM 可直接读取无需重新执行
无网络依赖	单静态二进制，无外部 API 调用
隐私	不发送数据到外部服务

8.1 安全白名单（保守策略）

主动不处理的命令类别：

docker run / exec / build
带有任意参数的 curl / wget
不受信任的第三方 CLI

9. 高级配置

9.1 Hook 跳过特定命令

[hooks]
exclude_commands = ["curl", "playwright", "terraform apply"]

9.2 开关 Tee 模式

[tee]
enabled = true
mode = "always"    # 无论成功失败都保留原始输出
max_files = 50     # 最多保留 50 个日志文件

9.3 验证 Hook 完整性

rtk verify   # 运行 145+ 完整性测试

10. 与同类工具对比

维度	RTK	Caveman	context-mode
设计定位	Shell 输出压缩代理	AI 回复压缩	沙箱执行 + 输出过滤
压缩目标	命令输出（git/test/lint 等）	LLM 回复文本	日志 / Web 抓取
压缩率	60–90%	65–75%	最高 98%
实现语言	Rust（单二进制）	TypeScript	TypeScript（沙箱）
额外延迟	<10ms	~100ms	~50ms
支持命令数	100+	N/A（回复层）	有限
Hook 集成	✅ PreToolUse 自动改写	❌	❌
跨 Agent	14+ 工具	Claude Code 专用	Claude Code 专用

11. 轻量分支：rtk-lite-cc

rtk-lite-cc 是专注 Claude Code 的精简分支：

剥离 ~15,000 行代码
移除：遥测、SQLite 数据库、Token 分析、CLAUDE.md 补丁、权限系统、非 Claude Agent
保留：完整过滤管线
纯单二进制，零网络调用

适用场景：对隐私极其敏感、只需 Claude Code 支持、偏好最小依赖。

12. 故障排查

问题	解决方案
`rtk` 命令找不到	检查 `~/.local/bin` 是否在 PATH 中；或重新执行安装脚本
`rtk gain` 无输出	确认安装了 `rtk-ai/rtk` 而非 crates.io 上的同名 “Rust Type Kit”
Hook 未生效（Unix）	运行 `rtk init -g` 重新注册；检查 `~/.claude/settings.json`
Hook 未生效（Windows）	使用 WSL 获得完整体验；或手动配置 PowerShell/Git Bash Hook
PreToolUse Hook 与其他插件冲突	RTK 自动协调多 Hook，通常无需手动处理
Hook 版本告警	运行 `rtk init -g` 更新版本标记
Tee 文件占用磁盘	调整 `max_files` 或设置 `mode = "failures"`
特定命令未改写	检查 `exclude_commands` 配置和命令白名单