dsngeu/code-review-agents
GitHub: dsngeu/code-review-agents
基于 Claude 的 GitHub 集中式代码审查平台，提供安全漏洞扫描、代码质量审查和分支对比分析三个可复用的自动化 Agent。
Stars: 0 | Forks: 0
# code-review-agents
适用于 GitHub 的集中式、可复用的**代码审查平台**。只需在此处**编写一次**审查逻辑；其他所有代码库只需添加微小的调用方工作流，即可自动获取该逻辑。只需修复或改进一次共享引擎，所有代码库都能同步更新。三个 Agent 共享同一个引擎，它们**仅提供建议**（绝不阻止合并）、**失败放行**，并且支持**多语言**（检测每个文件的语言并应用正确的检查）。
## 三个 Agent
| Agent | 触发器 | 审查内容 | 输出 | 默认 model | 开关 |
|-------|---------|---------|--------|---------------|--------|
| **1 · Security** | 自动，每个 PR | 仅安全漏洞 | 内联评论 + 摘要评论 + Check Run | Sonnet | 始终开启 |
| **2 · Branch review** | 手动（Actions 标签页） | 分支相对于 base 的更改 — 质量 **+** 安全 | 运行页面上的 Job Summary | Sonnet | 无（手动） |
| **3 · PR review** | 自动，每个 PR | 常规质量（bug、性能、设计）— **无安全检查** | 单条摘要评论 + Check Run | Sonnet | 代码库变量 `ENABLE_PR_REVIEW` |
这三个 Agent 都会在发现 HIGH/CRITICAL 级别的问题时 @-mention PR 作者及您的审查者列表，并且**每个 Agent 的模型均可配置**（`model` 工作流输入，默认为 `claude-sonnet-4-6`）。
## 工作原理
```
┌─────────────────────────────────────────────┐
│ code-review-agents (this repo) — the brain │
│ agents/_core/ shared engine │
│ agents/security/ Agent 1 (security) │
│ agents/review/ Agents 2 & 3 (quality) │
│ .github/workflows/ 3 reusable workflows │
└─────────────────────────────────────────────┘
▲ callers invoke the reusable workflows
┌──────────┴──────────┬─────────────┐
┌────────┐ ┌────────┐ ┌────────┐
│ repo 1 │ │ repo 2 │ │ repo N │ ← each adds small caller workflows
└────────┘ └────────┘ └────────┘
```
目标代码库的调用方工作流会调用此处的可复用工作流，该工作流会在 GitHub 托管的 runner 上运行匹配的 Agent。每个 Agent 都是共享 `runReview()` 引擎的一个轻量级入口，该引擎会：
- 获取 PR diff（或用于分支审查的 `compare/base...head`）以及已更改文件的完整内容
- **跳过任何技术栈的依赖/构建产物**（node_modules、Pods、Gradle、DerivedData、target/、.venv、lockfiles、binaries 等）
- 对文件进行风险分级并应用 `MAX_FILES` 预算（会披露被跳过的部分）
- 引入未更改的导入文件以提供数据流上下文
- 在文件边界处对大型 diff 进行分块，并**并行**审查各分块
- 通过 Claude tool-use 返回**结构化的审查结果**（无需脆弱的 JSON 解析）
- 运行**对抗性验证过程**以剔除误报
- 通过 Agent 的渠道（内联 / 摘要评论 / Job Summary / Check Run）进行输出，具备**幂等性**（首先删除其之前的评论）
**失败放行：** 任何错误 → 发出一条错误评论 / Job-Summary 备注 + @-mention，Check Run 状态为 `neutral`，绝不阻止 PR。
## 仓库布局
```
agents/_core/ config.js · github.js · payload.js · claude.js · review.js (shared engine)
agents/security/ index.js (Agent 1) · prompt.js (security lens)
agents/review/ prompt.js (general lens) · pr.js (Agent 3) · branch.js (Agent 2)
.github/workflows/ security-review.yml · pr-review.yml · branch-review.yml (reusable)
caller-workflow-template/ pr-security.yml · pr-review.yml · branch-review.yml (copy into target repos)
package.json Dependencies (@anthropic-ai/sdk)
```
## 设置 — 将 Agent 添加到您的仓库
您只需执行**一次**此操作：在您的账户下 fork（或复制）此仓库，然后在每个需要审查的仓库中存储**两个密钥**，并为每个 Agent 添加一个**调用方工作流文件**。下面是完整的操作步骤。
### 第 1 步 — 生成两个密钥
**密钥 1：Anthropic API key**（允许 Agent 调用 Claude）
1. 前往 **https://console.anthropic.com**
2. **Settings → API Keys → Create Key**，将其命名为例如 `code-review`
3. 复制其值 — 它以 `sk-ant-...` 开头（仅显示一次）
4. 确保您的账户已启用账单/积分功能，否则调用将失败
**密钥 2：GitHub Personal Access Token**（允许 Agent 检出 Agent 代码）
1. 前往 **https://github.com/settings/tokens** → **Tokens (classic)**
2. **Generate new token → Generate new token (classic)**
3. 将其命名为 `code-review`，并选择一个过期时间
4. 勾选唯一的顶级 **`repo`** 权限范围（无需其他权限）
5. **Generate token** 并复制它 — 以 `ghp_...` 开头（仅显示一次）
### 第 2 步 — 在每个目标仓库中保存密钥
GitHub 会按仓库存储这些信息。在**每个您希望被审查的仓库**中，前往：
**Repo → Settings → Secrets and variables → Actions → _Secrets_ 标签页 → New repository secret**
添加这两个密钥（名称必须**完全一致**）：
| 名称 | 值 | 标签页 |
|------|-------|-----|
| `ANTHROPIC_API_KEY` | 您的 `sk-ant-...` 密钥 | **Secrets** |
| `GH_PAT` | 您的 `ghp_...` token | **Secrets** |
### 第 3 步 — 添加调用方工作流文件
在目标代码库中，于 **`.github/workflows/`** 下创建以下文件 — 每个 Agent 对应一个。您可以任意挑选组合。
**Agent 1 — Security** → `.github/workflows/pr-security.yml`
```
name: Security Review
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
checks: write
pull-requests: write
jobs:
security:
uses: dsngeu/code-review-agents/.github/workflows/security-review.yml@main
with:
repo: ${{ github.repository }}
pr_number: ${{ github.event.pull_request.number }}
head_sha: ${{ github.event.pull_request.head.sha }}
pr_author: ${{ github.event.pull_request.user.login }}
# model: 'claude-sonnet-4-6' # optional per-repo override
secrets: inherit
```
**Agent 3 — PR quality review** → `.github/workflows/pr-review.yml`
```
name: Code Review
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
checks: write
pull-requests: write
jobs:
code-review:
if: ${{ vars.ENABLE_PR_REVIEW == 'true' }} # toggle (see Step 4)
uses: dsngeu/code-review-agents/.github/workflows/pr-review.yml@main
with:
repo: ${{ github.repository }}
pr_number: ${{ github.event.pull_request.number }}
head_sha: ${{ github.event.pull_request.head.sha }}
pr_author: ${{ github.event.pull_request.user.login }}
secrets: inherit
```
**Agent 2 — Manual branch review** → `.github/workflows/branch-review.yml`
```
name: Branch Review
on:
workflow_dispatch:
inputs:
model:
description: 'Claude model id'
required: false
default: 'claude-sonnet-4-6'
permissions:
contents: read
jobs:
branch-review:
uses: dsngeu/code-review-agents/.github/workflows/branch-review.yml@main
with:
repo: ${{ github.repository }}
ref: ${{ github.ref_name }} # the branch you pick in "Use workflow from"
base: '' # diff against the default branch
model: ${{ inputs.model }}
secrets: inherit
```
### 第 4 步 — 开启 Agent 3（仅在您添加了它的情况下）
Agent 3 **默认关闭**，因此它绝不会在代码库中造成意外惊吓。通过代码库**变量**来启用它：
**Repo → Settings → Secrets and variables → Actions → _Variables_ 标签页 → New repository variable**
- 名称：`ENABLE_PR_REVIEW`
- 值：`true`
将其设置为任何其他值（或删除它）即可关闭 Agent 3 — 无需更改文件。（Agent 1 和 2 不使用此功能。）
### 第 5 步 — 如果运行无法启动（`startup_failure`）
GitHub 可能会默认将 runner token 设置为只读。如果您看到 `startup_failure`，请为 token 授予一次写入权限：
**Repo → Settings → Actions → General → Workflow permissions → "Read and write permissions" → Save**
（或者执行 `gh api --method PUT repos///actions/permissions/workflow -f default_workflow_permissions=write`。）
### 快速参考
| 如果您想… | 位置 |
|----------|-------|
| 添加密钥 | Repo → Settings → Secrets and variables → Actions → **Secrets** |
| 启用 Agent 3 | Repo → Settings → Secrets and variables → Actions → **Variables** → `ENABLE_PR_REVIEW=true` |
| 更改 Agent 的模型 | 该调用方文件中 `with:` 下的 `model:` |
| 运行 Agent 2 | Repo → **Actions** 标签页 → Branch Review → Run workflow → 选择分支 |
## 测试它
1. 在目标代码库中，创建一个分支并添加一个包含故意留下的漏洞的文件，例如：
// test-vulnerabilities.js
function getUser(userId) {
db.query(`SELECT * FROM users WHERE id = ${userId}`); // SQL injection
}
const API_KEY = 'sk-prod-abc123def456'; // hardcoded secret
function runCmd(input) {
require('child_process').execSync(`ls ${input}`); // command injection
}
2. 从该分支向 `main` 发起一个 PR。
3. 检查该 PR — 您应该会看到：
- 一个 **Security Review** Check Run（中性）
- 针对漏洞代码行的**内联评论**
- 一条带有问题汇总表的**摘要评论**
- PR 作者 + 配置的审查者被 @-mention（因为发现了 HIGH/CRITICAL 级别的问题）→ 电子邮件通知
**错误路径测试：** 暂时将 `ANTHROPIC_API_KEY` 设置为无效值，发起一个 PR，并确认 Agent 会发布一条错误评论 + @-mention，且 Check Run 状态为 `neutral`（PR 仍然可以合并）。
## 配置
### 环境变量（按目标代码库调整，无需更改代码）
如果需要覆盖默认值，请将这些设置为代码库/组织变量，或在调用方工作流的 `env:` 中进行设置：
| 控制项 | 位置 | 默认值 | 含义 |
|------|-------|---------|---------|
| `model` | 调用方 `with:` 输入 | 按每个 Agent 设定 | Claude 模型 ID。所有 Agent 默认为 `claude-sonnet-4-6`。 |
| `ENABLE_PR_REVIEW` | 代码库**变量** | 未设置 | 设置为 `true` 以在代码库中启用 Agent 3（自动 PR 审查）。 |
| `notify_users` | 调用方 `with:` 输入 | — | 额外以逗号分隔的审查者，用于 @-mention（在 PR 作者之外额外添加）。 |
| `MAX_FILES` | env | `80` | 深入分析的最大已更改文件数；其余文件将被剔除风险评级并披露为已跳过。 |
| `CHUNK_CONCURRENCY` | env | `4` | 并行发送给 Claude 的分块数量。 |
| `INLINE_MIN_SEVERITY` | env | `LOW` | 发布**内联**评论所需的最低严重性级别（所有问题仍会出现在摘要中）。 |
| `VERIFY` | env | `true` | 用于剔除误报的对抗性验证过程。`false` = 更快/更便宜/更多噪音。 |
### 代码常量 (`agents/_core/config.js`)
| 常量 | 默认值 | 含义 |
|----------|---------|---------|
| `DEFAULT_MODEL` | `claude-sonnet-4-6` | 未提供 `model` 输入时的全局模型回退项 |
| `MAX_TOKENS` | `16000` | 每次 Claude 调用的最大输出 token 数 |
| `CLAUDE_MAX_RETRIES` | `5` | 针对临时 API 错误 (429/5xx) 的重试次数 |
| `CHUNK_SIZE_CHARS` | `600_000` | 进行分块前的字符阈值（约 150k token） |
| `ALWAYS_NOTIFY` | `['dsngeu']` | 硬编码的审查者回退项（在 `notify_users` 为空时使用） |
| `MAX_INLINE_COMMENTS` | `50` | 每次审查的内联评论上限 |
| `MAX_CONTEXT_FILES` | `20` | 为提供数据流上下文而引入的未更改的导入文件 |
| `SKIP_PATTERNS` | deps/build/binaries（所有技术栈） | 排除在审查之外的文件 |
安全审查标准位于 `agents/security/prompt.js`；常规审查标准位于 `agents/review/prompt.js`。
### 它如何处理棘手情况
- **大型 PR：** 对文件进行风险评级（安全关键字 + 代码本质优先于原始大小）；审查前 `MAX_FILES` 个文件，其余文件在摘要中披露 — 绝不悄无声息地丢弃。
- **可靠的审查结果：** Claude 返回结构化的工具输出（无需 JSON 解析）；内联评论行会根据 diff 进行验证，并带有针对每条评论的回退机制，因此一行错误的代码不会导致整个审查失效。
- **更少的误报：** 验证过程会在发布前驳斥薄弱的审查结果。
- **幂等重跑：** 每次推送都会在发布新评论之前删除 Agent 之前的评论（带有隐藏标记） — 不会产生重复的垃圾信息。
## 设计保证
- **只读 + 评论** — Agent 只能读取代码并发布/更新 PR 评论。它们**无法修改或删除代码、分支、PR 或评论。** 通过两种方式强制执行此操作：工作流 token 为 `contents: read`（无 push/edit/delete 权限），并且代码硬阻断了除 GET/POST/PATCH 之外的所有 HTTP 方法（DELETE/PUT 会抛出异常）。重跑会原地更新现有评论 — 绝不删除。
- **无服务器** — 按需在 GitHub Actions 上运行。
- **单一事实来源** — 在此修复共享引擎，每个代码库都会即时更新。
- **按 Agent 设置模型** — 每个 Agent 的模型均通过 `model` 输入进行设置（参见配置）；更改其中一个不会影响其他 Agent。
- **仅提供建议** — 绝不阻止合并。
- **失败放行** — Agent 错误绝不会阻止 PR。
## 路线图
- GitHub App 身份验证（适用于客户账户，取代个人 PAT）
- 可选的合并阻断模式
- 基于共享引擎提供额外的审查视角（如无障碍访问、测试质量）
标签：AI辅助, GitHub Actions, MITM代理, SOC Prime, 代码审查, 开发工具, 网络调试, 自动化, 自动笔记, 自定义脚本, 错误基检测, 静态代码分析