企业官网建设流程全解析

Pilot Shell tool_token_saver深度解析：Bash输出透明压缩进上下文的机制

【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell

Pilot Shell 是一款面向 Claude Code 与 OpenAI Codex 的专业上下文工程（Context Engineering）工具。它的tool_token_saver钩子能在 AI 执行 Bash 命令的瞬间，透明地把命令重写为 RTK 代理版本，将工具输出压缩 60%–90%，让更少 Token 进入模型上下文——而用户和 AI 全程无感。

为什么上下文压缩对 AI 编程如此重要 🎯

AI 编程助手的每一次工具调用结果（git status、ls、cargo build……）都会被原样塞进对话上下文。一次普通的git status可能带回几十行冗余文本，一个大型目录的ls -la更是动辄数百行。这些"噪音 Token"会带来两个直接问题：

• 上下文窗口被快速挤占，触发频繁压缩（Compaction），打断工作流；
• Token 成本持续上涨，尤其是长会话和多 Agent 协作场景。

Pilot Shell 的思路是：不在事后清理输出，而是在命令执行前把它改写成"Token 友好"版本。这背后是一个名为 RTK（Token 优化型 CLI 代理）的 MIT 开源组件，其工具清单见 open-source-tools.md。

透明压缩机制：tool_token_saver 如何工作 🔍

核心实现只有 131 行 Python，位于 tool_token_saver.py，它作为PreToolUse钩子注册在 hooks.json 中（matcher 精确匹配Bash工具）：

command: "... run_if_licensed.py ... tool_token_saver.py" matcher: "Bash"

整个流程分 6 步，全程对用户透明：

1. 拦截：AI 即将执行一条 Bash 命令时，钩子从 stdin 读取 JSON 载荷，取出tool_input.command；
2. 平台识别：通过CLAUDE_PROJECT_PLATFORM环境变量（或 Codex 原生的turn_id、session_id证据）判断当前宿主是 Claude Code 还是 Codex；
3. 能力检查：确认系统装有rtk且版本 ≥ 0.23.0（低于版本静默跳过）；
4. 命令重写：调用rtk rewrite <原命令>（5 秒超时），例如git status→rtk git status。RTK 代理执行后返回的是精简过的输出；
5. 回填命令：钩子输出updatedInput，把改写后的命令替换原命令，AI 照常执行，拿到的却是压缩版结果；
6. 静默兜底：rtk 不存在、版本过旧、重写失败、或平台无法识别时，钩子直接输出空并退出——原始命令原样执行，绝不破坏用户的权限流程。

💡 一句话总结：命令被改写，输出被压缩，但 Agent 和用户都不需要知道这件事发生过。

权限契约：Claude 与 Codex 的差异化处理 ⚖️

这是该钩子设计上最精妙的部分——重写命令会改变"将要执行的内容"，因此必须尊重各宿主的权限模型：

源码注释（tool_token_saver.py）写得很直白：在 Claude 端加上allow会跳过用户原本的权限提示，所以刻意省略。这一"权限契约"在测试中被参数化验证（见下文）。

失败开放（Fail-Open）：任何异常都不打扰你 🛡️

上下文工程工具的第一原则是不能因为省 Token 而破坏开发流程。tool_token_saver在以下全部场景中静默返回、保持原命令不变：

• 系统未安装rtk（shutil.which返回 None）；
• rtk 版本低于 0.23.0；
• rtk rewrite超时或抛出系统错误；
• rtk 回显的命令与原命令相同（无压缩收益，直接放弃）；
• 平台标识缺失的"模糊宿主"——源码注释强调：模糊宿主必须保留原命令及其权限流程，而不是收到一个"猜测出来的"响应。

唯一需要留意的边界：rtk 的rewrite子命令以退出码 3 表示成功，钩子因此只信任 stdout 内容、不依赖退出码——这一反直觉的行为被专门写成了回归测试（test_tool_token_saver.py）。

如何验证压缩收益：rtk gain 📊

安装 Pilot Shell 后你几乎不需要做任何事——钩子自动接管。若想查看累计节省了多少 Token，直接运行：

rtk gain # 压缩收益分析 rtk gain --history # 按历史会话查看

相关规则说明在 cli-tools.md 中，还提醒了一个经典坑：如果rtk gain报错，多半是 PATH 里混入了另一个同名rtk（Rust Type Kit）。

相关源码与文档 📂

小结 🚀

tool_token_saver用不到 150 行代码解决了 AI 编程中最"安静"却最昂贵的问题：工具输出的上下文膨胀。它的三个设计亮点值得借鉴——

• 执行前拦截而非事后压缩，从源头削减进入上下文的 Token；
• 权限契约差异化，同一份重写逻辑在 Claude 与 Codex 上各自遵守宿主的审批语义；
• 全面失败开放，任何异常都退化为"什么都没发生"，绝不打断开发流。

对于跑长会话、多 Agent、大量终端操作的工程师来说，这套透明压缩机制是上下文工程里性价比最高的"隐形优化"之一。

【免费下载链接】pilot-shellProfessional context and harness engineering for Claude Code and OpenAI Codex. Build production-grade software with spec-driven development, TDD, persistent memory, quality gates, code intelligence, human oversight, and end-to-end verification.项目地址: https://gitcode.com/GitHub_Trending/cl/pilot-shell