尧图网页设计 
rtk 开源贡献指南设计哲学、过滤器选型与测试门禁的完整拆解【免费下载链接】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/rtkrtkRust Token Killer是一个运行在 LLM coding agent 与 CLI 之间的代理它在命令输出进入 LLM 上下文之前先做过滤和压缩将常见开发命令的 bash 输出削减 60-90%。这篇指南基于仓库根目录的 CONTRIBUTING.md 全文展开完整继承其中的设计哲学、贡献边界、过滤器选型依据、提交规范与测试门禁并结合src/下对应源码逐一印证每个约束背后的实现——读完你可以掌握如何为 rtk 新增一个合格的过滤器TOML 或 Rust 两种路线、如何写满足门禁要求的测试以及 PR 从分支命名到合入develop的完整流程。1. rtk 是什么贡献前必须建立的正确心智模型rtk 是一个 coding agent proxy核心目标是砍掉命令输出里的噪音。它过滤并压缩 CLI 输出后再交给 LLM 上下文在常见操作上可将 bash 输出减少 60-90%。愿景是消除不必要的 token 消耗让 AI 辅助开发更快、更便宜。贡献前有一个必须澄清的事实边界仓库中出现的每一个百分比度量的都是 bash 输出不是账单金额。这些字节只是输入 token 的一个组成部分而输入 token 又只是总成本的一部分账单还计输出 token。因此引用任何节省数字之前应先阅读 docs/guide/resources/savings-explained.md。从源码结构看这个近似而非精确的定位是刻意的src/core/tracking.rs 中的 token 估算采用tokens ceil(chars / 4)的启发式见该文件estimate_tokens函数的文档注释RTK 不内置真实 tokenizer所以比例可靠、绝对 token 数是近似值——这一点直接决定了下文测试门禁中20% 削减的验证方式。2. 五种贡献方式类型示例Report提交清晰的 issue复现步骤、期望行为 vs 实际行为Fix修 bug、修复损坏的过滤器Build新过滤器、新命令支持、新功能核心功能需先与维护者讨论Review评审开放中的 PR、本地验证改动、留下有建设性的反馈Document改进文档、消除歧义注意Build一栏的限定核心功能core features在动手前必须先与维护者讨论避免方向性返工。3. 设计哲学四条原则 可扩展性CONTRIBUTING.md 明确四条原则指导每一个 RTK 设计决策并附一条可扩展性补充。理解它们是写出天然契合项目的 PR 的前提。以下逐条展开并给出源码级的落地证据。3.1 Correctness VS Token Savingsflag-aware 过滤当用户或 LLM 通过 flags 显式要求详细输出例如git log --comments、cargo test -- --nocapture、ls -la时必须尊重这个意图——压缩掉显式请求的细节是本末倒置LLM 要它就是因为需要它。过滤器应当是flag-aware的默认输出无 flags激进压缩verbose/详细类 flags 则放行更多内容。拿不准时优先保正确性。文档给出的例子是rtk cargo test只显示失败约 90% 的 bash 输出被削减而rtk cargo test -- --nocapture保留全部输出因为用户显式要求了。源码中可以看到这条链路的真实形态src/cmds/rust/cargo_cmd.rs 的filter_cargo_test()是一个逐行状态机跳过Compiling/Downloading/Finished等编译噪音行、跳过running N tests与test ... ok行只收集failures:区段内的失败块与test result:汇总行——这就是只显示失败的实现。而--之后的参数在 Clap 解析中会被剥离cargo 子命令又需要它因此该文件提供了restore_double_dash()修复见 src/cmds/rust/README.md并有专门单测验证rtk cargo test -- --nocapture与rtk cargo test my_test -- --nocapture两种形态都能还原出[--, --nocapture]/[my_test, --, --nocapture]见 cargo_cmd.rs 测试段。从源码结构看flag-aware 意味着当你给某个过滤器新增详细模式时检测 verbose flags 并在该模式下降低压缩强度是 Rust 模块而非 TOML 过滤器才具备的能力——这也是下文 TOML vs Rust 选型表中的一行依据。3.2 Transparency输出必须是更短的真实命令输出LLM 并不知道哪些命令经过了 RTK——hooks 是静默重写命令的。因此 RTK 的输出必须是原始工具输出的有效、有用的子集而不是 LLM 意想不到的另一种格式如果 LLM 在解析git diff的输出RTK 过滤后的版本仍然必须长得像git diff的输出。两条硬约束不要发明新的输出格式不要在默认输出中加入 RTK 专属的头部或标记。过滤后的输出应当与一个更短版本的真实命令输出不可区分。src/filters/README.md 对 TOML 过滤器也重申了同一条规则TOML 过滤器剥离噪音行——它不重新格式化输出。透明性还有一条可机检的底线用guard::never_worse(raw, filtered)强制执行。它在语义上保证RTK 永远不会输出比原始命令更多的 token直至命令什么都没产生时什么都不输出。看它的实现逻辑极简src/core/guard.rs/// Returns filtered, or raw when filtered would emit more tokens. pub fn never_worsea(raw: a str, filtered: a str) - a str { if estimate_tokens(filtered) estimate_tokens(raw) { raw } else { filtered } }配套的单测覆盖了几条关键边界guard.rs 测试段filtered 更小则保留 filteredfiltered 反而更大则回退 raw平手tie保留 filteredraw 为空必须原样返回空保证命令没输出时什么都不输出。仓库中还有专门的 tests/guard_integration_test.rs 做集成验证。当你需要在输出后追加 tee 恢复提示hint时应使用runner::emit_guarded(filtered, hint, raw)而不是自己打印。看 src/core/runner.rs 的实现它把filtered与可选 hint 拼成完整正文后再过一遍never_worse打印并返回实际输出的内容让调用方 track 的正是被输出的那部分——提示行本身也计入 token 上限防止加了 hint 反而更长的漏洞。3.3 Never Block过滤失败回退 rawhooks 错误路径一律 exit 0过滤器失败时回退到原始输出。RTK 永远不应阻止命令执行或产生输出——宁可放行未过滤的输出也不要报错。hooks 同理所有错误路径都 exit 0让 agent 的命令原样运行。由此推出三条可执行的贡献规则每个过滤器都需要一条 fallback 路径每个 hook 都必须优雅处理畸形输入截断truncation也遵循同一规则把输出截断到 N 条只有在附带让 agent 能找回隐藏数据的提示时才可接受。最后一条在 src/cmds/README.md 中被细化为硬性约定永远不要在没有恢复路径的情况下显示… N more——agent 无从获取被隐藏的内容。具体选择哪种 hint 有明确的对照表内容类型函数适用条件扁平列表每条一行force_tee_tail_hint(content, slug, MAX 1)PR 列表、错误行、文件路径——每条都是单行字符串多行块force_tee_hint(content, slug)测试失败、构建错误块——条目跨多行行偏移没有意义截断的上限值统一来自 src/core/truncate.rs 的四个全局常量pub const CAP_ERRORS: usize 20; // 错误信号密度最高 pub const CAP_WARNINGS: usize 10; // 警告/测试失败 pub const CAP_LIST: usize 20; // 扁平列表PR、服务、包 pub const CAP_INVENTORY: usize 50; // 清单类pip list、docker images贡献约定为数据类别选一个CAP_*绑定到本地常量如const MAX_XXX: usize CAP_ERRORS;并由它派生take(MAX_XXX)、判断条件与偏移MAX_XXX 1。确需偏离时只能通过truncate::reduced(CAP_Y, n)truncate.rs 中的const fn欠安全、越界时回退到全量 cap0保持0并附一行注释说明原因——禁止裸字面量、禁止cap - ncap 变成运行时可配置后会下溢、禁止乘除。这条规则的价值在于未来 cap 成为配置项时所有截断只需拨一个开关而不是全库搜索。3.4 Zero Overhead 10ms 启动热路径零 I/O启动 10ms。无 async 运行时。关键路径上没有配置文件 I/O。文档的说法很直白如果开发者感知到任何延迟他们会禁用 RTK。速度是被采用与被抛弃的分界线。对应的工程约束所有正则使用LazyLock静态量惰性编译无网络调用热路径hot path无磁盘读取改动前后用hyperfine做基准对比。docs/contributing/TECHNICAL.md 把这些目标量化成了可验证的指标表启动 10mshyperfine rtk git status git status、常驻内存 5MB/usr/bin/time -v rtk git status、二进制 5MBstripped、每个过滤器 bash 输出削减 ≥ 20%快照 token 计数测试。达成手段是零 async 开销单线程无 tokio、LazyLock惰性正则、借用优先于克隆、启动时不读配置按需加载。3.5 Extensibility复用既有组件始终复用已存在的组件以避免重复可能时使用可扩展模块。文档特别强调如果你想提交新的核心功能这一点必须重点留意。对照 src/cmds/README.md 的边界规则可以具体化一个模块只有当它执行外部命令并过滤其输出时才属于src/cmds/服务于多个模块、不调用外部命令的基础设施属于src/core/跨生态路由如lint_cmd检测到 Python 项目后委托给ruff_cmd是组件内部事务。新生态目录的门槛是3 个及以上相关命令语言无关命令放system/。4. 什么属于 RTKIn Scope / Out of Scope 边界4.1 In Scope同时满足两个条件的命令才值得写过滤器产生文本输出通常 100 token且字节可以被压缩20% 以上而不丢失 LLM 所需的关键信息参见上文Correctness VS Token Savings。测试运行器vitest、pytest、cargo test、go testLinter 与类型检查器eslint、ruff、tsc、mypy构建工具cargo build、dotnet build、make、next buildVCS 操作git status/log/diff、gh pr/issue包管理器pnpm、pip、cargo install、brew文件操作ls、tree、grep、find、cat/head/tail有文本输出的基础设施工具docker、kubectl、terraform实现新过滤器/命令时必须对照上文设计哲学。4.2 Out of Scope交互式 TUIhtop、vim、less不兼容 batch 模式二进制输出图片、编译产物没有可过滤的文本琐碎命令不值得付出开销且可能丢失重要信息无文本输出的命令没有可压缩的内容其他与 RTK 这类 LLM 代理无关的功能。4.3 TOML 还是 Rust选型决策表这是贡献者最常踩的选型问题CONTRIBUTING.md 给出的判据是用TOML 过滤器当……用Rust 模块当……输出是结构可预测的纯文本行输出是结构化的JSON、NDJSON正则行过滤能削减 60% 的字节需要状态机解析如 pytest 的分阶段输出不需要注入 CLI flags需要注入 flags如--format json不做跨命令路由路由到其他命令lint → ruff/mypy例子brew、df、shellcheck、rsync、ping例子vitest、pytest、golangci-lint、gh两侧的权威指引分别位于 src/filters/README.mdTOML 过滤器与 src/cmds/README.mdRust 模块。从源码结构看Rust 模块存在的理由就是 TOML 做不到的四件事解析结构化输出、跨阶段状态机解析、注入 CLI flags、flag-aware 过滤检测--nocapture这类 verbose flags 并调整压缩策略——与 3.1 节的原则直接对应。4.4 新增过滤器的检查清单分步清单创建过滤器 → 注册 rewrite pattern → 在 main.rs 注册 → 写测试 → 更新文档以 src/cmds/README.md 的 Adding a New Command Filter 一节 为准。要点摘录Rust 模块路线在src/cmds/ecosystem/mycmd_cmd.rs创建模块filter_mycmd()写成纯函数str - String无副作用pub fn run(...) - Resulti32通过runner::run_filtered()委托执行骨架。解析结构化 stdoutJSON/NDJSON时用RunOptions::stdout_only()stderr 会污染解析过滤合并文本时用RunOptions::default()解析结构化输出的过滤器要加.tee(label)开启失败恢复。退出码由run_filtered()全自动处理。注册模块生态目录的mod.rs使用automod::dir!()目录里的.rs自动成为公开模块注意WIP/辅助文件也会被暴露只提交可用的命令模块在 src/main.rs 的Commands枚举加变体带#[arg(trailing_var_arg true, allow_hyphen_values true)]并加路由 match 臂。在 src/discover/rules.rs 添加 rewrite patternPATTERNS 与 RULES 数组在相同下标配对使 hooks 能自动重写命令。写测试真实 fixture、快照测试、≥20% 削减验证。更新文档生态 READMECHANGELOG.md 由 release-please 自动生成不要手改。TOML 过滤器路线在 src/filters/ 按命名规范新建cmd-subcommand.toml更新description、match_command与至少一个动作字段并添加[[tests.my-tool]]内联测试在src/discover/rules.rs添加 rewrite pattern跑cargo test——构建步骤会校验 TOML 语法并执行内联测试。TOML 过滤器的文件结构值得原样记住src/filters/README.md 中的格式说明[filters.my-tool] description Short description of what this filter does match_command ^my-tool\\b # 正则匹配完整命令字符串 strip_ansi true # 可选先剥离 ANSI 转义码 strip_lines_matching [ # 可选删除匹配任一则的行 ^\\s*$, ^noise pattern, ] max_lines 40 # 可选过滤后只保留前 N 行 on_empty my-tool: ok # 可选过滤后为空时的兜底消息 [[tests.my-tool]] name descriptive test name input raw command output here expected expected filtered output完整字段表包括description、match_command、strip_ansi、filter_stderr把 stderr 合并进 stdout 再过滤适用于 liquibase 这类向 stderr 打横幅的工具、strip_lines_matching、keep_lines_matching、replace正则替换对、match_output短路规则{ pattern, message }、truncate_lines_at、max_lines、tail_lines其他过滤之后保留最后 N 行、on_empty。构建链路上build.rs会按字母序把src/filters/*.toml拼成一个 TOML blob 编译进二进制cargo test同时断言内置过滤器数量、每个过滤器名字在册、以及每个过滤器都有内联测试——缺测试直接构建测试失败。运行时查找优先级为项目级.rtk/filters.toml→ 用户级~/.config/rtk/filters.toml→ 内置 BUILTIN_TOML → 原样透传passthrough首匹配生效项目过滤器同名遮蔽内置过滤器时会告警。5. 提交规范与 ChangelogRTK 使用 Conventional Commits 加 release-please 来自动生成 CHANGELOG.md、版本号提升与 release。绝不手改CHANGELOG.md——它完全由 release-please 从提交信息生成。这一点在仓库配置层面可以证实release-please-config.json 声明release-type: rust、包名rtk、bump-minor-pre-major: true、bump-patch-for-minor-pre-major: true与下表的 semver 影响完全一致。5.1 提交格式type(scope): short descriptionTypeSemver 影响使用场景featMinor新功能、新过滤器、新命令支持fixPatch修 bug、修正perfPatch性能改进refactor—代码重构不产生 changelog 条目docs—仅文档chore—维护、CI、依赖feat!/fix!Major破坏性变更type 后加!Scope应与模块或领域对应git、cargo、gh、hook、tracking、cicd等。5.2 示例feat(kubectl): add pod log filtering fix(git): preserve merge commit messages in log filter perf(cargo): lazy-compile clippy regex patterns feat!(hook): change rewrite config format这些提交信息会在 release-please 创建 release PR 时直接成为 CHANGELOG 条目——写它们时请当作会被用户阅读来写。6. 分支命名约定Git 分支名不能含空格和冒号所以采用斜杠前缀命名选与改动类型匹配的前缀后跟可选 scope 与 kebab-case 短描述。前缀使用场景fix/修 bug、修正、小调整feat/新功能、新过滤器、新命令支持chore/CI/CD、依赖、维护、破坏性变更scope 能增加清晰度时加上如git、kubectl、filter、tracking、config格式为fix/scope-description或feat/description。示例fix/git-log-filter-drops-merge-commits feat/kubectl-add-pod-list-filter chore/release-pipeline-cleanup7. PR 流程从分支到合入7.1 Scope 规则每个 PR 只聚焦一个功能、一个修复或一项改动。diff 必须与作者在 PR 标题和正文中描述的 scope 保持一致超出 scope 的内容无关重构、顺手修、格式化未触碰的文件必须拆到单独的 PR。大功能或大重构优先拆成多部分 PR 而非一个巨型 PR拆成逻辑上可独立评审、可独立合入的块例如feat(Part 1): 数据模型 测试feat(Part 2): CLI 命令 集成feat(Part 3): 文档更新为什么小而聚焦的 PR 更好评审、更安全的合入、更快的上线。大 PR 拖慢评审、藏 bug、放大合并冲突风险。7.2 流程步骤第 1 步创建分支git checkout develop git pull origin develop git checkout -b feat/scope-your-clear-description第 2 步做改动并遵守四条代码风格约定尊重现有目录结构。新文件放到同类文件所在处未经讨论不要重组目录函数保持短小聚焦。每个函数只做一件事——如果它需要注释来解释自己在干什么它大概就太长了拆掉它不要写显然型注释。不要注释代码已经说明的东西注释解释为什么why永远不解释是什么what以避免噪音大型命令文件是预期内的。命令模块*_cmd.rs把实现、测试、fixture 放在同一个文件里一个命令自包含的大文件没有问题未来会调整。第 3 步加测试——每个改动必须包含测试见第 9 节。第 4 步加文档——新过滤器、新功能、以及影响已记录行为的改动必须更新文档纯 bug 修复和重构通常不需要。CLA贡献者许可协议所有贡献合入前必须签署 CLA。签署即认证你 100% 原创该贡献或拥有提交所需权利你授予rtk-ai与rtk-ai Labs一份永久、全球、免版税的许可以使用你的贡献——包括用于rtk Pro等商业产品基于 Apache License 2.0如果你的雇主对作品有权利你已取得其许可。该流程是自动化的开 PR 时 CLA Assistant 会在 PR 下评论请求签署用 GitHub 账户点击链接一次即可。第 5 步合入develop——就绪后向develop分支开 PR。第 6 步评审——① 维护者评审代码质量与项目契合度② CI/CD 检查自动化测试与 lint必须通过③ 解决评审反馈或 CI 失败。第 7 步集成与发布——合入后你的改动在develop分支上与其他功能一起被集成测试。维护者满意develop的状态后会以特定版本发布到masteryour branch -- develop (review CI integration testing) -- version branch -- master (versioned release)8. 文档更新对照表新过滤器、新功能、影响已记录行为的改动都需要更新文档。按改了什么查该更新哪些文档你改了什么要更新哪些文档新 Rust 过滤器src/cmds/对应生态README.md如src/cmds/git/README.md、README.md 的命令列表新 TOML 过滤器src/filters/命名规范变化时更新 src/filters/README.md、README.md 命令列表新 rewrite patternsrc/discover/rules.rs——参见 src/cmds/README.md 的新过滤器清单核心基础设施src/core/src/core/README.md、流程变化时 docs/contributing/TECHNICAL.mdHook 系统src/hooks/src/hooks/README.md、面向 agent 的 hooks/README.md架构或设计变化docs/contributing/ARCHITECTURE.md、docs/contributing/TECHNICAL.md注意不要手改CHANGELOG.md——它由 release-please 从提交信息自动生成见第 5 节。文档写作风格要求简洁、实用——例子优先于解释。文档导航链是CONTRIBUTING.md总纲即本文基础→ docs/contributing/TECHNICAL.md架构 端到端流程→ 各目录的README.md实现细节。9. 测试TDD、四类测试与 PR 检查清单每个改动必须包含测试项目遵循TDD红-绿-重构先写失败测试写最小实现通过它再重构。9.1 四类测试类型位置运行方式单元测试每个模块内的#[cfg(test)] mod testscargo test快照测试过滤器模块的#[cfg(test)]中创建快照cargo test冒烟测试scripts/test-all.shbash scripts/test-all.sh集成测试需要已安装二进制的#[ignore]测试cargo test --ignored测试写法fixture 来自真实命令输出、同文件内#[cfg(test)]写测试、验证 ≥20% 削减的完整示例见 docs/contributing/TECHNICAL.md 的 Testing 一节。核心模式是从真实命令输出建立 fixture绝不用合成数据include_str!引入后断言内容正确性再用 token 估算验证削减比例——注意这个 20% 是用 RTK 自己的 token 估算器bytes/4启发式度量的不是真实 tokenizer作为比例可靠。9.2 提交前门禁强制三项必须全部通过才能开 PRcargo fmt --all --check cargo clippy --all-targets cargo test9.3 PR 测试检查清单为改动的代码新增/更新了单元测试过滤器有快照测试bash 输出削减 ≥20% 已验证用 RTK token 估算器度量非真实 tokenizer任何被截断的列表都带恢复提示force_tee_tail_hint或force_tee_hint且上限值取自 src/core/truncate.rs 的CAP_*边界情况已覆盖cargo fmt --all --check cargo clippy --all-targets cargo test全部通过手动测试运行rtk cmd并检查输出截断相关的两条检查项对应 3.3 节的 Never Block 原则被隐藏的数据必须可恢复且所有 cap 统一路由到全局常量未来可配置化时只需一处开关。10. 外部贡献者的安全审查外部贡献者的 PR 会经过自动化安全审查见 SECURITY.md。原因是 RTK 本质上是 shell 执行能力很强的代理hooks 拦截并改写命令、过滤器控制 agent 看到的输出、自定义过滤器文件可覆写内置行为——因此必须防御注入攻击与供应链风险。这与 3.3 节 hooks 所有错误路径 exit 0、以及自定义过滤器需rtk trust信任门槛src/filters/README.md的设计是一脉相承的RTK 对谁能影响命令与输出保持高度防御。结语把约束当接口回看 CONTRIBUTING.md 的全貌rtk 的贡献规范其实是一套可机器验证的设计约束正确性优先于节省flag-aware 过滤、透明never_worse守卫 不发明格式、不阻塞fallback tee 恢复提示、零开销LazyLock 热路径零 I/O。每一条评价标准背后都有对应源码可以查证——从 src/core/guard.rs 的 13 行守卫函数到 src/core/truncate.rs 的四个全局 cap再到 src/cmds/README.md 的执行骨架与跨模块行为契约。贡献 rtk 时把这些约束当作接口来对待写代码前先对照 In/Out Scope 与 TOML vs Rust 选型表写完用第 9 节的清单逐项自检就能让 PR 天然契合这个项目的评审口味。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 rtk 开源贡献指南：设计哲学、过滤器选型与测试门禁的完整拆解
rtk 开源贡献指南设计哲学、过滤器选型与测试门禁的完整拆解【免费下载链接】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/rtkrtkRust Token Killer是一个运行在 LLM coding agent 与 CLI 之间的代理它在命令输出进入 LLM 上下文之前先做过滤和压缩将常见开发命令的 bash 输出削减 60-90%。这篇指南基于仓库根目录的 CONTRIBUTING.md 全文展开完整继承其中的设计哲学、贡献边界、过滤器选型依据、提交规范与测试门禁并结合src/下对应源码逐一印证每个约束背后的实现——读完你可以掌握如何为 rtk 新增一个合格的过滤器TOML 或 Rust 两种路线、如何写满足门禁要求的测试以及 PR 从分支命名到合入develop的完整流程。1. rtk 是什么贡献前必须建立的正确心智模型rtk 是一个 coding agent proxy核心目标是砍掉命令输出里的噪音。它过滤并压缩 CLI 输出后再交给 LLM 上下文在常见操作上可将 bash 输出减少 60-90%。愿景是消除不必要的 token 消耗让 AI 辅助开发更快、更便宜。贡献前有一个必须澄清的事实边界仓库中出现的每一个百分比度量的都是 bash 输出不是账单金额。这些字节只是输入 token 的一个组成部分而输入 token 又只是总成本的一部分账单还计输出 token。因此引用任何节省数字之前应先阅读 docs/guide/resources/savings-explained.md。从源码结构看这个近似而非精确的定位是刻意的src/core/tracking.rs 中的 token 估算采用tokens ceil(chars / 4)的启发式见该文件estimate_tokens函数的文档注释RTK 不内置真实 tokenizer所以比例可靠、绝对 token 数是近似值——这一点直接决定了下文测试门禁中20% 削减的验证方式。2. 五种贡献方式类型示例Report提交清晰的 issue复现步骤、期望行为 vs 实际行为Fix修 bug、修复损坏的过滤器Build新过滤器、新命令支持、新功能核心功能需先与维护者讨论Review评审开放中的 PR、本地验证改动、留下有建设性的反馈Document改进文档、消除歧义注意Build一栏的限定核心功能core features在动手前必须先与维护者讨论避免方向性返工。3. 设计哲学四条原则 可扩展性CONTRIBUTING.md 明确四条原则指导每一个 RTK 设计决策并附一条可扩展性补充。理解它们是写出天然契合项目的 PR 的前提。以下逐条展开并给出源码级的落地证据。3.1 Correctness VS Token Savingsflag-aware 过滤当用户或 LLM 通过 flags 显式要求详细输出例如git log --comments、cargo test -- --nocapture、ls -la时必须尊重这个意图——压缩掉显式请求的细节是本末倒置LLM 要它就是因为需要它。过滤器应当是flag-aware的默认输出无 flags激进压缩verbose/详细类 flags 则放行更多内容。拿不准时优先保正确性。文档给出的例子是rtk cargo test只显示失败约 90% 的 bash 输出被削减而rtk cargo test -- --nocapture保留全部输出因为用户显式要求了。源码中可以看到这条链路的真实形态src/cmds/rust/cargo_cmd.rs 的filter_cargo_test()是一个逐行状态机跳过Compiling/Downloading/Finished等编译噪音行、跳过running N tests与test ... ok行只收集failures:区段内的失败块与test result:汇总行——这就是只显示失败的实现。而--之后的参数在 Clap 解析中会被剥离cargo 子命令又需要它因此该文件提供了restore_double_dash()修复见 src/cmds/rust/README.md并有专门单测验证rtk cargo test -- --nocapture与rtk cargo test my_test -- --nocapture两种形态都能还原出[--, --nocapture]/[my_test, --, --nocapture]见 cargo_cmd.rs 测试段。从源码结构看flag-aware 意味着当你给某个过滤器新增详细模式时检测 verbose flags 并在该模式下降低压缩强度是 Rust 模块而非 TOML 过滤器才具备的能力——这也是下文 TOML vs Rust 选型表中的一行依据。3.2 Transparency输出必须是更短的真实命令输出LLM 并不知道哪些命令经过了 RTK——hooks 是静默重写命令的。因此 RTK 的输出必须是原始工具输出的有效、有用的子集而不是 LLM 意想不到的另一种格式如果 LLM 在解析git diff的输出RTK 过滤后的版本仍然必须长得像git diff的输出。两条硬约束不要发明新的输出格式不要在默认输出中加入 RTK 专属的头部或标记。过滤后的输出应当与一个更短版本的真实命令输出不可区分。src/filters/README.md 对 TOML 过滤器也重申了同一条规则TOML 过滤器剥离噪音行——它不重新格式化输出。透明性还有一条可机检的底线用guard::never_worse(raw, filtered)强制执行。它在语义上保证RTK 永远不会输出比原始命令更多的 token直至命令什么都没产生时什么都不输出。看它的实现逻辑极简src/core/guard.rs/// Returns filtered, or raw when filtered would emit more tokens. pub fn never_worsea(raw: a str, filtered: a str) - a str { if estimate_tokens(filtered) estimate_tokens(raw) { raw } else { filtered } }配套的单测覆盖了几条关键边界guard.rs 测试段filtered 更小则保留 filteredfiltered 反而更大则回退 raw平手tie保留 filteredraw 为空必须原样返回空保证命令没输出时什么都不输出。仓库中还有专门的 tests/guard_integration_test.rs 做集成验证。当你需要在输出后追加 tee 恢复提示hint时应使用runner::emit_guarded(filtered, hint, raw)而不是自己打印。看 src/core/runner.rs 的实现它把filtered与可选 hint 拼成完整正文后再过一遍never_worse打印并返回实际输出的内容让调用方 track 的正是被输出的那部分——提示行本身也计入 token 上限防止加了 hint 反而更长的漏洞。3.3 Never Block过滤失败回退 rawhooks 错误路径一律 exit 0过滤器失败时回退到原始输出。RTK 永远不应阻止命令执行或产生输出——宁可放行未过滤的输出也不要报错。hooks 同理所有错误路径都 exit 0让 agent 的命令原样运行。由此推出三条可执行的贡献规则每个过滤器都需要一条 fallback 路径每个 hook 都必须优雅处理畸形输入截断truncation也遵循同一规则把输出截断到 N 条只有在附带让 agent 能找回隐藏数据的提示时才可接受。最后一条在 src/cmds/README.md 中被细化为硬性约定永远不要在没有恢复路径的情况下显示… N more——agent 无从获取被隐藏的内容。具体选择哪种 hint 有明确的对照表内容类型函数适用条件扁平列表每条一行force_tee_tail_hint(content, slug, MAX 1)PR 列表、错误行、文件路径——每条都是单行字符串多行块force_tee_hint(content, slug)测试失败、构建错误块——条目跨多行行偏移没有意义截断的上限值统一来自 src/core/truncate.rs 的四个全局常量pub const CAP_ERRORS: usize 20; // 错误信号密度最高 pub const CAP_WARNINGS: usize 10; // 警告/测试失败 pub const CAP_LIST: usize 20; // 扁平列表PR、服务、包 pub const CAP_INVENTORY: usize 50; // 清单类pip list、docker images贡献约定为数据类别选一个CAP_*绑定到本地常量如const MAX_XXX: usize CAP_ERRORS;并由它派生take(MAX_XXX)、判断条件与偏移MAX_XXX 1。确需偏离时只能通过truncate::reduced(CAP_Y, n)truncate.rs 中的const fn欠安全、越界时回退到全量 cap0保持0并附一行注释说明原因——禁止裸字面量、禁止cap - ncap 变成运行时可配置后会下溢、禁止乘除。这条规则的价值在于未来 cap 成为配置项时所有截断只需拨一个开关而不是全库搜索。3.4 Zero Overhead 10ms 启动热路径零 I/O启动 10ms。无 async 运行时。关键路径上没有配置文件 I/O。文档的说法很直白如果开发者感知到任何延迟他们会禁用 RTK。速度是被采用与被抛弃的分界线。对应的工程约束所有正则使用LazyLock静态量惰性编译无网络调用热路径hot path无磁盘读取改动前后用hyperfine做基准对比。docs/contributing/TECHNICAL.md 把这些目标量化成了可验证的指标表启动 10mshyperfine rtk git status git status、常驻内存 5MB/usr/bin/time -v rtk git status、二进制 5MBstripped、每个过滤器 bash 输出削减 ≥ 20%快照 token 计数测试。达成手段是零 async 开销单线程无 tokio、LazyLock惰性正则、借用优先于克隆、启动时不读配置按需加载。3.5 Extensibility复用既有组件始终复用已存在的组件以避免重复可能时使用可扩展模块。文档特别强调如果你想提交新的核心功能这一点必须重点留意。对照 src/cmds/README.md 的边界规则可以具体化一个模块只有当它执行外部命令并过滤其输出时才属于src/cmds/服务于多个模块、不调用外部命令的基础设施属于src/core/跨生态路由如lint_cmd检测到 Python 项目后委托给ruff_cmd是组件内部事务。新生态目录的门槛是3 个及以上相关命令语言无关命令放system/。4. 什么属于 RTKIn Scope / Out of Scope 边界4.1 In Scope同时满足两个条件的命令才值得写过滤器产生文本输出通常 100 token且字节可以被压缩20% 以上而不丢失 LLM 所需的关键信息参见上文Correctness VS Token Savings。测试运行器vitest、pytest、cargo test、go testLinter 与类型检查器eslint、ruff、tsc、mypy构建工具cargo build、dotnet build、make、next buildVCS 操作git status/log/diff、gh pr/issue包管理器pnpm、pip、cargo install、brew文件操作ls、tree、grep、find、cat/head/tail有文本输出的基础设施工具docker、kubectl、terraform实现新过滤器/命令时必须对照上文设计哲学。4.2 Out of Scope交互式 TUIhtop、vim、less不兼容 batch 模式二进制输出图片、编译产物没有可过滤的文本琐碎命令不值得付出开销且可能丢失重要信息无文本输出的命令没有可压缩的内容其他与 RTK 这类 LLM 代理无关的功能。4.3 TOML 还是 Rust选型决策表这是贡献者最常踩的选型问题CONTRIBUTING.md 给出的判据是用TOML 过滤器当……用Rust 模块当……输出是结构可预测的纯文本行输出是结构化的JSON、NDJSON正则行过滤能削减 60% 的字节需要状态机解析如 pytest 的分阶段输出不需要注入 CLI flags需要注入 flags如--format json不做跨命令路由路由到其他命令lint → ruff/mypy例子brew、df、shellcheck、rsync、ping例子vitest、pytest、golangci-lint、gh两侧的权威指引分别位于 src/filters/README.mdTOML 过滤器与 src/cmds/README.mdRust 模块。从源码结构看Rust 模块存在的理由就是 TOML 做不到的四件事解析结构化输出、跨阶段状态机解析、注入 CLI flags、flag-aware 过滤检测--nocapture这类 verbose flags 并调整压缩策略——与 3.1 节的原则直接对应。4.4 新增过滤器的检查清单分步清单创建过滤器 → 注册 rewrite pattern → 在 main.rs 注册 → 写测试 → 更新文档以 src/cmds/README.md 的 Adding a New Command Filter 一节 为准。要点摘录Rust 模块路线在src/cmds/ecosystem/mycmd_cmd.rs创建模块filter_mycmd()写成纯函数str - String无副作用pub fn run(...) - Resulti32通过runner::run_filtered()委托执行骨架。解析结构化 stdoutJSON/NDJSON时用RunOptions::stdout_only()stderr 会污染解析过滤合并文本时用RunOptions::default()解析结构化输出的过滤器要加.tee(label)开启失败恢复。退出码由run_filtered()全自动处理。注册模块生态目录的mod.rs使用automod::dir!()目录里的.rs自动成为公开模块注意WIP/辅助文件也会被暴露只提交可用的命令模块在 src/main.rs 的Commands枚举加变体带#[arg(trailing_var_arg true, allow_hyphen_values true)]并加路由 match 臂。在 src/discover/rules.rs 添加 rewrite patternPATTERNS 与 RULES 数组在相同下标配对使 hooks 能自动重写命令。写测试真实 fixture、快照测试、≥20% 削减验证。更新文档生态 READMECHANGELOG.md 由 release-please 自动生成不要手改。TOML 过滤器路线在 src/filters/ 按命名规范新建cmd-subcommand.toml更新description、match_command与至少一个动作字段并添加[[tests.my-tool]]内联测试在src/discover/rules.rs添加 rewrite pattern跑cargo test——构建步骤会校验 TOML 语法并执行内联测试。TOML 过滤器的文件结构值得原样记住src/filters/README.md 中的格式说明[filters.my-tool] description Short description of what this filter does match_command ^my-tool\\b # 正则匹配完整命令字符串 strip_ansi true # 可选先剥离 ANSI 转义码 strip_lines_matching [ # 可选删除匹配任一则的行 ^\\s*$, ^noise pattern, ] max_lines 40 # 可选过滤后只保留前 N 行 on_empty my-tool: ok # 可选过滤后为空时的兜底消息 [[tests.my-tool]] name descriptive test name input raw command output here expected expected filtered output完整字段表包括description、match_command、strip_ansi、filter_stderr把 stderr 合并进 stdout 再过滤适用于 liquibase 这类向 stderr 打横幅的工具、strip_lines_matching、keep_lines_matching、replace正则替换对、match_output短路规则{ pattern, message }、truncate_lines_at、max_lines、tail_lines其他过滤之后保留最后 N 行、on_empty。构建链路上build.rs会按字母序把src/filters/*.toml拼成一个 TOML blob 编译进二进制cargo test同时断言内置过滤器数量、每个过滤器名字在册、以及每个过滤器都有内联测试——缺测试直接构建测试失败。运行时查找优先级为项目级.rtk/filters.toml→ 用户级~/.config/rtk/filters.toml→ 内置 BUILTIN_TOML → 原样透传passthrough首匹配生效项目过滤器同名遮蔽内置过滤器时会告警。5. 提交规范与 ChangelogRTK 使用 Conventional Commits 加 release-please 来自动生成 CHANGELOG.md、版本号提升与 release。绝不手改CHANGELOG.md——它完全由 release-please 从提交信息生成。这一点在仓库配置层面可以证实release-please-config.json 声明release-type: rust、包名rtk、bump-minor-pre-major: true、bump-patch-for-minor-pre-major: true与下表的 semver 影响完全一致。5.1 提交格式type(scope): short descriptionTypeSemver 影响使用场景featMinor新功能、新过滤器、新命令支持fixPatch修 bug、修正perfPatch性能改进refactor—代码重构不产生 changelog 条目docs—仅文档chore—维护、CI、依赖feat!/fix!Major破坏性变更type 后加!Scope应与模块或领域对应git、cargo、gh、hook、tracking、cicd等。5.2 示例feat(kubectl): add pod log filtering fix(git): preserve merge commit messages in log filter perf(cargo): lazy-compile clippy regex patterns feat!(hook): change rewrite config format这些提交信息会在 release-please 创建 release PR 时直接成为 CHANGELOG 条目——写它们时请当作会被用户阅读来写。6. 分支命名约定Git 分支名不能含空格和冒号所以采用斜杠前缀命名选与改动类型匹配的前缀后跟可选 scope 与 kebab-case 短描述。前缀使用场景fix/修 bug、修正、小调整feat/新功能、新过滤器、新命令支持chore/CI/CD、依赖、维护、破坏性变更scope 能增加清晰度时加上如git、kubectl、filter、tracking、config格式为fix/scope-description或feat/description。示例fix/git-log-filter-drops-merge-commits feat/kubectl-add-pod-list-filter chore/release-pipeline-cleanup7. PR 流程从分支到合入7.1 Scope 规则每个 PR 只聚焦一个功能、一个修复或一项改动。diff 必须与作者在 PR 标题和正文中描述的 scope 保持一致超出 scope 的内容无关重构、顺手修、格式化未触碰的文件必须拆到单独的 PR。大功能或大重构优先拆成多部分 PR 而非一个巨型 PR拆成逻辑上可独立评审、可独立合入的块例如feat(Part 1): 数据模型 测试feat(Part 2): CLI 命令 集成feat(Part 3): 文档更新为什么小而聚焦的 PR 更好评审、更安全的合入、更快的上线。大 PR 拖慢评审、藏 bug、放大合并冲突风险。7.2 流程步骤第 1 步创建分支git checkout develop git pull origin develop git checkout -b feat/scope-your-clear-description第 2 步做改动并遵守四条代码风格约定尊重现有目录结构。新文件放到同类文件所在处未经讨论不要重组目录函数保持短小聚焦。每个函数只做一件事——如果它需要注释来解释自己在干什么它大概就太长了拆掉它不要写显然型注释。不要注释代码已经说明的东西注释解释为什么why永远不解释是什么what以避免噪音大型命令文件是预期内的。命令模块*_cmd.rs把实现、测试、fixture 放在同一个文件里一个命令自包含的大文件没有问题未来会调整。第 3 步加测试——每个改动必须包含测试见第 9 节。第 4 步加文档——新过滤器、新功能、以及影响已记录行为的改动必须更新文档纯 bug 修复和重构通常不需要。CLA贡献者许可协议所有贡献合入前必须签署 CLA。签署即认证你 100% 原创该贡献或拥有提交所需权利你授予rtk-ai与rtk-ai Labs一份永久、全球、免版税的许可以使用你的贡献——包括用于rtk Pro等商业产品基于 Apache License 2.0如果你的雇主对作品有权利你已取得其许可。该流程是自动化的开 PR 时 CLA Assistant 会在 PR 下评论请求签署用 GitHub 账户点击链接一次即可。第 5 步合入develop——就绪后向develop分支开 PR。第 6 步评审——① 维护者评审代码质量与项目契合度② CI/CD 检查自动化测试与 lint必须通过③ 解决评审反馈或 CI 失败。第 7 步集成与发布——合入后你的改动在develop分支上与其他功能一起被集成测试。维护者满意develop的状态后会以特定版本发布到masteryour branch -- develop (review CI integration testing) -- version branch -- master (versioned release)8. 文档更新对照表新过滤器、新功能、影响已记录行为的改动都需要更新文档。按改了什么查该更新哪些文档你改了什么要更新哪些文档新 Rust 过滤器src/cmds/对应生态README.md如src/cmds/git/README.md、README.md 的命令列表新 TOML 过滤器src/filters/命名规范变化时更新 src/filters/README.md、README.md 命令列表新 rewrite patternsrc/discover/rules.rs——参见 src/cmds/README.md 的新过滤器清单核心基础设施src/core/src/core/README.md、流程变化时 docs/contributing/TECHNICAL.mdHook 系统src/hooks/src/hooks/README.md、面向 agent 的 hooks/README.md架构或设计变化docs/contributing/ARCHITECTURE.md、docs/contributing/TECHNICAL.md注意不要手改CHANGELOG.md——它由 release-please 从提交信息自动生成见第 5 节。文档写作风格要求简洁、实用——例子优先于解释。文档导航链是CONTRIBUTING.md总纲即本文基础→ docs/contributing/TECHNICAL.md架构 端到端流程→ 各目录的README.md实现细节。9. 测试TDD、四类测试与 PR 检查清单每个改动必须包含测试项目遵循TDD红-绿-重构先写失败测试写最小实现通过它再重构。9.1 四类测试类型位置运行方式单元测试每个模块内的#[cfg(test)] mod testscargo test快照测试过滤器模块的#[cfg(test)]中创建快照cargo test冒烟测试scripts/test-all.shbash scripts/test-all.sh集成测试需要已安装二进制的#[ignore]测试cargo test --ignored测试写法fixture 来自真实命令输出、同文件内#[cfg(test)]写测试、验证 ≥20% 削减的完整示例见 docs/contributing/TECHNICAL.md 的 Testing 一节。核心模式是从真实命令输出建立 fixture绝不用合成数据include_str!引入后断言内容正确性再用 token 估算验证削减比例——注意这个 20% 是用 RTK 自己的 token 估算器bytes/4启发式度量的不是真实 tokenizer作为比例可靠。9.2 提交前门禁强制三项必须全部通过才能开 PRcargo fmt --all --check cargo clippy --all-targets cargo test9.3 PR 测试检查清单为改动的代码新增/更新了单元测试过滤器有快照测试bash 输出削减 ≥20% 已验证用 RTK token 估算器度量非真实 tokenizer任何被截断的列表都带恢复提示force_tee_tail_hint或force_tee_hint且上限值取自 src/core/truncate.rs 的CAP_*边界情况已覆盖cargo fmt --all --check cargo clippy --all-targets cargo test全部通过手动测试运行rtk cmd并检查输出截断相关的两条检查项对应 3.3 节的 Never Block 原则被隐藏的数据必须可恢复且所有 cap 统一路由到全局常量未来可配置化时只需一处开关。10. 外部贡献者的安全审查外部贡献者的 PR 会经过自动化安全审查见 SECURITY.md。原因是 RTK 本质上是 shell 执行能力很强的代理hooks 拦截并改写命令、过滤器控制 agent 看到的输出、自定义过滤器文件可覆写内置行为——因此必须防御注入攻击与供应链风险。这与 3.3 节 hooks 所有错误路径 exit 0、以及自定义过滤器需rtk trust信任门槛src/filters/README.md的设计是一脉相承的RTK 对谁能影响命令与输出保持高度防御。结语把约束当接口回看 CONTRIBUTING.md 的全貌rtk 的贡献规范其实是一套可机器验证的设计约束正确性优先于节省flag-aware 过滤、透明never_worse守卫 不发明格式、不阻塞fallback tee 恢复提示、零开销LazyLock 热路径零 I/O。每一条评价标准背后都有对应源码可以查证——从 src/core/guard.rs 的 13 行守卫函数到 src/core/truncate.rs 的四个全局 cap再到 src/cmds/README.md 的执行骨架与跨模块行为契约。贡献 rtk 时把这些约束当作接口来对待写代码前先对照 In/Out Scope 与 TOML vs Rust 选型表写完用第 9 节的清单逐项自检就能让 PR 天然契合这个项目的评审口味。【免费下载链接】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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考