6. 使用建议与最佳实践

6.1 快速入门指南

6.1.1 安装验证

# 1. 安装（选择一种方式）

# Homebrew（推荐，macOS/Linux）
brew install rtk

# Quick Install（Linux/macOS）
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

# Cargo（通用）
cargo install --git https://github.com/rtk-ai/rtk

# 2. 验证安装
rtk --version   # 应显示 "rtk 0.27.1"
rtk gain        # 应显示 token 节省统计

# ⚠️ 如果 `rtk gain` 失败，说明安装了错误的包（Rust Type Kit）
# 解决：cargo uninstall rtk && cargo install --git https://github.com/rtk-ai/rtk

6.1.2 初始配置

# 1. 安装 Hook（推荐，实现自动重写）
rtk init --global

# 2. 验证 Hook 安装
rtk init --show
# 应显示："✅ Hook: executable, with guards"

# 3. 重启 Claude Code
# Hook 在 PreToolUse 阶段生效，需重启 Claude Code

# 4. 测试
git status  # 应自动重写为 rtk git status

6.1.3 配置模板

# ~/.config/rtk/config.toml

[general]
default_filter_level = "minimal"  # 平衡压缩率和精度
enable_tracking = true            # 启用 token 追踪

[hooks]
# 排除敏感命令（根据环境调整）
exclude_commands = [
    "curl", "wget",              # 网络请求
    "scp", "ssh", "sftp",        # 远程连接
    "vault",                     # 密钥管理
    "kubectl exec",              # 容器执行
]

[tee]
enabled = true
mode = "failures"  # 仅失败时保存完整输出
max_files = 20     # 轮转限制

[tracking]
database_path = "~/.local/share/rtk/history.db"
retention_days = 90  # 90 天后自动清理

6.2 场景化使用建议

6.2.1 日常开发（推荐配置）

场景：个人开发，LLM 辅助编码

配置：

[general]
default_filter_level = "minimal"

[hooks]
exclude_commands = []  # 无排除，100% 自动重写

[tee]
enabled = true
mode = "failures"

使用模式：

# 完全依赖 Hook 自动重写
git status      # → rtk git status
git diff        # → rtk git diff
cargo test      # → rtk cargo test
npm run lint    # → rtk lint

# 查看 token 节省
rtk gain

预期收益：

• Token 节省：70-80%
• 时间节省：~5 分钟/小时开发
• 精度损失：可接受（日常开发场景）

6.2.2 调试阶段（高精度配置）

场景：排查复杂 Bug，需要完整上下文

配置：

[general]
default_filter_level = "none"  # 不过滤

[tee]
enabled = true
mode = "always"  # 始终保存完整输出

使用模式：

# 使用 verbose 模式查看完整输出
rtk cargo test -vvv      # 显示原始输出
rtk git diff -vvv        # 显示完整 diff

# 或直接使用原始命令
cargo test
git diff

# 查看 Tee 文件（如果需要）
cat ~/.local/share/rtk/tee/1707753600_cargo_test.log

预期效果：

• Token 节省：0-20%（调试阶段不追求节省）
• 信息完整：100%
• 调试效率：最大化

6.2.3 代码审查（平衡配置）

场景：Review PR，需要理解代码变更

配置：

[general]
default_filter_level = "minimal"

[tee]
enabled = true
mode = "failures"

使用模式：

# 使用 RTK 查看概览
rtk git diff feature-branch  # 压缩的 diff

# 关键 PR 使用原始命令
git diff feature-branch > /tmp/pr.diff  # 完整 diff 用于审查

# 使用 RTK 查看文件
rtk read src/main.rs -l minimal  # 保留注释，去除函数体

建议：

• ✅ 日常 PR 使用 RTK
• ⚠️ 关键 PR（安全、架构变更）使用原始 diff
• ❌ 不要在 RTK 压缩的 diff 上直接应用 patch

6.2.4 CI/CD 失败排查（推荐配置）

场景：CI 构建失败，需要快速定位问题

配置：

[tee]
enabled = true
mode = "always"  # CI 环境始终保存完整输出

使用模式：

# 在 CI 中使用 RTK
rtk cargo build    # 构建错误概览
rtk cargo test     # 测试失败概览

# 查看完整输出（通过 Tee）
cat ~/.local/share/rtk/tee/*_cargo_test.log

# 或使用 verbose 模式
rtk cargo test -vvv

CI 配置示例（.github/workflows/ci.yml）：

- name: Install RTK
  run: curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh

- name: Build
  run: rtk cargo build

- name: Test
  run: rtk cargo test
  continue-on-error: true  # RTK 保留退出码，失败会正确报告

- name: Upload Tee Logs
  if: failure()
  uses: actions/upload-artifact@v4
  with:
    name: rtk-tee-logs
    path: ~/.local/share/rtk/tee/

6.2.5 生产环境（谨慎配置）

场景：生产环境运维，需完整审计

配置：

[general]
enable_tracking = false  # 禁用追踪，避免记录敏感命令

[hooks]
# 排除所有敏感命令
exclude_commands = [
    "curl", "wget", "scp", "ssh",
    "vault", "kubectl", "docker",
    "aws", "gcloud", "az",
]

[tee]
enabled = true
mode = "always"  # 始终保存，用于审计
max_files = 100  # 增加轮转限制

使用模式：

# 手动使用 RTK 前缀（禁用 Hook 自动重写）
rtk kubectl get pods
rtk docker ps

# 敏感操作使用原始命令
curl -X POST https://api.internal/deploy  # 不使用 RTK
kubectl apply -f deployment.yaml          # 不使用 RTK

建议：

• ⚠️ 生产环境建议禁用 Hook，使用手动 rtk 前缀
• ⚠️ 启用 Tee mode=always，保留完整审计日志
• ⚠️ 定期清理 Tee 文件，避免敏感信息泄露

6.3 常用命令参考

6.3.1 文件操作

# 目录浏览（树状压缩）
rtk ls .                    # 标准模式
rtk ls -u                   # 超紧凑模式（ASCII 图标）

# 文件阅读（代码过滤）
rtk read file.rs            # 标准模式（保留注释）
rtk read file.rs -l minimal # 最小过滤（仅去注释）
rtk read file.rs -l aggressive  # 激进过滤（仅保留签名）

# 代码搜索
rtk grep "pattern" .        # 按文件分组结果
rtk find "*.rs" .           # 紧凑 find 输出

6.3.2 Git 操作

# Git 状态
rtk git status              # 2 modified, 1 untracked ✓
rtk git status -u           # 超紧凑模式

# Git 日志
rtk git log -n 10           # 10 commits, +142/-89
rtk git log --oneline -n 20 # 20 commits（单行摘要）

# Git 差异
rtk git diff                # 压缩的 diff（人类可读）
rtk git diff --stat         # 仅统计信息

# Git 操作
rtk git add .               # → "ok"
rtk git commit -m "msg"     # → "ok abc1234"
rtk git push                # → "ok main"
rtk git pull                # → "ok 3 files +10 -2"

6.3.3 测试运行

# Rust
rtk cargo test              # 仅失败项（-90%）
rtk cargo test -v           # 显示所有测试

# JavaScript/TypeScript
rtk vitest run              # 仅失败项（-99.5%）
rtk playwright test         # E2E 结果（仅失败）
rtk npm test                # 调用 runner 测试模式

# Python
rtk pytest                  # 仅失败项（-90%）
rtk pytest -v               # 显示所有测试

# Go
rtk go test                 # NDJSON 流，仅失败包（-90%）
rtk go test ./...           # 所有包

6.3.4 Lint/编译

# JavaScript/TypeScript
rtk lint                    # ESLint 按规则/文件分组
rtk lint biome              # Biome lint
rtk tsc                     # TypeScript 错误按文件分组
rtk prettier --check .      # 仅列出需要格式化的文件

# Python
rtk ruff check              # JSON 输出，按规则分组
rtk ruff format             # 文本输出，摘要

# Go
rtk golangci-lint run       # JSON 输出，按规则分组

# Rust
rtk cargo clippy            # 压缩的 clippy 输出（-80%）
rtk cargo build             # 仅错误（-80%）

6.3.5 Token 分析

# 查看节省统计
rtk gain                    # 摘要统计
rtk gain --graph            # ASCII 图表（最近 30 天）
rtk gain --history          # 最近命令历史
rtk gain --daily            # 每日明细
rtk gain --all --format json  # JSON 导出

# 发现未优化的命令
rtk discover                # 发现可优化的命令
rtk discover --all --since 7  # 所有项目，最近 7 天

6.4 故障排查

6.4.1 常见问题

问题 1：rtk gain 命令不存在

症状：

$ rtk --version
rtk 1.0.0

$ rtk gain
rtk: 'gain' is not a rtk command.

原因：安装了错误的包（Rust Type Kit）

解决：

cargo uninstall rtk
cargo install --git https://github.com/rtk-ai/rtk
rtk gain  # 验证

问题 2：Hook 不生效

症状：Claude Code 不自动使用 RTK

检查：

rtk init --show
# 应显示："✅ Hook: executable, with guards"

解决：

# 1. 重新安装 Hook
rtk init --global

# 2. 验证 settings.json
cat ~/.claude/settings.json | grep -A5 PreToolUse

# 3. 重启 Claude Code

问题 3：命令被错误重写

症状：curl https://api.internal 被重写为 rtk curl ...，行为异常

解决：

# ~/.config/rtk/config.toml
[hooks]
exclude_commands = ["curl", "wget", "ssh"]  # 添加排除

6.4.2 诊断脚本

# 运行官方诊断脚本
bash scripts/check-installation.sh

# 检查内容：
# ✅ RTK 已安装且在 PATH 中
# ✅ 正确的版本（Token Killer，非 Type Kit）
# ✅ 可用功能（pnpm, vitest, next 等）
# ✅ Claude Code 集成（CLAUDE.md 文件）
# ✅ 自动重写 Hook 状态

6.5 最佳实践清单

6.5.1 安装阶段

• 使用官方安装方式（Homebrew 或 install.sh）
• 验证安装：rtk --version 和 rtk gain
• 确认是 Token Killer，非 Type Kit
• 添加到 PATH（如果需要）

6.5.2 配置阶段

• 安装 Hook：rtk init --global
• 验证 Hook：rtk init --show
• 配置排除列表（根据环境）
• 启用 Tee：mode = "failures" 或 "always"
• 设置追踪保留时间：retention_days = 90

6.5.3 日常使用

• 依赖 Hook 自动重写（无需手动输入 rtk）
• 定期查看 rtk gain 了解节省效果
• 调试时使用 -vvv 查看完整输出
• 关键操作使用原始命令（不依赖 RTK）

6.5.4 安全维护

• 定期清理 Tee 文件（或使用轮转机制）
• 定期清理 tracking.db（或依赖自动清理）
• 审查排除列表，确保敏感命令被排除
• 更新 RTK：brew upgrade rtk 或重新运行 install.sh

6.5.5 团队协作

• 在团队文档中说明 RTK 的使用
• 统一配置（可共享 config.toml 模板）
• 培训团队成员了解 RTK 的局限性
• 在 CI/CD 中可选集成 RTK

6.6 进阶技巧

6.6.1 自定义过滤级别

# 临时覆盖默认配置
rtk read file.rs -l aggressive  # 激进过滤
rtk read file.rs -l none        # 不过滤

# 创建别名（.bashrc 或 .zshrc）
alias rtk-read-signatures='rtk read -l aggressive'
alias rtk-read-full='rtk read -l none'

6.6.2 批量分析

# 导出 JSON 数据用于自定义分析
rtk gain --all --format json > rtk-stats.json

# 使用 jq 分析
jq '.commands' rtk-stats.json                    # 总命令数
jq '.avg_savings_pct' rtk-stats.json             # 平均节省率
jq '.top_commands[0:5]' rtk-stats.json           # Top 5 命令

6.6.3 自定义 Hook 规则

# 编辑 Hook 脚本（高级用户）
vim ~/.claude/hooks/rtk-rewrite.sh

# 添加自定义重写规则
case "$cmd" in
    my-custom-cmd*) echo "rtk summary $cmd" ;;
    # ...
esac

6.7 结论

6.7.1 推荐使用场景

6.7.2 核心价值

1. Token 节省：60-90% 平均节省率，降低 LLM 使用成本
2. 效率提升：减少 LLM 响应时间，提升开发流畅度
3. 信息聚焦：过滤噪声，突出关键信息
4. 透明执行：所有命令可见，退出码保留

6.7.3 使用原则

1. 场景驱动：根据场景选择合适的精度级别
2. 配置优先：通过配置平衡节省和精度
3. 安全底线：敏感操作使用原始命令
4. 持续优化：定期审查配置，根据反馈调整

6.7.4 最终建议

RTK 是一个值得投资的开发效率工具。对于日常开发场景，它能显著降低 token 消耗，提升 LLM 辅助开发的流畅度。但需了解其局限性，在关键场景（生产运维、安全审计、根因分析）使用原始命令。

推荐起步路径：

1. 安装验证 → 2. 配置 Hook → 3. 日常使用 → 4. 定期优化

避免的陷阱：

• ❌ 在生产环境盲目使用
• ❌ 不配置排除列表
• ❌ 忽略 Tee 文件的敏感信息
• ❌ 在关键场景依赖压缩输出

合理使用 RTK，让它成为你的开发利器，而非潜在风险源。