bssm-oss/CodeAgora
GitHub: bssm-oss/CodeAgora
一个多 LLM 辩论式代码审查工具，通过让多个大模型并行审查、对抗讨论并达成共识，自动发现代码中的安全漏洞和逻辑缺陷。
Stars: 7 | Forks: 1
CodeAgora
让 LLM 为你的代码展开辩论
多个 LLM 并行审查你的代码，对冲突的意见进行辩论，然后由一个主 Agent 给出最终结论。不同的模型能捕获不同的 bug —— 共识机制过滤掉噪音。
## 快速开始
```
npm i -g @codeagora/review
agora init
git diff | agora review
```
`agora init` 会自动检测你的 API 密钥和 CLI 工具，然后生成配置。
## 支持的提供商（第 1 级）
| 提供商 | 类型 | 费用 |
|----------|------|------|
| Groq | API | 免费 |
| Anthropic | API | 付费 |
| Claude Code | CLI | 订阅 |
| Gemini CLI | CLI | 免费 |
| Codex CLI | CLI | 订阅 |
[完整提供商列表（24+ API，12 CLI） ->](docs/PROVIDERS.md)
## 工作原理
```
git diff | agora review
Pre --- Semantic Diff Classification
--- TypeScript Diagnostics
--- Change Impact Analysis
|
L1 --- Reviewer A (security) --+
--- Reviewer B (logic) --+-- parallel specialist reviews
--- Reviewer C (general) --+
|
Filter -- Hallucination Check (file/line validation)
--- Self-contradiction Filter
--- Evidence Dedup
|
L2 --- Adversarial Discussion (supporters must disprove)
--- Static analysis evidence in debate
|
L3 --- Head Agent --> ACCEPT / REJECT / NEEDS_HUMAN
|
Output -- Triage: N must-fix / N verify / N ignore
```
## 桌面应用
旧的 Web 仪表板和终端 TUI 正被整合到一个跨平台的 Tauri 桌面应用程序中。
CLI 仍然是 LLM Agent 和 CI 的主要自动化平台。桌面应用将成为面向人类的本地 UI，用于查看审查历史、配置、进度、成本和结果探索。
初步的私有脚手架位于 `packages/desktop` 目录中，桌面 MVP 正在逐步成型。
## MCP 服务器 (Claude Code / Cursor)
用于 AI IDE 集成的 9 工具 MCP server。
```
// claude_desktop_config.json or .cursor/mcp.json
{
"mcpServers": {
"codeagora": {
"command": "npx",
"args": ["-y", "@codeagora/mcp"]
}
}
}
```
工具：`review_diff`、`review_pr`、`review_staged`、`session_list`、`session_detail`、`explain_session`、`config_get`、`config_set`、`health_check`。
## 扩展
所有扩展都是可选的 —— 仅按需安装。
| 包 | 安装 | 功能 |
|---------|---------|-------------|
| [@codeagora/mcp](https://www.npmjs.com/package/@codeagora/mcp) | `npm i -g @codeagora/mcp` | MCP server（9 个工具） — 与 Claude Code、Cursor 及任何兼容 MCP 的 IDE 集成 |
核心的 `codeagora` CLI 包含了命令行审查和 GitHub Actions 所需的一切。面向人类的 UI 工作正在向桌面应用转移。
[扩展指南 ->](docs/EXTENSIONS.md)
## GitHub Actions
只需 2 步即可将 CodeAgora 添加到任何仓库：
**1. 创建 `.ca/config.json`**（或运行 `agora init`）：
```
{
"mode": "pragmatic",
"reviewers": [
{ "id": "r1", "model": "llama-3.3-70b-versatile", "backend": "api", "provider": "groq", "enabled": true, "timeout": 120 },
{ "id": "r2", "model": "qwen/qwen3-32b", "backend": "api", "provider": "groq", "enabled": true, "timeout": 120 },
{ "id": "r3", "model": "meta-llama/llama-4-scout-17b-16e-instruct", "backend": "api", "provider": "groq", "enabled": true, "timeout": 120 }
]
}
```
**2. 添加工作流**（`.github/workflows/codeagora-review.yml`）：
```
name: CodeAgora Review
on:
pull_request:
types: [opened, synchronize, reopened]
permissions:
contents: read
pull-requests: write
statuses: write
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: bssm-oss/CodeAgora@v2
with:
github-token: ${{ secrets.GITHUB_TOKEN }}
env:
GROQ_API_KEY: ${{ secrets.GROQ_API_KEY }}
```
**3. 将 `GROQ_API_KEY` 添加**到你仓库的 Settings > Secrets > Actions 中。
每个 PR 都会收到内联的审查评论、总结性结论和提交状态检查。在任何 PR 上添加 `review:skip` 标签即可跳过审查。
## 文档
| 文档 | 内容 |
|-----|---------|
| [CLI 参考](docs/CLI_REFERENCE.md) | 所有命令和选项 |
| [配置](docs/CONFIGURATION.md) | 配置文件指南 |
| [提供商](docs/PROVIDERS.md) | 完整提供商列表及层级 |
| [架构](docs/ARCHITECTURE.md) | Pipeline 设计与项目结构 |
| [扩展](docs/EXTENSIONS.md) | MCP 和桌面应用方向 |
| [产品界面计划](docs/PRODUCT_SURFACE_AND_LIGHTWEIGHT_PLAN.md) | 当前界面与轻量级路线图 |
| [Agent 契约](docs/AGENT_CONTRACT.md) | 稳定的 JSON、NDJSON、退出码和 MCP 输出语义 |
| [故障排除](docs/TROUBLESHOOTING.md) | 常见错误与修复，退出码 |
| [常见问题](docs/FAQ.md) | 常见问题解答 |
## 开发
```
pnpm install && pnpm build
pnpm test # 3386 tests
pnpm test:coverage # with coverage report
pnpm typecheck
pnpm cli review path/to/diff.patch
```
## 基准测试
`benchmarks/golden-bugs/` 下的黄金 bug fixture 驱动着假阴性测量框架（参见 #472）。
**对预计算结果进行评分**（快速，无 API 调用）：
```
pnpm bench:fn -- --validate-only # schema-check fixtures
pnpm bench:fn -- --results path/to/results-dir # score against pre-computed review output
pnpm bench:fn -- --results path/to/results-dir --json # CI-friendly JSON report
```
**针对每个 fixture 运行实时 Pipeline**（生成上述结果目录）：
```
export OPENROUTER_API_KEY=...
pnpm bench:fn:run -- --results ./bench-out
pnpm bench:fn -- --results ./bench-out
```
驱动程序默认使用 `benchmarks/.ca/config.json`。专用的运行配置位于 `benchmarks/.ca/` 目录下，包括用于单 fixture 免费模型门控的 `config.free-smoke.json`，以及用于当前低成本多样化基准测试的 `config.low-cost-diverse.json`。添加 `--fixtures id1,id2` 进行限制，添加 `--skip-head` 跳过 L3 裁决阶段。
两种 fixture 类型并存：
- **召回率用例**（`expectedFindings` 非空）—— 审查必须列出每个提及的 bug。遗漏计为 FN。
- **FP 回归用例**（`expectedFindings` 为 `[]`）—— 审查不应报告任何内容。任何发现都属于回归。
当前种子 fixture：8 个召回率用例（共 10 个预期发现） + 4 个 FP 回归用例。有关 fixture 格式，请参见 `benchmarks/golden-bugs/README.md`。
### 最新低成本多样化汇总 (2026-04-28 KST)
完整报告：[`docs/golden-bug-benchmark-report-2026-04-27.md`](docs/golden-bug-benchmark-report-2026-04-27.md)。
冒烟测试门控：
```
pnpm bench:fn:run -- --results ./bench-out-smoke \
--config benchmarks/.ca/config.free-smoke.json \
--fixtures authz-admin-bypass \
--skip-head
pnpm bench:fn -- --results ./bench-out-smoke
```
冒烟测试运行仅执行了 `authz-admin-bypass` 并通过了该 fixture（`1/1`，`fp=0`）。`bench-out-smoke` 的全量汇总数据没有实际意义，因为其他 fixture 并未运行。
完整的低成本多样化运行：
```
pnpm bench:fn:run -- --results ./bench-out-low-cost-confirmed-20260427 \
--config benchmarks/.ca/config.low-cost-diverse.json \
--skip-head
pnpm bench:fn -- --results ./bench-out-low-cost-confirmed-20260427
```
2026-04-28 的后续操作添加了 `auth-session-dual` 作为非配额的同文件多 bug 召回 fixture，然后将该 fixture 重新运行到相同的结果目录中：
```
pnpm bench:fn:run -- --results ./bench-out-low-cost-confirmed-20260427 \
--config benchmarks/.ca/config.low-cost-diverse.json \
--fixtures auth-session-dual \
--skip-head
pnpm bench:fn -- --results ./bench-out-low-cost-confirmed-20260427
```
| 指标 | 结果 |
|---|---:|
| 总 fixture 数 | 12 |
| 召回 / FP 回归 fixture 数 | 8 / 4 |
| 预期发现数 | 10 |
| 实际发现数 | 32 |
| TP / FP / FN | 10 / 0 / 0 |
| 精确率 | 100.0% |
| 召回率 | 100.0% |
| F1 | 100.0% |
| FP 干净率 | 100.0% |
| 平均 recall@3 / @5 / @10 | 100.0% / 100.0% / 100.0% |
| 触发的 FP 回归数 | 0/4 |
单 fixture 结果：每个召回 fixture 均以 `fp=0` 和 `r@3=100.0%` 通过；每个 FP 回归 fixture 均通过。在确认的汇总中，`quota-manager-dual` 和 `auth-session-dual` 均获得 `2/2`、`fp=0` 和 `r@3=100.0%` 的分数。
`bench:fn:run` 还会在 `
/_meta/` 下写入每个 fixture 的运行时元数据。对于目标为 `auth-session-dual` 的运行，`_meta/auth-session-dual.json` 记录了 `4` 次后端调用、`31,504ms` 的总后端延迟、`32,636ms` 的挂钟时间，以及成本 `N/A`，因为这些调用没有返回 token 使用量。
调优前的会话基线在低成本多样化运行中为 `TP=5 FP=20 FN=3`，精确率 `20.0%`，召回率 `62.5%`，F1 `30.3%`，FP 干净率 `50.0%`。
### 基线 (n=3, 2026-04-20)
使用默认 3 审查者 OpenRouter 配置进行的 3 次实时运行（[#24666562754](https://github.com/bssm-oss/CodeAgora/actions/runs/24666562754)、[#24667305646](https://github.com/bssm-oss/CodeAgora/actions/runs/24667305646)、[#24667897271](https://github.com/bssm-oss/CodeAgora/actions/runs/24667897271))：
| 指标 | 平均值 | 最小值 | 最大值 |
|---|---|---|---|
| recall@3 | 100.0% | 100.0% | 100.0% |
| recall@5 | 100.0% | 100.0% | 100.0% |
| recall@10 | 100.0% | 100.0% | 100.0% |
| 每个 fp-regression fixture 的 FP 数 | 2.3 | 2 | 3 |
| 触发的 fp-regression | 3/3 次运行 |
**召回率稳定** —— 在每次运行中，均在 top-3 内捕获了所有三个召回用例（off-by-one、null-deref、SQL injection）。
**每次运行均触发了 FP 回归** —— 但虚假发现的*内容*在不同运行之间会有所变化：第 1 次运行是关于未处理 `JSON.parse` 的 CRITICAL×3，第 2 次运行是关于 regex DoS + 输入大小的 WARNING×2，第 3 次运行是关于无限制字符串 + 缺少类型导入的 WARNING + CRITICAL。每一项单独的主张都是听起来合理、代码级别的断言，就像审查会对真实的 diff 提出的那样，这正是当前的校准栈没有过滤掉它们的原因。这证实了 `project_calibration_stack.md` 中记录的“高置信度确证 FP”盲点。该 fixture 是未来校准工作的回归门控（参见 #468）。
## 许可证
MIT标签：AI代码审查, AI辅助编程, Anthropic, CIS基准, Claude, CVE检测, DevSecOps, DLL 劫持, Gemini, Git集成, GNU通用公共许可证, LLM, MITM代理, Node.js, NPM包, OSV-Scalibr, TypeScript, Unmanaged PE, 上游代理, 云安全监控, 人机协同, 代码安全, 代码审查, 代码缺陷检测, 代码评审, 多智能体, 大语言模型, 威胁情报, 安全插件, 对抗性辩论, 开发者工具, 暗色界面, 漏洞枚举, 自动化攻击, 逻辑审查, 防幻觉检测, 静态分析