企业官网建设流程全解析

rtk git log

【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtk

Condensesgit logoutput 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://link.gitcode.com/i/53fb9c1295386421b66ae666f8b3dc24) 中的测试 `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），并约定了一套退出码协议：

脚本还会跳过 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

【免费下载链接】rtkCLI proxy that reduces LLM token consumption by 60-90% on common dev commands. Single Rust binary, zero dependencies项目地址: https://gitcode.com/GitHub_Trending/rtk4/rtk