wai-play

WAI Play — 面向网页游戏的 Agent 自动试玩

WAI Play 会操控真实浏览器试玩正在运行的网页游戏，建模游戏目标和关键节点，进行游玩，并返回五个维度的质量评分，以及可复现的问题卡片（状态变化、截图、时长 ≤20 s 的片段）和修复建议。测试可信度会与游戏质量分开报告，因此薄弱的测试框架不会抬高或拉低游戏评分。

工作几乎从不以“运行测试”开始，而是先确认这款游戏能否进行测试，而这个答案将决定后续的一切。

何时使用此技能

• 一款氛围式编码的网页游戏需要在演示、Game Jam 截止日期或发布前自动试玩，用户想要的是证据，而非感觉
• 游戏没有 Agent 可读取的状态，需要编写或修复 GameFlowAgentAPI 桥接层
• 测试运行已完成，用户需要帮助解读评分、问题卡片或可信度诊断
• 无法到达必需的关键节点（首次升级、Boss 阶段、关卡目标、结局），用户必须在修复前置条件、跳转或采用自然路线之间做出选择
• 用户正在决定采用本地、Docker 还是无密钥（降级）运行方式

何时不使用此技能

• Unity / Unreal 帧耗时或性能分析器相关工作 → game-performance-profiler
• 引擎构建、烘焙或打包失败 → game-build-log-triage
• 人工试玩笔记、Steam Playtest 回复、主播反馈 → game-demo-feedback-triage
• 不含游戏模型的一般浏览器自动化或脚本化 E2E 测试套件 → browser-harness 或 playwriter
• 构建游戏本身，而不是测试游戏 → web-game-development

说明

第 1 步：开始操作工具前收集必要信息

收集以下五项信息。缺少任何一项都会改变建议：

1. 游戏类型 — 以下类型之一：survivor_like、arcade_shooter、platformer、 puzzle_card、visual_novel。WAI Play 仅支持这五种类型；其他游戏会采用最接近的配置，并明确说明限制。
2. 可访问的 URL — 正在运行的游戏，而不是代码仓库。本地主机也可以。
3. 集成状态 — 页面是否公开了 window.GameFlowAgentAPI？ 仅通过 URL 进行黑盒测试是可行的，但如果没有它，流程建模和关键节点路由能力会明显减弱。
4. 源代码是否可用 — 可选提供与部署版本匹配的 ZIP。它只会作为临时副本进行分析；WAI Play 绝不会修改项目。
5. 密钥是否可用 — DeepSeek 和 Kimi 密钥，或如实说明采用无密钥方式。

第 2 步：只选择一种模式

模式	适用场景	产出
testability	不确定游戏是否能以任何方式操控	给出就绪状态结论，并指出每项阻碍能力
integration	没有 API，或桥接层只是空壳	接入真实游戏状态的 GameFlowIntegration 桥接层
run	游戏可测试且已完成配置	已配置的运行：类型、URL、可选 ZIP、步数预算
report	运行已完成	区分游戏质量与测试可信度的评分解读
scenario-gap	无法到达必需的关键节点	给出修复计划、跳转或自然路线的选择及理由
ops	部署、隐私或无密钥相关问题	本地、Docker 或降级运行方式的选择

不要混用模式。在 run 前执行 testability 是本技能中最有价值的顺序——针对无法读取状态的游戏运行测试，只会产生看似可靠的胡言乱语。

第 3 步：使用只读 doctor 检查就绪状态

bash .agent-skills/wai-play/scripts/wai-play.sh doctor
bash .agent-skills/wai-play/scripts/wai-play.sh doctor /path/to/wai-play

doctor 会报告 Python 版本、四个运行时软件包、是否存在 Playwright Chromium 构建版本，以及设置了哪些 .env 密钥——只报告密钥名称，绝不显示密钥值。它不会安装任何内容，也不会启动测试。

第 4 步：先编写或修复桥接，再归咎于游戏

上游 v2 模板拒绝伪造状态：未实现的 observe() 或 step() 会抛出异常，而不是返回看似合理的数据。 这是刻意为之。返回虚构状态的桥接描述的是桥接本身，而不是游戏的评分。

发布前，请对候选集成文件进行静态检查：

python3 .agent-skills/wai-play/scripts/check_integration.py \
  --game-type survivor_like path/to/game-integration.js

检查器仅使用标准库，并会输出一个带有 ```review 围栏的 JSON 块， 列出缺失的方法、遗留的模板占位符、未实现的抛出异常桩，以及未找到的 必需状态字段。如果存在阻塞项，检查器会以 1 退出。这是一次静态文本检查： 检查通过只意味着文件看起来符合契约，不代表桥接已接入真实的游戏逻辑。 请另外确认这一点。

契约详情见 references/integration-api.md。

第 5 步：契约尚新时，先对照演示游戏运行

仓库附带五款参考游戏，每种类型各一款。启动服务并针对其中一款运行， 先确认测试框架正常工作，再调试真实游戏：

bash .agent-skills/wai-play/scripts/wai-play.sh demo /path/to/wai-play 8768

这会在前台启动本地静态服务器——这是有意执行且对用户可见的操作， 而不是作为后台副作用运行的操作。

第 6 步：阅读报告时，将质量与可信度分开看待

五个加权维度为游戏评分：核心流程（0.24）、游戏玩法 （0.26）、UI/视觉效果（0.20）、反馈（0.15）、技术稳定性（0.15）。 API 集成完整度、证据完整度和 Agent 可靠性作为可信度诊断项报告， 不计入这些评分。

有两条规则很容易弄错：

• feedback 维度只评估玩家能看到或听到的内容，或评审者能从片段中 确认的内容。单凭内部 API 值发生变化，并不能作为反馈良好的证据。
• 一个问题只报告一次，并关联到最佳尝试的证据。不要按出现次数重复报告 同一个缺陷。

评分等级、各项标准的权重和证据规则见 references/scoring-and-reports.md。

第 7 步：如实处理无法到达的关键节点

无法进入必需场景时，API 会返回一个编码原因，每个代码都有唯一正确的处理方式：

代码	含义	正确处理方式
SCENARIO_PRECONDITION_MISSING	无法读取判定所需的状态	将缺失字段添加到 observe()，然后重新检查
SCENARIO_LOADER_NOT_IMPLEMENTED	不存在场景初始化器	实现它，或采用自然路线
SCENARIO_UNSAFE_TO_JUMP	跳转会导致状态不一致	采用自然路线；不要强行进行不完整跳转
SERVER_AUTHORITATIVE_STATE	状态由服务器管理	申请测试账号、存档或注入端点
REPAIRER_NOT_IMPLEMENTED	不存在安全的修复路径	采用自然路线

切勿只设置一个字段来满足关键节点。上游对此有明确警告：如果为了进入 Boss 阶段而将 elapsed = 360，却没有初始化关卡、装备、地图、出生点池和 Boss AI，那么这个场景 虽然能通过，却毫无意义。

各游戏类型的场景表见 references/game-profiles-and-scenarios.md。

第 8 步：遵守运行边界

• 仅测试你拥有或获准测试的游戏和源代码。
• 上传的 ZIP 会作为临时副本进行分析；每次运行后都要清理。
• 开启 AI 源码建模后，源码摘要会发送给已配置的第三方模型提供商（DeepSeek、Kimi）。在对尚未发布或客户拥有的代码启用此功能前，请说明这一点。
• 当前版本面向本地使用。公开的多用户托管还需要账号、作业队列、配额、远程 URL 限制和自动测试数据清理功能，而上游尚未实现这些功能——请明确说明这一点，不要暗示它已可用于部署。

设置、Docker、无密钥降级和路由转出说明见 references/setup-and-route-outs.md。

最佳实践

1. 先确保可测试性，再开始测试。 对不可读取的游戏进行一次运行，只会生成自信却错误的报告。
2. 绝不要在桥接层伪造状态。 返回编造数据的存根只会让存根得分。抛出异常才是正确的未实现行为。
3. 在每份摘要中将游戏质量与测试可信度分开，就像该工具所做的那样。
4. 初始化完整场景，而不是单个字段。 部分跳转会导致关键节点通过，却毫无意义。
5. 优先选择自然路线，而不是不安全的跳转。 缓慢但真实的路径胜过快速却不连贯的路径。
6. 将每个问题与一组最佳尝试证据关联起来——状态变化加截图或不超过 20 s 的视频片段，并且只报告一次。
7. 说明结果何时有所降级。 没有密钥就无法进行源码建模和 AI 路线规划，只能提供规则级建议。
8. 如果游戏不属于五种类型之一，请一开始就说明这一限制。

示例

示例 1：“WAI Play 甚至能测试我的游戏吗？”

运行 doctor，然后检查页面是否挂载了 GameFlowAgentAPI。如果没有，答案应是只能进行黑盒测试，并建议使用 integration 模式——而不是直接运行。

示例 2：桥接层存在，但每项得分都低得可疑

python3 .agent-skills/wai-play/scripts/check_integration.py \
  --game-type platformer web/game-integration.js

遗留的 throw new Error(...) 存根和模板占位符，比游戏本身更常导致低分。

示例 3：Boss 阶段始终无法触发

查看返回的代码。SCENARIO_UNSAFE_TO_JUMP 表示应采用自然路线并延长步数预算，而不是强行跳转。

示例 4：用户希望将其部署为公共服务

如实回答：目前适用于本地和演示用途；公共托管还需要账号、排队、配额、URL 限制和数据清理功能，而这些目前都不存在。

参考资料

• references/integration-api.md — GameFlowAgentAPI / GameFlowIntegration 方法契约、v1 与 v2 的区别、各类型的状态结构
• references/game-profiles-and-scenarios.md — 五种游戏类型、操作、必需关键节点、成功运算符
• references/scoring-and-reports.md — 维度权重、标准、评级区间、证据与可信度规则
• references/setup-and-route-outs.md — 安装、.env、Docker、演示游戏、降级模式、路由转出
• scripts/wai-play.sh — 只读的 doctor、check 透传、前台运行的 demo 服务
• scripts/check_integration.py — 仅使用标准库，对集成文件进行静态契约检查
• WAI Play GitHub Repository
• 项目标准：.agent-skills/skill-standardization/SKILL.md