AI Game Playtester

AI Game Playtester

AI 驱动的自动化游戏测试执行器。启动游戏实例，模拟玩家行为，收集运行指标，输出结构化质量报告。

⚠️ Hard Rules

1. 测试过程中严禁修改游戏源码 — Playtester 的职责是"发现问题"而非"修复问题"。所有发现的缺陷写入报告，由开发者或其他 Skill 决定是否修复
2. 必须在隔离环境中运行 — 测试运行不得影响用户的开发环境。使用独立的预览实例或沙箱进程，不得占用用户正在使用的编辑器或预览端口
3. 超时必须强制终止 — 每个测试用例有硬性超时（默认 60 秒），超时视为 FAIL 并记录，防止死循环或卡死导致测试永远挂起
4. 截图/日志必须伴随结论 — 每条 PASS/FAIL 判定必须附带可追溯的证据（终端输出片段、错误日志行号、截图路径），禁止无证据标记 PASS
5. 性能数据必须连续采样 — FPS、内存等性能指标必须以 ≥1Hz 频率连续采样至少 10 秒，禁止只取单点快照。单点快照无法反映卡顿和内存泄漏
6. 测试报告必须机器可解析 — 同时输出 JSON（机器消费）和 Markdown（人类阅读）两种格式

触发条件

当用户说以下内容时触发本 Skill：

• "测试一下游戏" / "跑个冒烟测试"
• "检查有没有崩溃" / "验证关卡能不能通关"
• "跑回归测试" / "性能测试"
• "run playtest" / "smoke test" / "QA check"

不触发条件

以下情况应使用其他 Skill：

• 用户想修复发现的 bug → 直接编辑代码或使用开发 Skill
• 用户想生成新关卡 → 使用 ai-game-level-generator
• 用户想导入/生成素材 → 使用 ai-game-asset-pipeline
• 用户想编写单元测试代码 → 使用项目的测试框架

输入参数

测试集定义

Smoke（冒烟测试）— 快速验证核心链路

Regression（回归测试）— 验证已有功能未被破坏

Performance（性能测试）— 采集运行时指标

执行流程

步骤 0：前置检查

1. 检查游戏项目是否存在：
   • 扫描项目根目录，确认存在引擎配置文件或可运行的构建产物
   • 若找不到任何可识别的游戏项目 → 报错并停止
2. 检查构建产物是否就绪：
   • Web 游戏：检查是否存在 index.html 或类似入口文件
   • 桌面游戏：检查是否存在可执行文件或引擎项目文件
   • 不存在 → 提示用户先执行构建/导出
3. 创建报告输出目录：{report_dir}/ 不存在时自动创建

步骤 1：启动测试环境

在隔离环境中启动游戏实例。根据项目类型选择启动方式：

Web 游戏：

启动本地 HTTP Server（选用未占用的端口，如 18080-18099）
  → 加载游戏页面（index.html）
  → 等待 window.onload 或引擎 ready 信号
  → 确认渲染帧数 > 0

桌面游戏：

启动导出的可执行文件 或 引擎的命令行运行模式
  → 捕获 stdout/stderr
  → 等待主场景初始化完成

启动失败判定：

• 进程在 15 秒内退出（exit code ≠ 0）→ FAIL，记录 stderr
• 进程启动但 30 秒内无渲染帧 → FAIL，记录日志

步骤 2：执行测试用例

按 test_suite 展开对应的测试集，逐条执行：

执行逻辑：

FOR EACH test_case IN test_suite:
  1. 记录开始时间
  2. 设置超时计时器（timeout_seconds）
  3. 执行测试步骤（模拟输入 / 读取状态 / 检查日志）
  4. 对比期望结果
  5. 若 capture_screenshots == true → 在关键节点截图
  6. 记录结果：PASS / FAIL / TIMEOUT / BLOCKED
  7. 记录证据：日志片段 / 截图路径 / 具体数值
  超时 → 标记 TIMEOUT，强制终止当前用例，继续下一条

输入模拟方式：

状态检测方式：

步骤 3：采集性能数据

性能测试单独执行（不与功能测试混合，避免互相干扰）：

1. 启动游戏到主场景稳态
2. 等待 3 秒使初始化完成
3. 开始连续采样（采样间隔 1 秒）
4. 采样 10-30 秒
5. 计算统计值：avg / min / max / p95 / stddev
6. 与阈值对比，输出判定

性能数据结构：

{
  "tc_id": "PF-01",
  "metric": "fps",
  "samples": [58, 60, 59, 45, 60, 60, 58, 60, 30, 60],
  "statistics": {
    "avg": 55.0,
    "min": 30,
    "max": 60,
    "p95": 60,
    "stddev": 9.2
  },
  "threshold": { "avg_gte": 30, "min_gte": 15 },
  "verdict": "PASS"
}

步骤 4：生成报告

在 report_dir 下同时输出两种格式的报告：

4.1 JSON 报告 — playtest-{timestamp}.json

{
  "schema_version": "1.0",
  "test_suite": "smoke",
  "timestamp": "2026-05-07T17:30:00Z",
  "environment": {
    "engine": "your-engine-name",
    "engine_version": "x.x",
    "platform": "web",
    "project_root": "/path/to/project"
  },
  "summary": {
    "total": 5,
    "pass": 4,
    "fail": 0,
    "timeout": 1,
    "blocked": 0,
    "pass_rate": "80%"
  },
  "results": [
    {
      "tc_id": "SM-01",
      "name": "游戏启动",
      "verdict": "PASS",
      "duration_ms": 2340,
      "evidence": "进程 PID 12345 正常启动，exit_code=null（仍在运行）"
    },
    {
      "tc_id": "SM-04",
      "name": "输入响应",
      "verdict": "TIMEOUT",
      "duration_ms": 60000,
      "evidence": "模拟 KEY_RIGHT 后 60 秒内 Player.position.x 无变化，疑似输入未绑定"
    }
  ],
  "performance": [],
  "screenshots": [
    ".playtest/reports/screenshots/SM-02_main_scene_loaded.png",
    ".playtest/reports/screenshots/SM-04_input_no_response.png"
  ]
}

4.2 Markdown 报告 — playtest-{timestamp}.md

# 🎮 Playtest 报告

> 测试时间: 2026-05-07 17:30 | 引擎: your-engine x.x | 测试集: Smoke

## 📊 总览

| 指标 | 值 |
|------|-----|
| 总用例 | 5 |
| ✅ PASS | 4 |
| ❌ FAIL | 0 |
| ⏱️ TIMEOUT | 1 |
| 通过率 | 80% |

## 📝 详细结果

| TC-ID | 用例 | 结果 | 耗时 | 证据 |
|-------|------|------|------|------|
| SM-01 | 游戏启动 | ✅ PASS | 2.3s | 进程正常启动 |
| SM-02 | 主场景加载 | ✅ PASS | 1.8s | 场景根节点存在 |
| SM-03 | 基础渲染 | ✅ PASS | 0.5s | FPS=58 |
| SM-04 | 输入响应 | ⏱️ TIMEOUT | 60s | 输入后无位移变化 |
| SM-05 | 无致命错误 | ✅ PASS | 0.2s | 日志无 ERROR |

## ⚠️ 需关注

- **SM-04 输入响应超时**: 模拟 KEY_RIGHT 后 Player 节点 position.x 无变化，
  可能原因：输入按键未在项目的按键映射中注册，或游戏主循环未处理该输入事件。

步骤 5：清理测试环境

1. 终止测试启动的所有子进程（HTTP Server、游戏进程）
2. 释放占用的端口
3. 保留报告和截图文件，不删除

完成标志

报告已写入 report_dir 且测试环境已清理后，输出：

<promise>DONE</promise>

错误处理

与其他 Skill 的协作

ai-game-level-generator
    ├─ 生成关卡配置
    └─ 输出 level_id
    ↓
ai-game-asset-pipeline
    ├─ 生成/导入素材
    └─ 写入引擎资源目录
    ↓
开发者 / AI Agent
    ├─ 实现游戏逻辑
    └─ 构建/导出游戏
    ↓
ai-game-playtester (本 Skill)
    ├─ 自动运行游戏
    ├─ 执行测试用例
    ├─ 采集性能数据
    └─ 输出质量报告
    ↓
开发者
    └─ 根据报告修复问题