代码评审基础：使用 /plannotator-review 评审 Git Diff

学完你能做什么

✅ 使用 /plannotator-review 命令评审 Git Diff
✅ 在 side-by-side 和 unified 视图间切换
✅ 点击行号选择代码范围，添加行级注释
✅ 添加不同类型的注释（comment/suggestion/concern）
✅ 切换不同的 diff 类型（uncommitted/staged/last commit/branch）
✅ 将评审反馈发送给 AI Agent

你现在的困境

问题 1：用 git diff 查看代码变更时，输出在终端里滚动，难以全面理解改动内容。

问题 2：想给 Agent 反馈代码问题时，只能用文字描述"第 10 行有问题"、"修改这个函数"，容易产生歧义。

问题 3：不知道 Agent 具体改了哪些文件，在大量改动中难以聚焦关键部分。

问题 4：评审代码后，想把结构化反馈发送给 Agent，让它根据建议重新修改。

Plannotator 能帮你：

可视化 Git Diff，支持 side-by-side 和 unified 两种视图
点击行号即可选中代码范围，精确标注问题位置
添加行级注释（comment/suggestion/concern），附带建议代码
一键切换 diff 类型（uncommitted、staged、last commit、branch）
注释自动转换为 Markdown，Agent 准确理解你的反馈

什么时候用这一招

使用场景：

Agent 完成代码修改后，你需要评审改动内容
提交代码前，想全面检查自己的变更
与团队协作时，需要结构化反馈代码问题
想在多个 diff 类型间切换（未提交 vs 已暂存 vs 上次提交）

不适用场景：

评审 AI 生成的实施计划（使用计划评审功能）
直接在终端中使用 git diff（不需要可视化界面）

🎒 开始前的准备

前置条件：

✅ 已安装 Plannotator CLI（详见快速开始）
✅ 已配置 Claude Code 或 OpenCode 插件（详见对应安装指南）
✅ 当前目录在 Git 仓库中

触发方式：

在 Claude Code 或 OpenCode 中执行 /plannotator-review 命令

核心思路

代码评审是什么

代码评审是 Plannotator 提供的可视化 Git Diff 评审工具，让你在浏览器中查看代码变更并添加行级注释。

为什么需要代码评审？

AI Agent 完成代码修改后，通常会用终端输出 git diff 内容。这种纯文本方式难以全面理解改动，也不方便精确标注问题位置。Plannotator 提供可视化界面（side-by-side 或 unified），支持点击行号添加注释，并将结构化反馈发送给 Agent，让它根据建议重新修改代码。

工作流程

┌─────────────────┐
│  用户          │
│  (执行命令)    │
└────────┬────────┘
         │
         │ /plannotator-review
         ▼
┌─────────────────┐
│  CLI          │
│  (运行 git)    │
│  git diff HEAD │
└────────┬────────┘
         │
         │ rawPatch + gitRef
         ▼
┌─────────────────┐
│ Review Server  │  ← 本地服务器启动
│  /api/diff     │
└────────┬────────┘
         │
         │ 浏览器打开 UI
         ▼
┌─────────────────┐
│ Review UI     │
│                 │
│ ┌───────────┐  │
│ │ File Tree  │  │
│ │ (文件列表) │  │
│ └───────────┘  │
│       │         │
│       ▼         │
│ ┌───────────┐  │
│ │ DiffViewer │  │
│ │ (代码对比) │  │
│ │ split/     │  │
│ │ unified   │  │
│ └───────────┘  │
│       │         │
│       │ 点击行号
│       ▼         │
│ ┌───────────┐  │
│ │ 添加注释   │  │
│ │ comment/   │  │
│ │ suggestion/│  │
│ │ concern    │  │
│ └───────────┘  │
│       │         │
│       ▼         │
│ ┌───────────┐  │
│ │ 发送反馈   │  │
│ │ Send       │  │
│ │ Feedback   │  │
│ │ 或 LGTM    │  │
│ └───────────┘  │
└────────┬────────┘
         │
         │ Markdown 格式反馈
         ▼
┌─────────────────┐
│  AI Agent     │
│  (根据建议修改) │
└─────────────────┘

视图模式

视图模式	描述	适用场景
Split (Side-by-side)	左右分屏，旧代码在左，新代码在右	对比大段改动，清晰看到修改前后
Unified	上下合并，删除和添加在同一列	查看小改动，节省垂直空间

注释类型

Plannotator 支持三种代码注释类型：

注释类型	用途	UI 表现
Comment	评论某行代码，提出问题或说明	紫色/蓝色边框标记
Suggestion	提供具体的代码修改建议	绿色边框标记，附带建议代码块
Concern	标记需要关注的潜在问题	黄色/橙色边框标记

注释类型的区别

Comment：用于提问、说明、一般性反馈
Suggestion：用于提供具体的代码修改方案（附带建议代码）
Concern：用于标记需要修复的问题或潜在风险

Diff 类型

Diff 类型	Git 命令	描述
Uncommitted	`git diff HEAD`	未提交的变更（默认）
Staged	`git diff --staged`	已暂存的变更
Unstaged	`git diff`	未暂存的变更
Last commit	`git diff HEAD~1..HEAD`	上次提交的内容
Branch	`git diff main..HEAD`	当前分支与默认分支的对比

跟我做

第 1 步：触发代码评审

在 Claude Code 或 OpenCode 中执行 /plannotator-review 命令：

用户：/plannotator-review

CLI：正在运行 git diff...
      浏览器已打开

你应该看到：

浏览器自动打开 Plannotator 代码评审界面
左侧显示文件列表（File Tree）
右侧显示 Diff Viewer（默认为 split 视图）
顶部有视图切换按钮（Split/Unified）
底部有 "Send Feedback" 和 "LGTM" 按钮

第 2 步：浏览文件列表

在左侧的 File Tree 中查看改动的文件：

文件按路径分组显示
每个文件显示变更统计（additions/deletions）
点击文件切换到对应的 diff 内容

你应该看到：

src/
  auth/
    login.ts          (+12, -5)  ← 点击查看这个文件的 diff
    user.ts          (+8, -2)
  api/
    routes.ts        (+25, -10)

第 3 步：切换视图模式

在页面顶部点击 "Split" 或 "Unified" 按钮切换视图：

Split 视图（Side-by-side）：

旧代码在左（灰色背景，红色删除线）
新代码在右（白色背景，绿色添加线）
适合对比大段改动

Unified 视图（合并）：

旧代码和新代码在同一列
删除的行用红色背景，添加的行用绿色背景
适合查看小改动

你应该看到：

Split 视图：左右分屏，清晰对比修改前后
Unified 视图：上下合并，节省垂直空间

第 4 步：选中代码行，添加注释

添加 Comment 注释：

将鼠标悬停在代码行上，行号旁会出现 + 按钮
点击 + 按钮，或直接点击行号选中该行
选中多行：点击起始行号，按住 Shift 点击结束行号
在弹出的工具栏中输入评论内容
点击 "Add Comment" 按钮

添加 Suggestion 注释（附带建议代码）：

按照上述步骤添加注释
在工具栏中点击 "Add suggested code" 按钮
在弹出的代码框中输入建议的代码
点击 "Add Comment" 按钮

你应该看到：

注释显示在代码行下方
Comment 注释：紫色/蓝色边框标记，显示评论内容
Suggestion 注释：绿色边框标记，显示评论内容和建议代码块
右侧侧边栏会显示所有注释列表

第 5 步：切换 Diff 类型

在页面顶部选择不同的 diff 类型：

Uncommitted changes（默认）：未提交的变更
Staged changes：已暂存的变更
Last commit：上次提交的内容
vs main（如果不在默认分支）：与默认分支的对比

你应该看到：

Diff Viewer 更新为新选择的 diff 内容
文件列表刷新显示新的变更统计

第 6 步：发送反馈给 Agent

Send Feedback（发送反馈）：

添加必要的注释（Comment/Suggestion/Concern）
点击页面底部的 "Send Feedback" 按钮
如果没有注释，会弹出确认对话框询问是否继续

LGTM（Looks Good To Me）：

如果代码没有问题，点击 "LGTM" 按钮。

你应该看到：

浏览器自动关闭（1.5 秒延迟）
终端显示反馈内容或 "LGTM - no changes requested."
Agent 收到反馈后开始修改代码

第 7 步：查看反馈内容（可选）

如果你想查看 Plannotator 发送给 Agent 的反馈内容，可以在终端中查看：

# Code Review Feedback

## src/auth/login.ts

### Line 15 (new)
这里需要添加错误处理逻辑。

### Line 20-25 (old)
**Suggested code:**
```typescript
try {
  await authenticate(req);
} catch (error) {
  return res.status(401).json({ error: 'Authentication failed' });
}

src/api/routes.ts

Line 10 (new)

这个函数缺少输入验证。


**你应该看到**：
- 反馈按文件分组
- 每个注释显示文件路径、行号、类型
- Suggestion 注释附带建议代码块

## 检查点 ✅

完成以上步骤后，你应该能够：

- [ ] 执行 `/plannotator-review` 命令，浏览器自动打开代码评审界面
- [ ] 在 File Tree 中查看改动的文件列表
- [ ] 在 Split 和 Unified 视图间切换
- [ ] 点击行号或 `+` 按钮选中代码行
- [ ] 添加 Comment、Suggestion、Concern 注释
- [ ] 在注释中添加建议代码
- [ ] 切换不同的 diff 类型（uncommitted/staged/last commit/branch）
- [ ] 点击 Send Feedback，浏览器关闭，终端显示反馈内容
- [ ] 点击 LGTM，浏览器关闭，终端显示 "LGTM - no changes requested."

**如果某一步失败**，详见：
- [常见问题](../../faq/common-problems/)
- [Claude Code 安装指南](../../start/installation-claude-code/)
- [OpenCode 安装指南](../../start/installation-opencode/)

## 踩坑提醒

**常见错误 1**：执行 `/plannotator-review` 后，浏览器没有打开

**原因**：可能是端口占用或服务器启动失败。

**解决**：
- 检查终端中是否有错误信息
- 尝试手动在浏览器中打开显示的 URL
- 如果问题持续，详见 [故障排查](../../faq/troubleshooting/)

**常见错误 2**：点击行号后，没有弹出工具栏

**原因**：可能是因为选中的是空行，或者浏览器窗口太小。

**解决**：
- 尝试选中包含代码的行
- 放大浏览器窗口
- 确保没有禁用 JavaScript

**常见错误 3**：添加注释后，注释没有显示在代码下方

**原因**：可能是因为选中的是空行，或者浏览器窗口太小。

**解决**：
- 尝试选中包含代码的行
- 放大浏览器窗口
- 确保没有禁用 JavaScript
- 检查右侧侧边栏是否显示了注释列表

**常见错误 4**：点击 Send Feedback 后，终端没有显示反馈内容

**原因**：可能是网络问题或服务器错误。

**解决**：
- 检查终端中是否有错误信息
- 尝试重新发送反馈
- 如果问题持续，详见 [故障排查](../../faq/troubleshooting/)

**常见错误 5**：Agent 收到反馈后，没有按照建议修改代码

**原因**：Agent 可能没有正确理解注释的意图。

**解决**：
- 尝试使用更明确的注释（Suggestion 比 Comment 更明确）
- 使用 Comment 添加详细说明
- 在 Suggestion 中提供完整的建议代码
- 如果问题持续，可以再次运行 `/plannotator-review` 评审新的改动

**常见错误 6**：切换 diff 类型后，文件列表为空

**原因**：可能是因为选中的 diff 类型没有变更内容。

**解决**：
- 尝试切换回 "Uncommitted changes"
- 检查 git 状态，确认是否有变更
- 使用 `git status` 查看当前状态

## 本课小结

代码评审是 Plannotator 提供的可视化 Git Diff 评审工具：

**核心操作**：
1. **触发**：执行 `/plannotator-review`，浏览器自动打开 UI
2. **浏览**：在 File Tree 中查看改动的文件列表
3. **视图**：在 Split（side-by-side）和 Unified 视图间切换
4. **注释**：点击行号选中代码行，添加 Comment/Suggestion/Concern 注释
5. **切换**：选择不同的 diff 类型（uncommitted/staged/last commit/branch）
6. **反馈**：点击 Send Feedback 或 LGTM，反馈发送给 Agent

**视图模式**：
- **Split（Side-by-side）**：左右分屏，旧代码在左，新代码在右
- **Unified**：上下合并，删除和添加在同一列

**注释类型**：
- **Comment**：评论某行代码，提出问题或说明
- **Suggestion**：提供具体的代码修改建议（附带建议代码）
- **Concern**：标记需要关注的潜在问题

**Diff 类型**：
- **Uncommitted**：未提交的变更（默认）
- **Staged**：已暂存的变更
- **Unstaged**：未暂存的变更
- **Last commit**：上次提交的内容
- **Branch**：当前分支与默认分支的对比

## 下一课预告

> 下一课我们学习 **[添加代码注释](../code-review-annotations/)**。
>
> 你会学到：
> - 如何精确使用 Comment、Suggestion、Concern 注释
> - 如何添加建议代码并格式化显示
> - 如何编辑和删除注释
> - 注释的最佳实践和常见场景
> - 如何在 side-by-side 视图中选择 old/new 侧

---

## 附录：源码参考

<details>
<summary><strong>点击展开查看源码位置</strong></summary>

> 更新时间：2026-01-24

| 功能              | 文件路径                                                                                              | 行号    |
|--- | --- | ---|
| 代码评审服务器     | [`packages/server/review.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/server/review.ts#L1-L302)           | 1-302   |
| 代码评审 UI       | [`packages/review-editor/App.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/App.tsx#L1-L150) | 1-150   |
| DiffViewer 组件    | [`packages/review-editor/components/DiffViewer.tsx`](https://github.com/backnotprop/plannotator/blob/main/packages/review-editor/components/DiffViewer.tsx#L1-L349) | 1-349   |
| Git 工具         | [`packages/server/git.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/server/git.ts#L1-L148)                 | 1-148   |
| Hook 入口（review） | [`apps/hook/server/index.ts`](https://github.com/backnotprop/plannotator/blob/main/apps/hook/server/index.ts#L46-L84)         | 46-84   |
| 代码注释类型定义    | [`packages/ui/types.ts`](https://github.com/backnotprop/plannotator/blob/main/packages/ui/types.ts#L53-L83)                  | 53-83   |

**关键类型**：
- `CodeAnnotationType`：代码注释类型枚举（comment、suggestion、concern）（`packages/ui/types.ts:53`）
- `CodeAnnotation`：代码注释接口（`packages/ui/types.ts:55-66`）
- `DiffType`：Diff 类型枚举（uncommitted、staged、unstaged、last-commit、branch）（`packages/server/git.ts:10-15`）
- `GitContext`：Git 上下文接口（`packages/server/git.ts:22-26`）

**关键函数**：
- `startReviewServer()`：启动代码评审服务器（`packages/server/review.ts:79`）
- `runGitDiff()`：运行 git diff 命令（`packages/server/git.ts:101`）
- `getGitContext()`：获取 Git 上下文（分支信息和 diff 选项）（`packages/server/git.ts:79`）
- `parseDiffToFiles()`：将 diff 解析为文件列表（`packages/review-editor/App.tsx:48`）
- `exportReviewFeedback()`：将注释导出为 Markdown 反馈（`packages/review-editor/App.tsx:86`）

**API 路由**：
- `GET /api/diff`：获取 diff 内容（`packages/server/review.ts:118`）
- `POST /api/diff/switch`：切换 diff 类型（`packages/server/review.ts:130`）
- `POST /api/feedback`：提交评审反馈（`packages/server/review.ts:222`）
- `GET /api/image`：获取图片（`packages/server/review.ts:164`）
- `POST /api/upload`：上传图片（`packages/server/review.ts:181`）
- `GET /api/agents`：获取可用 agents（OpenCode）（`packages/server/review.ts:204`）

**业务规则**：
- 默认查看未提交的 diff（`apps/hook/server/index.ts:55`）
- 支持切换到 vs main diff（`packages/server/git.ts:131`）
- 反馈格式化为 Markdown（`packages/review-editor/App.tsx:86`）
- 批准时发送 "LGTM" 文本（`packages/review-editor/App.tsx:430`）

</details>

5 分钟快速上手

评审 AI 计划和代码

多人协作+笔记存档

遇到问题怎么办

查 API 和数据结构

看看新功能

代码评审基础：使用 /plannotator-review 评审 Git Diff

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

代码评审是什么

工作流程

视图模式

注释类型

Diff 类型

跟我做

第 1 步：触发代码评审

第 2 步：浏览文件列表

第 3 步：切换视图模式

第 4 步：选中代码行，添加注释

第 5 步：切换 Diff 类型

第 6 步：发送反馈给 Agent

第 7 步：查看反馈内容（可选）

src/api/routes.ts

Line 10 (new)

代码评审基础：使用 /plannotator-review 评审 Git Diff ​

学完你能做什么 ​

你现在的困境 ​

什么时候用这一招 ​

🎒 开始前的准备 ​

核心思路 ​

代码评审是什么 ​

工作流程 ​

视图模式 ​

注释类型 ​

Diff 类型 ​

跟我做 ​

第 1 步：触发代码评审 ​

第 2 步：浏览文件列表 ​

第 3 步：切换视图模式 ​

第 4 步：选中代码行，添加注释 ​

第 5 步：切换 Diff 类型 ​

第 6 步：发送反馈给 Agent ​

第 7 步：查看反馈内容（可选） ​

src/api/routes.ts ​

Line 10 (new) ​

代码评审基础：使用 /plannotator-review 评审 Git Diff

学完你能做什么

你现在的困境

什么时候用这一招

🎒 开始前的准备

核心思路

代码评审是什么

工作流程

视图模式

注释类型

Diff 类型

跟我做

第 1 步：触发代码评审

第 2 步：浏览文件列表

第 3 步：切换视图模式

第 4 步：选中代码行，添加注释

第 5 步：切换 Diff 类型

第 6 步：发送反馈给 Agent

第 7 步：查看反馈内容（可选）

src/api/routes.ts

Line 10 (new)