rtk-awareness 解析：rtk 如何让 Claude Code 自动经 rtk 代理命令以压缩 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
hooks/claude/rtk-awareness.md是 rtk（Rust Token Killer）为 Claude Code 准备的一份“意识文件”：它被rtk init嵌入到用户的 Claude 指令体系中，告诉 AI Agent 哪些 rtk 元命令应直接调用、如何验证 rtk 安装正确，以及其余命令为何无需关心——因为它们会被 Claude Code 的PreToolUsehook 透明改写成rtk <cmd>形式。读完本文，你将掌握这份意识文件的完整用法、它在 rtk 安装流程中的生成与注入链路，以及底层 hook 改写协议（rtk rewrite退出码协议、版本守卫、审计日志）的实现细节。
rtk-awareness.md 的定位与内容全貌
rtk-awareness.md 是一份刻意保持极短的指令文件，hooks/claude/README.md 称之为 “slim instructions file”，由rtk init安装时写入用户环境。它只有三块内容：
- Meta Commands（元命令）——要求 Agent “始终直接使用 rtk”调用，即不经过 hook 改写、由 Agent 主动发起的管理类命令：
rtk gain # Show token savings analytics rtk gain --history # Show command usage history with savings rtk discover # Analyze Claude Code history for missed opportunities rtk proxy <cmd> # Execute raw command without filtering (for debugging)- Installation Verification（安装验证）——用于确认 PATH 里的是正确的 rtk 二进制：
rtk --version # Should show: rtk X.Y.Z rtk gain # Should work (not "command not found") which rtk # Verify correct binary- Hook-Based Usage（hook 接管）——明确告知 Agent：其余所有命令都由 Claude Code hook 自动改写，例如
git status→rtk git status，透明且 0 token 开销，完整命令参考见 CLAUDE.md。
这份文件的设计意图是把需要 Agent 主动知道的事情压到最少：只有元命令（查询节省量、审计历史、调试透传）必须“直接执行”，日常开发命令全部交给 hook 静默改写，Agent 上下文里因此不需要维护一长串命令映射表。
它从哪里来：rtk init的注入链路
从源码结构看，这份文件并不是安装后手工拷贝的，而是编译期打包进二进制的内嵌字符串。在 src/hooks/init.rs 中：
// Embedded slim RTK awareness instructions const RTK_SLIM: &str = include_str!("../../hooks/claude/rtk-awareness.md"); const RTK_SLIM_CODEX: &str = include_str!("../../hooks/codex/rtk-awareness.md");rtk init的默认模式（run_default_mode，见 init.rs）会：
- 将
RTK_SLIM的完整内容原子写入~/.claude/RTK.md（见 init.rs 中write_if_changed(&rtk_md_path, RTK_SLIM, RTK_MD, ctx)），并通过@RTK.md引用挂接到用户的CLAUDE.md； - 同时向
~/.claude/settings.json的hooks.PreToolUse注入改写 hook（常量见 src/hooks/constants.rs：hook 文件名为rtk-rewrite.sh，当前安装形态的 hook 命令是rtk hook claude）； - 使用 tempfile + rename 的
atomic_write保证写入不损坏已有文件，且写入是幂等的（内容相同则跳过）。
值得注意的是，同一个RTK_SLIM内容还被复用于其他 Agent 的指令文件：Gemini 的GEMINI.md（init.rs）和 Vibe 的 prompt 文件（init.rs），也就是说这份“意识文件”是 rtk 多 Agent 支持中共享的最小知识单元；卸载时rtk init --global的对应清理逻辑会移除RTK.md、CLAUDE.md中的引用块以及settings.json里的 hook 条目。
元命令详解：awareness 文件中的四条核心指令
awareness 文件要求 Agent “always use rtk directly” 的四条命令，分别对应 rtk 的分析与调试能力，以下逐一结合源码说明其行为。
rtk gain 与 rtk gain --history：节省量分析
rtk gain输出 token 节省统计，--history追加展示每条命令的使用历史。实现位于 src/analytics/gain.rs，入口函数签名即为run(..., history: bool, ...)（见 gain.rs），history标志开启后在 gain.rs 处输出历史明细。节省数据的来源是 SQLite 跟踪库：CLAUDE.md 说明“Token savings are tracked in SQLite viasrc/core/tracking.rs”，且 RTK 不内置 tokenizer，token 数按bytes / 4估算——因此这些数字是“可靠的比例 + 近似的绝对值”。
rtk discover：发现被漏掉的节省机会
rtk discover分析 Claude Code 的命令历史，找出没有经过 RTK 过滤执行的命令并估算潜在损失，支持rtk discover --all（所有项目）与rtk discover --all --since 7（最近 7 天）等参数。行为细节可参考 docs/guide/analytics/discover.md。如果安装后该报告仍持续列出“漏网”命令，通常意味着 hook 对当前 Agent 未生效——这正是 awareness 文件与 hook 配置需要一起检查的信号。
rtk proxy ：无过滤透传（调试用）
rtk proxy <command> [args...]绕过 RTK 过滤执行原生命令，但依然记录用量（在rtk gain --history中显示为 0% 削减，输入 = 输出）。CLAUDE.md 中给出三个典型用途与示例：
rtk proxy git log --oneline -20 # Full git log output (no truncation) rtk proxy npm install express # Raw npm output (no filtering) rtk proxy curl https://api.example.com/data # Any command works它同时扮演“过滤出 bug 时的逃生通道”与“保证任何命令都能跑”的兼容兜底——这也是 awareness 文件强调调试场景用rtk proxy而非直接裸命令的原因。
安装验证与同名项目陷阱
awareness 文件专门用一条警告强调命名冲突：
⚠️Name collision: If
rtk gainfails, you may have reachingforthejack/rtk (Rust Type Kit) installed instead.
CLAUDE.md 对此有完整阐述：生态里存在两个名为 "rtk" 的项目——本项目 Rust Token Killer 与 reachingforthejack/rtk（Rust Type Kit，生成 Rust 类型，完全不同）。因此验证序列是三条命令交叉确认：
rtk --version # 应显示 "rtk 0.28.2"（或更新版本） rtk gain # 应显示节省统计（而非 "command not found"） which rtk # 确认二进制来源rtk gain是关键的判别探针：Rust Type Kit 没有gain子命令，一旦报 command not found 即可断定装错了包。
Hook-Based Usage 的底层机制：透明改写协议
awareness 文件最后一段写道：“All other commands are automatically rewritten by the Claude Code hook. Example:git status→rtk git status(transparent, 0 tokens overhead)”。这句话的完整实现链路由三部分组成。
1. 薄 Bash hook：rtk-rewrite.sh
rtk-rewrite.sh 是一个刻意保持“薄”的PreToolUsehook，文件头注释明确：所有改写逻辑都在rtk rewrite子命令中（Rust 注册表是唯一事实来源），shell 脚本只做守卫与委托。其执行流程：
- 依赖守卫：
jq缺失 → 打印警告并exit 0（静默降级）；rtk缺失 → 同样静默退出（见 rtk-rewrite.sh）； - 版本守卫：
rtk rewrite是 0.23.0 才引入的命令，脚本解析rtk --version并缓存到$XDG_CACHE_HOME/rtk-hook-version-ok，低于 0.23.0 则警告后退出（见 rtk-rewrite.sh）； - 委托改写：从 stdin 读入 Claude Code 的 JSON，用
jq提取.tool_input.command，然后执行rtk rewrite "$CMD"，按退出码分流（见 rtk-rewrite.sh）：
| 退出码 | 含义 | hook 动作 |
|---|---|---|
| 0 + stdout | 找到改写且无 deny/ask 规则命中 | 输出updatedInput并自动放行（permissionDecision: "allow"） |
| 1 | 无 RTK 等价命令 | 原样透传，不做任何事 |
| 2 | 命中 deny 规则 | 透传，交给 Claude Code 原生 deny 处理 |
| 3 + stdout | 命中 ask 规则 | 输出改写但不带permissionDecision，由 Claude Code 弹确认框 |
放行与请求确认两种分支的 JSON 输出分别见 rtk-rewrite.sh。hooks/claude/README.md 总结其失败哲学：jq 缺失、rtk 缺失、版本过旧、无匹配——任何失败都静默exit 0，绝不让 hook 打断 Agent 工作流。
2. Rust 端决策：rtk rewrite
真正的判定逻辑在 src/hooks/rewrite_cmd.rs 的run()中，其文档注释完整定义了退出码协议（0/1/2/3 与上表一致）。决策函数evaluate_with_verdict（rewrite_cmd.rs）按顺序做三件事：
- 权限裁决：读取 Claude Code 的 settings 规则（allow/ask/deny）。
Deny直接返回退出码 2； - 不可证明结构检查：
crate::discover::lexer::contains_unattestable_construct(cmd)检测到反引号、$()命令替换、文件重定向等无法静态证明等价性的结构时，一律透传，不冒险改写；注意 fd 复制（2>&1）不算在内，仍可改写——这与测试中cargo test 2>&1→rtk cargo test 2>&1的行为一致； - 注册表改写：
registry::rewrite_command(cmd, excluded, transparent_prefixes)（src/discover/registry.rs）查找改写规则，支持exclude_commands（排除清单）与transparent_prefixes两个用户配置项。
一个安全关键点值得注意：PermissionVerdict::Default（无任何规则命中）必须映射到退出码 3（ask）而非 0（allow），否则任何没有显式 allow 规则的命令都会被 hook 自动放行，绕过 Claude Code 的最小权限默认值。该约束由 rewrite_cmd.rs 中专门的exit_code_protocol测试模块固化，防止未来重构引入自动放行旁路。
3. 回归验证：60+ 断言的测试套件
hooks/claude/test-rtk-rewrite.sh 通过向 hook 喂入 mock JSON 来验证改写行为，可用HOOK=/path/to/rtk-rewrite.sh覆盖测试目标（见 hooks/claude/README.md）。测试覆盖了 awareness 文件所依赖的全部关键行为：
- 基础改写：
git status→rtk git status、rg pattern src/→rtk grep pattern src/、cat package.json→rtk read package.json； - 环境变量前缀保留：
GIT_PAGER=cat git status→GIT_PAGER=cat rtk git status； - 不该改写的场景：heredoc、
echo、cd、mkdir、python3、node -e，以及 rtk 未实现子命令的docker compose up -d、docker compose down（对比docker compose logs/ps/build会被改写）； - RTK_DISABLED 开关：
RTK_DISABLED=1 git status不被改写； - 重定向与
&边界：cargo test 2>&1、cargo test & git status等（&不会被误判为重定向）； - 幂等性：
rtk git status输入即原样输出； - 审计日志：设置
RTK_HOOK_AUDIT=1与RTK_AUDIT_DIR后，hook 会写hook-audit.log（4 字段管道分隔），action 取值如rewrite、skip:already_rtk、skip:heredoc、skip:no_match；未设置时不产生日志。
审计能力的配置说明见 docs/guide/getting-started/configuration.md（RTK_HOOK_AUDIT=1一行），实现见 src/hooks/hook_cmd.rs，配套的聚合分析命令入口在 src/main.rs（“Show hook rewrite audit metrics (requires RTK_HOOK_AUDIT=1)”）。
小结：一个“少即是多”的 Agent 指令设计
rtk-awareness.md体现了 rtk 在 Claude Code 集成上的核心权衡：用 hook 承担 99% 的透明改写工作（规则集中在 Rust 注册表 src/discover/registry.rs 中单点维护），只用一份十几行的意识文件教 Agent 三件事——四条元命令、安装自检、以及“其余的不用管”。对读者而言，实践路径是：先按 awareness 文件的验证序列确认装对了 rtk，再用rtk init完成RTK.md/hook 注入，最后用rtk gain、rtk discover与RTK_HOOK_AUDIT=1审计日志持续观察节省效果与 hook 覆盖率。
【免费下载链接】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
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
