1. 概述：为什么需要 RTK

AI 编程助手（Claude Code、Cursor、Codex 等）在执行 git status、cargo test、npm test 等命令时，会将完整的原始输出送入 LLM 上下文窗口。测试框架的一次运行可能产生 5,000–10,000 tokens 的输出，而其中 90% 是冗余信息。

RTK 是一个 Rust 编写的 CLI 代理，位于 AI Agent 和 Shell 之间，自动拦截命令、压缩输出后再送入 LLM。平均节省 60–90% Token，单二进制文件，零依赖，<10ms 开销。

核心数据

指标	数值
GitHub Stars	56,000+
平均压缩率	89%
额外延迟	<10ms
支持命令	100+
二进制大小	~3.8 MB（静态链接）
支持 AI 工具	14+（Claude Code、Cursor、Copilot、Gemini CLI、Codex 等）
许可协议	MIT
最新版本	v0.38.x

实测效果

场景	原始 Token	RTK 后	节省率
cargo test（262 tests）	~4,823	~11	99.8%
git status	~3,000	~600	80%
pytest（33 tests）	~8,000	~256	96.8%
30 分钟完整开发会话	~150,000	~16,850	88.9%
长期统计（15,720 条命令）	—	—	83.7%（1.38 亿 Token）

---

2. 架构原理

2.1 整体数据流

无 RTK:                              有 RTK:

Claude --git status--> Shell --> Git   Claude --git status--> RTK --> Git
  ^                         |           ^                  |         |
  |     ~3,000 tokens 原始   |           |   ~600 tokens    | 过滤    |
  +-------------------------+           +--- (已压缩) -----+---------+

RTK 通过 PreToolUse Hook 在 Claude Code 执行命令前静默改写命令，Claude Code 完全无感知。

2.2 四步改写管线

Claude Code 执行 "git status"
       │
       ▼
  [PreToolUse Hook 拦截]          ← rtk-rewrite.sh（4 状态状态机）
       │
       ▼
  "rtk rewrite" → "rtk git status"  ← Rust 二进制改写命令
       │
       ▼
  RTK 执行 → 4 种策略过滤 → 输出压缩版  ← Rust 过滤管线
       │
       ▼
  Claude Code 看到 ~80% 更少的 Token

2.3 PreToolUse Hook——4 状态状态机

Hook 脚本通过不同退出码控制命令流转：

退出码	行为	JSON 输出
0 + JSON	允许并改写 —— permissionDecision: "allow" + updatedInput	命令已改写，自动批准
1（无 JSON）	透传 —— Hook 无操作，原命令直接执行	无
2（无 JSON）	拒绝移交 —— 交由 Claude Code 原生拒绝规则处理	无
3 + JSON	询问 —— 改写命令但省略 permissionDecision，提示用户确认	改写后输入，无决策

关键安全机制：

• Kill Switch：touch /tmp/agentkit-ccpack-pause 即时停止所有改写
• 版本守卫：解析 rtk --version，版本 < 0.23.0 则优雅退出
• 依赖守卫：检测 jq 可用性，缺失时告警退出（fail-open，不阻塞会话）
• 多 Hook 协调：RTK 通过补丁化插件缓存成为唯一的 Bash PreToolUse 处理器，同时将其他插件作为子进程调用，防止 Claude Code 丢弃 updatedInput

2.4 四种过滤策略

策略	说明	示例
智能过滤	去除注释、空白、样板提示文本	去掉 git status 的 "use git add..." 建议
分组聚合	将相似条目按类别归组	262 个通过测试 → 一行计数
截断	保留关键结构，裁剪次要细节	保留失败堆栈，压缩日志前缀
结构化摘要	保留失败追踪原文，压缩通过输出	只展示失败用例的完整断言信息

2.5 Tee 模式——失败时保留完整输出

当命令失败时，RTK 将完整未过滤输出保存到 ~/.local/share/rtk/tee/，LLM 无需重新执行即可读取：

✓ 42 passed, 1 failed (3.2s)
FAIL: test_parse_complex_input - assertion failed at src/filter.rs:142
📄 Full output: ~/.local/share/rtk/tee/cargo-test-2026-02-12-143052.log

配置项（config.toml）：

[tee]
enabled = true        # 失败时保存原始输出（默认开启）
mode = "failures"     # "failures"、"always" 或 "never"
max_files = 20        # 轮转上限

---

3. 安装

3.1 方式一：Homebrew（macOS 推荐）

brew install rtk

3.2 方式二：Shell 脚本（Linux / macOS）

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

安装到 ~/.local/bin，需确保该目录在 PATH 中。

3.3 方式三：Cargo

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

3.4 方式四：预编译二进制

从 GitHub Releases 下载对应平台的二进制：

• macOS：x86_64 / aarch64
• Linux：musl / gnu
• Windows：msvc

3.5 验证安装

rtk --version   # 应显示 "rtk 0.38.x"
rtk gain        # 应显示 Token 节省统计（区分正版的关键步骤）

⚠️ 注意：crates.io 上存在同名项目 “Rust Type Kit”，安装后务必运行 rtk gain 确认安装的是正确的 rtk-ai/rtk。

---

4. 配置与初始化

4.1 全局初始化（推荐）

# 安装 Hook + RTK.md + 补丁 settings.json
rtk init -g

# 非交互模式（CI/CD）
rtk init -g --auto-patch

# 仅安装 Hook，不添加 RTK.md
rtk init -g --hook-only

rtk init -g 自动完成：

1. 在 ~/.claude/settings.json 注册 PreToolUse Hook
2. 在 CLAUDE.md 中注入 RTK 使用指令
3. 配置 Hook 版本标记和完整性哈希

4.2 按 AI 工具初始化

rtk init -g --gemini              # Gemini CLI
rtk init -g --codex               # Codex (OpenAI)
rtk init -g --agent cursor        # Cursor
rtk init -g --agent windsurf      # Windsurf
rtk init --agent cline            # Cline / Roo Code
rtk init --agent kilocode         # Kilo Code
rtk init --agent hermes           # Hermes
rtk init --agent antigravity      # Google Antigravity

4.3 配置文件

配置文件位于 ~/.config/rtk/config.toml（macOS: ~/Library/Application Support/rtk/config.toml）：

[hooks]
# 跳过这些命令的改写（直接透传）
exclude_commands = ["curl", "playwright"]

[tee]
enabled = true        # 失败时保存原始输出
mode = "failures"     # "failures"、"always" 或 "never"
max_files = 20        # 轮转上限

4.4 卸载

rtk init -g --uninstall  # 移除 Hook、RTK.md、settings.json 条目
brew uninstall rtk        # 如通过 Homebrew 安装
cargo uninstall rtk       # 如通过 Cargo 安装

---

5. Windows 支持

5.1 现状

Unix 平台上，rtk init -g 安装 OS 级别的 PreToolUse Hook，可靠性 ~100%。Windows 上原生不支持 Hook 自动改写，需采用以下替代方案：

方案	机制	可靠性
Unix rtk init -g	PreToolUse Hook（OS 级）	~100%
Windows 默认回退	CLAUDE.md 指令注入	~70–80%
Windows + PowerShell Hook	原生 PreToolUse Hook	~100%
Windows + Git Bash Hook	PreToolUse Hook（通过 bash.exe）	~100%
WSL（推荐）	完整的 Unix Hook 机制	~100%

5.2 推荐方案

WSL 中获得完整体验：在 WSL 中按 Unix 方式安装，所有功能完全可用。

---

6. 支持的命令完整列表（100+）

6.1 文件与搜索

命令	说明
rtk ls	Token 优化的目录树
rtk read <file>	智能文件读取
rtk read <file> -l aggressive	仅保留签名（剥离函数体）
rtk smart <file>	2 行启发式代码摘要
rtk find "*.rs" .	紧凑查找结果
rtk grep "pattern" .	分组搜索结果
rtk diff <f1> <f2>	压缩差异对比
rtk cat / tree / rg	别名，同上

6.2 Git

命令	说明	压缩率
rtk git status	紧凑状态	-80%
rtk git log -n 10	单行提交记录	-
rtk git diff	压缩 diff	-85%
rtk git add / commit / push / pull	返回简洁确认	-
rtk git branch / fetch / stash / show	紧凑输出	-

6.3 GitHub CLI

命令	说明
rtk gh pr list	紧凑 PR 列表
rtk gh pr view 42	PR 详情 + Checks
rtk gh issue list	Issue 列表
rtk gh run list	Workflow 运行状态
rtk gh api / release	紧凑 API 响应

6.4 测试框架

命令	说明	压缩率
rtk cargo test	Rust 测试	-90%
rtk pytest	Python 测试	-90%
rtk go test	Go 测试（NDJSON）	-90%
rtk jest / vitest	JS/TS 测试（仅失败）	-
rtk playwright test	E2E 结果（仅失败）	-
rtk rspec	Ruby RSpec（JSON）	-60%+
rtk npm test	npm 测试	-90%
rtk test <cmd>	通用测试包装器——仅失败	-90%
rtk err <cmd>	仅过滤错误输出	-

6.5 构建与 Lint

命令	说明	压缩率
rtk cargo build	Cargo 构建	-80%
rtk cargo clippy	Cargo Clippy	-80%
rtk tsc	TypeScript 编译错误（按文件分组）	-85%
rtk next build	Next.js 构建	-
rtk lint	ESLint（按规则/文件分组）	-
rtk lint biome	Biome linter	-
rtk ruff check	Python linting（JSON）	-80%
rtk golangci-lint run	Go linting（JSON）	-85%
rtk rubocop	Ruby linting（JSON）	-60%+
rtk prettier --check .	需要格式化的文件列表	-

6.6 包管理

命令	说明
rtk pnpm list	紧凑依赖树
rtk pip list	Python 包（自动检测 uv）
rtk pip outdated	过期包列表
rtk uv pip	UV pip 支持
rtk bundle install	Ruby gems（剥离 Using 行）
rtk prisma generate	Schema 生成（移除 ASCII 艺术）

6.7 AWS

命令	说明
rtk aws sts get-caller-identity	单行身份信息
rtk aws ec2 describe-instances	紧凑实例列表
rtk aws lambda list-functions	名称/运行时/内存（剥离密钥）
rtk aws logs get-log-events	仅时间戳消息
rtk aws cloudformation describe-stack-events	失败优先展示
rtk aws dynamodb scan	展开类型注解
rtk aws iam list-roles	剥离策略文档
rtk aws s3 ls	截断 + tee 恢复

6.8 容器

命令	说明
rtk docker ps	紧凑容器列表
rtk docker images	紧凑镜像列表
rtk docker logs <container>	去重日志
rtk docker compose ps	Compose 服务列表
rtk docker run / build / exec	紧凑运行/构建输出
rtk kubectl pods	紧凑 Pod 列表
rtk kubectl logs <pod>	去重日志
rtk kubectl services	紧凑服务列表
rtk kubectl get / describe / apply	紧凑操作输出

6.9 数据与分析

命令	说明
rtk json config.json	结构展示（不含值）
rtk deps	依赖摘要
rtk env -f AWS	过滤环境变量
rtk log app.log	去重日志
rtk curl <url>	截断 + 保存完整输出
rtk wget <url>	下载，剥离进度条
rtk summary <cmd>	启发式摘要
rtk proxy <cmd>	原始透传 + 追踪

---

7. Token 节省分析

7.1 rtk gain——核心分析命令

rtk gain                # 摘要统计
rtk gain --graph        # ASCII 图表（最近 30 天）
rtk gain --history      # 最近命令历史
rtk gain --daily        # 按日统计
rtk gain --all --format json  # JSON 导出（可用于仪表盘）

7.2 rtk discover——发现遗漏的节省机会

rtk discover                  # 扫描当天遗漏
rtk discover --all --since 7  # 所有项目，最近 7 天

7.3 rtk session——会话中 RTK 采纳率

rtk session   # 查看最近会话中 RTK 的使用占比

7.4 典型 30 分钟 Claude Code 会话 Token 流

操作	频率	原始 Token	RTK Token	节省
ls / tree	10×	2,000	400	-80%
cat / read	20×	40,000	12,000	-70%
git status/diff/log	20×	15,500	3,600	-77%
cargo test / npm test	5×	25,000	2,500	-90%
总计		~118,000	~23,900	-80%

---

8. 安全模型

机制	说明
Fail-Open	依赖缺失或版本不兼容时优雅退出，不阻塞会话
Kill Switch	touch /tmp/agentkit-ccpack-pause 即时停止所有改写
保守白名单	docker run/exec/build 等危险命令不改写，直接透传
原子写入	所有文件修改使用 temp-file-then-rename，绝不产生部分写入
版本守卫	自动检测 RTK 版本，过低版本不注入 Hook
Tee 恢复	失败时保留完整输出，LLM 可直接读取无需重新执行
无网络依赖	单静态二进制，无外部 API 调用
隐私	不发送数据到外部服务

8.1 安全白名单（保守策略）

主动不处理的命令类别：

• docker run / exec / build
• 带有任意参数的 curl / wget
• 不受信任的第三方 CLI

---

9. 高级配置

9.1 Hook 跳过特定命令

[hooks]
exclude_commands = ["curl", "playwright", "terraform apply"]

9.2 开关 Tee 模式

[tee]
enabled = true
mode = "always"    # 无论成功失败都保留原始输出
max_files = 50     # 最多保留 50 个日志文件

9.3 验证 Hook 完整性

rtk verify   # 运行 145+ 完整性测试

---

10. 与同类工具对比

维度	RTK	Caveman	context-mode
设计定位	Shell 输出压缩代理	AI 回复压缩	沙箱执行 + 输出过滤
压缩目标	命令输出（git/test/lint 等）	LLM 回复文本	日志 / Web 抓取
压缩率	60–90%	65–75%	最高 98%
实现语言	Rust（单二进制）	TypeScript	TypeScript（沙箱）
额外延迟	<10ms	~100ms	~50ms
支持命令数	100+	N/A（回复层）	有限
Hook 集成	✅ PreToolUse 自动改写	❌	❌
跨 Agent	14+ 工具	Claude Code 专用	Claude Code 专用

---

11. 轻量分支：rtk-lite-cc

rtk-lite-cc 是专注 Claude Code 的精简分支：

• 剥离 ~15,000 行代码
• 移除：遥测、SQLite 数据库、Token 分析、CLAUDE.md 补丁、权限系统、非 Claude Agent
• 保留：完整过滤管线
• 纯单二进制，零网络调用

适用场景：对隐私极其敏感、只需 Claude Code 支持、偏好最小依赖。

---

12. 故障排查

问题	解决方案
rtk 命令找不到	检查 ~/.local/bin 是否在 PATH 中；或重新执行安装脚本
rtk gain 无输出	确认安装了 rtk-ai/rtk 而非 crates.io 上的同名 “Rust Type Kit”
Hook 未生效（Unix）	运行 rtk init -g 重新注册；检查 ~/.claude/settings.json
Hook 未生效（Windows）	使用 WSL 获得完整体验；或手动配置 PowerShell/Git Bash Hook
PreToolUse Hook 与其他插件冲突	RTK 自动协调多 Hook，通常无需手动处理
Hook 版本告警	运行 rtk init -g 更新版本标记
Tee 文件占用磁盘	调整 max_files 或设置 mode = "failures"
特定命令未改写	检查 exclude_commands 配置和命令白名单

---

参考资源

• GitHub 仓库： github.com/rtk-ai/rtk
• 官方网站： rtk-ai.app
• 安装文档： github.com/rtk-ai/rtk/blob/master/INSTALL.md
• 架构文档： github.com/rtk-ai/rtk/blob/master/ARCHITECTURE.md
• 安全文档： github.com/rtk-ai/rtk/blob/master/SECURITY.md
• 轻量分支： github.com/sderosiaux/rtk-lite-cc
• 配置文件： ~/.config/rtk/config.toml
• 许可协议： MIT
• 最新版本： v0.38.0