1. 为什么我要自己搭一套 open-code-review团队里代码评审这件事说多了都是泪。项目一多人一忙PR 挂三天没人看是常态好不容易有人看了留一句“这里再优化下”就完事新人根本不知道优化什么。更麻烦的是评审标准全靠个人经验A 觉得没问题的写法 B 能挑出一堆毛病来回拉扯特别消耗精力。我折腾 open-code-review 这套东西核心诉求就一个把代码评审里那些重复的、机械的、有明确规则的检查项交给一个跑在本地的命令行工具去自动完成人只负责看架构、看业务逻辑、看那些真正需要判断力的部分。它不是一个云端 SaaS不需要把代码推到别人服务器上整个流程跑在你自己的机器上用 Git 做版本管理用 LLM Agent 做语义分析通过 CLI 串起来。这套方案适合谁我觉得三类人最值得看一是小团队的技术负责人想给团队立一套统一的评审基线又不想买商业工具二是独立开发者自己写自己审想有个“第二双眼睛”帮忙兜底三是刚接触 code review 流程的新人想搞清楚一次规范的评审到底该看哪些维度。它解决的不是“替代人评审”而是“把人从低价值检查里解放出来”。下面我按自己实际搭建和踩坑的顺序把整套东西拆开讲。涉及到的 Git 操作、CLI 工具选型、LLM Agent 的接入方式我都会给出具体命令和参数能直接抄。2. 整体设计思路与关键选型2.1 为什么是 CLI 而不是 IDE 插件或 Web 服务一开始我也想过做成 IDE 插件点一下就能审。但实际用下来发现几个问题插件受限于 IDE 版本和语言支持团队里有人用 VS Code 有人用 JetBrains维护两套成本太高Web 服务又涉及代码上传安全合规上过不去。CLI 的好处是它天然跨编辑器、跨平台只要机器上有 Git 和终端就能跑接进 CI 也方便。更重要的是CLI 的输入输出都是文本流这意味着它可以被组合。我可以把 open-code-review 的输出直接管道给 grep 过滤也可以写进文件再喂给别的工具。这种“可组合性”是插件和 Web 服务给不了的。热词里频繁出现的 codex cli、claude cli、trae cli 其实都是同一个思路——把能力收敛到一个命令行入口剩下的交给用户自己编排。2.2 LLM Agent 在这里扮演什么角色很多人分不清 agent、LLM、AI 模型这几个词。我用大白话解释一下AI 模型是“大脑”比如 DeepSeek、GPT 这类它本身只会根据输入吐输出LLM 是“大语言模型”的统称DeepSeek 就属于 LLM 的一种Agent 则是“给大脑装上手脚和记忆”之后的东西它能自己决定调用什么工具、分几步完成任务。在 open-code-review 里Agent 的价值在于它能做多步推理。比如看到一段代码它先判断这是业务逻辑还是工具函数再决定要不要去查这个函数的调用方最后才给出评审意见。如果只用裸的 LLM你只能把 diff 一股脑塞进去问“有没有问题”效果差很多。我实测下来带 Agent 编排的评审准确率比单次 LLM 调用高出一大截尤其是涉及跨文件引用的时候。2.3 用 Git 做评审的数据底座整套流程的数据来源就是 Git。评审的对象是 diff评审的历史可以存成 Git note 或者单独的评审分支评审规则本身也可以纳入版本管理。热词里 git worktree、git commit --amend、git diff 这些命令在这里都有实际用途。我特别推荐用git worktree来隔离评审环境。原因是评审时经常需要切到目标分支去看完整文件如果直接在开发目录里切来切去很容易把没提交的改动搞乱。worktree 可以让你在另一个目录里检出同一个仓库的某个分支互不干扰。命令很简单git worktree add ../review-workspace feature-branch这样../review-workspace就是一个独立的工作目录评审完直接git worktree remove删掉干净利落。3. 环境准备与核心工具链搭建3.1 Git 安装与基础配置的坑Windows 上装 Git 我建议直接去官网下安装包安装时注意两个选项一是“Adjusting your PATH environment”选第二项“Git from the command line and also from 3rd-party software”这样在 Windows Terminal 和 PowerShell 里都能直接用 git 命令二是换行符处理选“Checkout as-is, commit Unix-style line endings”避免跨平台协作时满屏的换行符 diff。装完先配身份这是提交记录的基础git config --global user.name 你的名字 git config --global user.email 你的邮箱如果团队用 Gitee还需要配 SSH 密钥。生成密钥后把公钥贴到 Gitee 的 SSH 设置里ssh-keygen -t ed25519 -C 你的邮箱 cat ~/.ssh/id_ed25519.pub注意生成密钥时如果提示文件已存在不要直接覆盖先确认旧密钥是否还在用。我就干过覆盖了旧密钥导致另一台机器拉不了代码的事。3.2 CLI 工具的选择与安装open-code-review 本身是一个 CLI 入口它需要调用底层的 LLM 能力。这里有个常见报错值得先说unable to locate the codex cli binary or required runtime。这个错误的意思是系统找不到你配置的 CLI 可执行文件通常是安装路径没进 PATH或者版本不匹配。我的做法是把所有相关 CLI 统一装到一个目录下然后把这个目录加进 PATH。以类 Unix 系统为例mkdir -p ~/tools/cli export PATH$HOME/tools/cli:$PATH把这行 export 写进~/.bashrc或~/.zshrc重开终端就生效。Windows 上则在“系统属性-环境变量”里把目录加进 Path。安装完成后一定要验证open-code-review --version能打印版本号才算装好。热词里提到的codex --version能查看版本但终端里用不了八成是 PATH 没配好或者装在了某个虚拟环境里没激活。3.3 评审规则的目录结构设计我习惯在仓库根目录建一个.review/目录里面放三类东西rules/评审规则每条规则一个 YAML 文件写明检查项、严重级别、适用文件类型prompts/给 LLM Agent 的提示词模板按评审维度分文件history/评审结果存档按 commit hash 命名这样设计的好处是规则和代码一起走版本管理谁改了规则、为什么改git log 里一目了然。新人 clone 下来就能看到团队积累的评审经验比口头传授靠谱得多。4. 核心评审流程的实操拆解4.1 从 diff 提取到评审任务生成评审的第一步是拿到“改了什么”。这里不要用git diff的默认输出因为它对新增文件、重命名、二进制文件的处理不够清晰。我推荐用git diff --no-optional-locks --find-renames --find-copies --unified5 main...HEAD几个参数解释一下--no-optional-locks避免在评审时因为锁文件冲突卡住--find-renames和--find-copies让重命名和复制能被识别出来不然会显示成删一个文件加一个文件评审时容易误判--unified5把上下文从默认 3 行扩到 5 行给 LLM 更多判断依据。拿到 diff 后open-code-review 会把它拆成一个个“评审单元”。拆分的逻辑是按文件加变更块hunk来分每个单元独立送进 Agent。这样做的好处是单个任务上下文小、响应快而且某个单元评审失败不影响其他单元。4.2 规则引擎与 LLM 的分工不是所有检查都值得动用 LLM。我把检查项分成两层第一层是规则引擎处理确定性检查比如文件是否超过 500 行、函数是否超过 50 行、是否有 console.log 残留、是否有 TODO 没关联 issue 号。这些用正则和 AST 就能搞定快且零成本。第二层才是 LLM Agent处理需要理解的检查比如命名是否表意清晰、异常处理是否完整、边界条件是否考虑、有没有潜在的并发问题。这个分工很关键。我见过有人把所有检查都丢给 LLM结果又慢又贵而且简单的格式问题它还会漏。规则引擎先过滤一遍LLM 只处理剩下的整体效率能提升好几倍。4.3 提示词模板的写法给 Agent 的提示词我踩过不少坑。最开始写得太笼统——“请评审这段代码”结果它什么都点评重点全无。后来改成结构化模板效果稳定很多。我的模板大致长这样你是一名资深评审者正在评审 {language} 代码。 变更背景{commit_message} 评审重点{focus_areas} 请按以下格式输出 1. 严重问题会导致 bug 或安全问题 2. 改进建议可读性、性能 3. 亮点写得好的地方 对每条问题给出文件行号、问题描述、修改建议。 如果某类没有问题写“无”。关键是“变更背景”这一项。把 commit message 喂进去Agent 能理解这次改动的意图评审时就不会把“故意为之”当成“错误”。比如一次重构提交它就不会纠结函数被改名了。4.4 评审结果的聚合与输出每个评审单元跑完后结果需要聚合。我用的格式是 Markdown因为可以直接贴到 PR 评论里。聚合时按严重级别排序严重问题置顶。同时记录每个问题的来源规则引擎还是 LLM方便后续调优。输出到终端时用颜色区分级别输出到文件时用纯文本。这里有个小技巧把结果同时写一份 JSON 格式到history/目录后续可以做统计分析比如“哪类问题出现频率最高”反过来优化规则。5. 常见问题与排查实录5.1 CLI 找不到可执行文件的排查路径unable to locate the codex cli binary这类报错排查顺序我总结成一张表排查项检查方法常见原因PATH 是否包含安装目录echo $PATH安装后没重开终端可执行文件是否存在ls 安装目录安装中断或权限不足版本是否匹配工具名 --version装了旧版本是否在虚拟环境内which 工具名环境未激活我遇到最多的是第一种装完忘了重开终端。其次是 Windows 上装到了用户目录但没加进系统 Path。5.2 LLM 调用失败的几种典型情况login failed. check api token这个报错通常是 token 过期或没配。我的做法是把 token 放在环境变量里不写进配置文件export REVIEW_API_TOKEN你的token这样既避免 token 进版本库也方便在不同机器上切换。另外要注意 token 的权限范围只给评审需要的读权限不要给写权限。还有一种情况是调用超时。评审大文件时经常遇到解决办法是限制单个评审单元的大小超过阈值的文件先拆分再送。我在规则里设了 800 行的上限超过就提示“文件过大建议拆分”。5.3 Git 操作中的疑难杂症git commit --amend用错场景是高频问题。它只能改最近一次提交如果已经 push 到远程amend 后需要 force push团队协作时容易覆盖别人的提交。我的原则是本地未 push 的提交随便 amend已 push 的一律用新提交修正。git worktree用完记得清理否则会残留一堆工作目录。查看现有 worktreegit worktree list删除不需要的git worktree remove ../review-workspace如果目录被手动删了但记录还在用git worktree prune清理。5.4 评审结果误报的处理LLM 评审难免误报比如把某种设计模式当成坏味道。我的处理方式是建一个“豁免清单”把确认是误报的模式记下来下次评审时先过一遍豁免清单。豁免清单也纳入版本管理团队共享。另外提示词里加一句“如果不确定标记为待确认而不是严重问题”能有效降低误报带来的干扰。评审者看到“待确认”会自己去判断而不是被“严重问题”吓一跳。6. 把评审接进日常工作流6.1 本地提交前的自检我给自己配了一个 pre-push 钩子push 前自动跑一遍 open-code-review只跑规则引擎那层几秒钟出结果。有问题就拦下来没问题才放行。这样能挡掉大部分低级问题不至于让它们进到 PR 阶段浪费别人时间。钩子脚本放在.git/hooks/pre-push记得加执行权限chmod x .git/hooks/pre-push6.2 与 CI 的衔接CI 里跑完整评审包括 LLM 那层。结果作为构建产物存档同时在 PR 里留评论。这里要注意 CI 环境的 token 配置用 CI 平台提供的密钥管理功能不要硬编码。CI 里跑评审有个好处是环境干净、可复现。本地因为缓存、环境变量差异导致的结果不一致在 CI 里能避免。我一般让 CI 跑全量本地只跑增量。6.3 评审历史的沉淀每次评审结果都存进history/时间长了就是一份团队代码质量档案。我定期做一次统计看哪类问题反复出现然后针对性调整规则或做团队分享。比如发现“空指针未判”出现频率高就在规则里加一条强制检查同时在提示词里加重这个维度的权重。这套东西跑了大半年最大的感受是工具的价值不在于它多智能而在于它把评审这件事变得“可积累”。规则可以沉淀提示词可以迭代历史可以回溯。人还是会累会忘但工具不会。最后分享一个我踩过的坑一开始我把评审规则写得太严几乎每个 PR 都报一堆问题结果大家干脆不看评审结果了。后来我把规则分成“阻断”和“建议”两级只有真正会导致 bug 的才阻断其余都是建议。这样评审结果的可信度上来了大家才愿意认真看。工具是给人用的别让它变成负担。