catalog/repos/agavra--tuicr.md

# 终端代码审查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 生成的代码差异。

![demo](./public/tuicr-demo.gif)

## 为什么要做这个

我经常使用 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
```