1. 为什么我要自己搭一套 open-code-review 流程代码审查这件事做过团队协作的人都有体会。理想状态下每次提交都有人认真看、认真提意见合并前把问题拦在门外。现实往往是另一回事提交堆成山审查者扫两眼就点了通过等到线上出问题再回头翻记录发现当时明明有人觉得不对劲但没说出来。更常见的是小团队或者个人项目压根没人帮你审自己写完自己合时间一长代码质量全靠自觉。open-code-review这个标题我理解成两层意思。一层是“开放的代码审查”也就是不依赖某个特定平台的付费功能用开源工具和通用命令行把审查流程搭起来另一层是“把代码审查这件事打开”让审查过程透明、可追溯、可自动化。我最近几个月一直在折腾这套东西核心思路很简单用 Git 做版本底座用 CLI 工具做操作入口用 LLM Agent 做初审助手把人工审查的精力集中到真正需要判断力的地方。这套流程能解决什么问题最直接的是三件事。第一提交前自动跑一遍静态检查和风格校验把低级问题挡在提交之外。第二用 LLM Agent 对 diff 做一轮语义级初审标出可疑逻辑、潜在空指针、边界条件遗漏这类机器能看出来的问题。第三把审查意见结构化落到 Git 的提交信息或者独立的审查记录里方便回溯。适合谁来参考我觉得三类人最合适一是独立开发者没人帮你审代码但想要一道防线二是小团队的技术负责人想用低成本方式把审查流程规范化三是对 CLI 和 Agent 感兴趣、想动手搭一套自己工具链的工程师。需要提前说明的是下面涉及的所有工具选型、参数配置、脚本写法都是基于我自己的实践和常见做法整理的。不同团队规模、不同技术栈具体落地时肯定要调整。我会把“为什么这么选”讲清楚你照着改就行。2. 整体设计与核心思路拆解2.1 为什么用 Git 做底座而不是别的代码审查的根基是版本控制。没有版本控制审查就无从谈起因为你连“改了什么”都说不清楚。Git 在这件事上的优势不是它有多先进而是它的对象模型天然适合做 diff 和追溯。每次 commit 是一个快照每个快照有唯一的哈希diff 就是两个快照之间的差异计算。这套机制让审查有了明确的输入一段确定的变更集。我见过有人用文件备份的方式做“审查”比如每次改完复制一份到review/目录然后对比两个文件。这种方式在单人小项目里勉强能用但一旦涉及多人协作、分支合并、历史回溯立刻就崩了。Git 的git diff、git log、git blame这些命令本质上就是为审查场景设计的。git diff告诉你改了什么git log告诉你谁在什么时候改的git blame告诉你每一行代码的最后修改者。这三板斧配合起来审查的基本信息就齐了。还有一个容易被忽略的点Git 的钩子机制。pre-commit、commit-msg、pre-push这些钩子可以在特定时机自动触发脚本。这意味着审查流程可以部分自动化不需要人手动去跑检查。我后面会详细讲怎么用钩子把静态检查和 Agent 初审串起来。2.2 CLI 工具在审查流程里的定位CLI 在这里扮演的是“操作入口”的角色。为什么不用 GUI因为审查流程需要可脚本化、可组合、可远程执行。GUI 工具适合交互式操作但很难嵌入自动化流水线。CLI 工具的输出是文本文本可以管道传递、可以重定向、可以被其他程序解析。这是构建工具链的基本前提。具体到open-code-review这个场景CLI 的用途主要有几个。一是执行 Git 命令获取 diff比如git diff HEAD~1 HEAD拿到最近一次提交的变更。二是调用静态检查工具比如各种 linter把结果输出成统一格式。三是调用 LLM Agent 的接口把 diff 内容发过去拿回审查意见。四是把审查结果写回文件或者提交信息。这四步都可以用 CLI 串起来形成一个可重复执行的脚本。我试过用纯 GUI 的方式做这件事结论是一次性审查可以但想常态化、自动化CLI 是绕不开的。而且 CLI 工具通常更轻量启动快适合频繁调用。2.3 LLM Agent 做初审的边界在哪里这里要先厘清几个容易混淆的概念。Agent、LLM、AI 模型这几个词经常被混用但含义不同。LLM 是 Large Language Model大语言模型比如 DeepSeek、GPT 系列、Claude 系列它们本质上是“文本进、文本出”的模型。Agent 是在 LLM 基础上加了一层“行动能力”的系统它能调用工具、执行命令、根据结果决定下一步做什么。Embedding 则是把文本转成向量的技术常用于相似度检索和审查场景关系不大。在代码审查里LLM 能做的是“读 diff、找问题、给建议”。它擅长识别模式化的缺陷比如变量未定义就使用、条件分支覆盖不全、异常处理缺失、命名不一致。它不擅长的是理解业务上下文、判断架构合理性、评估性能影响。所以我的定位很明确LLM Agent 做初审人工做终审。Agent 负责把明显的问题筛出来减少人工审查的负担但最终合并与否还是人说了算。这个边界很重要。如果指望 Agent 全自动审查并合并迟早出事。如果完全不用 Agent人工审查的负担又太重。合理的做法是让 Agent 做“第一道筛子”把 diff 里可疑的地方标出来人工重点看这些标记同时扫一遍整体逻辑。2.4 整体流程的串联方式把上面三块拼起来流程大致是这样开发者在本地完成修改执行git add暂存变更。触发pre-commit钩子钩子里先跑静态检查检查不通过直接阻断提交。静态检查通过后钩子调用一个脚本脚本用git diff --cached拿到暂存的变更发给 LLM Agent 做初审。Agent 返回的意见写入一个临时文件如果意见里有“严重”级别的标记同样阻断提交提示开发者先处理。开发者处理完再次提交通过后进入commit-msg钩子校验提交信息格式。最后git commit完成审查记录随提交一起进入历史。推送时pre-push钩子可以再做一轮检查确保推送到远端的代码是干净的。这套流程的好处是审查发生在提交之前问题在本地就被拦住不会污染远端仓库。而且整个过程是自动的开发者只需要正常写代码、正常提交不需要额外操作。3. 核心细节解析与实操要点3.1 Git 环境准备与基础配置先把 Git 装好、配好这是所有后续操作的前提。Windows 上安装 Git 最省事的方式是去官网下载安装包一路下一步即可。安装完成后打开 Git Bash 或者 Windows Terminal执行git --version确认版本。我建议用较新的版本2.30 以上因为一些钩子相关的特性在新版本里更完善。配置这块最少要设置用户名和邮箱否则提交会报错。命令是git config --global user.name 你的名字 git config --global user.email 你的邮箱如果团队用 Gitee 或者自建 Git 服务还需要配置 SSH 密钥。生成密钥的命令是ssh-keygen -t ed25519 -C 你的邮箱然后把公钥内容复制到平台的密钥设置里。这一步的细节网上教程很多不展开。有一个配置我强烈建议打开git config --global diff.mnemonicPrefix true。这个配置让 diff 输出的前缀更有语义比如i/表示 indexw/表示 worktreec/表示 commit。审查时看 diff 更清楚。另外core.quotepath false也建议设置避免中文文件名被转义成八进制。还有一个容易被忽略的点git worktree。这个功能允许你在同一个仓库里检出多个工作树每个工作树对应不同的分支。审查场景下你可以用一个工作树跑检查脚本另一个工作树正常开发互不干扰。命令是git worktree add ../review-branch review这样就在上级目录创建了一个 review 分支的工作树。3.2 静态检查工具的选型与接入静态检查是审查的第一道防线。它的作用是发现那些“机器一定能看出来”的问题比如语法错误、未使用的变量、明显的风格违规。这类问题不应该浪费人工审查的精力。工具选型取决于技术栈。JavaScript/TypeScript 项目用 ESLintPython 用 Ruff 或 Flake8Go 用 golangci-lintJava 用 Checkstyle 或 SpotBugs。选型的原则是社区活跃、配置灵活、输出格式可解析。我倾向于选那些支持 JSON 或机器可读输出的工具方便后续脚本处理。以 ESLint 为例接入方式是先在项目里安装依赖然后创建配置文件.eslintrc.json定义规则集。运行npx eslint --format json src/就能拿到 JSON 格式的检查结果。脚本里解析这个 JSON提取出错误和警告按严重程度分类。这里有个实操心得静态检查的规则不要一次开太猛。我见过有人直接把所有规则都打开结果每次提交报几百个警告开发者直接无视了。合理的做法是先开核心规则比如no-unused-vars、no-undef、eqeqeq这些等团队适应了再逐步加。规则是服务于人的不是用来炫技的。3.3 LLM Agent 的接入方式与提示词设计LLM Agent 的接入核心是两件事怎么把 diff 发过去怎么把结果拿回来。发送方式取决于你用哪个模型服务。常见的有 HTTP API 调用也有官方提供的 CLI 工具。比如有些模型提供了命令行客户端安装后配置好 API Token就能用命令直接调用。提示词的设计是成败关键。我试过很多版本最后稳定下来的结构是这样的先给角色设定告诉模型“你是一个资深代码审查者”然后给审查标准列出要重点关注的几类问题接着给 diff 内容最后给输出格式要求比如“按严重程度分级每条意见包含文件、行号、问题描述、修改建议”。一个具体的提示词片段你是一名资深代码审查者。请审查以下 Git diff重点关注 1. 逻辑错误条件分支遗漏、循环边界错误、空指针风险 2. 安全问题输入未校验、敏感信息硬编码、注入风险 3. 可维护性命名不清、重复代码、过长函数 4. 性能隐患不必要的循环、重复计算、资源未释放 输出格式 [严重程度] 文件:行号 - 问题描述 - 修改建议 严重程度分为严重、警告、建议 diff 内容 这里插入 diff这个提示词的好处是约束明确模型不容易跑偏。我实测下来加了输出格式约束之后返回结果的结构化程度明显提升后续脚本解析也方便。3.4 审查结果的结构化存储审查结果如果只是打印在终端里看完就没了没法追溯。我的做法是把结果写入一个固定位置的文件比如.review/last-review.md同时把摘要追加到提交信息里。这样每次提交都能看到当时的审查意见。文件格式用 Markdown方便人读也方便后续用脚本解析。结构大概是## 审查时间 2024-XX-XX XX:XX ## 变更摘要 - 修改文件数3 - 新增行数45 - 删除行数12 ## 审查意见 ### 严重 - src/main.js:23 - 变量未定义就使用 - 建议先声明再使用 ### 警告 - src/utils.js:56 - 函数过长建议拆分 ### 建议 - src/main.js:12 - 命名可以更语义化这个文件随提交一起进入 Git 历史后续用git log就能翻到。如果团队用 Gitee 之类的平台还可以把这个文件的内容作为提交评论发上去形成平台内的审查记录。4. 实操过程与核心环节实现4.1 从零搭建审查脚本的完整步骤假设你有一个现成的 Git 仓库现在要加一套自动审查流程。步骤大致如下。第一步在仓库根目录创建.githooks/目录用来存放钩子脚本。为什么不直接用.git/hooks/因为.git/目录不纳入版本控制团队其他成员克隆仓库后拿不到钩子。用.githooks/纳入版本控制然后执行git config core.hooksPath .githooks让 Git 从这个目录读取钩子。第二步创建pre-commit钩子文件内容是一个 shell 脚本。脚本开头是#!/bin/sh然后依次调用静态检查脚本和 Agent 审查脚本。如果任一脚本返回非零退出码钩子就阻断提交。第三步写静态检查脚本scripts/lint.sh。脚本里调用具体的 linter解析输出如果有严重错误就exit 1。第四步写 Agent 审查脚本scripts/agent-review.sh。脚本用git diff --cached拿到暂存变更调用模型接口解析返回结果写入.review/last-review.md。如果结果里有“严重”级别的意见exit 1。第五步创建commit-msg钩子校验提交信息格式。比如要求提交信息以feat:、fix:、docs:等前缀开头长度不超过 72 字符。第六步测试。故意写一段有问题的代码git add后git commit看钩子是否按预期阻断。通过后修正代码再次提交确认流程走通。4.2 关键脚本的写法与参数说明pre-commit钩子的核心逻辑#!/bin/sh echo 开始静态检查... sh scripts/lint.sh if [ $? -ne 0 ]; then echo 静态检查未通过提交已阻断 exit 1 fi echo 开始 Agent 初审... sh scripts/agent-review.sh if [ $? -ne 0 ]; then echo Agent 初审发现严重问题提交已阻断 exit 1 fi echo 审查通过 exit 0这里用$?检查上一条命令的退出码非零就阻断。这是 shell 脚本里最基础的错误处理方式简单可靠。agent-review.sh里获取 diff 的命令是git diff --cached --unified3。--cached表示看暂存区的变更--unified3表示上下文显示 3 行。上下文行数不宜太多否则发给模型的 token 量太大也不宜太少否则模型看不清上下文。3 行是经验值大多数情况够用。调用模型接口的部分假设用的是 HTTP API可以用curlDIFF$(git diff --cached --unified3) PROMPT你是一名资深代码审查者...\n\n$DIFF RESPONSE$(curl -s -X POST https://api.example.com/v1/chat \ -H Authorization: Bearer $API_TOKEN \ -H Content-Type: application/json \ -d {\prompt\: \$PROMPT\}) echo $RESPONSE .review/last-review.md实际使用时要把 API 地址、Token、请求体格式换成你所用服务的真实值。Token 建议放在环境变量里不要硬编码在脚本中。4.3 参数计算与阈值设定审查流程里有几个参数需要根据实际情况调整。第一个是 diff 的最大行数。如果一次提交改了上千行全发给模型既慢又贵而且模型对超长输入的处理质量会下降。我的做法是设一个阈值比如 500 行。超过就只发变更最集中的文件或者提示开发者拆分提交。拆分提交本身就是好习惯一次提交只做一件事审查起来也清晰。第二个是模型返回结果的解析阈值。模型返回的意见里怎么判断哪些是“严重”我的做法是看关键词比如返回里包含“严重”或“critical”就归为严重级别。这个判断不完美但够用。更精细的做法是让模型在输出里带一个结构化的严重程度字段脚本直接解析字段。第三个是超时时间。调用模型接口可能因为网络原因变慢脚本里要设超时避免卡死。curl的--max-time 30表示 30 秒超时。超时后按“审查未完成”处理可以选择放行或者阻断。我倾向于放行但记录日志避免因为网络问题阻断正常开发。4.4 实操现场记录与效果验证我拿一个真实的小项目做了测试。项目是一个 Node.js 写的命令行工具大约 800 行代码。我故意在src/parser.js里加了一段有问题的代码function parseConfig(input) { const lines input.split(\n); const result {}; for (let i 0; i lines.length; i) { const line lines[i].trim(); if (line.startsWith(#)) continue; const [key, value] line.split(); result[key] value; } return result; }这段代码有两个明显问题循环条件i lines.length会导致数组越界lines[i]在最后一次迭代是undefined调用.trim()会抛异常另外line.split()如果行里没有等号value是undefined赋值后结果不对。git add后执行git commit静态检查先跑ESLint 报了no-unused-vars之类的警告但没阻断。接着 Agent 初审跑起来返回结果里明确标出了“循环边界错误”和“解构可能为 undefined”两条严重问题。提交被阻断提示我先处理。我修正代码后再次提交这次通过了。.review/last-review.md里记录了完整的审查意见随提交进入历史。整个过程从触发到阻断大约 8 秒其中模型调用占了 5 秒左右。这个延迟在可接受范围内不会明显影响开发节奏。5. 常见问题与排查技巧实录5.1 钩子不生效的几种原因最常见的问题是钩子根本没执行。原因通常有三个。一是core.hooksPath没配置Git 还在读默认的.git/hooks/目录。用git config core.hooksPath查看当前配置如果为空就说明没设。二是钩子文件没有可执行权限。在 Linux 和 macOS 上需要chmod x .githooks/pre-commit。Windows 上 Git Bash 对权限的处理不太一样通常不强制要求但建议还是加上。三是钩子文件名不对。Git 对钩子文件名是大小写敏感的必须是pre-commit而不是Pre-Commit或pre_commit。排查方法很简单在钩子脚本第一行加echo hook triggered然后执行一次提交看终端有没有输出。没有输出就是钩子没被调用有输出但后续逻辑没跑就是脚本内部的问题。5.2 模型返回结果解析失败的应对模型返回的内容不一定严格符合你要求的格式。有时候会多一段解释有时候严重程度字段写成了别的词。脚本解析时如果按固定格式硬解析很容易失败。我的应对策略是“宽松解析”。不要求完全匹配而是用正则去搜关键词。比如搜严重|critical|high来判断严重级别搜文件|file后面的路径来提取文件名。这样即使格式有偏差也能提取出核心信息。另外在提示词里反复强调输出格式能显著提高格式的稳定性。如果解析完全失败脚本应该把原始返回内容完整记录下来而不是丢弃。记录到.review/raw-response.txt方便事后排查是提示词的问题还是模型的问题。5.3 提交被频繁阻断的处理如果钩子太严格开发者会被频繁阻断体验很差最后可能直接--no-verify跳过钩子。这就失去了自动审查的意义。我的经验是分级处理。静态检查里的“错误”级别阻断提交“警告”级别只提示不阻断。Agent 初审里的“严重”级别阻断“警告”和“建议”级别只记录。这样既保证了关键问题被拦住又不会因为鸡毛蒜皮的小事打断开发节奏。另外可以加一个“紧急通道”。在提交信息里包含[skip-review]时跳过 Agent 初审只跑静态检查。这个通道要慎用但确实需要比如线上出故障需要紧急修复时。5.4 常见问题速查表问题现象可能原因排查方法解决方法钩子不执行hooksPath 未配置git config core.hooksPath执行git config core.hooksPath .githooks钩子执行报权限错误文件无可执行权限ls -l .githooks/chmod x .githooks/*模型调用超时网络慢或输入过长查看脚本日志设--max-time限制 diff 行数解析结果为空返回格式不符预期查看 raw-response.txt调整提示词改用宽松解析提交被误阻断阈值过严查看审查意见调整严重级别判定规则中文文件名乱码quotepath 未关git config core.quotepath设为 falsediff 内容为空没有暂存变更git status先git add再提交5.5 几个踩过的坑第一个坑是钩子脚本里的路径问题。pre-commit钩子执行时工作目录是仓库根目录但如果你在子目录里执行git commit钩子里的相对路径可能不对。稳妥的做法是在脚本开头cd $(git rev-parse --show-toplevel)强制切到仓库根目录。第二个坑是模型对 diff 格式的理解。有些模型对标准 unified diff 格式的解析不太好会把和-开头的行当成普通文本。解决办法是在提示词里明确说明“以下内容是 unified diff 格式开头是新增行-开头是删除行”。第三个坑是 Token 泄露。我见过有人把 API Token 直接写在脚本里然后提交到仓库这是严重的安全问题。Token 必须放在环境变量或者本地配置文件中配置文件要加入.gitignore。第四个坑是审查记录文件本身被提交。.review/last-review.md每次提交都会变如果纳入版本控制会导致大量无意义的变更。建议把.review/加入.gitignore只把审查摘要写入提交信息不提交记录文件本身。6. 进阶玩法与扩展方向6.1 把审查接入 CI 流水线本地钩子的局限是“可以被绕过”。开发者加--no-verify就跳过了。要强制审查需要在 CI 流水线里再跑一遍。做法是在 CI 配置里加一个步骤拉取代码后执行同样的审查脚本不通过就标记流水线失败阻止合并。CI 环境里没有暂存区的概念所以获取 diff 的方式要改。用git diff HEAD~1 HEAD拿最近一次提交的变更或者用平台提供的“变更集”接口。具体命令取决于 CI 平台但核心逻辑和本地一致。6.2 审查意见的聚合与统计单个提交的审查意见价值有限把一段时间内的意见聚合起来能看出代码质量的趋势。比如统计每周的“严重”意见数量如果持续上升说明代码质量在下降需要引起注意。实现方式是把每次的审查结果追加到一个日志文件格式用 JSON Lines每行一条记录。然后用脚本做聚合分析输出统计报表。这个报表可以在团队周会上过一遍比空泛地说“大家注意代码质量”有说服力得多。6.3 针对不同语言定制审查规则不同编程语言的常见问题不一样。JavaScript 要重点关注异步处理和类型转换Python 要关注缩进和可变默认参数Go 要关注错误处理和 goroutine 泄漏。在提示词里针对语言定制审查重点能提高 Agent 的命中率。我的做法是维护一个规则配置文件按语言分类。脚本根据变更文件的扩展名自动选择对应的规则集拼进提示词。这样一套流程可以服务多种语言的项目。6.4 审查意见的自动修复尝试对于某些模式化的问题比如命名不规范、缺少分号、导入顺序不对可以让 Agent 直接给出修复后的代码人工确认后应用。这比只给建议更进一步能减少手动修改的工作量。但要注意自动修复只适用于低风险、模式化的问题。涉及逻辑变更的修复必须人工判断不能让 Agent 直接改。我的原则是Agent 可以建议但修改动作由人执行。7. 我在这套流程上的一些个人体会这套 open-code-review 流程我用了大概三个月最大的感受是它没有让审查变得“自动化”而是让审查变得“有重点”。以前人工审查要通读所有 diff现在 Agent 先把可疑的地方标出来人工只需要重点看这些标记再扫一遍整体逻辑。审查时间大概减少了四成但发现的问题数量反而多了因为 Agent 能注意到一些人工容易忽略的细节。另一个体会是提示词的质量直接决定审查质量。我前后改了十几版提示词从最初的“帮我看看这段代码”到后来的结构化指令效果差异巨大。提示词这件事没有捷径就是不断试、不断调。建议你从简单版本开始遇到问题再逐步加约束。还有一点不要指望这套流程能替代人的判断。Agent 会误报也会漏报。它的价值在于“减少人工的机械劳动”而不是“替代人工的判断”。把这一点想清楚落地时的心态会好很多。最后分享一个小技巧审查脚本的输出格式尽量用 Markdown因为 Markdown 在终端、在 Git 平台、在文档工具里都能正常渲染。用纯文本或者 JSON 虽然机器友好但人读起来费劲。审查这件事最终还是服务于人的输出格式要优先考虑人的阅读体验。