GitHub Debate System

GitHub辩论系统（A2A×MCP）

这是一个结合了Agent to Agent（A2A）和Model Context Protocol（MCP）的、以GitHub PR为主题的AI辩论系统。

概要

这个项目两个AI代理（代码评估AI与文档一致性AI）将分析实际的GitHub拉取请求，并就是否合并展开辩论。由评判AI最终判定胜负。

特点

• MCP（模型上下文协议） 与GitHub API的协作
• A2A（代理对代理） 基于此的多个代理的协同操作
• 基于真实GitHub PR数据的有理有据的讨论
• 三轮制辩论（开场陈词→反驳→终局陈词）
• 基于JSON Schema的评判打分

架构

┌─────────────────────────────────────┐
│  Python CLI (debate_github.py)      │
│  - ReviewerBot (コード評価)         │
│  - DocGuard (ドキュメント整合性)     │
│  - ArbiterJudge (審判)              │
└──────────────┬──────────────────────┘
               │ stdio
┌──────────────▼──────────────────────┐
│  GitHub MCP Server (Node.js)        │
│  - get_pull_request                 │
│  - get_pull_request_files           │
│  - get_file_content                 │
└──────────────┬──────────────────────┘
               │ GitHub API
┌──────────────▼──────────────────────┐
│         GitHub.com                   │
└─────────────────────────────────────┘

设置

1. 安装依赖包

Node.js 包

npm install

Python包

pip install -r requirements.txt

2. 设置环境变量

.env.example 进行复制 .env 制作：

cp .env.example .env

.env 编辑文件，进行以下设置：

# OpenAI API Key
OPENAI_API_KEY=sk-...

# GitHub Personal Access Token
# 必要な権限: repo (read-only)
GITHUB_TOKEN=ghp_...

# Optional: GPT Model
GPT_MODEL=gpt-4o-mini

获取GitHub Token的方法

1. 访问 https://github.com/settings/tokens
2. 点击“生成新令牌（经典）”
3. 权限： repo 仅选择（只读）
4. 复制代币 .env 粘贴到

使用方法

基本使用方法

python3 debate_github.py --repo openai/openai-python --pr 1724

选项

python3 debate_github.py \
  --repo OWNER/REPO \
  --pr PR_NUMBER \
  --rounds 3 \
  --model gpt-4o-mini \
  --log-dir ./logs

• --repo仓库（owner/name 格式）
• --pr拉取请求编号
• --rounds辩论轮数（默认：3）
• --model所使用的GPT模型（默认：gpt-4o-mini）
• --log-dir日志保存目录（默认：./logs）

辩论的流程

第一轮：开场陈述（初步主张）

• 评论者机器人从代码质量、测试和技术合理性的角度主张合并
• DocGuard（可译为“文档卫士”或根据具体语境调整为更贴切的名称）鉴于文档一致性问题以及破坏性变更通知不足，主张暂不合并

第二轮：反驳

• 各代理对对方主张进行反驳

第三轮：Final（最终主张）

• 各代理机构应强化自身立场并阐明结论

裁判的判定

• 评估逻辑性、依据的恰当性、反驳的准确性、清晰度以及实务上的合理性
• 以JSON格式输出评分和获胜者

项目结构

github-debate-system/
├── README.md                 # このファイル
├── requirements.txt          # Python 依存パッケージ
├── package.json              # Node.js 依存パッケージ
├── .env.example             # 環境変数テンプレート
├── .gitignore               # Git 除外設定
├── mcp-server.js            # GitHub MCP Server
├── debate_github.py         # メイン CLI スクリプト
├── mcp/
│   ├── __init__.py
│   └── client.py           # Python MCP Client
├── agents/
│   ├── __init__.py
│   ├── reviewer.py         # ReviewerBot
│   ├── docguard.py         # DocGuard
│   └── judge.py            # ArbiterJudge
├── prompts/
│   ├── reviewer_system.txt # ReviewerBot のシステムプロンプト
│   ├── docguard_system.txt # DocGuard のシステムプロンプト
│   └── judge_system.txt    # Judge のシステムプロンプト
└── logs/                    # ディベートログ保存先

关于MCP（模型上下文协议）

MCP是用于使LLM应用程序能够与外部数据源和工具安全协作的标准协议。

该项目中MCP的角色

1. GitHub MCP 服务器（Node.js）

- 提供对GitHub API的访问 - 通过stdio与Python客户端通信 - 提供工具： - github.get_pull_request获取PR信息和diff - github.get_pull_request_files获取变更文件列表 - github.get_file_content获取文件内容

1. Python MCP 客户端

- 与MCP服务器的接口 - 通过JSON-RPC 2.0协议进行通信

MCP的优势

• 标准化可通过统一的API访问不同的数据源
• 安全在服务器端管理认证信息
• 可再利用性一旦实现，即可在其他项目中使用
• 可扩展性可轻松添加新工具

关于A2A（代理对代理）

A2A是一种方法，即多个AI代理相互通信、协同解决问题。

该项目中A2A的实施

1. 评论机器人 和 DocGuard（可译为“文档卫士”或根据具体语境调整为更贴切的名称） 独立思考
2. 在每一轮中参照对方的主张进行反驳
3. 仲裁裁判员 评价双方的论点

A2A的优点

• 多角度分析从不同视角的评价
• 讨论的深入通过反驳使论点明确化
• 品质提升通过相互核对提高精度

故障排除

GitHub Token 错误

Error: GITHUB_TOKEN environment variable is not set

→ .env 请在文件中设置GitHub Token

OpenAI API错误

Error code: 429 - You exceeded your current quota

请确认OpenAI API的使用量限制

MCP服务器启动错误

Server error: ...

请确认Node.js的版本（建议使用v18以上）

许可证

麻省理工学院（MIT）

参考资料

• 模型上下文协议
• OpenAI API 文档

-