diff --git a/README.md b/README.md index 9141e2a..462a156 100644 --- a/README.md +++ b/README.md @@ -1,24 +1,30 @@ + +> [!NOTE] +> 本文档由 WeHub 基于上游 README 翻译整理，属于社区翻译，非官方中文文档。 +> [English](./README.en.md) · [原始项目](https://github.com/rtk-ai/rtk) · [上游 README](https://github.com/rtk-ai/rtk/blob/HEAD/README.md) +> 原作者、版权与许可证归属以原始项目及本仓库 LICENSE 文件为准。 +

RTK - Rust Token Killer

- High-performance CLI proxy that reduces LLM token consumption by 60-90% + 高性能 CLI 代理，将 LLM token 消耗降低 60-90%

CI Release License: Apache 2.0 - Discord + Discord Homebrew

- Website • - Install • - Troubleshooting • - Architecture • + 官网 • + 安装 • + 故障排除 • + 架构 • Discord

@@ -28,482 +34,145 @@ 中文 • 日本語 • 한국어 • - Espanol • - Português + Espanol

--- -rtk filters and compresses command outputs before they reach your LLM context. Single Rust binary, 100+ supported commands, <10ms overhead. +rtk 在命令输出到达 LLM 上下文之前进行过滤和压缩。单一 Rust 二进制文件，零依赖，<10ms 开销。 -## Token Savings (30-min Claude Code Session) +## Token 节省（30 分钟 Claude Code 会话） -| Operation | Frequency | Standard | rtk | Savings | -|-----------|-----------|----------|-----|---------| +| 操作 | 频率 | 标准 | rtk | 节省 | +|------|------|------|-----|------| | `ls` / `tree` | 10x | 2,000 | 400 | -80% | | `cat` / `read` | 20x | 40,000 | 12,000 | -70% | | `grep` / `rg` | 8x | 16,000 | 3,200 | -80% | | `git status` | 10x | 3,000 | 600 | -80% | | `git diff` | 5x | 10,000 | 2,500 | -75% | -| `git log` | 5x | 2,500 | 500 | -80% | -| `git add/commit/push` | 8x | 1,600 | 120 | -92% | | `cargo test` / `npm test` | 5x | 25,000 | 2,500 | -90% | -| `ruff check` | 3x | 3,000 | 600 | -80% | -| `pytest` | 4x | 8,000 | 800 | -90% | -| `go test` | 3x | 6,000 | 600 | -90% | -| `docker ps` | 3x | 900 | 180 | -80% | -| **Total** | | **~118,000** | **~23,900** | **-80%** | +| **总计** | | **~118,000** | **~23,900** | **-80%** | -> Estimates based on medium-sized TypeScript/Rust projects. Actual savings vary by project size. +## 安装 -## Installation - -### Homebrew (recommended) +### Homebrew（推荐） ```bash brew install rtk ``` -### Quick Install (Linux/macOS) +### 快速安装（Linux/macOS） ```bash curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh ``` -> Installs to `~/.local/bin`. Add to PATH if needed: -> ```bash -> echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc # or ~/.zshrc -> ``` - ### Cargo ```bash cargo install --git https://github.com/rtk-ai/rtk ``` -### Pre-built Binaries - -Download from [releases](https://github.com/rtk-ai/rtk/releases): -- macOS: `rtk-x86_64-apple-darwin.tar.gz` / `rtk-aarch64-apple-darwin.tar.gz` -- Linux: `rtk-x86_64-unknown-linux-musl.tar.gz` / `rtk-aarch64-unknown-linux-gnu.tar.gz` -- Windows: `rtk-x86_64-pc-windows-msvc.zip` - -> **Windows users**: Extract the zip and place `rtk.exe` somewhere in your PATH (e.g. `C:\Users\\.local\bin`). Run RTK from **Command Prompt**, **PowerShell**, or **Windows Terminal** — do not double-click the `.exe` (it will flash and close). The full hook system works natively on Windows (and in [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)). See [Windows setup](#windows) below for details. - -### Verify Installation +### 验证 ```bash -rtk --version # Should show "rtk 0.28.2" -rtk gain # Should show token savings stats +rtk --version # 应显示 "rtk 0.27.x" +rtk gain # 应显示 token 节省统计 ``` -> **Name collision warning**: Another project named "rtk" (Rust Type Kit) exists on crates.io. If `rtk gain` fails, you have the wrong package. Use `cargo install --git` above instead. - -## Quick Start +## 快速开始 ```bash -# 1. Install for your AI tool -rtk init -g # Claude Code / Copilot (default) -rtk init -g --gemini # Gemini CLI -rtk init -g --codex # Codex (OpenAI) -rtk init -g --agent cursor # Cursor -rtk init -g --agent windsurf # Windsurf -rtk init --agent cline # Cline / Roo Code -rtk init --agent kilocode # Kilo Code -rtk init --agent antigravity # Google Antigravity -rtk init -g --agent pi # Pi -rtk init --agent hermes # Hermes -rtk init -g --agent droid # Factory Droid +# 1. 为 Claude Code 安装 hook（推荐） +rtk init --global -# 2. Restart your AI tool, then test -git status # Automatically rewritten to rtk git status +# 2. 重启 Claude Code，然后测试 +git status # 自动重写为 rtk git status ``` -Hook-based agents rewrite Bash commands (e.g., `git status` -> `rtk git status`) before execution. Plugin-based agents, including Hermes, use their plugin API to rewrite commands before execution. The agent receives compact output without needing to call `rtk` explicitly. - -**Important:** the hook only runs on Bash tool calls. Claude Code built-in tools like `Read`, `Grep`, and `Glob` do not pass through the Bash hook, so they are not auto-rewritten. To get RTK's compact output for those workflows, use shell commands (`cat`/`head`/`tail`, `rg`/`grep`, `find`) or call `rtk read`, `rtk grep`, or `rtk find` directly. - -## How It Works +## 工作原理 ``` - Without rtk: With rtk: + 没有 rtk： 使用 rtk： Claude --git status--> shell --> git Claude --git status--> RTK --> git ^ | ^ | | - | ~2,000 tokens (raw) | | ~200 tokens | filter | - +-----------------------------------+ +------- (filtered) ---+----------+ + | ~2,000 tokens（原始） | | ~200 tokens | 过滤 | + +-----------------------------------+ +------- （已过滤）-----+----------+ ``` -Four strategies applied per command type: +四种策略： -1. **Smart Filtering** - Removes noise (comments, whitespace, boilerplate) -2. **Grouping** - Aggregates similar items (files by directory, errors by type) -3. **Truncation** - Keeps relevant context, cuts redundancy -4. **Deduplication** - Collapses repeated log lines with counts +1. **智能过滤** - 去除噪音（注释、空白、样板代码） +2. **分组** - 聚合相似项（按目录分文件，按类型分错误） +3. **截断** - 保留相关上下文，删除冗余 +4. **去重** - 合并重复日志行并计数 -## Commands +## 命令 -### Files +### 文件 ```bash -rtk ls . # Token-optimized directory tree -rtk read file.rs # Smart file reading -rtk read file.rs -l aggressive # Signatures only (strips bodies) -rtk smart file.rs # 2-line heuristic code summary -rtk find "*.rs" . # Compact find results -rtk grep "pattern" . # Grouped search results -rtk diff file1 file2 # Condensed diff (exit 1 if files differ) +rtk ls . # 优化的目录树 +rtk read file.rs # 智能文件读取 +rtk find "*.rs" . # 紧凑的查找结果 +rtk grep "pattern" . # 按文件分组的搜索结果 ``` ### Git ```bash -rtk git status # Compact status -rtk git log -n 10 # One-line commits -rtk git diff # Condensed diff -rtk git add # -> "ok" -rtk git commit -m "msg" # -> "ok abc1234" +rtk git status # 紧凑状态 +rtk git log -n 10 # 单行提交 +rtk git diff # 精简 diff rtk git push # -> "ok main" -rtk git pull # -> "ok 3 files +10 -2" ``` -### GitHub CLI +### 测试 ```bash -rtk gh pr list # Compact PR listing -rtk gh pr view 42 # PR details + checks -rtk gh issue list # Compact issue listing -rtk gh run list # Workflow run status +rtk jest # Jest 紧凑输出 +rtk vitest # Vitest 紧凑输出 +rtk pytest # Python 测试（-90%） +rtk go test # Go 测试（-90%） +rtk test # 仅显示失败（-90%） ``` -### Test Runners +### 构建 & 检查 ```bash -rtk jest # Jest compact (failures only) -rtk vitest # Vitest compact (failures only) -rtk playwright test # E2E results (failures only) -rtk pytest # Python tests (-90%) -rtk go test # Go tests (NDJSON, -90%) -rtk cargo test # Cargo tests (-90%) -rtk rake test # Ruby minitest (-90%) -rtk rspec # RSpec tests (JSON, -60%+) -rtk err # Filter errors only from any command -rtk test # Generic test wrapper - failures only (-90%) +rtk lint # ESLint 按规则分组 +rtk tsc # TypeScript 错误分组 +rtk cargo build # Cargo 构建（-80%） +rtk ruff check # Python lint（-80%） ``` -### Build & Lint +### 容器 ```bash -rtk lint # ESLint grouped by rule/file -rtk lint biome # Supports other linters -rtk tsc # TypeScript errors grouped by file -rtk next build # Next.js build compact -rtk prettier --check . # Files needing formatting -rtk cargo build # Cargo build (-80%) -rtk cargo clippy # Cargo clippy (-80%) -rtk ruff check # Python linting (JSON, -80%) -rtk golangci-lint run # Go linting (JSON, -85%) -rtk rubocop # Ruby linting (JSON, -60%+) +rtk docker ps # 紧凑容器列表 +rtk docker logs # 去重日志 +rtk kubectl pods # 紧凑 Pod 列表 ``` -### Package Managers +### 分析 ```bash -rtk pnpm list # Compact dependency tree -rtk uv run pytest # Preserve uv env, errors only -rtk pip list # Python packages (auto-detect uv) -rtk pip outdated # Outdated packages -rtk bundle install # Ruby gems (strip Using lines) -rtk prisma generate # Schema generation (no ASCII art) +rtk gain # 节省统计 +rtk gain --graph # ASCII 图表（30 天） +rtk discover # 发现遗漏的节省机会 ``` -### AWS -```bash -rtk aws sts get-caller-identity # One-line identity -rtk aws ec2 describe-instances # Compact instance list -rtk aws lambda list-functions # Name/runtime/memory (strips secrets) -rtk aws logs get-log-events # Timestamped messages only -rtk aws cloudformation describe-stack-events # Failures first -rtk aws dynamodb scan # Unwraps type annotations -rtk aws iam list-roles # Strips policy documents -rtk aws s3 ls # Truncated with tee recovery -``` +## 文档 -### Containers -```bash -rtk docker ps # Compact container list -rtk docker images # Compact image list -rtk docker logs # Deduplicated logs -rtk docker compose ps # Compose services -rtk kubectl pods # Compact pod list -rtk kubectl logs # Deduplicated logs -rtk kubectl services # Compact service list -rtk oc get pods # OpenShift pod summary -rtk oc get services # OpenShift service list -rtk oc logs # Deduplicated logs -``` +- **[TROUBLESHOOTING.md](docs/TROUBLESHOOTING.md)** - 解决常见问题 +- **[INSTALL.md](INSTALL.md)** - 详细安装指南 +- **[ARCHITECTURE.md](docs/contributing/ARCHITECTURE.md)** - 技术架构 -### Infrastructure as Code -```bash -rtk pulumi preview # Strip header/URL/duration noise -rtk pulumi up # Compact apply output -rtk pulumi destroy # Compact destroy output -rtk pulumi refresh # Drift summary -rtk pulumi stack # Stack metadata (strips owner/timestamps) -``` +## 贡献 -### Data & Analytics -```bash -rtk json config.json # Structure without values -rtk deps # Dependencies summary -rtk env -f AWS # Filtered env vars -rtk log app.log # Deduplicated logs -rtk curl # Truncate + save full output -rtk wget # Download, strip progress bars -rtk summary # Heuristic summary -rtk proxy # Raw passthrough + tracking -``` +欢迎贡献！请在 [GitHub](https://github.com/rtk-ai/rtk) 上提交 issue 或 PR。 -### Token Savings Analytics -```bash -rtk gain # Summary stats -rtk gain --graph # ASCII graph (last 30 days) -rtk gain --history # Recent command history -rtk gain --daily # Day-by-day breakdown -rtk gain --all --format json # JSON export for dashboards +加入 [Discord](https://discord.gg/RySmvNF5kF) 社区。 -rtk discover # Find missed savings opportunities -rtk discover --all --since 7 # All projects, last 7 days +## 许可证 -rtk session # Show RTK adoption across recent sessions -``` +Apache 2.0 许可证 - 详见 [LICENSE](LICENSE)。 -## Global Flags +## 免责声明 -```bash --u, --ultra-compact # ASCII icons, inline format (extra token savings) --v, --verbose # Increase verbosity (-v, -vv, -vvv) -``` - -## Examples - -**Directory listing:** -``` -# ls -la (45 lines, ~800 tokens) # rtk ls (12 lines, ~150 tokens) -drwxr-xr-x 15 user staff 480 ... my-project/ --rw-r--r-- 1 user staff 1234 ... +-- src/ (8 files) -... | +-- main.rs - +-- Cargo.toml -``` - -**Git operations:** -``` -# git push (15 lines, ~200 tokens) # rtk git push (1 line, ~10 tokens) -Enumerating objects: 5, done. ok main -Counting objects: 100% (5/5), done. -Delta compression using up to 8 threads -... -``` - -**Test output:** -``` -# cargo test (200+ lines on failure) # rtk test cargo test (~20 lines) -running 15 tests FAILED: 2/15 tests -test utils::test_parse ... ok test_edge_case: assertion failed -test utils::test_format ... ok test_overflow: panic at utils.rs:18 -... -``` - -## Auto-Rewrite Hook - -The most effective way to use rtk. The hook transparently intercepts Bash commands and rewrites them to rtk equivalents before execution. - -**Result**: 100% rtk adoption across all conversations and subagents, zero token overhead. - -**Scope note:** this only applies to Bash tool calls. Claude Code built-in tools such as `Read`, `Grep`, and `Glob` bypass the hook, so use shell commands or explicit `rtk` commands when you want RTK filtering there. - -### Setup - -```bash -rtk init -g # Install hook + RTK.md (recommended) -rtk init -g --opencode # OpenCode plugin (instead of Claude Code) -rtk init -g --auto-patch # Non-interactive (CI/CD) -rtk init -g --hook-only # Hook only, no RTK.md -rtk init --show # Verify installation -``` - -After install, **restart Claude Code**. - -## Windows - -RTK works fully on native Windows. Since **v0.37.2** the auto-rewrite hook runs as a **native binary command** (`rtk hook claude`) — no Unix shell, bash, or jq required — so commands are rewritten transparently on Command Prompt, PowerShell, and Windows Terminal, just like on Linux and macOS. - -### Native Windows - -```powershell -# 1. Download and extract rtk-x86_64-pc-windows-msvc.zip from releases -# 2. Add rtk.exe to your PATH (e.g. C:\Users\\.local\bin) -# 3. Initialize — installs the native binary hook -rtk init -g -``` - -**Upgrading from an older install?** If you set RTK up before v0.37.2 you may still have the legacy `rtk-rewrite.sh` shell hook (which does need a Unix shell). Re-run `rtk init -g` to migrate to the native binary hook. - -**Prerequisites**: some filters shell out to [ripgrep](https://github.com/BurntSushi/ripgrep) (`rg`). Install it and keep it on your PATH (e.g. `winget install BurntSushi.ripgrep.MSVC`) to avoid `Binary 'rg' not found on PATH` warnings. - -**Important**: Do not double-click `rtk.exe` — it is a CLI tool that prints usage and exits immediately. Always run it from a terminal (Command Prompt, PowerShell, or Windows Terminal). - -### WSL - -[WSL](https://learn.microsoft.com/en-us/windows/wsl/install) also works and behaves exactly like Linux: - -```bash -# Inside WSL -curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh -rtk init -g -``` - -| Feature | Native Windows | WSL | -|---------|----------------|-----| -| Filters (cargo, git, etc.) | Full | Full | -| Auto-rewrite hook | Yes (native binary) | Yes | -| `rtk init -g` | Hook mode | Hook mode | -| `rtk gain` / analytics | Full | Full | - -## Supported AI Tools - -RTK supports 15 AI coding tools. Each integration rewrites shell commands to `rtk` equivalents for 60-90% token savings where the agent supports command interception. - -| Tool | Install | Method | -|------|---------|--------| -| **Claude Code** | `rtk init -g` | PreToolUse hook (native binary) | -| **GitHub Copilot (VS Code)** | `rtk init -g --copilot` | PreToolUse hook — transparent rewrite | -| **GitHub Copilot CLI** | `rtk init -g --copilot` | PreToolUse deny-with-suggestion (CLI limitation) | -| **Cursor** | `rtk init -g --agent cursor` | preToolUse hook (hooks.json) | -| **Gemini CLI** | `rtk init -g --gemini` | BeforeTool hook | -| **Codex** | `rtk init -g --codex` | AGENTS.md + RTK.md instructions | -| **Windsurf** | `rtk init -g --agent windsurf` | .windsurfrules (project-scoped) | -| **Cline / Roo Code** | `rtk init --agent cline` | .clinerules (project-scoped) | -| **OpenCode** | `rtk init -g --opencode` | Plugin TS (tool.execute.before) | -| **OpenClaw** | `openclaw plugins install ./openclaw` | Plugin TS (before_tool_call) | -| **Pi** | `rtk init -g --agent pi` (global) | TypeScript extension (tool_call) | -| **Hermes** | `rtk init --agent hermes` | Python plugin adapter (terminal command mutation via `rtk rewrite`) | -| **Mistral Vibe** | Planned ([#800](https://github.com/rtk-ai/rtk/issues/800)) | Blocked on upstream | -| **Kilo Code** | `rtk init --agent kilocode` | .kilocode/rules/rtk-rules.md (project-scoped) | -| **Google Antigravity** | `rtk init --agent antigravity` | .agents/rules/antigravity-rtk-rules.md (project-scoped) | -| **Factory Droid** | `rtk init -g --agent droid` (or per-project) | PreToolUse hook in `~/.factory/hooks.json` (matcher `Execute`) | - -For per-agent setup details, override controls, and graceful degradation, see the [Supported Agents guide](https://www.rtk-ai.app/guide/getting-started/supported-agents). The Hermes plugin source and tests live in `hooks/hermes/`; installed Hermes runtime files still live under `~/.hermes/plugins/rtk-rewrite/`. - -## Configuration - -`~/.config/rtk/config.toml` (macOS: `~/Library/Application Support/rtk/config.toml`): - -```toml -[hooks] -exclude_commands = ["curl", "playwright"] # skip rewrite for these - -[tee] -enabled = true # save raw output on failure (default: true) -mode = "failures" # "failures", "always", or "never" -``` - -When a command fails, RTK saves the full unfiltered output so the LLM can read it without re-executing: - -``` -FAILED: 2/15 tests -[full output: ~/.local/share/rtk/tee/1707753600_cargo_test.log] -``` - -For the full config reference (all sections, env vars, per-project filters), see the [Configuration guide](https://www.rtk-ai.app/guide/getting-started/configuration). - -### Uninstall - -```bash -rtk init -g --uninstall # Remove hook, RTK.md, settings.json entry -cargo uninstall rtk # Remove binary -brew uninstall rtk # If installed via Homebrew -``` - -## Documentation - -- **[rtk-ai.app/guide](https://www.rtk-ai.app/guide)** — full user guide (installation, supported agents, what gets optimized, analytics, configuration, troubleshooting) -- **[INSTALL.md](INSTALL.md)** — detailed installation reference -- **[ARCHITECTURE.md](docs/contributing/ARCHITECTURE.md)** — system design and technical decisions -- **[CONTRIBUTING.md](CONTRIBUTING.md)** — contribution guide -- **[SECURITY.md](SECURITY.md)** — security policy - -## Privacy & Telemetry - -RTK can collect **anonymous, aggregate usage metrics** once per day. Telemetry is **disabled by default** and requires **explicit opt-in consent** (GDPR Art. 6, 7) during `rtk init` or via `rtk telemetry enable`. This data helps us build a better product: identifying which commands need filters, which filters need improvement, and how much value RTK delivers. For the full list of fields, data handling, and contributor guidelines, see **[docs/TELEMETRY.md](docs/TELEMETRY.md)**. - -**What is collected and why:** - -| Category | Data | Why | -|----------|------|-----| -| Identity | Salted device hash (SHA-256, not reversible) | Count unique installations without tracking individuals | -| Environment | RTK version, OS, architecture, install method | Know which platforms to support and test | -| Usage volume | Command count (24h), total commands, tokens saved (24h/30d/total) | Measure adoption and value delivered | -| Quality | Top 5 passthrough commands (0% savings), parse failure count, commands with <30% savings | Identify missing filters and weak ones to improve | -| Ecosystem | Command category distribution (e.g. git 45%, cargo 20%, js 15%) | Prioritize filter development for popular ecosystems | -| Retention | Days since first use, active days in last 30 | Understand engagement and detect churn | -| Adoption | AI agent hook type (claude/gemini/codex), custom TOML filter count | Track integration coverage and DSL adoption | -| Configuration | Whether config.toml exists, number of excluded commands, project count | Understand user maturity and customization patterns | -| Features | Usage counts for meta-commands (gain, discover, proxy, verify) | Know which RTK features are valued vs unused | -| Economics | Estimated USD savings (based on API token pricing) | Quantify the value RTK provides to users | - -All data is **aggregate counts or anonymized command names** (first 3 words, no arguments). Top commands report only tool names (e.g. "git", "cargo"), never full command lines. - -**What is NOT collected:** source code, file paths, command arguments, secrets, environment variables, personal data, or repository contents. - -**Manage telemetry:** -```bash -rtk telemetry status # Check current consent state -rtk telemetry enable # Give consent (interactive prompt) -rtk telemetry disable # Withdraw consent — stops all collection immediately -rtk telemetry forget # Withdraw consent + delete all local data + request server-side erasure -``` - -**Override via environment:** -```bash -export RTK_TELEMETRY_DISABLED=1 # Blocks telemetry regardless of consent -``` - -## Star History - - - - - - Star History Chart - - - -## StarMapper - - - - - - StarMapper - - - -## Core team - -- **Patrick Szymkowiak** — Founder - [GitHub](https://github.com/pszymkowiak) · [LinkedIn](https://www.linkedin.com/in/patrick-szymkowiak/) -- **Florian Bruniaux** — Core contributor - [GitHub](https://github.com/FlorianBruniaux) · [LinkedIn](https://www.linkedin.com/in/florian-bruniaux-43408b83/) -- **Adrien Eppling** — Core contributor - [GitHub](https://github.com/aeppling) · [LinkedIn](https://www.linkedin.com/in/adrien-eppling/) -- **Nicolas Le Cam** — Core contributor - [Github](https://github.com/kush) · [LinkedIn](https://www.linkedin.com/in/nicolas-le-cam-386387160/) - -## Contributing - -Contributions welcome! Please open an issue or PR on [GitHub](https://github.com/rtk-ai/rtk). - -Join the community on [Discord](https://discord.gg/RySmvNF5kF). - -## License - -Apache License 2.0 - see [LICENSE](LICENSE) for details. - -## Disclaimer - -See [DISCLAIMER.md](DISCLAIMER.md). +详见 [DISCLAIMER.md](DISCLAIMER.md)。