# rtk (Rust Token Killer) — WorkBuddy 安装与适配指南

> **项目地址**：https://github.com/rtk-ai/rtk  
> **当前版本**：v0.39.0  
> **目标平台**：WorkBuddy (macOS / Windows Git Bash)
>
> **效果**：所有 `ls` / `find` / `grep` / `cat` 等命令的输出自动压缩 60-90%，预计整体 Token 节约 25-30%。
>
> **使用方式**：把本文档路径告诉 WorkBuddy，AI 会自动按步骤执行安装和配置。

---

## 目录

1. [一键安装（快捷方式）](#1-一键安装快捷方式)
2. [安装流程（分步说明）](#2-安装流程分步说明)
3. [WorkBuddy 自动适配（核心）](#3-workbuddy-自动适配核心)
4. [Windows 平台说明](#4-windows-平台说明)
5. [安装自检](#5-安装自检)
6. [Token 节约分析（参考）](#6-token-节约分析参考)
7. [持续追踪：查询节约数据](#7-持续追踪查询节约数据)

---

## 1. 一键安装（快捷方式）

以下命令一次性完成 rtk 安装 + 自动适配配置 + 信任确认：

```bash
# ── rtk 一键安装 + WorkBuddy 自动适配 ──
# 可在终端直接执行，也可交给 WorkBuddy AI 自动运行

# Step 1: 检查是否已安装
if ! which rtk &>/dev/null; then
  echo "⏳ 正在安装 rtk..."
  curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
  echo "✅ rtk 安装完成"
else
  echo "✅ rtk 已安装 ($(rtk --version))"
fi

# Step 2: 配置 WorkBuddy 自动适配（shell function，幂等）
FUNC_MARKER="# ── rtk auto-wrap (WorkBuddy) ──"
if ! grep -q "$FUNC_MARKER" ~/.zshenv 2>/dev/null; then
  cat >> ~/.zshenv << 'EOF'

# ── rtk auto-wrap (WorkBuddy) ──
# 函数而非 alias：WorkBuddy shell-snapshot 会执行 unalias -a，
# 但不清除函数。
# 仅 WorkBuddy 环境生效（靠 CLIENT_INFO_PLATFORM 隔离），终端不受影响。
if [[ "$CLIENT_INFO_PLATFORM" == "WorkBuddy" ]]; then
  # 输出密集型命令自动通过 rtk 压缩，省 60-90% token
  ls()   { rtk ls "$@"; }
  cat()  { rtk cat "$@"; }
  head() { rtk head "$@"; }
  tail() { rtk tail "$@"; }
  grep() { rtk grep "$@"; }
  find() { rtk find "$@"; }
  diff() { rtk diff "$@"; }
  tree() { rtk tree "$@"; }
  du()   { rtk du "$@"; }
  df()   { rtk df "$@"; }
  # 排除 wc/sort/uniq：输出通常很小或用于管道，无压缩收益
fi
EOF
  echo "✅ WorkBuddy 自动适配已写入 ~/.zshenv"
else
  echo "✅ WorkBuddy 自动适配已存在"
fi

# Step 3: rtk trust（消除 untrusted filters 警告）
rtk trust 2>/dev/null && echo "✅ rtk trust 已确认"

# Step 4: 验证
echo ""
echo "═══════════════════════════════════════"
echo " 安装验证"
echo "═══════════════════════════════════════"
echo "rtk 版本 : $(rtk --version)"
echo "自动适配 : $(grep -c 'rtk auto-wrap' ~/.zshenv 2>/dev/null) 处函数定义"
echo "trust 状态: $(rtk trust 2>&1 | head -1)"
echo ""
echo "✅ 全部完成！后续 WorkBuddy 中所有 ls/find/grep 等命令自动走 rtk"
```

---

## 2. 安装流程（分步说明）

### 2.1 环境预检

检查本地是否已有 rtk，以及依赖是否可用：

```bash
# 检查 rtk 安装状态
which rtk 2>/dev/null && rtk --version || echo "未安装"

# 检查依赖
which curl && which tar
```

若已安装，跳到 [第 3 节](#3-workbuddy-自动适配核心)。

### 2.2 在线安装（推荐）

```bash
curl -fsSL https://raw.githubusercontent.com/rtk-ai/rtk/refs/heads/master/install.sh | sh
```

**预期输出**：

```
[INFO] Installing rtk...
[INFO] Detected: darwin aarch64          # macOS + Apple Silicon
[INFO] Target: aarch64-apple-darwin
[INFO] Version: v0.39.0
[INFO] Downloading from: https://github.com/rtk-ai/rtk/releases/download/v0.39.0/rtk-aarch64-apple-darwin.tar.gz
[INFO] Extracting...
[INFO] Successfully installed rtk to ~/.local/bin/rtk
```

> Linux x86_64 用户会看到 `linux x86_64` / `x86_64-unknown-linux-musl`。

**安装位置**：`~/.local/bin/rtk`

### 2.3 PATH 确认

确保 `~/.local/bin` 在 PATH 中：

```bash
echo "$PATH" | grep -q "$HOME/.local/bin" || \
  echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshenv
```

---

## 3. WorkBuddy 自动适配（核心）

### 3.1 关键差异

| 项目 | Claude Code | WorkBuddy |
|------|------------|-----------|
| 指令注入 | 自动读取 CLAUDE.md | 不读取 CLAUDE.md |
| 命令前缀 | AI 自动加 `rtk` | ❌ 依赖人工记忆 |
| hook 机制 | 支持 PreToolUse hook | ❌ 不支持 |

**WorkBuddy 不能依赖 AI 自觉**：靠人记「每次命令前加 rtk」在长会话中必然遗漏。必须用 shell 层自动包裹。

### 3.2 可行方案对比

| 方案 | 原理 | WorkBuddy 可行性 | 结论 |
|------|------|:---------------:|:----:|
| `alias`（~/.zshrc） | shell 别名 | ❌ shell-snapshot 执行 `unalias -a` | 不可用 |
| **shell 函数（~/.zshenv）** | 函数不受 `unalias` 影响 | ✅ 已验证生效 | **采用** |
| `AGENTS.md` 约束 | 人肉提醒 | 靠自觉，必然漏 | 备选 |
| rtk 内置 hook | PreToolUse | ❌ WorkBuddy 不支持 | 不可用 |

### 3.3 适配方案（已验证）

**核心原理**：向 `~/.zshenv` 追加 shell 函数定义，函数在 WorkBuddy 环境下自动用 rtk 包裹指定命令。

**为什么是 `~/.zshenv` 而非 `~/.zshrc`**：
- WorkBuddy 的 Bash 工具执行顺序为：先 source `~/.zshenv` → 再加载 shell-snapshot（内含 `unalias -a`）→ 最后执行用户命令
- 函数（function）不受 `unalias -a` 影响，alias 会被清除
- `~/.zshenv` 在每次 zsh 登录会话中都生效

**自动包裹的命令名单（10 个）**：

```bash
ls()   { rtk ls "$@"; }    # 目录浏览，省 65-80%
cat()  { rtk cat "$@"; }   # 文件读取，省 60-70%
head() { rtk head "$@"; }  # 文件头部，省 60-70%
tail() { rtk tail "$@"; }  # 文件尾部，省 60-70%
grep() { rtk grep "$@"; }  # 搜索，省 75-80%
find() { rtk find "$@"; }  # 文件查找，省 65-80%
diff() { rtk diff "$@"; }  # 差异对比，省 80%
tree() { rtk tree "$@"; }  # 目录树，省 80%
du()   { rtk du "$@"; }    # 磁盘使用，省 65%
df()   { rtk df "$@"; }    # 文件系统，省 65%
```

**不包裹的命令**：`wc` / `sort` / `uniq`（输出通常很小或在管道中使用，无压缩收益）

### 3.4 执行配置

将以下内容追加到 `~/.zshenv`：

```bash
# ── rtk auto-wrap (WorkBuddy) ──
if [[ "$CLIENT_INFO_PLATFORM" == "WorkBuddy" ]]; then
  ls()   { rtk ls "$@"; }
  cat()  { rtk cat "$@"; }
  head() { rtk head "$@"; }
  tail() { rtk tail "$@"; }
  grep() { rtk grep "$@"; }
  find() { rtk find "$@"; }
  diff() { rtk diff "$@"; }
  tree() { rtk tree "$@"; }
  du()   { rtk du "$@"; }
  df()   { rtk df "$@"; }
fi
```

### 3.5 使用限制说明

| 场景 | 是否自动包裹 | 说明 |
|------|:----------:|------|
| `ls` / `find` / `grep` 等直接命令 | ✅ **是** | shell 函数自动转成 `rtk ls` |
| 带管道的链式命令 `ls \| grep foo` | ✅ **是** | 每个命令独立受函数包裹 |
| `rtk` 本身 | ✅ 无影响 | 函数内已用完整路径 `rtk` |
| 需要原始输出时 | 用 `command ls` 绕过 | `command` 前缀跳过 shell 函数 |
| WorkBuddy 专属工具（Read/Write/Edit） | ❌ 不走 bash | 这些是工具 API 调用，不受影响 |

### 3.6 消除 rtk trust 警告

首次使用 rtk 时，部分命令（如 `grep`）会输出 `[untrusted filters]` 警告。执行以下命令消除：

```bash
rtk trust
```

---

## Windows 平台说明

> ✅ **Windows 11 + Git Bash (MINGW64) 已于 2026-05-19 完成实测验证，功能可用。** 以下为验证通过的安装与配置方案。

### 4.1 平台支持对照

| 维度 | Git Bash (MINGW64) ✅ | WSL (推荐) | 原生 PowerShell |
|------|:--:|:--:|:--:|
| rtk 二进制 | ✅ rtk-x86_64-pc-windows-msvc.zip | ✅ 同左 | ✅ 同左 |
| rtk 过滤/分析功能 | ✅ 完整 | ✅ 完整 | ✅ 完整 |
| **WorkBuddy 自动包裹** | ✅ shell 函数（~/.bashrc） | ✅ shell 函数 | ❌ 未测试 |
| 安装方式 | ghproxy 镜像下载 | 同 macOS 在线安装 | 手动下载解压 |
| 已知问题 | PATH 解析警告（可忽略） | 无 | 不推荐 |

> **推荐 Git Bash**：实测 WorkBuddy 在 Windows 上通过 Git Bash 执行 bash 命令，shell 函数方案完全可用。

### 4.2 Git Bash 安装步骤（已验证）

```bash
# 1. 下载（GitHub 直连不通时使用 ghproxy 镜像）
curl -L -o rtk.zip "https://ghproxy.net/https://github.com/rtk-ai/rtk/releases/download/v0.39.0/rtk-x86_64-pc-windows-msvc.zip"

# 2. 解压到 ~/.local/bin/
unzip rtk.zip -d ~/.local/bin/

# 3. 验证
export PATH="$HOME/.local/bin:$PATH"
rtk --version  # → rtk 0.39.0
```

### 4.3 Git Bash 自动包裹配置（已验证）

将以下内容追加到 `~/.bashrc`：

```bash
# ── PATH ──
if [[ ":$PATH:" != *":$HOME/.local/bin:"* ]]; then
  export PATH="$HOME/.local/bin:$PATH"
fi

# ── rtk auto-wrap (WorkBuddy only) ──
if [[ "$CLIENT_INFO_PLATFORM" == "WorkBuddy" ]]; then
  ls()   { rtk ls "$@"; }
  cat()  { rtk cat "$@"; }
  head() { rtk head "$@"; }
  tail() { rtk tail "$@"; }
  grep() { rtk grep "$@"; }
  find() { rtk find "$@"; }
  diff() { rtk diff "$@"; }
  tree() { rtk tree "$@"; }
  du()   { rtk du "$@"; }
  df()   { rtk df "$@"; }
fi
```

**设计要点：**
- 用 shell 函数而非 alias——WorkBuddy 的 shell-snapshot 会执行 `unalias -a`，但不清除函数
- 用 `CLIENT_INFO_PLATFORM` 环境变量隔离——仅在 WorkBuddy 环境生效，手动打开终端不受影响
- macOS 方案（`~/.zshenv` + alias）不适用于 Windows Git Bash，需改用 `~/.bashrc` + 函数

### 4.4 已知问题

| 问题 | 级别 | 说明 | 处理 |
|------|:--:|------|------|
| `Failed to resolve via PATH, falling back to direct exec` | ⚠️ 警告 | rtk 是原生 Windows PE 二进制，其 PATH 查找走 Windows 原生 `%PATH%`，无法解析 Git Bash 的 MSYS2 虚拟路径。rtk 内置 fallback 机制可正确处理 | **可安全忽略**，功能完全正常 |
| `tree` 命令依赖外部工具 | ❌ 报错 | Git Bash 不自带 `tree`，`rtk tree` 执行失败 | 如不需要 tree，从 .bashrc 函数列表中移除 `tree() { rtk tree "$@"; }` 这行 |
| 非交互式 Shell 不加载 .bashrc | ℹ️ 说明 | WorkBuddy 的 Bash 工具启动的是非交互式 shell，不会自动加载 `~/.bashrc` | WorkBuddy 内部已有 shell snapshot 机制，实测 PATH 和函数在 WorkBuddy 会话中正常生效 |

### 4.5 WSL 用户适配指引

如果 WorkBuddy 在 Windows 的 bash 命令通过 WSL 执行，使用与 macOS 相同的 shell function 方案：

1. **安装 rtk**：在 WSL 内执行在线安装命令（[第 1 节](#1-一键安装快捷方式)）
2. **写入位置**：从 `~/.zshenv` 改为 `~/.bashrc`（WSL 默认使用 bash）
3. **配置内容**：

```bash
# ── rtk auto-wrap (WorkBuddy on WSL) ──
if [[ "$CLIENT_INFO_PLATFORM" == "WorkBuddy" ]]; then
  ls()   { rtk ls "$@"; }
  cat()  { rtk cat "$@"; }
  head() { rtk head "$@"; }
  tail() { rtk tail "$@"; }
  grep() { rtk grep "$@"; }
  find() { rtk find "$@"; }
  diff() { rtk diff "$@"; }
  du()   { rtk du "$@"; }
  df()   { rtk df "$@"; }
fi
```

### 4.6 自检命令（Windows）

```bash
echo "═══════════════ rtk Windows 自检 ═══════════════"

echo ""
echo "1️⃣  二进制安装检查"
if which rtk &>/dev/null; then
  echo "   ✅ rtk 路径: $(which rtk)"
  echo "   ✅ 版本: $(rtk --version)"
  echo "   ✅ 架构: $(file $(which rtk))"
else
  echo "   ❌ rtk 未安装"
  exit 1
fi

echo ""
echo "2️⃣  WorkBuddy 自动适配检查"
if grep -q 'rtk auto-wrap' ~/.bashrc 2>/dev/null; then
  echo "   ✅ ~/.bashrc 已配置"
elif grep -q 'rtk auto-wrap' ~/.zshenv 2>/dev/null; then
  echo "   ✅ ~/.zshenv 已配置"
else
  echo "   ❌ 未找到 rtk auto-wrap 配置"
fi

echo ""
echo "3️⃣  核心命令验证"
for cmd in ls cat grep find diff; do
  rtk $cmd --help &>/dev/null && echo "   ✅ rtk $cmd" || echo "   ❌ rtk $cmd"
done

echo ""
echo "4️⃣  WorkBuddy 环境变量"
echo "   CLIENT_INFO_PLATFORM=$CLIENT_INFO_PLATFORM"

echo ""
echo "═══════════════════════════════════════"
```

### 4.7 完整子命令列表（v0.39.0，共 52 个）

```
ls tree read smart git gh glab aws psql pnpm err test json deps env
find diff log dotnet docker kubectl summary grep init wget wc gain
cc-economics config jest vitest prisma tsc next lint prettier format
playwright cargo npm npx curl discover session telemetry learn run
proxy pipe trust untrust verify ruff pytest mypy rake rubocop rspec
pip go gt golangci-lint hook-audit rewrite hook help
```

---

## 5. 安装自检

### 5.1 完整自检（macOS）

```bash
echo "═══════════════ rtk 自检 ═══════════════"

echo ""
echo "1️⃣  二进制安装检查"
if which rtk &>/dev/null; then
  echo "   ✅ rtk 路径: $(which rtk)"
  echo "   ✅ 版本: $(rtk --version)"
else
  echo "   ❌ rtk 未安装"
  exit 1
fi

echo ""
echo "2️⃣  WorkBuddy 自动适配检查"
if grep -q 'rtk auto-wrap' ~/.zshenv 2>/dev/null; then
  FUNC_COUNT=$(grep -c '^  [a-z]*()' ~/.zshenv)
  echo "   ✅ ~/.zshenv 已配置（$FUNC_COUNT 个函数）"
else
  echo "   ❌ ~/.zshenv 未配置"
fi

echo ""
echo "3️⃣  WorkBuddy 环境变量检测"
echo "   CLIENT_INFO_PLATFORM=$CLIENT_INFO_PLATFORM"
if [[ "$CLIENT_INFO_PLATFORM" == "WorkBuddy" ]]; then
  echo "   ✅ WorkBuddy 环境识别正常"
else
  echo "   ℹ️  当前非 WorkBuddy 环境（终端预览 OK）"
fi

echo ""
echo "4️⃣  压缩效果对比"
# 转储自身作为测试文件列表（避免依赖特定目录）
mkdir -p /tmp/rtk-test
for f in foo bar baz qux quux corge grault garply waldo fred; do
  echo "file: $f" > /tmp/rtk-test/$f.md
done
RAW=$(command ls -la /tmp/rtk-test/ | wc -c)
COMPRESSED=$(ls -la /tmp/rtk-test/ | wc -c)
rm -rf /tmp/rtk-test
echo "   原始输出: ${RAW}B"
echo "   rtk 压缩: ${COMPRESSED}B"
if [[ $RAW -gt 0 ]]; then
  SAVED=$(( (RAW - COMPRESSED) * 100 / RAW ))
  echo "   压缩率: ${SAVED}%"
else
  echo "   压缩率: N/A"
fi

echo ""
echo "═══════════════════════════════════════"
```

### 5.2 版本验证

```bash
rtk --version
# 预期：rtk x.y.z
```

### 5.3 函数生效验证

```bash
# 检查 ls 是否被函数包裹
which ls
# 预期输出应包含 "rtk ls" 字样
```

### 5.4 自检清单

| 检查项 | 通过标准 |
|--------|---------|
| 二进制安装 | `which rtk` 返回路径 |
| PATH 可访问 | 任意目录可执行 `rtk --version` |
| WorkBuddy 自动适配 | `~/.zshenv` 包含 rtk 函数定义（`grep 'rtk auto-wrap' ~/.zshenv`） |
| 函数生效 | `which ls` 输出显示函数定义而非 `/bin/ls` |
| trust 通过 | `rtk trust` 无警告 |
| 压缩效果 | `ls` 输出 < `command ls` 输出 |

---

## 6. Token 节约分析（参考）

> 以下数据基于真实 WorkBuddy 重度用户的实际使用记录。不同用户的工作模式差异会影响实际节约比例，建议在安装一周后运行 `rtk gain` 查看自己的数据。

### 6.1 Bash 命令构成与压缩收益

| 命令类型 | Bash 占比 | rtk 压缩率 | 加权节约 |
|---------|:------:|:------:|:------:|
| `ls` / `find` / `tree` — 目录浏览 | 20% | 80% | 16.0% |
| `grep` / `rg` — 代码/文件搜索 | 20% | 80% | 16.0% |
| `cat` / `read` — 文件内容读取 | 25% | 70% | 17.5% |
| `git` 系列 — 版本控制 | 15% | 80% | 12.0% |
| `pip` / `npm` — 包管理 | 10% | 80% | 8.0% |
| 脚本/工具输出 | 5% | 70% | 3.5% |
| 其他 | 5% | 50% | 2.5% |
| **合计** | **100%** | | **75.5%** |

### 6.2 整体 Token 节约

```
Bash 输出占总 Token 消耗比例   ≈ 35-40%
Bash 输出加权压缩率（rtk）     ≈ 75%
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
整体 Token 节约比例           ≈ 27-30%
```

### 6.3 收益最高的场景 Top 5

| 排名 | 场景 | rtk 命令 | 压缩率 |
|:---:|------|----------|:-----:|
| 1 | 大目录浏览（50+ 文件） | `ls` → `rtk ls` | ~80% |
| 2 | 全局代码/日志搜索 | `grep` → `rtk grep` | ~80% |
| 3 | 大改动 git diff | `diff` → `rtk diff` | ~80% |
| 4 | 构建/安装输出 | `npm install` → `rtk npm install` | ~90% |
| 5 | 文件内容查阅 | `cat` → `rtk cat` | ~70% |

### 6.4 WorkBuddy 实测数据

安装后实际使用 39 次调用的全局数据：

```
Total commands:    39
Tokens saved:      103.0K (96.3%)
Total exec time:   1.5s (avg 39ms/command)

By Command (Top 5):
  rtk grep           2次    98.8K saved  (98.1%)
  rtk ls -la        10次     3.3K saved  (58-81%)
  rtk git pull       1次      614 saved  (99.0%)
  rtk find           4次      197 saved  (88.3%)
  rtk ls             4次      107 saved  (33.8%)

效率仪表盘: ███████████████████████░ 96.3%
```

> 实测线：对 `ls -la` 原始 3,815B → rtk 压缩后 1,646B，**省 57%**。

---

## 7. 持续追踪：查询节约数据

rtk 的统计功能不依赖 Claude Code，在 WorkBuddy 中同样可用。

### 7.1 查询命令

| 命令 | 用途 |
|------|------|
| `rtk gain` | 累计统计摘要：总调用次数、节约 token 数、效率仪表盘 |
| `rtk gain --history` | 完整明细：每条命令的时间、名称、节约量、压缩率、耗时 |

### 7.2 统计原理

```
WorkBuddy 执行 ls → shell 函数转为 rtk ls → rtk 压缩输出 → 同时写入本地统计 DB
                                                               ↓
                                               rtk gain → 读取 DB → 展示报告
```

### 7.3 数据存储位置

统计数据库为本地文件，无需手动管理：
- **macOS**：`~/Library/Application Support/rtk/history.db`
- **Linux**：`~/.local/share/rtk/history.db`

### 7.4 典型查询节奏

| 节点 | 推荐操作 |
|------|---------|
| 安装当天 | `rtk gain` 确认统计功能正常（应有少量记录） |
| 使用一周后 | `rtk gain --history` 查看命令分布，识别高收益场景 |
| 每月底 | `rtk gain` 获取月度总节约，评估 ROI |

---

## 附录

### A. 问题排查

| 问题 | 可能原因 | 修复 |
|------|---------|------|
| `which ls` 显示 `/bin/ls` 而非函数 | `~/.zshenv` 或 `~/.bashrc` 未正确加载 | 检查文件语法：`source ~/.zshenv` 或 `source ~/.bashrc` 确认无报错 |
| `rtk: command not found` | 未安装或 PATH 未配置 | 重新执行在线安装命令（macOS）或手动安装（Windows） |
| `[untrusted filters]` 警告 | 首次使用需确认 trust | 执行 `rtk trust` |
| 终端中出现 `rtk` 前缀 | `CLIENT_INFO_PLATFORM` 未正确隔离 | 检查 `~/.zshenv` / `~/.bashrc` 中的判断条件，非 WorkBuddy 环境会跳过 |
| (Windows Git Bash) `Failed to resolve via PATH` | Windows PE 二进制与 MSYS2 路径不一致 | **可安全忽略**，rtk 内置 fallback 机制正常工作 |
| (Windows Git Bash) `tree: command not found` | Git Bash 不自带 tree | 从 `.bashrc` 函数列表中移除 `tree()` 行 |

### B. 注意事项

- rtk 只压缩 **Bash 命令输出**，不拦截 WorkBuddy 专属工具（Read、Write、Edit、WebFetch 等）
- 需要原始输出时：用 `command ls` 而非 `ls`（`command` 前缀跳过 shell 函数）
- 跨平台支持：macOS (arm64/x86_64)、Linux (x86_64/arm64)、Windows (x86_64，Git Bash + WSL)
  - macOS 自动包裹方案 **已验证（shell function + ~/.zshenv）**
  - Windows Git Bash 自动包裹方案 **已验证（shell function + ~/.bashrc）**，详见第 4 节
- 本项目地址：https://github.com/rtk-ai/rtk