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

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

【免费下载链接】rtkCLI 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" 的项目，安装前务必区分：

✅Rust Token Killer（本项目）——LLM token 优化器
- 仓库：rtk-ai/rtk
- 可通过rtk gain命令查看节省统计面板
❌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 往其中写入一个PreToolUseHook，在工具调用前透明改写命令。不注册的话 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模式写入的块），内容就是这份 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。读一遍脚本就能理解整条链路：

依赖检查：需要jq解析 Hook 输入 JSON、需要 PATH 中有rtk，缺一即打印警告并静默放行（exit 0），绝不打断 Claude 的执行。
版本守卫：rtk rewrite自 0.23.0 起存在；脚本会把rtk --version的检查结果缓存到~/.cache/rtk-hook-version-ok，避免每次 Hook 调用都多起一个进程。版本低于 0.23.0 时警告并放行。

委托改写：从 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中的遗留块（若清理后文件为空则整个删除）、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）的代理前缀。

企业官网建设流程全解析