## 功能简介 automated-code-review-tool 是一个多终端自动化代码审查平台。它通过 VS Code 扩展、GitHub webhooks 和 GitHub Action 获取源文件和 PR diffs，通过 FastAPI ML worker 运行反模式检测，并通过 Next.js 仪表板展示内联波浪线提示、PR 评论和质量评分。 三个用户终端分别为： - **VS Code 扩展** — 保存时提供内联诊断 - **GitHub Action** — 在 pull_request 事件中进行 PR 审查注释 - **Next.js Web 仪表板** — 仓库级别的质量趋势和发现记录 生产环境检测器：确定性后备扫描器 Fine-tuned checkpoint：不可用 模型训练 pipeline：验证中 真实冻结数据集：不可用 已验证的评估工件：不可用 Redis 限流：已实现 Hunk 级别本地化：已实现 该平台搭载了一个确定性后备扫描器作为其主要的生产环境检测器。Fine-tuned 的 CodeBERT 模型 pipeline 目前正在验证中。 ## 架构 ``` ┌──────────────────────────┐ │ User Surfaces │ ├──────────────────────────┤ │ Next.js Dashboard │ │ VS Code Extension │ │ GitHub Action │ └────────────┬─────────────┘ │ HTTPS ▼ ┌──────────────────────────┐ │ Spring Boot API │ │ Java 21 · JWT · JPA │ │ GitHub OAuth · Webhooks │ └────┬───────────────┬─────┘ │ │ JPA │ │ HTTP (internal) ▼ ▼ ┌──────────────────┐ ┌──────────────────┐ │ PostgreSQL 16 │ │ FastAPI ML │ │ Redis 7 cache │ │ Worker │ └──────────────────┘ └────────┬─────────┘ │ ▼ ┌──────────────────┐ │ HF Hub / Rules │ │ (model storage) │ └──────────────────┘ ``` ### 系统拓扑 ``` graph TD UserSurface["User Surfaces (Dashboard / VS Code / GitHub Action)"] Gateway["Spring Boot Gateway (Java 21)"] DB[(PostgreSQL 16)] Cache[(Redis 7)] MLWorker["FastAPI ML Worker (Python 3.11)"] HFRepo[("HuggingFace Hub or Rule-based Scanner")] UserSurface -->|HTTPS API Requests / cookies / API Keys| Gateway Gateway -->|JPA Persistence| DB Gateway -->|Rate Limits & Sessions| Cache Gateway -->|HTTP REST Client| MLWorker MLWorker -->|Loads fine-tuned model OR rule-based scan| HFRepo ``` ## Webhook 审查与检测 Pipeline 当开发者在已连接的仓库中发起 PR 时，系统会运行以下端到端流程： ``` sequenceDiagram autonumber actor Developer participant GitHub as GitHub Webhook participant Gateway as Spring Boot API participant DB as Postgres & Redis participant MLWorker as FastAPI ML Worker participant Model as CodeBERT / Rule Scanner Developer->>GitHub: Pushes code / Opens PR GitHub->>Gateway: POST /api/webhook/github (HMAC Signature + Delivery ID) rect rgb(240, 248, 255) Note over Gateway,DB: Check Signature & Idempotency Gateway->>Gateway: Verify SHA-256 HMAC Signature Gateway->>DB: Query processed_webhooks (exists check) DB-->>Gateway: Exists (Skip) or Not Exists (Save & Proceed) end Gateway-->>GitHub: HTTP 200 OK (Immediate response) rect rgb(255, 240, 245) Note over Gateway,MLWorker: Asynchronous PR Scanning (ThreadPoolTaskExecutor) Gateway->>GitHub: GET PR Diff file (using decrypted OAuth Token) GitHub-->>Gateway: Code Diff Payload Gateway->>MLWorker: POST /ml/review (Raw Diff Content) MLWorker->>Model: Sliding-window inference OR regex scan Model-->>MLWorker: Findings + quality score MLWorker-->>Gateway: Findings + quality score end Gateway->>DB: Save Scan PullRequestEntity & MlFindings Gateway->>GitHub: POST /repos/{repo}/issues/{number}/comments (Quality Report) ``` ### Pipeline 阶段说明 1. **身份验证与 HMAC 签名验证。** 每个 GitHub webhook 都会使用恒定时间的 SHA-256 HMAC 与仓库注册的密钥进行比对验证。 2. **有状态幂等性。** Webhook 投递会在 Redis 和 PostgreSQL (`processed_webhooks`) 中进行跟踪，以唯一的 `X-GitHub-Delivery` 标头作为键，从而杜绝重放攻击和冗余的模型运行。 3. **异步派发。** API 会立即向 GitHub 返回 `200 OK`。PR diff 获取和 ML worker 编排将在配置好的 Spring `ThreadPoolTaskExecutor` 上运行。 4. **Diff 分割与滑动窗口。** 大型 PR diff 会被分割成 512-token 的窗口，并带有 50-token 的重叠步长，以便适应 CodeBERT 的序列限制。每个窗口的 logits 会通过 max-pool 进行聚合。 5. **模型推理。** FastAPI worker 托管了一个基于 CodeBERT 的多标签分类器，包含六个二元头：`SECURITY`、`PERFORMANCE`、`ARCHITECTURE`、`RELIABILITY`、`READABILITY` 和 `MAINTAINABILITY`。当模型不可用时，基于规则的后备扫描器将返回关于硬编码凭据、SQL 注入、异步路径中的同步 I/O、裸 except 和二次循环的检测结果。 6. **报告。** 检测结果将被持久化，PR 会随之更新，同时一份 Markdown 格式的质量报告将作为评论发布到 PR 上。 ## 技术栈 | 组件 | 语言 / 技术 | 路径 | | ---------------- | ------------------------------- | ---------------------- | | **API** | Java 21 · Spring Boot 3.3 | `apps/api/` | | **安全** | JWT, OAuth 2.0, HMAC-SHA256 | `apps/api/src/main/java/com/automatedcodereviewtool/security/` | | **ML Worker** | Python 3.11 · FastAPI · CodeBERT | `apps/ml-worker/` | | **Web 仪表板**| TypeScript · Next.js 15 | `apps/web/` | | **VS Code 扩展** | TypeScript · VS Code API | `apps/vscode-ext/` | | **GitHub Action**| TypeScript · @actions/core | `github-action/` | | **数据库** | PostgreSQL 16 · Flyway | `apps/api/src/main/resources/db/migration/` | | **缓存 / 队列**| Redis 7 | `apps/api/src/main/resources/` | | **ML 模型托管**| HuggingFace Hub (或基于规则) | 可通过 `MODEL_NAME` 环境变量配置 | | **CI/CD** | GitHub Actions | `.github/workflows/` | | **容器化**| Docker · Render blueprints | `Dockerfile`, `render.yaml` | ## 反模式类别 | 类别 | 描述 | 示例 | | ---------------- | -------------------------------------------------- | ----------------------------------------- | | SECURITY | 漏洞和凭据泄露 | 硬编码 API 密钥、SQL 注入、弱加密 | | PERFORMANCE | 低效的数据访问或计算 | N+1 查询、二次循环 | | ARCHITECTURE | 结构 / 模块级别的坏味道 | 上帝类、循环导入 | | RELIABILITY | 故障模式和缺失的安全防护 | 裸 except、缺失重试、缺失超时 | | READABILITY | 命名和结构清晰度 | 魔法数字、晦涩的命名、过长的方法 | | MAINTAINABILITY | 代码腐化和重复 | 被注释掉的代码、重复的逻辑 | ## 快速开始 ### 使用 Docker Compose 自托管 ``` git clone https://github.com/tanmay-alpha/automated-code-review-tool.git cd automated-code-review-tool cp .env.example .env # fill in GITHUB_CLIENT_ID, JWT_SECRET, etc. docker compose up --build # postgres, redis, ml-worker, api, web ``` 一旦 web 容器健康运行，即可打开 `http://localhost:3000`。 ### 部署到 Render 该仓库提供了一个 `render.yaml` 蓝图，定义了四个服务： - `automated-code-review-tool-db` — PostgreSQL 16，Standard 计划 - `automated-code-review-tool-redis` — Redis 7，Starter 计划 - `automated-code-review-tool-api` — Spring Boot web 服务，Standard 计划 - `automated-code-review-tool-ml-worker` — FastAPI web 服务，Standard 计划 将仓库作为“基础设施即代码”项目连接到 Render，这四个服务将自动启动。在首次部署之前，请设置 `sync: false` 环境变量（`JWT_SECRET`、`ENCRYPTION_KEY`、`GITHUB_CLIENT_ID/SECRET`、`HF_TOKEN`、`ML_WORKER_SECRET`）。 ### 连接到 Supabase (生产云数据库) 要在 Render 上部署或在本地运行时将应用程序连接到 **Supabase** PostgreSQL： 1. 在 [Supabase](https://supabase.com) 创建一个项目。 2. 在 Render 上将 `SPRING_DATASOURCE_URL`、`SPRING_DATASOURCE_USERNAME` 和 `SPRING_DATASOURCE_PASSWORD` 设置为您的 Supabase JDBC 凭据。 3. Spring Boot 的 Flyway 集成会在启动时自动初始化并迁移您的 Supabase 数据库 schema。 有关完整的集成分步指南，请参阅 **[SUPABASE_SETUP.md](SUPABASE_SETUP.md)**。 ### 训练 CodeBERT 模型 ``` cd apps/ml-worker pip install -r requirements-train.txt # 1. 生成训练数据（4k 合成样本） python training/generate_training_data.py \ --output-dir training/data \ --train-size 4000 --val-size 400 --test-size 400 # 2. 在 GPU 机器或 Colab Pro 上进行 Fine-tune python training/train.py \ --output-dir ./automated-code-review-tool-model \ --data-dir training/data \ --model-name microsoft/codebert-base \ --epochs 5 --batch-size 16 --lr 2e-5 \ --push-to-hub --hf-repo YOUR_USER/automated-code-review-tool-codebert # 3. （可选）在留出测试集上进行评估 python training/evaluate.py \ --model-dir ./automated-code-review-tool-model \ --data-dir training/data \ --output evaluation_results.json ``` 完整的 pipeline 请参阅 `apps/ml-worker/training/RUN_TRAINING.md`。 ## 评估 评估框架已完全实现。可以使用精确率、召回率和 macro-F1 在留出测试集上对训练好的模型进行评估。有关训练 pipeline，请参阅 `apps/ml-worker/training/evaluate.py` 和 `RUN_TRAINING.md`。 | 模型 | Macro-F1 | 精确率 | 召回率 | 推理延迟 (p50) | | ------------------------------ | -------- | --------- | ------ | ----------------------- | | CodeBERT fine-tune | _run evaluate.py_ | _run_ | _run_ | _measure_ | | 基于规则的基线 (regex) | _run evaluate.py_ | _run_ | _run_ | ~5 ms | ## API 参考 ### `POST /api/scan/file` — 文件级扫描 (VS Code 扩展，内部) ``` curl -X POST http://localhost:8080/api/scan/file \ -H "Authorization: Bearer $AUTOMATED_CODE_REVIEW_TOOL_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "content": "for u in users:\n posts = Post.where(user=u)", "language": "python", "filePath": "app/services/posts.py" }' # → { "findings": [...], "qualityScore": 62.5 } ``` ### `POST /api/auth/api-key/regenerate` — 签发新的 VS Code 密钥 ``` curl -X POST http://localhost:8080/api/auth/api-key/regenerate \ -H "Cookie: automated_code_review_tool_session=$JWT" \ # → { "apiKey": "cl_live_..." } ``` ## 安全实现 - **JWT token 黑名单** — 基于 JTI 的 token 失效机制实现安全登出 - **OAuth 2.0 集成** — 具备完善错误处理的 GitHub OAuth - **API 密钥管理** — 支持轮换且具有限流功能的 API 密钥 - **HMAC-SHA256 webhook 验证** — 恒定时间签名比对 - **敏感数据脱敏** — 自动过滤日志中的凭据信息 - **加密存储** — 使用 AES-GCM 加密 GitHub OAuth token 和 webhook 密钥 - **容器加固** — 非 root 用户、只读文件系统、健康检查 - **输入验证** — 结合 bean validation 和大小限制的多层验证 ## 简历要点 ## 许可证 [MIT](LICENSE) — © 2026 Tanmay Mangal.

标签：AV绕过, CodeBERT, FastAPI, GitHub Actions, SOC Prime, 代码审查, 域名枚举, 开发工具, 自动笔记, 请求拦截, 错误基检测, 静态代码分析