企业官网建设流程全解析

做代码评审这件事，很多团队都有一肚子话想说。评审本意是提前拦截问题、传递代码上下文，可实际执行起来，要么变成“LGTM（Looks Good To Me）”式的形式主义，要么变成耗费大量时间的逐行辩论。我一直在想，能不能让本地 AI 先把第一遍粗筛干掉，把人从重复劳动里解放出来，只去处理那些真正需要人类判断的问题。带着这个想法，我折腾了一套叫 open-code-review 的本地代码评审系统，搭完之后最大的感受是：它不见得能替代人，但确实能把评审的起点抬高一大截。这篇文章就把这套系统的设计思路、选型过程、落地细节和踩过的坑完整记录下来。

1. 项目概述

1.1 项目要解决的核心问题

open-code-review 是一套面向本地 AI 的代码评审系统，目标很直接：在你提交代码之后、合入之前，让跑在本地的大模型先对 diff 做一次自动评审，输出可能存在的 bug、安全隐患、风格问题、可维护性隐患，再交给人类开发者确认。它不追求替代 Code Review，而是把“机器能做的粗筛”和“人该做的判断”分开，解决三个常见痛点。

第一，评审节奏容易被琐碎问题拖慢。很多团队不是不想认真评审，而是 PR（Pull Request）一多，评审者实在看不过来，最后只能抓大放小，小问题混进主干，慢慢变成技术债。第二，本地代码仓库和 CI（持续集成）环境往往有数据隔离要求，代码不能随便传到外部 API，这就需要一个完全跑在本地的评审方案。第三，现在的大模型编码能力已经相当可观，但对“某个具体仓库的代码风格、边界条件、历史约定”并不了解，直接丢一个完整文件给它，它给出来的建议通常很泛，缺乏针对性。

open-code-review 的定位就是补齐这最后一公里：它围绕 git diff 生成评审上下文，把变更点、关联文件、仓库约定一起喂给本地模型，让模型输出的意见能直接落在一个可执行、可讨论的层面上。

1.2 这套系统适合谁用

如果你正在维护一个中等规模的代码仓库，团队人不多，评审人手紧张，或者你有强离线要求、代码不能出内网，那 open-code-review 这种思路会很合适。它同样适合个人开发者：自己写 side project 没人帮着看代码，让本地模型跑一遍，很多低级错误一眼就能暴露出来。

我自己的主力机器是一张 24GB 显存的显卡，跑 7B 到 14B 参数的量化模型都很从容。如果显存低于 8GB，也不是不能玩，但需要选更小的模型，比如 3B 到 4B 参数档位，并且要把代码分块控制得更小。文章后面会专门讲参数调整和模型选型。

2. 整体设计与工作流程

2.1 一个最小可用的评审闭环

在设计 open-code-review 之前，我先把“本地 AI 评审代码”这件事拆成了几个不可跳过的环节：获取变更内容、构造评审上下文、调用模型生成意见、汇总输出结果。逐个拆开之后，你会发现大部分功能其实不复杂，真正的难点在“怎么让模型看到它该看的东西”。

先说获取变更内容。最通用的方式是读 git diff，因为 diff 本身就浓缩了这个 PR 做了什么。但光有 diff 不够，模型经常需要知道修改发生在哪个函数里、这个函数的完整实现长什么样、同文件里有没有类似的既有写法。所以 open-code-review 的做法是：解析 diff 中每个变更文件，提取变更行所在的函数或类范围，再连同相关代码片段一起构造输入。

再说评审上下文。我给模型设计的输入结构大体是这样的：先给系统指令，说明这是一个严格的代码评审任务，要求模型按严重程度输出问题；接着给仓库约定，比如缩进风格、命名规则、禁用的语法；然后给这一次的变更内容，按文件分块；最后给出输出格式模板。整个过程不是把整个仓库灌给模型，而是精准抽取“与变更相关的最小集合”。

最后是输出。模型输出我要求用结构化的文本格式，每条问题带文件路径、行号、问题级别、原因说明和修改建议。这样后续无论是接到终端展示，还是转成评论发布到 GitLab/GitHub，都有明确的解析目标。

2.2 为什么选本地模型而不是云端 API

这可能是很多人第一时间会问的问题：现在各家云端模型代码能力都这么强，为什么不直接调 API？我当时的考虑有三个。

第一是隐私和合规。企业内部代码往往有严格的保密要求，尤其是还没公开的业务逻辑、密钥相关代码，往外发一次就多一分风险。本地推理把这些数据全部留在自己的机器上，心理负担和合规压力都小很多。第二是成本。代码评审是高频动作，每个 commit 都可能触发一次，如果每次都按 token 计费，长期下来是一笔不小的支出；本地推理只有电费和硬件折旧，跑得再多也不心疼。第三是定制空间。本地模型你可以随意调 prompt、调整采样参数、甚至微调，不用受外部 API 的约束。

当然，本地方案也有明显的短板：对硬件有要求，模型能力上限通常低于云端顶尖模型，推理速度也慢一些。但对我来说，这些短板在接受范围内，而且随着开源模型迭代，差距正在快速缩小。如果你跑的是最新一代的开源代码模型，在绝大多数常规代码评审场景下，它的输出质量已经够用了。

2.3 工作流设计：什么时候触发、什么时候等人工

open-code-review 的默认工作流不是“全自动合入”，而是“机器先审，人工复核”。我通常把它接在 git 的 pre-push hook 或者 CI 的第一个阶段。代码推到远端之前，先跑一遍本地评审，发现高危问题就直接在终端标红，开发者本地改完再推。如果推到远端，CI 里也可以再跑一遍，把评审意见以评论形式关联到 MR/PR 上。

这里有个设计取舍：到底是把评审结果当“门禁”强制拦截，还是当“建议”仅作参考？我的建议是默认不要做强门禁。因为本地模型一定会产生误报，把误报变成硬性拦截反而会消耗团队信任。更好的做法是让结果直观、可追溯，但由人来决定是否处理。只有当模型在某几类规则上表现足够稳定之后，再考虑为那几类问题单独设置检查门槛。

3. 技术选型与核心模块

3.1 模型选择：到底该用哪个开源模型

本地代码评审对模型的要求和普通聊天不太一样。它需要模型有较强的代码理解能力、指令遵循能力，还要尽量低的幻觉率。我实际对比过几类模型，简单说下适用场景。

如果你显存在 8GB 到 16GB 之间，可以优先考虑 Qwen2.5-Coder-7B-Instruct 或者 DeepSeek-Coder-6.7B-Instruct 的量化版本。这两个模型对中英文指令的理解都不错，代码能力在 7B 档位里属于第一梯队，跑起来速度也快。我自己最开始就是用 Qwen2.5-Coder-7B 做的验证，效果已经比预想好很多。

如果显存在 24GB 左右，可以上 Qwen2.5-Coder-14B 或者 CodeLlama-34B 的更大量化档。14B 的模型在复杂逻辑判断上明显比 7B 更稳，尤其是在分析空指针、并发问题、资源泄漏这类需要多步推理的场景。再往上走的话，比如 32B 甚至 70B 的模型，推理速度会明显下降，除非你有充裕的时间和算力，否则对日常评审来说有点奢侈。

我在选型时看两个硬性指标：一是 HumanEval 之类的代码生成分数（虽然不能完全代表评审能力，但能反映基础代码理解水平）；二是上下文长度。评审任务往往需要塞入多段代码，上下文太短的话很容易截断关键信息。现在很多新模型的上下文做到了 32K 甚至 128K，但实际使用时会发现，上下文越长，推理越慢，所以不是越长越好，够用就行。

3.2 推理引擎：用 llama.cpp 还是 Ollama

本地推理这块，我先后用过 llama.cpp 和 Ollama，最后长期留的是 Ollama，但底层思路两者相通。llama.cpp 胜在灵活、资源占用低，你可以精确控制量化方式和 GPU 层数，适合喜欢折腾的人。Ollama 胜在开箱即用，一条命令就能把模型跑起来，而且它对模型文件的管理、API 的暴露都做得比较规范，适合我这种更关注上层业务的人。

实际落地时，我建议通过 Ollama 的 HTTP API 来对接，而不是直接走命令行交互。原因是评审流程需要程序化地发送 prompt 并解析流式响应，命令行交互不利于自动化。Ollama 默认监听 11434 端口，用 Python 的 requests 或者 OpenAI SDK 兼容接口就能轻松对接，省去很多中间层的开发。

如果你的机器上已经装了 Docker，也可以用 Ollama 的容器镜像跑，这样环境隔离更干净，升级也方便。我个人没用容器方案，因为本地模型文件比较大，直接装原生程序更省心。

3.3 上下文构造：怎么把代码喂给模型才能让它“看得懂”

这部分是整个系统里最影响效果的地方。直接丢一行 git diff 给模型，它很难判断这行改动是不是真的有问题，因为它不知道这个函数原本的意图、不知道周围变量的类型、也不知道可能被哪些地方调用。所以 open-code-review 做了一个“上下文增强”模块。

第一步，解析 git diff，拿到修改文件的列表和每个文件的 hunk。第二步，定位每个 hunk 中变更行所在的函数或方法，用简单的语法解析或者正则匹配，提取这个函数在最新版本里的完整代码。第三步，把原始 diff、完整函数代码、相关文件列表、仓库约定一起按固定格式拼接。第四步，如果整体内容超过模型上下文限制，就按文件拆成多个子任务，而不是暴力截断。

这四步听着简单，但每一步都有细节。比如定位函数时，Python 可以按缩进判断，Go 可以按大括号匹配，JavaScript 则要小心箭头函数和对象方法的写法。为了省事，我第一版只支持 Python 和 JavaScript，后面才慢慢扩展。每一类语言加进来的时候，都要专门准备一批测试用例，确保函数边界抓得准。

3.4 Prompt 设计：评审意见怎么才能不“泛泛而谈”

我见过很多人用 AI 做评审，得到的意见永远都是“建议增加空行”“注意命名规范”这种正确但没用的废话。问题往往出在 prompt 上，模型确实知道代码有问题，但你给它的任务描述太空泛，它只能按最安全的套路输出。

我给 open-code-review 设计的系统提示词包含几个固定部分。第一，角色定位：“你是资深代码评审专家，擅长发现逻辑缺陷、边界条件、安全问题与可维护性隐患。”第二，任务边界：“只针对本次变更，不要评价未修改的既有代码。”第三，输出要求：“每条意见必须包含文件路径、行号、严重程度（高危/中危/低危/建议）、问题描述、修改建议。”第四，回答约束：“如果变更没有问题，请明确回答无需改动，不要编造问题。”

其中“不要评价未修改的既有代码”和“无需改动时明确回答”这两条非常关键。没有这两条，模型很容易把仓库里原有的问题都翻出来，让输出变成一堆噪音；也容易为了“显得有用”强行报几条意见，误报率居高不下。加进去之后，整个输出质量肉眼可见地提升。

4. 从零到一：搭建 open-code-review 的实操过程

4.1 环境准备与依赖安装

我这套环境的基准配置是：Ubuntu 22.04，CPU 是 8 核，内存 32GB，显卡 RTX 3090 24GB。如果你用的是 Windows，建议优先考虑 WSL2，因为在原生 Windows 上跑 llama.cpp 或者 Ollama 虽然也能跑，但 GPU 加速配置更麻烦，遇到问题社区资料也没那么多。

第一步安装 Ollama：

curl -fsSL https://ollama.com/install.sh | sh

安装完后先拉取模型：

ollama pull qwen2.5-coder:14b

如果你显存小于 16GB，可以换成：

ollama pull qwen2.5-coder:7b

拉取模型的同时，我把 open-code-review 的代码从仓库克隆下来，创建 Python 虚拟环境：

git clone https://github.com/yourname/open-code-review.git cd open-code-review python3 -m venv venv source venv/bin/activate pip install -r requirements.txt

依赖项不多，核心就是 requests、gitpython、pyyaml。这里要提醒一句，gitpython 不是必须的，如果你不想引入额外依赖，直接用 subprocess 调用 git 命令也可以。但 gitpython 在处理 diff 的时候更方便，尤其是按文件、按 hunk 解析时，能省不少代码。

4.2 配置文件：让系统认识你的仓库

open-code-review 的配置我放在一个 YAML 文件里，结构大致如下：

model: qwen2.5-coder:14b base_url: http://localhost:11434 temperature: 0.2 max_tokens: 2048 repo: path: /path/to/your/project language: python convention: | - 使用 4 空格缩进 - 函数命名使用 snake_case - 禁止使用全局可变状态 rules: enabled: - logic - security - performance - style

这里的 temperature 我固定在 0.2。评审任务不是创作任务，需要的是稳定输出和低随机性，温度调太高会让模型反复横跳，同一段代码跑两次意见不一样，没法看。max_tokens 设 2048 一般够用，如果仓库里一次变更特别大，输出可能会被截断，可以适当往上调。

仓库约定这项看似简单，实际上对输出质量影响很大。模型不知道你们团队约定什么命名风格、什么场景禁止做什么，你把约定写清楚，它就能在评审时主动比对。我就见过一个团队把“禁止在 try 块里写空 except”写进约定之后，模型对这种问题的检出率立刻提高。

4.3 写一个最小工作流脚本

核心逻辑我封装到了一个 Python 脚本里。整体流程可以概括为三步：取 diff，构造 prompt，解析模型输出。

先看获取 diff 的部分：

import subprocess def get_diff(repo_path, commit_range="HEAD~1..HEAD"): result = subprocess.run( ["git", "-C", repo_path, "diff", "--unified=20", commit_range], capture_output=True, text=True, encoding="utf-8", ) return result.stdout

--unified=20这个参数容易被忽略，但它很重要。默认 diff 上下文只有 3 行，模型很难看清被修改代码的完整逻辑；放大到 20 行，模型能更好地理解变更所在的函数上下文。当然，代价是输入变长、推理变慢，具体数值你可以自己权衡。

然后是构造 prompt。我会先读配置里的仓库约定，再拼接 diff 内容，最后在末尾加上输出格式要求：

def build_prompt(diff_text, convention): prompt = f""" 你是一名资深代码评审专家。请针对以下代码变更进行评审。 仓库约定： {convention} 变更内容：

{diff_text}

要求： 1. 只针对变更部分给出意见，不要评价未修改代码。 2. 按以下格式输出，每条意见单独一行： [级别] 文件路径:行号 问题描述 | 修改建议 级别取值：高危/中危/低危/建议 3. 如果变更没有明显问题，只输出：无需改动 """ return prompt

最后调用 Ollama 的接口：

import requests def review_diff(prompt, model, base_url, temperature=0.2): response = requests.post( f"{base_url}/api/generate", json={ "model": model, "prompt": prompt, "stream": False, "temperature": temperature, }, timeout=300, ) return response.json()["response"]

这里我使用了 requests 库，实际生产环境下建议用 OpenAI SDK 的兼容接口，因为 Ollama 从某个版本开始已经支持 OpenAI 格式了，接口更标准化，后续换其他推理引擎也方便。

4.4 跑通第一个评审案例

我在一个测试仓库里故意制造了几类问题：一个未判空的可能空引用、一个重复计算导致的小性能浪费、一个命名不规范的临时变量。然后运行脚本，看模型能不能识别出来。

第一次跑的时候，输出确实有些惊喜。模型不仅找出了空引用，还给出了复现路径，虽然没有精确到行号，但已经能定位到具体函数。同时它也输出了好几条“建议增加注释”这类低价值意见，误报率仍然存在。我没有急着调模型，而是先调 prompt：在要求里加了一句“只有影响代码正确性、安全性或可维护性的问题才需要输出，风格类问题仅在明显违反仓库约定时输出”。这一改，低价值意见立刻少了很多。

这里想强调一个经验：不要一上来就怪模型“笨”，很多时候是输入和指令不够清晰。先把 prompt 里的约束写明白，再考虑换更大的模型，这是成本最低的优化路径。

5. 实际使用效果与参数调优

5.1 用三个指标衡量评审效果

在调参之前，得先定义什么叫“效果好”。我给自己定了三个指标：查全率、查准率、单次评审耗时。

查全率指的是“模型找出的真实问题数 / 真实问题总数”，这个指标关心的是漏报。查准率指的是“模型找出的问题中真实问题占比”，这个指标关心的是误报。评审任务里，两个指标都重要，但实际使用时容易顾此失彼：你为了降低漏报，让模型更激进地报问题，误报率马上上来；你为了减少误报，让模型更保守，漏报又明显增加。这个平衡点没有标准答案，取决于你团队的容忍度。我的设置是：中危以上的误报可以接受部分存在，但高危误报不能太多，因为开发者会逐条看，报得太离谱容易失去信任。

耗时这个指标容易被忽略，但体验影响很大。如果一次评审要等十分钟，开发者大概率就不会在本地跑了，只有 CI 里强制跑才行。我一般把单次评审控制在 30 秒到 2 分钟以内，超过这个范围的变更就分块处理。

5.2 温度与上下文窗口

temperature 是影响随机性的关键参数。我实际测试过 0.2、0.5、0.8 三档，0.8 时模型会写一些花哨的解释，但推理结论不稳定，同一段代码跑两次可能给出完全不同的意见；0.5 仍然有波动；0.2 基本稳定，偶尔会有微小措辞差异，但结论一致。所以最终固定在 0.2。如果你用 low temperature 时发现模型总是给出“安全但无用”的回复，可以考虑微调到 0.3 到 0.4，但别超过 0.5。

上下文窗口不是调越大越好。模型支持 32K 上下文，但实际塞太多内容进去，注意力会被稀释，模型可能忽略真正关键的问题。我一般把单次评审的输入控制在 6K 到 8K token 以内。如果一次变更包含十几个文件，我会先按文件分组成多个子任务，每个子任务独立评审，最后合并结果。这样虽然总的耗时变长了，但每个子任务的质量有保障。

5.3 一次真实 Pull Request 的评审记录

我拿一个真实的 Python Web 项目 PR 做过测试。这个 PR 改动了一个订单查询接口，涉及 3 个文件：一个新增的查询函数、一个修改的数据库访问层、一个修改的路由注册。

模型输出的意见里比较有价值的有三条：一是指出新增查询函数里缺少对输入参数空字符串的校验，可能导致后续数据库查询条件失效；二是指出数据库访问层新增的排序逻辑没有加索引提示，数据量大时会有性能问题；三是路由注册里异常处理只捕获了通用 Exception，建议细分异常。

这三条虽然称不上“惊艳”，但都指向了真实存在的问题，而且基本符合评审者会提出的方向。作为第一遍粗筛，这个质量已经能帮助评审者把注意力集中到更核心的业务逻辑上。当然它也漏掉了一个问题：并发场景下订单状态的原子更新没有考虑，这个需要模型理解更复杂的业务约束，确实超出了它当前能力。所以结论很明确：它能做助理，别让它当终审。

6. 常见问题与排查技巧

6.1 模型输出不稳定，怎么办

症状：相同代码、相同 prompt，跑两次意见完全不同。原因通常是 temperature 太高，或者 prompt 里的约束不够强。先检查 temperature，评审任务应当尽量低，建议 0.2 以下。如果温度正常，再检查 prompt 开头是不是给了足够清晰的角色和任务边界。还有一种情况是量化模型本身的不确定性，低比特量化会让输出稍微波动，可以换更高比特的量化文件或者更稳定的模型。

另一种“不稳定”不是随机性问题，而是输出格式不统一。模型有时候不按你要求的格式输出，直接生成一段对话式意见。解决办法是在 prompt 里给出一个输出示例，再做一层轻量的后处理解析。解析失败的时候，我宁愿丢弃这条输出，也不要把它原样贴给开发者。

6.2 推理速度慢、内存不足

如果你跑 14B 模型时出现内存不足或生成速度很慢，第一件事是确认显存是否足够。Ollama 默认会优先加载到 GPU 上，但显存不够时会把部分层放到 CPU，速度断崖式下降。查看是否 GPU 加载的命令：

ollama ps

看输出里 GPU 和 CPU 的列，如果很多层都在 CPU 上，说明显存不够，考虑换小模型或者加量化。另外可以限制进程使用的 CPU 线程数，避免推理时整机卡死。还有一个小技巧：把并发请求数限制为 1，避免多个评审任务同时挤占资源。

6.3 误报太多，开发者开始不信任结果

这是团队落地时最容易出的问题。我的经验是分两步走：先从 prompt 端压制误报，例如明确说“只有影响正确性、安全性的问题才报告高危”；再做规则白名单，把模型容易误报的场景写到仓库约定里。比如我们约定“所有临时调试打印必须移除”，模型就会更认真地查这个点，而不是漫无目的地挑刺。

如果仍然误报太多，可以给输出加一个置信度字段，让模型自己对每条意见标记“确认/需要人工确认”。虽然这个置信度不完全可靠，但能给开发者一个优先级参考，减少“逐条判断是否值得看”的负担。

6.4 换了新语言后效果下降

模型训练语料对热门语言覆盖更好，冷门语言自然效果差一些。遇到这种情况，我会先调整 prompt 中仓库约定部分，把语言的常见陷阱写进去。比如 C++ 里我会强调注意指针所有权和异常安全，Rust 里强调生命周期和所有权约束。这一招能让模型更聚焦在语言特有的风险上，效果比换更大的模型更明显。

如果你的仓库里同时存在多种语言，建议按语言拆成不同的评审配置，为不同语言设定不同的约定文本。不要试图用一个通用 prompt 覆盖所有语言，那只会让模型每样都懂一点，每样都不够精准。

7. 后续扩展方向和我的个人体会

open-code-review 目前对我来说已经是一个稳定可用的工具了。平时开发时，我先跑一遍本地评审，再自己过一遍，提交质量明显比裸写好很多。让我比较意外的是，它不光帮我发现了 bug，还会逼着我把“为什么这么写”想得更清楚：当模型对一个改动提出质疑时，我需要能解释清楚为什么它是合理的，这个解释过程本身就是一种提升。

后续我打算做两个扩展。第一是支持把评审结果直接发布到 GitLab/GitHub 的 MR/PR 评论上，而不是只输出在终端里。这个在技术上不复杂，主要是要处理评论文本过长和重复评论的去重问题。第二是想做一个“误报反馈”机制：如果开发者标记某条意见是误报，可以记录下来，后续通过微调或者参考示例的方式改进模型表现。这等于把团队评审沉淀成模型经验，价值会越来越大。

还有一个扩展方向是接入更细粒度的静态分析结果。大模型和传统静态分析工具各有侧重：静态分析在数据流、控制流分析上很精准但规则有限；大模型灵活但有时会漏。把两者结合，让模型基于静态分析告警做深入判断，误报和漏报都能再压一压。

如果你也想在本地搭一套，我的建议是从最小闭环开始：先跑通单次提交的评审，别急着做 CI 集成和评论回写。等 prompt 和模型选型都稳定了，再把自动化一步步加上。毕竟工具再强大，最终还是要让开发者用起来觉得省事、可信。机器先把粗活干了，人就能把注意力留给真正有价值的讨论，这可能才是代码评审这个环节最该有的走向。