rtk 的 /diagnose 命令：为 RTK × Claude Code 集成构建一套可复用的环境诊断流程

RTK 是一个用 Rust 编写的单二进制 CLI 代理，通过过滤和压缩常用开发命令的输出，将 LLM 场景下的 token 消耗降低 60%–90%。在接入 Claude Code 后，RTK 依赖两条 PreToolUse Bash 钩子（rtk-rewrite.sh 与 rtk-suggest.sh）和 rtk rewrite 命令完成透明命令重写，任何一环断裂都会表现为"命令没被改写""hook 报错"或"节省统计消失"。本文基于仓库中的 .claude/commands/diagnose.md，完整讲解这个 /diagnose 斜杠命令的触发时机、三段式诊断检查项、标准诊断报告格式与修复动作，并结合 .claude/hooks/rtk-rewrite.sh 和 src/hooks/rewrite_cmd.rs 的源码，说明这些检查项背后的实现原理，读完你可以直接把它作为 RTK 排障的操作手册。

命令定位：这是一个 Claude Code 斜杠命令

diagnose.md 位于 Claude Code 的命令目录 .claude/commands/ 下，文件头部的 frontmatter 声明了它的运行模型与用途：

---
model: haiku
description: RTK environment diagnostics - Checks installation, hooks, version, command routing
---

即该命令由 haiku 这类轻量模型执行，职责是"检查 RTK 的安装状态、钩子状态、版本与命令路由"。它的核心设计是：先并行执行一组只读检查命令收集证据，再按固定格式输出诊断报告，最后按检查结果提供一组可一键执行的修复选项。

触发时机：自动建议与手动触发

文档定义了 /diagnose 的两类使用场景。

自动建议场景——当 Claude 观察到以下错误模式时，应主动建议用户运行 /diagnose：

错误	Pattern	可能原因
RTK not found	rtk: command not found	未安装或未加入 PATH
Hook error	Hook execution failed, permission denied	钩子脚本没有可执行权限（需要 chmod +x）
Version mismatch	RTK 输出中出现 Unknown command	RTK 版本不兼容（需要升级）
No analytics	rtk gain 失败或命令不存在	RTK 安装不完整或版本过旧
Command not rewritten	命令未经 RTK 代理执行	钩子集成断裂（检查 CLAUDE_CODE_HOOK_BASH_TEMPLATE）

文档还给出三个自动建议的话术示例，例如检测到 rtk: command not found 时应回复"该错误表示 RTK 未安装或不在 PATH 中，建议运行 /diagnose 检查安装状态并获取修复命令"；检测到 hook 权限拒绝时，则提示运行 /diagnose 定位问题并用 chmod +x 修复。

手动触发场景——在刚安装完 RTK、升级 RTK 之后，或观察到行为异常（命令没有被改写、节省统计不更新）时主动运行。

第一段：并行执行六组环境检查

诊断的第一步是并行运行以下检查命令。全部为只读操作，不修改任何文件。

1. RTK 二进制安装检查

# RTK installation check
which rtk && rtk --version || echo "❌ RTK not found in PATH"

同时验证两件事：二进制能否被 shell 解析（which rtk）、版本号是否符合预期（rtk --version）。

2. Git 状态（确认工作目录）

# Git status (verify working directory)
git status --short && git branch --show-current

这一步用于确认诊断是在预期的仓库与分支上进行的，避免在错误的工作目录中误判"缺少文件"。

3. 钩子文件检查：存在性与可执行位

RTK 的 Claude Code 集成依赖两个钩子脚本，分别位于 .claude/hooks/ 下：

# Hook configuration check
if [ -f ".claude/hooks/rtk-rewrite.sh" ]; then
    echo "✅ OK: rtk-rewrite.sh hook present"
    # Check if hook is executable
    if [ -x ".claude/hooks/rtk-rewrite.sh" ]; then
        echo "✅ OK: hook is executable"
    else
        echo "⚠️ WARNING: hook not executable (chmod +x needed)"
    fi
else
    echo "❌ MISSING: rtk-rewrite.sh hook"
fi

rtk-suggest.sh 使用完全相同的检查逻辑（存在性 + 可执行位）。

从仓库源码看，这两个检查项对应的正是真实存在的文件 .claude/hooks/rtk-rewrite.sh 与 .claude/hooks/rtk-suggest.sh：

• rtk-rewrite.sh 是"透明改写"钩子，挂在 Claude Code 的 PreToolUse:Bash 事件上。它从 stdin 读取工具调用 JSON，用 jq 提取 .tool_input.command，然后调用 rtk rewrite "$CMD" 完成改写——注释中明确写着 "single source of truth — no duplicate mapping logic here"，即所有命令映射逻辑只存在于 Rust 侧，脚本本身不维护映射表。若缺少 rtk 或 jq 依赖，脚本会静默 exit 0 跳过，这也是诊断中"依赖是否齐全"隐含要验证的点。
• rtk-suggest.sh 是"建议"钩子，它不修改命令，而是对匹配到的 git/cargo/vitest/docker/curl 等命令输出 systemMessage（如 "⚡ RTK available: rtk git status"），提示模型可改用 RTK 等价命令。

钩子的"存在 + 可执行"之所以是关键检查项，是因为 Claude Code 执行 hook 脚本要求文件带 x 权限位；文件存在但没有可执行位，会直接表现为"permission denied"或"hook 未触发"两类故障。

4. Claude Code 上下文检查

# Claude Code context check
if [ -n "$CLAUDE_CODE_HOOK_BASH_TEMPLATE" ]; then
    echo "✅ OK: Running in Claude Code context"
    echo "   Hook env var set: CLAUDE_CODE_HOOK_BASH_TEMPLATE"
else
    echo "⚠️ WARNING: Not running in Claude Code (hooks won't activate)"
    echo "   CLAUDE_CODE_HOOK_BASH_TEMPLATE not set"
fi

CLAUDE_CODE_HOOK_BASH_TEMPLATE 由 Claude Code 运行时注入，是判断"当前是否真的处于 Claude Code 会话"的可靠信号。如果该变量为空却观察到"命令没有被改写"，基本可以定位到钩子未加载（例如 chmod 之后没有重启 Claude Code 会话），而不是 RTK 本身的问题。

5. 命令路由干跑（dry-run）

# Test command routing (dry-run)
if command -v rtk >/dev/null 2>&1; then
    # Test if rtk gain works (validates install)
    if rtk --help | grep -q "gain"; then
        echo "✅ OK: rtk gain available"
    else
        echo "❌ MISSING: rtk gain command (old version or wrong binary)"
    fi
else
    echo "❌ RTK binary not found"
fi

这里以 rtk gain 子命令是否存在作为"二进制正确且版本够新"的探针：既能验证安装完整，又能区分"装成了同名但功能不同的其他 rtk"这一类问题（后文 Troubleshooting 详述）。

第二段：验证 token 分析链路

# Run rtk gain to verify analytics work
if command -v rtk >/dev/null 2>&1; then
    echo ""
    echo "📊 Token Savings (last 5 commands):"
    rtk gain --history 2>&1 | head -8 || echo "⚠️ rtk gain failed"
else
    echo "⚠️ Cannot test rtk gain (binary not installed)"
fi

rtk gain --history 读取 RTK 本地跟踪数据库并展示近期命令的节省记录，是"安装 → 代理执行 → 统计落盘"整条链路的最小端到端验证。如果该命令失败，常见原因是安装不完整或版本过旧。

rtk gain 的完整能力在 docs/usage/AUDIT_GUIDE.md 中有系统说明，诊断命令中的 --history 只是其中一项，排障时还可以借助：

rtk gain                        # 全局摘要
rtk gain --history              # 近期命令历史
rtk gain --daily / --weekly / --monthly
rtk gain --all --format json > savings.json
rtk gain --failures             # 解析失败日志（发生 fallback 的命令）

其中 --failures 对排障尤其有用：若统计"消失"但命令明明执行过，先查这里确认是否存在未被识别而回退到原始输出的命令。另需注意该文档指出的计量口径：rtk gain 按 bytes / 4 估算 token（见 src/core/tracking.rs），绝对值不与服务计费精确一致，百分比则可靠。

第三段：RTK 仓库内的质量检查（条件执行）

当诊断发生在 RTK 源码仓库内部时，附加一组 Rust 工程质量检查：

# Only run if we're in RTK repository
if [ -f "Cargo.toml" ] && grep -q 'name = "rtk"' Cargo.toml 2>/dev/null; then
    echo ""
    echo "🦀 RTK Repository Quality Checks:"

    # Check if cargo fmt passes
    if cargo fmt --all --check >/dev/null 2>&1; then
        echo "✅ OK: cargo fmt (code formatted)"
    else
        echo "⚠️ WARNING: cargo fmt needed"
    fi

    # Check if cargo clippy would pass (don't run full check, just verify binary)
    if command -v cargo-clippy >/dev/null 2>&1 || cargo clippy --version >/dev/null 2>&1; then
        echo "✅ OK: cargo clippy available"
    else
        echo "⚠️ WARNING: cargo clippy not installed"
    fi
else
    echo "ℹ️ Not in RTK repository (skipping quality checks)"
fi

注意两个实现细节：仓库判定用的是 Cargo.toml 存在且包含 name = "rtk"（当前仓库的 Cargo.toml 即满足该条件）；clippy 检查刻意只做"工具是否可用"而非完整跑一遍 lint，保持诊断快速、只读。

标准诊断报告格式

检查完成后，/diagnose 按固定版式输出结构化报告，便于人或 Agent 解析：

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
🔍 RTK Environment Diagnostic
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📦 RTK Binary:      ✅ OK (v0.16.0) | ❌ NOT FOUND
🔗 Hooks:           ✅ OK (rtk-rewrite.sh + rtk-suggest.sh executable)
                    ❌ MISSING or ⚠️ WARNING (not executable)
📊 Token Analytics: ✅ OK (rtk gain working)
                    ❌ FAILED (command not available)
🎯 Claude Context:  ✅ OK (hook environment detected)
                    ⚠️ WARNING (not in Claude Code)
🦀 Code Quality:    ✅ OK (fmt + clippy ready) [if in RTK repo]
                    ⚠️ WARNING (needs formatting/clippy)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

报告覆盖五个维度：二进制、钩子、token 分析、Claude Code 上下文、（条件性的）代码质量。每一维只有 OK / MISSING / WARNING 三态，排障时可以直接按维度定位。

修复动作：按诊断结果提供选项

文档要求：一旦发现问题，用 AskUserQuestion（multiSelect）向用户呈现修复选项，而不是直接执行。基础选项集为：

• cargo install --path . —— 从 RTK 仓库本地安装
• chmod +x .claude/hooks/bash/*.sh —— 使钩子可执行
• "Tout corriger (recommandé)"（全部修复）——安装 RTK + 修复钩子权限

并按具体故障给出不同的选项变体：

• RTK 未安装时：提供 cargo install --path .（在仓库内）、cargo install rtk（从 crates.io 取最新 release）、brew install rtk-ai/tap/rtk（Homebrew）三种安装途径。当前仓库的 Homebrew 安装方式由 Formula/rtk.rb 提供，其注释给出的用法是 brew tap rtk-ai/tap && brew install rtk，与 README.md 中记载的 brew install rtk 一致。
• 钩子缺失/不可执行时：chmod +x .claude/hooks/*.sh，或在缺失时从主仓库复制模板钩子。
• rtk gain 失败时：cargo install --path . --force 重装，或先 rtk --version 确认版本（文档中要求 v0.16.0+ 才具备 rtk gain）。

对应的"执行修复"命令为：

# Fix 1: 从 RTK 仓库根目录本地安装
cargo install --path .
# 验证安装
which rtk && rtk --version

# Fix 2: 使钩子可执行
chmod +x .claude/hooks/*.sh
# 验证权限
ls -la .claude/hooks/*.sh

# Fix 3: 全部修复（推荐）
cargo install --path .
chmod +x .claude/hooks/*.sh
# 验证
which rtk && rtk --version && rtk gain --history | head -3

Fix 3 的验证链值得注意：它同时验证了 PATH 解析、版本可用、分析链路打通三个层面，是"修好"的验收标准。

源码佐证：rtk rewrite 的退出码协议

诊断命令中"命令路由干跑"检查的底层，是 rtk rewrite 子命令。它把一条原始 shell 命令翻译成 RTK 等价命令，并用退出码向调用方（钩子脚本）传达权限决策。src/hooks/rewrite_cmd.rs 中定义的协议表与钩子脚本头部注释完全一致：

退出码	标准输出	含义
0	改写后的命令	允许改写——钩子可自动放行改写后的命令
1	无	无 RTK 等价命令——原样放行
2	无	命中 deny 规则——交由 Claude Code 原生 deny 处理
3	改写后的命令	命中 ask 规则——执行改写但不自动放行，由 Claude Code 提示用户确认

从源码结构看，决策逻辑（evaluate_with_verdict）先读取权限判定（PermissionVerdict），再检查命令是否含有"无法证安全"的构造（contains_unattestable_construct，命中则 Passthrough），最后调用 src/discover/registry.rs 中的 rewrite_command 完成映射——这也解释了 rtk-rewrite.sh 注释中"要支持新命令请改 src/discover/registry.rs（PATTERNS + RULES）"的指引：映射规则集中在 Rust 侧维护，钩子只是执行器。

此外，钩子内置了可选审计日志：设置 RTK_HOOK_AUDIT=1 后，每次 skip/rewrite 决策都会以 时间戳 | 动作 | 原命令 | 改写后命令 的格式追加到 ${RTK_AUDIT_DIR:-$HOME/.local/share/rtk}/hook-audit.log。当"命令没被改写"且原因不明时，开启审计日志再复现一次命令，是定位钩子在哪一步跳过的直接手段；配套的 hooks/claude/rtk-rewrite.sh 与 hooks/claude/test-rtk-rewrite.sh 提供了离线测试钩子行为的脚本。

Troubleshooting：三个高频故障的诊断与修复

故障 1：RTK 已安装但不在 PATH

症状：cargo install --path . 成功，但 which rtk 失败。

诊断：

# 确认二进制是否落在 Cargo bin
ls -la ~/.cargo/bin/rtk

# 确认 ~/.cargo/bin 是否在 PATH 中
echo $PATH | grep -q .cargo/bin && echo "✅ In PATH" || echo "❌ Not in PATH"

修复：

# 加入 ~/.zshrc 或 ~/.bashrc
export PATH="$HOME/.cargo/bin:$PATH"

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

故障 2：多个同名 RTK 二进制冲突

症状：rtk --version 正常，但 rtk gain 报 "command not found"。

原因：crates 上存在另一个同名项目 "Rust Type Kit"（reachingforthejack/rtk），若曾安装它，会得到一个没有 gain/discover 等子命令的二进制。

诊断：

rtk --version
# 应显示 "rtk X.Y.Z"，而不是 "Rust Type Kit"

rtk --help | grep gain
# 应有 "gain" 子命令；缺失即装错了二进制

修复：

cargo uninstall rtk
cargo install --path .   # 安装本仓库的 RTK
rtk gain --help          # 验证应可用

故障 3：Claude Code 中钩子不触发

症状：命令没有被自动改写为 rtk <cmd> 形式。

诊断：

echo $CLAUDE_CODE_HOOK_BASH_TEMPLATE
# 应输出 hook 模板路径；为空说明不在 Claude Code 上下文中

ls -la .claude/hooks/*.sh
# 权限应为 -rwxr-xr-x（可执行）

修复：

chmod +x .claude/hooks/*.sh
# 之后必须重启 Claude Code 会话，钩子才会重新加载

版本兼容矩阵与当前版本说明

diagnose.md 给出了一张功能演进矩阵，帮助判断"缺哪个子命令"对应"哪个版本"：

RTK 版本	rtk gain	rtk discover	Python/Go 支持	备注
v0.14.x	❌ No	❌ No	❌ No	已过时，建议升级
v0.15.x	✅ Yes	❌ No	❌ No	缺少 discover
v0.16.x	✅ Yes	✅ Yes	✅ Yes	推荐版本
main 分支	✅ Yes	✅ Yes	✅ Yes	最新功能

该矩阵描述的是历史版本间的能力边界（gain 自 v0.15 引入、discover 自 v0.16 引入），是"用缺失的子命令反推版本过旧"的依据。需要注意：当前仓库 Cargo.toml 中的版本已演进到 0.42.4，且 src/main.rs 中 gain 与 discover 子命令均已存在，因此在当前仓库构建安装的 RTK 天然覆盖矩阵中"推荐"及以上的全部能力项。

若确认正在运行 v0.15.x 或更早版本，文档建议的升级路径为：

# 在 RTK 仓库根目录
git pull origin main
cargo install --path . --force
rtk --version   # 应显示 0.16.x 或更高

小结

/diagnose 的价值在于把"RTK 集成不生效"这类模糊问题拆成了五个可独立验证的维度：二进制是否在 PATH、钩子文件是否存在且可执行、rtk gain 分析链路是否打通、是否真正处于 Claude Code 上下文、（在仓库内时）Rust 工具链是否就绪。每个维度都配有明确的 ✅/⚠️/❌ 判据、对应的修复命令，以及由 rtk rewrite 退出码协议背书的命令路由语义。按"先并行只读检查、再按报告维度定位、最后选择修复选项"的顺序执行，即可在不动仓库代码的前提下完成 RTK 环境的端到端排障。