三亩地 三亩地SAN MU DI · CODE DIARY
交流投稿
ARTICLE DETAIL

日记详情

真实记录编程学习的某一天，欢迎挑你感兴趣的翻一翻。

首页/学习日记/日记详情

基于多Agent架构的AI代码审查系统：原理、实现与工程实践

发布时间：2026/8/6 4:34:53 三亩地 编程学习日记
基于多Agent架构的AI代码审查系统：原理、实现与工程实践

1. 项目概述：当代码审查遇上AI Agent

最近在团队内部搞了个挺有意思的玩意儿，我们叫它“AI Code Review Agent”。说白了，就是让AI来当你的代码审查员。这可不是简单的静态代码分析工具，也不是让大模型读一遍代码给点模糊建议。我们构建的是一个基于多Agent架构的自动化系统，它能模拟一个资深开发者在Review代码时的完整思考链路：从代码风格、潜在Bug、安全漏洞，到架构设计合理性，甚至能结合你团队的编码规范给出定制化建议。

为什么做这个？相信每个开发者都深有体会。人工Code Review成本太高了，资深工程师时间宝贵，新人又可能看不出深层问题。传统的自动化工具（比如SonarQube、Checkstyle）规则是死的，只能检查一些硬性的格式错误和已知的代码坏味道，对于代码逻辑、设计模式运用、业务上下文理解这些需要“智能”判断的地方，完全无能为力。而大语言模型（LLM）的出现，让我们看到了解决这个问题的可能性。但直接用ChatGPT去审代码，效果又很随机，缺乏系统性，也无法集成到CI/CD流程里。

我们的目标，就是打造一个稳定、可定制、可解释、能落地的AI审查伙伴。它不是一个黑盒，它的每一步判断你都能追溯原因；它也不是一个孤立的玩具，它能无缝接入你的Git工作流，在提交PR时自动运行，给出结构化的审查报告。这个项目的核心，就在于“多Agent架构”。我们不是用一个AI去干所有事，而是设计了一组各司其职的“智能体”（Agent），让它们协作完成审查任务，这比单一模型“一把梭”要可靠和强大得多。

2. 核心架构设计：为什么是多Agent？

在项目启动前，我们评估过几种方案。最简单粗暴的，就是写个脚本，把代码片段和提示词（Prompt）扔给OpenAI的API，然后解析返回结果。我们试过，问题一大堆：审查点不全面、反馈格式混乱、对长上下文支持不好、而且一旦遇到复杂模块，模型很容易“跑偏”或给出笼统的建议。这就像让一个全才去同时做语法检查、安全审计和架构评审，结果往往是哪样都不精。

所以，我们决定采用多Agent协同的架构。其核心思想是“分而治之”与“专业分工”。我们把复杂的代码审查任务，拆解成多个子任务，并为每个子任务设计一个专门的、能力聚焦的Agent。这些Agent共享一些基础能力（比如代码理解），但在其专业领域内有更精细的Prompt工程和决策逻辑。

2.1 架构组成与职责划分

我们的系统主要由以下几类Agent组成，它们像是一个虚拟的审查委员会：

  1. 协调者Agent (Orchestrator Agent)：

    • 职责：它是系统的“大脑”和“调度中心”。当一个新的代码变更（如Git Pull Request）触发审查时，协调者Agent首先被激活。它的工作是分析变更集（diff），理解这次提交的总体范围（是前端UI改动、后端API新增，还是数据库迁移脚本），然后制定审查计划。
    • 具体工作：决定需要调用哪些专项Agent（例如，如果改了SQL文件，就一定要调用安全Agent；如果新增了API接口，就需要调用架构和API设计Agent）。它还会初始化审查上下文，包括代码库信息、相关技术栈、团队特定的规则等。

  2. 代码风格与规范Agent (Style & Convention Agent)：

    • 职责：这是最“死板”但也最必要的Agent。它负责检查代码格式、命名规范、注释要求等。与传统的Linter不同，它不仅能应用通用规则（如PEP 8 for Python, Google Java Style），还能动态加载和适配团队自定义的规范文档。
    • 实现关键：它的Prompt里会明确写入团队规范，例如：“我们规定Service层类名必须以Service结尾”、“DTO字段必须使用@JsonProperty注解”。这样，它的审查建议就极具针对性，而不是泛泛而谈的“建议统一命名风格”。

  3. 静态分析与缺陷检测Agent (Static Analysis & Bug Detection Agent)：

    • 职责：查找潜在的编程错误和代码坏味道。例如，空指针引用、资源未关闭（如数据库连接、文件流）、循环内的低效操作、重复代码块等。它会结合抽象语法树（AST）分析和语义理解。
    • 优势：相比传统静态分析工具，它能理解意图。比如，它看到一段手动拼接SQL的代码，不仅能提示“有SQL注入风险”（这是规则），还能进一步建议“考虑使用MyBatis的#{}占位符或JPA的查询构造器”，因为它理解代码的上下文和可用的技术组件。

  4. 安全与漏洞扫描Agent (Security & Vulnerability Agent)：

    • 职责：专注于安全层面。检查硬编码的密码、密钥、不安全的反序列化、XXE漏洞、CORS配置不当、依赖库中的已知漏洞（需要集成SCA工具数据）等。
    • 深度：这个Agent的Prompt经过了特殊训练，包含大量OWASP Top 10案例和修复方案。它不仅能指出问题，还能提供修复代码片段示例，这对于初级开发者尤其有帮助。

  5. 架构与设计模式Agent (Architecture & Design Pattern Agent)：

    • 职责：这是最具“智能”和挑战性的部分。它审查代码的结构合理性，比如是否符合分层架构、是否恰当使用了设计模式（单例用对了吗？这个场景用策略模式是否过度设计？）、模块间的耦合度是否过高、新加的类是否职责单一。
    • 工作方式：它需要“看到”比当前变更更广的上下文。协调者Agent会为它提供相关的模块接口定义、关键类的代码。它的审查意见往往像资深架构师的点评，例如：“这个新的PaymentProcessor类与OrderService存在双向依赖，建议引入事件驱动模式解耦。”

  6. API与契约Agent (API & Contract Agent)：

    • 职责：如果变更涉及REST API或RPC接口，这个Agent会被激活。它检查API端点设计是否符合RESTful规范、请求/响应体的数据结构是否一致、前后端契约（如Swagger/OpenAPI文档）是否需要同步更新。
    • 实用功能：它甚至可以对比新旧版本的API定义，自动提示“你删除了/user/{id}的GET方法，但前端模块X仍在使用它，这可能导致兼容性问题。”

  7. 报告生成与汇总Agent (Report & Summarization Agent)：

    • 职责：所有专项Agent完成审查后，会将各自的结果（包括问题描述、严重等级、代码位置、修复建议）提交给报告Agent。这个Agent的任务是汇总、去重、排序，并生成一份人类可读的审查报告。
    • 核心价值：它不只是简单罗列。它会将问题归类（风格、缺陷、安全、架构），按严重性（阻塞、重要、建议）排序，并生成一个简明的总结，比如：“本次提交主要引入了3个重要问题（1个安全警告，2个潜在空指针）和5个代码风格建议。总体风险中等，建议修复前3项后再合并。”

提示：多Agent架构的核心优势在于“可插拔”和“可演进”。如果你的项目不用Java用Go，你可以替换或调整“代码风格Agent”的规则库；如果未来出现了新的审查维度（比如性能瓶颈分析），你只需要开发一个新的专项Agent，注册到协调者那里即可，系统整体架构无需推翻重来。

2.2 Agent间的通信与协作流程

这些Agent不是孤立工作的，它们通过一个清晰的消息协议进行协作。我们采用了一种基于“事件”或“工作流”的轻量级协调模式。

  1. 触发：Git Webhook通知系统有新的PR。
  2. 协调：协调者Agent被唤醒，获取PR的diff、提交信息、相关代码文件。
  3. 任务分解：协调者分析变更，决定启动哪几个专项Agent，并将带有上下文信息的“审查任务单”分发给它们。这个过程可以是并行的，以提高效率。
  4. 专项审查：每个被调用的Agent独立工作。它们接收代码片段和上下文，调用底层的大模型API（我们支持OpenAI GPT、Claude、以及本地部署的开源模型如DeepSeek-Coder），结合自身专业的Prompt进行分析，并生成结构化的初步发现。
  5. 结果汇总：专项Agent将结果返回给协调者，或直接发送到消息队列。报告生成Agent消费这些结果。
  6. 生成与反馈：报告生成Agent整理出最终报告，通过评论的形式提交到PR页面，或者发送到团队的协作工具（如钉钉、飞书群）。

这个流程确保了审查的系统性和效率，也使得每个环节都可追溯、可调试。

3. 关键技术实现与选型要点

搭建这样一个系统，技术选型至关重要。它直接决定了系统的能力上限、成本和稳定性。

3.1 大模型选型：通用vs.代码专用

底层的大模型是Agent的“智力”源泉。我们对比了几类模型：

  • 通用大模型（如GPT-4, Claude-3）：优势是理解能力强、逻辑推理好、知识面广，在架构设计和业务逻辑审查上表现突出。缺点是专门针对代码的优化可能不如专用模型，且API调用成本较高。
  • 代码专用模型（如DeepSeek-Coder, CodeLlama, StarCoder）：在代码补全、语法理解、生成代码片段方面非常强悍，对多种编程语言支持深入。成本可能更低（尤其是开源可本地部署的）。但在复杂逻辑推理和跨领域知识结合上，有时略逊于顶级通用模型。

我们的策略是混合使用。对于“代码风格”、“静态分析”这类需要深度理解语法和常见模式的Agent，我们优先选用强大的代码专用模型，性价比高。对于“架构设计”、“安全漏洞”这类需要广泛知识和严谨推理的Agent，我们使用通用大模型。关键技巧在于，为不同类型的Agent精心设计不同的System Prompt和Few-shot示例，让它们在自己的赛道上发挥最佳水平。

3.2 Prompt工程：让Agent变得“专业”

Prompt是Agent的灵魂。一个糟糕的Prompt会让最强的模型也变成“人工智障”。我们的经验是，Prompt必须清晰、具体、结构化，并且要为模型提供充足的“思考框架”。

以“架构与设计模式Agent”的Prompt为例，一个差的Prompt可能是：“请审查下面这段代码的设计是否合理。”

而一个好的Prompt应该是这样的：

你是一个经验丰富的软件架构师，正在审查一个Java Spring Boot项目的代码变更。请遵循以下步骤进行分析： 1. **上下文理解**：本次变更涉及在`com.example.order.service`包下新增了一个`DiscountStrategy`接口及其两个实现类`PercentageDiscountStrategy`和`FixedAmountDiscountStrategy`。原有的`OrderService`类修改了`calculateTotal`方法，通过一个`StrategyFactory`来调用不同的折扣策略。 2. **审查重点**： a. **设计模式应用**：评估策略模式（Strategy Pattern）在此处应用是否恰当。是否满足了“在运行时选择算法”的需求？是否有过度设计的嫌疑？ b. **单一职责原则**：新的策略类是否职责清晰、单一？ c. **开闭原则**：如果未来需要增加一种新的折扣类型（如“会员等级折扣”），现有的设计是否易于扩展，而无需修改`OrderService`和`StrategyFactory`的核心逻辑？ d. **依赖关系**：检查`OrderService`、`StrategyFactory`、各`Strategy`实现类之间的依赖关系是否清晰、松耦合？ 3. **输出格式**：请按以下JSON格式输出你的审查结果，包括`issue_type`（可选：Design_Pattern, SOLID, Coupling等）、`severity`（HIGH, MEDIUM, LOW）、`location`（类名和方法名）、`description`（问题描述）、`suggestion`（具体的改进建议，可包含简化的代码示例）。

可以看到，好的Prompt定义了角色、提供了上下文、指明了具体的分析维度和步骤，并约束了输出格式。这极大地提高了模型输出的稳定性、相关性和可解析性。

3.3 上下文管理与长代码处理

代码审查往往需要看整个类、甚至多个关联文件。而大模型有上下文长度限制（Token数限制）。如何处理长代码是一个挑战。

我们的解决方案是“分层加载”和“智能切片”：

  1. 关键文件优先：协调者Agent会识别变更中的核心文件（如新增的类、修改行数最多的文件），优先将这些文件的完整内容提供给相关Agent。
  2. 关联上下文摘要：对于被修改方法所调用的其他类或方法，我们不直接传送全部代码，而是让一个轻量级的预处理Agent先为其生成一个简洁的“摘要”（例如：“UserRepository.findById方法，根据ID从数据库查询用户实体，可能返回null”），然后将摘要作为上下文提供。
  3. 分块审查与合并：对于特别长的单个文件，我们将其按类、按函数进行切分，分多次让模型审查，最后再由报告生成Agent汇总去重。这里需要注意维护好代码块之间的关联信息，避免模型丢失全局观。

3.4 工具链集成与自动化

Agent系统本身不是目的，让它融入开发生命周期才是价值所在。我们重点做了以下集成：

  • Git平台集成（GitHub/GitLab/Gitee）：通过Webhook实现自动触发。审查报告以PR评论的形式发布，支持@特定人员。我们还将问题标记为“必须解决”（阻塞）或“仅供参考”（建议），方便团队跟踪。
  • CI/CD流水线：将AI审查作为一个CI步骤。可以配置为：如果发现“高危”或“阻塞”级别的问题，则自动标记CI构建为失败，阻止代码合并。这为质量保障增加了一道智能关卡。
  • 团队知识库对接：让Agent能够读取团队内部的架构决策记录（ADR）、API设计规范、安全红线文档等，使它的审查建议更加“接地气”，符合团队特定要求。

4. 实操部署与配置指南

理论说了这么多，怎么把它跑起来？下面是一个基于开源框架（比如LangChain或自定义微服务）的简化部署思路。

4.1 环境准备与核心组件

假设我们使用Python作为胶水语言，Docker进行容器化部署。

1. 基础设施：

  • 服务器：一台或多台拥有GPU的服务器（如果使用本地开源大模型），或只需CPU的服务器（如果完全使用云端API）。建议内存不少于16GB。
  • 容器环境：Docker & Docker Compose。
  • 消息队列：RabbitMQ或Redis，用于Agent间的异步通信。
  • 存储：PostgreSQL或MongoDB，用于存储审查历史、团队配置。

2. 核心服务：

  • Orchestrator Service：接收Webhook，协调任务。可以用FastAPI或Spring Boot快速搭建。
  • Agent Pool：每个专项Agent可以是一个独立的Python服务（使用FastAPI），监听特定的消息队列主题。
  • LLM Gateway：一个统一的网关服务，负责管理对不同大模型API（OpenAI, Anthropic, 本地Ollama等）的调用，包括负载均衡、缓存、计费和降级策略。
  • Report Service：生成和发布报告的服务。

4.2 配置详解：以代码风格Agent为例

我们来看一个“代码风格与规范Agent”的配置文件可能长什么样。这决定了Agent的行为。

# config/style_agent_config.yaml agent: name: "code_style_agent" description: "检查代码风格和团队规范" triggered_by: ["java", "python", "javascript"] # 监听哪些语言的文件变更 llm_backend: "openai-gpt-4-turbo" # 使用的模型后端 # 也可以配置为本地模型： "local-deepseek-coder-33b" prompt_templates: system_prompt: | 你是一个严格的代码规范检查员。你的知识包括： 1. 通用编程规范：PEP 8 (Python), Google Java Style, Airbnb JavaScript Style。 2. 团队自定义规范（见下文`team_rules`部分）。 请仔细检查提供的代码，找出所有违反上述规范的地方。对于每个问题，必须提供具体的代码行号、违规描述、以及修改后的正确代码示例。 team_rules: | # 以下是“星辰科技”后端团队的Java开发规范（节选）： - Service层实现类必须放在`*.service.impl`包下，并以`ServiceImpl`结尾。 - 所有REST控制器（@RestController）的公共方法必须使用`@Operation`注解（来自swagger）描述接口。 - 不允许在业务逻辑中直接使用`System.out.println`进行日志记录，必须使用SLF4J的`Logger`。 - 数据库实体类字段命名必须使用小写蛇形命名法（snake_case），并与数据库表字段一致。 severity_mapping: # 违规级别映射 "命名不符合规范": "LOW" "缺少必要的注解": "MEDIUM" "使用了被禁止的API/方法": "HIGH" "日志记录不规范": "MEDIUM" output_schema: # 约束输出格式 type: "array" items: type: "object" properties: line: type: "integer" rule_violated: type: "string" severity: type: "string" enum: ["HIGH", "MEDIUM", "LOW"] description: type: "string" suggestion_code: type: "string"

这个配置文件使得Agent的行为高度可定制。当团队规范更新时，只需修改team_rules部分并重启Agent，无需改动核心代码。

4.3 运行与调试流程

部署完成后，一个典型的工作流如下：

  1. 启动：docker-compose up -d启动所有服务。
  2. 配置Git仓库：在GitLab上配置Webhook，指向你的Orchestrator Service的URL。
  3. 提交测试：创建一个带有故意错误的PR（例如，一个Java类命名不符合规范，一个方法可能产生空指针）。
  4. 观察日志：查看各个服务的日志，了解任务分发、模型调用、结果汇总的过程。
  5. 审查报告：在PR页面上，你应该能看到AI Agent提交的详细评论，指出问题并给出建议。
  6. 迭代优化：如果发现Agent误报（将正确的代码判为错误）或漏报（没发现真正的问题），你需要分析原因。是Prompt不够精确？是上下文信息不足？还是模型本身能力有限？根据分析结果，去调整对应Agent的Prompt或配置。

注意：在初期，误报率可能会比较高。一个重要的实践是，不要追求100%的准确率起步，而是追求100%的可解释性和可改进性。确保每一个审查意见你都能理解AI为什么这么想，这样才能有针对性地优化它。

5. 效果评估、局限性与未来演进

上线运行一段时间后，我们需要客观地看待它的效果和不足。

5.1 效果评估维度

我们主要从以下几个维度评估系统：

  • 问题检出率：对比AI审查和资深工程师人工审查，AI能发现多少比例的真实问题？我们统计了“检出率”（AI发现的真问题/所有真问题）和“误报率”（AI认为是问题但实际不是的比例）。初期目标是将高危问题的检出率提升到80%以上，误报率控制在30%以下。
  • 效率提升：AI审查平均为每次PR节省了多少人工Review时间？我们统计了从PR创建到收到第一条人工评论的平均时间，这个时间因为AI的先期评论而显著缩短。
  • 知识传承：对于团队新人，AI的审查意见是否起到了“即时培训”的作用？我们通过调研发现，新人普遍认为AI的详细解释和代码示例对他们快速掌握团队规范非常有帮助。
  • 开发者接受度：开发者是否愿意采纳AI的建议？我们跟踪了AI建议的“采纳率”。通过不断优化建议的准确性和表述方式（从“你错了”改为“这里有一个常见的优化模式…”），采纳率逐步提升。

5.2 当前面临的挑战与局限性

尽管效果显著，但我们必须清醒认识到局限性：

  • “幻觉”问题：大模型偶尔会“无中生有”，指出一个根本不存在的“问题”，或者引用一个不存在的API。这需要通过更严格的输出格式校验、以及让Agent在“不确定”时明确标注“低置信度”来缓解。
  • 上下文理解局限：AI对业务领域的深层逻辑、历史遗留代码的“特殊原因”缺乏理解。它可能建议一个更优雅的设计，但忽略了与老旧系统兼容的历史包袱。因此，AI审查绝不能替代人工审查的最后把关，尤其是涉及复杂业务逻辑的部分。
  • 成本与性能：频繁调用高性能大模型API成本不菲。审查大量代码或团队多人频繁提交时，需要设计缓存策略（对相似代码片段缓存审查结果）、排队机制，并考虑在非关键路径上使用更经济的模型。
  • 配置与维护成本：维护一套有效的Prompt、规则和Agent协调逻辑，本身需要投入。它成了一个需要持续“训练”和调优的AI产品。

5.3 迭代方向与未来展望

基于现有实践，我们认为有几个方向值得深入：

  • 个性化与学习：让Agent能够从历史数据中学习。当开发者多次拒绝某一类AI建议，并附上理由时，系统可以学习并调整未来类似场景下的审查策略，甚至为不同开发者提供不同严格程度的审查。
  • 自动化修复：从“指出问题”到“自动修复”。对于一些简单的、模式固定的问题（如代码格式、重命名），可以让Agent在获得授权后，直接创建修复提交（Fix-up Commit）。这需要极高的准确率作为前提。
  • 多模态审查：不仅审查代码，还能审查与此次变更相关的文档更新、数据库迁移脚本、甚至API测试用例是否同步更新，实现更立体的变更质量评估。
  • 深度集成IDE：将轻量级的Agent能力前置到开发者的IDE中，在编码时实时提供建议，实现“左移”的质量保障，将问题消灭在提交之前。

这个AI Code Review Agent项目，对我们团队来说，已经从一个实验性的想法，变成了日常开发流程中不可或缺的一环。它没有取代我们的工程师，而是成为了一个不知疲倦、知识渊博的初级助手，承担了大量重复性的、规则性的检查工作，让人类工程师能更专注于创造性的设计和复杂的逻辑判断。构建它的过程，也是我们不断深入理解AI能力边界、学习如何将AI有效落地的过程。如果你也在为代码审查的效率和质量发愁，不妨从一个小团队、一个简单的专项Agent开始尝试，这条路上踩过的坑和收获的惊喜，远比想象中要多。

编程学习 学习日记 实战经验
← 返回列表