1. 为什么我要自己搭一套 open-code-review代码审查这件事做过团队协作的人都有体会。理想状态下每次提交都有人认真看、认真提意见但现实往往是提交堆成山审查靠随缘等到上线出了问题再回头翻 commit才发现某一行早就埋了雷。市面上的商业代码审查工具不少但要么按人头收费贵得离谱要么把代码传到别人的服务器上心里总有点不踏实。open-code-review这个项目核心思路就是用开源的方式把代码审查这件事自动化、本地化。它本质上是一个跑在命令行的工具通过 Git 钩子或者手动触发把代码变更喂给一个 LLM Agent让模型按照预设的规则去检查代码最后输出一份结构化的审查报告。你可以把它理解成一个随叫随到的审查员它不会累、不会漏、不会因为跟你关系好就放水。这套东西适合谁用我总结了三类人一是小团队里没有专职审查者的开发者二是想在自己项目里加一道质量防线的独立开发者三是对 LLM Agent 和 CLI 工具链感兴趣、想拿个真实项目练手的技术爱好者。不管你之前有没有用过类似的工具只要你会基本的 Git 操作就能把这套流程跑起来。我搭这套东西的起因很简单手头有几个项目提交频率高人工审查根本跟不上。试过几个在线服务要么配置复杂要么数据要出境最后决定自己动手。下面把我从选型、搭建到踩坑的完整过程拆开讲尽量把每个决策背后的逻辑说清楚让你少走弯路。2. 整体设计与技术选型拆解2.1 核心架构CLI Git LLM Agent 的三层结构open-code-review的架构不复杂但每一层都有讲究。最底层是 Git负责提供代码变更的原始数据中间层是 CLI 工具本身负责调度和编排最上层是 LLM Agent负责实际的代码分析和意见生成。为什么用 CLI 而不是做个 Web 服务这里有个很实际的考量。代码审查这个动作天然发生在开发者的本地环境里。你刚写完代码顺手跑一条命令就能看到审查结果这个体验比打开浏览器、登录、上传代码要顺畅得多。而且 CLI 工具容易集成到现有的工作流里比如 Git 钩子、CI 流水线不需要额外维护一套服务。Git 这一层的作用被很多人低估了。open-code-review不是把整个代码库丢给模型而是只分析变更部分。这背后依赖的是git diff系列命令。具体来说工具会先确定审查范围——是暂存区的变更、最近一次提交还是两个分支之间的差异——然后提取出对应的 diff 内容。这样做的好处很明显一是节省 token二是让模型聚焦在真正改动的地方避免被大量无关代码干扰。LLM Agent 这一层是整个工具的大脑。这里要区分几个容易混淆的概念LLM 是底层的大语言模型比如 DeepSeek、GPT 系列Agent 是在 LLM 之上加了一层思考-行动循环的封装它能决定什么时候调用工具、什么时候输出结果而 CLI 只是 Agent 的一个交互入口。open-code-review用的是 Agent 模式不是简单地把 diff 拼成 prompt 丢给模型。Agent 会先分析变更的类型新增功能、修复 bug、重构然后决定用哪些检查规则最后才生成审查意见。2.2 为什么选 Agent 模式而不是直接调 API直接调 LLM API 做代码审查最省事但效果往往不理想。原因在于代码审查是一个多步骤的推理过程不是单次问答能搞定的。举个例子审查一段新增的函数你需要先理解这个函数要做什么再检查它的实现有没有逻辑漏洞然后看它有没有遵循项目的代码规范最后还要考虑它跟现有代码的兼容性。这一连串动作如果塞进一个 prompt 里让模型一次性输出模型很容易顾此失彼。Agent 模式的好处在于它可以把这些步骤拆开每一步都有明确的输入和输出。open-code-review的 Agent 通常会走这么几轮第一轮识别变更意图第二轮按规则逐项检查第三轮汇总生成报告。每一轮都可以调用不同的工具比如读取项目配置文件、查询历史提交记录、运行静态检查工具。这种分而治之的策略实测下来比单次调用准确率高不少。当然Agent 模式也有代价调用次数多延迟高token 消耗大。所以open-code-review在实现上做了取舍——对于简单的变更比如改个文案、调个格式走快速通道单次调用就出结果对于复杂的变更比如新增模块、修改核心逻辑才启用完整的 Agent 流程。这个判断逻辑本身也是由模型来做的算是用魔法打败魔法。2.3 工具链选型Git 配置与 CLI 环境准备在动手之前得先把基础环境搭好。这部分看起来琐碎但配置不对后面全是坑。Git 的安装和配置是第一步。Windows 用户直接去官网下载安装包安装时注意几个选项默认编辑器建议选 VS Code 或者 Vim看你顺手PATH 环境变量一定要选Git from the command line and also from 3rd-party software否则后面 CLI 工具调不到 git 命令换行符处理选Checkout Windows-style, commit Unix-style line endings这是跨平台协作的稳妥选择。安装完之后配置用户信息git config --global user.name 你的名字 git config --global user.email 你的邮箱这两条命令写入的是全局配置存在~/.gitconfig文件里。如果你有多个项目用不同的身份可以在项目目录下再跑一遍不带--global的命令覆盖全局设置。接下来是 SSH 密钥配置如果你用 Gitee 或者自建的 Git 服务这一步绕不开ssh-keygen -t ed25519 -C 你的邮箱生成的公钥默认在~/.ssh/id_ed25519.pub把它复制到 Git 服务的 SSH 密钥设置里就行。测试连接ssh -T gitgitee.com看到欢迎信息就说明配置成功了。CLI 工具这边open-code-review本身是个 Node.js 项目所以需要先装 Node.js。建议用 nvm 或者 fnm 来管理版本避免不同项目之间的版本冲突。装完之后全局安装npm install -g open-code-review或者用 npx 直接跑不装到全局npx open-code-review --help我个人习惯用 npx因为不污染全局环境而且能确保每次用的都是最新版本。3. 核心细节解析与实操要点3.1 Git diff 的提取与预处理open-code-review最核心的一步是把 Git 的变更数据提取出来转成模型能理解的格式。这一步做得好不好直接决定了审查质量。工具默认审查的是暂存区的变更也就是你git add之后但还没git commit的内容。对应的命令是git diff --cached如果你想审查最近一次提交用git diff HEAD~1 HEAD如果想审查两个分支之间的差异比如当前分支和主分支git diff main...HEAD这里有个细节要注意git diff的输出格式是统一的 diff 格式包含文件路径、变更位置、增删行等信息。但模型直接读这个格式效果不一定好因为 diff 里的上下文行没有变更的行会占用大量 token。所以open-code-review在提取之后会做一轮预处理去掉纯上下文的行只保留变更行和必要的上下文通常是变更行前后各三行。预处理还有一个作用是过滤噪音。比如package-lock.json、yarn.lock这类自动生成的文件变更内容没有审查价值工具会自动跳过。这个过滤规则可以在配置文件里自定义后面会讲。提示如果你的项目里有大量自动生成的文件建议在.gitattributes里把它们标记为linguist-generated这样open-code-review会自动识别并跳过。3.2 LLM Agent 的提示词设计Agent 的效果七分靠提示词。open-code-review的提示词设计有几个关键点值得单独拎出来说。第一点是角色设定。提示词开头会明确告诉模型你是一个经验丰富的代码审查者你的任务是找出代码中的问题而不是夸奖代码写得好。这个设定很重要因为模型默认倾向于说好话如果不加约束审查报告会变成彩虹屁大全。第二点是检查清单。工具内置了一套检查规则涵盖常见的代码问题空指针风险、边界条件、错误处理、命名规范、注释完整性、性能隐患等。这些规则不是一股脑塞给模型而是根据变更类型动态选择。比如变更涉及数据库操作就重点检查 SQL 注入和事务处理变更涉及网络请求就重点检查超时和重试逻辑。第三点是输出格式。工具要求模型按固定的 JSON 结构输出包含问题等级严重、警告、建议、问题位置文件、行号、问题描述、修复建议。这样做的好处是输出可以被程序解析方便后续集成到 CI 流水线或者生成 HTML 报告。我实测下来提示词里加一句如果你不确定某个问题是否成立标记为建议而不是严重能显著降低误报率。模型有时候会过度自信把一些风格问题当成严重 bug 报出来加上这个约束后会收敛很多。3.3 配置文件详解与自定义规则open-code-review的配置文件默认叫.open-code-review.json放在项目根目录。这个文件控制工具的行为几个关键字段{ model: deepseek-chat, apiBase: https://api.deepseek.com, maxDiffLines: 500, ignorePatterns: [*.lock, dist/**, *.min.js], rules: { security: true, performance: true, style: false }, language: zh-CN }model字段指定用哪个模型。这里要说明一下open-code-review本身不绑定特定模型只要模型提供兼容 OpenAI 格式的 API 就行。DeepSeek、通义千问、本地部署的模型都可以接。选模型的时候代码能力是首要考量其次才是价格。我试过几个模型代码审查这种任务模型之间的差距比想象中大建议先用小样本测试再决定。maxDiffLines控制单次审查的最大变更行数。超过这个数工具会自动分批处理。这个值设太小会导致审查不完整设太大又会超出模型的上下文窗口。我的经验是500 行是个比较平衡的值对应大约 8000 到 10000 token 的输入。ignorePatterns是文件过滤规则支持 glob 语法。除了自动生成的文件测试文件、文档文件也可以考虑加进去除非你希望模型也审查测试代码。rules字段控制检查规则的开关。安全类和性能类的规则建议默认开启风格类的规则看团队习惯。如果团队有 ESLint 或者 Prettier 这类工具管风格open-code-review的风格检查就可以关掉避免重复。注意配置文件里的 API 密钥不要直接写明文用环境变量引用。工具支持${ENV_VAR}语法比如apiKey: ${OPEN_CODE_REVIEW_KEY}。4. 实操过程与核心环节实现4.1 从零搭建安装、配置、首次运行我把完整的搭建过程走一遍你可以跟着操作。第一步确认 Git 和 Node.js 都装好了git --version node --version npm --version三个命令都能输出版本号说明环境没问题。如果git命令报不是内部或外部命令说明 Git 的 PATH 没配好重新跑一遍安装程序选上Git from the command line那个选项。第二步安装open-code-reviewnpm install -g open-code-review如果网络慢可以换国内镜像源npm config set registry https://registry.npmmirror.com第三步在项目根目录初始化配置open-code-review init这个命令会生成一个.open-code-review.json模板文件你需要填入模型信息和 API 密钥。密钥建议通过环境变量传入export OPEN_CODE_REVIEW_KEY你的密钥Windows 用户用set命令或者直接在系统环境变量里配。第四步跑一次审查open-code-review review默认审查暂存区的变更。如果暂存区是空的工具会提示你先git add。你也可以指定审查范围open-code-review review --range HEAD~3..HEAD这条命令审查最近三次提交的变更。4.2 集成到 Git 钩子实现自动审查手动跑审查容易忘集成到 Git 钩子里才能形成习惯。open-code-review提供了钩子安装命令open-code-review install-hook这个命令会在.git/hooks/pre-commit里写入一段脚本每次git commit之前自动触发审查。如果审查发现严重问题提交会被阻止你需要先修复再提交。钩子的工作流程是这样的git commit触发 pre-commit 钩子钩子调用open-code-review review --staged工具提取暂存区的 diff发给模型审查如果发现问题等级为严重返回非零退出码Git 就会中止提交。这里有个坑要注意钩子脚本的执行环境可能跟你的终端环境不一样特别是环境变量。如果你把 API 密钥配在.bashrc或者.zshrc里钩子可能读不到。稳妥的做法是把密钥配在系统级环境变量里或者在项目目录下放一个.env文件工具会自动读取。另一个坑是审查耗时。模型调用有延迟如果每次提交都等十几秒体验会很差。我的做法是钩子里只做快速检查单次调用不启用完整 Agent 流程完整的审查放到 CI 流水线里跑。open-code-review支持--quick参数就是干这个的。4.3 在 CI 流水线中运行完整审查CI 流水线里的审查可以跑得慢一点但要求更全面。以 GitHub Actions 为例配置文件大概长这样name: Code Review on: pull_request: branches: [main] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/setup-nodev4 with: node-version: 20 - run: npm install -g open-code-review - run: open-code-review review --range origin/main...HEAD --output report.json env: OPEN_CODE_REVIEW_KEY: ${{ secrets.OPEN_CODE_REVIEW_KEY }} - uses: actions/upload-artifactv4 with: name: review-report path: report.json这里fetch-depth: 0很关键它让 checkout 拉取完整的提交历史否则git diff拿不到两个分支之间的差异。--output report.json把审查结果输出到文件方便后续处理比如发到 PR 评论里。如果你用 Gitee 的流水线配置逻辑类似只是语法不同。核心是三步装环境、跑审查、传结果。4.4 审查报告的解读与处理审查报告是 JSON 格式结构大概是这样{ summary: { filesChanged: 3, linesAdded: 120, linesRemoved: 45, issues: { critical: 1, warning: 3, suggestion: 5 } }, issues: [ { level: critical, file: src/auth.js, line: 42, message: 用户输入未做校验存在注入风险, suggestion: 在拼接 SQL 之前使用参数化查询 } ] }解读报告的时候重点关注critical级别的问题这些是必须修的。warning级别的问题看情况如果确认是误报可以在配置文件里加规则排除。suggestion级别的问题属于锦上添花有空再改。我个人的习惯是把报告里的问题按文件分组逐个处理。处理完之后在 commit message 里注明fix: 修复审查发现的 XX 问题方便追溯。提示如果某个问题你确认是误报可以在代码里加一行注释// open-code-review: ignore工具会跳过这一行。这个功能在遇到模型钻牛角尖的时候特别有用。5. 常见问题与排查技巧实录5.1 模型调用失败与网络问题最常见的问题就是模型调不通。报错信息通常是login failed或者unable to locate之类的。排查思路分三步先确认 API 密钥对不对。把密钥复制到 curl 命令里直接测curl -X POST https://api.deepseek.com/chat/completions \ -H Authorization: Bearer $OPEN_CODE_REVIEW_KEY \ -H Content-Type: application/json \ -d {model:deepseek-chat,messages:[{role:user,content:test}]}如果 curl 能通说明密钥没问题问题出在工具配置上。检查.open-code-review.json里的apiBase字段注意结尾不要带斜杠路径要跟模型服务商的文档一致。如果 curl 也不通检查网络。有些模型服务商对请求来源有限制或者需要配置代理。这里要说明的是代理配置属于网络环境问题具体怎么配取决于你的网络架构我这边不展开。还有一个容易忽略的点Node.js 的版本。有些模型 SDK 要求 Node.js 18 以上版本太低会报奇怪的错误。用node --version确认一下低了就升级。5.2 审查结果不准确或误报过多模型审查的准确率受几个因素影响。按影响程度排序提示词质量 模型能力 diff 质量。如果误报多先检查提示词。open-code-review的默认提示词已经调过很多轮但不同项目的代码风格差异大可能需要微调。你可以在配置文件里加customPrompt字段追加自己的要求。比如{ customPrompt: 本项目使用 TypeScript忽略所有关于类型注解的建议。 }如果漏报多检查 diff 提取是否完整。有时候git diff的输出被截断了模型看不到完整的变更上下文。调大maxDiffLines试试或者用--verbose参数看工具实际提取了多少行。模型能力这块我的经验是代码审查任务模型之间的差距主要体现在理解意图上。有些模型能看出你这段代码是想做什么然后判断实现对不对有些模型只能做表面检查比如变量名拼写、括号匹配。如果预算允许选代码能力强的模型省下来的审查时间比模型费用值钱。5.3 Git 相关的疑难杂症open-code-review依赖 GitGit 出问题工具就跑不起来。几个高频问题问题一git diff输出为空。最常见的原因是变更没有暂存。git add之后再跑审查。如果确认暂存了还是空检查是不是在错误的目录下执行命令或者.gitignore把变更文件排除了。问题二中文文件名乱码。Git 默认会对非 ASCII 文件名做转义显示成\344\270\255\346\226\207这种形式。解决办法是配置git config --global core.quotepath false这个配置让 Git 直接显示原始文件名不转义。问题三git worktree场景下的审查。如果你用git worktree管理多个工作区每个工作区有自己的暂存区。审查的时候要确认在正确的工作区目录下执行命令否则会审到别的分支的变更。问题四git commit --amend之后的审查。--amend会修改最近一次提交但暂存区的内容可能跟提交内容不一致。审查之前先git status确认状态必要时用git diff HEAD而不是git diff --cached。5.4 常见问题速查表问题现象可能原因排查方法解决方案模型调用报 401API 密钥错误或过期用 curl 直接测密钥重新生成密钥更新环境变量审查结果为空暂存区无变更git status查看先git add再审查中文文件名乱码Git 默认转义查看 diff 输出git config core.quotepath false钩子不触发钩子文件无执行权限ls -l .git/hooks/pre-commitchmod x加执行权限审查超时diff 太大或模型响应慢查看 diff 行数调小maxDiffLines或分批审查误报过多提示词不适配项目检查报告内容加customPrompt微调Node 版本报错版本过低node --version升级到 18 以上6. 我踩过的坑和几条实在建议搭这套东西的过程中我踩的坑不算少挑几个有代表性的说说。第一个坑是过度依赖自动审查。刚开始我把所有审查都交给工具人工只看报告。结果有一次工具漏掉了一个并发问题上线后出了故障。后来我调整了策略工具负责扫雷把明显的问题筛出来人工负责把关重点看核心逻辑和边界条件。两者是互补关系不是替代关系。第二个坑是提示词写得太长。我一开始想把所有规则都塞进提示词结果模型反而抓不住重点审查质量下降。后来精简到只保留最关键的几条效果反而更好。这印证了一个道理提示词不是越长越好关键是信息密度。第三个坑是忽略了成本控制。Agent 模式调用次数多如果每次提交都跑完整流程月底账单会很难看。我的做法是分级触发本地提交走快速检查PR 走完整审查定期比如每周跑一次全量扫描。这样既保证了覆盖率又控制了成本。几条实在建议一是先用小项目试水跑顺了再上大项目二是审查规则要跟团队对齐别让工具报一堆团队根本不关心的问题三是定期回顾审查报告看看哪些问题是反复出现的从根源上解决而不是每次都靠工具提醒。最后分享一个小技巧open-code-review支持把审查结果输出成 Markdown 格式直接贴到 PR 评论里。命令是--format markdown。这样团队成员不用装工具在 PR 页面就能看到审查意见协作效率高不少。