Game Agent Harness

Game Agent Harness 是 Godot 游戏的确定性测试运行器。它在独立进程中启动演示，调用一个窄领域 API，验证 JSON 响应，模拟输入，捕获屏幕截图，并写入诊断产物。

根据 Apache License 2.0 许可。

该仓库包含一个原创的 8x6 战术微游戏。它仅使用基本的 Godot 绘图；不包含任何参考项目的代码或美术资源。

要求

• Godot 4.6.3

• Python 3.11 或更新版本

• macOS、Linux 或 Windows，且需要有可用显示器进行截图和 UI 测试。

Python 客户端和随附的 Godot 插件均固定为 godot-e2e==1.2.0。stdio MCP 门面使用官方的 mcp==2.0.0 Python SDK。

安装

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'

在 Godot 中打开 examples/tactics_demo/project.godot 以手动游玩演示。自动化服务器在正常游戏会话中保持休眠状态。

运行场景

.venv/bin/python -m game_agent_harness run scenarios/tactics_smoke.yaml
.venv/bin/python -m game_agent_harness run scenarios/tactics_full.yaml
.venv/bin/python -m game_agent_harness run scenarios/tactics_ui.yaml
.venv/bin/python -m game_agent_harness soak scenarios/tactics_smoke.yaml --runs 100

退出码 0 表示通过，1 表示游戏断言失败，2 表示配置、进程、传输或协议错误。

每次运行都会在 artifacts/<run-id>/ 下创建解析后的场景、命令、事件、状态、截图、捕获的 Godot 日志以及 JSON 和 Markdown 格式的报告。在诊断失败运行时，请将 report.md 及其相邻的 JSONL 文件交给 Codex。

MCP 服务器

使用绝对工作区路径启动本地 stdio 服务器：

.venv/bin/game-agent-harness-mcp \
  --workspace-root /absolute/path/to/game-agent-codex

MCP 主机可以使用以下配置启动它：

{
  "mcpServers": {
    "game-agent-harness": {
      "command": "/absolute/path/to/game-agent-codex/.venv/bin/game-agent-harness-mcp",
      "args": [
        "--workspace-root",
        "/absolute/path/to/game-agent-codex"
      ]
    }
  }
}

该服务器发布四个工具：

• list_scenarios 列出 scenarios/ 下的 YAML 文件。

• run_scenario 运行一个列出的场景。

• soak_scenario 重复运行一个列出的场景，硬性限制为 100 次。

• read_report 从 artifacts/ 的直接子项中读取 report.json。

MCP 层使用与 CLI 相同的 ScenarioRunner。它不暴露任意的文件系统路径、Godot 节点调用、属性写入或代码编辑工具。场景项目和生成的产物必须保持在配置的工作区之内。

Game Agent API

/root/GameAgent 在 --e2e 会话期间暴露六个方法：

agent_get_manifest()
agent_reset(options)
agent_get_state()
agent_list_actions()
agent_perform_action(request)
agent_get_events(after_sequence)

0.1.0 契约由 protocol/ 下的 schema 定义。动作请求包含唯一的 request_id、调用方的 expected_revision、动作名称及其参数。过期的修订版本或无效动作将被拒绝，且不会更改游戏状态。

要添加一个动作：

1. 在 TacticsGameController.perform_action 中实现验证和行为。

2. 将其参数 schema 添加到 GameAgent.agent_get_manifest。

3. 失败时返回稳定的错误代码，且不递增 revision。

4. 添加一个领域测试和一个场景步骤。

CLI 有意不暴露任意的 Godot 节点调用。

验证

scripts/verify.sh

该脚本运行无头 Godot 领域测试、Python 单元测试、Ruff、mypy 和冒烟场景。它在可用时使用 .venv/bin/python，否则使用 python3。设置 GAME_AGENT_PYTHON=/path/to/python 以选择另一个已安装的环境。该包直接从 orchestrator/ 加载，但其第三方依赖必须首先安装。

VisualProbe

VisualProbe 被隔离在 examples/visual_probe_fixture 中，这是一个 Forward+ 测试夹具，不会影响 tactics_demo 使用的 Compatibility 渲染器。它仅暴露注册的目标 fixture 以及正交视图 front、back、left、right 和 top。支持的渲染通道为 beauty、silhouette、depth、normal、object_id 和 wireframe。

安装可选的图像栈，并在 GPU 运行器上使用专用验证器：

.venv/bin/pip install -e '.[dev,visual]'
scripts/verify-visual.sh

视觉运行将 PNG 存储在 visual/targets/<target>/ 下；变体捕获使用 visual/targets/<target>/variants/<id>/。基线包存储在 scenarios/baselines/<id>/ 下，包含 metadata.json 以及 images/ 中映射的 PNG。在计算轮廓差异之前，其元数据必须与捕获渲染器和分辨率匹配。PNG 和基线文件有大小限制，并且读取时不跟随符号链接。

该夹具传输仅监听回环地址，要求每次运行的 e2e 令牌，接受最大 64 MiB 的帧，并且只允许对 /root/GameAgent 进行 VisualProbe 调用。缺少 Godot 4.6 安装、GPU 环境或视觉依赖项属于配置错误（退出码 2），绝不能作为通过测试的替代。

参考项目

该设计参考了：

• Grid Tactics Foundation

• Godot RPG Demo

• 2D Tactical RPG Demo

没有从这些项目中复制任何代码或美术。参见 THIRD_PARTY_NOTICES.md 了解随附的依赖项。