autowzry-agent 项目架构设计文档¶
日期: 2025-01-12 版本: v1.0 状态: 架构设计阶段
项目目标¶
基于强化学习 (RL) 技术，构建一个用于 MOBA 游戏（王者荣耀）策略的自主决策 Agent。
核心技术栈¶
- 基础库: PyTorch、OpenCV、NumPy、HDF5
- 游戏接口: autowzry / autowzry-lite (ADB连接、截图、操作)
- 算法: DQN (Deep Q-Network)
- 数据格式: HDF5 (episode存储)
模块层次架构¶
├── Core Layer (核心层)
│ ├── Agent (主控制器 - 模式切换)
│ ├── Model (神经网络模型)
│ ├── Trainer (DQN训练逻辑)
│ └── Policy (策略选择器)
│
├── Learning Layer (学习层)
│ ├── ExperienceCollector (经验收集 + episode保存)
│ ├── ReplayBuffer (多文件加载 + 随机采样)
│ └── Dataset (PyTorch Dataset封装)
│
├── Environment Layer (环境交互层)
│ ├── Compatibility (设备接口封装)
│ ├── ActionSpace (动作空间定义)
│ └── RewardEvaluator (感知+奖励统一模块)
│
└── Utility Layer (工具层)
├── ImageProcessing (图像预处理)
├── ActionInference (动作推断)
└── Logger (日志工具)
数据流全景图¶
数据收集阶段 (Collecting Phase)¶
[游戏/视频] → ExperienceCollector → 临时Buffer
↓
定期保存到磁盘
↓
episode_001.h5
episode_002.h5
episode_xxx.h5
数据整合阶段 (Consolidation Phase)¶
[多个episode文件] → ReplayBuffer.load_multiple_files()
↓
统一的大型Buffer (内存/磁盘映射)
训练阶段 (Training Phase)¶
ReplayBuffer → random_sample() → ExperienceDataset
↓
PyTorch DataLoader
↓
Trainer.train()
关键设计决策¶
1. 三种运行模式¶
- 观战模式 (spectate): 读取视频/观战，通过图像差分推断action
- 对战模式 (battle): 模型实时推理，控制英雄对战
- 离线模式 (offline): 加载已保存的episode进行训练
2. 感知与奖励合并¶
reward_evaluator.py统一管理状态识别和奖励计算- 支持可配置的颗粒度 (初期: 生/死/击杀)
- 便于扩展新的感知项 (血量/位置/金币等)
- 设计理由: 不同的感知结果直接用于计算奖励，合并在同一文件中，修改新的感知时可以同步增加奖励分数
3. 配置管理¶
config.py: 统一的配置管理器（加载YAML、解析命令行、生成默认配置）default_config.yaml: YAML配置文件- 支持命令行参数覆盖
- 包含超参数、路径、环境设置
4. 策略解耦¶
- Policy模块独立于Model
- 支持 ε-greedy、Softmax 等多种探索策略
- 便于调整探索/利用平衡
5. 脚本分离¶
collect.py: 专注数据收集train.py: 专注训练evaluate.py: 专注评估main.py: 轻量级路由入口（避免main.py过大）
核心模块最小功能集定义¶
Agent Module (agent.py)¶
- 模式切换 (collect/train/evaluate)
- 流程编排
- checkpoint管理
Model Module (model.py)¶
- SimpleConvNet (2-3层卷积 + 全连接)
- forward推理
- save/load
Trainer Module (trainer.py)¶
- DQN loss计算 (Q-learning)
- 梯度优化
- target网络定期更新
Policy Module (policy.py)¶
- ε-greedy策略
- Softmax策略
- Greedy策略
- 探索率衰减
ExperienceCollector (experience_collector.py)¶
- collect_one_step() - 收集单步经验
- collect_episode() - 收集完整一局
- save_episode() - 保存为HDF5
- collect_and_save_multiple_episodes() - 批量收集
ReplayBuffer (replay_buffer.py)¶
- push() - 添加单条经验
- load_episode_file() - 加载单个episode
- load_from_directory() - 加载多个episode文件
- sample() - 随机采样batch
- save_consolidated() - 保存整合后的buffer
- get_statistics() - 统计信息
Dataset (dataset.py)¶
- PyTorch Dataset封装
- 配合DataLoader使用
- 高效的批量数据加载
RewardEvaluator (reward_evaluator.py)¶
- detect_events() - OpenCV状态识别（生/死/击杀/助攻等）
- compute_reward() - 根据状态变化计算奖励
- 可配置的enabled_detections/enabled_rewards
- 奖励字典管理
Compatibility Module (compatibility.py)¶
- init_device() - 初始化autowzry/autowzry-lite
- capture_screen() - 截图并预处理
- execute_action() - 执行游戏操作
- is_battle_running() - 判断对战状态
- enter_battle() - 进入对战 (autowzry专用)
ActionSpace (action_space.py)¶
- define_action_space() - 定义可用动作
- encode_action() - 命令 → index
- decode_action() - index → 具体命令
- get_dim() - 返回动作维度
Config Module (config.py)¶
- from_yaml() - 从YAML文件加载配置
- from_args() - 从命令行参数构建配置
- save_yaml() - 保存配置到YAML
- generate_default_config() - 生成默认配置
- create_argument_parser() - 创建命令行解析器（含--help）
完整的项目结构 (最终版)¶
autowzry-agent/
├── config/
│ ├── __init__.py
│ ├── config.py # 配置管理器 (加载YAML、解析命令行、生成默认配置)
│ └── default_config.yaml # 默认配置文件示例
│
├── core/
│ ├── __init__.py
│ ├── agent.py # Agent主控制器 (模式切换、流程编排)
│ ├── model.py # 模型定义 (BaseModel + SimpleConvNet)
│ ├── trainer.py # DQN训练器 (loss计算、优化、target网络更新)
│ └── policy.py # 策略选择器 (ε-greedy、Softmax等)
│
├── environment/
│ ├── __init__.py
│ ├── compatibility.py # 兼容模块 (autowzry/autowzry-lite接口封装、截图、动作执行)
│ ├── action_space.py # 动作空间定义 (动作编码/解码、维度定义)
│ └── reward_evaluator.py # 感知与奖励模块 (OpenCV状态识别 + 奖励计算，统一管理)
│
├── data/
│ ├── __init__.py
│ ├── experience_collector.py # 经验收集器 (collect_one_step、collect_episode、save_episode)
│ ├── replay_buffer.py # 经验缓冲区 (多文件加载、随机采样、统计信息)
│ └── dataset.py # PyTorch Dataset封装 (配合DataLoader使用)
│
├── utils/
│ ├── __init__.py
│ ├── image_processing.py # 图像预处理 (resize、灰度化、帧堆叠)
│ ├── action_inference.py # 动作推断 (从图像差分推断执行的动作)
│ └── logger.py # 日志工具 (TensorBoard、文件日志)
│
├── scripts/
│ ├── __init__.py
│ ├── collect.py # 数据收集脚本 (观战/对战/离线模式)
│ ├── train.py # 训练脚本 (离线训练)
│ ├── evaluate.py # 评估脚本 (模型性能测试)
│ └── generate_config.py # 生成默认配置文件
│
├── data/ # 数据目录 (gitignore)
│ └── episodes/ # episode文件存储
│ ├── episode_20250112_143022_1234steps.h5
│ └── ...
│
├── models/ # 模型存储 (gitignore)
│ └── checkpoints/
│
├── logs/ # 日志目录 (gitignore)
│
├── templates/ # OpenCV模板图像 (用于状态识别)
│ ├── death_icon.png
│ └── ...
│
├── main.py # 轻量级入口 (路由到各个scripts)
├── requirements.txt
├── .gitignore
└── README.md
开发阶段规划¶
阶段1: 基础框架 (优先级最高)¶
- Config模块 + 配置文件生成
- Compatibility模块 (接入autowzry-lite)
- ActionSpace定义
- 简单的ImageProcessing工具
阶段2: 数据收集¶
- ExperienceCollector (观战模式优先)
- ActionInference (图像差分推断动作)
- RewardEvaluator (初期只识别生/死/击杀)
- episode保存功能
阶段3: 训练流程¶
- ReplayBuffer (加载多文件)
- Dataset + DataLoader
- SimpleConvNet模型
- DQN Trainer
- train.py脚本
阶段4: 在线学习¶
- Policy模块 (ε-greedy)
- ExperienceCollector对战模式
- 边玩边学逻辑
阶段5: 优化与扩展¶
- 复杂模型
- 更细粒度的状态识别
- Logger和可视化
- 评估脚本
使用示例工作流¶
# 1. 生成配置文件
python main.py config --output config/my_config.yaml
# 2. 编辑配置 (修改超参数等)
# vim config/my_config.yaml
# 3. 观战模式收集数据
python main.py collect --mode spectate --num-episodes 20
# 4. 离线训练
python main.py train --config config/my_config.yaml --epochs 100
# 5. 对战模式评估
python main.py evaluate --mode battle --model-path models/best_model.pth
# 或者直接使用scripts
python scripts/collect.py --mode spectate --num-episodes 10
python scripts/train.py --batch-size 64 --epochs 50
python scripts/evaluate.py --model-path models/final_model.pth
待明确的技术细节（后续讨论）¶
1. 图像预处理方案¶
- 输入分辨率 (84x84?)
- 帧堆叠数量 (4帧?)
- 灰度化 or RGB?
2. 动作空间设计¶
- 移动方向离散化 (8方向? 16方向?)
- 技能映射方案
- 组合动作处理
3. 状态识别实现¶
- OpenCV模板匹配 vs OCR
- 关键UI元素位置
- 鲁棒性处理
4. 奖励函数细节¶
- 具体奖励数值
- 时间衰减
- 奖励塑形策略
5. 训练稳定性¶
- Experience Replay采样策略
- Target网络更新频率
- 学习率调度
重要的架构原则¶
- 高内聚、低耦合: 每个模块职责单一明确
- 可配置性: 通过配置文件和命令行参数灵活控制
- 可扩展性: 支持新的感知项、动作、模型的便捷添加
- 模块化: 便于其他用户移植到不同游戏或切换不同模型
- 数据驱动: 数据收集、存储、加载流程清晰高效
下一步计划¶
下次讨论可以从以下任一方向继续： - 具体模块的接口定义 - 动作空间和状态表示的详细设计 - 开始实现第一个模块的代码 - 讨论数据预处理和奖励函数的细节
文档结束