企业官网建设流程全解析

RTK Pi 扩展实战：通过 Pi 的 tool_call 事件透明重写命令，压缩 90% 的 LLM 上下文

【免费下载链接】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 仓库的 hooks/pi/README.md 与扩展源码 hooks/pi/rtk.ts 展开，讲解 RTK 的 Pi（pi-coding-agent）集成如何作为一个"仅重写"（rewrite-only）的 token 优化器工作：它订阅 Pi 的tool_call事件，把 bash 命令原地改写为rtk前缀等价命令，从而在不改变 Agent 工作流的前提下削减进入 LLM 上下文的 bash 输出。读完本文，你将掌握 Pi 扩展的安装/卸载方式、加载期版本守卫、rtk rewrite退出码协议，以及如何在不安装的情况下直接验证重写是否生效。

设计意图：只做重写，不做权限控制

RTK 的 Pi 扩展被明确定位为一个rewrite-only token optimizer：它只变更（mutate）bash 命令为其rtk前缀等价形式，目标是削减最多 90% 到达上下文的 bash 输出。

权限门控被刻意排除在范围之外。RTK 不拦截、不确认、不审计命令——这类职责应交给专门的权限扩展（例如对rm -rf、sudo做门控的扩展）。README 强调，这种分离让 RTK 的 hook 保持"快、可预测、可与其他 Pi 扩展组合"。

这与仓库整体的 hook 架构一脉相承：在 hooks/README.md 中，所有 Agent 集成被定义为thin delegates（薄委托）——解析 Agent 特定的 JSON、以子进程方式调用rtk rewrite、按 Agent 特定格式回传，重写模式注册表（70+ 条规则）的唯一事实来源是 Rust 侧的 src/discover/registry.rs。Pi 集成在该文档的 Agent 对照表中对应的机制正是：TypeScript 扩展、tool_call事件、原地修改（in-place mutation）、可以修改命令。

安装与卸载：两种作用域，幂等可重复

安装命令

Pi 扩展不是 shell hook，而是一个由rtk init安装的 TypeScript 扩展文件：

# 项目本地安装（默认），生成 .pi/extensions/rtk.ts rtk init --agent pi # 全局安装，生成 ~/.pi/agent/extensions/rtk.ts rtk init --agent pi --global

Pi 在启动时会自动发现这两个路径下的扩展，无需额外配置。这一点在 docs/guide/getting-started/supported-agents.md 的 Pi 小节中也有印证：rtk init --agent pi创建.pi/extensions/rtk.ts（本地）或~/.pi/agent/extensions/rtk.ts（全局），"Pi auto-discovers extensions from both paths on startup"。

从源码结构看，安装逻辑位于 src/hooks/init.rs：

• 扩展内容通过include_str!("../../hooks/pi/rtk.ts")直接嵌入 Rust 二进制（PI_PLUGIN常量），因此无需依赖源码仓库，任何装有 rtk 的机器都能生成与当前版本一致的扩展文件；
• run_pi_mode(global, ctx)按作用域计算目标路径：本地为.pi/extensions/rtk.ts（常量PI_LOCAL_DIR/PI_EXTENSIONS_SUBDIR/PI_PLUGIN_FILE，见 src/hooks/constants.rs），全局则先解析 Pi 配置目录；
• 全局路径解析resolve_pi_dir()尊重PI_CODING_AGENT_DIR环境变量覆盖，未设置时回落到~/.pi/agent；
• ensure_pi_plugin_installed()内部是write_if_changed——文件缺失或过期才写入，因此重复执行rtk init是安全的，已是最新时输出 "already up to date"；
• 安装完成后会提示验证命令：pi -e <扩展路径> --no-session。

卸载命令

# 移除项目本地安装（在项目根目录执行） rtk init --uninstall --agent pi # → 删除 .pi/extensions/rtk.ts # 移除全局安装 rtk init --uninstall --agent pi --global # → 删除 ~/.pi/agent/extensions/rtk.ts

卸载是幂等的——未安装时再次执行只会输出 "RTK Pi extension was not installed (nothing to remove)"，是 no-op。且安装/卸载只管理扩展文件本身，不触碰其他任何文件；对应实现在 src/hooks/init.rs 的uninstall_pi()：仅在文件存在时删除，并提示重启 pi 生效。

扩展源码解析：hooks/pi/rtk.ts 的完整工作流

扩展本体只有约 90 行，是一个"薄委托"的典型形态。以下按加载顺序拆解 hooks/pi/rtk.ts。

1. 类型导入的性能考量

import type { BashToolCallEvent, ExtensionAPI, ToolCallEvent, } from "@earendil-works/pi-coding-agent"

源码注释解释了一个容易忽略的细节：Pi 包提供的isToolCallEventType是值导出，import 它会在扩展加载时拉起整个 barrel，实测约 250ms；而import type在编译期被擦除，开销约为 10ms。因此扩展本地重新实现了类型守卫：

function isBashToolCallEvent(event: ToolCallEvent): event is BashToolCallEvent { return event.toolName === "bash" }

这正是 README "Specifics" 一节所述的"避免在扩展加载时引入包的 barrel 导出"，也是 README 强调 Pi 集成"not a shell hook, nozxdependency"的原因——相比 hooks/opencode/rtk.ts 使用zx执行子进程，Pi 扩展用 Pi 原生的pi.exec完成同样的事。

2. 加载期版本守卫

扩展加载时先探测rtk是否可用且版本足够新：

const REWRITE_TIMEOUT_MS = 2_000 const MIN_SUPPORTED_RTK_MINOR = 23 const ver = await pi.exec("rtk", ["--version"], { timeout: REWRITE_TIMEOUT_MS }) if (ver.code !== 0) { console.warn("[rtk] rtk binary not found in PATH — extension disabled") return } const parsed = parseSemver(ver.stdout.replace(/^rtk\s+/, "")) if (parsed) { const [major, minor] = parsed if (major === 0 && minor < MIN_SUPPORTED_RTK_MINOR) { console.warn(`[rtk] rtk ${ver.stdout.trim()} is too old (need >= 0.23.0) — extension disabled`) return } }

要点：

• rtk rewrite子命令在 0.23.0 引入，因此守卫检查rtk >= 0.23.0（parseSemver从"X.Y.Z"解析出 major/minor/patch）；
• binary 缺失或版本过旧时，扩展打印警告并直接return——即"注册 no-op"，Pi 照常启动，所有命令原样通过；
• 当前仓库版本（见 Cargo.toml 中version = "0.42.4"）远高于该下限，正常安装即可满足守卫。

3. tool_call 事件处理：过滤顺序与原地改写

pi.on("tool_call", async (event, ctx) => { try { if (!isBashToolCallEvent(event)) return const cmd = event.input.command if (typeof cmd !== "string" || cmd.trim() === "") return if (cmd.startsWith("rtk ")) return if (process.env.RTK_DISABLED === "1") return const rewritten = await rewriteCommand(pi, cmd, ctx.signal) if (rewritten && rewritten !== cmd) { event.input.command = rewritten } } catch (err) { console.warn("[rtk] unexpected error in tool_call handler; passing through command", err) return } })

过滤链条按序执行，任何一步不满足都静默放行：

4. 子进程调用与退出码协议

async function rewriteCommand(pi: ExtensionAPI, cmd: string, signal?: AbortSignal) { const result = await pi.exec("rtk", ["rewrite", cmd], { timeout: REWRITE_TIMEOUT_MS, signal, }) if (result.killed) return null if (result.code !== 0 && result.code !== 3) return null return result.stdout.trim() || null }

文件头注释写明了rtk rewrite的退出码契约：

README 的 "Design Notes" 特别指出：退出码 0 和 3 都表示"重写并放行"，在 Pi 扩展中被同等处理。这与 Rust 侧 src/hooks/rewrite_cmd.rs 的完整协议对应——在 Claude Code 场景下退出码 3 表示"匹配到 ask 规则，重写后交由宿主工具询问用户"，而 Pi 没有该权限面，故只需取 stdout 即可。

重写决策的唯一事实来源：rtk rewrite 内部发生了什么

Pi 扩展本身不含任何模式匹配逻辑——README 的 Design Notes 第一条即声明 "All filtering logic lives inrtk rewrite(the Rust registry), not in this file"。rtk rewrite的决策流程在 src/hooks/rewrite_cmd.rs 中可以看到：

1. 加载~/.config/rtk/config.toml中的hooks.exclude_commands与transparent_prefixes（用户可声明永不重写的命令）；
2. 权限裁决为 Deny → 直接退出码 2，不重写；
3. 命令含不可证明结构（如反引号/$()替换、重定向等，由 src/discover/lexer.rs 检测）→ 一律 Passthrough（退出码 1），保证只在语义可静态证明的场合改写；
4. 调用registry::rewrite_command匹配模式：命中则按权限裁决返回 Allow（退出码 0）或 Ask（退出码 3），未命中则退出码 1。

这意味着要新增或修改重写规则，应编辑 Rust 注册表，而不是这个 TypeScript 文件（扩展文件头注释也如此要求）。注册表覆盖 Test Runners、Build Tools、VCS、Linters、包管理器等 70+ 命令族，并能处理&&、||、;、|等复合命令——例如cargo fmt --all && cargo test会被改写为rtk cargo fmt --all && rtk cargo test（两侧独立重写，管道中间阶段保持原始形态，详见 hooks/README.md 的 Compound Command Handling 一节）。

验证方式：无需安装即可测试

README 的 Testing 一节给出了完整的验证清单：

# 直接加载扩展，无需安装 pi -e ./hooks/pi/rtk.ts # 验证重写生效 —— 让 Agent 跑一条命令，然后查历史 rtk gain --history # 应能看到 rtk 前缀命令及其节省百分比 # 测试 RTK_DISABLED 放行 RTK_DISABLED=1 pi -e ./hooks/pi/rtk.ts # → 命令原样通过；rtk gain --history 中无重写记录 # 测试版本守卫 —— 临时用一个打印 "rtk 0.22.0" 的 stub 遮蔽 rtk # → 扩展在启动时打印警告并注册 no-op；pi 正常启动

rtk gain --history属于 RTK 的分析模块（src/analytics/），它会记录哪些命令被 rtk 前缀执行过并统计节省量——这是验证 Pi 扩展"重写确实发生在工具调用层"的最直接手段。此外，pi -e <路径> --no-session也是rtk init --agent pi安装完成后主动打印的验证命令（见 src/hooks/init.rs 的print_pi_result）。

边界总结：非阻塞是这条链路的硬性契约

贯穿整个 Pi 集成的核心不变式是RTK 永不阻塞执行：

• 扩展层：所有错误路径（binary 缺失、超时被 kill、非 0/3 退出码、异常）都返回null/静默放行，pi.exec有 2 秒超时并透传ctx.signal以便 Pi 取消时及时中断；
• 协议层：hooks/README.md 的 Exit Code Contract 要求所有 hook 在一切错误路径上都不阻止命令执行——"A hook that exits non-zero prevents the user's command from executing"；
• 版本层：加载期守卫保证旧版 rtk 不会导致扩展异常，只会降级为 no-op。

Pi 扩展由此实现了 RTK 在 hooks/README.md 中定义的"Plugin 层级"集成：维护成本中等（Agent 负责加载）、通过tool_call事件做原地修改、可以修改命令，同时把所有过滤逻辑收敛到 Rust 单二进制中，与其余 9 个 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