大型Code Review太痛苦？试试终端“分章”审查法，效率翻倍

大型 Code Review 太痛苦？试试在终端里“一章一章”地看完整个变更

之前在参与一个中大型项目时，我最怕的不是写代码，而是每周的 Code Review 环节：一个 MR（Merge Request）动辄几十个文件、上千行改动，浏览器里加载 diff 都要等半天，从上往下翻还没有翻完，已经忘记了前面几个文件到底改了什么。这种状态下的评审，大概率只能给出“看起来没问题”这种低质量结论，真正的问题反而被漏掉。

后来我尝试调整工作流，把大型代码变更拆成一个个“章节”，直接在终端里完成审查。整个过程不再依赖浏览器的长页面滚动，也没有来回切换文件的拉扯感，审查效率和准确率都提升了很多。今天这篇教程，就完整分享一下这套基于终端的“分章审查”思路，以及如何从零实现一个小工具，帮你把大型变更变成一段段可以消化的内容。

适合读者：

• 经常需要评审大型 PR / MR 的后端开发、前端开发、测试工程师。
• 对 Git、Terminal、命令行工具感兴趣的开发者。
• 想用 LLM（大语言模型）辅助 Code Review，又不希望离开终端环境的人。

读完本文，你将掌握：

• 大型 Code Review 效率低下的原因分析。
• 终端审查的独特价值与适用场景。
• 如何提取 git 变更、拆分成可独立审查的“章节”。
• 如何写一个简单的终端审查工具，并接入 AI 辅助分析。
• 常见的报错排查思路与工程实践建议。

---

1. 背景：大型 Code Review 为什么这么痛苦

1.1 大型代码变更的认知负担

先思考一个很常见的问题：一个 2000 行改动的 PR，和 5 个 400 行改动的 PR，哪个更好审？

直觉上答案很清晰：5 个 400 行的 PR 更好审。原因在于人的工作记忆容量是有限的。心理学中经典的“7±2 法则”告诉我们，人类同时处理的信息组块是有限的，而大型 diff 会把你的工作记忆占满，导致你无法同时记住“这个函数最初是什么样子”“中间第 3 个文件改了什么”“第 8 个文件的改动和开头的设计是否一致”。

具体来说，大型 Code Review 通常面临三个问题：

1. 上下文丢失：当你在浏览器审查时，需要反复记住之前看过的内容。改动的文件越多，上下文切换越频繁，丢失概率越高。
2. 注意力稀释：大型 diff 中往往夹杂着格式化改动、重命名、依赖版本变化等噪音，真正的业务逻辑改动被淹没，评审人容易陷入“逐行检查”但抓不住重点。
3. 评审疲态（Review Fatigue）：一次性阅读超过 400 行代码变更后，大脑开始疲劳，后续审查质量明显下降。这也是很多团队把 review 时间拉得越来越长的原因——不是不想快点结束，而是真的看不完。

1.2 为什么需要“一次一个章节”地审查

这里说的“章节”，可以理解为一组逻辑上相关的变更块。它可以是：

• 一个功能模块涉及的所有文件改动。
• 按业务语义分组的提交（commit）。
• 按文件或 hunk 拆分的最小审查单元。

把大型变更拆成章节，本质上是把“一个大任务”变成“多个小任务”，降低每一次审查的认知负荷。每看一个章节，你只关注这一个完整的小逻辑变化，看完后做一次结论（通过/需要修改/不通过），再进入下一章节。

这种模式类似读书：你不会一次性把整本小说塞进脑子，而是按章节阅读、消化、暂停。代码审查也一样，章节化之后你能记住每个部分在做什么，也更容易发现跨文件的逻辑一致性问题。

1.3 终端为什么适合做代码审查

有人可能会问：GitHub/GitLab 上已经有评论系统、文件树、讨论线程，为什么还要在终端里做？

我的体验是，终端审查有几个无法替代的优势：

• 轻量高效：不需要等待浏览器渲染大量交互组件，一个git diff命令直接输出纯文本，速度极快，尤其适合远程服务器、SSH 开发环境。
• 离 Git 更近：终端里可以直接运行测试、编译、静态检查命令，看完一段代码马上验证，不需要切换到另一个窗口。
• 适合自动化：终端的输出天然是文本，适合脚本处理、管道处理（pipe）。把 diff 传给 AI、统计改动量、过滤噪音，都可以用标准工具链完成。
• 专注度高：浏览器里有标签页、即时通讯、邮件提醒，审查过程很容易被打断。终端全屏状态下，反而更容易保持沉浸。

值得注意的是，终端审查并不排斥浏览器审查。实践中更常见的做法是：先用终端快速走查一遍逻辑，标记可疑点，再回到 MR 页面针对具体位置评论。两者互补，终端负责“读”，浏览器负责“写评论和协作”。

---

2. 环境准备与版本说明

2.1 运行环境

本文以 Linux / macOS 环境为例，Windows 用户可以使用 WSL 2 或 Git Bash 获得接近 Unix 的体验。示例工具使用 Python 编写，Python 3 是必须的运行环境。

必要工具清单：

工具	用途	说明
Git	版本控制	本文要求已初始化仓库并存在目标分支
Python 3	运行示例脚本	建议 3.8 及以上版本
pip	安装 Python 依赖	如果使用虚拟环境，需要额外安装虚拟环境工具
curl	测试接口	可选，用于验证 AI 接口连通性
Terminal	执行命令	macOS 用 Terminal/iTerm2，Linux 用系统自带终端，Windows 用 WSL

版本需要根据你的项目实际情况调整，本文示例以常见环境为例，重点演示配置思路。核心逻辑不依赖特定 Git 版本，只要支持git diff和git log即可。

2.2 安装依赖

示例工具需要调用 OpenAI 兼容的 API。这里先安装必需的 Python 依赖：

pip install requests

如果你不希望污染全局 Python 环境，可以用虚拟环境隔离：

python3 -m venv review-env source review-env/bin/activate # Windows 下执行 review-env\Scripts\activate pip install requests

安装完成后，创建一个工作目录，用于存放后续的脚本和配置：

mkdir -p code-review-tool cd code-review-tool

2.3 环境变量与 API Key

调用 LLM 需要一个 API Key。常见做法是通过环境变量配置，避免硬编码在代码中：

export OPENAI_API_KEY="sk-xxxxxxxxxxxxxxxx" export OPENAI_BASE_URL="https://api.openai.com/v1"

如果你使用的是国内云厂商提供的兼容接口，或者企业内部的推理服务，只需调整OPENAI_BASE_URL即可。这里不限定具体厂商，保持接口兼容即可。

安全提示：千万不要把 API Key 提交到 Git 仓库。建议在项目根目录添加.gitignore，把环境文件或配置文件排除在外。

---

3. 核心原理拆解：把大型变更拆成“章节”

3.1 理解 diff、patch 与变更块

Git 中，diff是表示代码变更的核心数据格式。每段差异由多个部分组成：

• 文件头（file header）：形如diff --git a/src/main.py b/src/main.py，表示变更涉及的文件。
• hunk 头（hunk header）：形如@@ -10,6 +10,7 @@，表示原文件从第 10 行开始、共 6 行，新文件从第 10 行开始、共 7 行。
• 变更内容行：以-开头表示删除的行，以+开头表示新增的行，以空格开头表示上下文行。

一个 hunk 是 diff 中的最小独立单元。如果你的变更很大，一个文件可能有多个 hunk，它们分布在不同位置。

git diff --unified=3

--unified=3参数控制上下文行数为 3，这能让 AI 或人类评审者看到更多改动上下文，但又不会太多导致噪音。

3.2 如何划分“章节”

“章节”的划分方式有很多种，常见策略如下：

划分方式	说明	适用场景
按文件划分	每个文件当作一个章节	文件数量少，但单文件很大时不太合适
按 hunk 划分	每个 hunk 当作一个章节	适合快速从 diff 中定位小改动
按 commit 划分	每个 commit 当作一个章节	前提是开发者在提交时已经按逻辑提交，而不是一次提交所有改动
按目录 / 模块划分	相同模块下的文件合并为一章	适合大型项目，模块边界清晰的情况
按语义划分	根据代码上下文，把相关的多个改动合并成“功能章节”	最灵活，也最难自动化，通常需要人工或 LLM 参与

在简单工具中，最稳妥的方式是“按文件 + 按 hunk”两级拆分：

1. 先用git diff拿到全量变更。
2. 解析 diff 格式，按文件分块。
3. 如果单个文件改动超过一定行数（例如 100 行），再按 hunk 拆分成子章节。

拆分之后，每个章节都带上文件路径、起始行号、变更内容，方便后续逐章处理。

3.3 在终端中展示审查上下文

终端不是浏览器，交互方式受限，但也有自己的展示优势。可以使用 ANSI 颜色高亮新增行和删除行，使用less或fzf等工具实现文本分页和搜索。

例如，用less查看 diff：

git diff --color=always | less -R

-R参数让 less 保留颜色转义字符。如果你希望交互式选择文件，可以使用 fzf：

git diff --name-only | fzf

选中文件后，再单独查看该文件的 diff。这样配合起来，就能在一定程度上实现“按章节浏览”。

---

4. 完整实战：终端分章审查工具的实现

下面我们实现一个简化但可用的终端审查工具，核心功能是：

• 读取当前工作区的变更。
• 把变更按文件拆分。
• 对每个文件单独调用 LLM 分析。
• 在终端中显示分析结果。
• 支持人工标记“下一章/跳过/退出”。

4.1 创建项目结构

code-review-tool/ ├── review.py ├── requirements.txt └── README.md

先用touch创建文件：

touch review.py requirements.txt README.md

requirements.txt里声明依赖：

requests

4.2 提取代码变更

在review.py中，第一步是调用 Git 命令获取 diff。使用subprocess模块，注意处理返回状态和编码。

# 文件路径：code-review-tool/review.py import subprocess def get_diff() -> str: """获取当前工作区相对 HEAD 的全部变更内容。""" result = subprocess.run( ["git", "diff", "HEAD", "--unified=3"], capture_output=True, text=True, encoding="utf-8", ) if result.returncode != 0: raise RuntimeError(f"git diff 执行失败: {result.stderr}") return result.stdout

这里说明一下：git diff HEAD对比的是当前工作区与 HEAD 的差异，包含已暂存和未暂存的内容。如果你只想审查某两个分支之间的差异，可以换成：

git diff main...feature-branch

4.3 解析 diff 并按文件拆分

解析 diff 文件最保险的方式是使用现成库，例如unidiff，但为了减少依赖，我们先手动实现一个简单的解析函数。

# 文件路径：code-review-tool/review.py import re def split_diff_by_file(diff_text: str) -> list[dict]: """把 diff 按文件拆分成多个章节。 返回格式: [ { "file": "src/main.py", "content": "diff --git a/src/main.py b/src/main.py\\n...", }, ] """ chapters = [] current_file = None current_lines = [] for line in diff_text.splitlines(): if line.startswith("diff --git "): if current_file and current_lines: chapters.append({ "file": current_file, "content": "\n".join(current_lines), }) match = re.search(r"diff --git a/(.+) b/(.+)", line) if match: current_file = match.group(2) else: current_file = "unknown" current_lines = [line] else: if current_lines is not None: current_lines.append(line) if current_file and current_lines: chapters.append({ "file": current_file, "content": "\n".join(current_lines), }) return chapters

这个解析逻辑简单直接：遇到diff --git行就开启新文件章节，其余行追加到当前章节。在实际项目中，你可以改成调用unidiff库，能更稳妥地处理重命名、新增文件等边界情况。

4.4 调用 LLM 分析变更

拿到章节内容后，就可以调用 LLM 生成审查意见。这里使用 OpenAI 兼容接口，通过环境变量读取 Key。

# 文件路径：code-review-tool/review.py import os import requests def review_with_llm(file_path: str, diff_content: str) -> str: """调用 LLM 审查单个文件的 diff。""" api_key = os.environ.get("OPENAI_API_KEY") base_url = os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1") if not api_key: return "未配置 OPENAI_API_KEY，跳过 AI 分析。" system_prompt = ( "你是一名资深代码评审专家。请根据提供的 git diff 内容进行审查，" "重点关注：1) 逻辑错误 2) 安全隐患 3) 性能问题 " "4) 可读性与命名规范 5) 缺少测试的边界场景。" "请用中文输出，每条问题附带严重程度（高/中/低）和建议改进方案。" "如果变更没有明显问题，请简洁地说明。" ) user_prompt = f"文件路径: {file_path}\n\n```diff\n{diff_content}\n```" resp = requests.post( f"{base_url}/chat/completions", headers={ "Authorization": f"Bearer {api_key}", "Content-Type": "application/json", }, json={ "model": "gpt-4o-mini", "messages": [ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_prompt}, ], "temperature": 0.2, }, timeout=60, ) if resp.status_code != 200: return f"调用 LLM 失败，HTTP {resp.status_code}: {resp.text[:200]}" data = resp.json() return data["choices"][0]["message"]["content"]

模型名称根据实际可用资源调整，不一定使用gpt-4o-mini。这里采用 OpenAI 兼容格式，很多国内模型服务也支持这种格式，只需修改OPENAI_BASE_URL。

4.5 终端交互主流程

主流程的目标是“一章一章”地审查。每次显示一个章节，询问用户是继续、跳过还是退出。

# 文件路径：code-review-tool/review.py def main(): diff_text = get_diff() if not diff_text.strip(): print("没有检测到代码变更。") return chapters = split_diff_by_file(diff_text) print(f"共发现 {len(chapters)} 个变更文件，开始逐章审查。\n") total_issues = 0 for idx, chapter in enumerate(chapters, start=1): print(f"\n{'='*60}") print(f"[章节 {idx}/{len(chapters)}] 文件: {chapter['file']}") print(f"{'='*60}") # 先展示变更内容 print("\n--- 变更内容（前 80 行）---") diff_lines = chapter["content"].splitlines() preview_lines = diff_lines[:80] print("\n".join(preview_lines)) if len(diff_lines) > 80: print(f"... 还有 {len(diff_lines) - 80} 行变更未显示") # 调用 LLM 分析 print("\n--- AI 审查意见 ---") review_result = review_with_llm(chapter["file"], chapter["content"]) print(review_result) # 人工决定是否继续 while True: choice = input("\n下一步 [n=下一章, s=跳过, q=退出]: ").strip().lower() if choice in ("n", "next", ""): break elif choice in ("s", "skip"): print("已跳过当前章节。") break elif choice in ("q", "quit"): print("审查结束。") return else: print("无效输入，请输入 n / s / q。") print("\n全部章节审查完成。") print(f"共审查 {len(chapters)} 个文件。") if total_issues: print(f"估计问题数量：{total_issues}") if __name__ == "__main__": main()

这里total_issues变量目前只是一个占位，实际项目中可以由 AI 返回的文本中提取问题数量，或者由用户在人工确认后手动标记。

4.6 运行与验证

给脚本添加可执行权限后运行：

chmod +x review.py python3 review.py

预期输出大致如下：

共发现 3 个变更文件，开始逐章审查。 ============================================================ [章节 1/3] 文件: src/utils/format.py ============================================================ --- 变更内容（前 80 行）--- diff --git a/src/utils/format.py b/src/utils/format.py index 1234567..89abcde 100644 --- a/src/utils/format.py +++ b/src/utils/format.py @@ -10,6 +10,8 @@ def format_number(value): if value is None: return "0" + if value < 0: + return f"({abs(value)})" return str(value) --- AI 审查意见 --- - [中] 当传入负数时，返回格式为 `(10)`，但调用方其他地方可能期望纯数字字符串，建议搜索所有调用点确认格式约定。 - [低] 新增逻辑没有单元测试，建议添加负数场景用例。 下一步 [n=下一章, s=跳过, q=退出]: n

这套工具虽然简单，但已经具备了“分章审查”的核心能力。你可以把它看作一个最小可运行版本，后续可以扩展很多功能，例如：

• 支持按 hunk 拆分超大文件。
• 使用rich库美化终端输出。
• 把审查结果导出为 Markdown 报告。
• 接入评论 API，直接把问题发回 MR。

下面是扩展后的实现思路片段，使用rich高亮：

pip install rich

from rich.console import Console from rich.table import Table console = Console() def print_summary(chapters: list[dict], verdicts: list[str]): table = Table(title="审查汇总") table.add_column("文件") table.add_column("结论") for ch, verdict in zip(chapters, verdicts): table.add_row(ch["file"], verdict) console.print(table)

---

5. 常见问题与排查思路

在终端审查工具的使用过程中，比较容易踩到下面几个问题，整理成排查表供参考。

问题现象	常见原因	解决思路
git diff没有输出	误以为当前目录不是 Git 仓库，或工作区干净	先执行git status确认仓库状态；再确认是否在仓库根目录执行命令
输出乱码	终端编码不是 UTF-8，或 diff 包含二进制文件	设置export LANG=en_US.UTF-8；文本文件可执行git config core.quotepath false
解析 diff 时漏掉文件	简单的split_diff_by_file未处理重命名、新文件头部	改用unidiff库解析，或增加对rename to、new file mode的兼容判断
API 调用超时	网络不通、代理配置异常或模型响应过长	先执行curl $OPENAI_BASE_URL/chat/completions测试连通性；增大timeout参数；确认 API Key 有效
模型返回内容不可读	temperature 过高导致输出发散；提示词不清晰	把temperature降低到 0.2 左右；用系统提示词固定输出格式
大文件 diff 太长	单文件几十 MB，或 diff 包含生成代码	增加文件大小上限，超过阈值时只分析前 N 行，或跳过该文件并提示人工审查
Windows 终端运行报错	Python 路径或 shell 语法差异	在 WSL 2 中运行；或使用python代替python3（视环境而定）

排查顺序建议：

1. 先跑最小命令，例如git diff HEAD | head -50，确认 Git 输出正常。
2. 再跑python3 review.py，观察脚本是否能读到 diff。
3. 如果 AI 分析失败，单独用curl测试接口，排除网络和 Key 问题。
4. 如果解析异常，把diff内容保存到文件，用测试脚本单独解析。

---

6. 审查效率与工程最佳实践

6.1 提交历史与 MR/PR 拆分

工具只能辅助审查，代码是否好审，很大程度取决于开发者在提交阶段是否做了合理的拆分。这里给项目团队几条实际建议：

• 每个 commit 只做一件事：一个 commit 尽量对应一个逻辑变更，例如“修复登录接口的空指针”“新增订单导出功能”。不要把格式化、重构、业务改动混在一起。
• MR/PR 控制在可评审范围：单次 MR 的代码变更尽量控制在 400 行以内。超过这个规模，建议先合并父任务的分支，分多次评审。
• 用提交信息辅助审查者：提交信息里写清楚“是什么”和“为什么”，比代码注释更能帮助审查者快速进入状态。

6.2 审查清单化

人工审查时，最怕的是凭感觉、抓到什么看什么。建议给自己准备一份固定的审查清单，例如：

• [ ] 本次变更是为了修复还是新增功能？改动与描述一致吗？
• [ ] 有没有改动公共接口却未更新调用方？
• [ ] 边界条件是否覆盖：空值、超长字符串、非法输入、并发场景？
• [ ] 数据持久化是否有事务保证？异常回滚是否安全？
• [ ] 是否有日志输出？日志中会不会泄露敏感信息？
• [ ] 测试是否覆盖新增或修改逻辑？
• [ ] 是否有循环依赖、重复代码、不合理的耦合？

当审查对象很大时，把清单与章节结合：每个章节至少核对三条与本章相关的条目，避免遗漏。

6.3 自动化与人工结合

AI 辅助审查也不能完全替代人工。目前的 LLM 在单文件、小范围的逻辑审查上表现不错，但在跨文件影响面、团队代码规范、历史上下文、架构约束等方面仍然存在盲区。

建议的分层策略是：

1. 静态扫描优先：使用 ESLint、SonarQube、PyLint 等工具先扫一遍语法和常见问题。
2. LLM 辅助初筛：用终端工具按章节浏览，先让 AI 给出初步意见。
3. 人工重点复核：AI 标出的中/高风险问题必须人工确认；AI 没有提示但改动密集的关键业务逻辑，也要人工看一遍。
4. 评论归档：把确认的问题以评论形式发回 MR，保证有迹可循。

6.4 安全与权限边界

如果审查工具运行在 CI 或服务器上，需要注意几个问题：

• 最小权限原则：工具只需要读取代码的权限，不要给整个仓库的写入权限。
• API Key 管理：不要把密钥写入配置文件；优先使用环境变量或密钥管理服务（如 Vault、云厂商的 Secrets Manager）。
• 敏感信息过滤：diff 中可能包含数据库连接串、密码、Token。在发送给 LLM 之前，建议先扫描并替换敏感字段。
• 生产环境变更：如果审查的代码涉及生产数据库结构的变更，切勿直接在测试环境或生产环境执行DROP、TRUNCATE、UPDATE一类高危 SQL。所有变更先在小范围测试环境验证，并做好备份与回滚方案。

6.5 性能优化

当项目仓库历史庞大时，需要注意终端审查的性能：

• 避免每次执行都拉取全仓库 diff；用git diff HEAD~1或指定分支范围。
• 大文件的 diff 生成可能较慢，可以先git diff --stat查看变更统计，再决定是否查看详情。
• 若在 CI 中批量审查，可以把章节分发给多个 worker，并行调用 LLM，缩短总耗时。

---

7. 总结与下一步学习建议

这套“终端分章审查”方案，核心并不是某个具体工具，而是一种审查思路：把大型代码变更拆成可独立消化的小单元，降低认知负荷，再用终端和 AI 辅助提高效率。实现一个最小工具只需要几十行 Python，但它带来的工作流变化是巨大的。

值得继续深入的方向：

• 学习 Git 的高级 diff 和 patch 操作，比如git apply、git format-patch、git log -p，把终端审查和日常开发组合得更顺滑。
• 研究 unidiff 等 diff 解析库，把工具做得更健壮，支持重命名、二进制文件、子模块等场景。
• 把 LLM 审查看作一个“初筛助手”，用提示词工程让输出更贴合团队规范，例如自定义输出 JSON 结构，方便程序化处理。
• 把审查工具接入 Git Hook 或 CI 流程，实现提交前自动检查，把问题拦截在更早阶段。
• 如果你想系统化提升 Code Review 技能，可以从“如何写可评审的 MR 描述”“如何高效回复 review 意见”“如何做安全专项审查”这几个方向逐一学习。

最后想提醒的是：无论工具多方便，Code Review 的核心仍然是“人”。终端能让你更快地读完代码，AI 能帮你找到容易忽略的问题，但最终决定代码是否合并、是否重构、是否补测试的，还是你的判断力。把这些工具当作放大注意力的杠杆，而不是替代思考的捷径，才能长期受益。

如果你在实际使用中踩到了不同的坑，或者有其他好用的终端审查技巧，欢迎在评论区分享。