AI导哈

奇偶游戏代理联盟系统

一个分布式多代理系统，实现竞争性的奇偶游戏联盟，包含联盟管理器、裁判和玩家三种代理类型，通过league.v2协议进行通信。

  • by hadarwayn
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 hadarwayn/L25-Even-Odd-AI-Agent-League-System

使用说明

偶数/奇数AI代理联盟系统

一个分布式多代理系统，实现了一个有竞争力的偶数/奇数游戏联盟。该系统包括三种代理类型（联赛经理、裁判、球员），通过 league.v2 通过JSON-RPC 2.0 HTTP传输使用MCP（模型上下文协议）的协议。

系统架构

┌─────────────────────────────────────────────────────────┐
│                  LEAGUE MANAGEMENT LAYER                 │
│  ┌─────────────────────────────────────────────────┐   │
│  │           League Manager (Port 8000)             │   │
│  │  - Player/Referee registration                   │   │
│  │  - Round-robin scheduling                        │   │
│  │  - Standings calculation                         │   │
│  └─────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────┘
                           ↕
┌─────────────────────────────────────────────────────────┐
│                  GAME REFEREEING LAYER                   │
│  ┌──────────────────┐    ┌──────────────────┐          │
│  │  Referee REF01   │    │  Referee REF02   │          │
│  │  (Port 8001)     │    │  (Port 8002)     │          │
│  └──────────────────┘    └──────────────────┘          │
└─────────────────────────────────────────────────────────┘
                           ↕
┌─────────────────────────────────────────────────────────┐
│                    PLAYER LAYER                          │
│  ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐          │
│  │  P01   │ │  P02   │ │  P03   │ │  P04   │          │
│  │ :8101  │ │ :8102  │ │ :8103  │ │ :8104  │          │
│  └────────┘ └────────┘ └────────┘ └────────┘          │
└─────────────────────────────────────────────────────────┘

特性

  • 多代理架构：联赛经理、裁判和球员
  • 协议遵从：已满 league.v2 具有18种消息类型的协议
  • 可插拔策略：随机、确定性、交替、自适应
  • 共享SDK：常见组件 SHARED/league_sdk/
  • 安全：身份验证令牌验证、速率限制、输入净化
  • 韧性：断路器，以指数回退重试
  • JSONL日志记录：环形缓冲区结构化日志记录
  • 状态持久性：代理在重启后仍能存活
  • 演出：连接池、基准实用程序
  • 可视化：性能图表

代码文件摘要

入口点和模拟

文件 描述 行
run_league.py 联赛模拟入口点 52
simulation/__init__.py 模拟包导出 24
simulation/player.py 模拟玩家代理 70
simulation/referee.py 模拟裁判代理人 48
simulation/league.py 联盟编排 148
simulation/output.py 输出格式 65

SDK核心

文件 描述 行
SHARED/league_sdk/mcp_server.py FastAPI MCP服务器 148
SHARED/league_sdk/mcp_client.py 带断路器的HTTP客户端 148
SHARED/league_sdk/schemas.py 18种消息类型型号 148
SHARED/league_sdk/schemas_base.py 基本模式和枚举 95
SHARED/league_sdk/auth.py 速率限制和身份验证 148
SHARED/league_sdk/circuit_breaker.py 断路器型式 145
SHARED/league_sdk/helpers.py 实用功能 109
SHARED/league_sdk/logger.py JSONL结构化记录器 113
SHARED/league_sdk/game_rules/even_odd.py 游戏逻辑 95

SDK扩展

文件 描述 行
SHARED/league_sdk/ring_buffer_logger.py 环形缓冲区日志记录 142
SHARED/league_sdk/state_persistence.py 玩家状态持久性 140
SHARED/league_sdk/benchmarks.py 绩效基准 138
SHARED/league_sdk/visualization.py 结果可视化 130
SHARED/league_sdk/error_handlers.py 错误恢复处理程序 135

代理

文件 描述 行
agents/league_manager/main.py 联赛经理经纪人 87
agents/league_manager/handlers.py LM消息处理程序 145
agents/referee_template/main.py 裁判代理模板 75
agents/referee_template/handlers.py 裁判处理程序 130
agents/player_template/main.py 玩家代理模板 70
agents/player_template/handlers.py 玩家处理程序 125

测试（按类别划分）

文件 描述 行
tests/test_timestamp.py UTC时间戳验证 35
tests/test_enums.py 枚举验证测试 62
tests/test_helpers.py 辅助功能测试 35
tests/test_messages.py 消息模型测试 95
tests/test_game_logic.py 游戏逻辑测试 85
tests/test_points.py 点数计算测试 30
tests/test_sender.py 发件人解析测试 55

数学基础

偶数/奇数博弈论

偶数/奇数游戏是 对称零和博弈 一旦随机数被提取，结果就具有确定性。

概率分析

给定一个从1-10中随机抽取的数字：

  • P（偶数） =5/10=0.5（数字：2、4、6、8、10）
  • P（奇数） =5/10=0.5（数字：1、3、5、7、9）

结果矩阵

对手：偶数 对手：奇数
你：甚至 平局（50%），赢/输（50%） 偶数赢（50%）
你：奇怪 偶数输（50%），奇数赢（50%） 平局（50%）、输赢（50%）

期望值

对于选择概率p为偶数的任何混合策略：

E[points] = 3 × P(win) + 1 × P(draw) + 0 × P(loss)

纳什均衡

这 唯一纳什均衡 是随机策略：

  • 选择概率为0.5的偶数
  • 选择概率为0.5的奇数

这保证了每场比赛对任何对手策略的预期值为1.5分。

战略分析

策略 vs随机 vs偶数 vs奇数 vs自适应
随机 1.5 1.5 1.5 1.5
检测偶数 1.5 1.5 1.5 可变
检测赔率 1.5 1.5 1.5 可变
自适应 1.5 >1.5 >1.5 可变

这 适应战略 可以利用可预测的对手，但在随机游戏中表现相同。

虚拟环境设置（必需）

此项目使用 紫外线 用于快速、可靠的包管理。

步骤1：安装UV（如果未安装）

Linux/Mac/WSL：

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows PowerShell：

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

步骤2：创建和激活虚拟环境

cd L25
uv venv

WSL/Linux/Mac：

source .venv/bin/activate

Windows PowerShell：

.venv\Scripts\activate

步骤3：安装依赖项

uv pip install -r requirements.txt

步骤4：验证安装

python --version
# Should show Python 3.10+

python -c "import fastapi; print(f'FastAPI: {fastapi.__version__}')"

运行全联盟

按以下顺序在单独的终端中启动代理：

1号航站楼：联赛经理

cd agents/league_manager && python main.py

终端2-3：裁判

cd agents/referee_REF01 && python main.py
cd agents/referee_REF02 && python main.py

终端4-7：玩家

cd agents/player_P01 && python main.py
cd agents/player_P02 && python main.py
cd agents/player_P03 && python main.py
cd agents/player_P04 && python main.py

玩家策略

玩家 策略 描述
P01 随机 等概率偶数/奇数
P02 确定性偶数 总是选择偶数
P03 交替 偶数/奇数之间的切换
P04 自适应 从对手历史中学习

快速模拟

用一个命令运行一个完整的联赛模拟：

python run_league.py

性能基准

操作 平均时间 最小值 最大值 内存
注册 8ms 5ms 15ms 1.2MB
比赛执行时间 12ms 8ms 25ms 1.5MB
奇偶校验选择 2ms 1ms 5ms 0.5MB
展位计算 3ms 2ms 8ms 0.8MB
全联盟（6场比赛） 150ms 100ms 250ms 8MB

结果

联盟活动日志

时间 事件 详细信息
11:04:29 参考_已注册 REF01已注册
11:04:29 参考_已注册 REF02已注册
11:04:29 玩家_已注册 P01（AlphaBot）已注册
11:04:29 玩家_已注册 P02（BetaBot）已注册
11:04:29 玩家_已注册 P03（GammaBot）已注册
11:04:29 玩家_已注册 P04（DeltaBot）已注册
11:04:29 日程生成 3轮，6场比赛
11:04:29 联赛开始
11:04:29 第一轮开始
11:04:29 材料已完成 R1M1:P01与P02->图纸
11:04:29 材料已完成 R1M2:P03与P04->图纸
11:04:29 第一轮比赛已完成 第二轮比赛已结束
11:04:29 第二轮开始
11:04:29 材料已完成 R2M1:P01与P03->图纸
11:04:29 材料已完成 R2M2:P02与P04->图纸
11:04:29 第二轮比赛已完成
11:04:29 第三轮开始
11:04:29 已完成 R3M1:P01与P04->P04
11:04:29 材料已完成 R3M2:P02与P03->图纸
11:04:29 第三轮比赛已完成
11:04:29 联赛结束 联赛结束

最终排名

排名 玩家 策略 P W D L 得分
1 P04（DeltaBot） 自适应 3 1 2 0 5
2 P02（BetaBot） 确定性_偶数 3 0 3 0 3
3 P03（GammaBot） 交替 3 0 3 0_3
4 P01（AlphaBot） 随机 3 0 2 1 2

冠军

P04（德尔塔机器人） -适应性策略

  • 记录：1W-2D-0L（5分）
  • 通过学习对手模式获得的自适应策略！

示例游戏2：确定性策略获胜

第二轮联赛展示了结果如何根据随机抽签而变化：

比赛历史

比赛 回合 球员A 选择 对战 球员B 选择 平局# 获胜者
R1M1 1 P01 偶数 vs P02 偶数 6 DRAW
R1M2 1 P03 偶数 vs P04 偶数 9 DRAW
R2M1 2 P01 奇数 vs P03 奇数 7 DRAW
R2M2 2 P02 偶数 vs P04 奇数 2 P02
R3M1 3 P01 奇数 vs P04 奇数 1 DRAW
R3M2 3 P02 偶数 vs P03 偶数 2 DRAW

最终排名

排名 玩家 策略 P W D L 得分
1 P02（BetaBot） 确定性_偶数 3 1 2 0 5
2 P01（AlphaBot） 随机 3 0 3 0 3
3 P03（GammaBot） 交替 3 0 3 0_3
4 P04（DeltaBot） 自适应 3 0 2 1 2

冠军

P02（BetaBot） -确定性均衡策略

  • 记录：1W-2D-0L（5分）
  • 性能：总计0.27ms，0.04ms/批
  • 当适应性对手在偶数平局中选择奇数时，确定性偶数策略获胜！

分析

这个游戏展示了如何 同样的策略会产生不同的结果 基于随机抽取：

  • 游戏1：通过利用模式赢得的适应性策略（P04）
  • 游戏2：当P04的自适应选择错误时，确定性偶数（P02）获胜

这说明了 混合策略纳什均衡 -没有一种纯粹的策略在所有游戏中都占主导地位。

故障排除

“找不到模块”错误

# Ensure virtual environment is activated
source .venv/bin/activate  # Linux/Mac/WSL
.venv\Scripts\activate     # Windows

# Verify Python path
which python  # Should point to .venv/bin/python

连接被拒绝

# Start agents in order: Manager → Referees → Players
# Check if agent is running
curl http://localhost:8000/health

端口已在使用中

# Find process using port (Linux/Mac)
lsof -i :8000

# Find process using port (Windows)
netstat -ano | findstr :8000

# Kill process (Windows)
taskkill /PID <pid> /F

注册超时

# Verify League Manager is responding
curl http://localhost:8000/health

# Check firewall settings
# Ensure no VPN interfering with localhost

WSL路径问题

# Use Linux paths in WSL, not Windows paths
# Wrong: /mnt/c/Users/...
# Right: ~/projects/L25

安装后未找到紫外线

# Add to PATH (add to ~/.bashrc or ~/.zshrc)
export PATH="$HOME/.cargo/bin:$PATH"
source ~/.bashrc  # or source ~/.zshrc

测试中的导入错误

# Ensure SHARED is in PYTHONPATH
export PYTHONPATH="${PYTHONPATH}:$(pwd)/SHARED"
pytest tests/ -v

代理在启动时崩溃

# Check log files in SHARED/logs/{agent_type}/
cat SHARED/logs/players/P01.log.jsonl | tail -20

# Verify JSON config files are valid
python -c "import json; json.load(open('SHARED/config/agents.json'))"

未显示匹配结果

# Verify all agents registered successfully
# Check League Manager logs for registration events
# Ensure referees received match assignments

API 文档

看 docs/API.md文件 以获取完整的API参考。

运行测试

# Run all tests
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=SHARED/league_sdk

# Run specific test
pytest tests/test_protocol.py -v

学习目标

该项目展示了：

  1. 多智能体系统 -自主代理之间的协调
  2. MCP协议 -基于HTTP的JSON-RPC 2.0实现
  3. 分布式体系结构 -三层体系设计
  4. 协议遵从 -严格遵守规范
  5. 策略模式 -可插拔决策算法
  6. 存储库模式 -干净的数据访问抽象
  7. 断路器 -容错模式
  8. 速率限制 -请求调节稳定性

许可证

教育用途的开源。

相关 MCP