多智能体不是凑热闹而是“代码审查”这个任务本身太复杂单靠一个大模型提示词很难覆盖全部职责。Uber 对外介绍 uReview 时核心思路就是把代码审查拆成多个专家智能体让每个智能体只负责一个维度再由编排层汇总成最终审查报告。这篇文章不打算重复分享视频里的每一句话而是把这类多智能体代码审查引擎的架构设计拆开讲清楚为什么要用多智能体、智能体之间怎么协作、上下文怎么传递、批量 PR 怎么接入、自建一套最小版本需要什么代码。对正在做研发效能工具、想给团队引入 AI 代码审查、或者想深入了解多智能体系统落地方式的人来说这篇文章可以直接配合项目代码看。第 5 节给了一套精简版 Python 实现思路第 6 节给了 API 和批量任务设计第 8 节归纳了最常见的坑点。先讲能不能落地再讲怎么落地。1. 核心能力速览从现有材料看uReview 不是一个简单的 CI 插件而是一个面向代码审查场景设计的多智能体引擎。下面按“系统设计 工程经验”两个层面做一个能力速览。能力项说明项目类型多智能体代码审查引擎面向研发流程中的 Pull Request / Merge Request 审查场景架构风格编排层 专家智能体层 聚合层属于多智能体系统中的层级协作模式核心功能自动理解变更、拆分子任务、多维度并行审查、聚合生成结构化审查意见审查维度变更摘要、代码风格、逻辑正确性、性能风险、安全漏洞、测试覆盖等智能体协作方式多个专家智能体各自负责单一维度通过聚合器统一输出与普通工具区别传统静态扫描按规则匹配单模型审查缺乏分工边界uReview 用多智能体分工处理支持接入方式可对接代码平台 Webhook、API 服务、批量任务队列批量任务支持多个 PR/MR 排队审查需要控制并发避免 API 超限硬件门槛依赖云端 LLM API 或私有化模型服务不需要本地高显存推理设备适用场景研发效能团队、AI 应用工程师、需要把 LLM 嵌入代码评审流程的团队这里需要说明一点如果只看“代码审查”四个字很多人第一反应是直接用 GPT 或 Claude 把 diff 粘贴进去让它提意见。uReview 的多智能体设计思路不同它先把审查任务拆成若干个子任务每个子任务由独立智能体完成最后再做聚合。这个设计带来的直接好处是单个智能体的上下文更聚焦输出更稳定后续新增审查维度不需要改动整体流程只要新增一个智能体。2. 为什么代码审查要用多智能体架构代码审查和普通问答最大的区别在于“责任面”非常宽。一次代码审查既要看功能逻辑对不对又要看风格是否统一、有没有明显的性能问题、有没有安全风险、测试有没有覆盖到关键路径。这些问题需要的背景知识差异很大如果全部塞给同一个模型提示词会变得非常长模型容易顾此失彼而且某次调整可能影响所有维度。多智能体架构解决的是职责切分问题。每个专家智能体只拿到它需要的那部分上下文例如安全智能体只需要变更代码和项目依赖信息测试智能体只需要变更代码和测试文件。职责越细提示词越短输出越稳定。更重要的是多智能体架构天然支持并行执行。一次 PR 审查可以同时发起安全扫描、性能检查、风格检查整体耗时取决于最慢的智能体而不是所有任务相加。从工程角度看单模型审查还有一个维护性问题。团队对审查维度的要求会变化今天想看安全明天想看 SQL 性能如果用单模型提示词控制提示词会越来越复杂很难定位是哪个要求导致输出变差。多智能体把每个维度独立成模块新增一个审查维度就是新增一个智能体原有智能体不受影响。这一点在长期迭代中价值很大。另外要注意这里说的多智能体并不是指“多个模型通过强化学习互相博弈”。当前多数代码审查场景仍然是 LLM 提示词编排和工程调度多智能体强化学习更多是学术方向。uReview 这类系统更接近“多智能体系统核心架构与运行原理”里讲到的分层协作一个协调者负责调度多个执行者负责具体子任务一个聚合者负责结果合并。这个结构简单、可控、容易加日志追踪。3. 多智能体系统核心架构与运行原理要理解 uReview 的架构先看多智能体系统里三种常见协作模式。第一种是管道Pipeline模式智能体 A 的输出作为智能体 B 的输入适合有强先后依赖的任务。代码审查里先让“变更理解智能体”输出变更摘要再把摘要交给后续专家智能体就属于这种模式。第二种是层级Hierarchy模式一个编排智能体负责任务分发和结果汇总下面挂多个专家智能体这是当前代码审查工具最常用的结构。第三种是图Graph模式任务可以分支、合并、循环适合流程不固定的场景但实现复杂度更高。uReview 整体的运行原理可以抽象成四个阶段第一阶段是接入与解析。代码平台收到新的 PR 事件后通过 Webhook 通知审查服务服务拉取变更数据整理成统一的变更表示包括文件列表、diff、关联的 issue、PR 描述、测试结果等。第二阶段是任务分发。编排智能体根据变更规模、文件类型、涉及模块决定需要启动哪些专家智能体以及每个智能体需要哪些上下文。第三阶段是专家审查。各专家智能体并行处理自己的子任务输出结构化审查意见。第四阶段是聚合与回写。聚合智能体收集所有意见去重、分类、标记严重程度再回写到代码平台成为 PR 评论。在设计文档里可以给每个智能体定义清晰的输入输出接口。实际上多智能体系统的难点往往不在模型本身而在于上下文管理和结果合并。比如同一个文件同时被性能和风格两个智能体提出意见聚合层需要决定是合并展示还是分开展示这属于结果层面的冲突消解可以通过定义输出结构来解决。为了让整个系统可观测每个智能体执行时都应该记录输入摘要、输出结果、模型耗时和 token 消耗。这样当某个审查维度质量下降时可以直接回看数据定位问题而不是把整套提示词重新调一遍。这也是 uReview 这类引擎相对“单 prompt 脚本”更工程化的原因。4. uReview 审查任务拆解与工作流设计代码审查任务拆成多个子任务是整个多智能体设计的核心。参考已有代码审查工具的经验至少可以从下面几个维度拆变更理解这个 PR 改了什么影响哪些模块有没有破坏对外接口。静态检查增强编译错误、明显未定义变量、死代码等这类任务模型可以和 linter 输出结合。代码风格与一致性是否遵循项目风格规范命名是否统一是否引入不必要的依赖。逻辑正确性条件判断是否合理边界条件是否处理并发场景是否有竞态。性能风险循环内是否有重复查询是否有明显可以被缓存的计算大对象是否过早创建。安全风险输入校验、注入、硬编码密钥、越权操作等。测试覆盖新增代码是否有对应测试关键路径是否被覆盖。接口和兼容性改动是否影响调用方是否需要同步更新文档。实际项目中不需要一次启用全部维度。更好的做法是配置化。系统里维护一张智能体注册表每个智能体包含名称、能力描述、适用的文件类型、提示词模板、是否需要额外上下文。编排层收到 PR 后根据配置决定启用哪些专家智能体。工作流设计上我建议按照“先理解、再聚焦、后交付”的顺序。先跑变更理解智能体生成结构化的变更摘要然后各专家智能体并行执行最后聚合层基于变更摘要和所有专家结果生成最终报告。顺序可以用配置表达比如支持串行、并行和按条件触发。# 工作流配置示例 review_workflow { stages: [ {agent: change_understanding, mode: serial, next: [logic, security, style]}, {agent: logic, mode: parallel, next: [aggregator]}, {agent: security, mode: parallel, next: [aggregator]}, {agent: style, mode: parallel, next: [aggregator]}, {agent: aggregator, mode: serial, next: []} ] }这里要注意一点并行执行专家智能体时不能让每个智能体都携带完整仓库的代码否则 token 成本会成倍上涨。更合理的做法是给每个智能体配置“上下文裁剪规则”例如安全智能体只关心变更代码、依赖文件、请求入口文件风格智能体只需要变更文件和项目风格配置文件。上下文裁剪直接影响成本和输出质量是多智能体代码审查系统最重要的调优点。5. 程序化脚手架实现一个精简版 uReview下面给出一套可以直接运行的最小化多智能体代码审查实现思路代码结构参考了层级协作模式包含基础智能体接口、专家智能体、编排器和聚合器。实际使用时要根据项目使用的 LLM SDK 调整请求方式。先定义基础智能体接口# agents/base.py from abc import ABC, abstractmethod from typing import Any, Dict class ReviewAgent(ABC): 所有审查智能体的基类统一输入输出格式。 def __init__(self, name: str, model: str): self.name name self.model model abstractmethod def build_prompt(self, context: Dict[str, Any]) - str: 根据裁剪后的上下文构造提示词。 abstractmethod def parse_response(self, response: str) - Dict[str, Any]: 解析模型输出为结构化审查意见。 def run(self, context: Dict[str, Any]) - Dict[str, Any]: 执行审查并返回结构化结果。 prompt self.build_prompt(context) # 这里假设 llm.call 是一个统一的模型调用封装 response llm.call(self.model, prompt) return self.parse_response(response)再实现一个具体的专家智能体以安全和风格为例。安全智能体关注硬编码密钥、注入风险、越权操作风格智能体关注命名和代码格式。# agents/security_agent.py import json from agents.base import ReviewAgent from typing import Any, Dict class SecurityAgent(ReviewAgent): 安全审查智能体只接收变更代码和依赖信息。 def build_prompt(self, context: Dict[str, Any]) - str: return f 你是一个代码安全审查专家。请基于下面的变更代码和依赖信息识别潜在安全风险。 要求 1. 重点关注注入、硬编码密钥、越权、路径遍历问题。 2. 只报告确定存在或高度可疑的问题不要泛泛而谈。 3. 每个问题必须标注文件、行号和风险等级。 变更代码 {context[diff]} 依赖信息 {context.get(dependencies, 无)} def parse_response(self, response: str) - Dict[str, Any]: # 实际开发中建议要求模型输出 JSON 格式 try: return json.loads(response) except json.JSONDecodeError: return {raw: response, issues: []}核心是编排器。编排器负责接收 PR 上下文启用哪些专家智能体并行执行最后交给聚合器。# orchestrator.py from concurrent.futures import ThreadPoolExecutor, as_completed class ReviewOrchestrator: def __init__(self, agents: dict, aggregator): self.agents agents self.aggregator aggregator def run_review(self, pr_context: dict) - dict: 按配置执行多智能体审查。 results {} # 第一阶段串行运行变更理解智能体 if change_understanding in self.agents: context self.agents[change_understanding].run(pr_context) results[change_understanding] context # 第二阶段并行运行其他专家智能体 parallel_agents [ name for name, agent in self.agents.items() if name ! change_understanding and name ! aggregator ] with ThreadPoolExecutor(max_workerslen(parallel_agents)) as executor: future_map { executor.submit(self.agents[name].run, pr_context): name for name in parallel_agents } for future in as_completed(future_map): name future_map[future] results[name] future.result() # 第三阶段聚合 final_report self.aggregator.run(results) return final_report聚合器的作用不只是拼接。它会按严重程度排序、去掉重复项、把同类问题合并最终输出一条 PR 评论所需的结构化数据。# aggregator.py import json class ReportAggregator: 把多个专家智能体结果合并成结构化报告。 SEVERITY_ORDER {critical: 0, warning: 1, suggestion: 2} def run(self, results: dict) - dict: merged_issues [] for agent_name, result in results.items(): issues result.get(issues, []) for issue in issues: issue[agent] agent_name merged_issues.append(issue) merged_issues.sort(keylambda x: self.SEVERITY_ORDER.get(x.get(severity, suggestion), 2)) return { summary: f本次审查覆盖 {len(results)} 个维度发现 {len(merged_issues)} 个问题。, issues: merged_issues }这个脚手架省略了模型调用细节和上下文裁剪逻辑但已经具备多智能体审查的基本骨架。实际接入时最优先做两件事一是把每个智能体的输入输出格式定义清楚特别是让模型输出结构化 JSON二是把所有智能体的运行日志和 token 消耗记录下来这是后续调优的基础。6. 接口 API 与批量任务设计代码审查引擎要真正进入研发流程必须提供接口服务而不是只在本地脚本里运行。uReview 这类系统通常需要对外暴露两类接口一类是接收代码平台 Webhook 的入口另一类是提供给内部平台或工程师手动触发审查的 API。先看手动触发接口。一个最小可用的审查请求接口可以这样设计curl -X POST http://127.0.0.1:8080/api/v1/review \ -H Content-Type: application/json \ -d { repo: your-org/your-repo, pr_number: 42, trigger: manual, agents: [security, style, performance] }服务端收到请求后先做鉴权和参数校验再把任务丢进队列异步执行。这里有一个重要原则审查任务不要做成同步接口因为一次完整的 PR 审查可能要调用多个模型耗时几十秒到几分钟同步接口很容易超时。更好的做法是提交任务后立即返回任务 ID审查完成后回调结果或由前端轮询。Python 里可以用简单的队列加后台线程模拟任务队列# api.py import uuid from queue import Queue from threading import Thread from orchestrator import ReviewOrchestrator review_queue Queue() task_status {} def submit_review(review_request: dict) - str: task_id str(uuid.uuid4()) task_status[task_id] {status: pending, result: None} review_queue.put((task_id, review_request)) return task_id def worker(): while True: task_id, review_request review_queue.get() task_status[task_id][status] running try: result orchestrator.run_review(review_request) task_status[task_id][result] result task_status[task_id][status] done except Exception as exc: task_status[task_id][status] failed task_status[task_id][error] str(exc) finally: review_queue.task_done() Thread(targetworker, daemonTrue).start()批量任务方面重点是控制并发。如果团队一天有几十上百个 PR每个 PR 的审查又会触发多个模型调用直接全量并发跑会导致 LLM API 限流甚至拖垮内网服务。建议做成“全局并发限制 单仓库排队”的方式同一时间最多运行 N 个 PR 审查任务同一个仓库的任务排在同一个队列里避免同一个仓库的多个 PR 同时拉取大量代码。任务失败重试也要设计。多智能体审查中最常见的失败原因是模型 API 返回格式不符合预期比如安全智能体要求 JSON 输出但模型返回了普通文本。这种情况下不应该直接把整个任务标记失败而是让编排器对单个智能体做一次重试。重试时会带上上一次的原始输出提示词里追加“严格按照 JSON 格式输出”。超过重试次数后聚合器仍可以基于其他智能体的结果生成部分报告。回调建议统一走代码平台评论接口比如 GitHub 的 review comment API 或内部代码平台的 webhook。审查结果里必须包含智能体名称和严重程度方便开发者在 PR 页面上按严重程度筛选。如果某个智能体失败也需要在最终报告里明确标注避免开发者误以为“未发现问题就是没问题”。7. 资源成本、运行效率与性能观察多智能体代码审查真正要面对的瓶颈是 token 成本和时延。一次 PR 审查会发起多次模型请求每个智能体消耗的 token 取决于上下文裁剪质量。观察成本和性能最基础的方法是给每次调用打点至少记录三项数据输入 token、输出 token、单次调用耗时。从工程经验看几个最容易造成成本失控的地方需要优先处理。第一是重复拉取全量代码。多个智能体公共依赖“变更代码”时如果每个智能体自己拉一遍全量仓库 contenttoken 会迅速膨胀。更合理的做法是在编排层统一拉取一次 diff经过裁剪后以结构化的方式传给各专家智能体避免重复读取。代码示例里pr_context就是承担这个角色的公共数据对象。第二是模型选择。不同审查维度对模型能力要求不同风格检查可以用小模型安全审查需要相对更强的模型。系统里应当支持按智能体配置模型名而不是所有智能体都用同一个最强模型。例如风格智能体用轻量模型变更理解和安全智能体用能力更强的模型这样能在质量和成本之间取得平衡。第三是缓存。同一个 PR 被重复触发审查的情况很常见比如 push 后触发一次全量审查单文件重新 push 又触发一次。可以对 diff hash 做缓存如果某个文件的变更内容没有变化就不重新跑对应的专家审查只加载之前的缓存结果。这个优化对成本影响最明显。运行效率方面并行度并不是越大越好。专家智能体并行执行时大部分耗时被最慢的智能体决定但过高的并发会导致模型 API 限流和日志链路混乱。建议先从 3 到 5 个智能体并行开始观察 API 限流频率再逐步加大。显存相关的参数在这里反而不是重点因为大多数团队会把模型部署为独立服务或直接使用云 API审查引擎本身是无状态服务只需要普通 CPU 资源和足够的内存处理代码数据。如果是全私有化部署则要按模型服务单独规划 GPU。稳妥的判断是先让容器在 4 核 8G 内存环境下跑通再根据并发量扩容。8. 常见问题与排查方法多智能体审查系统涉及代码平台、模型服务、任务队列、聚合逻辑多个环节故障定位比单模型脚本复杂。下面按实际排查顺序列出常见问题。问题现象可能原因排查方式解决方案收到 Webhook 但没有触发审查网络不同 / 密钥校验失败 / 路由配置错误查看服务日志和代码平台投递记录检查密钥和回调地址先 curl 手动调用接口验证部分智能体没有返回结果上下文裁剪后内容为空 / 模型拒绝回答查看单智能体运行日志检查裁剪规则和提示词确认有实际代码输入审查结果大量重复意见多个智能体覆盖同一个维度统计聚合前后 issue 数量在注册表中明确各智能体职责边界聚合层增加去重逻辑模型输出不是合法 JSON提示词要求不严格 / 模型能力不足查看原始响应追加“只输出 JSON”约束增加一次解析重试任务队列堆积严重并发设置过高被限流 / 模型响应慢观察队列长度和 API 限流错误降低全局并发增加单仓库排队提升模型超时时间审查报告时延太长并行度不足 / 串行阶段任务过重查看各智能体耗时统计把无依赖智能体改为并行裁剪过长输入API 调用偶发失败流式响应断开 / 网络波动查看异常栈和重试次数增加指数退避重试失败智能体单独标注回写评论被代码平台拒绝权限不足 / 评论内容超长查看回写接口错误把评论按严重程度分段写入检查平台权限结果质量不稳定上下文不一致 / 缓存命中错误对比同 diff 多次输出固定上下文裁剪规则清掉按仓库路径缓存的错误数据排查时建议遵循“先链路后提示词”的原则。某个智能体输出异常先确认输入上下文是否正确再调提示词不要一上来就重写 prompt。记录每轮调用的输入摘要和输出摘要排查效率会高很多。还有一类问题来自代码平台的特殊场景。比如超大 PR 一次性修改了几百个文件直接把全量 diff 作为上下文会让所有智能体超限。处理方式是设置文件上限超限只审查高风险的目录或提交片段并在最终报告里明确说明覆盖范围。这个策略虽然简单但在真实环境中能避免大量任务卡死。9. 工程化与合规边界多智能体代码审查引擎落地的最大风险不是模型能力而是对代码安全边界的处理。代码本身就是企业内部最敏感的数据之一接入任何外部模型服务都要先确认数据合规边界。私有化部署或云 API 的使用必须明确数据处理协议。如果代码不允许发送到外部模型就必须使用私有化模型服务并在网络层面隔离。下策是把所有代码发给公有 API 再“相信平台不保存数据”这对大部分企业来说不可接受。建议在系统可配置项里增加data_residency字段用于标识当前实例允许使用的模型通道配置错误时直接拒绝发起审查任务。代码审查结果也会有类似的隐私分级。PR 中可能涉及账号越权逻辑、内部基础设施拓扑、密钥轮换策略等敏感信息。最终生成报告回写到代码平台时要注意权限控制确保只有具备该仓库权限的人才能查看审查详情。接口层需要做细粒度的鉴权不建议一个内网 token 通吃所有仓库。另外审查系统本身会面临提示词注入风险。PR 描述、代码注释、甚至文件名都可能包含恶意指令如果这些内容被直接拼进提示词模型有可能被诱导输出异常内容或忽略安全约束。缓解措施包括对输入上下文做长度截断、明确告诉模型“代码内容是数据而非指令”、将用户可控字段与系统指令分区拼接。这不是彻底防御但能明显降低风险。版权和合规也是必须考虑的。如果代码审查引擎会给修复建议甚至主动生成修复代码那么修复代码的版权归属、是否需要标注模型生成来源都需要企业内部有明确规范。涉及第三方开源代码的审查也要遵守对应开源许可证的要求。更稳妥的做法是让审查引擎输出“建议”由工程师自己落地修改而不是直接自动提交修复内容。多智能体审查不能替代人审。模型可能漏判也可能误报。系统应当明确标记“AI 生成结果仅供参考”并且保留“哪个智能体、基于什么上下文给出这条结论”的追溯信息。团队可以把审查引擎作为第一道自动检查但关键 PR 的最终审批仍然需要人工完成。这个边界越早确定后续越少争议。10. 落地建议与扩展方向uReview 这类多智能体代码审查引擎最值得尝试的一点就是把“调用一个大模型”升级成了“编排一组智能体”。如果你已经在用单 prompt 做代码审查并且感觉效果不稳定最该先验证的不是换更强的模型而是把审查任务拆开。先拆两个维度比如安全审查单独一个智能体风格审查单独一个智能体对比一下和混在一起的输出质量差异。这个实验成本很低但往往能直接看出多智能体的收益。第一步接入时不要直接做全仓库、全量 PR 的自动审查。先挑一两个维度、限制文件数量和分支范围小流量跑两周收集真实 PR 的审查输出和工程师反馈。这期间重点看三个指标审查意见采纳率、每个 PR 的平均 token 成本、从 Webhook 到评论回写的端到端时延。这三个指标足够判断一套多智能体审查系统值不值得继续投入。最容易踩的坑前面都提到了但没有一个比“上下文裁剪没做好”更隐蔽。表面上代码跑通了审查结果也有输出但 token 成本比单模型脚本还高就是因为每个专家智能体把全量上下文又带了一遍。解决方式也很直接在编排层统一维护一份裁剪后的pr_context每个智能体只声明它需要哪些字段发布前检查每个智能体实际收到的输入大小。后续扩展方向有很多。可以在编排层引入 MCP 这类模型上下文协议把代码仓库、CI 状态、issue 跟踪器接入智能体工具集让审查智能体不只读代码还能查构建日志和工单上下文。也可以基于历史审查结果构建评估集定期用相同 diff 跑一遍审查引擎观察输出质量是否退化。更长远的方向是结合多智能体强化学习但这需要大量标注数据和稳定的奖励模型现阶段更适合作为研究课题而不是第一阶段的工程目标。多智能体代码审查不是一个花哨概念它能直接解决研发流程里的具体痛点。先从最小的两个智能体开始跑你会比背任何架构图都更快理解它为什么有用。