Li Liu
308 lines
12 KiB
Markdown
308 lines
12 KiB
Markdown
# Magpie - 多 AI 对抗式 PR 审查工具
|
||
|
||
## 概述
|
||
|
||
Magpie 是一个多 AI 对抗式代码审查工具。通过让多个 AI（不同模型 + 不同角色 prompt）互相辩论，暴露盲点，提升 PR 审查质量。
|
||
|
||
**核心理念：** Magpie 是一个"中转站"，在项目目录内运行，协调多个 AI 之间的辩论，每个 AI 都有完整的项目访问能力。
|
||
|
||
## 目标用户场景
|
||
|
||
- 主要场景：PR 审核
|
||
- 工作环境：VSCode（主力）+ GitHub 网页
|
||
- 代码托管：GitHub
|
||
|
||
## 整体架构
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ VSCode Extension │
|
||
│ (UI层：侧边栏、命令面板、结果展示) │
|
||
└─────────────────┬───────────────────────┘
|
||
│ 调用
|
||
┌─────────────────▼───────────────────────┐
|
||
│ Magpie CLI │
|
||
│ - 编排 AI 辩论流程 │
|
||
│ - 管理配置 │
|
||
│ - 在项目目录内运行 │
|
||
└─────────────────┬───────────────────────┘
|
||
│ 启动
|
||
┌─────────────────▼───────────────────────┐
|
||
│ AI Reviewers │
|
||
│ (各自有完整工具能力：gh、读文件等) │
|
||
│ Claude / GPT / Gemini / ... │
|
||
└─────────────────────────────────────────┘
|
||
```
|
||
|
||
**CLI 是核心**：所有逻辑在 CLI，VSCode 插件只是调用 CLI 并展示结果。
|
||
|
||
## Magpie 核心职责
|
||
|
||
Magpie 只做两件事：
|
||
|
||
1. **传话** - A 说完 → 传给 B → B 反驳 → 传给 C → ...
|
||
2. **管理流程** - 启动、轮数控制、结束、触发总结、输出结果
|
||
|
||
**AI 自己负责：**
|
||
- 获取 PR 信息（调用 `gh pr view`、`gh pr diff` 等）
|
||
- 理解项目上下文（按需读取文件）
|
||
- 分析 PR、提出观点和反驳
|
||
|
||
## 辩论流程
|
||
|
||
### 辩论模式
|
||
|
||
- **对抗式辩论**：多个 AI 轮流发言，互相挑战/反驳
|
||
- **支持 2+ 个 reviewer**：不限于两个 AI
|
||
- **轮流发言**：A → B → C → A → B → C... 每人依次回应之前所有发言
|
||
|
||
### 终止条件
|
||
|
||
- 设置最大轮数（默认 3 轮）
|
||
- 用户可随时介入或提前结束
|
||
|
||
### 运行模式
|
||
|
||
```bash
|
||
# 全自动模式（默认）- 跑完所有轮次
|
||
magpie review 123
|
||
|
||
# 手动模式 - 每个 AI 发言前暂停，可插话
|
||
magpie review 123 --interactive
|
||
```
|
||
|
||
手动模式下：
|
||
```
|
||
[审阅者1 发言完毕]
|
||
|
||
按 Enter 继续 / 输入内容插话 / 输入 q 结束辩论
|
||
> _
|
||
```
|
||
|
||
### 完整流程
|
||
|
||
```
|
||
用户: magpie review 123
|
||
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 1. 启动辩论者 │
|
||
│ AI-A (角色 prompt A) │
|
||
│ AI-B (角色 prompt B) │
|
||
│ AI-C (角色 prompt C) │
|
||
│ ... 都在项目目录下运行，有完整工具能力 │
|
||
└─────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 2. 辩论循环（轮流发言） │
|
||
│ A: 自己获取 PR 信息，分析，提出观点 │
|
||
│ ↓ (Magpie 传话) │
|
||
│ B: 看到 A 的观点，反驳/补充 │
|
||
│ ↓ (Magpie 传话) │
|
||
│ C: 看到 A、B 的观点，反驳/补充 │
|
||
│ ↓ │
|
||
│ ... 重复直到: 达到最大轮数 / 用户介入 │
|
||
└─────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 3a. 双方各自总结（匿名） │
|
||
│ │
|
||
│ AI-A → "请总结你的核心观点，不要透露身份" │
|
||
│ → 观点总结 1 │
|
||
│ │
|
||
│ AI-B → "请总结你的核心观点，不要透露身份" │
|
||
│ → 观点总结 2 │
|
||
│ │
|
||
│ AI-C → ... │
|
||
│ → 观点总结 3 │
|
||
└─────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 3b. 第三方总结 │
|
||
│ │
|
||
│ 新开 AI (中立 prompt) │
|
||
│ 输入: 所有匿名观点总结 │
|
||
│ 输出: │
|
||
│ - 共识点 │
|
||
│ - 分歧点及分析 │
|
||
│ - 最终建议 / action items │
|
||
└─────────────────────────────────────────────────────┘
|
||
↓
|
||
┌─────────────────────────────────────────────────────┐
|
||
│ 4. 输出 │
|
||
│ → VSCode 侧边栏显示（流式） │
|
||
│ → 或 markdown 文件 │
|
||
└─────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## CLI 设计
|
||
|
||
### 核心命令
|
||
|
||
```bash
|
||
# 审核一个 PR
|
||
magpie review <pr-url-or-number>
|
||
|
||
# 例如
|
||
magpie review 123
|
||
magpie review https://github.com/user/repo/pull/123
|
||
```
|
||
|
||
### 常用选项
|
||
|
||
```bash
|
||
# 指定配置文件（默认读取 ~/.magpie/config.yaml）
|
||
magpie review 123 --config ./custom-config.yaml
|
||
|
||
# 控制辩论轮数
|
||
magpie review 123 --rounds 5
|
||
|
||
# 手动模式（可插话）
|
||
magpie review 123 --interactive
|
||
|
||
# 输出格式
|
||
magpie review 123 --output report.md # 输出到文件
|
||
magpie review 123 --format json # JSON 格式（供 VSCode 插件解析）
|
||
```
|
||
|
||
### 辅助命令
|
||
|
||
```bash
|
||
magpie init # 初始化配置文件
|
||
magpie config validate # 验证配置文件
|
||
```
|
||
|
||
### 流式输出
|
||
|
||
```
|
||
$ magpie review 123
|
||
|
||
正在审查 PR #123...
|
||
|
||
[审阅者1 - 发言中...]
|
||
> 我注意到这个 PR 在 auth.ts:42 有一个潜在的...
|
||
> SQL 注入风险，用户输入直接拼接到查询中...
|
||
|
||
[审阅者2 - 发言中...]
|
||
> 同意安全问题，另外我注意到这里的循环...
|
||
```
|
||
|
||
## 配置文件设计
|
||
|
||
**全局配置 `~/.magpie/config.yaml`：**
|
||
|
||
```yaml
|
||
# AI 提供商密钥
|
||
providers:
|
||
anthropic:
|
||
api_key: ${ANTHROPIC_API_KEY}
|
||
openai:
|
||
api_key: ${OPENAI_API_KEY}
|
||
google:
|
||
api_key: ${GOOGLE_API_KEY}
|
||
|
||
# 默认辩论设置
|
||
defaults:
|
||
max_rounds: 3
|
||
output_format: markdown # markdown | json
|
||
|
||
# 角色配置
|
||
reviewers:
|
||
security-expert:
|
||
model: claude-sonnet-4-20250514
|
||
prompt: |
|
||
你是一位严格的安全专家。审查代码时重点关注：
|
||
- 注入漏洞（SQL、XSS、命令注入）
|
||
- 认证和授权问题
|
||
- 敏感数据处理
|
||
- 依赖安全性
|
||
|
||
performance-expert:
|
||
model: gpt-4o
|
||
prompt: |
|
||
你是一位性能优化专家。审查代码时重点关注：
|
||
- 时间复杂度
|
||
- 内存使用
|
||
- 不必要的计算或 IO
|
||
- 缓存机会
|
||
|
||
code-quality-expert:
|
||
model: gemini-pro
|
||
prompt: |
|
||
你是一位代码质量专家。审查代码时重点关注：
|
||
- 可读性和可维护性
|
||
- 设计模式运用
|
||
- 测试覆盖
|
||
- 文档完整性
|
||
|
||
# 总结者配置
|
||
summarizer:
|
||
model: claude-sonnet-4-20250514
|
||
prompt: |
|
||
你是一位中立的技术评审总结者。
|
||
基于多位审阅者的匿名观点，输出客观总结：
|
||
- 共识点
|
||
- 分歧点及各自理由
|
||
- 建议的 action items
|
||
```
|
||
|
||
## VSCode 插件设计
|
||
|
||
**功能极简，只做 UI 壳：**
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────┐
|
||
│ VSCode │
|
||
│ │
|
||
│ ┌─────────────────┐ ┌──────────────────────┐ │
|
||
│ │ │ │ Magpie 侧边栏 │ │
|
||
│ │ │ │ │ │
|
||
│ │ 编辑器 │ │ PR #123 │ │
|
||
│ │ │ │ ──────────────────── │ │
|
||
│ │ │ │ 审阅者1: 发现SQL注入 │ │
|
||
│ │ │ │ 审阅者2: 这里性能有问 │ │
|
||
│ │ │ │ 审阅者1: 同意，但安全 │ │
|
||
│ │ │ │ ... │ │
|
||
│ │ │ │ ──────────────────── │ │
|
||
│ │ │ │ 📋 总结 │ │
|
||
│ │ │ │ [导出 Markdown] │ │
|
||
│ └─────────────────┘ └──────────────────────┘ │
|
||
│ │
|
||
└─────────────────────────────────────────────────┘
|
||
```
|
||
|
||
**插件职责：**
|
||
- 命令面板：`Magpie: Review PR`，输入 PR 号
|
||
- 调用 CLI：`magpie review <pr> --format json`
|
||
- 展示结果：侧边栏实时流式显示辩论过程和总结
|
||
- 导出：一键保存为 markdown
|
||
|
||
**不做：**
|
||
- 不做配置 UI，配置文件编辑就行
|
||
- 不做复杂交互，保持简单
|
||
|
||
## 技术栈
|
||
|
||
- **语言**：TypeScript + Node.js
|
||
- **理由**：
|
||
- CLI 和 VSCode 插件都是 TypeScript，可共享代码
|
||
- npm 生态好，各 AI 提供商都有官方 SDK
|
||
- 用户群体（开发者）大概率已有 Node 环境
|
||
|
||
## 市场差异化
|
||
|
||
| 工具 | 描述 | 与 Magpie 差异 |
|
||
|------|------|----------------|
|
||
| PR-Agent (CodiumAI) | AI 代码审查 | 单 AI，无对抗 |
|
||
| CodeRabbit | AI PR 审查 | 单 AI，无对抗 |
|
||
| GitHub Copilot | PR review 功能 | 单 AI，无对抗 |
|
||
|
||
**Magpie 的独特价值**：多 AI 对抗式辩论，通过不同视角和互相挑战，发现单一 AI 可能遗漏的问题。
|
||
|
||
## 后续步骤
|
||
|
||
1. 初始化项目结构
|
||
2. 实现 CLI 核心：配置加载、AI 调用、辩论编排
|
||
3. 实现流式输出
|
||
4. 实现 VSCode 插件
|
||
5. 测试和迭代
|