RTK 接入 Kilo Code：Rules 文件提示级集成与 `rtk init --agent kilocode` 安装机制详解

本文围绕 RTK（Rust Token Killer）仓库中 hooks/kilocode/ 目录下的集成文档展开，讲清 Kilo Code 为什么采用“纯提示级”（prompt-level）而非程序化 Hook 的集成方式、rules.md 指令文件的完整内容与生效原理，以及 rtk init --agent kilocode 安装命令背后的 Rust 源码实现——包括幂等性检查、追加合并、dry-run 等细节。读完后你能掌握如何在 Kilo Code 工作区中完成 RTK 接入、验证规则文件是否生效，并从源码层面理解这套“零拦截”集成的设计取舍。

一、定位：Kilo Code 属于 Rules 文件集成档位

在 RTK 的 Agent 集成体系中，hooks/README.md 把各 Agent 集成划分为三个档位（Integration Tiers）：

档位	机制	维护成本	代表集成
Full hook	Shell 脚本或 Rust 二进制，通过 Agent 的 Hook API 拦截命令	高——需跟踪 Agent API 变更	Claude Code、Cursor、Copilot、Gemini
Plugin	TypeScript/JS/Python 插件，运行于 Agent 插件系统	中——由 Agent 管理加载	OpenCode、Hermes、Pi
Rules file	Agent 读取的提示级指令	低——没有会坏掉的代码	Cline、Windsurf、Codex

Kilo Code 归属于第三档 Rules file 集成。hooks/kilocode/README.md 的核心结论只有三条：

1. Prompt-level guidance only（纯提示级引导，无程序化 Hook）——依赖 Kilo Code 读取自定义指令（custom instructions）的能力，RTK 不拦截、不重写命令，而是“劝说”模型主动使用 rtk 前缀；
2. rules.md 承载全部指令内容——包括“所有 shell 命令加 rtk 前缀”的规则、使用示例和元命令（meta commands）；
3. 由 rtk init --agent kilocode 安装到 .kilocode/rules/rtk-rules.md（项目级，project-local）。

与 Full hook 集成 形成对比：Full hook（如 Claude Code、Cursor、Gemini）是“命令在 Agent 看到之前就被重写”，重写是保证发生的；而 Rules file 集成（Cline、Windsurf、Codex、Kilo Code、Antigravity）依赖模型遵循指令，是引导而非强制。这一取舍的前提是 Kilo Code 将 .kilocode/rules/ 目录下的文件作为项目级自定义指令读取——这与 docs/guide/getting-started/supported-agents.md 中的说明一致：“Kilo Code reads .kilocode/rules/ as custom instructions”。

二、rules.md 指令文件：内容、示例与元命令

RTK 实际写入 Kilo Code 的指令内容就是仓库中的 hooks/kilocode/rules.md，其结构如下：

1. 核心规则（Rule）

Always prefix shell commands with `rtk` to minimize token consumption.

2. 使用示例（Examples）

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

覆盖 VCS、构建/测试、文件操作、容器、GitHub CLI 等高频开发命令，为模型提供了可直接照抄的模式，降低其“忘记加前缀”的概率。

3. 元命令（Meta Commands）

rtk gain              # 显示 token 节省量
rtk gain --history    # 带节省量的命令历史
rtk discover          # 找出被漏掉的 RTK 优化机会
rtk proxy <cmd>       # 原样运行（不过滤，用于调试）

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.

这段“Why”很重要：提示级集成的说服效果很大程度上依赖模型理解“为什么”。rtk discover 与 rtk gain 命令由 src/analytics/ 模块实现（如 gain.rs），rtk proxy 提供“不过滤的原始执行”作为排障手段。

三、安装机制：rtk init --agent kilocode 的源码实现

3.1 命令入口与项目级作用域限制

命令分发位于 src/main.rs：

} else if agent == Some(AgentTarget::Kilocode) {
    if global {
        anyhow::bail!("Kilo Code is project-scoped. Use: rtk init --agent kilocode");
    }
    hooks::init::run_kilocode_mode(ctx)?;
}

可以确认两个事实：

• Kilo Code 集成仅支持项目级安装。由于规则文件放在项目根目录的 .kilocode/rules/ 下（workspace-scoped），如果误加 --global，程序会直接报错中止并提示正确用法；
• 入口函数是 hooks::init::run_kilocode_mode，实现位于 src/hooks/init.rs。

3.2 规则内容的内嵌与写入逻辑

安装函数在编译期就把指令文件打进二进制（init.rs#L1730）：

const KILOCODE_RULES: &str = include_str!("../../hooks/kilocode/rules.md");

即仓库中 hooks/kilocode/rules.md 是单一事实来源，用户机器上的 .kilocode/rules/rtk-rules.md 是它的副本。写入逻辑（run_kilocode_mode_at）的关键行为：

场景	行为	源码依据
目标文件已存在且内容含 RTK/rtk	视为已配置，输出 “(already present)”，不重写	幂等保护：existing.contains("RTK") || existing.contains("rtk")
目标文件存在但为空/无 RTK 标记，且已有其他内容	将 RTK 规则追加在原有内容之后（existing + "\n\n" + KILOCODE_RULES）	不覆盖用户在 .kilocode/rules/rtk-rules.md 中已有的其他指令
目标文件不存在或为空	直接写入 KILOCODE_RULES	fs::write(&rules_path, &new_content)
目录不存在	自动创建 .kilocode/rules/ 父目录	fs::create_dir_all(&target_dir)
--dry-run	只打印 “would write …” 及（-v 时）完整内容，不落盘	dry-run 分支 + print_dry_run_footer()
--verbose	写盘后向 stderr 打印 “Wrote .kilocode/rules/rtk-rules.md”	verbose > 0 分支

安装成功后的终端输出为：

RTK configured for Kilo Code.

  Rules: .kilocode/rules/rtk-rules.md (installed)
  Kilo Code will now use rtk commands for token savings.
  Test with: git status

最后提示用 git status 验证——在 Kilo Code 会话里让它执行 git 状态查询，观察其是否生成 rtk git status。

3.3 测试用例印证

src/hooks/init.rs 内有两个针对 Kilo Code 模式的单元测试：

• test_kilocode_mode_creates_rules_file：在临时目录执行安装，断言 .kilocode/rules/rtk-rules.md 被创建且内容包含 “RTK”；
• test_kilocode_mode_is_idempotent：连续执行两次安装，断言第二次不会改变文件内容（“Idempotent: content should not change”）。

这两个测试与 3.2 节描述的幂等/合并逻辑一一对应，可作为实现事实的直接佐证。

四、为什么 Kilo Code 没有程序化 Hook？

从 hooks/README.md 的全局设计看，RTK 的所有 Hook 脚本（Claude/Cursor 的 shell hook、Copilot/Vibe 的 Rust 二进制等）都是“薄委托”：解析 Agent 特定 JSON、调用 rtk rewrite 子进程、再按 Agent 格式返回响应，重写逻辑统一收口在 src/discover/registry.rs 的 70+ 条重写模式上。而 Kilo Code 的集成完全没有这一层，原因可以归纳为：

1. 机制匹配：Kilo Code 暴露的扩展面是 .kilocode/rules/ 自定义指令目录。RTK 选择最低维护成本的方式——写一个 Markdown 文件，没有脚本、没有二进制、没有 Agent API 依赖，因此不会因 Kilo Code 升级而“坏掉”；
2. 代价是“尽力而为”：Full hook 是透明重写，Agent 永远看不到裸命令；Rules file 集成则依赖模型遵循指令，个别情况下模型仍可能直接执行裸命令。RTK 为此提供了 rtk discover 元命令——它会扫描会话中未被 RTK 覆盖的命令，帮助使用者发现漏网之鱼；
3. 与 Cline/Windsurf/Codex 同档：supported-agents.md 的汇总表将 Kilo Code 列为 “Rules file (prompt-level)”、“Can Modify Command? = N/A”，并明确“Rules file integrations rely on the model following instructions”，与源码行为一致。

换言之，Kilo Code 集成不是功能缺失，而是 RTK 集成档位模型中有意选择的低成本方案：牺牲确定性换零维护成本。

五、实操指南：在 Kilo Code 项目中使用 RTK

5.1 前提

• 已安装 RTK 二进制（rtk 在 PATH 中可用）；
• 当前目录是希望接入的项目根目录（规则文件是 workspace-scoped，每个项目需单独安装一次）。

5.2 安装步骤

# 1. 在项目根目录执行
rtk init --agent kilocode

# 可选：先预览将要写入的内容
rtk init --agent kilocode --dry-run

# 2. 验证文件生成
cat .kilocode/rules/rtk-rules.md   # 应看到 "Always prefix shell commands with `rtk`"

注意：不要加 --global，命令会报 Kilo Code is project-scoped 并中止（见 3.1 节源码）。

5.3 生效验证

在 Kilo Code 中发起一次包含 shell 操作的对话，例如“查看 git 状态并列出 src 下的 Rust 文件”，预期模型生成的命令形如 rtk git status、rtk find "*.rs" .。随后用元命令确认节省效果：

rtk gain --history    # 查看每条命令的 token 节省
rtk discover         # 检查是否还有可被 RTK 压缩但未压缩的命令

若怀疑某命令的过滤结果异常，可用 rtk proxy <cmd> 执行未过滤的原始版本进行对照调试（rules.md 中 Meta Commands 一节）。

5.4 多项目与共享

由于规则文件写在项目目录内，团队可以把它随仓库提交，让所有成员（以及他们的 Kilo Code 实例）自动获得一致的 RTK 使用指引。重复执行 rtk init --agent kilocode 是安全的 no-op（幂等，见 3.3 节测试）；若你在该文件中手动追加了其他指令，安装器检测到已有 rtk 标记后会跳过重写，不会覆盖你的自定义内容。

六、小结

Kilo Code 集成体现了 RTK 多档位集成策略中“Rules file”档位的完整实现：

• 机制：hooks/kilocode/rules.md 单一事实来源 → include_str! 编译期内嵌 → rtk init --agent kilocode 写入项目级 .kilocode/rules/rtk-rules.md（src/hooks/init.rs）；
• 约束：仅项目级作用域，--global 被显式拒绝（src/main.rs）；
• 健壮性：幂等、dry-run、已有内容追加合并，均有单元测试覆盖（src/hooks/init.rs）；
• 定位：提示级引导，依赖模型遵循指令，配合 rtk gain / rtk discover / rtk proxy 元命令形成“引导—度量—排障”闭环，与 Full hook 集成互补。

对于 Kilo Code 用户，这一集成的接入成本几乎为零（一个 Markdown 文件），且不会因 Agent 升级引入兼容性问题；需要更强保证的重写场景，则可以参照 RTK 对 Claude Code、Cursor 等 Agent 的 Full hook 集成方案。