RTK代理原理图详解：命令从AI Agent到压缩输出的完整路径

RTK代理原理图详解：命令从AI Agent到压缩输出的完整路径

【免费下载链接】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

RTK（Rust Token Killer）是一个高性能的CLI 代理（CLI proxy），用单个 Rust 二进制、零依赖的方式，把 AI Agent 读取的 bash 命令输出压缩60%–90%。本文用一张"原理路径图"串起它的完整工作机制：你的命令如何从 AI Agent 出发，经过钩子拦截、CLI 解析、过滤器压缩，最终以精简文本回到模型上下文。

一图看懂 RTK 代理的完整路径

先看整体对比：没有 RTK 时，Agent 拿到的是全量原始输出；装上 RTK 后，命令会先绕道 RTK 代理，输出被过滤压缩后才返回。

无 RTK： 有 RTK： Claude --git status--> shell --> git Claude --git status--> RTK --> git ^ | ^ | | | 完整原始输出 | | 压缩输出 | filter | +-----------------------------+ +----- (过滤后) -----+--------+

整条路径可以拆成四个阶段：

阶段	发生位置	核心动作
① 钩子拦截	AI Agent 侧（PreToolUse 事件）	把git status改写成rtk git status
② 解析路由	src/main.rs	Clap 解析参数，按命令枚举分发到对应过滤模块
③ 过滤压缩	src/cmds/或src/filters/	执行命令并只保留"有用信息"
④ 追踪回写	src/core/tracking.rs	记录原始/压缩后字节数，写入 SQLite 供rtk gain展示

下面逐个阶段拆解。

阶段一：钩子拦截与命令改写（Agent → RTK）

这是路径的起点。rtk init会在你的 AI 工具（Claude Code、Copilot、Cursor 等 16 款）里安装一个轻量钩子：

Agent 执行命令（如 cargo test --nocapture） → 钩子拦截 PreToolUse 事件 → 读取 JSON，提取命令字符串 → 调用 rtk rewrite "cargo test --nocapture" → 注册表命中模式，返回 "rtk cargo test --nocapture" → Agent 改写执行，压缩后输出进入 LLM 上下文

几个值得注意的设计：

• 钩子只是"薄代理"：所有改写逻辑都在 Rust 二进制内部（src/discover/registry.rs），钩子脚本只负责适配各家 Agent 的 JSON 格式（见 hooks/README.md），保证 70+ 条改写规则有单一事实来源。
• 复合命令分段处理：cargo fmt --all && cargo test | tail -20会被词法分析器（src/discover/lexer.rs）按&&、|拆段，逐段改写，管道中间环节保持原样，避免破坏 shell 语义。
• 失败即静默放行：任何一步出错（缺依赖、无匹配规则），原始命令照常执行——这是 RTK "Fail-Safe" 设计原则的第一道体现。

阶段二：CLI 解析与命令路由

改写后的rtk git status进入 RTK 主程序，路径如下：

1. Clap 解析：Cli::try_parse()把命令行匹配到Commands枚举（入口在src/main.rs）；
2. 完整性检查：src/hooks/integrity.rs校验已安装钩子的 SHA-256 哈希，防止钩子被篡改；
3. 路由分发：一个match cli.command把请求派发到 42 个命令过滤模块中的对应一个。

如果命令不在枚举里（比如rtk some-unknown-tool），不会报错，而是进入fallback 路径：先查 TOML 声明式过滤器，再匹配不上就纯透传——RTK 保证"透明代理"，未知命令原样执行。

阶段三：双过滤器系统与压缩策略（核心环节）

这是"省 token"真正发生的地方。RTK 有两套过滤系统：

• Rust 过滤器（src/cmds/）：编译进二进制的高性能模块，按生态组织——git、rust、js、python、go、dotnet、cloud、system 等 9 个生态，处理复杂转换（JSON 解析、状态机、正则分组）；
• TOML DSL 过滤器（src/filters/*.toml）：声明式配置，8 级流水线（去 ANSI → 正则替换 → 行匹配保留/剔除 → 截断 → 头尾裁剪等），适合快速为新命令补规则。

以rtk git log --oneline -5为例，执行生命周期六步走：

PARSE（解析参数）→ ROUTE（路由到 git 模块） → EXECUTE（真正跑 git，捕获 stdout + 退出码） → FILTER（统计抽取：5 commits, +142/-89，压缩 96%） → PRINT（输出彩色精简结果） → TRACK（500 字节 → 20 字节 写入 ~/.local/share/rtk 数据库）

不同命令类型对应不同压缩策略，官方归纳了 12 类，挑几个最直观的：

策略	原始输出	压缩后	典型命令
统计抽取	5000 行 status	3 files, +142/-89	git status、git diff
失败聚焦	100 个测试全量输出	2 failed: test_auth...	pytest、vitest、go test
按模式分组	100 条零散 lint 错误	no-unused-vars: 23	lint、tsc、ruff
日志去重	重复日志行	[ERROR] ... (×5)	rtk log
进度条剥离	ANSI 动态进度条	✓ Downloaded	wget、pnpm install
树形压缩	50 个文件平铺列表	src/ ├─ lib/ (12)	ls、tree

想看完整策略矩阵，可参考 docs/contributing/ARCHITECTURE.md 中的 Filtering Strategy Taxonomy 章节。

阶段四：Token 追踪与失败恢复

路径的最后两环让"省了多少"变得可量化、可追溯：

• Token 追踪：每次执行都记录原始/压缩字节数（按bytes / 4估算 token）、节省百分比、项目路径到 SQLite，数据自动保留 90 天。运行rtk gain即可看到节省看板与 30 天 ASCII 图表；rtk discover还能反查哪些高频命令还没被压缩。
• Tee 失败恢复：命令退出码非零时，RTK 会把未过滤的完整原始输出另存到本地日志文件，并在结果里附一行提示路径——Agent 需要细节时重读文件即可，不必重跑失败命令。

为什么这套代理设计可靠？

四条设计原则贯穿始终（详见 docs/contributing/TECHNICAL.md）：

1. Fail-Safe：过滤失败 → 回退原始输出，绝不吞掉信息；
2. 退出码保真：RTK 永不掩盖非零退出码，CI/CD 场景安全；
3. 透明可控：-v/-vv/-vvv三级调试可看到被过滤前的原始输出；
4. 极低开销：单线程、无 async，启动 <10ms，常驻内存 <5MB。

⚠️ 小贴士：RTK 压缩的是bash 输出占用的输入 token，它只是账单中"输入 token"的一部分贡献者，不等于整单费用下降 90%。官方口径：百分比可靠，绝对 token 数为近似值。

快速上手：5 分钟跑通完整路径

# 1. 安装（任选其一） brew install rtk # 或：curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh # 2. 为你的 AI 工具安装钩子 rtk init -g # 3. 重启 AI 工具后测试 git status # 自动被改写为 rtk git status # 4. 查看节省效果 rtk gain # 节省看板 rtk gain --graph # 近 30 天 ASCII 图表

一条命令走完全程：Agent 发命令 → 钩子改写 → RTK 路由 → 过滤压缩 → 精简输出回传 → 节省数据入库。理解这条路径后，你就能明白为什么 RTK 能以 <10ms 的开销，稳定为 AI Agent 省下 60%–90% 的命令输出 token。

【免费下载链接】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