1. 为什么我要自己搭一套 open-code-review代码审查这件事做过团队协作的人都有体会。理想状态下每次提交都有人认真看、认真提意见但现实往往是项目赶进度PR 堆了十几个没人理或者 reviewer 自己也很忙扫两眼就点了 approve。时间一长代码质量全靠个人自觉技术债越滚越大。我所在的团队规模不大七八个人后端前端加起来每天大概有二十到三十次提交。之前试过几种方案纯人工 review累且慢用 SaaS 类的代码审查工具贵且数据要往外传也试过一些开源的静态分析工具但规则太死误报率高大家用了一阵就都不看了。后来我琢磨着能不能用 LLM 来做这件事。不是让它替代人而是让它当第一道筛子——把明显的风格问题、潜在 bug、安全隐患先过一遍人工只需要看它标记出来的重点。这样既省时间又能保证基本质量。open-code-review这个项目就是在这个背景下搞出来的。它的核心思路很简单一个命令行工具你给它一个 Git 仓库地址或者本地路径它自动拉取代码、分析 diff、调用 LLM 生成审查意见最后输出一份结构化的报告。整个过程不需要你打开浏览器不需要配置复杂的 CI 流水线一条命令就能跑。适合谁来参考我觉得三类人比较合适一是小团队的技术负责人想低成本搭一套自动化审查流程二是独立开发者自己写代码没人 review想让 AI 帮忙看看三是对 LLM Agent 和 CLI 工具感兴趣的同学想了解怎么把这两者结合起来做实际的东西。下面我会从整体设计、核心细节、实操过程、常见问题几个方面把这套东西拆开讲清楚。代码不会贴太多重点是思路和踩过的坑。2. 整体设计与思路拆解2.1 为什么选 CLI 而不是 Web 服务最开始我其实想做个 Web 服务前端页面展示报告后端跑分析任务。但后来放弃了原因有几个。第一部署成本。Web 服务意味着要维护服务器、数据库、前端构建对于小团队来说太重了。CLI 工具只需要一个可执行文件扔到任何一台开发机上就能跑零运维。第二集成灵活性。CLI 可以很方便地嵌入到现有的 Git hook、CI 脚本、甚至 Makefile 里。比如我可以在pre-push钩子里调用它推送前自动跑一遍。Web 服务要做到这一点还得额外写 API 调用逻辑。第三数据安全。代码是团队的核心资产能不外传就不外传。CLI 工具在本地跑LLM 调用可以走自己的 API key代码内容只经过必要的传输可控性更强。当然 CLI 也有缺点比如报告的可读性不如网页没法做复杂的交互。但我觉得对于代码审查这个场景文本报告足够了关键信息能看清楚就行。2.2 LLM Agent 在其中的角色定位这里要澄清一个概念。很多人把 LLM、Agent、AI 模型混着说其实它们不是一回事。LLM 是底层的大语言模型比如 DeepSeek、GPT 系列、Claude 系列它们负责理解和生成文本。Agent 是在 LLM 之上加了一层决策循环——它会根据当前状态决定下一步做什么调用工具、观察结果、再决定下一步。AI 模型是个更宽泛的说法包含 LLM 也包括传统的机器学习模型。在open-code-review里LLM 负责的是看懂代码 diff 并给出意见Agent 负责的是决定先看哪个文件、要不要深入某个函数、什么时候输出报告。我用的是一种轻量级的 Agent 模式不是完全自主的那种而是有明确的流程控制LLM 在关键节点做判断。为什么不用完全自主的 Agent因为代码审查这个任务流程相对固定拉代码、算 diff、逐文件分析、汇总报告。完全自主的 Agent 容易跑偏比如反复读同一个文件或者陷入无关的细节。轻量级 Agent 加上明确的流程约束稳定性和可控性都好很多。2.3 技术选型背后的考量语言方面我选了 Python。原因很简单LLM 相关的 SDK 生态最成熟Git 操作有GitPython这样的库文本处理也方便。虽然 Go 或 Rust 性能更好但在这个场景下性能不是瓶颈开发效率更重要。Git 操作这块我没有直接用GitPython的全部功能而是混合使用了subprocess调用原生 git 命令。为什么因为有些操作比如git diff的某些参数组合用库反而绕。直接调命令行更直观也更容易调试。比如git -c diff.mnemonicprefixfalse -c core.quotepathfalse --no-optional-locks diff这种直接写命令比查库的 API 快得多。LLM 调用方面我设计了一个抽象的 provider 层。目前支持 OpenAI 兼容的接口和 Anthropic 的接口理论上任何提供 HTTP API 的模型都能接进来。这样做的好处是你可以根据成本和效果灵活切换模型。比如日常审查用便宜的小模型遇到重要模块再切到强模型。输出格式我选了 Markdown。原因也很实际Markdown 在终端里可以直接渲染在 GitLab/GitHub 的评论里也能用复制到飞书、钉钉里格式也不会乱。比纯文本可读性好比 HTML 轻量。3. 核心细节解析与实操要点3.1 代码获取与 diff 计算第一步是拿到要审查的代码。这里分两种情况本地仓库和远程仓库。本地仓库简单直接读文件系统就行。远程仓库需要先 clone 或者 fetch。我在这里踩过一个坑如果每次都全量 clone大仓库会非常慢。后来改成用--depth 1做浅克隆只拉最新一次提交速度快很多。但如果要对比历史版本浅克隆就不够了得用--depth指定足够的深度或者干脆全量。diff 的计算是核心。我用的命令是git -c diff.mnemonicprefixfalse -c core.quotepathfalse --no-optional-locks diff --unified5 base head这里有几个参数值得说明。--unified5表示每个变更块前后各显示 5 行上下文。默认是 3 行我改成 5 行是因为 LLM 需要更多上下文才能准确判断。太少了它看不懂太多了 token 消耗大。实测 5 行是个平衡点。diff.mnemonicprefixfalse和core.quotepathfalse是为了让输出更干净避免一些特殊字符被转义。--no-optional-locks是防止在并发场景下 git 锁文件冲突。拿到 diff 之后我会按文件拆分每个文件单独送给 LLM 分析。为什么不一次性送整个 diff因为 token 限制。一个大的 PR 可能有几千行变更一次性送进去要么超限要么模型注意力分散效果反而差。按文件拆分每个文件的分析更聚焦。3.2 Prompt 设计与上下文管理Prompt 是决定审查质量的关键。我试过很多版本最后稳定下来的结构是这样的你是一个资深代码审查员。请分析以下代码变更找出 1. 潜在的 bug 或逻辑错误 2. 安全隐患 3. 性能问题 4. 代码风格问题 5. 可读性和可维护性建议 对于每个问题请给出 - 文件路径和行号 - 问题描述 - 严重程度高/中/低 - 修改建议 代码变更 diff 内容 相关上下文 文件的其他部分如果需要这个 prompt 有几个设计点。第一明确角色让模型进入审查员的状态。第二分类列出要找的问题类型避免它泛泛而谈。第三要求结构化输出方便后续解析。第四提供上下文让模型能看到变更之外的相关代码。上下文管理是个难点。如果只给 diff模型可能不理解变更的背景。比如一个函数被删了但 diff 里看不到谁在调用它。我的做法是对于每个变更的文件把整个文件的内容也附上但只附关键部分——比如变更所在的函数、相关的类定义。这样既给了上下文又控制了 token 消耗。还有一个技巧在 prompt 里加入项目的编码规范。比如本项目使用 4 空格缩进、禁止使用全局变量之类的。这样模型提意见时会参考项目自己的规则而不是它自己的偏好。3.3 结果解析与报告生成LLM 的输出是自然语言要变成结构化的报告需要解析。我一开始想用正则表达式提取但发现模型输出格式不稳定有时候用 Markdown 列表有时候用编号有时候直接写段落。后来改成让模型输出 JSON解析就稳定多了。但 JSON 也有问题模型有时候会输出不合法的 JSON比如多一个逗号或者字符串没转义。我的处理方式是加一层容错先尝试直接解析失败的话用正则提取关键字段再失败就降级为纯文本展示。实测下来95% 以上的情况能直接解析成功。报告生成这块我设计了几种输出格式格式适用场景特点Markdown终端查看、粘贴到聊天工具可读性好格式通用JSON程序化处理、集成到其他系统结构化方便解析纯文本邮件、日志兼容性最好默认是 Markdown。如果检测到输出到终端会加上颜色高亮如果重定向到文件就去掉颜色代码。报告里我会按严重程度排序高严重度的问题放最前面。每个问题包含文件路径、行号、描述、建议。最后有一个汇总统计总共发现多少问题高/中/低各多少。3.4 配置管理与密钥安全API key 的管理是个敏感问题。我见过有人在代码里硬编码 key然后不小心提交到公开仓库结果被人盗刷。这个坑一定要避开。我的做法是key 只从环境变量读取不写入任何配置文件。配置文件里只放非敏感的配置比如模型名称、API 地址、超时时间。如果环境变量没设置工具会报错并提示怎么设置而不是用默认值硬跑。配置文件我选了 YAML 格式放在项目根目录的.open-code-review.yml。结构大概是这样model: provider: openai name: gpt-4o-mini base_url: https://api.example.com/v1 timeout: 60 review: max_files: 50 severity_threshold: low ignore_patterns: - *.md - test/** output: format: markdown color: autoignore_patterns是个实用功能。有些文件不需要审查比如文档、测试数据、自动生成的代码。配置好之后工具会自动跳过节省时间和 token。4. 实操过程与核心环节实现4.1 环境准备与依赖安装先说环境。Python 版本我建议 3.10 以上因为用了一些新的类型语法。安装依赖用 pip 或者 poetry 都行我习惯用 pippip install open-code-review如果要从源码跑先 clone 仓库然后git clone https://github.com/example/open-code-review.git cd open-code-review pip install -e .-e是 editable 模式改代码不用重新安装方便调试。Git 的安装这里提一句。Windows 用户如果还没装 Git去官网下载安装包一路下一步就行。装完之后在命令行里跑git --version确认。Mac 用户一般自带没有的话brew install git。Linux 用包管理器装。装完之后配置一下用户信息git config --global user.name 你的名字 git config --global user.email 你的邮箱这个不是必须的但建议配上不然有些 git 操作会报错。4.2 第一次运行从本地仓库开始最简单的用法是审查本地仓库的未提交变更ocr review --local .ocr是open-code-review的简写命令。它会自动检测当前目录是不是 Git 仓库然后计算工作区和暂存区的 diff送给 LLM 分析。如果你想审查最近一次提交ocr review --local . --commit HEAD审查两个提交之间的变更ocr review --local . --range HEAD~3..HEAD这些参数的设计参考了 git 本身的习惯用过 git 的人应该很熟悉。第一次运行会提示你设置 API key。按照提示设置环境变量export OCR_API_KEY你的keyWindows 上用set或者$env:。设置完之后再跑一次应该就能看到报告了。4.3 审查远程仓库与 CI 集成审查远程仓库ocr review --remote https://github.com/example/project.git --branch main它会先浅克隆到临时目录分析完自动清理。如果仓库是私有的需要配置访问凭证。我建议用 SSH key 或者 token不要用密码。集成到 CI 的话以 GitLab CI 为例在.gitlab-ci.yml里加一段code-review: stage: test script: - pip install open-code-review - ocr review --local . --range $CI_MERGE_REQUEST_DIFF_BASE_SHA..$CI_COMMIT_SHA --format markdown review.md artifacts: paths: - review.md only: - merge_requests这样每次 MR 都会自动跑审查报告作为 artifact 保存。如果想让报告直接评论到 MR 里需要额外调 GitLab API这个可以后续扩展。4.4 参数调优与效果验证跑起来之后你会发现默认参数不一定适合你的项目。几个关键参数需要调--max-files控制最多分析多少个文件。默认 50大 PR 可能超。调大意味着更长的运行时间和更高的 token 消耗。我的建议是先设小一点比如 20看看效果再调。--severity-threshold控制报告里显示的最低严重程度。默认显示全部。如果你只想看高严重度的问题设成high。--model可以临时切换模型。比如日常用便宜的重要审查用贵的ocr review --local . --model gpt-4o效果验证这块我的做法是找几个已知有问题的提交跑一遍看能不能找出来。比如我之前写的一个有 SQL 注入风险的函数工具确实标记出来了。也找了一些风格问题比如变量命名不规范它也能提。但有些它也会漏比如复杂的业务逻辑错误它不一定能理解。所以定位要清楚它是辅助不是替代。5. 常见问题与排查技巧实录5.1 安装与配置类问题问题一command not found: ocr这个通常是安装路径没加到 PATH 里。pip 安装的可执行文件一般在~/.local/bin或者 Python 的Scripts目录。检查一下python -m site --user-base把输出的路径加上/bin加到 PATH 里。或者直接用python -m open_code_review来跑。问题二API 调用报 401一般是 key 没设置对。检查环境变量echo $OCR_API_KEYWindows 上用echo %OCR_API_KEY%。如果为空说明没设置成功。注意不要有多余的空格或引号。问题三unable to locate the codex cli binary这个错误一般出现在你用了某个依赖 codex cli 的功能但系统里没装。open-code-review本身不依赖 codex cli但如果你配置了相关的 provider需要先装好。检查一下配置文件里的 provider 设置或者临时切回默认的 HTTP provider。5.2 运行时报错与排查问题四Git 操作失败提示not a git repository确认你在一个 Git 仓库里跑或者用--remote指定远程地址。如果是子目录git 会往上找一般没问题。但如果目录被.gitignore排除了可能会有问题。问题五diff 为空没有分析结果可能是你指定的范围没有变更。比如HEAD~3..HEAD但最近三次提交没有改动。检查一下git log --oneline -5确认提交历史。另外如果变更都在被忽略的文件里也会显示为空。检查ignore_patterns配置。问题六LLM 返回内容被截断一般是 token 超限。调小--max-files或者把大文件拆开分析。也可以在配置里设置max_tokens_per_file超过就跳过或分段。5.3 效果优化与避坑经验经验一不要指望它找业务逻辑 bugLLM 对代码的理解停留在语法和常见模式层面。它能发现空指针、资源泄漏、SQL 拼接这类问题但业务逻辑错误比如这个折扣算错了它基本看不出来。所以人工 review 不能省只是可以把精力集中在业务逻辑上。经验二prompt 里加项目规范效果翻倍我在 prompt 里加了项目的编码规范之后风格类的误报少了很多。比如项目规定用 2 空格缩进模型就不会再提建议用 4 空格这种意见。经验三定期更新模型LLM 迭代很快新模型在代码理解上往往有提升。我大概每两个月会试一下新出的模型对比一下效果和成本。有时候换个模型同样的问题能多找出 20%。经验四报告要有人看才有价值工具跑出来的报告如果没人看就是浪费。我的做法是把报告集成到日常流程里比如每天早会前跑一遍昨天的提交会上快速过一下高严重度的问题。养成习惯之后大家会主动关注。常见问题速查表现象可能原因解决方法命令找不到PATH 未配置检查安装路径加入 PATH401 错误API key 未设置或错误检查环境变量diff 为空范围无变更或文件被忽略检查 git log 和 ignore 配置返回截断token 超限减少文件数或分段分析误报多prompt 不够具体加入项目规范调整阈值运行慢文件太多或模型太慢减少 max-files换轻量模型6. 一些扩展思路和实际体会这套工具跑了大半年团队里的反馈整体是正面的。最明显的变化是代码风格问题在 review 阶段被提前拦住了人工 review 的时间大概省了三分之一。当然也有同事一开始抵触觉得机器懂什么代码后来看到它确实能找出一些自己没注意的问题态度就转变了。扩展方向我想过几个。一个是加缓存同样的 diff 不重复分析省 token。另一个是支持多模型投票几个模型分别分析取交集或并集提高准确率。还有一个是做成 Git hook提交时自动跑但考虑到运行时间可能只对高严重度问题做拦截。如果你也想搭一套我的建议是从小处开始。先跑通本地仓库的审查看看效果再逐步集成到 CI。不要一上来就搞大而全容易半途而废。模型选择上先用便宜的试水觉得有价值再升级。最后分享一个小技巧在 prompt 里让模型用我建议而不是你应该语气会柔和很多团队接受度更高。这种细节看起来不起眼但实际用起来差别挺大的。
基于LLM Agent的CLI代码审查工具：open-code-review实战
1. 为什么我要自己搭一套 open-code-review代码审查这件事做过团队协作的人都有体会。理想状态下每次提交都有人认真看、认真提意见但现实往往是项目赶进度PR 堆了十几个没人理或者 reviewer 自己也很忙扫两眼就点了 approve。时间一长代码质量全靠个人自觉技术债越滚越大。我所在的团队规模不大七八个人后端前端加起来每天大概有二十到三十次提交。之前试过几种方案纯人工 review累且慢用 SaaS 类的代码审查工具贵且数据要往外传也试过一些开源的静态分析工具但规则太死误报率高大家用了一阵就都不看了。后来我琢磨着能不能用 LLM 来做这件事。不是让它替代人而是让它当第一道筛子——把明显的风格问题、潜在 bug、安全隐患先过一遍人工只需要看它标记出来的重点。这样既省时间又能保证基本质量。open-code-review这个项目就是在这个背景下搞出来的。它的核心思路很简单一个命令行工具你给它一个 Git 仓库地址或者本地路径它自动拉取代码、分析 diff、调用 LLM 生成审查意见最后输出一份结构化的报告。整个过程不需要你打开浏览器不需要配置复杂的 CI 流水线一条命令就能跑。适合谁来参考我觉得三类人比较合适一是小团队的技术负责人想低成本搭一套自动化审查流程二是独立开发者自己写代码没人 review想让 AI 帮忙看看三是对 LLM Agent 和 CLI 工具感兴趣的同学想了解怎么把这两者结合起来做实际的东西。下面我会从整体设计、核心细节、实操过程、常见问题几个方面把这套东西拆开讲清楚。代码不会贴太多重点是思路和踩过的坑。2. 整体设计与思路拆解2.1 为什么选 CLI 而不是 Web 服务最开始我其实想做个 Web 服务前端页面展示报告后端跑分析任务。但后来放弃了原因有几个。第一部署成本。Web 服务意味着要维护服务器、数据库、前端构建对于小团队来说太重了。CLI 工具只需要一个可执行文件扔到任何一台开发机上就能跑零运维。第二集成灵活性。CLI 可以很方便地嵌入到现有的 Git hook、CI 脚本、甚至 Makefile 里。比如我可以在pre-push钩子里调用它推送前自动跑一遍。Web 服务要做到这一点还得额外写 API 调用逻辑。第三数据安全。代码是团队的核心资产能不外传就不外传。CLI 工具在本地跑LLM 调用可以走自己的 API key代码内容只经过必要的传输可控性更强。当然 CLI 也有缺点比如报告的可读性不如网页没法做复杂的交互。但我觉得对于代码审查这个场景文本报告足够了关键信息能看清楚就行。2.2 LLM Agent 在其中的角色定位这里要澄清一个概念。很多人把 LLM、Agent、AI 模型混着说其实它们不是一回事。LLM 是底层的大语言模型比如 DeepSeek、GPT 系列、Claude 系列它们负责理解和生成文本。Agent 是在 LLM 之上加了一层决策循环——它会根据当前状态决定下一步做什么调用工具、观察结果、再决定下一步。AI 模型是个更宽泛的说法包含 LLM 也包括传统的机器学习模型。在open-code-review里LLM 负责的是看懂代码 diff 并给出意见Agent 负责的是决定先看哪个文件、要不要深入某个函数、什么时候输出报告。我用的是一种轻量级的 Agent 模式不是完全自主的那种而是有明确的流程控制LLM 在关键节点做判断。为什么不用完全自主的 Agent因为代码审查这个任务流程相对固定拉代码、算 diff、逐文件分析、汇总报告。完全自主的 Agent 容易跑偏比如反复读同一个文件或者陷入无关的细节。轻量级 Agent 加上明确的流程约束稳定性和可控性都好很多。2.3 技术选型背后的考量语言方面我选了 Python。原因很简单LLM 相关的 SDK 生态最成熟Git 操作有GitPython这样的库文本处理也方便。虽然 Go 或 Rust 性能更好但在这个场景下性能不是瓶颈开发效率更重要。Git 操作这块我没有直接用GitPython的全部功能而是混合使用了subprocess调用原生 git 命令。为什么因为有些操作比如git diff的某些参数组合用库反而绕。直接调命令行更直观也更容易调试。比如git -c diff.mnemonicprefixfalse -c core.quotepathfalse --no-optional-locks diff这种直接写命令比查库的 API 快得多。LLM 调用方面我设计了一个抽象的 provider 层。目前支持 OpenAI 兼容的接口和 Anthropic 的接口理论上任何提供 HTTP API 的模型都能接进来。这样做的好处是你可以根据成本和效果灵活切换模型。比如日常审查用便宜的小模型遇到重要模块再切到强模型。输出格式我选了 Markdown。原因也很实际Markdown 在终端里可以直接渲染在 GitLab/GitHub 的评论里也能用复制到飞书、钉钉里格式也不会乱。比纯文本可读性好比 HTML 轻量。3. 核心细节解析与实操要点3.1 代码获取与 diff 计算第一步是拿到要审查的代码。这里分两种情况本地仓库和远程仓库。本地仓库简单直接读文件系统就行。远程仓库需要先 clone 或者 fetch。我在这里踩过一个坑如果每次都全量 clone大仓库会非常慢。后来改成用--depth 1做浅克隆只拉最新一次提交速度快很多。但如果要对比历史版本浅克隆就不够了得用--depth指定足够的深度或者干脆全量。diff 的计算是核心。我用的命令是git -c diff.mnemonicprefixfalse -c core.quotepathfalse --no-optional-locks diff --unified5 base head这里有几个参数值得说明。--unified5表示每个变更块前后各显示 5 行上下文。默认是 3 行我改成 5 行是因为 LLM 需要更多上下文才能准确判断。太少了它看不懂太多了 token 消耗大。实测 5 行是个平衡点。diff.mnemonicprefixfalse和core.quotepathfalse是为了让输出更干净避免一些特殊字符被转义。--no-optional-locks是防止在并发场景下 git 锁文件冲突。拿到 diff 之后我会按文件拆分每个文件单独送给 LLM 分析。为什么不一次性送整个 diff因为 token 限制。一个大的 PR 可能有几千行变更一次性送进去要么超限要么模型注意力分散效果反而差。按文件拆分每个文件的分析更聚焦。3.2 Prompt 设计与上下文管理Prompt 是决定审查质量的关键。我试过很多版本最后稳定下来的结构是这样的你是一个资深代码审查员。请分析以下代码变更找出 1. 潜在的 bug 或逻辑错误 2. 安全隐患 3. 性能问题 4. 代码风格问题 5. 可读性和可维护性建议 对于每个问题请给出 - 文件路径和行号 - 问题描述 - 严重程度高/中/低 - 修改建议 代码变更 diff 内容 相关上下文 文件的其他部分如果需要这个 prompt 有几个设计点。第一明确角色让模型进入审查员的状态。第二分类列出要找的问题类型避免它泛泛而谈。第三要求结构化输出方便后续解析。第四提供上下文让模型能看到变更之外的相关代码。上下文管理是个难点。如果只给 diff模型可能不理解变更的背景。比如一个函数被删了但 diff 里看不到谁在调用它。我的做法是对于每个变更的文件把整个文件的内容也附上但只附关键部分——比如变更所在的函数、相关的类定义。这样既给了上下文又控制了 token 消耗。还有一个技巧在 prompt 里加入项目的编码规范。比如本项目使用 4 空格缩进、禁止使用全局变量之类的。这样模型提意见时会参考项目自己的规则而不是它自己的偏好。3.3 结果解析与报告生成LLM 的输出是自然语言要变成结构化的报告需要解析。我一开始想用正则表达式提取但发现模型输出格式不稳定有时候用 Markdown 列表有时候用编号有时候直接写段落。后来改成让模型输出 JSON解析就稳定多了。但 JSON 也有问题模型有时候会输出不合法的 JSON比如多一个逗号或者字符串没转义。我的处理方式是加一层容错先尝试直接解析失败的话用正则提取关键字段再失败就降级为纯文本展示。实测下来95% 以上的情况能直接解析成功。报告生成这块我设计了几种输出格式格式适用场景特点Markdown终端查看、粘贴到聊天工具可读性好格式通用JSON程序化处理、集成到其他系统结构化方便解析纯文本邮件、日志兼容性最好默认是 Markdown。如果检测到输出到终端会加上颜色高亮如果重定向到文件就去掉颜色代码。报告里我会按严重程度排序高严重度的问题放最前面。每个问题包含文件路径、行号、描述、建议。最后有一个汇总统计总共发现多少问题高/中/低各多少。3.4 配置管理与密钥安全API key 的管理是个敏感问题。我见过有人在代码里硬编码 key然后不小心提交到公开仓库结果被人盗刷。这个坑一定要避开。我的做法是key 只从环境变量读取不写入任何配置文件。配置文件里只放非敏感的配置比如模型名称、API 地址、超时时间。如果环境变量没设置工具会报错并提示怎么设置而不是用默认值硬跑。配置文件我选了 YAML 格式放在项目根目录的.open-code-review.yml。结构大概是这样model: provider: openai name: gpt-4o-mini base_url: https://api.example.com/v1 timeout: 60 review: max_files: 50 severity_threshold: low ignore_patterns: - *.md - test/** output: format: markdown color: autoignore_patterns是个实用功能。有些文件不需要审查比如文档、测试数据、自动生成的代码。配置好之后工具会自动跳过节省时间和 token。4. 实操过程与核心环节实现4.1 环境准备与依赖安装先说环境。Python 版本我建议 3.10 以上因为用了一些新的类型语法。安装依赖用 pip 或者 poetry 都行我习惯用 pippip install open-code-review如果要从源码跑先 clone 仓库然后git clone https://github.com/example/open-code-review.git cd open-code-review pip install -e .-e是 editable 模式改代码不用重新安装方便调试。Git 的安装这里提一句。Windows 用户如果还没装 Git去官网下载安装包一路下一步就行。装完之后在命令行里跑git --version确认。Mac 用户一般自带没有的话brew install git。Linux 用包管理器装。装完之后配置一下用户信息git config --global user.name 你的名字 git config --global user.email 你的邮箱这个不是必须的但建议配上不然有些 git 操作会报错。4.2 第一次运行从本地仓库开始最简单的用法是审查本地仓库的未提交变更ocr review --local .ocr是open-code-review的简写命令。它会自动检测当前目录是不是 Git 仓库然后计算工作区和暂存区的 diff送给 LLM 分析。如果你想审查最近一次提交ocr review --local . --commit HEAD审查两个提交之间的变更ocr review --local . --range HEAD~3..HEAD这些参数的设计参考了 git 本身的习惯用过 git 的人应该很熟悉。第一次运行会提示你设置 API key。按照提示设置环境变量export OCR_API_KEY你的keyWindows 上用set或者$env:。设置完之后再跑一次应该就能看到报告了。4.3 审查远程仓库与 CI 集成审查远程仓库ocr review --remote https://github.com/example/project.git --branch main它会先浅克隆到临时目录分析完自动清理。如果仓库是私有的需要配置访问凭证。我建议用 SSH key 或者 token不要用密码。集成到 CI 的话以 GitLab CI 为例在.gitlab-ci.yml里加一段code-review: stage: test script: - pip install open-code-review - ocr review --local . --range $CI_MERGE_REQUEST_DIFF_BASE_SHA..$CI_COMMIT_SHA --format markdown review.md artifacts: paths: - review.md only: - merge_requests这样每次 MR 都会自动跑审查报告作为 artifact 保存。如果想让报告直接评论到 MR 里需要额外调 GitLab API这个可以后续扩展。4.4 参数调优与效果验证跑起来之后你会发现默认参数不一定适合你的项目。几个关键参数需要调--max-files控制最多分析多少个文件。默认 50大 PR 可能超。调大意味着更长的运行时间和更高的 token 消耗。我的建议是先设小一点比如 20看看效果再调。--severity-threshold控制报告里显示的最低严重程度。默认显示全部。如果你只想看高严重度的问题设成high。--model可以临时切换模型。比如日常用便宜的重要审查用贵的ocr review --local . --model gpt-4o效果验证这块我的做法是找几个已知有问题的提交跑一遍看能不能找出来。比如我之前写的一个有 SQL 注入风险的函数工具确实标记出来了。也找了一些风格问题比如变量命名不规范它也能提。但有些它也会漏比如复杂的业务逻辑错误它不一定能理解。所以定位要清楚它是辅助不是替代。5. 常见问题与排查技巧实录5.1 安装与配置类问题问题一command not found: ocr这个通常是安装路径没加到 PATH 里。pip 安装的可执行文件一般在~/.local/bin或者 Python 的Scripts目录。检查一下python -m site --user-base把输出的路径加上/bin加到 PATH 里。或者直接用python -m open_code_review来跑。问题二API 调用报 401一般是 key 没设置对。检查环境变量echo $OCR_API_KEYWindows 上用echo %OCR_API_KEY%。如果为空说明没设置成功。注意不要有多余的空格或引号。问题三unable to locate the codex cli binary这个错误一般出现在你用了某个依赖 codex cli 的功能但系统里没装。open-code-review本身不依赖 codex cli但如果你配置了相关的 provider需要先装好。检查一下配置文件里的 provider 设置或者临时切回默认的 HTTP provider。5.2 运行时报错与排查问题四Git 操作失败提示not a git repository确认你在一个 Git 仓库里跑或者用--remote指定远程地址。如果是子目录git 会往上找一般没问题。但如果目录被.gitignore排除了可能会有问题。问题五diff 为空没有分析结果可能是你指定的范围没有变更。比如HEAD~3..HEAD但最近三次提交没有改动。检查一下git log --oneline -5确认提交历史。另外如果变更都在被忽略的文件里也会显示为空。检查ignore_patterns配置。问题六LLM 返回内容被截断一般是 token 超限。调小--max-files或者把大文件拆开分析。也可以在配置里设置max_tokens_per_file超过就跳过或分段。5.3 效果优化与避坑经验经验一不要指望它找业务逻辑 bugLLM 对代码的理解停留在语法和常见模式层面。它能发现空指针、资源泄漏、SQL 拼接这类问题但业务逻辑错误比如这个折扣算错了它基本看不出来。所以人工 review 不能省只是可以把精力集中在业务逻辑上。经验二prompt 里加项目规范效果翻倍我在 prompt 里加了项目的编码规范之后风格类的误报少了很多。比如项目规定用 2 空格缩进模型就不会再提建议用 4 空格这种意见。经验三定期更新模型LLM 迭代很快新模型在代码理解上往往有提升。我大概每两个月会试一下新出的模型对比一下效果和成本。有时候换个模型同样的问题能多找出 20%。经验四报告要有人看才有价值工具跑出来的报告如果没人看就是浪费。我的做法是把报告集成到日常流程里比如每天早会前跑一遍昨天的提交会上快速过一下高严重度的问题。养成习惯之后大家会主动关注。常见问题速查表现象可能原因解决方法命令找不到PATH 未配置检查安装路径加入 PATH401 错误API key 未设置或错误检查环境变量diff 为空范围无变更或文件被忽略检查 git log 和 ignore 配置返回截断token 超限减少文件数或分段分析误报多prompt 不够具体加入项目规范调整阈值运行慢文件太多或模型太慢减少 max-files换轻量模型6. 一些扩展思路和实际体会这套工具跑了大半年团队里的反馈整体是正面的。最明显的变化是代码风格问题在 review 阶段被提前拦住了人工 review 的时间大概省了三分之一。当然也有同事一开始抵触觉得机器懂什么代码后来看到它确实能找出一些自己没注意的问题态度就转变了。扩展方向我想过几个。一个是加缓存同样的 diff 不重复分析省 token。另一个是支持多模型投票几个模型分别分析取交集或并集提高准确率。还有一个是做成 Git hook提交时自动跑但考虑到运行时间可能只对高严重度问题做拦截。如果你也想搭一套我的建议是从小处开始。先跑通本地仓库的审查看看效果再逐步集成到 CI。不要一上来就搞大而全容易半途而废。模型选择上先用便宜的试水觉得有价值再升级。最后分享一个小技巧在 prompt 里让模型用我建议而不是你应该语气会柔和很多团队接受度更高。这种细节看起来不起眼但实际用起来差别挺大的。