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日志记录：环形缓冲区结构化日志记录
• 状态持久性：代理在重启后仍能存活
• 演出：连接池、基准实用程序
• 可视化：性能图表

______________________________________________________________________

代码文件摘要

入口点和模拟

SDK核心

SDK扩展

代理

测试（按类别划分）

______________________________________________________________________

数学基础

偶数/奇数博弈论

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

概率分析

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

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

结果矩阵

期望值

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

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

纳什均衡

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

• 选择概率为0.5的偶数
• 选择概率为0.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

玩家策略

快速模拟

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

python run_league.py

______________________________________________________________________

性能基准

______________________________________________________________________

结果

联盟活动日志

最终排名

冠军

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

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

______________________________________________________________________

示例游戏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 
 /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. 速率限制 -请求调节稳定性

许可证

教育用途的开源。