使用说明
AI代码审查代理
多代理人工智能系统，使用4个专门的LLM代理+并行运行的Semgrep静态分析来审查GitHub拉取请求，捕捉安全漏洞、性能问题、风格违规和测试差距——按严重程度和确切的行号分类。
为什么这很重要
手动代码审查受到审查员可用性和认知负荷的限制。该代理在30-90秒内审查PR，在安全性、性能、风格和测试方面具有一致的覆盖范围——由于时间压力，人工审查人员经常跳过或匆匆通过这些领域。
建筑
┌─────────────────┐
│ Entry Points │
│ Web UI │ CLI │ │
│ GitHub Action │
│ MCP Server │
└────────┬────────┘
│
┌────────▼────────┐
│ FastAPI │
│ Backend API │
└────────┬────────┘
│
┌───────────────▼───────────────┐
│ GitHub Service (PyGithub) │
│ Fetch PR diff + metadata │
└───────────────┬───────────────┘
│
┌───────────────▼───────────────┐
│ Diff Parser & Chunker │
│ Smart splitting by function │
│ boundaries + file priority │
└───────────────┬───────────────┘
│
┌────────────────────▼────────────────────┐
│ LangGraph Orchestration │
│ │
│ ┌────────────────────────────────────┐ │
│ │ Semgrep MCP (deterministic SAST) │ │
│ │ Security scan → ground truth │ │
│ └──────────────┬─────────────────────┘ │
│ │ │
│ ┌──────────┐ ┌▼─────────┐ ┌──────────┐ │
│ │ Security │ │ Perf │ │ Style │ │
│ │ Agent │ │ Agent │ │ Agent │ │
│ │+Semgrep │ └────┬─────┘ └────┬─────┘ │
│ └────┬─────┘ │ │ │
│ │ ┌─────────┴─────────────┘ │
│ │ │ ┌──────────┐ │
│ │ │ │ Tests │ │
│ │ │ │ Agent │ │
│ │ │ └────┬─────┘ │
│ │ │ │ │
│ ┌────▼──▼───────▼────────────────────┐ │
│ │ Aggregator │ │
│ │ Dedup + rank + cross-validate │ │
│ └──────────────┬─────────────────────┘ │
│ │ │
│ ┌────────▼────────┐ │
│ │ Meta Reviewer │ │
│ │ Score & Verdict │ │
│ └────────┬────────┘ │
└────────────────┼─────────────────────────┘
│
┌────────────────▼────────────────┐
│ PostgreSQL Redis │
│ (review history) (diff cache) │
└─────────────────────────────────┘
技术栈
| 层 | 技术 | 为什么 |
|---|---|---|
| 前端 | Next.js 14，TypeScript，顺风，shadcn/ui | SSR，优秀的DX，现代组件库 |
| 后端 | FastAPI，Python 3.12，Pydantic | 异步原生，自动生成OpenAPI，强类型 |
| 代理框架 | LangGraph | 真正的并行扇出/扇入、条件路由、状态管理 |
| LLM | 顶点AI（Gemini 3.1 Pro） | 直接SDK，保证结构化JSON的response_schema |
| 静态分析 | Semgrep（通过MCP+CLI） | 确定性SAST——已知漏洞模式的零假阴性 |
| 结构化输出 | Pydantic模式+Gemini response_schema | 每次LLM调用都会返回经过验证的JSON；对格式错误的输出自动重试 |
| MCP | FastMCP服务器+Semgrep MCP客户端 | 将代理作为工具公开，并通过模型上下文协议使用外部工具 |
| Git | PyGithub | PR差异提取，评论发布 |
| 数据库 | PostgreSQL 16 | 查看历史记录，通过asyncpg异步 |
| 缓存 | Redis 7 | 跳过重新查看相同的差异（SHA-256哈希） |
| 部署 | Docker Compose，Vercel | 全栈本地开发，前端部署 |
关键设计：混合分析管道
代理人结合 确定性的 和 概率性的 分析：
| 层 | 工具 | 强度 | 弱点 |
|---|---|---|---|
| 确定性的 | Semgrep（3000多条规则） | 已知模式、精确的CWE/OWASP标签、精确的行 | 无法推理业务逻辑或新的错误 |
| 概率性的 | Gemini LLM（4个代理） | 发现逻辑错误、设计问题、缺失的测试、上下文问题 | 可能会产生幻觉或错过事情 |
| 混合 | Semgrep→ 安全代理 | Semgrep的发现作为基础事实注入，LLM验证+扩展 | 两者兼而有之：覆盖范围和推理 |
结构化输出执行
每次LLM调用都使用三层保证：
- 双子座
response_schema--模型被迫输出与Pydantic模式匹配的JSON - Pydantic验证 --使用严格类型解析和验证响应
- 自动重试 --验证失败时，错误将附加到提示中并重试（最多2x）
这完全消除了“有时LLM返回垃圾”的问题。
评估套件
8个已知错误的故意错误代码测试用例：
| 案例 | 预期检测 | 类别 |
|---|---|---|
| 通过f-string进行SQL注入 | SQL注入+参数化查询修复 | 安全 |
| 硬编码API密钥+密码 | 秘密检测 | 安全性 |
| ORM循环中的N+1查询 | 查询优化 | 性能 |
| 文件I/O+API上缺少try/except | 错误处理 | 样式 |
| 零测试的支付处理商 | 测试覆盖率差距 | 测试覆盖 |
| 阻塞异步函数中的I/O | 异步+资源泄漏 | 性能 |
| XSS+pickle反序列化+CSRF | 多漏洞 | 安全 |
| O（n²）重复查找器 | 算法优化 | 性能 |
运行评估：
docker exec ai-code-review-agent-backend-1 python -m evals.runner
docker exec ai-code-review-agent-backend-1 python -m evals.runner --case sql_injection -v
结果： 100%检测率 在测试用例上（SQL注入、硬编码秘密、缺少测试）。
入口点
| 方法 | 说明 |
|---|---|
| 网页用户界面 | 将PR URL粘贴到 http://localhost:3000，获取视觉审查报告 |
| 命令行界面 | python backend/cli.py https://github.com/owner/repo/pull/123 |
| GitHub行动 | PR打开/更新时自动触发，发布评论作为PR评论 |
| MCP服务器 | 从Claude Desktop或Cursor使用：“为我查看此PR” |
技术决策
| 决策 | 权衡 | 基本原理 |
|---|---|---|
| CrewAI上的LangGraph | 更陡峭的学习曲线 | 通过 Send API，条件路由，一流的状态管理 |
| 平行扇出 | 更复杂的图拓扑 | 4个代理同时运行→ ~4x比顺序快 |
| Semgrep+LLM混合动力车 | 额外依赖（Semgrep） | 确定性SAST捕捉到LLM错过的东西；LLM能够理解规则无法表达的内容 |
| Gemini响应_模式 | 限制输出格式 | 消除JSON解析失败；重试处理边缘情况 |
| 直接谷歌GenAI SDK | 无LangChain抽象 | 更少的依赖关系，完全控制，立即支持最新模型 |
| Redis差异哈希缓存 | 额外的基础设施 | 相同的差异会立即返回；SHA-256确保正确性 |
| 条件聚合跳过 | 图中边缘稍多 | 如果没有发现，直接跳到元审阅者以保存LLM调用 |
| 正则表达式差异解析器+智能分块 | 不如Tree sitter AST精确 | 处理所有语言，按函数边界拆分，感知令牌预算 |
| MCP双向 | 要维护的两个协议 | 代理既是MCP服务器（可由IDE调用），也是MCP客户端（调用Semgrep） |
快速开始
先决条件
- Docker&Docker编写
- 什么之中的一个： 顶点AI（GCP） 或 Gemini API密钥
设置
git clone <repo-url>
cd ai-code-review-agent
cp backend/.env.example backend/.env
# Edit backend/.env — set GCP_PROJECT_ID or GEMINI_API_KEY
docker compose up -d
用法
Web用户界面： 打开 http://localhost:3000
CLI：
python backend/cli.py https://github.com/owner/repo/pull/123
评价：
docker exec ai-code-review-agent-backend-1 python -m evals.runner -v
MCP服务器（克劳德桌面）：
# See mcp-config.example.json for configuration
python backend/mcp_server.py
API终点
| 方法 | 端点 | 描述 |
|---|---|---|
| 职位 | /api/v1/reviews |
提交PR以供审核 |
| 得到 | /api/v1/reviews |
列出审核历史记录 |
| 得到 | /api/v1/reviews/{id} |
获取评论详细信息 |
| 职位 | /api/v1/webhook/github |
GitHub webhook接收器 |
| 得到 | /api/v1/health |
健康检查 |
MCP工具
| 工具 | 方向 | 描述 |
|---|---|---|
review_pull_request |
服务器（公开） | 按URL查看GitHub PR |
review_diff |
服务器（暴露） | 查看原始git差异 |
get_supported_languages |
服务器（公开） | 列出可分析的语言 |
security_check |
客户端（已消耗） | 调用Semgrep MCP进行SAST扫描 |
代理
| 代理人 | 职责 | 关键检查 |
|---|---|---|
| Semgrep | 确定性SAST | CWE/OWASP基于规则的扫描，3000多种模式 |
| 安全 | 漏洞检测（LLM） | SQL注入、XSS、硬编码秘密、身份验证缺陷、SSRF+Semgrep上下文 |
| 演出 | 效率分析 | N+1查询、内存泄漏、O（N²）算法、阻塞I/O |
| 风格 | 代码质量 | 命名、DRY、SOLID、错误处理、可读性、类型注释 |
| 测试覆盖率 | 测试差距 | 缺失测试、边缘情况、断言质量 |
| 聚合器 | 结果合并 | 重复数据删除、优先级排序、误报删除 |
| 元审阅者 | 最终判定 | 总分（0-10）、推荐、风险评估 |
项目结构
ai-code-review-agent/
├── backend/
│ ├── app/
│ │ ├── agents/
│ │ │ ├── graph.py # LangGraph pipeline (Semgrep → 4 agents → aggregator)
│ │ │ ├── llm.py # Google GenAI SDK + structured output + retry
│ │ │ ├── schemas.py # Pydantic response models for LLM output
│ │ │ └── prompts.py # Agent system prompts
│ │ ├── api/routes.py # FastAPI endpoints
│ │ ├── core/
│ │ │ ├── config.py # Pydantic settings (Vertex AI / API key)
│ │ │ ├── database.py # PostgreSQL async
│ │ │ └── cache.py # Redis caching
│ │ ├── models/
│ │ │ ├── review.py # SQLAlchemy models
│ │ │ └── schemas.py # API Pydantic schemas
│ │ ├── services/
│ │ │ ├── github_service.py # GitHub API integration
│ │ │ ├── review_service.py # Review orchestration
│ │ │ └── semgrep_service.py# Semgrep MCP client + CLI fallback
│ │ ├── utils/code_parser.py # Diff parsing & smart chunking
│ │ └── main.py # FastAPI app
│ ├── evals/
│ │ ├── test_cases.py # 8 known-bad code samples
│ │ └── runner.py # Eval CLI with scoring metrics
│ ├── mcp_server.py # MCP Server entry point
│ ├── cli.py # CLI entry point
│ └── Dockerfile
├── frontend/
│ ├── src/
│ │ ├── app/ # Next.js pages
│ │ ├── components/ # React components + shadcn/ui
│ │ └── lib/api.ts # API client
│ └── Dockerfile
├── mcp-config.example.json # MCP client configuration
├── docker-compose.yml
└── README.md
