rtk-ai/rtk 实现原理

**核心结论：**rtk 不是模型级压缩器，而是面向 AI Coding Agent 的 **CLI 命令代理 + 输出过滤器 + Hook 改写系统**。它把常见命令自动改写为 `rtk xxx`，代理执行真实命令，再用规则化解析、分组、截断、去重等方式把输出压缩后返回给 LLM。

一、整体链路

典型流程是：Agent 准备执行 git status，hook 先把命令改写成 rtk git status；rtk 再运行真正的 git status，捕获输出并返回更短的摘要。

二、核心机制

机制	实现方式	效果
命令改写	通过 Claude Code、Cursor、Gemini CLI、OpenCode 等 Agent 的 hook/plugin，把常见 shell 命令改写为 `rtk xxx`	用户和 Agent 不需要手动改命令
代理执行	Rust 内部使用 `std::process::Command` 调用真实工具，如 git、cargo、pytest、tsc	保持原工具语义和 exit code
专用过滤器	对 git、JS/TS、Rust、Python、Go、Docker、AWS 等命令实现规则化解析	比通用摘要更稳定、更快
降级 passthrough	不认识的命令或解析失败时原样执行，或者走 TOML DSL 过滤器	避免破坏用户工作流
失败恢复	命令失败时把完整原始输出保存到本地 tee 文件	压缩输出不够时可回读完整日志
节省统计	用 `ceil(chars / 4)` 估算 token，并写入本地 SQLite	`rtk gain` 可展示节省情况

三、过滤策略

**Smart Filtering：**移除注释、空行、样板文本、进度条、ANSI 控制字符。
**Grouping：**把同类错误按文件、规则、错误码、目录聚合。
**Truncation：**保留关键上下文，截断长 diff、长日志、长 JSON。
**Deduplication：**重复日志折叠成一行并附带出现次数。
**Failure Focus：**测试命令只展示失败用例和关键错误，隐藏通过项。
**Structure Only：**JSON 等结构化数据只展示 key、层级和类型，剥离大 value。

四、典型命令示例

原始命令	改写后	压缩重点
`git status`	`rtk git status`	使用 porcelain 格式，只保留分支、变更、冲突状态
`git diff`	`rtk git diff`	先输出 stat，再按文件展示紧凑 diff
`cargo test`	`rtk cargo test`	隐藏通过项，保留失败测试和错误信息
`pytest`	`rtk pytest`	状态机解析测试生命周期，聚焦失败
`tsc`	`rtk tsc`	按文件和错误码聚合 TypeScript 错误
`docker logs`	`rtk docker logs`	日志去重、截断、保留异常行

五、源码结构

text

src/main.rs              CLI 入口、clap 解析、命令路由
src/cmds/                各类命令专用过滤器
src/cmds/git/            git status / diff / log / add / commit / push
src/cmds/js/             eslint / tsc / vitest / playwright / pnpm
src/cmds/rust/           cargo / test runner
src/cmds/python/         pytest / ruff / pip / mypy
src/core/filter.rs       源码过滤逻辑
src/core/tracking.rs     token 节省统计
src/core/toml_filter.rs  TOML 声明式过滤器
src/hooks/               hook 安装、校验、改写逻辑
src/discover/registry.rs 命令识别和 rewrite 规则

六、实现特点与局限

### 优点 - 速度快：单 Rust binary，目标开销约 5-15ms。 - 可解释：规则化过滤，不依赖模型推理。 - 低风险：保留 exit code，不认识的命令会 passthrough。 - 面向 Agent：通过 hook 自动接入 AI Coding 工具。 ### 局限 - 依赖规则质量，未知命令压缩效果有限。 - 不是语义级摘要，无法真正理解业务上下文。 - 过度过滤可能遗漏边缘信息，所以需要 tee 文件兜底。 - Claude Code 的 Read、Grep、Glob 等内置工具不会经过 Bash hook。

七、本质定位

rtk 的本质是 shell command proxy + rule-based parser + output compressor + agent hook integration。它通过减少 CLI 噪声来降低 LLM 上下文消耗，而不是直接压缩模型 token 或改造 LLM。