Three.js 浏览器游戏发布前的可验证 QA 与构建流程

在发布 Three.js 浏览器游戏前，用可测量的画布检查、机器人试玩、移动端与响应式验证、生产构建和风险报告来证明游戏真的能玩、能发布。

适用场景

解决思路

1. 安装依赖，运行 build 和 typecheck，启动 dev 或 preview 服务器。
2. 打开目标浏览器，捕获 console、page 和 network 错误。
3. 确认 canvas 像素非空白且视觉上有变化。
4. 在每个目标视口（默认桌面和移动端）捕获实际游玩画面，而不只是标题画面。
5. 验证主要输入、目标推进、失败与重试，以及最近改动最多的部分。
6. 检查 HUD 文本适配、安全区域、触摸目标和响应式布局。
7. 当音频有改动时：检查用户手势解锁、SFX 触发、环境音循环启停、暂停与重启清理、静音与音量、解码错误。
8. 决定是否引入视觉测试工具（visual test harness）。对于高端、发布就绪、UI 密集或生成式资产的工作通常值得引入；无论是否引入都要说明理由。
9. 运行机器人试玩（scaffold 游戏中的 tests/bot-playtest.template.ts），用于支撑发布就绪的玩法结论，并报告其 metrics JSON。
10. 当动画有改动时，捕获一段未暂停的短序列，并使用 references/visual-test-harness.md 检查移动、clip 过渡、脚部、骨骼变形以及攻击/接触时机。
11. 使用命令 node <this-skill-dir>/scripts/inspect-threejs-canvas.mjs --url http://127.0.0.1:5188 --state active-play --run-id pass-1 运行画布检查器；--mobile 选择移动端模拟，--state <name>（可配合 --seed <n>）在捕获前等待游戏测试钩子。
12. 确保状态钩子确认 { state: name }，且 setPausedForScreenshot 必须立即停止模拟但继续渲染；捕获会在稳定前冻结已确认状态，完整准备阶段有超时；缺失钩子、无操作结果、未知状态和不匹配确认都视为失败。
13. 每次验证 pass 使用新的 --run-id 和单独的 --out 目录；按 director 的 references/evidence-manifest.md 格式预先声明期望的视口/状态对，然后用 --manifest 运行其检查器；包含所有请求状态，不要为了通过 manifest 而删除失败槽位；省略 --state 只做当前视图的画布检查。
14. 读取 JSON 中的 metrics 块（颜色熵、边缘密度、亮度对比度、主色占比）和 renderBudget 与 tier 预算的对比；这些是 threejs-aaa-graphics-builder/references/visual-scorecard.md 中视觉评分卡的 Measured Evidence；超预算行需要记录权衡，空白画布或错误条件会以非零退出。
15. 发布 pass：检查 package scripts、Vite config、base path 和 public assets → 对 debug UI、logging 和 test helpers 做门控 → 运行生产构建并在静态服务器上预览 → 在目标视口检查构建产物 → 审查 bundle 和大资产 → 记录部署命令、主机假设和残余风险。
16. 报告时先给出结果和未解决缺陷；把详细命令、manifest、截图、运动证据、执行过的控制、已修复问题和部署说明放入项目的 evidence report；在范围内时包含 harness 决策和 bot metrics；把产物路径返回给 lead。
17. 注意：仅凭截图不能覆盖玩法改动；通过的像素和已确认的状态钩子本身并不能证明美学质量或玩法成功。

适用边界 · 注意事项

• 只做桌面端且明确限定范围时，不需要额外添加移动端玩法验证。
• 没有安装 npm 依赖或无法运行游戏项目时，画布检查器无法正常工作。
• 不要为了通过 evidence manifest 而删除失败的状态槽位或忽略超预算指标。