RTK 的 Git/VCS 命令过滤模块：让 git、gh、glab 与 diff 输出对 LLM 友好

RTK 的 Git/VCS 命令过滤模块：让 git、gh、glab 与 diff 输出对 LLM 友好

【免费下载链接】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

本文以 RTK 仓库中src/cmds/git/模块的模块说明文档为主线，拆解该模块如何把git、gh（GitHub CLI）、glab（GitLab CLI）以及独立diff的高噪声输出压缩成 LLM 可消费的紧凑形式：包括原生 git 参数如何原样透传、git status/git log/git diff的默认压缩策略、退出码如何在 CI/CD 管道中正确传播，以及 gh 与 glab 在 JSON 模式上的差异处理。读完本文，你可以掌握该模块的过滤链路（参数透传 → 捕获 → 压缩 →never_worse兜底 → 退出码回传），并能依据源码定位每个压缩行为的具体实现。

模块构成与职责划分

src/cmds/git/目录由五个 Rust 源文件组成，每个文件对应一类命令族（见 模块文档 与 src/cmds/git/mod.rs）：

git.rs 中的GitCommand枚举定义了被过滤的子命令集合：

pub enum GitCommand { Diff, Log, Status, Show, Add, Commit, Checkout, Push, Pull, Branch, Fetch, Stash { subcommand: Option<String> }, Worktree, }

未被枚举覆盖的任意 git 子命令走run_passthrough（git.rs#L2236-L2257）：直接以std::process::Command::status()执行原生 git，不捕获输出，仅记录跟踪指标。

模块文档还明确了三处跨命令共享关系（README “Cross-command” 一节）：

• gh_cmd.rs从git.rs导入compact_diff()复用 diff 压缩；markdown 助手（filter_markdown_body、filter_markdown_segment）定义在gh_cmd.rs自身；
• glab_cmd.rs同样复用git.rs的compact_diff()处理mr diff，其filter_markdown_body目前是从gh_cmd.rs复制而来（模块文档注明“shared-module refactor deferred”，即共享模块重构被推迟）；
• diff_cmd.rs是一个独立实现，不依赖git diff。

参数透传：trailing_var_arg + allow_hyphen_values

模块文档的第一条要点是：git 子命令在 src/main.rs 的 clap 定义中统一使用#[arg(trailing_var_arg = true, allow_hyphen_values = true)]。全仓库搜索可确认这一属性被 git 的所有子命令变体一致声明（如 main.rs#L93 等处大量出现）。这两个属性的组合解决了一个典型问题：clap 默认会把--oneline、--cached、-sb这类以连字符开头的 token 当作自己的选项解析而报错。allow_hyphen_values允许带连字符的值进入参数列表，trailing_var_arg则把子命令之后的所有 token 原封不动地塞进一个变长参数，交给过滤层自行解释。

这里有一个 clap 的陷阱：--分隔符会被trailing_var_arg吃掉。RTK 用 src/core/args_utils.rs 中的restore_double_dash()在运行前把丢失的--重新插回。git.rs 中两处调用并标注了对应 issue：

// Re-insert `--` when clap's trailing_var_arg consumed it (issue #1215) let args = &args_utils::restore_double_dash(args);

git log路径的注释更具体地说明了后果：不恢复--的话，rtk git log -- -p中的-p会被误判为 patch 开关，而实际上它只是名为-p的 pathspec。

全局 git 选项（-C、--git-dir、--work-tree、--no-pager）则在子命令之前前置拼接，见 git.rs#L38-L44：

fn git_cmd(global_args: &[String]) -> Command { let mut cmd = resolved_command("git"); for arg in global_args { cmd.arg(arg); } cmd }

模块文档还提到一个 locale 细节：内部解析依赖 git 英文措辞的命令（例如从状态输出中识别 rebase/merge 状态行）使用LC_ALL=C变体git_cmd_c_locale()（git.rs#L51-L55），而用户可见的输出仍保留其本地 locale。

git status：porcelain 紧凑路径与状态保真

模块文档说明：默认git status使用--porcelain -b，保证紧凑输出永远不超过原生git status的体量（一个未跟踪目录会折叠为单行，与 git 默认行为一致）；只有“分支/短格式”类参数复用紧凑路径，其他显式参数则原样透传。

实现上，uses_compact_status_path 判定哪些参数允许走紧凑路径：

fn uses_compact_status_path(args: &[String]) -> bool { if args.is_empty() { return true; } let mut saw_branch = false; for arg in args { match arg.as_str() { "-b" | "--branch" => saw_branch = true, "-sb" | "-bs" => return true, "-s" | "--short" => {} _ => return false, } } saw_branch }

即：无参数、或仅带-b/--branch/-sb/-bs/-s/--short组合时，build_status_command 注入--porcelain -b；任何其它显式参数则整组原样传给 git。

紧凑路径（run_status）随后做三件保真工作：

1. porcelain 格式化：format_status_inner 把## branch...首行渲染为* branch，空仓库输出Clean working tree，干净状态追加clean — nothing to commit；
2. detached HEAD 还原：porcelain-b会把 detached HEAD 折叠成晦涩的## HEAD (no branch)，RTK 从已捕获的 plain 输出中提取HEAD detached at <ref>行（extract_detached_head），用真实 ref 覆盖显示；
3. 进行中状态不丢失：--porcelain会省略 rebase/merge/cherry-pick/bisect/am/sparse-checkout 的状态头。源码注释明确说“Hiding that block is a correctness bug”——交互式 rebase 编辑期间用户会误以为工作区干净。extract_state_header 扫描 plain 输出（到 “Changes to be committed:” 等停止行之前），识别出如rebase in progress、merge in progress. unresolved conflicts等摘要（枚举见 GitStatusState），并前插到格式化结果之前。

走非紧凑路径时（用户带了复杂参数），则只施加最小过滤 filter_status_with_args：去空行、去(use "git add ...")类提示行，保留其余内容。

git diff：stat + compact_diff 两段式

run_diff（git.rs#L112-L216）的策略分三条路：

• 用户要--stat/--numstat/--shortstat，或显式--no-compact→ 直接透传，原样打印（--no-compact是 RTK 自有 flag，执行前被剔除）；
• 默认路径 → 先跑一次git diff --stat得到变更概览，再跑一次git diff得到完整 diff，交给compact_diff()压缩后以Changes:段落拼接在 stat 之后；
• 任一步失败 → 原样回传 stderr 与退出码。

核心压缩函数 compact_diff 是一个逐行状态机，规则如下：

• 遇到diff --git行：刷新上一 hunk 的截断标记，输出文件路径（取b/后的部分）；
• 遇到@@hunk 头：完整保留（包括第二个@@后的函数上下文）；
• hunk 内的+/-行：计入该文件的增删计数，且每个 hunk 最多展示 100 行（max_hunk_lines = 100），超出的部分累计为... (N lines truncated)；
• 上下文行只在 hunk 已开始展示后跟随输出；
• 每个文件结束时输出+added -removed汇总行；
• 整体输出受max_lines（默认 500，来自调用处max_lines.unwrap_or(500)）上限，截断时追加提示[full diff: rtk git diff --no-compact]，告诉用户/Agent 如何取回全量。

该函数被git diff、git show、glab mr diff与git stash show -p四处复用（后者上限为 100 行），是模块文档中“cross-command 共享”的主要载体。

git show（run_show）类似地走三步：一行 commit 摘要（--pretty=format:%h %s (%ar) <%an>）→--stat汇总 → 压缩 diff；而git show rev:path这类打印 blob 的调用、或用户自带--stat/--pretty/--format时直接透传，避免重复输出。

git log：格式注入、限额解析与输出整形

run_log（git.rs#L428-L531）是模块中参数解析最复杂的一条路径：

1. 原始形态透传：若参数中出现会改变输出形态的 flag（-p、--stat、--name-status、--numstat等，见 requests_raw_diff_shape），整组参数走run_passthrough，不注入任何 RTK 格式；
2. tokenize：log_arg_tokens 把参数切分为 flag 与被消费的 value 两类，遇到--即停止（其后的 token 是路径而非 flag）。consumes_next_token_as_value 列出了--grep、--author、-n等约 40 个“下一 token 是值”的选项——这保证--grep --pretty中的--pretty不会被误认为格式 flag；
3. 格式注入：用户未提供--oneline/--pretty/--format时，RTK 注入--pretty=format:%h %s (%ar) <%an>%n%b%n---END---。源码注释说明保留%b（commit body 首段）是为了给 Agent 留下BREAKING CHANGE、Closes #xxx等上下文；---END---作为 commit 块分隔符；
4. 限额：用户显式-N/-n N/--max-count(=N)时尊重用户值；仅给了格式 flag 时默认 50 条；什么都没有则默认 10 条，并自动追加--no-merges（除非用户显式要 merge commit）；
5. 后处理：filter_log_output 按---END---切块，每块只保留头行 + 至多 3 行非 trailer 正文（剔除Signed-off-by:、Co-authored-by:），超长行按 80 字符（用户显式限额时为 120 字符，注释说明更宽的阈值是保留 rebase/squash 所需的 commit 上下文）截断并追加...。

写操作族：一行式结果与退出码传播

模块文档强调“Exit code propagation is critical for CI/CD pipelines”。从源码看，所有写操作都遵循同一契约：成功 → stdout 输出一行紧凑结果；失败 → stderr 回传原生错误并return Ok(result.exit_code)把 git 的退出码原样交给上层。逐个来看：

• git add（run_add）：无参时补.；成功后追加跑git diff --cached --stat --shortstat，输出ok 2 files changed, 5 insertions(+)。源码注释指出：无变化的git add必须保持静默（镜像 git 自身行为），因为若对 Agent 统一打印ok，它无法区分“暂存了 N 个文件”和“什么都没暂存”；
• git commit（run_commit）：用exec_capture_stdin继承 stdin，保证交互式编辑器、GPG 口令提示、credential helper 仍能到达终端；parse_commit_output 从首行方括号中提取短 hash（ok abc1234），并用find定位括号以避免在 hook 前置输出、多字节字符开头的行上按字节切片导致 panic。失败时通过 CommitOutcome::Failed 回传退出码；
• git push（run_push）：这是唯一走流式过滤的子命令——GitPushLineHandler 逐行丢弃Enumerating objects:、Counting objects:、Writing objects:等进度噪声前缀，并监听Everything up-to-date与-> refs/...行，结束后输出ok (up-to-date)或ok origin/branch；
• git pull（run_pull）：解析N files changed, X insertions(+), Y deletions(-)汇总行，输出ok 3 files +10 -2；
• git branch（run_branch）：按“写操作 flag（-d/-D/-m/-M/-c/-u/--set-upstream-to等）→ 透传；--show-current→ 透传原样 stdout；列表模式 → 过滤”三分支。filter_branch_output 把remotes/<remote>/<branch>去前缀、去重，并把与本地重名的远端分支折叠进remote-only (N):分组，超过CAP_WARNINGS上限的以... +N more收尾；
• git fetch / stash / worktree：fetch 统计 stderr 中->与[new行得到ok fetched (N new refs)；stash 对push/save输出ok stashed，但把No local changes to save原样透出（同样的“no-op 不得伪装成成功”原则，见 format_stash_message 注释）；stash show的 patch 模式复用compact_diff，stat 模式用 compact_stash_stat 把 diffstat 压成path N +-形式；worktree 的add/remove/prune/...透传，list则把 home 前缀换成~并规整为path hash [branch]单行。

never_worse：压缩不得劣化的兜底

几乎每条读路径在打印前都套一层never_worse(&raw, &filtered)（来自 src/core/guard.rs）：如果压缩后的输出反而比原始输出“更长或更差”，则回退打印原始输出。例如 run_diff 的收尾：

let raw = format!("{}\n{}", result.stdout, diff_result.stdout); let shown = never_worse(&raw, &printed);

这保证了模块文档第一条承诺——git status的紧凑输出“never exceeds rawgit status”——在实现层面有硬性约束而非仅靠代码审查。

glab 命令族：与 gh 的差异适配

glab_cmd.rs 的模块头注释与 glab vs gh JSON schema quick-ref 表 给出了同一份事实。glab 输出适配必须遵守的 JSON 模式差异如下（表格完整继承自模块文档）：

源码印证了表中每一项：glab_cmd.rs#L1-L12 的文档注释逐条列出；state_icon 按小写opened/merged/closed映射[open]/[merged]/[closed]（超紧凑模式退化为单字母O/M/C）；pipeline_icon 从head_pipeline.status取值，非紧凑模式输出文本标签[ok]、[fail]、[cancel]、[run]、[pend]、[skip]——模块文档解释了原因：文本标签与gh_cmd.rs保持一致，同时避免多字节（emoji）图标在终端中的渲染怪癖。

其余 glab 特有行为（均出自模块文档并在源码中可查）：

• clap 层全局 flag 追加：-R/--repo与-g/--group在 clap 层声明，但执行时追加（append）到 glab 参数末尾而非前置，避免破坏 glab 的子命令分发；
• 输出 flag 短路：has_output_flag()检测到用户显式请求-F/--output/--json时直接透传，避免 RTK 再注入一次 JSON 造成双重注入；
• view 短路：should_passthrough_view()在mr view/issue view带--web或--comments时转向透传；
• JSON 助手：各 JSON 子命令统一走本地run_glab_json<F>()，包装runner::run_filtered与RunOptions::stdout_only().early_exit_on_failure().no_trailing_newline()；JSON 解析失败时回退打印原始 stdout（glab 在空结果时可能输出纯文本）；
• ci status 关键词解析：glab 该子命令不支持-F json，因此用英文状态关键词解析文本输出；若未识别到任何英文状态词（非英文 locale），原样返回 raw 输出，不做猜测；
• ci trace 纯文本过滤：ANSI 剥离 + GitLab section 标记过滤 + runner/git/artifact 样板行剔除，保持文本过滤而非转 JSON。源码中对应两条正则：SECTION_MARKER_RE 匹配section_start/end:timestamp:name及裸的[0K序列；
• release list 双格式兼容：优先按 glab 1.82+ 的新格式解析，不匹配时回退到旧的制表符分隔解析，再不行则回退 raw。

markdown 正文过滤（filter_markdown_body）按代码围栏（``` 或 ~~~）切段：围栏内原样保留，围栏外经 filter_markdown_segment 剔除 HTML 注释、badge 行、纯图片行、水平分割线，并把连续 3 个以上空行折叠为一个。

独立 diff 命令：与 git diff 无关的超精简比较

模块文档指出diff_cmd.rs是“standalone ultra-condensed diff (separate fromgit diff)”。diff_cmd.rs 的run(file1, file2)直接读两个文件做行级比较，输出file1 → file2、+N added, -M removed, ~K modified汇总和仅含变更行的明细（+行号/-行号/~行号 old → new），并遵守 diff 惯例退出码：相同为 0，不同为 1（render_diff）。另有 run_stdin 从管道读取 unified diff 并压缩，同样套never_worse兜底。

小结：一个可验证的设计模式

把模块文档的要点与源码对照后可以归纳出该模块统一遵循的四层模式：

1. 透传优先：任何“用户已显式改变输出形态”的信号（--stat、--pretty、-F json、--web、未枚举的 git 子命令）都让位于原样透传，压缩只发生在默认形态上；
2. 有损压缩 + 逃生门：compact_diff的 hunk 级截断、filter_log_output的 body 行上限、filter_branch_output的 remote-only 上限，全部伴随可执行的恢复提示（如[full diff: rtk git diff --no-compact]、... +N more）；
3. 正确性护栏：never_worse保证输出不劣化、LC_ALL=C内部解析与用户 locale 分离、detached HEAD 与 rebase 状态头主动还原、no-op 不伪装成功、退出码全程传播；
4. 跨命令复用：compact_diff与 markdown 过滤助手在 git/gh/glab 间共享，glab 侧以一张 JSON schema 差异表约束适配面。

如需进一步深入，建议按 模块文档 → git.rs 的过滤实现 → glab_cmd.rs 的适配实现 的顺序对照阅读，git.rs 文件尾部内置的#[cfg(test)] mod tests（自 git.rs#L2259 起）覆盖了git_cmd全局参数拼接、log 参数 tokenize、限额解析等关键分支的单测，可直接作为行为规格的参考。

【免费下载链接】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