RTK 与 Kilo Code 集成：用提示词级规则文件实现 CLI 命令的 Token 优化

本文围绕 RTK 仓库中 Kilo Code 的集成规则文件 hooks/kilocode/rules.md 展开。RTK（Rust Token Killer）是一个用 Rust 编写的单二进制 CLI 代理，在常见开发命令上可削减 60%–90% 的 LLM token 消耗。Kilo Code 属于 RTK 支持的提示词级（prompt-level）集成对象之一：RTK 向项目的 .kilocode/rules/ 目录写入一份规则文件，指导 Kilo Code 在执行 shell 命令时始终加上 rtk 前缀，从而让命令输出在进入 LLM 上下文之前先经过过滤与压缩。读完本文，你将理解该规则文件的全部指令内容、rtk init --agent kilocode 的安装机制与源码行为，以及 gain、discover、proxy 等元命令的用途。

一、Kilo Code 集成在 RTK 中的定位

RTK 对各 AI 编码助手的集成分为三个层级：完整的 hook 拦截（如 Claude Code 的 PreToolUse 钩子）、插件式原地改写（如 OpenCode、Pi 的 TypeScript 插件）、以及提示词级规则文件（Rules file）。Kilo Code 属于第三类——hooks/README.md 与支持文档 docs/guide/getting-started/supported-agents.md 均将其标注为 "Rules file (prompt-level)"，即没有可编程的 hook API 可拦截命令，而是依赖 Kilo Code 读取并遵循自定义指令。

这一点在 hooks/kilocode/README.md 中有明确说明：

• 仅提示词级指导（prompt-level guidance only），无可编程 hook；
• rules.md 包含"所有 shell 命令加 rtk 前缀"的指令、使用示例和元命令清单；
• 由 rtk init --agent kilocode 安装到 .kilocode/rules/rtk-rules.md（项目级作用域）。

从源码结构看，这个定位与实现完全一致：src/main.rs 中的 AgentTarget 枚举（约 L38–L62）列出了所有受支持的目标 agent，其中包含 Kilocode；而分发逻辑（约 L2094–L2098）在 agent == Some(AgentTarget::Kilocode) 时调用 hooks::init::run_kilocode_mode(ctx)，且如果同时带了 --global 会直接报错 "Kilo Code is project-scoped. Use: rtk init --agent kilocode"——因为 Kilo Code 只从项目根目录读取 .kilocode/rules/，不存在用户级全局规则路径。

二、规则文件内容全解（rules.md）

rules/kilocode/rules.md 是安装后 Kilo Code 实际读取的指令文本，其结构非常紧凑，分为四个部分。以下按原文脉络逐一说明。

1. Usage：一句话定位

文档开篇即声明用途：Token-optimized CLI proxy for shell commands（shell 命令的 token 优化代理）。这是写给 agent 看的自我描述，让模型知道 rtk 是什么、何时该用它。

2. Rule：核心规则

Always prefix shell commands with rtk to minimize token consumption. （始终为 shell 命令加上 rtk 前缀，以最小化 token 消耗。）

随后给出 7 个标准示例：

rtk git status
rtk cargo test
rtk ls src/
rtk grep "pattern" src/
rtk find "*.rs" .
rtk docker ps
rtk gh pr list

这 7 个示例覆盖了 RTK 最主要的几类过滤能力：VCS（git status）、Rust 测试（cargo test）、文件操作（ls、grep、find）、容器（docker ps）、GitHub CLI（gh pr list）。这些命令在 src/main.rs 的 Commands 枚举中都有对应的专门子命令——例如 Grep（约 L316–L347）会剥离空白、截断超长行并按文件分组，Find（约 L264–L269）以紧凑树形输出替代原生 find 的逐行路径输出。

需要说明的是：规则文件只列出了代表性示例。RTK 实际上暴露了几十个带过滤器的子命令（cargo、pytest、vitest、tsc、lint、mvn、phpunit、kubectl 等，见 src/main.rs 的完整 Commands 枚举），并且 git、cargo、gh 等命令对未显式实现的子命令也支持直通（passthrough）。因此规则文件要求的是"所有 shell 命令都加前缀"，而不是"只用这 7 条"。

3. Meta Commands：元命令

rtk gain              # Show token savings
rtk gain --history    # Command history with savings
rtk discover          # Find missed RTK opportunities
rtk proxy <cmd>       # Run raw (no filtering, for debugging)

这四条元命令对应源码中的真实实现：

• rtk gain：显示累计 token 节省量。实现位于 src/analytics/gain.rs，基于本地 tracking 数据库统计每日/每周/每月节省，并支持 --history（命令历史）、--graph、--quota（订阅额度节省估算）、--project（限定当前项目）、--failures（解析失败日志）、--reset 等选项（参数定义见 src/main.rs 约 L437–L478 的 Gain 子命令）。
• rtk gain --history：即 Gain 子命令中的 history: bool（-H），展示带节省数据的近期命令历史。
• rtk discover：扫描会话历史，找出"本可以走 RTK 但没有"的命令，量化错过的节省机会。对应 Discover 子命令（src/main.rs 约 L603–L620），支持 --project 过滤、--limit（每节最多条数，默认 15）、--since（限定最近 N 天，默认 30）、--format text|json。
• rtk proxy <cmd>：原样执行命令、不做任何过滤，专门用于调试对比。Proxy 子命令在 src/main.rs 约 L666–L671 定义为 "Execute command without filtering but track usage"，执行时还会记录原始命令与代理命令的使用量（约 L2728–L2732），以便统计口径完整。

这四条元命令均被列入 src/core/constants.rs 的 RTK_META_COMMANDS 常量（L10–L31），其中 gain、discover、proxy 都可见。该列表的作用之一是在参数解析测试中区分"元命令必须严格解析参数、不能落入原始执行"的校验逻辑。

4. Why：原理一句话

RTK filters and compresses command output before it reaches the LLM context, cutting up to 90% of the bash output on common operations. Always use rtk <cmd> instead of raw commands. （RTK 在命令输出到达 LLM 上下文之前对其进行过滤和压缩，在常见操作上可削减高达 90% 的 bash 输出。始终使用 rtk <cmd> 而非原始命令。）

这正是 RTK 的核心机制：先执行命令，再对 stdout 应用对应语言的过滤器（去样板行、去 ANSI 色码、错误/告警分组、超长输出截断、JSON 压缩等），把"人肉可读的冗长输出"变成"LLM 高效的紧凑摘要"。对测试类命令（如 cargo test、pytest、vitest），过滤器只保留失败用例；对 git 写操作（add、commit、push），成功时只回一行确认。

三、安装流程：rtk init --agent kilocode 的源码级解析

Kilo Code 集成的安装入口只有一条命令：

rtk init --agent kilocode

它会在当前项目根目录创建 .kilocode/rules/rtk-rules.md。该行为由 src/hooks/init.rs 中的 run_kilocode_mode 实现（约 L1730–L1776），关键逻辑如下：

1. 规则文本内嵌于二进制：const KILOCODE_RULES: &str = include_str!("../../hooks/kilocode/rules.md");——编译时直接把 hooks/kilocode/rules.md 嵌进二进制，因此安装不依赖仓库文件在场，更新规则需要更新 RTK 版本。
2. 目标路径：.kilocode/rules/rtk-rules.md，目录不存在时自动创建。
3. 幂等与合并：写入前先读现有文件，若已包含 "RTK" 或 "rtk" 字样则提示 "RTK already configured for Kilo Code in this project" 并不再重复写入；若已有其他自定义规则内容，则把 RTK 规则追加到现有内容之后（format!("{}\n\n{}", existing.trim(), KILOCODE_RULES)），不会覆盖用户已有的规则。
4. dry-run 支持：rtk init --agent kilocode --dry-run 只打印将写入的文件，不落盘（InitContext 携带 dry_run 标志）。
5. 测试保障：同一文件中已有测试 test_kilocode_mode_creates_rules_file 验证文件被正确创建且包含 RTK 内容，test_kilocode_mode_is_idempotent 验证重复执行内容不变（约 L5386–L5408）。

安装完成后，Kilo Code 在该项目中的每次 shell 调用都会参考这份规则。由于是提示词级集成，是否每次都正确加前缀取决于模型对指令的遵循度——这也是它与 Claude Code 等"完整 hook"集成的本质区别：后者在命令发出前由 hook 程序强制改写，规则文件集成则是"指导而非保证"。如果需要确认 agent 侧整体状态，可用 rtk init --show 查看当前配置。

卸载与回滚

从 init.rs 的整体结构和 Commands::Init 的 --uninstall 参数（src/main.rs 约 L402–L404）可以看出，rtk init --uninstall --agent kilocode 用于移除 RTK 写入的规则产物。由于 RTK 在追加模式下会把规则接在用户原有内容之后，手工回滚时也可对照 .kilocode/rules/rtk-rules.md 的内容删除 RTK 段落。

四、规则集成后的使用闭环

在 Kilo Code 会话中使用 RTK 时，建议遵循以下工作流（均可由规则文件内容直接推出）：

1. 所有命令加前缀：让 Kilo Code 直接执行 rtk <cmd>。这是规则文件 Rule 一节的硬性要求。
2. 定期核算节省量：rtk gain 查看累计节省；rtk gain --history 查看逐条命令的节省明细；rtk discover 找出漏掉 RTK 的命令并评估优化空间。
3. 调试用 proxy：当怀疑过滤导致信息丢失时，用 rtk proxy <cmd> 跑一次无过滤的原始输出，与过滤结果对比。
4. 组合命令：RTK 的改写注册表对 &&、||、; 连接的命令两侧独立处理（例如 cargo fmt --all && cargo test 会整体成为 rtk cargo fmt --all && rtk cargo test），因此规则中"所有命令加前缀"的要求在链式命令下依然成立（参见 hooks/README.md 的 Compound Command Handling 一节）。

五、适用前提与边界说明

• 作用域：Kilo Code 集成是项目级的，规则写入项目内 .kilocode/rules/，不写入用户主目录；带 --global 会直接报错。
• 集成层级：提示词级，无运行时拦截；命令是否被改写依赖 agent 遵循规则，属于"guidance only"，而非 Claude Code 式的透明改写。
• 二进制要求：规则文件本身只是文本，但 rtk 可执行文件必须已安装并在 PATH 中，否则 agent 执行 rtk <cmd> 会失败；RTK 对无专用过滤器的命令会直通原样输出，因此加前缀在功能上是安全的（这也是 src/hooks/init.rs 中内嵌指令 "Golden Rule" 一节强调 "RTK is always safe to use" 的原因）。
• 收益口径：规则文件宣称"最高削减 90% bash 输出"，该数字对应 RTK 对测试、构建等高频命令的过滤效果；具体节省量以 rtk gain 的本地统计为准。

六、小结

hooks/kilocode/rules.md 虽然篇幅不长，但它完整定义了 RTK 与 Kilo Code 的契约：一条"永远加 rtk 前缀"的规则、七个代表性命令示例、四条元命令（gain、gain --history、discover、proxy）和一条原理说明。配合 src/hooks/init.rs 的幂等安装逻辑与 src/main.rs 中几十个过滤子命令的实现，这套提示词级集成让 Kilo Code 用户在不改变工作流的前提下，把 shell 输出压缩 60%–90% 后再送入 LLM 上下文。对于需要审计自身节省效果的用户，rtk gain 与 rtk discover 提供了可直接运行的度量闭环。