首页
/ RTK（Rust Token Killer）安装与初始化全解：从二进制校验到 AI Agent 透明命令改写

RTK（Rust Token Killer）安装与初始化全解：从二进制校验到 AI Agent 透明命令改写

2026-09-06 12:06:46作者：卓炯娓
rtk
CLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies
项目地址：https://gitcode.com/GitHub_Trending/rtk4/rtk

本文基于仓库根目录的 INSTALL.md 编写，完整覆盖 RTK 从安装前检查、二进制获取、rtk init 初始化到卸载与排障的全流程，并结合 install.sh、src/hooks/init.rs、hooks/claude/rtk-rewrite.sh 等源码说明每一步背后的实现机制。读完后你将能够独立完成 RTK 的安装与验证、为 Claude Code 配置全局 Hook、理解命令透明改写的底层协议，并掌握升级、回滚与排障方法。

安装前必读：两个同名 "rtk" 项目

存在两个完全不同的名为 "rtk" 的项目，安装前务必区分：

  1. ✅ Rust Token Killer（本项目）——LLM token 优化器
    • 仓库：rtk-ai/rtk
    • 可通过 rtk gain 命令查看节省统计面板
  2. ❌ Rust Type Kit（reachingforthejack/rtk）——完全不同的项目
    • Rust 代码库查询与类型生成工具
    • 如果你的目标是 token 优化，切勿安装它

安装前检查（必需）

AI 助手在执行任何安装动作前，都应先验证 RTK 是否已安装、是否是"正确的那个"：

# 检查 RTK 是否已安装
rtk --version

# 关键：验证是 Token Killer 而不是 Type Kit
rtk gain    # 应显示节省面板（savings dashboard），而不是 "command not found"

# 检查安装路径
which rtk
  • 如果 rtk gain 能正常输出节省面板，说明正确版本已安装，不要重复安装，直接跳到"项目初始化"一节。
  • 如果 rtk gain 失败但 rtk --version 成功，说明装错了（Type Kit），先卸载再安装正确版本。

安装 RTK 二进制

步骤 0：卸载错误的 RTK（如需要）

如果误装了 Rust Type Kit：

cargo uninstall rtk

方式一：一键脚本安装（Linux/macOS，推荐）

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

这条命令下载的是仓库中的 install.sh，它是一个纯 POSIX shell 脚本，安装流程远比"下载文件"更严谨，从源码可以看出以下机制：

  • 平台与架构探测：detect_os / detect_arch 仅支持 Linux 与 Darwin，架构支持 x86_64 与 aarch64，其他组合直接报错退出。
  • 目标三元组选择：Linux x86_64 下载 x86_64-unknown-linux-musl 静态构建；Linux ARM64 下载 aarch64-unknown-linux-gnu；macOS 下载 ${ARCH}-apple-darwin。
  • 版本发现：优先解析 releases/latest 的 302 重定向获取 tag（不消耗 API 配额），失败再回退到 GitHub REST API；也可通过环境变量 RTK_VERSION=vX.Y.Z 固定版本。
  • SHA-256 强校验：脚本会同时下载 checksums.txt，用 sha256sum（Linux）或 shasum -a 256（macOS）比对，校验失败或不匹配时拒绝安装（见 install.sh）。如确需跳过可设 RTK_SKIP_CHECKSUM=1，但官方明确不推荐。
  • 压缩包安全检查：解压前用 tar -tzf 检查归档内是否存在绝对路径或 .. 组件（CWE-22 路径穿越防护），发现即拒绝解压（见 install.sh）。
  • 安装位置：默认 ~/.local/bin，可用环境变量 RTK_INSTALL_DIR 覆盖；脚本最后运行 verify 打印 rtk --version，并检测 PATH——若二进制不在 PATH 中会提示添加 export PATH="$HOME/.local/bin:$PATH"。

安装后立即验证是正确版本：

rtk gain  # 必须显示节省面板（不能是 "command not found"）

方式二：手动安装（Cargo）

# 从 rtk-ai 仓库安装（注意：不是 reachingforthejack！）
cargo install --git https://github.com/rtk-ai/rtk

# 或者（若 crates.io 上发布的就是本项目）
cargo install rtk

# 安装后务必验证
rtk gain  # 必须显示节省面板，而不是 "command not found"

⚠️ 警告：crates.io 上的 cargo install rtk 可能装到错误的包，永远要用 rtk gain 验证。

从 Cargo.toml 可确认当前项目声明的版本为 0.42.4，rust-version = "1.91"，即源码构建需要 Rust 1.91 及以上的稳定工具链；项目为 Apache 2.0 许可、单二进制发布、无运行时外部依赖。

项目初始化：rtk init 的模式选择

安装完二进制后，需要让 AI 编码助手"知道"该用 RTK。rtk init 提供三种模式，按需求选择：

  是否希望 RTK 在所有 Claude Code 项目中生效？
  │
  ├─ 是 → rtk init -g              （推荐）
  │         Hook + RTK.md（约 10 token 上下文开销）
  │         命令被透明地自动改写
  │
  ├─ 是，但要最小化 → rtk init -g --hook-only
  │         仅装 Hook，不改 CLAUDE.md
  │         上下文开销为零
  │
  └─ 否，仅单个项目 → rtk init
            只写本地 CLAUDE.md（137 行）
            无 Hook、无全局副作用

从 src/main.rs 的 Init 子命令定义可见，除上述三种核心模式外，rtk init 还暴露了更多开关：--show（查看当前配置）、--claude-md（遗留模式：注入完整指令块）、--hook-only、--auto-patch / --no-patch（二选一）、--uninstall、--dry-run（预览不落盘）、--codex / --gemini / --agent / --copilot / --opencode（面向不同 Agent）。--auto-patch 与 --no-patch 属于同一参数组，互斥。

推荐方案：全局 Hook-First（rtk init -g）

适用场景：所有项目、自动启用 RTK。

rtk init -g
# → 安装 Hook 到 ~/.claude/hooks/rtk-rewrite.sh
# → 创建 ~/.claude/RTK.md（10 行，仅元命令）
# → 在 ~/.claude/CLAUDE.md 中添加 @RTK.md 引用
# → 提示："Patch settings.json? [y/N]"
# → 若确认：写入 settings.json 并先创建备份（~/.claude/settings.json.bak）

# 自动化替代：
rtk init -g --auto-patch    # 不提示，直接修补
rtk init -g --no-patch      # 只打印手动操作说明，不写文件

# 验证安装
rtk init --show  # 检查 Hook 已安装且可执行

上下文成本：Hook 方案只往上下文里放一份 10 行的 RTK.md（内容见 hooks/claude/rtk-awareness.md，仅含 rtk gain / rtk discover / rtk proxy 等元命令与验证命令），命令改写本身对上下文零开销；对比之下，本地模式要把 137 行完整命令参考塞进每个项目的 CLAUDE.md。

settings.json 是什么？ 它是 Claude Code 的 Hook 注册表。RTK 往其中写入一个 PreToolUse Hook，在工具调用前透明改写命令。不注册的话 Claude 不会自动触发 Hook。改写流程如下：

  Claude Code          settings.json        rtk-rewrite.sh        RTK 二进制
       │                    │                     │                    │
       │  "git status"      │                     │                    │
       │ ──────────────────►│                     │                    │
       │                    │  PreToolUse 触发     │                    │
       │                    │ ───────────────────►│                    │
       │                    │                     │  改写命令          │
       │                    │                     │  → rtk git status  │
       │                    │◄────────────────────│                    │
       │                    │  更新后的命令        │                    │
       │  执行: rtk git status                                          │
       │ ─────────────────────────────────────────────────────────────►│
       │                                                               │  过滤输出
       │  "3 modified, 1 untracked ✓"                                   │
       │◄──────────────────────────────────────────────────────────────│

settings.json 修补的实现细节（见 src/hooks/init.rs）：

  • 修补行为由 PatchMode 枚举控制：Ask（默认，交互式 [y/N]）、Auto（--auto-patch）、Skip（--no-patch，改为打印 JSON 片段让你手动粘贴）。
  • 非交互式环境（stdin 不是 TTY）下 Ask 模式默认按 N 处理，不会挂起等待输入。
  • 写入是幂等的：若 Hook 条目已存在则返回 AlreadyPresent 直接跳过；写入采用"临时文件 + 原子 rename"，避免中途崩溃留下半截 JSON。
  • 备份安全：修改前先把原文件复制为 ~/.claude/settings.json.bak，需要回滚时执行：
cp ~/.claude/settings.json.bak ~/.claude/settings.json

另外，rtk init 在非 dry-run 流程结束时会询问一次匿名遥测同意（写入本地 config.toml），可随时用 rtk telemetry disable 关闭，详见 docs/TELEMETRY.md。

备选方案：本地项目模式

适用场景：只想在单个项目里启用，不装全局 Hook。

cd /path/to/your/project
rtk init  # 创建 ./CLAUDE.md，写入完整 RTK 指令（137 行）

上下文成本：指令仅在本项目加载。对应源码中的遗留全量指令块 RTK_INSTRUCTIONS（即 --claude-md 模式写入的 <!-- rtk-instructions --> 块），内容就是这份 137 行命令参考本身（见 src/hooks/init.rs），覆盖构建、测试、Git、GitHub、JS/TS 工具链、文件搜索、基础设施、网络等分类的压缩比说明。

从旧版本升级

从 0.22 之前的 137 行 CLAUDE.md 注入升级：

rtk init -g  # 自动迁移到 Hook-First 模式
# → 删除旧的 137 行块
# → 安装 Hook + RTK.md
# → 添加 @RTK.md 引用

从 0.24 之前的内联逻辑 Hook 升级 —— ⚠️ 破坏性变更：

RTK 0.24.0 把原来约 200 行的内联命令检测 Hook 替换为一个薄委托器（thin delegator），改写逻辑全部收敛进 rtk rewrite 子命令，即二进制成为唯一事实来源。好处是新增命令不再需要更新 Hook 脚本。旧 Hook 仍可工作，但无法享受后续版本新增的规则。

# 把 Hook 升级为薄委托器
rtk init --global

# 验证新 Hook 生效
rtk init --show
# 应显示：✅ Hook: ... (thin delegator, up to date)

Hook 的工作原理：薄委托器脚本

全局 Hook 的真实文件是 hooks/claude/rtk-rewrite.sh，rtk init -g 会把它的内嵌副本安装到 ~/.claude/hooks/rtk-rewrite.sh。读一遍脚本就能理解整条链路：

  1. 依赖检查：需要 jq 解析 Hook 输入 JSON、需要 PATH 中有 rtk，缺一即打印警告并静默放行（exit 0），绝不打断 Claude 的执行。

  2. 版本守卫：rtk rewrite 自 0.23.0 起存在；脚本会把 rtk --version 的检查结果缓存到 ~/.cache/rtk-hook-version-ok，避免每次 Hook 调用都多起一个进程。版本低于 0.23.0 时警告并放行。

  3. 委托改写：从 stdin 用 jq 提取 .tool_input.command，交给 rtk rewrite "$CMD"，按退出码分派：

    退出码 含义 Hook 行为
    0 + stdout 找到改写、无 deny/ask 规则命中 输出 permissionDecision: allow 的 hookSpecificOutput，自动放行改写后的命令
    1 无 RTK 等价命令 原样透传
    2 命中 Deny 规则 透传，交给 Claude Code 原生 deny 处理
    3 + stdout 命中 Ask 规则 改写命令但不带自动放行，让 Claude Code 向用户确认

    退出码协议完整写在脚本头部注释（hooks/claude/rtk-rewrite.sh），改写规则的单一事实来源在 Rust 侧的命令注册表（src/discover/registry.rs），新增命令只改 Rust 注册表即可。

常见用户流程

首次使用（推荐路径）

# 1. 安装 RTK
cargo install --git https://github.com/rtk-ai/rtk
rtk gain  # 验证（必须显示节省面板）

# 2. 交互式初始化
rtk init -g
# → 提示 patch settings.json 时回答 'y'
# → 自动创建备份

# 3. 重启 Claude Code
# 4. 测试：执行 git status（应观察到走 rtk）

CI/CD 或自动化

# 非交互初始化（无提示）
rtk init -g --auto-patch

# 脚本中验证
rtk init --show | grep "Hook:"

保守用户（手动控制）

# 只打印手动说明，不修改任何文件
rtk init -g --no-patch

# 检查打印出的 JSON 片段
# 手动编辑 ~/.claude/settings.json
# 重启 Claude Code

临时试用

# 安装 Hook
rtk init -g --auto-patch

# 之后想全部移除
rtk init -g --uninstall

# 如需恢复
cp ~/.claude/settings.json.bak ~/.claude/settings.json

安装验证与核心命令速查

安装验证

# 基础测试
rtk ls .

# Git 测试
rtk git status

# pnpm 测试
rtk pnpm list

# Vitest 测试
rtk vitest

文件类命令

rtk ls .              # 紧凑树视图
rtk read file.rs      # 优化后的文件读取
rtk grep "pattern" .  # 按文件分组的结果

Git

rtk git status        # 紧凑状态
rtk git log -n 10     # 浓缩日志
rtk git diff          # 优化后的 diff
rtk git add .         # → "ok ✓"
rtk git commit -m "msg"  # → "ok ✓ abc1234"
rtk git push          # → "ok ✓ main"

下文中的百分比指 bash 输出的压缩率，不是账单的压缩率。

Pnpm（仅 fork 支持）

rtk pnpm list     # 依赖树（-70%）
rtk pnpm outdated # 可用更新（-80-90%）
rtk pnpm install  # 静默安装

测试

rtk cargo test      # 过滤后的 Cargo 测试输出（-90%）
rtk go test         # 过滤后的 Go 测试（NDJSON，-90%）
rtk jest            # 过滤后的 Jest 输出（-99.6%）
rtk vitest          # 过滤后的 Vitest 输出（-99.6%）
rtk playwright test # 过滤后的 Playwright 输出（-94%）
rtk pytest          # 过滤后的 Python 测试（-90%）
rtk rake test       # 过滤后的 Ruby 测试（-90%）
rtk rspec           # 过滤后的 RSpec 测试（-60%）
rtk test <cmd>      # 通用测试包装器 - 仅显示失败（-90%）

统计

rtk gain              # 节省面板
rtk gain --graph      # 带 ASCII 图表
rtk gain --history    # 带命令历史

RTK 对输出的处理

RTK 在 Agent 读取 shell 命令输出前对其进行压缩，实际效果如下表：

操作 RTK 对输出做了什么
vitest / jest 只保留失败项；通过的套件折叠为计数
git status 紧凑 stat 格式，按状态分组
pnpm list 紧凑依赖树
pnpm outdated 只保留包名、当前版本与目标版本
cargo test 只保留失败项，含断言与位置

命令旁标注的百分比是 bash 输出字节的减少量——这是 RTK 能控制的部分。它不等于账单同比例下降：bash 输出只是输入 token 的一个来源，而输入 token 也只是账单的一部分（账单还计输出 token）。完整解释见 docs/guide/resources/savings-explained.md，其中也说明了 RTK 报告的 token 数为何是估算值。

卸载

完整移除（仅限全局安装）

# 完整移除（仅适用于全局安装）
rtk init -g --uninstall

# 移除的内容：
#   - Hook：~/.claude/hooks/rtk-rewrite.sh
#   - 上下文文件：~/.claude/RTK.md
#   - ~/.claude/CLAUDE.md 中的 @RTK.md 引用行
#   - settings.json 中的 RTK Hook 条目

对照 src/hooks/init.rs 的 uninstall 实现，实际清理范围比文档所列更完整：还会删除 Hook 的完整性哈希旁挂文件、遗留的内联逻辑 Hook 文件、CLAUDE.md 中的 <!-- rtk-instructions --> 遗留块（若清理后文件为空则整个删除）、OpenCode 插件与 Cursor Hook，且每一步都支持 --dry-run 预览。移除后重启 Claude Code 生效。

本地项目：手动从 ./CLAUDE.md 中删除 RTK 块即可。

移除二进制

# 若通过 cargo 安装
cargo uninstall rtk

# 若通过包管理器安装
brew uninstall rtk          # macOS Homebrew
sudo apt remove rtk         # Debian/Ubuntu
sudo dnf remove rtk         # Fedora/RHEL

从备份恢复（如需要）

cp ~/.claude/settings.json.bak ~/.claude/settings.json

故障排查

安装后找不到 rtk 命令

# 检查 PATH
echo $PATH | grep -o '[^:]*\.cargo[^:]*'

# 如需要，把安装目录加入 PATH（~/.bashrc 或 ~/.zshrc）
# cargo 安装为 ~/.cargo/bin，install.sh 安装为 ~/.local/bin
export PATH="$HOME/.cargo/bin:$PATH"

# 重载 shell
source ~/.bashrc  # 或 source ~/.zshrc

某个命令不可用（如 vitest）

# 检查分支
cd /path/to/rtk
git branch

# 如需要切换到对应功能分支
git checkout feat/vitest-support

# 重新安装
cargo install --path . --force

编译错误

# 更新 Rust（项目要求 rust-version = 1.91）
rustup update stable

# 清理并重新编译
cargo clean
cargo build --release
cargo install --path . --force

AI 助手操作清单

每个会话开始前：

  • [ ] 验证 RTK 已安装：rtk --version
  • [ ] 未安装 → 按上文安装方式执行
  • [ ] 项目未初始化 → rtk init
  • [ ] 所有 git/pnpm/test/vitest 命令一律走 rtk
  • [ ] 查看节省：rtk gain

黄金法则：AI 编码助手应始终把 rtk 作为产生冗长输出的 shell 命令（git、pnpm、npm、cargo test、vitest、docker、kubectl）的代理前缀。

延伸阅读

rtk
CLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies
项目地址：https://gitcode.com/GitHub_Trending/rtk4/rtk
登录后查看全文

相关内容推荐

1 RTK 故障排查实战：从 "not a rtk command" 到 Windows Hook 回退的完整诊断指南2 RTK 安装完全指南：四种方式安装 Rust Token Killer、验证正确版本并完成项目初始化3 RTK（Rust Token Killer）官方指南：Hook 拦截、输出过滤与 Token 节省度量的完整工作流4 rtk-awareness 解析：rtk 如何让 Claude Code 自动经 rtk 代理命令以压缩 Token 消耗5 RTK 快速上手：5 分钟完成 Hook 初始化并验证 Token 节省6 RTK 实战指南：用单个 Rust 二进制代理压缩 CLI 输出，为 LLM Agent 削减最高 90% 的 Bash Token7 RTK (Rust Token Killer) 实战指南：让 LLM 只读压缩后的 Bash 输出，最高削减 90%8 RTK 在 Google Antigravity 中的集成：基于 Rules 文件的 Token 优化代理配置9 rtk git log10 RTK 实战指南：让 LLM Agent 少读 90% 命令行输出的 Rust CLI 代理
热门项目推荐
相关项目推荐

热门内容推荐

1 编程实践项目探索指南：从零构建技术能力体系2 技术解构式学习：从0到1构建你的编程知识体系3 构建自己的技术世界：build-your-own-x项目的实践探索指南4 解锁编程技能的实践之旅：从零构建你的技术世界5 技术实践探索：从零开始构建核心系统的实践指南6 亲手锻造技术引擎：从0到1构建核心系统的实践指南

最新内容推荐

three.js NodeObjectLoader 深度解析：用 JSON 场景格式加载 TSL 节点材质对象freeCodeCamp Bootstrap 课程实战：为 Bootstrap Wells 添加 h4 标签（Label Bootstrap Wells）freeCodeCamp Bootstrap 课程实战：使用 btn-block 打造通栏块级按钮Transformers 中的 GLM-V 视觉语言模型指南：从 GLM-4.1V 到 GLM-4.6V 的图像与视频推理实战PPT Master 音频旁白全流程指南：从逐页 TTS 配音、SRT 字幕到 PowerPoint 原生视频导出OpenMontage HyperFrames 动画规则实战：Orbit 3D Entry——从三维空间翻转入场到持续椭圆环绕Puppeteer 页面指标采集完全指南：Page.metrics() 方法剖析与 Chrome DevTools 底层原理supervision 弃用与迁移全指南：ByteTrack、keypoint、LMM/VLM 等已废弃 API 的升级路径Ant Design ColorPicker 编码格式详解：HEX / HSB / RGB 的切换、受控与格式化实践Hugging Face Transformers 中的 Mllama：Llama 3.2 Vision 多模态模型架构解析与推理实战

项目优选

收起
kernelkernel
deepin linux kernel
C
33
18
pytorchpytorch
作为 Ascend for PyTorch 社区的核心组件，TorchNPU 是昇腾专为 PyTorch 打造的深度学习适配插件，使 PyTorch 框架能够直接调用昇腾 NPU，为开发者提供昇腾 AI 处理器的超强算力。
Python
856
1.35 K
kernelkernel
openEuler内核是openEuler操作系统的核心，既是系统性能与稳定性的基石，也是连接处理器、设备与服务的桥梁。
C
529
592
leetcodeleetcode
🔥LeetCode solutions in any programming language | 多种编程语言实现 LeetCode、《剑指 Offer（第 2 版）》、《程序员面试金典（第 6 版）》题解
Markdown
77
23
ops-transformerops-transformer
本项目是CANN提供的transformer类大模型算子库，实现网络在NPU上加速计算。
C++
1.13 K
2.73 K
docsdocs
暂无描述
Markdown
897
5.79 K
jiuwenswarmjiuwenswarm
JiuwenSwarm 是一款基于openJiuwen开发的智能AI Agent，它能够将大语言模型的强大能力，通过你日常使用的各类通讯应用，直接延伸至你的指尖。
Python
3.57 K
1.01 K
cann-learning-hubcann-learning-hub
CANN 学习中心仓，支持在线互动运行、边学边练，提供教程、示例与优化方案，一站式助力昇腾开发者快速上手。
Jupyter Notebook
1.01 K
513
ops-nnops-nn
本项目是CANN提供的神经网络类计算算子库，实现网络在NPU上加速计算。
C++
912
1.83 K
openGauss-serveropenGauss-server
openGauss kernel ~ openGauss is an open source relational database management system
C++
213
313