别再逐行手动审代码了!自制本地AI工具批量审查真的香

在软件研发活动中，代码审查始终是保障质量的重要环节。

无论是需求迭代中的增量开发，还是历史系统的维护重构，团队都需要通过审查识别潜在缺陷、发现安全隐患、评估可维护性，并尽可能在缺陷进入测试甚至生产之前完成纠偏。

但在实际工作中，代码审查往往面临两类典型矛盾：一方面，技术团队希望审查尽量深入，能够覆盖正确性、性能、安全、测试充分性等多个维度；

另一方面，审查本身又受到人力、时间和上下文复杂度的限制，尤其在跨语言、多文件或项目级分析场景下，人工审查成本会迅速上升。

传统代码审查流程通常依赖开发工程师或测试开发工程师手工完成。执行者需要先阅读文件内容，再理解模块边界、推断上下文关系、提炼关注点，最后给出结构化建议。

这一过程高度依赖个人经验和注意力稳定性。对于简单文件，人工审查尚可快速完成；但在文件数量增加、上下文跨越多个目录甚至需要从整个项目视角理解风险时，审查效率和稳定性都会明显下降。

大语言模型的出现，为代码审查自动化提供了新的实现路径。相比传统静态规则工具，LLM不仅能够理解自然语言指令，也能对程序结构、错误模式和潜在风险进行一定程度的语义推理。

因此，一个实用的代码审查助手，不应只是“把文件内容发给模型”这么简单，而应在输入组织、上下文控制、批次拆分、结果整合、错误回显和交互体验等方面进行完整设计。

本文围绕一个轻量级AI代码审查项目展开。该项目以Python为实现语言，采用Gradio构建交互界面，使用兼容OpenAI风格的接口作为模型接入方式，支持单文件、多文件以及整个项目目录的审查流程。

系统既可以直接读取本地项目目录，也支持上传ZIP压缩包进行项目级分析。在项目规模较大时，系统会自动拆分多个批次分别审查，再生成最终汇总报告。

和许多Demo性质的AI工具不同，本项目强调对可落地的审查过程控制。它不仅生成结果，还尽量让用户知道系统究竟审查了哪些文件、向模型发送了什么提示词、何时发生了异常，以及结果为什么会被拆分汇总。

换言之，本项目的目标不是替代工程师判断，而是降低代码审查的进入门槛，提高首轮筛查效率，为开发、测试和评审提供一个可解释、可扩展的辅助系统。

代码审查类工具大体可以分为两类。第一类是基于规则和模式匹配的静态分析工具。

这类工具在语法错误、空指针、未使用变量、部分安全规则等方面效果稳定，但对于跨文件语义理解、业务合理性判断和测试建议生成往往能力有限。

第二类是基于大模型的审查系统，这类系统具有较强的自然语言理解和综合分析能力，但也面临上下文长度、成本控制、结果一致性与数据安全等问题。

如果不对输入内容做管理，直接把大量项目文件拼接发送给模型，会迅速遇到三个问题。

● 第一，输入体积不可控，超过上下文窗口后必须截断，而截断位置一旦不合理，就可能丢失关键语义。

● 第二，文件数量过多时，模型容易给出泛化描述，而不是定位到具体文件的问题。

● 第三，用户很难判断结果是否可信，因为他不知道模型看到了哪些内容、遗漏了哪些内容。

因此，一个真正能用于日常工作的代码审查助手，需要具备明确的输入选择策略、合理的上下文分片机制以及可追踪的输出方式。

结合上述问题，本项目的设计目标可以概括为以下四点：

● 第一，提供统一的审查入口，支持单文件、多文件和项目目录三种输入模式。

● 第二，在项目规模较大时自动完成内容裁剪、批次拆分和结果汇总，避免一次性向模型灌入过长上下文。

● 第三，兼容OpenAI风格接口，便于接入不同厂商或本地模型，降低模型替换成本。

● 第四，提供面向使用者的可解释信息，包括涉及文件列表、提示词预览和错误回显，以提升审查结果的可理解性。

从功能定位看，本项目并不是一个通用代码托管平台插件，也不是一个完整的CI审查流水线，而是一个轻量、直接、可本地运行的AI审查助手。

它的主要使用场景包括：测试开发对某个变更文件做快速风险评估，开发者在提交前对多个核心文件做自检，以及对一个中小型项目进行首轮整体审查。系统当前提供两类审查模式。

第一类是“文件审查”，支持上传一个或多个代码文件。该模式适合针对具体变更进行集中分析，尤其适用于补丁检查、功能点回归前的重点排查等场景。

第二类是“整个项目审查”，支持输入本地目录路径或上传ZIP包，并允许用户配置包含模式、排除目录、最多读取文件数和每文件最大字符数。这一模式更接近架构性和工程性分析。

从交互方式看，系统采用Gradio提供Web页面，用户可以直接在界面中输入模型地址、密钥、模型名以及审查重点。审查结果以Markdown形式展示，便于阅读结构化结论；

同时，系统还会展示本次真正发送给模型的提示词，以及参与审查的文件列表。对于需要调试提示工程或核对输入边界的用户，这一设计非常重要。

在首次使用前，需要完成Python虚拟环境的创建与依赖安装。项目依赖项已在requirements.txt中定义，主要包括gradio和openai两个核心包。

Windows PowerShell：

python -m venv .venv.\.venv\Scripts\Activate.ps1pip install -r requirements.txt

Windows CMD：

python -m venv .venv.\.venv\Scripts\activate.batpip install -r requirements.txt

macOS/Linux：

python3 -m venv .venvsource .venv/bin/activatepip install -r requirements.txt

项目提供两种启动入口：

# 方式一：通过根目录入口启动python app.py# 方式二：通过包模块入口启动python -m ai_reviewer

启动后，系统会在本地启动Gradio Web服务，默认监听 http://127.0.0.1:7860。用户可在浏览器中打开该地址进行交互。

在界面顶部的“模型配置”区域，需要填写以下参数：

| 参数 | 说明 | 默认值 ||------|------|--------|| Base URL | 模型服务地址，兼容 OpenAI 风格接口 | `https://api.openai.com/v1` || API Key | 模型访问密钥 | 无（需用户填写） || Model | 模型名称 | `gpt-4o-mini` || Temperature | 输出随机性，值越低越稳定 | `0.1` || Max Tokens | 最大输出长度 | `2048` |

用户可根据实际需求切换模型服务。例如，若使用本地部署的模型代理服务，只需将Base URL指向代理地址即可。

文件审查模式适用于对单个或多个代码文件进行集中分析。操作步骤如下：

1、切换到“文件审查”标签页

2、点击上传区域，选择一个或多个代码文件（支持.py、.js、.ts、.java、.go等常见格式）

3、在“审查重点”文本框中填写关注方向，例如：

  ● Python代码规范、异常处理

  ● SQL注入风险、权限校验

  ● React性能优化、Hooks使用规范

4、确认模型配置无误后，点击“开始文件审查”按钮

审查完成后，界面将展示三部分内容：

● 审查结果：以Markdown格式呈现的结构化审查报告，包含总体结论、关键问题、优化建议等

● Prompt预览：本次实际发送给模型的完整提示词，便于调试和验证

● 涉及文件：本次审查纳入的文件列表

项目审查模式适用于对整个项目目录进行全局分析。系统支持两种输入方式：

方式一：本地目录路径

直接填写项目所在目录的绝对路径，例如：

● Windows：E:\my_project

● macOS/Linux：/home/user/my_project

方式二：上传ZIP压缩包

将项目打包为zip文件后上传。系统会自动解压并分析。

项目审查模式下，用户可配置以下参数：

| 参数 | 说明 | 默认值 ||------|------|--------|| 包含文件模式 | 需纳入审查的文件类型，逗号分隔 | `*.py, *.js, *.ts, *.tsx, *.jsx, *.java, *.go, *.rs, *.cpp, *.c, *.cs, *.md, *.json, *.yaml, *.yml, *.toml, *.sh` || 排除目录 | 需跳过的目录，逗号分隔 | `.git, .idea, .vscode, __pycache__, node_modules, dist, build, .next, .venv, venv, coverage` || 最多读取文件数 | 项目审查时读取文件的上限 | `40` || 每个文件最多读取字符数 | 单文件内容截断阈值 | `12000` |

操作步骤：

1、切换到“整个项目审查”标签页

2、填写项目目录路径或上传ZIP包

3、根据需要调整包含模式、排除目录、文件数限制等参数

4、填写审查重点，例如：

  ● 微服务边界划分、服务间通信

  ● 配置安全、敏感信息泄露

  ● 测试覆盖率、关键路径测试

5、点击“开始项目审查”按钮

当项目文件内容总量较大时，系统会自动启动批次审查机制：

1、系统将文件片段按字符量拆分为多个批次（默认每批次约 32000字符）

2、对每个批次分别调用模型进行审查

3、收集所有批次的审查结果

4、调用综合提示词，将各批次结果合并为最终报告

在Prompt预览区域，用户可以看到：

● 批次拆分信息

● 首个批次的提示词内容

● 最终汇总提示词内容

这种机制确保了大规模项目审查的稳定性，避免因上下文过长导致的截断或质量问题。

审查结果采用统一的中文结构化输出格式。

文件审查结果结构：

1、总体结论

2、关键问题

3、优化建议

4、建议补充的测试

项目审查结果结构：

1、项目总览

2、高优先级问题

3、中低优先级问题

4、架构与工程化建议

5、建议优先处理顺序

用户可根据报告中的优先级排序，有针对性地进行问题修复和代码改进。