rtk

rtk 快速入门

rtk（rtk-ai/rtk，Rust Token Killer）是拦在 shell 与大模型之间的 CLI 代理：你的 AI 编码 agent 每次执行 ls、git status、cargo test 这类命令时，rtk 先把原始输出压缩成结构化摘要，再把摘要交给模型——官方口径可削减最高 90% 的 bash 输出、单次开销 <10ms。单个 Rust 二进制、零运行时依赖，原生适配 Claude Code、Codex、Gemini CLI、Cursor、Windsurf、Cline、Kimi 等 15+ Agent（rtk init 一条命令完成注入）。Apache-2.0。2026-09-30 核验（GitHub API + 官方 README）：82,017★ / 5,203 fork，最近 push 2026-09-29（高频活跃），v0.50.0 已发布，Rust 主语言，170 名贡献者。

这是什么？适合谁？

agentic coding 的隐性成本大头不在模型，而在上下文里的命令输出：一次 ls 递归目录、一次全量测试跑、一段 git diff，动辄几千 token 灌进上下文，而 agent 真正需要的只是「哪些文件、哪个测试挂了、改了什么」。rtk 的做法是在 shell 与模型之间加一层确定性代理，按命令类型套用四种策略压缩输出：智能过滤（去注释/空白/样板）、分组聚合（文件按目录、错误按类型）、截断（保留相关上下文砍冗余）、去重（重复日志行折叠为计数）。例如 rtk git push 只回一行 ok main，rtk jest 只列失败用例。

适合人群：重度使用 Claude Code / Codex / Gemini CLI 等 agent CLI 的开发者（token 账单与上下文占用直接受益）；跑长会话 agent 任务、经常被无关输出淹没关键报错的团队；想在 agent 权限层加一道命令门禁的安全 minded 用户（rtk 的 hook 协议同时支持 allow/deny 规则）。

不适合谁：不用 agentic coding 工具的人（普通终端场景压缩收益有限）；对「任何中间层」零容忍的极简主义者（虽然 <10ms 开销几乎无感）；Windows 用户注意：hook 系统原生可用，但需在 PowerShell/Windows Terminal 里跑，且 cmd /C 直接执行语义有差异（详见官方 INSTALL.md）。

准备工作

1. 一台 macOS / Linux / Windows（含 WSL）机器；Homebrew（brew install rtk）、winget（winget install rtk-ai.rtk）、curl 安装脚本、cargo install --git 四种方式任选其一
2. 已安装的 AI agent：Claude Code / Copilot（默认）、Codex、Gemini CLI、Cursor、Windsurf、Cline、Antigravity、Kimi、Hermes、OMP 等（rtk init --help 查看完整列表）
3. 时间预算：安装 + 注入 5 分钟；跑通验证 5 分钟
4. 零成本：Apache-2.0 开源，本地运行不联网

⚠️ 命名冲突坑：crates.io 上另有一个叫 “rtk”（Rust Type Kit）的包。cargo install rtk 可能装错；官方建议用 cargo install --git https://github.com/rtk-ai/rtk 或 Homebrew/winget。

核心用法：四步上手

第 1 步：安装

# macOS（推荐）
brew install rtk
# Windows
winget install rtk-ai.rtk
# Linux/macOS 通用
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
# Rust 工具链
cargo install --git https://github.com/rtk-ai/rtk

验证：rtk --version 显示版本号、rtk gain 显示节省面板即成功。

第 2 步：给你的 agent 注入

rtk init -g                  # Claude Code / Copilot（全局）
rtk init -g --codex          # Codex（OpenAI）
rtk init -g --gemini         # Gemini CLI
rtk init -g --agent cursor   # Cursor
rtk init --agent cline       # Cline / Roo Code

然后重启你的 AI 工具。hook 型 agent 会在执行 Bash 命令前自动改写为 rtk <cmd>（如 git status → rtk git status）；插件型 agent（如 Hermes）走各自插件 API 完成改写。agent 全程无需显式调用 rtk。

第 3 步：验证生效

在 agent 会话里执行 git status，观察返回是否变成了紧凑的分组摘要（按状态分组 + 计数），而不是原始逐行列表。再跑一次你项目的测试命令（rtk jest / rtk pytest / rtk cargo test），确认只回失败用例、通过用例折叠为一行计数。想看累计收益，随时跑 rtk gain。

第 4 步：覆盖非 Bash 路径（重要）

hook 只拦截 Bash 工具调用——Claude Code 内置的 Read / Grep / Glob 不经过 Bash hook，不会被自动改写。要吃到这些场景的压缩，让 agent 改用 shell 命令（cat/head/tail、rg/grep、find），或直接调用 rtk read、rtk grep、rtk find。rtk read file.rs -l aggressive 可只回签名与结构、rtk smart file.rs 给两行代码摘要。

常见踩坑

1. 症状：装完 agent 里毫无变化。 根因：rtk init 后没有重启 AI 工具（hook 在会话启动时加载）。解决：完全退出并重启 agent；仍无效则跑 rtk init 确认无报错、检查对应 agent 的 hook 配置文件是否生成。
2. 症状：cargo install rtk 装到了另一个包。 根因：crates.io 命名冲突（Rust Type Kit 同名）。解决：卸载后改用 cargo install --git https://github.com/rtk-ai/rtk，或 brew/winget 渠道；rtk gain 报错即是装错的典型信号。
3. 症状：token 账单只降了一点，远不到 90%。 根因：官方口径是「bash 输出的削减」，不是「账单的削减」——bash 输出只是输入 token 的一部分，输入又只是账单的一部分，稀释是设计内的。解决：确认压缩覆盖面（把 Read/Grep 类操作也导流到 shell），用 rtk gain 看真实输出削减比例；token 数按 bytes/4 估算，绝对值仅供参考，百分比才可靠。
4. 症状：Windows 下双击 rtk.exe 一闪而过。 根因：它是 CLI 程序，双击会闪退。解决：从 PowerShell / Windows Terminal 运行；注意 cmd /C 直执行的搜索路径与内置命令行为与 Unix 有差异（126/127 退出码语义），详见官方 INSTALL.md 的 Windows 段。
5. 症状：担心压缩丢掉 agent 需要的信息。 根因：截断策略对超长输出做保留性裁剪。解决：rtk 的压缩是确定性的（同命令同输出同摘要），需要完整原始输出时显式绕过（不走 rtk 前缀）即可；对 Claude 的 prompt cache 无破坏（输出一次过滤后照常缓存）。

常见问题 FAQ

Q1: rtk 会不会破坏 Claude Code 的 prompt cache？

A: 不会。官方明确说明：过滤在每条命令执行时做一次，结果进入会话历史后照常缓存；更小的输出反而让 cache 写入与读取都更便宜。

Q2: 90% 的数字可信吗？

A: 「最高 90%」指 bash 输出的削减（ls/git/测试类命令压缩率最高），不是账单削减。rtk 不内置 tokenizer，token 数按 bytes/4 估算——百分比可靠、绝对值近似。完整口径见官方文档 savings-explained 一节。

Q3: 支持哪些命令？

A: 官方口径 100+ 条：文件类（ls/tree/cat/read/find/grep/diff/ast-grep）、git 全家（status/log/diff/add/commit/push）、GitHub CLI（gh pr/issue/run）、测试框架（jest/vitest/pytest/go test/cargo test）、lint（ruff/sqlfluff）、docker ps 等。不在列表里的命令原样透传，不受影响。

Q4: 和 Claude Code 自带的上下文压缩是一回事吗？

A: 不是。模型侧压缩（compact）是对会话历史的二次摘要，有损且发生在事后；rtk 是对命令输出的确定性前置过滤，在信息进上下文之前就裁掉噪声，两者互补、可同时用。

Q5: 商用/团队部署有什么限制？

A: Apache-2.0，无商用限制。本地单二进制运行，不联网、不上传数据；团队里给每台机器跑一次 rtk init -g 即可，也支持项目级 .rtk/filters.toml 定制过滤规则并随仓库分发。

参考链接

• 官方仓库 rtk-ai/rtk
• 官网 rtk-ai.app
• 官方安装文档 INSTALL.md
• 节省口径说明 savings-explained
• Homebrew formula

本文章基于公开资料整理，AI 辅助生成，独立实测与数据核验日期 2026-09-30（GitHub API 实时读取 stars/fork/pushed/license；未在本机做完整安装实测）。