rtk

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

rtk

rtk <wrapper> <command>

runs the real command and filters its output before it reaches your context. The captain's standing instruction (

~/AGENTS.md

, wrapper list in

~/RTK.md

) tells every agent on this box to prefer rtk for large or noisy output. There is no automatic command hook in jcode, so reaching for the rtk form is a manual choice you make each time.

Every wrapper passes the underlying command's real exit status through, so branch on

$?

, not on the filtered text.

rtk <wrapper> <command>

会执行实际命令，并在输出传入上下文之前对其进行过滤。主机预设规则（

~/AGENTS.md

，封装器列表位于

~/RTK.md

）要求本机所有Agent在处理输出量大或冗余的命令时优先使用rtk。 jcode中没有自动命令钩子，因此每次都需要手动选择是否使用rtk形式。

每个封装器都会传递底层命令的真实退出状态，因此请根据

$?

进行分支判断，而非过滤后的文本。

When to reach for it

适用场景

Wrap when the output is big, repetitive, and you only want the exceptions:

Test suites, builds, type checks, linters: you want failures, not thousands of passing lines.
Repository-wide search, directory walks, log files, long
```
git log
```
/
```
git diff
```
.
```
gh
```
list and view output, which is verbose JSON-ish prose by default.

Do NOT wrap:

Interactive commands, anything that prompts or needs a TTY.
Output you need verbatim: a file you are about to edit by exact bytes, a config you will copy, a hash or version string, a diff you will apply.
Short commands. Filtering a 5-line output saves nothing and adds a process.
The one failing case you are already debugging. Once you know a specific test or error matters, run it raw and read all of it; a filter that drops the one line you needed is worse than the raw dump.

rtk proxy <cmd>

is the escape hatch: runs the command raw, still counts it in the savings stats.

rtk run <cmd>

runs raw via

sh -c

with no filtering and no tracking.

当输出内容庞大、重复，且你只关注异常情况时，使用封装：

测试套件、构建、类型检查、代码检查工具：你只需要查看失败信息，而非成千上万条通过的记录。
仓库全局搜索、目录遍历、日志文件、冗长的
```
git log
```
/
```
git diff
```
输出。
```
gh
```
列表与查看输出，默认情况下是冗长类JSON格式的文本。

请勿封装以下命令：

交互式命令、任何需要提示或TTY的操作。
需要完整原始输出的内容：你即将按字节编辑的文件、要复制的配置、哈希或版本字符串、要应用的diff。
短命令。过滤5行输出毫无意义，反而会多启动一个进程。
你正在调试的单个失败案例。一旦确定某个特定测试或错误需要关注，直接运行原始命令并查看全部内容；如果过滤器恰好过滤掉了你需要的那一行，反而比原始输出更糟。

rtk proxy <cmd>

是逃生舱：执行原始命令，但仍会统计Token节省情况。

rtk run <cmd>

通过

sh -c

执行原始命令，不进行过滤也不追踪统计。

Workflows

工作流示例

Run a test suite and see only failures, then re-run the failing case raw:

bash

rtk test cargo test          # only failures, exit status preserved
cargo test some_failing_test -- --nocapture   # raw, once you know what to look at

Compile or lint and keep only errors and warnings:

bash

rtk err cargo check --message-format short

运行测试套件仅查看失败信息，然后重新运行失败案例的原始输出：

bash

rtk test cargo test          # 仅显示失败信息，保留退出状态
cargo test some_failing_test -- --nocapture   # 查看原始输出，当你明确关注目标后

编译或代码检查仅保留错误与警告：

bash

rtk err cargo check --message-format short

[ok] Command completed successfully (no errors) when clean

[ok] Command completed successfully (no errors) 当无问题时显示


Orient in an unfamiliar repository without dumping the tree:

```bash
rtk find src -name "*.rs"    # compact grouped tree, not one path per line
rtk read Cargo.toml          # filtered read
rtk grep -r "fn main" src    # grouped by file, whitespace stripped

Review repository state before committing:

bash

rtk git status               # branch plus "clean - nothing to commit"
rtk git log --oneline -5
rtk git diff HEAD~1 --stat   # condensed change summary

rtk diff

is a wrapper around the

diff(1)

binary and expects two paths; for repository changes use

rtk git diff

Filter output you already have, without re-running the command:

bash

git log --oneline -20 | rtk pipe

Check whether the wrapping is actually paying for itself:

bash

rtk gain                     # totals plus per-command savings table
rtk gain --history           # recent command history


在不熟悉的仓库中快速了解结构，无需输出完整目录树：

```bash
rtk find src -name "*.rs"    # 紧凑分组的目录树，而非每行一个路径
rtk read Cargo.toml          # 过滤后的内容展示
rtk grep -r "fn main" src    # 按文件分组，去除空白字符

提交前检查仓库状态：

bash

rtk git status               # 分支信息 + "clean - nothing to commit"
rtk git log --oneline -5
rtk git diff HEAD~1 --stat   # 精简的变更摘要

rtk diff

是

diff(1)

二进制文件的封装器，需要传入两个路径；若要查看仓库变更，请使用

rtk git diff

。

过滤已有的输出，无需重新运行命令：

bash

git log --oneline -20 | rtk pipe

检查封装是否真正起到了作用：

bash

rtk gain                     # 总节省量及按命令分类的节省统计表
rtk gain --history           # 近期命令历史记录

Fleet conventions

集群规范

Heavy runs go through
```
fm-heavy-run.sh
```
and rtk goes INSIDE it, not around it:
```
fm-heavy-run.sh --task <id> -- rtk test <runner>
```
. The helper returns the command's real exit status; act on that.
```
~/RTK.md
```
is the canonical wrapper list for this box. This skill is the judgment layer on top of it; when the two disagree,
```
~/RTK.md
```
wins on which wrappers exist and this skill wins on when to use them.
Wrapper coverage is not uniform.
```
rtk grep
```
needs
```
-r
```
for a directory (bare
```
rtk grep <pat> <dir>
```
hits the native
```
grep: is a directory
```
error),
```
rtk rg
```
needs
```
ripgrep
```
installed, and
```
rtk tree
```
needs
```
tree
```
installed. When a wrapper is missing its backing binary it says so and does nothing; fall back to the raw command rather than concluding there were no results.
An empty filtered result is ambiguous by design. Before reporting "nothing found", re-run the underlying command raw once to distinguish "no matches" from "filtered away".
Verify presence with
```
rtk --version
```
(installed at
```
/usr/local/bin/rtk
```
). Absent means run commands raw, not fail the task.
This repository is a fork. Open pull requests against
```
yjuyjuy/rtk
```
with base
```
develop
```
, never against the
```
rtk-ai/rtk
```
upstream.

重型任务通过
```
fm-heavy-run.sh
```
执行，rtk需在该脚本内部使用，而非外部：
```
fm-heavy-run.sh --task <id> -- rtk test <runner>
```
。该辅助脚本会返回命令的真实退出状态，请据此进行操作。
```
~/RTK.md
```
是本机的标准封装器列表。本技能是基于该列表的判断层；若两者出现分歧，
```
~/RTK.md
```
决定哪些封装器存在，而本技能决定何时使用它们。
封装器的覆盖范围并不统一。
```
rtk grep
```
需要
```
-r
```
参数才能遍历目录（直接使用
```
rtk grep <pat> <dir>
```
会触发原生
```
grep: is a directory
```
错误），
```
rtk rg
```
需要安装
```
ripgrep
```
，
```
rtk tree
```
需要安装
```
tree
```
。当封装器缺少对应的底层二进制文件时，会给出提示且不执行任何操作；此时请改用原始命令，而非认为没有结果。
过滤后结果为空是设计上的模糊情况。在报告“未找到内容”之前，请重新运行一次底层原始命令，以区分“无匹配结果”和“被过滤掉”两种情况。
使用
```
rtk --version
```
验证是否安装（安装路径为
```
/usr/local/bin/rtk
```
）。若未安装，则直接运行原始命令，无需终止任务。
本仓库是一个分支。请向
```
yjuyjuy/rtk
```
仓库的
```
develop
```
分支提交PR，切勿提交至
```
rtk-ai/rtk
```
上游仓库。

Non-goals

非目标

rtk filtering is lossy by design. It drops lines it judges uninteresting, and it can drop the line you needed. It is a context-budget tool, not a faithful transport. Any conclusion that depends on complete output must be drawn from a raw run.
Not a replacement for reading a file you are about to edit. Use the normal read path for exact content.
Not a test runner, build system, or search engine. It is a wrapper: the underlying tool must already be installed and correct on its own.
Not a substitute for
```
--help
```
. This skill covers only the judgment calls; flags and usage come from
```
rtk <command> --help
```
.
Not for output another program consumes. Filtered text is for human and agent eyes, never a pipeline that parses a fixed format.

rtk过滤本质上是有损的。它会丢弃被判定为无意义的行，也可能会丢弃你需要的内容。它是一个上下文预算工具，而非忠实的传输工具。任何依赖完整输出的结论都必须基于原始运行结果。
不能替代查看你即将编辑的文件。如需精确内容，请使用常规读取方式。
不是测试运行器、构建系统或搜索引擎。它只是一个封装器：底层工具必须已安装且本身功能正常。
不能替代
```
--help
```
。本技能仅涵盖判断逻辑；参数与用法请查看
```
rtk <command> --help
```
。
不适用于供其他程序消费的输出。过滤后的文本仅面向人类和Agent查看，绝不能用于依赖固定格式解析的管道流程。