rtk git log

Condenses git log output for token efficiency.

Syntax:

rtk git log [git-flags]

Examples:

# Show last 10 commits (condensed)
rtk git log -10

# With specific format
rtk git log --oneline --graph -20

Token Savings: 80% (verified with fixtures) Performance: <10ms startup

Expected Output:

commit abc1234 Add feature X
commit def5678 Fix bug Y
...

这个模板的设计逻辑值得注意：

1. **一句话功能定位**（Condenses ... for token efficiency）——让读者 3 秒内知道该命令省在哪；
2. **语法 + 带注释的示例**——示例不是孤立的命令，而是“意图（注释）+ 命令”配对，符合“Show, Don't Tell”原则；
3. **量化声明必须附验证方式**——“80% (verified with fixtures)”要求每个百分比都能追溯到某个 fixture，而不是拍脑袋；
4. **预期输出**——给出过滤后的实际形态，读者可以当场比对。

这一模板在仓库中有真实的执行痕迹。例如 [src/cmds/git/git.rs](https://gitcode.com/GitHub_Trending/rtk4/rtk/blob/e8541d1e1180f7ef4c736322cedc8e834f2f8f77/src/cmds/git/git.rs?utm_source=gitcode_repo_files#L3153-L3175) 中的测试 `test_filter_log_output_token_savings` 就是按同样的逻辑写的：构造 20 条带完整元数据的 `git log` 输出作为输入，经 `filter_log_output` 过滤后断言节省率 `savings >= 60.0`——即模板中“verified with fixtures”在工程上对应的是一个可重复执行的断言，而非一次性的人工测量。

## 四、性能声明的证据链：Fixture + count_tokens() + 测试阈值

Agent 规范中最有工程含量的部分是 **Performance Claims Documentation** 模板，它把“RTK 能省 60-90% token”这句话拆解成了一条完整的证据链：

```markdown
## Token Savings Evidence

**Methodology**:
- Fixtures: Real command output from production environments
- Measurement: Whitespace-based tokenization (`count_tokens()`)
- Verification: Tests enforce ≥60% savings threshold

方法论三要素与仓库源码完全对应：

• Fixtures（真实输出样本）：仓库 tests/fixtures/ 目录下存放着大量真实命令输出，如 tests/fixtures/sbt_test_pass.txt、tests/fixtures/mvn_install_slice_raw.txt、tests/fixtures/golangci_v2_json.txt 等，覆盖 sbt、Maven、golangci-lint、CTest 等生态，作为 Filter 测试的输入基准。

• 测量函数 count_tokens()：模板中提到的函数在 src/core/utils.rs 中有明确定义——

  /// Count whitespace-delimited tokens in text. Used by filter tests to verify
  /// token savings claims.
  #[cfg(test)]
  pub fn count_tokens(text: &str) -> usize {
      text.split_whitespace().count()
  }
  

  即“按空白分词计数”，且仅在测试构建（#[cfg(test)]）中启用，说明它是专门服务于性能声明验证的工具函数，而非运行时逻辑。

• 测试阈值 ≥60%：各 Filter 的测试内联复用了同一个分词函数并断言阈值，例如 src/cmds/git/git.rs：

  let output = filter_log_output(&input, 10, false, false);
  let savings = 100.0 - (count_tokens(&output) as f64 / count_tokens(&input) as f64 * 100.0);
  assert!(
      savings >= 60.0,
      "Expected ≥60% token savings, got {:.1}%",
      savings
  );
  

  模板中“Tests enforce ≥60% savings threshold”因此不是口号：只要节省率跌破 60%，cargo test 就会失败，Filter 合入即被拦截。

模板还规定了结果文档的呈现格式——“按 Filter 列表 + 每行附 fixture 路径”的表格，以及 hyperfine 启动耗时基准示例：

hyperfine 'rtk git status' --warmup 3

# Output:
Time (mean ± σ):       6.2 ms ±   0.3 ms    [User: 4.1 ms, System: 1.8 ms]
Range (min … max):     5.8 ms …   7.1 ms    100 runs

并以固定命令收尾验证：

# Run token accuracy tests
cargo test test_token_savings

# All tests should pass, enforcing ≥60% savings

从源码结构看，这条证据链还与运行时的分类器呼应：src/discover/registry.rs 中的 Classification::Supported 变体携带 estimated_savings_pct: f64 字段，说明每个被识别的命令在路由时都带有一个预估节省率——文档中面向用户展示的百分比与代码内部的元数据是同一套口径。

五、安装文档规范：多平台步骤 + 名称冲突预警 + 排障

规范第三个模板是 Installation Documentation，其结构是“每个平台给安装选项 → 每步后跟验证命令 → 末尾集中排障”：

macOS（两条路径）：

# Option 1: Homebrew
brew install rtk-ai/tap/rtk
rtk --version  # Should show rtk X.Y.Z

# Option 2: From Source
git clone <rtk repo>
cd rtk
cargo install --path .
rtk --version  # Verify installation

Linux（源码 + 二进制下载）：

# From Source (Cargo required)
cargo install --path .
which rtk && rtk --version

# Binary Download (faster)
# 下载 rtk-linux-x86_64 后：
chmod +x rtk
sudo mv rtk /usr/local/bin/
rtk --version

Windows：下载 rtk-windows-x86_64.exe，加入 PATH，rtk --version 验证。

模板随后给出两个高频故障的排障条目：

• rtk: command not found：原因是二进制不在 PATH，修复方式是 echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc；
• rtk gain 失败：原因是装错了名为 rtk 的另一项目（名称冲突，Rust Type Kit），修复方式是 cargo uninstall rtk 后从正确的 rtk-ai 仓库重装，并用 rtk gain --help 验证。

其中“名称冲突”这一点在仓库的 INSTALL.md 中有更完整的版本：该安装指南开篇即警告存在两个完全不同的 "rtk" 项目，并把 rtk gain 能显示节省量看板作为判定装对了 RTK（Rust Token Killer）的唯一金标准；仓库同样提供了 scripts/check-installation.sh 一类脚本辅助验证。模板要求“每个安装步骤必须有验证命令”的原则，在 rtk gain 这个探针上体现得最为彻底——因为它同时验证了“二进制存在”和“是这个项目的二进制”两件事。

六、Hook 集成文档：五步命令路由与两个 Hook 脚本

第四个模板讲解 RTK 与 Claude Code 的集成机制，给出了标准化的五步流程：

1. 用户在 Claude Code 中键入命令：git status；
2. Hook（rtk-rewrite.sh）拦截该命令；
3. 改写为 rtk git status；
4. RTK 应用 Filter，返回压缩后的输出；
5. Claude 看到的是 token 优化后的结果（文档标注约 80% 节省）。

模板指认了两个 Hook 文件及其职责分工，它们在仓库中均真实存在：

• .claude/hooks/rtk-rewrite.sh —— 命令改写（模板标注 DO NOT MODIFY）；
• .claude/hooks/rtk-suggest.sh —— 当某命令存在可用 Filter 时发出建议，不修改执行。

仓库源码比模板更能说明这套机制的工程细节。从 rtk-rewrite.sh 的头部注释可以看出，Hook 本身不含任何映射逻辑，而是把 rtk rewrite 子命令作为“单一事实来源”（single source of truth），并约定了一套退出码协议：

退出码	含义	Hook 行为
0 + stdout	找到改写且未命中 deny/ask 规则	输出 permissionDecision: "allow"，自动放行
1	无 RTK 等价命令	原样透传（exit 0）
2	命中 deny 规则	透传，交给 Claude Code 原生 deny 处理
3 + stdout	命中 ask 规则	改写命令但不自动放行，让 Claude Code 向用户弹确认

脚本还会跳过 heredoc（*'<<'*）与空命令；当设置环境变量 RTK_HOOK_AUDIT=1 时，所有动作（rewrite / skip:no_match / skip:deny_rule 等）会追加写入 ~/.local/share/rtk/hook-audit.log，使“透明改写”这一行为本身可审计。这正是文档中“Explain Hook Integration”要求落地为可验证依据的地方：ls -la .claude/hooks/*.sh 检查可执行位、rtk init --show 检查 Hook 是否安装，都是模板给出的验证手段（见 INSTALL.md “Project Initialization”一节）。

与之互补的 rtk-suggest.sh 则代表了另一条更温和的集成路径：它不调用 rtk rewrite，而是在脚本内用正则匹配 git status/diff/log、cargo test、vitest、pnpm list、docker ps 等命令族，命中后仅输出一条 systemMessage（如 "⚡ RTK available: rtk git status (60-90% token savings)"），把改写决定留给模型。从源码结构看，rewrite 走的是“二进制内规则表”（src/discover/rules.rs，经 src/discover/registry.rs 的 RegexSet 统一编译），而 suggest 走的是“脚本内启发式”，前者保证确定性路由，后者保证零侵入提示，两条路径在文档中被明确区分为“自动改写”与“建议”两种预期行为——“有 Filter 的命令 → 自动改写；无 Filter 的命令 → 原样执行”。

七、Filter 开发指南：从模块到质量门禁

第五个模板是 Filter Development Guide，规定了贡献一个新 Filter 的五步流程：

第 1 步：创建 Filter 模块

在 src/cmds/<ecosystem>/newcmd_cmd.rs 中实现，模板给出的骨架展示了三条硬性要求——正则必须惰性编译、过滤函数返回 Result、测试必须断言节省率：

use anyhow::{Context, Result};
use regex::Regex;
use std::sync::LazyLock;

static PATTERN: LazyLock<Regex> =
    LazyLock::new(|| Regex::new(r"pattern").unwrap());

pub fn filter_newcmd(input: &str) -> Result<String> {
    // Filter logic
    Ok(condensed_output)
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn test_token_savings() {
        let input = include_str!("../tests/fixtures/newcmd_raw.txt");
        let output = filter_newcmd(input).unwrap();
        let savings = calculate_savings(input, &output);
        assert!(savings >= 60.0);
    }
}

LazyLock<Regex> 这一要求在仓库里是普遍执行的惯例，例如 src/discover/registry.rs 用两个 LazyLock（REGEX_SET 与 COMPILED）把所有改写规则的正则在首次使用时一次性编译复用，避免每次调用重复编译——这是“<10ms 启动时间”目标的直接支撑。

第 2 步：注册到 main.rs

// src/main.rs
#[derive(Subcommand)]
enum Commands {
    Newcmd {
        #[arg(trailing_var_arg = true)]
        args: Vec<String>,
    },
}

trailing_var_arg = true 确保用户的原始参数被完整透传给底层命令，Filter 只作用于输出。

第 3 步：写测试

# Create fixture
newcmd --args > tests/fixtures/newcmd_raw.txt

# Run tests
cargo test

Fixture 的来源约定是“真实命令输出”（模板表述为 production environments 的真实输出），include_str! 在编译期将其固化进测试二进制，使节省率断言不依赖运行环境。

第 4 步：记录 token 节省

更新 README，按统一表格格式登记：

| `rtk newcmd` | 75% | Condenses newcmd output |

第 5 步：质量门禁

cargo fmt --all && cargo clippy --all-targets && cargo test --all

模板最后给出五条 Filter Quality Standards，它们共同构成新 Filter 的验收清单：

• Token 节省：测试中验证 ≥60%；
• 启动时间：hyperfine 测量 <10ms；
• 惰性正则：固定且复用的模式必须使用 LazyLock<Regex>；
• 错误处理：失败时回退到原始命令输出（保证代理永不“吞掉”信息）；
• 跨平台：在 macOS 与 Linux 上测试。

其中“失败回退到原始命令”这一条与 src/discover/registry.rs 中 Classification::Unsupported（无匹配则透传）的设计一脉相承：RTK 的文档规范与代码架构共享同一条安全底线——宁可不过滤，也不得错误过滤。

八、职责边界与五条文档原则

规范用 Boundaries 一节划清了 technical-writer 与仓库内其他 Agent（如 rust-rtk、rtk-testing-specialist）的分工：

Will（会做）：

• 编写带可运行示例的完整 CLI 文档；
• 用证据（基准、fixture）记录性能声明；
• 编写带平台差异说明与排障的安装指南；
• 解释 Hook 集成与命令路由机制；
• 指导带测试模式的 Filter 开发。

Will Not（不做）：

• 不实现新 Filter 或生产代码（交给 rust-rtk agent）；
• 不替 Filter 设计做架构决策；
• 不写没有证据的营销内容。

文档原则（Documentation Principles）则被归纳为五条，可视为整套体系的浓缩：

1. Show, Don't Tell：包含带预期输出的可运行示例；
2. Evidence-Based：性能声明必须有基准/测试支撑；
3. Platform-Aware：macOS/Linux/Windows 差异必须写明；
4. Verification Steps：每个步骤都有“验证它生效”的动作；
5. Troubleshooting：预判常见问题并给出修复方案。

风格指南（Style Guide）进一步用正例固定了三种典型场景的写法标准：

# 命令示例：命令 + 预期输出
rtk git status

# Output:
M src/main.rs
A tests/new_test.rs

# 性能声明：数字 + fixture + 验证命令
Token savings: 80% (2,450 → 489 tokens)
Fixture: tests/fixtures/git_log_raw.txt
Verification: cargo test test_git_log_savings

# 安装步骤：安装 + 验证
cargo install --path .
rtk --version  # Verify shows rtk X.Y.Z