Git Code Review Agent

基于 AI 的 GitHub PR 代码审查助手。监听 GitHub Webhook 事件，通过 Plan-Execute-Refine Agent 范式调度 LLM + 静态分析工具，自动生成结构化 Review 意见并回写到 PR 评论区。

架构总览

GitHub PR Webhook → Worker Pool → Agent Loop (Plan-Execute-Refine) → PR 评论区
                                        │
        ┌───────────┬───────────┬───────┴───────┬───────────┐
        ▼           ▼           ▼               ▼           ▼
     LLM        Analyzer     Memory         Prompt       VCS
   Provider     Router      (pgvector)     Manager     GitHub

Agent 范式：Plan-Execute-Refine（共 3 次 LLM 调用，执行阶段 goroutine 并发）

• Plan：LLM 分析 PR 上下文，制定审查策略
• Execute：goroutine 并发运行静态分析工具 + 语义记忆检索
• Synthesize：LLM 综合所有结果，生成结构化 Review
• Refine：LLM 自校正严重等级、过滤假阳性（失败时降级为未精炼结果）

快速开始

cp .env.example .env
# 编辑 .env 填入你的 API Key
docker compose up -d

Webhook 地址：http://your-host:8080/webhook

本地调试需要公网 Webhook URL：

docker compose --profile demo up -d
# ngrok 会暴露公网 URL，配置到 GitHub Webhook 即可

配置

主配置文件 config.yaml，敏感信息通过环境变量注入：

变量	说明
WEBHOOK_SECRET	GitHub Webhook 签名密钥
DEEPSEEK_API_KEY	DeepSeek API Key（主力 LLM）
OPENAI_API_KEY	OpenAI API Key（Embedding + 备用 LLM）
ANTHROPIC_API_KEY	Anthropic API Key（Claude LLM）
GITHUB_TOKEN	GitHub Personal Access Token
DB_USER / DB_PASSWORD / DB_HOST	PostgreSQL（pgvector）连接信息

项目结构

.
├── cmd/server/              # 入口，依赖注入 + HTTP 启动
├── internal/
│   ├── agent/               # Plan-Execute-Refine Agent 编排
│   ├── analyzer/            # 静态分析插件层（统一接口）
│   │   ├── gosec/           # Go 安全扫描
│   │   ├── staticcheck/     # Go 静态检查
│   │   ├── govet/           # Go 自带 vet
│   │   └── eslint/          # JS/TS 代码检查（跨语言验证点）
│   ├── llm/                 # LLM Provider 层（DeepSeek/OpenAI/Claude）
│   ├── embedding/           # Embedding Provider（text-embedding-3-small）
│   ├── vcs/                 # VCS Provider 层（GitHub，Gitee 预留）
│   ├── memory/              # 语义记忆（pgvector 向量检索 + 去重）
│   ├── prompt/              # Prompt 版本管理 + A/B 实验
│   ├── webhook/             # Webhook Handler（HMAC-SHA256 签名验证）
│   ├── worker/              # Channel-based 协程池
│   ├── db/                  # PostgreSQL 连接（pgx）
│   └── config/              # YAML 配置加载 + 环境变量替换
├── migrations/              # 数据库迁移（pgvector 扩展 + 表结构）
├── prompts/                 # Prompt 模板文件
├── testdata/                # 测试固件
├── docker-compose.yml       # 一键启动：app + pgvector + (可选) ngrok
├── Dockerfile               # 多阶段构建（< 30MB）
├── config.yaml              # 默认配置
└── Makefile

核心设计决策

1. Agent 范式选型：Plan-Execute-Refine

在六大主流 Agent 范式中选定 Plan-Execute-Refine，而非 ReAct。原因：

代码审查的工具链是确定的——安全、风格、性能检查一个都不能少，不存在"LLM 自行判断跳过 gosec"的情况。Plan-Execute-Refine 确保所有开启的分析器必跑，执行阶段零 LLM 开销全并发，最后加一层 Self-Refine 做质量兜底。

范式	LLM 调用	并行	适用场景
ReAct	5-8 次	❌	开放式探索
Plan-Execute-Refine	3 次	✅	代码审查
Reflexion	2+N 次	✅	试错学习
Tree-of-Thought	4-6 次	❌	多角度推理

2. 五层 Provider 抽象

所有外部依赖均抽象为 Go 接口，每层独立可测、可替换，不绑定任何厂商：

type LLMProvider interface { ... }       // DeepSeek / OpenAI / Claude
type EmbeddingProvider interface { ... }  // text-embedding-3-small
type VCSProvider interface { ... }        // GitHub（Gitee 接口预留）
type Analyzer interface { ... }           // gosec / staticcheck / govet / ESLint
type MemoryManager interface { ... }      // pgvector 语义检索

3. 向量库选型：pgvector

不引入专用向量数据库。Prompt 版本管理已用 PostgreSQL，pgvector 只是同一实例的一个扩展——CREATE EXTENSION vector 一行 SQL。pgvector/pgvector:pg16 镜像替代原生 postgres，零额外基础设施。IVFFlat 索引在 10 万条以内精度和 HNSW 无差别。

4. Embedding 跨厂商混用

LLM 主力用 DeepSeek（便宜、中文好），Embedding 用 OpenAI text-embedding-3-small。原因：Embedding API 维度永不变化（1536 维），pgvector 索引无需重建；调用量比 LLM 小一个数量级，成本差异可忽略。每层选最合适的，不绑定一家。

5. 错误降级策略

场景	策略
LLM API 超时/限流	重试 3 次 + 指数退避，最终失败回写 "⚠️ AI Review 暂时不可用"
静态分析工具报错	跳过该工具，作为 tool-error 类型 Finding 上报
pgvector 连接断开	降级跳过记忆检索，不影响主链路
Refine 阶段 LLM 不可用	降级使用 Synthesize 原始输出
Analyzer 二进制缺失	启动时 WARN + 自动 disable

6. Worker Pool 并发控制

Channel-based 协程池，maxConcurrent 控制同时处理的 PR 数，防止 LLM API 限流。Submit/Shutdown 互斥锁保护消除 send-on-closed-channel 竞态，worker panic 通过 defer recover 兜底。

技术栈

组件	选型
语言	Go 1.22+
LLM	DeepSeek（主力）/ OpenAI / Claude
Embedding	OpenAI text-embedding-3-small
向量库	pgvector（PostgreSQL 扩展）
数据库	PostgreSQL 16
静态分析	gosec / staticcheck / govet / ESLint
部署	Docker Compose（含可选 ngrok sidecar）
VCS SDK	go-github v68

设计文档

完整架构设计见 docs/superpowers/specs/2026-08-03-code-review-agent-design.md。