RTK 故障排查实战：从 "not a rtk command" 到 Windows Hook 回退的完整诊断指南

本文围绕 RTK（Rust Token Killer，一个用于压缩常见开发命令输出、降低 LLM token 消耗的 CLI 代理）的官方排查文档 docs/guide/resources/troubleshooting.md 展开。全文覆盖安装后找不到 rtk、装错同名包、AI 助手不自动使用 RTK、Windows 平台 Hook 失效等典型故障的定位与修复步骤，并结合仓库源码（src/main.rs、src/core/utils.rs、src/hooks/init.rs）与诊断脚本 scripts/check-installation.sh 说明每个现象背后的实现原理，帮助读者从「按步骤修」升级为「知其所以然」。

1. rtk gain 报 "not a rtk command"：你装错了包

这是 RTK 用户最常遇到的陷阱。运行 rtk gain 时如果看到：

$ rtk gain
rtk: 'gain' is not a rtk command. See 'rtk --help'.

原因并不是 RTK 损坏，而是你安装的是另一个同名项目 Rust Type Kit（reachingforthejack/rtk），而不是本项目 Rust Token Killer（rtk-ai/rtk）。两者共用 rtk 这个二进制名，而 Token Killer 的核心特征之一是 gain 子命令——在 src/main.rs 中可以确认 Gain 是 clap 定义的正式子命令，用于"Show token savings summary and history"，支持 --project、--graph、--history、--quota、--format（text/json/csv）等参数。如果 CLI 没有这个子命令，clap 就会报出 "'gain' is not a rtk command" 这类错误，这正是包身份的判别点。

修复方式：卸载错误包，改用本仓库的安装脚本重新安装：

cargo uninstall rtk
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/master/install.sh | sh
rtk gain    # 现在应显示 token 节省统计

仓库根目录下的 install.sh 即该脚本的源头。

如何快速判断你手上是哪个 rtk

原文档给出了一张判别表，其本质就是把 rtk gain 能否运行作为探针：

如果 rtk gain……	说明你拥有
显示 token 节省仪表盘	Rust Token Killer ✅
返回 "not a rtk command"	Rust Type Kit ❌

这一点也与仓库自带的诊断脚本一致：scripts/check-installation.sh 的第 3 步就是用 rtk gain（或 rtk gain --help）能否成功来判断"是否 Token Killer"，失败则直接判定为装错包并以退出码 1 终止。

2. cargo install rtk 可能装错包：始终使用显式仓库 URL

crates.io 上如果 Rust Type Kit 以 rtk 为名发布过，那么 cargo install rtk 就可能解析到错误的项目。原文档的建议是始终使用显式仓库地址并固定在发布分支：

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

这样绕过了包名歧义。需要说明的版本前提：排查文档中"更新到 v0.23.1+" 一节给出的即此命令；而当前仓库的 Cargo.toml 中包版本为 0.42.4，且 rust-version = "1.91"，说明仓库在持续演进，从源码构建时请以仓库当前声明的 Rust 版本要求为准（排查文档中给出的最低 1.70+ 是较早版本的要求）。

3. AI 助手没有使用 RTK：五步排查清单

症状：Claude Code（或其他 agent）仍在直接执行 cargo test，而不是 rtk cargo test。这通常意味着 Hook 未安装或未生效。原文档给出五步清单，这里完整保留并结合源码补充每步的落点：

# 1. 确认 RTK 本身已安装且身份正确
rtk --version
rtk gain

# 2. 初始化 Hook（按所用 agent 选择）
rtk init --global             # Claude Code
rtk init --global --cursor    # Cursor
rtk init --global --opencode  # OpenCode

# 3. 重启 AI 助手

# 4. 查看 Hook 状态
rtk init --show

# 5. 确认 settings.json 已注册 Hook（Claude Code）
cat ~/.claude/settings.json | grep rtk

从源码结构看，rtk init 的完整参数面定义在 src/main.rs 的 Init 子命令中：--global 表示写入全局助手配置目录而非项目本地文件；--opencode 表示额外安装 OpenCode 插件；--agent 可指定目标 agent（枚举值见 src/main.rs 的 AgentTarget，包括 Claude、Cursor、Windsurf、Cline、Kilocode、Hermes、Vibe 等十余种）；--show 输出当前配置；--dry-run 可预览不落盘。此外还有 --claude-md（旧版 CLAUDE.md 注入模式）与 --hook-only 两种互斥模式，以及 --auto-patch / --no-patch 控制是否自动改写 settings.json。

第 5 步检查的 settings.json 之所以关键，是因为自动改写依赖 Claude Code 的 PreToolUse Hook 调用 rtk rewrite（定义于 src/main.rs，"Rewrite a raw command to its RTK equivalent"）在命令执行前把 cargo test 这类原始命令重写成 rtk cargo test。Hook 未注册进 settings.json，重写链路就不存在，助手自然只会跑原始命令。

诊断脚本的第 6 步同样验证这条链路：检查 ~/.claude/hooks/rtk-rewrite.sh 是否存在、且 ~/.claude/settings.json 中是否引用了它（见 scripts/check-installation.sh）。

4. cargo install 后找不到 rtk：PATH 问题

症状：

$ rtk --version
zsh: command not found: rtk

原因：~/.cargo/bin 不在 PATH 中。按 shell 分别修复：

bash（~/.bashrc）或 zsh（~/.zshrc）：

export PATH="$HOME/.cargo/bin:$PATH"

fish（~/.config/fish/config.fish）：

set -gx PATH $HOME/.cargo/bin $PATH

然后重载并验证：

source ~/.zshrc    # 或 ~/.bashrc
rtk --version

5. Windows 平台专题

Windows 是 RTK 行为差异最大的平台，原文档列出三个子问题。

5.1 双击 rtk.exe 没有任何反应

RTK 是命令行工具，无参数运行时打印用法后立即退出，控制台窗口"闪一下就关"属于预期行为。正确姿势是先打开终端（Win+R 输入 cmd，或打开 PowerShell / Windows Terminal），再执行 rtk --version。

5.2 Hook 不生效：提示回退到 CLAUDE.md 模式

症状：rtk init -g 在 Windows 上显示 "Falling back to --claude-md mode"。

原因：自动改写 Hook 脚本 rtk-rewrite.sh 依赖 Unix shell，原生 Windows 没有。仓库的 hooks/ 目录（如 hooks/claude/rtk-rewrite.sh）也印证了 Hook 是 shell 脚本形态。

修复：在 WSL 内获得完整 Hook 支持：

# Inside WSL
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
rtk init -g    # 完整 Hook 模式在 WSL 中可用

在原生 Windows 上，RTK 回退为 CLAUDE.md 注入模式——这一点在源码中可以直接看到：src/hooks/init.rs 保留了 "Legacy full instructions for backward compatibility (--claude-md mode)" 的完整指令注入逻辑。回退模式下 AI 助手能拿到 RTK 使用说明，但不会自动重写命令，需要你（或助手）手动使用 rtk cargo test、rtk git status 等形式。

5.3 program not found：Node.js 工具找不到

症状：

rtk vitest --run
Error: program not found

原因：在 Windows 上，Node.js 全局工具安装为 .CMD/.BAT 包装脚本，而早期版本的 RTK 无法发现它们。修复：更新到 v0.23.1+：

cargo install --git https://github.com/rtk-ai/rtk --branch master
rtk --version    # 应为 0.23.1+

当前仓库的源码印证了这个问题的最终解法：src/core/utils.rs 中的 resolve_binary / resolved_command 专门处理 PATHEXT——注释明确写道 "Rust's std::process::Command::new() does NOT honor PATHEXT, so Command::new("vitest") fails even when vitest.CMD is on PATH"。实现上使用 which crate 做 PATH+PATHEXT 解析，解析失败时回退到直接执行并在 Windows 下打印告警。同文件（约 src/core/utils.rs）还有对应的单元测试，用临时 .cmd/.bat 包装脚本验证解析与执行路径。

6. 安装时编译错误：刷新工具链后强制重装

遇到编译失败时，按以下顺序处理：

rustup update stable
rustup default stable
cargo clean
cargo build --release
cargo install --path . --force

适用前提：排查文档给出的最低 Rust 版本为 1.70+；但如前所述，当前 Cargo.toml 声明 rust-version = "1.91"，从本仓库最新源码构建时应满足 manifest 中的实际要求。

7. OpenCode 没有使用 RTK

rtk init --global --opencode
# 重启 OpenCode
rtk init --show    # 应显示 "OpenCode: plugin installed"

对应的插件实现位于 openclaw/ 目录（含 openclaw/index.ts 与 openclaw/openclaw.plugin.json），rtk init --show 的输出即对该插件安装状态的检查。

8. 一键诊断：运行 scripts/check-installation.sh

不想逐条排查时，从 RTK 仓库根目录直接运行诊断脚本：

bash scripts/check-installation.sh

对照 scripts/check-installation.sh 的实现，它共执行 6 项检查：

1. RTK 是否安装且在 PATH 中（command -v rtk，并打印二进制路径）；
2. 打印 rtk --version；
3. 身份验证：以 rtk gain 能否成功区分 Token Killer 与 Type Kit，失败即判定装错包并 exit 1；
4. 功能覆盖检查：依次探测 gain、git、gh、pnpm、vitest、lint、tsc、next、prettier、playwright、prisma、discover 等子命令是否存在于 rtk --help 输出中，缺失项会汇总提示"基础版安装"；
5. Claude Code 集成检查：验证全局 ~/.claude/CLAUDE.md 与项目本地 ./CLAUDE.md 中是否含 RTK 内容；
6. 自动改写 Hook 检查：验证 ~/.claude/hooks/rtk-rewrite.sh 存在、且 settings.json 中已启用（可选但推荐）。

脚本末尾会输出总结：若功能缺失给出重新安装指引，若两个 CLAUDE.md 都未初始化则提示 rtk init --global（全局）或 rtk init（仅当前项目）。该脚本的 set -e 特性意味着第 3 步失败会立即终止，所以"装错包"是最优先被拦截的故障。

9. 排查顺序小结

结合上述各节，推荐的诊断顺序是：

1. 先跑 bash scripts/check-installation.sh，一次性定位"装没装 / 装的是哪个 / 功能全不全 / Hook 通没通"；
2. 报 "not a rtk command" → 装错包，按第 2 节用显式仓库 URL 重装；
3. command not found → 第 4 节修 PATH；
4. 助手不用 RTK → 第 3 节五步清单，重点看 settings.json 中 Hook 注册；
5. Windows 用户 → 第 5 节，完整 Hook 能力依赖 WSL，原生 Windows 接受 CLAUDE.md 注入的回退行为。

以上所有命令与路径均来自当前仓库的文档与源码（docs/guide/resources/troubleshooting.md、scripts/check-installation.sh、src/main.rs、src/core/utils.rs、src/hooks/init.rs），可直接在当前仓库中检索验证。若按此流程仍无法解决，建议在项目 issue tracker 中提交问题并附上 rtk --version 输出与诊断脚本的完整结果。