实战!手把手教你用Python + Gradio构建AI代码审查助手,告别“人肉”Review的焦虑

上篇《别再逐行手动审代码了！自制本地AI工具批量审查真的香》我们详细介绍了整个审查助手及其具体使用，今天我们继续学习它的技术架构、核心实现、工程化设计与质量风险分析。

本项目整体采用“交互层+审查编排层+文件采集与模型适配层”的分层设计。

虽然项目体量不大，但内部职责边界相对清晰，这使得系统在保持轻量的同时，具备较好的后续扩展基础。

交互层位于ai_reviewer/ui.py中，负责页面渲染、参数收集、按钮事件绑定和异常提示。系统使用Gradio Blocks组织界面，分为模型配置、文件审查和项目审查三个主要区域。

文件审查区域支持多文件上传，项目审查区域支持目录路径和ZIP包两种输入方式，并开放包含模式、排除目录、最大文件数、最大字符数等参数。

交互层本身不承担审查逻辑，只负责把用户输入传递给后端函数，并把返回的三个核心结果展示出来：审查总结、提示词预览、涉及文件列表。

这种设计减少了UI与业务逻辑的耦合度，使得后续替换前端框架时，不必重写核心审查流程。

编排层位于ai_reviewer/reviewer.py，负责组织文件内容、构造提示词、调用模型、处理分批审查以及生成最终结果。该层是项目的核心，也是整个系统从“文件读取器”升级为“审查助手”的关键所在。

编排层中定义了两个核心数据结构：ReviewResult和FileSnippet。前者封装最终摘要、提示词预览和参与审查的文件集合；后者封装单个文件的相对路径与文本内容。

这样的抽象使系统不再直接围绕“原始文件路径”处理问题，而是围绕“可送审的文件片段”处理问题，为后续引入缓存、增量审查甚至Git diff审查提供了良好接口。

文件采集层负责解决“哪些文件应该被送入模型”这一问题。项目通过collect_uploaded_file_snippets处理文件上传场景，通过collect_project_files处理目录遍历场景。

目录审查时，系统会先根据包含模式和排除目录进行筛选，再对二进制文件进行识别和跳过，最后按照最大文件数与最大字符数对数据规模进行控制。

这一层的价值在于，它把模型成本控制前置到了文件采集阶段。也就是说，系统不是在模型调用失败后再考虑“输入太大”，而是在进入模型前就主动做边界治理。

模型适配层通过OpenAI客户端对兼容OpenAI风格的接口进行调用。系统使用base_url、api_key和model三个输入参数完成模型路由配置，因此既可以对接官方接口，也可以对接代理服务或其他兼容实现。

值得注意的是，系统没有假设模型返回内容一定是纯字符串，而是通过extract_message_text与extract_response_text做了兼容解析。

这样做的原因在于，不同兼容接口对message.content的组织形式并不完全一致，有些返回字符串，有些返回内容数组，甚至有些会把主要内容放在扩展字段中。通过统一提取逻辑，系统降低了兼容风险。

系统完整的数据流可以概括如下：

1、用户在页面中选择文件或填写项目路径，并输入审查重点与模型配置。

2、交互层调用对应的审查入口函数。

3、文件采集层读取文本文件内容，过滤二进制文件和排除目录。

4、编排层根据文件数量和总字符规模构造单次提示词或多个批次提示词。

5、模型适配层发起一次或多次模型调用。

6、若存在多个批次，则系统先收集批次结果，再进行最终综合审查。

7、审查结果、提示词预览和涉及文件列表返回至界面。

8、若任意步骤异常，系统将错误信息直接回显给用户。

这种流程兼顾了交互体验与稳定性。尤其是在项目级审查中，系统没有把“超长上下文”问题留给模型兜底，而是通过预先分批和后续综合，实现了更稳妥的推理组织方式。

在许多工具中，单文件和多文件会被当成两套不同流程处理，导致逻辑重复，维护成本上升。本项目采用统一抽象：无论上传一个文件还是多个文件，都会先转化为FileSnippet列表，再进入后续处理流程。

这样一来，单文件只是多文件场景的特例，而不是另一条完全独立的实现路径。

统一处理还有一个直接好处，即多文件审查天然支持批量上下文组织。系统能够在同一轮审查中同时分析多个关联文件，例如某个控制器、服务层和配置文件的组合。

这比孤立地审查单文件更贴近真实工程问题，也更容易让模型识别跨文件接口不匹配、配置缺失或职责边界混乱等问题。

项目审查入口支持两种数据源：本地目录路径和ZIP压缩包。对于本地目录，系统直接遍历文件树；

对于ZIP包，系统会先解压到临时目录，再执行同样的筛选与读取逻辑。解压结束后，临时目录会在finally代码块中清理，避免中间文件残留。

这一设计的意义在于，它将“输入来源”与“审查流程”解耦。后续如果要接入Git仓库快照、CI产物目录或对象存储下载包，也只需新增新的输入解析方式，而不需要大改核心审查逻辑。

批次拆分是本项目最重要的工程策略之一。系统通过_build_project_batches根据累计字符量把多个文件片段拆分为若干批次，每一批次都由多个###FILE块组成。

若总内容较小，则直接进行一次审查；若内容过大，则先对每个批次分别审查，再调用综合提示词，把所有批次结果合并为最终报告。

相比简单截断，这种分层审查策略有两个优势。

●第一，它尽量保留了每个文件片段的完整性，减少“一个文件被拦腰切断”带来的语义损失。

●第二，它把模型的推理任务拆成了“局部分析”和“全局综合”两个阶段，更符合人类审查复杂项目时的思考方式。

当然，这一策略也存在局限。例如，当两个高耦合文件恰好被分到不同批次时，模型在第一阶段可能无法直接发现跨批次问题。但从稳定性与通用性权衡看，这种设计已经显著优于一次性粗暴拼接。

系统中存在四类提示词模板：文件审查提示词、项目审查提示词、项目批次审查提示词和项目结果综合提示词。它们共享同一个核心思想，即明确限定模型角色、审查维度和输出结构。

例如，系统会要求模型重点关注缺陷与正确性、安全风险、性能问题、可维护性和缺失测试，并在输出中按“总体结论”“关键问题”“优化建议”等结构组织内容。

对项目级审查，则进一步强调高优先级问题、架构建议和优先处理顺序。这样的结构化约束可以显著降低结果发散程度，提升报告的一致性和可读性。

值得一提的是，系统允许用户输入“审查重点”。这一字段不会替代默认审查维度，而是作为额外优先级注入提示词。

这样既保证了审查基础面不会缺失，又允许用户针对性能、异常处理、权限控制、测试覆盖率等特定方向做重点放大。

系统采用兼容OpenAI风格的调用方式，而不是把模型厂商写死在代码中。

这个决定的工程价值非常明显：一方面，用户可以根据成本、速度或合规要求切换模型服务；另一方面，项目在部署环境中的适配门槛更低，只要目标服务遵守相近的接口约定即可。

在返回值处理上，系统并没有假设response.choices[0].message.content一定可直接使用，而是增加了兼容层来提取字符串、数组文本乃至某些扩展字段内容。

对于模型输出为空的情况，系统也会显式抛出异常，而不是默默返回空字符串。这样做的好处是，一旦兼容接口行为异常，使用者能够第一时间看到错误原因，而不是误以为“项目没有审查结果”。

如果一个AI工具只在成功时展示结果，而在失败时什么都不说，那么它在实际使用中往往难以建立信任。

本项目在交互层专门提供了统一错误格式，将异常以Markdown形式返回到结果区。同时，launch阶段开启了show_error，便于开发和调试。

此外，系统会展示prompt预览与涉及文件列表。这一点非常关键。它意味着用户可以判断：本次审查究竟包含了哪些文件，某些文件为什么没进来，模型是在什么约束下生成结论的。

对于一个面向工程使用的审查助手来说，这种“输入可追溯”能力比单纯追求结果华丽更重要。

项目当前采用ai_reviewer包承载实际业务代码，根目录保留app.py和reviewer.py作为兼容入口。

这种结构看似简单，实际上体现了较好的工程习惯：真实实现聚合到包内，便于后续继续拆分模块；外部入口保持兼容，避免已有启动方式和旧引用失效。

这一设计为未来扩展测试代码、命令行入口、配置模块甚至安装打包提供了基础。对于一个处于演进阶段的小项目而言，尽早完成“脚本式结构”向“包式结构”的迁移，是很有价值的工程动作。

在目录扫描阶段，系统默认排除了.git、.vscode、node_modules、dist、build、.venv、coverage以及__pycache__等目录。

这一策略有三方面价值：减少无关内容进入模型，降低审查成本；避免噪声文件干扰结论。

同时，系统还会识别二进制文件并跳过。这一点虽不复杂，却十分必要。因为在真实项目中，图片、编译产物、缓存文件和部分非文本资源都可能被遍历到，如果不做过滤，不仅浪费token，还可能导致异常或无意义输出。

系统开放了多个可调参数，包括包含模式、排除目录、最大读取文件数、每文件最大字符数、温度和最大输出token数。它们共同构成了“审查边界控制面板”。

从默认值选择看，项目采用了相对保守的策略。最大项目文件数和每文件最大字符数都有默认上限，温度默认较低，意味着系统更倾向于输出稳定、收敛的审查结论，而不是富于创造性的发散建议。对于代码审查场景而言，这种取舍是合理的。

从质量保障角度看，本项目本身并不声称能够替代人工审查。它更适合做“第一轮自动分析器”或“审查辅助器”。

其优势在于速度、覆盖面和结构化输出，尤其适合帮助测试开发或开发者快速识别高风险区域。系统同样存在若干风险。

首先，模型审查本质上依赖输入上下文，如果关键文件未被纳入，结果自然会失真。

其次，模型输出具有概率性，即使提示词相同，也不保证结论完全一致。

再次，若用户将包含敏感逻辑的源码发送至外部模型服务，则还需额外考虑数据泄露与合规要求。

针对这些风险，当前项目已经提供了若干缓解措施，如文件过滤、结果回显、提示词预览、输入规模限制等。

但从生产使用角度看，后续仍应增加更严格的敏感目录排除、脱敏策略、本地模型支持和审查日志能力。