rtk-awareness 解析：rtk 如何让 Claude Code 自动经 rtk 代理命令以压缩 Token 消耗

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/rtkhooks/claude/rtk-awareness.md是 rtkRust 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 binaryHook-Based Usagehook 接管——明确告知 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.rshook 文件名为rtk-rewrite.sh当前安装形态的 hook 命令是rtk hook claude使用 tempfile rename 的atomic_write保证写入不损坏已有文件且写入是幂等的内容相同则跳过。值得注意的是同一个RTK_SLIM内容还被复用于其他 Agent 的指令文件Gemini 的GEMINI.mdinit.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.rshistory标志开启后在 gain.rs 处输出历史明细。节省数据的来源是 SQLite 跟踪库CLAUDE.md 说明“Token savings are tracked in SQLite viasrc/core/tracking.rs”且 RTK 不内置 tokenizertoken 数按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: Ifrtk gainfails, you may have reachingforthejack/rtk (Rust Type Kit) installed instead.CLAUDE.md 对此有完整阐述生态里存在两个名为 rtk 的项目——本项目 Rust Token Killer 与 reachingforthejack/rtkRust 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 hookrtk-rewrite.shrtk-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: allow1无 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_verdictrewrite_cmd.rs按顺序做三件事权限裁决读取 Claude Code 的 settings 规则allow/ask/deny。Deny直接返回退出码 2不可证明结构检查crate::discover::lexer::contains_unattestable_construct(cmd)检测到反引号、$()命令替换、文件重定向等无法静态证明等价性的结构时一律透传不冒险改写注意 fd 复制21不算在内仍可改写——这与测试中cargo test 21→rtk cargo test 21的行为一致注册表改写registry::rewrite_command(cmd, excluded, transparent_prefixes)src/discover/registry.rs查找改写规则支持exclude_commands排除清单与transparent_prefixes两个用户配置项。一个安全关键点值得注意PermissionVerdict::Default无任何规则命中必须映射到退出码 3ask而非 0allow否则任何没有显式 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_PAGERcat git status→GIT_PAGERcat 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_DISABLED1 git status不被改写重定向与边界cargo test 21、cargo test git status等不会被误判为重定向幂等性rtk git status输入即原样输出审计日志设置RTK_HOOK_AUDIT1与RTK_AUDIT_DIR后hook 会写hook-audit.log4 字段管道分隔action 取值如rewrite、skip:already_rtk、skip:heredoc、skip:no_match未设置时不产生日志。审计能力的配置说明见 docs/guide/getting-started/configuration.mdRTK_HOOK_AUDIT1一行实现见 src/hooks/hook_cmd.rs配套的聚合分析命令入口在 src/main.rs“Show hook rewrite audit metrics (requires RTK_HOOK_AUDIT1)”。小结一个“少即是多”的 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_AUDIT1审计日志持续观察节省效果与 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），仅供参考