南京邮电大学掼蛋AI算法对抗平台的客户端实现，支持AI自动出牌决策、自我对弈、数据收集和平台信息监控。
- 开发符合南京邮电大学掼蛋AI平台的客户端
- 实现AI自动出牌决策
- 支持自我对弈和数据收集
- 可扩展的架构设计
- 平台动态信息监控
- 平台名称: 南京邮电大学掼蛋AI算法对抗平台
- 平台地址: https://gameai.njupt.edu.cn/gameaicompetition/gameGD/index.html
- 当前版本: v1006（内测中，可参与）
- 联系方式:
- 研究兴趣咨询: chenxg@njupt.edu.cn
- 问题反馈: wuguduofeng@gmail.com
- QQ: 519301156
- Python 3.8+
- Windows / Linux
- 网络连接（用于平台信息监控）
- 克隆项目
git clone https://gitee.com/Philsz/yifei-ai-gd.git
cd YiFeiAI-GD- 安装依赖
pip install -r requirements.txt- 配置设置
# 复制配置文件模板
cp config.yaml.example config.yaml
# 编辑配置文件
vim config.yaml- 运行程序
python main.pywebsockets/websocket-client- WebSocket通信requests/httpx- HTTP请求（信息监控）beautifulsoup4/lxml- HTML解析（信息监控）schedule/APScheduler- 定时任务（信息监控）pyyaml- 配置文件解析
所有涉及当前时间、实时时间的场景必须调用系统时间API，禁止使用硬编码时间。
from datetime import datetime
# 获取当前时间
current_time = datetime.now()
# 获取当前时间戳
timestamp = datetime.now().timestamp()
# 格式化当前时间
formatted_time = datetime.now().strftime('%Y-%m-%d %H:%M:%S')
# 判断是否在静默时段
def is_quiet_hours():
now = datetime.now() # 必须调用系统时间
hour = now.hour
return 0 <= hour < 6
# 计算下次检查时间
def schedule_next_check(interval):
next_time = datetime.now() + timedelta(seconds=interval) # 基于当前时间计算
return next_time# 禁止硬编码时间
current_time = "2025-01-01 12:00:00" # ❌ 错误
# 禁止使用固定时间戳
timestamp = 1704067200 # ❌ 错误
# 禁止在代码中写死时间
if hour == 12: # ❌ 错误，应该从系统时间获取- ✅ 日志时间戳：
datetime.now() - ✅ 信息抓取时间：
datetime.now() - ✅ 静默时段判断：
datetime.now().hour - ✅ 定时任务调度：基于
datetime.now()计算 - ✅ 数据记录时间：
datetime.now() - ✅ 文件命名时间戳：
datetime.now().strftime('%Y%m%d_%H%M%S') - ❌ 历史日期记录：可以使用固定日期（如"2025年10月5日"这样的具体历史时间）
- 严格遵循平台JSON格式要求
- 所有消息必须符合平台规范
- 消息格式验证必须通过
- 第1个和第3个连接的AI自动为一队
- 第2个和第4个连接的AI自动为一队
- 必须正确识别队友并配合
- 决策响应时间建议 < 1秒
- 避免超时导致判负
- 检查间隔 ≥ 6小时
- 每日 0:00-6:00 为静默时段，不进行检查
- 遵守网站使用条款，不造成服务器压力
- ✅ WebSocket通信（本地/局域网）
- ✅ 完整牌型识别（Single/Pair/Trips等）
- ✅ 牌型比较和压制判断
- ✅ AI决策引擎（策略评估、出牌决策、配合策略）
- ✅ 游戏状态管理
- ✅ 错误处理和自动重连
- ✅ 对局记录和数据收集
- ✅ 平台信息监控（自动抓取平台动态）
- ✅ 信息通知（控制台/日志/可选邮件）
- ✅ 日志系统
guandan_ai_client/
├── main.py # 主程序入口
├── config.yaml # 配置文件
├── requirements.txt # 依赖包
├── README.md # 说明文档（本文件）
│
├── docs/ # 文档目录
│ ├── 掼蛋AI客户端架构方案.md
│ ├── 掼蛋AI比赛参赛指南.md
│ └── 掼蛋AI相关比赛汇总.md
│
├── src/
│ ├── communication/ # 通信模块
│ ├── game_logic/ # 游戏逻辑模块
│ ├── decision/ # 决策引擎模块
│ ├── data/ # 数据收集模块
│ ├── monitor/ # 信息监控模块
│ └── utils/ # 工具模块
│
├── tests/ # 测试代码
├── data/ # 数据目录
│ ├── replays/ # 回放文件
│ └── platform_info/ # 平台信息存储
└── logs/ # 日志目录
详细结构说明请参考 架构方案文档
# config.yaml
platform:
name: "南京邮电大学掼蛋AI平台"
version: "v1006"
url: "https://gameai.njupt.edu.cn/gameaicompetition/gameGD/index.html"
websocket:
local_url: "ws://127.0.0.1:23456/game/{user_info}"
network_url: "ws://[局域网IP]:23456/game/{user_info}"
reconnect_interval: 5
heartbeat_interval: 30
timeout: 10
ai:
strategy_level: "medium" # basic/medium/advanced
cooperation_enabled: true
risk_tolerance: 0.5
max_decision_time: 1.0 # 最大决策时间（秒）
info_monitor:
enabled: true # 是否启用信息监控
check_interval: 21600 # 检查间隔（秒），默认6小时（≥6小时）
quiet_hours: # 静默时段，不进行检查
enabled: true
start: "00:00" # 静默开始时间（24小时制）
end: "06:00" # 静默结束时间（24小时制）- 详细配置说明请参考 架构方案文档 - 配置管理
- 启动客户端
python main.py-
连接平台
- 本地测试：使用
ws://127.0.0.1:23456/game/{user_info} - 局域网对战：使用
ws://[局域网IP]:23456/game/{user_info}
- 本地测试：使用
-
查看日志
- 日志文件：
logs/ai_client.log - 控制台输出：根据配置显示
- 日志文件：
信息监控功能会自动在后台运行，定期检查平台动态：
- 检查频率: 每6小时（≥6小时）
- 静默时段: 每日 0:00-6:00 不进行检查
- 通知方式: 控制台输出、日志记录
- 信息存储:
data/platform_info/目录
from src.monitor.fetcher import PlatformInfoFetcher
fetcher = PlatformInfoFetcher()
updates = fetcher.check_updates()- 遵循 PEP 8 Python代码规范
- 使用类型提示（Type Hints）
- 编写清晰的注释和文档字符串
- 文档尽量简洁：避免一次性生成过长文档导致超时
- 先列提纲再填充：先创建文档框架和提纲并保存，再逐步填充内容
- 定期保存：每3分钟保存一次，避免长时间编辑导致内容丢失
- 遵守时间规范：文档中的时间信息应使用系统时间API，禁止硬编码时间
from datetime import datetime, timedelta
# ✅ 正确：使用系统时间
current_time = datetime.now()
timestamp = datetime.now().timestamp()
# ✅ 正确：基于当前时间计算
next_check = datetime.now() + timedelta(hours=6)
# ✅ 正确：判断当前时间
if datetime.now().hour < 6:
# 静默时段处理
pass
# ❌ 错误：硬编码时间
fixed_time = "2025-01-01 12:00:00" # 禁止
# ❌ 错误：使用固定时间戳
fixed_timestamp = 1704067200 # 禁止from datetime import datetime, timedelta
def get_current_time() -> datetime:
"""获取当前系统时间"""
return datetime.now()
def get_current_timestamp() -> float:
"""获取当前时间戳"""
return datetime.now().timestamp()
def format_time(dt: datetime = None) -> str:
"""格式化时间"""
if dt is None:
dt = datetime.now() # 默认使用当前时间
return dt.strftime('%Y-%m-%d %H:%M:%S')
def is_quiet_hours(current_time: datetime = None) -> bool:
"""判断是否在静默时段（0:00-6:00）"""
if current_time is None:
current_time = datetime.now() # 必须调用系统时间
hour = current_time.hour
return 0 <= hour < 6- 编写单元测试
- 进行集成测试
- 性能测试（响应时间<1秒）
- 代码必须通过所有测试
- 遵循时间处理规则
- 完整的日志记录
- 清晰的提交信息
-
安装Python
- Python 3.8 或更高版本
- 推荐使用虚拟环境
-
安装依赖
pip install -r requirements.txt- 配置开发环境
- 配置IDE（推荐VS Code或PyCharm）
- 配置代码格式化工具
- 配置代码检查工具
-
阅读文档
- 阅读 架构方案文档
- 理解游戏规则和JSON格式
- 了解平台要求
-
开发功能
- 按照架构设计实现各模块
- 遵循开发规范
- 编写测试代码
-
测试验证
- 本地测试
- 完整对局测试
- 稳定性测试
Q: 如何获取当前时间？
A: 必须使用 datetime.now() 获取系统时间，禁止硬编码。
Q: 信息监控的检查频率是多少？ A: 默认6小时（≥6小时），且每日0:00-6:00为静默时段不检查。
Q: 如何判断是否在静默时段？
A: 使用 datetime.now().hour 获取当前小时，判断是否在0-6之间。
Q: 组队规则是什么？ A: 第1、3个连接为一队，第2、4个连接为一队。
- 平台网站: https://gameai.njupt.edu.cn/gameaicompetition/gameGD/index.html
- 离线平台: 需从平台网站下载
- 使用说明书: 对应版本v1006
- 江苏省体育局掼蛋竞赛简易规则
- v1006版本特殊规则（抗贡规则调整）
- WebSocket协议文档
- JSON格式规范
- Python官方文档
本项目采用 MIT 许可证。
欢迎提交Issue和Pull Request！
- Fork 本项目: https://gitee.com/Philsz/yifei-ai-gd
- 创建特性分支 (
git checkout -b feature/AmazingFeature) - 提交更改 (
git commit -m 'Add some AmazingFeature') - 推送到分支 (
git push origin feature/AmazingFeature) - 在Gitee上开启 Pull Request
- Gitee仓库: https://gitee.com/Philsz/yifei-ai-gd
- 详细说明: 查看 REMOTE_REPO_INFO.md
注意: 提交代码前请确保：
- ✅ 遵循时间处理规则（必须调用系统时间API）
- ✅ 代码通过所有测试
- ✅ 遵循代码规范
- ✅ 更新相关文档
- 研究兴趣咨询: chenxg@njupt.edu.cn
- 问题反馈: wuguduofeng@gmail.com
- QQ: 519301156
- 时间处理: 所有涉及当前时间的场景必须调用系统时间API（
datetime.now()），禁止硬编码时间 - JSON格式: 严格按照平台JSON格式要求
- 组队规则: 正确识别队友（1-3一队，2-4一队）
- 响应时间: 决策响应时间建议<1秒
- 信息监控: 检查间隔≥6小时，静默时段（0:00-6:00）不检查
- 先实现基础功能，确保能正常连接和通信
- 逐步优化，先实现基本策略，再逐步优化
- 充分测试，本地完整测试后再提交
- 保持联系，遇到问题及时联系主办方
最后更新: 2025年1月
文档版本: v1.0
平台版本: v1006