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

RTK 故障排查实战从 not a rtk command 到 Windows Hook 回退的完整诊断指南【免费下载链接】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本文围绕 RTKRust 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 Kitreachingforthejack/rtk而不是本项目Rust Token Killerrtk-ai/rtk。两者共用rtk这个二进制名而 Token Killer 的核心特征之一是gain子命令——在 src/main.rs 中可以确认Gain是 clap 定义的正式子命令用于Show token savings summary and history支持--project、--graph、--history、--quota、--formattext/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 commandRust Type Kit ❌这一点也与仓库自带的诊断脚本一致scripts/check-installation.sh 的第 3 步就是用rtk gain或rtk gain --help能否成功来判断是否 Token Killer失败则直接判定为装错包并以退出码 1 终止。2.cargo install rtk可能装错包始终使用显式仓库 URLcrates.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 已注册 HookClaude 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.rsRewrite 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后找不到rtkPATH 问题症状$ rtk --version zsh: command not found: rtk原因~/.cargo/bin不在 PATH 中。按 shell 分别修复bash~/.bashrc或 zsh~/.zshrcexport PATH$HOME/.cargo/bin:$PATHfish~/.config/fish/config.fishset -gx PATH $HOME/.cargo/bin $PATH然后重载并验证source ~/.zshrc # 或 ~/.bashrc rtk --version5. Windows 平台专题Windows 是 RTK 行为差异最大的平台原文档列出三个子问题。5.1 双击 rtk.exe 没有任何反应RTK 是命令行工具无参数运行时打印用法后立即退出控制台窗口闪一下就关属于预期行为。正确姿势是先打开终端WinR输入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.3program not foundNode.js 工具找不到症状rtk vitest --run Error: program not found原因在 Windows 上Node.js 全局工具安装为.CMD/.BAT包装脚本而早期版本的 RTK 无法发现它们。修复更新到 v0.23.1cargo install --git https://github.com/rtk-ai/rtk --branch master rtk --version # 应为 0.23.1当前仓库的源码印证了这个问题的最终解法src/core/utils.rs 中的resolve_binary/resolved_command专门处理 PATHEXT——注释明确写道 Rustsstd::process::Command::new()does NOT honor PATHEXT, soCommand::new(vitest)fails even whenvitest.CMDis on PATH。实现上使用whichcrate 做 PATHPATHEXT 解析解析失败时回退到直接执行并在 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 没有使用 RTKrtk init --global --opencode # 重启 OpenCode rtk init --show # 应显示 OpenCode: plugin installed对应的插件实现位于 openclaw/ 目录含 openclaw/index.ts 与 openclaw/openclaw.plugin.jsonrtk init --show的输出即对该插件安装状态的检查。8. 一键诊断运行scripts/check-installation.sh不想逐条排查时从 RTK 仓库根目录直接运行诊断脚本bash scripts/check-installation.sh对照 scripts/check-installation.sh 的实现它共执行 6 项检查RTK 是否安装且在 PATH 中command -v rtk并打印二进制路径打印rtk --version身份验证以rtk gain能否成功区分 Token Killer 与 Type Kit失败即判定装错包并exit 1功能覆盖检查依次探测gain、git、gh、pnpm、vitest、lint、tsc、next、prettier、playwright、prisma、discover等子命令是否存在于rtk --help输出中缺失项会汇总提示基础版安装Claude Code 集成检查验证全局~/.claude/CLAUDE.md与项目本地./CLAUDE.md中是否含 RTK 内容自动改写 Hook 检查验证~/.claude/hooks/rtk-rewrite.sh存在、且settings.json中已启用可选但推荐。脚本末尾会输出总结若功能缺失给出重新安装指引若两个 CLAUDE.md 都未初始化则提示rtk init --global全局或rtk init仅当前项目。该脚本的set -e特性意味着第 3 步失败会立即终止所以装错包是最优先被拦截的故障。9. 排查顺序小结结合上述各节推荐的诊断顺序是先跑bash scripts/check-installation.sh一次性定位装没装 / 装的是哪个 / 功能全不全 / Hook 通没通报 not a rtk command → 装错包按第 2 节用显式仓库 URL 重装command not found→ 第 4 节修 PATH助手不用 RTK → 第 3 节五步清单重点看settings.json中 Hook 注册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输出与诊断脚本的完整结果。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考