# 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. 测试和迭代