mc-skills/catalog

Fork 0

mc-skills 52efc07510 catalog: 更新 2026-04-07 11:44

2026-04-07 11:44:56 +08:00

13 KiB

Raw Blame History

终端代码审查TUI工具

代码审查 TUI 终端工具 Git AI辅助开发 Vim键位 Rust

tuicr：终端代码审查工具

直接在终端中像审查 GitHub Pull Request 一样审查 AI 生成的代码差异。

为什么要做这个

我经常使用 Claude，但它没有介于"逐项审查每处修改"和"接受所有编辑"之间的中间方案。逐项审查会把速度拖回人工审核的节奏，而接受所有编辑又让最终审查变得痛苦——我只能一条一条地留评论，等一次修一次。

tuicr 就是那个中间方案。让 AI 放手去改，然后像正常 PR 一样审查变更，在需要的地方留下评论，最后将所有内容导出为结构化反馈，让 AI 一次性处理。

这让我的 AI 辅助开发飞速起来。

Tip

我把它念作"tweaker"（调整者）

概述

一个在终端中运行的 GitHub 风格差异查看器，支持 Vim 键位。可以滚动浏览变更文件、留下评论、将文件标记为已审查，并将完整审查内容复制到剪贴板，格式可直接粘贴回给 AI。

功能特性

无限滚动差异视图 - 所有变更文件在一个连续滚动视图中呈现（GitHub 风格）
Vim 键位 - 使用 j/k、Ctrl-d/u、g/G、{/}、[/] 导航
可展开上下文 - 在"... 展开（N 行）..."处按 Enter 展开 hunk 间隐藏的上下文
评论功能 - 可添加审查级别、文件级别或行级别的分类评论
可视模式 - 用 v / V 选择行范围，对多行同时添加评论
审查追踪 - 将文件标记为已审查，进度持久化保存到磁盘
.tuicrignore 支持 - 从审查差异中排除匹配的文件
剪贴板导出 - 复制为针对 LLM 消费优化的结构化 Markdown
会话持久化 - 审查内容自动保存，重启后自动恢复
Jujutsu 支持 - 内置 jj 支持（优先尝试，因为 jj 仓库基于 Git）
Mercurial 支持 - 内置 hg 支持

安装

Homebrew（macOS/Linux）

brew install agavra/tap/tuicr

预构建二进制文件

从 GitHub Releases 下载适合你平台的最新版本。

Mise（macOS/Linux/Windows）

mise use github:agavra/tuicr

从 crates.io 安装

cargo install tuicr

使用 Nix

# 构建 tuicr（将二进制链接到 ./result/bin/tuirc）
nix build github:agavra/tuicr

# 或直接运行
nix run github:agavra/tuicr

从源码安装

git clone https://github.com/agavra/tuicr.git
cd tuicr
cargo install --path .

使用方法

在任意 git、jujutsu 或 mercurial 仓库中运行 tuicr：

cd /path/to/your/repo
tuicr

检测顺序：Jujutsu → Git → Mercurial。Jujutsu 优先尝试，因为 jj 仓库基于 Git。

选项

参数	说明
`-r` / `--revisions <REVSET>`	要审查的提交范围/版本集，具体语法取决于 VCS 后端（Git、JJ、Hg）
`--theme <THEME>`	覆盖颜色主题（`dark`、`light`、`ayu-light`、`onedark`、`catppuccin-latte`、`catppuccin-frappe`、`catppuccin-macchiato`、`catppuccin-mocha`、`gruvbox-dark`、`gruvbox-light`）
`--appearance <MODE>`	默认主题的外观模式（`dark`、`light`、`system`）
`--stdout`	导出时输出到标准输出而非剪贴板
`--no-update-check`	启动时跳过更新检查

默认情况下，tuicr 以提交选择模式启动。
如果存在已暂存或未暂存的变更，第一个可选条目为 Staged changes（已暂存变更）和/或 Unstaged changes（未暂存变更）。
当提供 -r / --revisions 参数时，tuicr 直接打开对应的版本范围。
在窄终端（小于 100 列）下，tuicr 启动时隐藏文件列表；可用 ;e 切换显示。

配置

在以下路径设置默认主题：

Linux/macOS：$XDG_CONFIG_HOME/tuicr/config.toml（默认：~/.config/tuicr/config.toml）
Windows：%APPDATA%\tuicr\config.toml

示例：

theme = "catppuccin-mocha"

appearance = "system"
theme_dark = "gruvbox-dark"
theme_light = "gruvbox-light"

show_file_list = false
diff_view = "side-by-side"
wrap = true

comment_types = [
  { id = "note", label = "question", definition = "ask for clarification", color = "yellow" },
  { id = "suggestion", definition = "possible improvements" },
  { id = "issue", definition = "problems to fix" },
  { id = "praise", definition = "positive feedback" },
  { id = "nit", label = "nitpick", definition = "small optional tweaks", color = "#d19a66" }
]

show_file_list 控制启动时是否显示文件列表面板（默认：true）。运行时可用 ;e 切换。

diff_view 设置默认差异布局："unified"（统一视图，默认）或 "side-by-side"（左右对比）。运行时可用 :diff 切换。

wrap 在差异视图中启用自动换行（默认：false）。运行时可用 :set wrap! 切换。

comment_types 替换默认列表并定义 Tab 循环顺序。每个条目需要 id，可选设置 label、definition 和 color。颜色支持终端名称（如 yellow、light_red）或十六进制（#RRGGBB）。

`comment_types` 工作原理

id 是保存在会话中并用于匹配的内部稳定值。
label 是在界面和导出中显示的标签（[QUESTION]、[NITPICK] 等）。
definition 是为 LLM 提供的指导文字，包含在导出的 Comment types: 说明中。
color 控制 TUI 中评论徽章/边框的颜色。
声明 comment_types 是完全替换——如果你定义了 2 种类型，则只有这 2 种可用。
如果缺少 comment_types，tuicr 使用默认值：note、suggestion、issue、praise。
无效条目在启动时会显示警告并被忽略；若所有条目均无效，tuicr 回退到默认值。

最简替换示例：

comment_types = [
  { id = "question", definition = "ask for clarification" },
  { id = "blocker", color = "red", definition = "must be fixed before merge" }
]

主题解析优先级：

--theme <THEME>
配置文件中的 theme（OS 对应路径）
配置文件中的 theme_dark + theme_light（根据外观模式选择）
配置文件中仅有 theme_dark 或仅有 theme_light（忽略外观模式）
--appearance <MODE>（仅当未设置明确主题或变体时生效）
配置文件中的 appearance（仅当未设置明确主题或变体时生效）
内置默认值（system）

注意：

无效的 --theme 值会导致立即以非零状态退出。
config.toml 中的未知键会在启动时显示警告并被忽略。

使用 `.tuicrignore` 忽略文件

tuicr 从仓库根目录读取 .tuicrignore，并从所有审查差异中排除匹配的文件。

规则遵循 gitignore 风格的模式匹配，包括 ! 取反语法。

示例：

target/
dist/
*.lock
!Cargo.lock

键位绑定

按键	操作
`j` / `↓`	向下滚动
`k` / `↑`	向上滚动
`h` / `←`	向左滚动
`l` / `→`	向右滚动
`Ctrl-d` / `Ctrl-u`	向下/向上翻半页
`Ctrl-f` / `Ctrl-b`	向下/向上翻整页
`g` / `G`	跳到第一个/最后一个文件
`{N}G`	跳到当前文件的第 N 个源码行
`{` / `}`	跳到上一个/下一个文件
`[` / `]`	跳到上一个/下一个 hunk
`/`	在差异中搜索
`n` / `N`	下一个/上一个搜索匹配
`Enter`	展开/折叠 hunk 间隐藏的上下文
`zz`	将光标居中显示

文件树

按键	操作
`Space`	切换展开目录
`Enter`	展开目录 / 在差异中跳转到文件
`o`	展开所有目录
`O`	折叠所有目录

面板焦点

按键	操作
`Tab` / `Shift-Tab`	在文件列表、差异视图和提交选择器之间向前/向后切换焦点
`;h`	聚焦文件列表（左面板）
`;l`	聚焦差异视图（右面板）
`;k`	聚焦提交选择器（顶部面板）
`;j`	聚焦差异视图
`;e`	切换文件列表可见性
`Enter`	选择文件（文件列表聚焦时）

审查操作

按键	操作
`r`	切换文件已审查状态
`c`	添加行评论（若不在差异行上则添加文件评论）
`C`	添加文件评论
`;c`	添加审查评论
`v` / `V`	进入可视模式以进行范围评论
`dd`	删除光标处的评论
`i`	编辑光标处的评论
`y`	将审查内容复制到剪贴板

可视模式

按键	操作
`j` / `k`	向下/向上扩展选区
`c` / `Enter`	为选定范围创建评论
`Esc` / `v` / `V`	取消选择

评论模式

按键	操作
`Tab` / `Shift-Tab`	按 `comment_types` 顺序向前/向后循环评论类型
`Enter` / `Ctrl-Enter` / `Ctrl-s`	保存评论
`Shift-Enter` / `Ctrl-j`	插入换行
`←` / `→`	移动光标
`Ctrl-w`	删除单词
`Ctrl-u`	清除当前行
`Esc` / `Ctrl-c`	取消

命令

命令	操作
`:w`	保存会话
`:e`（`:reload`）	重新加载差异文件
`:clip`（`:export`）	将审查内容复制到剪贴板
`:diff`	切换差异视图（统一视图 / 左右对比）
`:commits`	选择要审查的提交
`:set wrap`	在差异视图中启用自动换行
`:set wrap!`	切换差异视图自动换行
`:set commits`	显示内联提交选择器
`:set nocommits`	隐藏内联提交选择器
`:set commits!`	切换内联提交选择器
`:clear`	清除所有评论
`:version`	显示 tuicr 版本
`:update`	检查更新
`:q`	退出（有未保存内容时提示）
`:q!`	强制退出
`:x` / `:wq`	保存并退出（若有评论则提示是否复制）
`?`	切换帮助显示
`q`	快速退出

提交选择（启动时）

按键	操作
`j` / `k`	移动选择
`Space`	切换提交选中状态
`Enter`	确认并加载差异
`q` / `Esc`	退出

内联提交选择器（多提交审查）

审查多个提交时，差异视图顶部会出现内联提交选择器面板。使用 ;k 或 Tab 聚焦。

按键	操作
`j` / `k`	导航提交
`Space` / `Enter`	切换提交选中状态（更新差异）
`(` / `)`	逐个循环提交
`Esc`	返回焦点到差异视图

确认对话框

按键	操作
`y` / `Enter`	是
`n` / `Esc`	否

审查输出

当你导出审查内容（:clip 或在 :wq 时确认），tuicr 会将结构化 Markdown 复制到剪贴板。该格式针对粘贴到 AI 对话进行了优化：

I reviewed your code and have the following comments. Please address them.

Comment types: ISSUE (problems to fix), SUGGESTION (improvements), NOTE (observations), PRAISE (positive feedback)

1. **[SUGGESTION]** `src/auth.rs` - Consider adding unit tests
2. **[ISSUE]** `src/auth.rs:42` - Magic number should be a named constant
3. **[NOTE]** `src/auth.rs:50-55` - This block could be refactored

每条评论都有编号，并包含完整的文件路径及行号或行范围（如适用）。
如果配置了 comment_types，说明和 [TYPE] 标签将反映你配置的标签和定义。

会话持久化

会话自动保存到 ~/.local/share/tuicr/reviews/（符合 XDG 规范）。当你在同一仓库中重新打开 tuicr 时，之前的审查进度（评论、已审查状态）会自动恢复。

AI 集成

tuicr 在 skills/tuicr/ 提供了一个仓库管理的技能包。

它会在 tmux 分屏中打开 tuicr，让你可以交互式地审查变更并将评论反馈给你的编程 AI。

使用方式： /tuicr 或让你的编程 AI "用 tuicr 审查我的变更"。

Claude Code

前提条件： Claude Code 在 tmux 内运行，已安装 tuicr。

安装（二选一）：

# 将共享技能复制到 Claude 的本地技能目录
mkdir -p ~/.claude/skills
cp -r /path/to/tuicr/skills/tuicr ~/.claude/skills/tuicr

Codex

前提条件： Codex 在 tmux 内运行，已安装 tuicr。

安装：

# 将共享技能复制到本地 agents 技能目录
mkdir -p ~/.agents/skills
cp -r /path/to/tuicr/skills/tuicr ~/.agents/skills/tuicr

13 KiB Raw Blame History Unescape Escape