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

G_whang2026-06-14 8:25

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）：

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

3. 安装

3.1 方式一：Homebrew（macOS 推荐）

bash 复制代码 
brew install rtk

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

bash 复制代码 
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

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

3.3 方式三：Cargo

bash 复制代码 
cargo install --git https://github.com/rtk-ai/rtk

3.4 方式四：预编译二进制

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

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

3.5 验证安装

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

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

4. 配置与初始化

4.1 全局初始化（推荐）

bash 复制代码 
# 安装 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 自动完成：

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

4.2 按 AI 工具初始化

bash 复制代码 
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）：

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

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

4.4 卸载

bash 复制代码 
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------核心分析命令

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

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

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

7.3 rtk session------会话中 RTK 采纳率

bash 复制代码 
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 跳过特定命令

toml 复制代码 
[hooks]
exclude_commands = ["curl", "playwright", "terraform apply"]

9.2 开关 Tee 模式

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

9.3 验证 Hook 完整性

bash 复制代码 
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 配置和命令白名单

参考资源

相关推荐
LingLong_roar1 小时前
SA8397 相机链路架构
架构·车载系统
Swizard2 小时前
还在被框架绑架？一文看懂“六边形架构”，让你的核心业务稳如泰山！
架构·architecture
飞凌嵌入式13 小时前
T153核心板：异构架构赋能工业嵌入式，筑牢工业设备实时控制底座
架构
陈猪的杰咪13 小时前
GitHub Copilot 2026计费新规：AI Credits消耗解析与节省策略
人工智能·ai·架构·github·copilot
watersink14 小时前
MCP 协议与 Skill 开发架构培训文档
人工智能·架构
@insist12314 小时前
系统架构设计师-嵌入式处理器核心知识体系：从分类到架构选型全解析
架构·分类·系统架构·软考·系统架构设计师·软件水平考试
实在智能RPA15 小时前
航空维修知识库构建方法：从RAG到Agent-native的架构演进与全栈工程实践
人工智能·ai·架构
Rain50915 小时前
2.1 Nest.js 项目初始化与模块化架构
开发语言·前端·javascript·后端·架构·数据分析·node.js
大蚂蚁2号16 小时前
深度解析：2026短视频批量生成底层技术、架构演进与企业落地实战
架构·音视频
热门推荐
01HTTP 与 HTTPS 的区别：从原理到实战详解022026 AI 编程工具终极实战指南：Cursor vs Claude Code vs Copilot，开发者该怎么选？03【AI】2026 年具身智能模型和世界模型总结042026年6月AI行业全景：从百模大战到Agent元年，这30天发生了什么？05《置身钉内》原文-可播放阅读06AI科技热点日报 | 2026年6月1日07Claude Code、Codex、Cursor三分天下：2026年AI编程Agent生态全景剖析08GitHub 镜像站点092026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf10AI一周事件 · 2026-06-03 至 2026-06-09