371 lines
13 KiB
Markdown
371 lines
13 KiB
Markdown
# 终端代码审查TUI工具
|
||
|
||
`代码审查` `TUI` `终端工具` `Git` `AI辅助开发` `Vim键位` `Rust`
|
||
|
||
# tuicr：终端代码审查工具
|
||
|
||
<a href="https://crates.io/crates/tuicr" target="_blank"><img src="https://img.shields.io/crates/v/tuicr" alt="Crates.io"></a>
|
||
<a href="https://github.com/agavra/tuicr/blob/main/LICENSE" target="_blank"><img src="https://img.shields.io/crates/l/tuicr" alt="License"></a>
|
||
<a href="https://tuicr.dev" target="_blank"><img src="https://img.shields.io/badge/website-tuicr.dev-green" alt="Website"></a>
|
||
|
||
直接在终端中像审查 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）
|
||
|
||
```bash
|
||
brew install agavra/tap/tuicr
|
||
```
|
||
|
||
### 预构建二进制文件
|
||
|
||
从 [GitHub Releases](https://github.com/agavra/tuicr/releases) 下载适合你平台的最新版本。
|
||
|
||
### Mise（macOS/Linux/Windows）
|
||
|
||
```
|
||
mise use github:agavra/tuicr
|
||
```
|
||
|
||
### 从 crates.io 安装
|
||
|
||
```bash
|
||
cargo install tuicr
|
||
```
|
||
|
||
### 使用 Nix
|
||
|
||
```bash
|
||
# 构建 tuicr（将二进制链接到 ./result/bin/tuirc）
|
||
nix build github:agavra/tuicr
|
||
|
||
# 或直接运行
|
||
nix run github:agavra/tuicr
|
||
```
|
||
|
||
### 从源码安装
|
||
|
||
```bash
|
||
git clone https://github.com/agavra/tuicr.git
|
||
cd tuicr
|
||
cargo install --path .
|
||
```
|
||
|
||
## 使用方法
|
||
|
||
在任意 git、jujutsu 或 mercurial 仓库中运行 `tuicr`：
|
||
|
||
```bash
|
||
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`
|
||
|
||
示例：
|
||
|
||
```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 回退到默认值。
|
||
|
||
最简替换示例：
|
||
|
||
```toml
|
||
comment_types = [
|
||
{ id = "question", definition = "ask for clarification" },
|
||
{ id = "blocker", color = "red", definition = "must be fixed before merge" }
|
||
]
|
||
```
|
||
|
||
主题解析优先级：
|
||
1. `--theme <THEME>`
|
||
2. 配置文件中的 `theme`（OS 对应路径）
|
||
3. 配置文件中的 `theme_dark` + `theme_light`（根据外观模式选择）
|
||
4. 配置文件中仅有 `theme_dark` 或仅有 `theme_light`（忽略外观模式）
|
||
5. `--appearance <MODE>`（仅当未设置明确主题或变体时生效）
|
||
6. 配置文件中的 `appearance`（仅当未设置明确主题或变体时生效）
|
||
7. 内置默认值（`system`）
|
||
|
||
注意：
|
||
- 无效的 `--theme` 值会导致立即以非零状态退出。
|
||
- `config.toml` 中的未知键会在启动时显示警告并被忽略。
|
||
|
||
### 使用 `.tuicrignore` 忽略文件
|
||
|
||
`tuicr` 从仓库根目录读取 `.tuicrignore`，并从所有审查差异中排除匹配的文件。
|
||
|
||
规则遵循 gitignore 风格的模式匹配，包括 `!` 取反语法。
|
||
|
||
示例：
|
||
|
||
```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 对话进行了优化：
|
||
|
||
```markdown
|
||
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。
|
||
|
||
**安装**（二选一）：
|
||
|
||
```bash
|
||
# 将共享技能复制到 Claude 的本地技能目录
|
||
mkdir -p ~/.claude/skills
|
||
cp -r /path/to/tuicr/skills/tuicr ~/.claude/skills/tuicr
|
||
```
|
||
|
||
### Codex
|
||
|
||
**前提条件：** Codex 在 tmux 内运行，已安装 tuicr。
|
||
|
||
**安装**：
|
||
|
||
```bash
|
||
# 将共享技能复制到本地 agents 技能目录
|
||
mkdir -p ~/.agents/skills
|
||
cp -r /path/to/tuicr/skills/tuicr ~/.agents/skills/tuicr
|
||
``` |