代码审查 Agent 实战

概述

AST 静态分析与 Diff 解析算法的自动化审查

代码审查 Agent 的核心能力在于结构化理解代码：与纯文本分析不同，代码具有严格的语法结构，同样的逻辑问题可能以完全不同的文本形式出现。因此，基于 AST（抽象语法树）的静态分析是代码审查 Agent 的重要补充。

AST 将代码解析为树状结构，每个节点代表一个语法元素（如函数定义、变量赋值、条件判断）。通过遍历 AST，审查 Agent 可以：

1. 识别代码异味（Code Smells）：如过长的函数、过深的嵌套、未使用的变量等。
2. 检测安全风险：如 SQL 注入（字符串拼接进 SQL 语句）、命令注入（用户输入进入 os.system）、不安全的反序列化等。
3. 分析依赖关系：识别循环依赖、未声明的依赖、以及已知有漏洞的第三方库。
4. 度量复杂度：计算圈复杂度（Cyclomatic Complexity）、认知复杂度等指标，标记需要重构的模块。

Diff 解析则是另一个关键技术。当审查 Pull Request 时，Agent 需要理解"改了什么"而非"整个文件是什么样的"。Diff 格式（Unified Diff）记录了文件的增删改操作，审查 Agent 可以基于 Diff 进行增量分析，只审查变更的部分及其直接影响范围。

从工程实践来看，纯 LLM 的代码审查容易产生伪阳性（报告不存在的问题）和伪阴性（遗漏真正的问题）。将 LLM 与专用静态分析工具（如 pylint、bandit、mypy）结合，可以显著提升审查的准确性：静态分析工具负责找出明确的规则违反，LLM 负责评估设计模式、命名规范和架构层面的问题。

使用 Sandbox Agent 实现自动化的代码审查、Bug 修复和单元测试生成。

正文

相关阅读

• OpenAI Agents SDK 快速上手
• SDK 核心概念一览

参考文档

• OpenAI Agents SDK 官方文档
• GitHub 仓库

完整实战示例：自动化代码审查流水线

以下示例展示了如何在生产环境中构建一个结合 AST 分析、规则引擎和 LLM 评估的自动化代码审查系统：

import asyncio
import ast
import re
from dataclasses import dataclass
from typing import Any
from agents import Agent, Runner, function_tool


@dataclass
class CodeIssue:
    severity: str  # critical, warning, info
    category: str
    message: str
    line: int
    suggestion: str


class StaticAnalyzer:
    """基于 AST 的静态分析器。"""

    def analyze(self, code: str, filename: str = "test.py") -> list[CodeIssue]:
        issues = []
        try:
            tree = ast.parse(code)
        except SyntaxError as e:
            return [CodeIssue("critical", "syntax", f"Syntax error: {e}", e.lineno or 1, "Fix syntax before further review")]

        for node in ast.walk(tree):
            if isinstance(node, ast.FunctionDef):
                # 检查函数长度
                lines = node.end_lineno - node.lineno if node.end_lineno else 1
                if lines > 50:
                    issues.append(CodeIssue("warning", "complexity", f"Function '{node.name}' is {lines} lines long", node.lineno, "Consider refactoring into smaller functions"))

            if isinstance(node, ast.Call):
                # 检查危险函数调用
                if isinstance(node.func, ast.Name) and node.func.id in ("eval", "exec"):
                    issues.append(CodeIssue("critical", "security", f"Dangerous function '{node.func.id}' used", node.lineno, "Avoid eval/exec; use ast.literal_eval for safe parsing"))

            if isinstance(node, ast.For):
                # 检查嵌套循环
                nested = any(isinstance(child, (ast.For, ast.While)) for child in ast.walk(node) if child != node)
                if nested:
                    issues.append(CodeIssue("warning", "performance", "Nested loop detected", node.lineno, "Consider optimizing with set operations or vectorization"))

        return issues


class CodeReviewAgent:
    """代码审查 Agent，结合静态分析和 LLM 评估。"""

    def __init__(self):
        self.analyzer = StaticAnalyzer()

    def _build_prompt(self, code: str, filename: str, static_issues: list[CodeIssue]) -> str:
        issues_text = "\n".join(f"- [{i.severity}] Line {i.line}: {i.message}" for i in static_issues) if static_issues else "No static issues found."

        return f"""
请对以下代码进行审查。静态分析器已发现以下问题：
{issues_text}

请额外关注：
1. 命名规范（PEP 8）
2. 类型注解完整性
3. 错误处理健壮性
4. 文档字符串质量
5. 是否有更 Pythonic 的实现方式

文件: {filename}
"""
```python
{code}

请以 JSON 格式输出审查结果：
{ {"summary": "总体评价", "issues": [{ {"severity": "…", "line": N, "message": "…", "suggestion": "…"}}]}}
""".strip()

async def review(self, code: str, filename: str = "review.py") -> dict:
    # 1. 静态分析
    static_issues = self.analyzer.analyze(code, filename)

    # 2. LLM 审查
    agent = Agent(
        name="CodeReviewer",
        instructions="You are a senior Python engineer conducting code reviews. Be thorough but constructive.",
        model="gpt-5-nano"

代码审查 Agent 的流水线架构

下图展示了自动化代码审查的完整流水线：

flowchart TD
    PR[Pull Request] --> D[Diff 解析]
    D --> S[静态分析 AST/pylint/bandit]
    S --> L[LLM 审查]
    L --> M[结果合并与去重]
    M --> G[Guardrails 检查]
    G --> F[格式化输出]
    F --> C[评论发布到 PR]
    S -->|严重问题| E[立即阻断合并]
    G -->|敏感内容| R[内容重写]
    R --> F
    style S fill:#c5e0b4,stroke:#5a4a3a
    style L fill:#e8d5b5,stroke:#5a4a3a
    style E fill:#f4b183,stroke:#5a4a3a

流水线的每个阶段都可以独立优化。静态分析负责找出明确的规则违反，LLM 负责评估设计层面的问题，两者互补而非替代。

代码审查 Agent 的精准度提升策略

代码审查 Agent 面临的根本挑战是伪阳性率——报告了大量实际上不是问题的问题，导致开发者对 Agent 的建议产生免疫。

分层审查策略：

将审查分为三个层次，每层关注不同维度：

1. L1 - 安全与正确性（必须修复）：空指针、SQL 注入、资源泄漏、并发问题
2. L2 - 规范与质量（建议修复）：命名不规范、缺少文档、复杂度过高
3. L3 - 优化与建议（可选参考）：性能优化建议、更 Pythonic 的写法

只有 L1 的问题会阻断合并，L2 和 L3 仅作为评论建议。这种分层降低了开发者的认知负担，也提升了 Agent 建议的采纳率。

团队规范适配：

不同团队有不同的编码规范（如行长度限制、引号风格、类型注解要求）。代码审查 Agent 应该读取项目根目录的 .review-config.yaml 文件，加载团队特定的规则：

rules:
  line_length:
    max: 120
  type_hints:
    required: true
  docstrings:
    style: google
  ignore_patterns:
    - "tests/"
    - "migrations/"

增量审查优化：

对于大型 PR，只审查变更的代码及其直接上下文（±10 行）。这不仅降低了 Token 消耗，也避免了审查与本次变更无关的旧代码。

def get_review_scope(diff: Diff) -> list[CodeRange]:
    scopes = []
    for file in diff.changed_files:
        for hunk in file.hunks:
            start = max(0, hunk.new_start - 10)
            end = hunk.new_start + hunk.new_lines + 10
            scopes.append(CodeRange(file.path, start, end))
    return scopes

代码审查 Agent 的最终目标是成为值得信赖的虚拟同事——它的建议应该像资深工程师的 Code Review 一样有洞察力、有建设性、并且尊重开发者的时间。实现这一目标需要持续收集开发者反馈，迭代优化审查标准和输出格式。代码审查的规则引擎与扩展方面，静态规则（如函数不能超过 50 行）容易维护但灵活性不足。更强大的方案是规则引擎，通过可扩展的规则函数实现定制化审查。规则引擎的优势在于可扩展性，团队可以根据项目特点自定义规则，甚至从代码审查历史中自动学习规则。代码审查 Agent 的审查意见应具有可操作性。每条意见都应包含：问题描述、影响范围、修复建议和严重程度，帮助开发者快速定位和解决问题。

常见问题与调试

问题一：AST 解析失败导致审查中断

如果代码包含语法错误或不兼容的 Python 版本特性，ast.parse 会抛出异常。解决方案：

1. 在解析前进行语法预检，对语法错误的代码提前返回明确的错误信息。
2. 指定目标 Python 版本（如 ast.parse(code, mode='exec', type_comments=True)）。
3. 对于包含类型注释的代码，确保使用与代码版本匹配的 AST 解析策略。

问题二：LLM 审查产生大量伪阳性

模型可能对风格偏好过于敏感，报告大量低价值的"建议"。缓解措施：

1. 在 prompt 中明确优先级：要求模型只报告"影响代码正确性、性能或安全"的问题。
2. 对 LLM 发现的问题进行二次过滤：与静态分析结果合并，如果静态分析未发现同类问题，降低其优先级。
3. 收集开发团队的反馈，持续优化 prompt 和审查标准。

问题三：大型代码文件的审查延迟过高

当 PR 包含数千行变更时，一次性送入 LLM 会导致 token 费用激增和延迟飙升。优化建议：

1. 按文件或按函数拆分审查任务，并行处理。
2. 对大型文件先进行摘要分析（如变更了哪些模块、增加了哪些依赖），只将关键部分送入详细审查。
3. 实现增量审查：只审查变更的代码及其直接上下文（±10 行），而非整个文件。

与其他方案对比

维度	Agents SDK 代码审查	GitHub Copilot	SonarQube
审查深度	语义+设计	实时建议	规则驱动
集成方式	CI/CD 或 IDE	IDE 实时	CI/CD 后
定制化	极高	中	高（规则配置）
安全检测	需自建	基础	专业（SAST）

GitHub Copilot 在开发阶段的实时建议方面无与伦比，但它主要用于代码补全而非系统性审查。SonarQube 是企业级代码质量平台，提供了数千条规则和详细的度量报告，但在设计模式和架构层面的审查能力有限。Agents SDK 的代码审查 Agent 提供了最大的灵活性：你可以将 AST 分析、自定义规则、LLM 评估和团队特定的审查清单整合到一个统一的流水线中，实现真正个性化的自动化审查。

代码审查流水线架构与模式应用

审查流水线的 Mermaid 图示

以下图表展示了代码审查 Agent 的完整处理链路，从代码输入到审查意见输出的全链路：

graph TD
    A[代码/Patch 输入] --> B[语法预检]
    B -->|语法错误| C[直接返回错误]
    B -->|语法正确| D[AST 静态分析]
    D --> E[规则引擎检查]
    E --> F[LLM 语义审查]
    F --> G[结果聚合与去重]
    G --> H[优先级排序]
    H --> I[生成审查报告]
    I --> J[一键修复建议]
    K[责任链处理器] -.-> D
    K -.-> E
    K -.-> F
    L[装饰器增强] -.-> D
    L -.-> E

责任链模式实现多阶段审查

代码审查涉及多个独立的检查阶段（语法检查、静态分析、安全扫描、LLM 语义评估），每个阶段都可能产生问题或决定流程是否继续。责任链模式（Chain of Responsibility Pattern）将这些阶段串联成一条处理链，每个节点只关注自身职责，并将结果传递给下一个节点。

from abc import ABC, abstractmethod
from dataclasses import dataclass, field
from typing import Any


@dataclass
class ReviewContext:
    """审查上下文，在责任链中传递。"""
    code: str
    filename: str
    issues: list[CodeIssue] = field(default_factory=list)
    metadata: dict[str, Any] = field(default_factory=dict)
    should_stop: bool = False


class ReviewHandler(ABC):
    """审查处理器抽象基类。"""

    def __init__(self):
        self._next: ReviewHandler | None = None

    def set_next(self, handler: "ReviewHandler") -> "ReviewHandler":
        self._next = handler
        return handler

    @abstractmethod
    async def handle(self, context: ReviewContext) -> ReviewContext:
        ...

    async def _pass_to_next(self, context: ReviewContext) -> ReviewContext:
        if self._next and not context.should_stop:
            return await self._next.handle(context)
        return context


class SyntaxCheckHandler(ReviewHandler):
    """语法预检处理器。"""

    async def handle(self, context: ReviewContext) -> ReviewContext:
        try:
            ast.parse(context.code)
        except SyntaxError as e:
            context.issues.append(CodeIssue(
                "critical", "syntax",
                f"Syntax error: {e}", e.lineno or 1,
                "Fix syntax before further review"
            ))
            context.should_stop = True
        return await self._pass_to_next(context)


class StaticAnalysisHandler(ReviewHandler):
    """AST 静态分析处理器。"""

    def __init__(self):
        super().__init__()
        self.analyzer = StaticAnalyzer()

    async def handle(self, context: ReviewContext) -> ReviewContext:
        issues = self.analyzer.analyze(context.code, context.filename)
        context.issues.extend(issues)
        # 记录复杂度元数据
        context.metadata["issue_count_static"] = len(issues)
        return await self._pass_to_next(context)


class LLMReviewHandler(ReviewHandler):
    """LLM 语义审查处理器。"""

    async def handle(self, context: ReviewContext) -> ReviewContext:
        # 构建增强 prompt，包含前面阶段的结果
        prompt = self._build_enhanced_prompt(context)
        agent = Agent(
            name="SemanticReviewer",
            instructions="You are a senior engineer. Focus on design patterns and architecture.",
            model="gpt-5-nano"
        )
        result = await Runner.run(agent, prompt)
        # 解析 LLM 输出并添加到上下文
        llm_issues = self._parse_issues(result.final_output)
        context.issues.extend(llm_issues)
        context.metadata["issue_count_llm"] = len(llm_issues)
        return await self._pass_to_next(context)


class ReviewPipeline:
    """审查流水线，组装责任链。"""

    def __init__(self):
        self._head = self._build_chain()

    def _build_chain(self) -> ReviewHandler:
        syntax = SyntaxCheckHandler()
        static = StaticAnalysisHandler()
        llm = LLMReviewHandler()
        # 组装责任链: syntax -> static -> llm
        syntax.set_next(static).set_next(llm)
        return syntax

    async def review(self, code: str, filename: str) -> ReviewContext:
        context = ReviewContext(code=code, filename=filename)
        return await self._head.handle(context)

责任链模式的核心价值在于阶段隔离与可组合性。开发团队可以根据项目需求灵活调整审查链路：对于脚本类项目可以跳过 AST 深度分析，对于安全敏感项目可以插入 SecurityScanHandler。每个处理器的输入输出通过 ReviewContext 统一约定，实现了阶段间的松耦合。

装饰器模式增强审查能力

在基础审查能力之上，团队往往需要按需增强特定功能（如忽略测试文件、对第三方库代码降级处理、添加团队自定义规范）。装饰器模式（Decorator Pattern）可以在不修改原处理器的前提下，为其附加额外行为。

class IgnorePatternDecorator(ReviewHandler):
    """装饰器：根据模式忽略特定文件。"""

    def __init__(self, handler: ReviewHandler, patterns: list[str]):
        super().__init__()
        self._handler = handler
        self._patterns = patterns

    async def handle(self, context: ReviewContext) -> ReviewContext:
        for pattern in self._patterns:
            if re.search(pattern, context.filename):
                context.metadata["ignored"] = True
                return context
        return await self._handler.handle(context)

通过组合责任链与装饰器，代码审查 Agent 既能保持核心逻辑的简洁，又能适应各种复杂的团队规范。这种架构设计使得审查系统可以随着工程实践的演进持续迭代，而不会陷入"牵一发而动全身"的维护困境。

增量审查与并发控制策略

在审查大型 Pull Request 时，全量分析会导致 token 消耗激增和延迟飙升。增量审查策略只分析变更的代码片段及其直接影响范围（如被修改函数的调用链），将问题域缩小到可管理的规模。

import git

class IncrementalReviewer:
    """增量审查器，基于 Git diff 确定审查范围。"""

    def __init__(self, repo_path: str):
        self.repo = git.Repo(repo_path)

    def get_review_targets(self, base_ref: str, head_ref: str) -> list[dict]:
        """获取需要审查的目标文件和行号范围。"""
        diff = self.repo.git.diff(base_ref, head_ref, unified=3)
        targets = []
        for file_diff in self._parse_diff(diff):
            # 只审查变更的函数及其调用者
            changed_lines = file_diff["changed_lines"]
            affected_funcs = self._find_affected_functions(
                file_diff["filename"], changed_lines
            )
            targets.append({
                "filename": file_diff["filename"],
                "functions": affected_funcs,
                "context_lines": changed_lines
            })
        return targets

并发控制方面，对于包含大量文件的 PR，可以将每个文件分配给独立的审查任务，通过 asyncio.gather 并行处理。但需要注意 LLM API 的速率限制，建议使用令牌桶或信号量控制并发数，避免因触发限流而导致审查失败。

生产环境部署与性能优化

CI/CD 集成的实践要点

将本章节的技术应用到生产环境时，首要考虑的是稳定性与可观测性。建议采用渐进式 rollout 策略：先在开发环境验证核心逻辑，再迁移到预发布环境进行压力测试，最后才全量上线。部署过程中应配置完善的日志收集和指标监控，确保任何问题都能被快速发现和定位。

具体来说，需要在基础设施层面做好以下准备：容器资源限制（CPU/内存）、网络策略配置（防火墙规则、服务网格）、持久化存储选型（SSD vs 标准盘）以及备份恢复方案。对于高可用要求严格的场景，建议部署多实例并配置负载均衡，避免单点故障导致服务中断。

审查覆盖率的关键指标

监控是生产系统的生命线。针对本章节涉及的功能，建议重点跟踪以下指标：请求延迟（P50/P95/P99）、错误率（4xx/5xx/超时）、吞吐量（QPS/TPS）以及资源利用率（CPU/内存/磁盘/网络）。这些指标应接入统一的监控大盘，并设置合理的告警阈值。

除了基础指标，还应关注业务层面的指标。例如功能成功率、用户满意度、成本消耗趋势等。通过将技术指标与业务指标关联分析，可以更准确地评估系统改进的实际价值，避免陷入"为了优化而优化"的陷阱。

大规模代码库的架构考量

随着业务规模增长，单实例部署很快会成为瓶颈。扩展性设计应在项目初期就纳入考量，而非事后补救。水平扩展通常比垂直扩展更具成本效益，但也引入了分布式系统的复杂性（数据一致性、服务发现、负载均衡等）。

在扩展过程中，建议遵循"无状态优先"原则：将状态外置到独立的存储层（如 Redis、PostgreSQL），使计算层可以随时水平扩容。对于无法避免的状态（如会话、缓存），采用分布式一致性协议或最终一致性模型来管理。定期进行容量规划和压力测试，确保系统在流量峰值时仍能稳定运行。

运维团队的协作建议

技术方案的落地离不开高效的团队协作。建议建立清晰的运维手册（Runbook），涵盖常见故障的诊断步骤、应急处理流程和升级路径。同时，通过定期的复盘会议，将线上事故转化为团队的学习素材，持续完善系统的健壮性。

在工具链方面，推荐将本章节的配置和脚本纳入版本控制（Git），并使用 Infrastructure as Code（IaC）工具（如 Terraform、Ansible）管理基础设施变更。这不仅能提高部署效率，还能确保环境一致性，减少"在我机器上能跑"的问题。
代码审查 Agent 的审查意见应支持一键应用到代码库。通过与 IDE 插件集成，开发者可以直接在编辑器中查看、讨论和采纳审查建议，形成闭环工作流。