Game_Tars - 游戏测试智能体系统

April 17, 2026 · View on GitHub

🎮 Game_Tars 是一个基于大模型的智能游戏测试系统，能够自动化执行游戏测试任务，通过视觉观察、AI决策和GUI自动化来完成复杂的游戏测试场景。

🌟 核心功能

🤖 智能游戏分析: 通过截图理解游戏状态和UI元素
🎯 自动化测试: 基于AI决策执行游戏操作
📊 多模态交互: 结合图像和文本的智能决策
🛠️ GUI自动化: 支持点击、输入、快捷键等操作
📈 测试报告: 生成详细的测试结果和分析
🔧 模块化设计: 易于扩展和维护

🏗️ 系统架构

Game_Tars/
├── llm_interface.py       # LLM接口模块 - OpenAI API集成
├── visual_observer.py     # 视觉观察模块 - 屏幕截图和图像分析
├── action_executor.py     # 动作执行模块 - GUI自动化操作
├── game_test_prompts.py   # 提示模板模块 - 游戏测试提示词
├── game_test_agent.py     # 主测试智能体 - 核心协调器
├── action_parser.py       # 动作解析器 - 解析AI输出为可执行操作
├── prompt_template.py     # 通用提示模板
└── openai_config.json     # OpenAI配置文件

📦 安装和配置

1. 环境要求

Python 3.8+
OpenAI API访问权限

2. 安装依赖

pip install openai pillow pyautogui opencv-python psutil requests

3. 配置OpenAI API

编辑 openai_config.json 文件：

{
  "api_key": "your-api-key-here",
  "base_url": "https://api.openai.com/v1",
  "model": "gpt-4-vision-preview",
  "quick_model": "gpt-4",
  "max_tokens": 4000,
  "temperature": 0.7
}

🚀 快速开始

基本使用示例

from game_test_agent import GameTestAgent
import time

# 创建游戏测试智能体
agent = GameTestAgent()

# 启动游戏（可选）
game_path = "/path/to/your/game.exe"
agent.launch_game(game_path)

# 执行完整的游戏测试
test_description = "测试贪吃蛇游戏的基本功能：移动、吃食物、碰撞检测"
results = agent.run_full_game_test(
    test_description=test_description,
    max_steps=10,
    timeout=300
)

# 查看测试结果
print(f"测试完成: {results['success']}")
print(f"执行步骤: {results['steps_completed']}")
print(f"测试报告: {results['report']}")

YummySnake游戏测试示例

from test_yummy_snake import YummySnakeTest

# 创建测试实例
test = YummySnakeTest()

# 运行模拟测试（不调用真实API）
test.run_mock_test()

# 运行真实测试（需要配置API）
# test.run_real_test()

# 运行手动步骤测试
test.run_manual_steps_test()

📚 API文档

GameTestAgent 类

核心方法

class GameTestAgent:
    def __init__(self, config_path: str = "openai_config.json")
    
    def launch_game(self, game_path: str) -> bool
        """启动游戏应用"""
    
    def analyze_game_state(self, screenshot_path: str = None) -> dict
        """分析当前游戏状态"""
    
    def generate_test_strategy(self, test_description: str, game_state: dict) -> dict
        """生成测试策略"""
    
    def execute_test_step(self, strategy: dict, step_index: int) -> dict
        """执行单个测试步骤"""
    
    def evaluate_test_result(self, action_result: dict, expected_outcome: str) -> dict
        """评估测试结果"""
    
    def run_full_game_test(self, test_description: str, max_steps: int = 10, timeout: int = 300) -> dict
        """运行完整的游戏测试"""
    
    def generate_test_report(self, session_id: str, format: str = "json") -> str
        """生成测试报告"""

LLMInterface 类

class LLMInterface:
    def analyze_game_screenshot(self, image_path: str, context: str = "") -> dict
        """分析游戏截图"""
    
    def generate_test_strategy(self, test_description: str, game_state: dict) -> dict
        """生成测试策略"""
    
    def decide_next_action(self, current_state: dict, strategy: dict, step_index: int) -> dict
        """决定下一步行动"""
    
    def evaluate_test_result(self, action_result: dict, expected_outcome: str) -> dict
        """评估测试结果"""

VisualObserver 类

class VisualObserver:
    def take_screenshot(self, save_path: str = None) -> str
        """截取屏幕截图"""
    
    def find_window_by_title(self, title: str) -> dict
        """根据标题查找窗口"""
    
    def detect_game_process(self, process_name: str) -> bool
        """检测游戏进程"""
    
    def analyze_image(self, image_path: str) -> dict
        """分析图像内容"""
    
    def detect_ui_elements(self, image_path: str) -> list
        """检测UI元素"""
    
    def compare_screenshots(self, image1_path: str, image2_path: str) -> dict
        """比较两张截图"""

ActionExecutor 类

class ActionExecutor:
    def execute_action(self, action: dict) -> dict
        """执行动作"""
    
    def click(self, x: int, y: int, button: str = "left") -> dict
        """点击操作"""
    
    def type_text(self, text: str) -> dict
        """输入文本"""
    
    def press_key(self, key: str) -> dict
        """按键操作"""
    
    def hotkey(self, *keys) -> dict
        """快捷键操作"""
    
    def scroll(self, x: int, y: int, direction: str) -> dict
        """滚动操作"""
    
    def wait(self, seconds: float) -> dict
        """等待操作"""

🎯 使用场景

1. 自动化游戏功能测试

# 测试游戏基本功能
agent = GameTestAgent()
results = agent.run_full_game_test(
    test_description="测试主菜单导航和游戏启动流程",
    max_steps=5
)

2. 游戏UI元素检测

from visual_observer import VisualObserver

observer = VisualObserver()
screenshot = observer.take_screenshot()
ui_elements = observer.detect_ui_elements(screenshot)
print(f"检测到UI元素: {len(ui_elements)}个")

3. 游戏性能测试

# 使用性能测试提示模板
from game_test_prompts import GameTestPrompts

prompts = GameTestPrompts()
performance_prompt = prompts.get_performance_test_prompt()

4. 自定义测试场景

# 创建自定义测试场景
custom_test = {
    "description": "测试角色技能系统",
    "steps": [
        {"action": "click", "target": "技能按钮", "expected": "打开技能界面"},
        {"action": "click", "target": "技能1", "expected": "技能激活"},
        {"action": "wait", "duration": 2, "expected": "技能冷却"}
    ]
}

agent = GameTestAgent()
# 执行自定义测试

🧪 测试和验证

运行单元测试

# 运行所有测试
python -m pytest test_*.py -v

# 运行特定模块测试
python test_llm_interface.py
python test_visual_observer.py
python test_action_executor.py
python test_game_test_prompts.py
python test_game_test_agent.py

运行集成测试

python integration_test.py

运行YummySnake示例测试

python test_yummy_snake.py

🔧 配置选项

动作执行器配置

# 启用/禁用安全模式
executor = ActionExecutor(safety_mode=True)

# 设置操作延迟
executor.set_delay(0.5)  # 每个操作间隔0.5秒

视觉观察器配置

# 设置截图保存路径
observer = VisualObserver(screenshot_dir="./screenshots")

# 配置图像分析参数
observer.set_analysis_params(
    confidence_threshold=0.8,
    detection_method="template_matching"
)

📊 测试报告

系统支持生成两种格式的测试报告：

JSON格式报告

{
  "session_id": "test_20240101_120000",
  "test_description": "YummySnake基本功能测试",
  "start_time": "2024-01-01 12:00:00",
  "end_time": "2024-01-01 12:05:00",
  "total_steps": 8,
  "success_rate": 0.875,
  "steps": [
    {
      "step_id": 1,
      "action": "click",
      "target": "start_button",
      "result": "success",
      "timestamp": "2024-01-01 12:00:30"
    }
  ],
  "summary": "测试成功完成，发现1个小问题"
}

文本格式报告

游戏测试报告
====================
测试会话: test_20240101_120000
测试描述: YummySnake基本功能测试
开始时间: 2024-01-01 12:00:00
结束时间: 2024-01-01 12:05:00
总步骤数: 8
成功率: 87.5%

详细步骤:
1. [12:00:30] 点击开始按钮 - 成功
2. [12:01:00] 移动蛇向右 - 成功
3. [12:01:30] 吃食物 - 成功
...

总结: 测试成功完成，发现1个小问题

🚨 故障排除

常见问题

OpenAI API调用失败
- 检查API密钥是否正确
- 确认网络连接正常
- 验证API配额是否充足
截图功能异常
- 确保有屏幕访问权限
- 检查是否安装了必要的图像处理库
- 验证显示器配置
GUI自动化失败
- 确保有辅助功能权限（macOS）
- 检查目标应用是否在前台
- 验证坐标计算是否正确
游戏进程检测失败
- 确认游戏路径正确
- 检查游戏是否正常启动
- 验证进程名称匹配

调试模式

# 启用详细日志
import logging
logging.basicConfig(level=logging.DEBUG)

# 使用调试模式
agent = GameTestAgent(debug=True)

📝 开发和扩展

添加新游戏支持

在 game_test_prompts.py 中添加专用提示模板
创建游戏特定的测试类
实现自定义的状态分析逻辑

添加新动作类型

在 action_executor.py 中添加新的动作方法
在 action_parser.py 中添加解析逻辑
更新提示模板以包含新动作

📄 许可证

本项目采用 Apache-2.0 许可证。

🤝 贡献

欢迎提交问题和拉取请求！

📞 联系方式

如有问题，请通过以下方式联系：

提交GitHub Issue
发送邮件至项目维护者

🎮 Game_Tars - 让游戏测试更智能！