1. 为什么我要自己搭一套 open-code-review代码审查这件事做过团队协作的人都有体会。理想状态下每次提交都有人认真看、认真提意见把问题拦在合并之前。现实往往是另一回事项目赶进度PR 堆了十几个没人理 reviewer 自己手头一堆活扫两眼点个 approve新人提交的代码没人带问题反复出现。时间一长代码质量全靠个人自觉团队的技术债越滚越大。我所在的团队规模不大七八个人前后端加数据都有。之前试过几种方案定规矩要求每天固定时间集中 review坚持了两周就散了用一些在线的代码托管平台自带的审查功能但那些工具更多是格式检查对业务逻辑、边界条件、潜在 bug 基本无能为力。后来大模型的能力上来了我就琢磨着能不能把 LLM 接进代码审查流程里让它先过一遍把明显的问题挑出来人只需要看它标记的重点就行。open-code-review这个项目就是在这个背景下折腾出来的。它的核心思路很直接用命令行工具拉取 Git 仓库的变更把 diff 内容喂给 LLM让模型按照预设的审查规则输出意见最后把结果整理成可读的报告。整套东西跑在本地或者 CI 里都行不依赖特定的代码托管平台Git 仓库在哪它就能在哪工作。这套东西适合谁用我觉得三类人比较合适。一是小团队的技术负责人想给团队加一道自动化的质量关卡但又不想引入太重的外部服务二是独立开发者自己写代码没人 review让 LLM 帮忙看看能发现不少低级错误三是对 LLM Agent 和 CLI 工具感兴趣、想动手实践的人这个项目涉及 Git 操作、命令行参数解析、LLM API 调用、结果格式化等环节是个不错的练手项目。下面我会从整体设计、核心细节、实操过程、问题排查几个方面把这套东西拆开讲清楚。里面涉及的代码和配置都是我实际跑过的参数选择也会说明理由你可以直接参考着搭一套自己的版本。2. 整体设计与技术选型拆解2.1 核心工作流是怎么串起来的整套工具的运行逻辑可以拆成四步。第一步是确定审查范围也就是搞清楚这次要看哪些改动。常见的方式有两种一种是看当前分支相对于目标分支的差异比如 feature 分支要合并到 main那就对比这两个分支另一种是看最近若干次提交比如最近三次 commit 都改了啥。这两种场景在实际工作中都会遇到所以工具得支持灵活指定。第二步是获取 diff 内容。Git 本身提供了git diff命令能输出两个提交之间的差异。但直接拿到的 diff 是纯文本包含大量上下文行、文件头信息、行号标记直接丢给 LLM 会浪费 token还可能干扰模型判断。所以中间需要一层解析把 diff 拆成按文件分组的变更块每个块里只保留真正改动的行和必要的上下文。第三步是调用 LLM 做审查。这里的关键是提示词的设计。不能简单地说“帮我看看这段代码有没有问题”那样模型输出会很发散。需要给它明确的角色设定、审查维度、输出格式要求。比如要求它从正确性、边界条件、性能、可读性几个角度分析每个问题给出文件位置、行号、问题描述、修改建议。第四步是汇总输出。模型返回的结果可能是 JSON也可能是 Markdown需要解析后整理成统一的报告格式。如果发现问题可以选择直接打印到终端也可以写进文件或者作为 CI 的评论发出去。这四步串起来就是一个完整的审查流程。每一步都有可以优化的空间后面会细说。2.2 为什么选 CLI 而不是 Web 服务做这个工具的时候我考虑过几种形态。做成 Web 服务界面友好但部署麻烦还得考虑鉴权、并发、任务队列。做成 IDE 插件用起来方便但受限于 IDE 的生态换个编辑器就用不了。最后选 CLI理由有几个。CLI 的侵入性最低。它就是一个命令你可以在本地终端跑也可以在 CI 脚本里跑还可以挂到 Git 的 hook 上。不需要改现有工作流不需要团队每个人都装什么客户端。对于小团队来说推广成本几乎为零。CLI 的组合能力最强。Unix 哲学里每个工具只做一件事然后通过管道组合。这个审查工具输出报告你可以用grep过滤可以用tee存文件可以重定向到其他工具做进一步处理。这种灵活性是 Web 服务给不了的。CLI 的调试最直接。出问题了加个--verbose看日志或者直接在代码里打断点。不用去翻服务器日志不用去猜请求链路。对于这种还在快速迭代的工具开发效率很重要。当然 CLI 也有缺点比如对不熟悉命令行的同事不太友好。但代码审查这个场景使用者本来就是开发者命令行是基本功这个门槛可以接受。2.3 LLM 选型与接入方式的考量模型这块我试过几种接入方式。最直接的是调各家厂商的 API比如 DeepSeek、通义千问、智谱这些国内可访问的模型服务。优点是稳定、速度快、按量计费透明。缺点是得管理 API Key而且不同厂商的接口格式有差异换模型要改代码。另一种方式是本地部署开源模型比如用 Ollama 跑 CodeLlama 或者 Qwen 的代码版本。好处是数据不出本地适合对代码保密性要求高的场景。坏处是对机器配置有要求推理速度也慢一些大仓库的 diff 可能跑不动。我最后的方案是做成可插拔的。抽象出一个 LLM Provider 接口定义review(diff_content, prompt)方法具体实现可以是 OpenAI 兼容接口、可以是 Ollama、也可以是其他任何服务。配置里指定用哪个 provider代码里通过工厂模式创建实例。这样换模型只需要改配置不用动核心逻辑。关于 Agent 和 LLM 的区别这里顺带说一句。LLM 是底层模型你给它输入它给你输出本身没有行动能力。Agent 是在 LLM 之上加了一层决策和工具调用能力它能根据任务自己决定下一步做什么比如先读文件、再搜索、再修改。这个审查工具严格来说不算 Agent因为它流程是固定的拿 diff、调模型、出报告。但如果后续想加自动修复功能比如让模型直接改代码然后提交那就往 Agent 方向走了。3. 核心细节解析与实操要点3.1 Git diff 的获取与解析获取 diff 看起来简单实际有不少细节。最基本的命令是git diff main...feature三个点表示对比两个分支的合并基两个点表示直接对比两个分支的末端。大多数情况下用三个点更符合直觉因为它只看 feature 分支引入的改动不会把 main 分支后来的提交也算进来。如果要看最近几次提交可以用git diff HEAD~3 HEAD表示对比当前提交和三次之前的提交。或者用git log -p -3直接输出最近三次提交的补丁内容。这两种方式输出的格式略有不同解析的时候要注意兼容。diff 的输出里每个文件以diff --git a/path b/path开头然后是index行、---和行接着是若干个 hunk。每个 hunk 以 -old_start,old_count new_start,new_count 开头后面跟着上下文行以空格开头、删除行以-开头、新增行以开头。解析的时候我按文件分组每个文件保留路径和它的所有 hunk。hunk 里的行号信息要保留因为后面要让模型指出问题在哪个文件的哪一行。但纯上下文行可以适当裁剪比如每个 hunk 只保留改动行前后各三行这样能大幅减少 token 消耗。有个坑要注意如果文件是二进制或者被重命名了diff 的输出格式会不一样。二进制文件直接跳过重命名的文件要特殊处理否则解析会出错。我在代码里加了个判断遇到Binary files开头或者rename from/to的行就做相应处理。3.2 提示词工程让模型输出可用的审查意见提示词这块我改了很多版。最开始写得很简单就是“请审查以下代码变更指出潜在问题”。结果模型输出一大段散文有时候还跑题去讨论代码风格根本没法用。后来我改成结构化提示词分几个部分。第一部分是角色设定告诉模型它是一个资深代码审查员有十年以上经验擅长发现边界条件、并发问题、资源泄漏这类隐蔽 bug。第二部分是审查维度明确列出要检查的项逻辑正确性、边界条件、错误处理、性能影响、可读性、安全性。第三部分是输出格式要求每个问题用 JSON 对象表示包含file、line、severity、message、suggestion五个字段。这样改完之后输出稳定多了。但还有个问题模型有时候会编造行号或者把上下文行当成改动行。解决办法是在提示词里强调“只针对以开头的行提出问题”并且在解析结果时做校验行号不在 diff 范围内的直接丢弃。另一个经验是给模型提供项目背景。比如这是个什么项目、用什么语言、有什么编码规范。这些信息可以放在系统提示里也可以从仓库里读 README 或者配置文件自动提取。有了背景信息模型的建议会更贴合实际不会给出“建议用 Python 的 f-string”这种在 Java 项目里毫无意义的意见。3.3 结果解析与报告生成模型返回的 JSON 不一定总是合法的。有时候会多一个逗号有时候字符串没转义有时候干脆返回 Markdown 代码块包裹的 JSON。所以解析的时候不能直接json.loads得先做清洗去掉代码块标记、修复常见语法错误、尝试提取 JSON 部分。解析成功后我按严重程度排序critical和high的排前面medium和low的排后面。然后生成两种格式的报告一种是终端友好的彩色输出用 ANSI 转义码给不同严重程度上色另一种是 Markdown 格式方便贴到 PR 评论或者存成文件。终端输出大概长这样先打印一个汇总显示总共发现多少个问题、各严重程度各多少个。然后按文件分组每个文件下列出具体问题包含行号、描述、建议。最后如果有问题退出码设为非零这样 CI 里能感知到审查不通过。Markdown 报告则更适合存档和分享。我会在开头加一个表格列出所有问题的概览然后每个问题一个二级标题详细展开。如果模型给了修改建议会用代码块展示建议的改法。3.4 配置管理与密钥安全配置这块我用的是 YAML 文件加环境变量覆盖的方式。YAML 里放非敏感的配置比如默认用哪个模型、审查哪些文件类型、严重程度阈值。API Key 这种敏感信息走环境变量不写进配置文件避免不小心提交到仓库。配置文件的结构大概是这样顶层分llm、review、output三个部分。llm里指定 provider、model、base_url、temperature 等参数。review里指定要忽略的文件模式、最大 diff 行数、是否启用某个审查维度。output里指定输出格式、是否写文件、文件路径。环境变量覆盖的规则是OCR_LLM_API_KEY覆盖llm.api_keyOCR_LLM_MODEL覆盖llm.model以此类推。这样在 CI 里可以通过环境变量注入密钥本地开发则可以用.env文件加载。有个细节要注意.env文件一定要加进.gitignore否则密钥泄露就是分分钟的事。我在项目模板里默认就加好了并且加了一个检查如果发现.env被追踪就报警告。4. 实操过程与核心环节实现4.1 环境准备与依赖安装先说要准备什么。Git 是必须的这个不用多说安装教程网上到处都是Windows 上装 Git for Windows 或者用 winget 装都行装完记得配一下用户名和邮箱不然提交会报错。Python 环境建议用 3.10 以上因为用了一些新语法。包管理用 pip 或者 uv 都可以我习惯用 uv速度快。依赖主要有几个click用来做命令行参数解析pyyaml读配置文件httpx发 HTTP 请求调 LLM APIrich做终端彩色输出pydantic做数据校验。这些都是成熟库装起来没什么坑。安装命令大概是这样pip install click pyyaml httpx rich pydantic如果用 uvuv add click pyyaml httpx rich pydantic装完之后把项目 clone 下来进入目录跑一下python -m open_code_review --help能看到帮助信息就说明环境没问题。4.2 核心代码结构说明项目目录结构我按功能划分open_code_review/ ├── __main__.py # 入口命令行解析 ├── config.py # 配置加载与合并 ├── git_utils.py # Git 操作封装 ├── diff_parser.py # diff 解析 ├── llm_provider.py # LLM 接口抽象与实现 ├── reviewer.py # 审查逻辑编排 ├── reporter.py # 报告生成 └── prompts/ └── default.txt # 默认提示词模板__main__.py里用 click 定义了几个子命令review是主命令config用来查看和校验配置version打印版本。review命令接受几个参数--base指定基准分支--head指定目标分支--commits指定看最近几次提交--format指定输出格式--output指定输出文件。git_utils.py封装了get_diff、get_current_branch、get_repo_root等函数。get_diff里根据传入的参数拼出对应的git diff命令用subprocess执行并捕获输出。这里要注意处理命令执行失败的情况比如分支不存在、仓库没初始化等给出友好的错误提示。diff_parser.py是核心之一。它把原始 diff 文本解析成FileDiff对象列表每个对象包含文件路径、变更类型、hunk 列表。hunk 里又包含起始行号、结束行号、变更行列表。解析逻辑用正则匹配文件头和 hunk 头然后逐行处理。llm_provider.py定义了LLMProvider抽象基类以及OpenAICompatibleProvider和OllamaProvider两个实现。前者适用于任何兼容 OpenAI 接口的服务后者专门适配 Ollama 的 API。每个 provider 实现review方法接收 diff 文本和提示词返回模型输出的字符串。reviewer.py把上面这些串起来加载配置、获取 diff、解析 diff、构造提示词、调用 provider、解析结果、返回问题列表。reporter.py负责把问题列表渲染成终端输出或 Markdown。4.3 关键参数的计算与选择有几个参数需要根据实际情况调整。第一个是max_diff_lines控制单次审查的最大 diff 行数。太少了会漏掉改动太多了会超出模型上下文限制。我的经验值是 2000 行左右对于大多数 PR 够用。如果超过这个数就按文件拆分分批审查。第二个是temperature控制模型输出的随机性。审查代码这种任务需要稳定、可复现的结果所以 temperature 设低一点0.1 到 0.3 之间比较合适。设成 0 也可以但有些模型在 temperature 为 0 时表现反而奇怪所以留一点余量。第三个是max_tokens控制模型输出的最大长度。审查意见一般不会太长设 2000 到 4000 就够了。设太大浪费设太小可能截断。如果发现输出被截断可以适当调大或者让模型分批输出。第四个是severity_threshold控制报告里显示哪些严重程度的问题。默认是low也就是全部显示。如果觉得噪音太多可以调到medium只显示中等问题及以上。这些参数都可以在配置文件里改也可以在命令行用--set临时覆盖方便调试。4.4 完整运行流程演示假设你有一个仓库当前在 feature 分支想审查它相对于 main 分支的改动。操作步骤是这样第一步确保在仓库根目录或者用--repo指定仓库路径。第二步配置好 API Key比如export OCR_LLM_API_KEYyour_key_here。第三步运行命令python -m open_code_review review --base main --head feature --format markdown --output review.md工具会先打印一行“正在获取 diff...”然后“正在调用模型审查...”最后“审查完成发现 5 个问题”。终端会显示彩色报告同时把 Markdown 报告写到review.md。如果想看最近三次提交的审查可以这样python -m open_code_review review --commits 3 --format terminal如果只想审查特定文件可以加--include *.py或者--exclude tests/*。跑完之后如果发现问题退出码是 1没问题退出码是 0。这样在 CI 里可以直接用退出码判断是否通过。4.5 接入 CI 的配置示例以 GitHub Actions 为例在.github/workflows/review.yml里写name: Code Review on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkoutv4 with: fetch-depth: 0 - uses: actions/setup-pythonv5 with: python-version: 3.11 - run: pip install -r requirements.txt - run: python -m open_code_review review --base origin/main --head HEAD --format markdown --output review.md env: OCR_LLM_API_KEY: ${{ secrets.OCR_LLM_API_KEY }} - uses: actions/upload-artifactv4 with: name: review-report path: review.md这里fetch-depth: 0很重要默认的浅克隆拿不到完整历史diff 会算错。API Key 放在 secrets 里不会泄露。如果想让审查结果直接评论到 PR 上可以再加一步用 GitHub 的 API 把review.md的内容发出去。不过这一步需要额外的 token 权限配置稍微复杂一点可以根据需要决定要不要加。5. 常见问题与排查技巧实录5.1 模型输出格式不对怎么办这是最常见的问题。表现是模型返回的内容不是合法 JSON或者 JSON 结构跟预期不符。排查思路分几步。先看原始输出。在代码里加个--debug选项把模型返回的原始字符串打印出来。很多时候一看就知道问题在哪可能是模型加了 Markdown 代码块标记可能是 JSON 里用了单引号可能是某个字段名拼错了。如果是代码块标记解析前先做清洗用正则把json和去掉。如果是单引号可以尝试用ast.literal_eval代替json.loads它对单引号更宽容。如果是字段名问题可以在提示词里再强调一遍字段名或者解析时做字段名映射。如果模型经常不按格式输出可以考虑用 function calling 或者 JSON mode。现在很多模型服务都支持强制 JSON 输出开启之后格式稳定性会好很多。DeepSeek 的 API 就支持response_format参数设成{type: json_object}就能强制 JSON。还有一个技巧是在提示词里给一个示例输出。模型看到示例模仿的概率会高很多。示例不用太长一个完整的 JSON 对象就够了。5.2 diff 太大导致超时或截断大 PR 的 diff 可能上万行直接丢给模型要么超时要么被截断。解决办法是分批处理。按文件分批是最自然的。每个文件的 diff 单独审查最后合并结果。这样每个请求的输入都小很多模型也能更专注。缺点是跨文件的问题可能发现不了比如一个函数在 A 文件定义、在 B 文件调用改动不一致。但对于大多数场景按文件分批已经够用。如果单个文件的 diff 还是太大可以按 hunk 分批。每个 hunk 独立审查但这样会丢失 hunk 之间的关联信息。折中方案是相邻的几个 hunk 合并成一批保证上下文连贯。另一个思路是先用模型做一轮粗筛让它指出哪些文件值得细看然后只对这部分文件做详细审查。这样能大幅减少 token 消耗但多了一次模型调用总体成本不一定低。我目前的策略是diff 小于 2000 行直接整体审查2000 到 10000 行按文件分批超过 10000 行先按文件分批再按 hunk 分批。这个阈值可以根据模型上下文长度调整。5.3 API 调用失败与重试策略网络请求失败是常态尤其是调外部 API。常见的失败原因有网络超时、限流、密钥无效、服务端错误。处理策略是分层重试。对于超时和 5xx 错误重试三次每次间隔翻倍比如 1 秒、2 秒、4 秒。对于 429 限流读响应头里的Retry-After按指示等待。对于 401 和 403直接报错退出重试没意义。重试的时候要注意幂等性。审查请求本身是幂等的重试不会产生副作用所以可以放心重试。但如果后续加了自动修复功能重试就要小心了避免重复修改。日志要记清楚。每次请求的 URL、状态码、耗时、重试次数都记下来出问题的时候好排查。我用的是 Python 的logging模块配置成输出到 stderr这样不会干扰正常的报告输出。5.4 常见问题速查表问题现象可能原因排查方法解决方案提示找不到 Git 仓库不在仓库目录或未初始化运行git status确认进入仓库目录或用--repo指定diff 为空分支名写错或没有差异手动运行git diff验证检查分支名确认有改动模型返回空API Key 无效或额度用完查看日志中的状态码检查密钥确认账户余额JSON 解析失败模型输出格式不对加--debug看原始输出清洗输出或开启 JSON mode审查结果行号不对diff 解析有误对比原始 diff 和解析结果修复解析逻辑处理边界情况运行超时diff 太大或网络慢看日志中的耗时分批处理调大超时时间中文乱码编码不一致检查终端和文件编码统一用 UTF-8退出码总是 0问题列表为空检查严重程度阈值调低阈值或检查模型输出5.5 几个踩过的坑和独家技巧第一个坑是 Git 的core.quotepath配置。默认情况下Git 会把非 ASCII 文件名转义成八进制导致解析出来的文件路径是乱码。解决办法是在命令里加-c core.quotepathfalse或者在仓库配置里设成 false。这个坑我踩了好几次才找到原因。第二个坑是 Windows 上的换行符。Windows 用 CRLFLinux 用 LFdiff 的时候可能会把整个文件都标成改动。解决办法是在仓库里加.gitattributes统一换行符或者在 diff 命令里加--ignore-cr-at-eol。第三个技巧是用git worktree来隔离审查环境。审查的时候需要 checkout 到目标分支如果直接在开发目录操作会打断当前工作。用git worktree add /tmp/review-branch feature可以创建一个独立的工作目录审查完删掉就行不影响主目录。第四个技巧是缓存模型结果。同样的 diff 审查两次结果应该是一样的。可以把 diff 的哈希作为 key模型输出作为 value存到本地文件或者 Redis 里。下次遇到同样的 diff 直接读缓存省时省钱。不过要注意缓存失效策略模型升级或者提示词改了缓存就得清掉。第五个技巧是给审查结果加置信度。让模型对每个问题给出一个 0 到 1 的置信度低于阈值的直接过滤掉。这样能减少误报提高信噪比。实测下来置信度低于 0.6 的问题大部分确实是误报。6. 后续可以怎么扩展这套工具目前能跑通基本流程但离好用还有距离。我接下来想做的几个方向也供你参考。一个是加自动修复。模型指出问题之后让它直接生成修复后的代码人工确认后一键应用。这个就有点 Agent 的味道了需要模型能理解代码上下文、能生成补丁、能验证补丁不破坏现有功能。技术上可行但风险也大得加严格的确认机制。另一个是加历史追踪。把每次审查的结果存到数据库分析哪些文件经常出问题、哪些类型的问题反复出现。时间长了能看出团队的技术短板有针对性地做改进。还有一个是支持多模型投票。同一个 diff 让多个模型分别审查取交集作为高置信度问题取并集作为待确认问题。这样能降低单个模型的偏差但成本会翻倍。最后是提示词的持续优化。不同项目、不同语言、不同团队适合的提示词不一样。可以做成模板库让用户按场景选择也可以让用户自己写提示词存进去。这套东西我还在持续迭代代码放在本地仓库里等稳定了再考虑开源。如果你也在折腾类似的东西欢迎交流。踩过的坑、试过的方案都可以聊。