workflow-progress-screenshots

工作流：进度截图

用户会通过查看画面来判断视觉效果，并且几乎每个对话中都会要求截图：

• “继续给我发截图”
• “每轮都发截图”
• “能给我看看这些的截图吗？”
• “我还是没看到截图。截图在哪儿？”

描述改动不等于展示改动。提到了截图却没有发送，不算数。

规则

1. 发送，不要描述。 使用宿主的文件发送工具（SendUserFile，或在报告中内嵌图片），让用户直接看到图片。只在句子里写路径不够。

2. 主动发送，边做边发。 每完成一轮有意义的工作后就发一张图，让用户能尽早提出调整意见：

   • 第一个可用版本；
   • 每次重大修复；
   • 每轮评分迭代。

   不要等到最终报告时才一次性全部发送，也不要刷屏：每轮发一小批，而不是每次保存都发。

3. 开始、关键时刻、结果。 对于任何有前后变化的改动，都要用相同的取景方式拍下这三个阶段：改动前的状态、交互过程（悬停、瞄准、动画中途、面板打开）以及结果。修复问题时，先展示问题，再展示修复结果。

4. 只用实际渲染结果。 截取真实页面、游戏或应用，而不是模型图或构想。使用评审夹具、URL 标记或调试钩子来设置状态，而不是用文字描述。

5. 发送前查看每张图。 出现以下情况时要重新截图：

   • 意外弹出的提示或悬停标记；
   • 素材加载不完整或字体缺失；
   • 场景错误或数值过时。

   如果图片无法证明图注所说的内容，就不能作为证据。

6. 说明截图证明了什么。 每张图片配一行说明改动内容及其验证结果。例如：“之前：提示为‘超出范围’。之后：‘90% 命中率 · 5 点伤害’。”

7. 如实标注。 使用“无头浏览器截图”或“浏览器视口”等说法。390×844 的视口是手机尺寸的浏览器检查，不是设备测试。脚本化或预设的场景要标明是预设的。

8. 对比时保持相同取景。 前后截图使用相同的视口、摄像机和状态。使用 compare.py 并排展示。

如何截图

• 应用内浏览器面板在可见时可以使用。隐藏的面板会导致 requestAnimationFrame 停滞，并返回过时或黑屏画面；此时应改用无头截图。
• 无头截图： 使用 scripts/capture.mjs <url> <out.png>，并设置 WIDTH/HEIGHT、MOBILE=1、WAIT_FOR="<ready expression>"、SETTLE=<ms> 以及用于点击、打开或滚动的 JS 步骤。该脚本会输出页面错误，因此可以发现页面故障，而不是把故障画面拍下来。
  • 桌面端使用 1600×900，390×844 的手机视口使用 MOBILE=1。
  • WebGL 或 3D 场景使用 SETTLE=3000–5000；无头模式下渲染较慢，过早截图会漏掉模型、字体和图标。
  • 一次只运行一张截图。在繁忙的机器上并行运行无头 Chrome 会导致协议错误和漏帧。
• 并排对比： 使用 scripts/compare.py out.jpg before.png "Before" after.png "After"；也可以使用三栏布局展示开始、关键时刻和结果。
• 动态效果： 单张静态图无法展示运动。连续截取效果中的几帧，并在应用提供时放慢页面时钟；也可以发送一组连帧图。
• 如果项目指定了某种截图工具（例如“使用 Codex 浏览器”），就按指定方式操作。
• 将截图脚本和输出文件保存在项目内被 git 忽略的文件夹中（例如 qa/captures/），不要放在应用重启时会清空的临时目录中。

最终报告

• 总结改动后，在正文中内嵌截图，并为每张图配上说明。
• 说明哪些截图是无头模式截取的，以及手机端检查使用的视口尺寸。
• 如果有内容无法截图，要说明原因。不要用文字描述代替截图。