workflow-progress-screenshots

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Workflow: progress screenshots

工作流：进度截图

The user judges visual work by looking at it, and asks for screenshots in almost every thread:

"keep giving me screenshots"
"send screenshots every pass"
"can you give me screenshots of those?"
"I still don't see the screenshots. Where are they?"

Describing a change is not showing it. A screenshot mentioned but not sent doesn't count.

用户通过亲自查看来判断视觉工作成果，并且几乎每个对话线程都会要求提供截图：

“持续给我截图”
“每轮都给我发截图”
“你能给我那些内容的截图吗？”
“我还是没看到截图。它们在哪里？”

描述变更不等于展示变更。仅提及但未发送的截图不算数。

Rules

规则

Send, don't describe. Use the host's file-sending tool (
```
SendUserFile
```
, or an inline image in the report) so the picture is in front of the user. A path in a sentence is not enough.
Unasked, and as you go. Send a picture after each meaningful pass, so the user can redirect early:
- the first working version;
- each big fix;
- each round of a scoring loop.
Don't hold them all for the final report. Don't flood them either: one small batch per pass, not every save.
Start, key moment, result. For any change with a before and after, capture all three with the same framing: the state before, the interaction (hovering, aiming, mid-animation, the panel opening), and the outcome. For fixes, show the bug, then the fix.
Real renders only. Capture the actual page, game or app, not a mockup or an idea of it. Set up the state with a review fixture, a URL flag or a debug hook, rather than describing it.
Look at every image before sending. Things that mean recapture:
- stray toasts or hover pins;
- half-loaded art or missing fonts;
- the wrong scene, or stale numbers.
If the picture doesn't show what the caption claims, it isn't evidence.
Caption what it proves. One line per picture: what changed and what it verifies. For example, "Before: the hint reads 'out of range'. After: '90% hit · 5 damage'."
Label honestly. Say "headless browser capture" or "browser viewport". A 390×844 viewport is a phone-sized browser check, not a device test. Scripted or staged moments are named as staged.
Same framing for comparisons. Use the same viewport, camera and state for before and after. Put them side by side with
```
compare.py
```
.

发送，而不只是描述。 使用宿主的文件发送工具（
```
SendUserFile
```
，或在报告中内嵌图片），让图片直接呈现在用户面前。仅在句子中提供路径是不够的。
无需等待要求，边做边发。 每完成一轮有意义的操作后发送一张图片，让用户能够尽早调整方向：
- 第一个可用版本；
- 每次重大修复；
- 评分循环的每一轮。
不要把所有截图都留到最终报告。也不要过度发送：每轮发送一小批即可，而不是每次保存后都发。
开始阶段、关键时刻、最终结果。 对于任何存在变更前后对比的修改，使用相同取景方式捕获以下三个阶段：变更前的状态、交互过程（悬停、瞄准、动画中途、面板打开等）以及最终结果。对于修复，应先展示问题，再展示修复效果。
只使用真实渲染结果。 捕获实际运行的页面、游戏或应用，而不是 mockup 或设计构想。使用 review fixture、URL flag 或 debug hook 设置所需状态，而不是仅用文字描述。
发送前逐张检查每张图片。 出现以下情况时需要重新捕获：
- 零散的 toast 或 hover pin；
- 仅加载一部分的美术资源或缺失的字体；
- 错误的场景或过期的数据。
如果图片没有展示图注所声称的内容，它就不能作为证据。
用图注说明图片证明了什么。 每张图片使用一行图注，说明发生了什么变化，以及该图片验证了什么。例如：“变更前：提示显示‘超出范围’。变更后：‘90% 命中 · 5 点伤害’。”
如实标注。 明确说明使用的是
```
headless browser capture
```
还是
```
browser viewport
```
。390×844 的 viewport 只是手机尺寸的浏览器检查，并不是设备测试。通过脚本执行或人为摆拍呈现的时刻，应明确标为 staged。
对比时使用相同取景。 变更前后应使用相同的 viewport、相机和状态。使用
```
compare.py
```
将图片并排放置，或制作包含开始阶段、关键时刻和最终结果的三个面板。

How to capture

截图捕获方式

The in-app browser pane is fine while it's visible. A hidden pane stalls
```
requestAnimationFrame
```
and returns stale or black frames, so use headless capture then.
Headless:
```
scripts/capture.mjs <url> <out.png>
```
, with
```
WIDTH
```
/
```
HEIGHT
```
,
```
MOBILE=1
```
,
```
WAIT_FOR="<ready expression>"
```
,
```
SETTLE=<ms>
```
, and JS steps to click, open or scroll. It prints page errors, so a broken page gets caught instead of photographed.
- 1600×900 for desktop,
```
MOBILE=1
```
  for a 390×844 phone viewport.
- ```
SETTLE=3000
```
  –
```
5000
```
  for WebGL or 3D scenes; they render slowly headless, and an early shot misses models, fonts and icons.
- Run captures one at a time. Parallel headless Chrome on a busy machine gives protocol errors and missed frames.

Side by side:

scripts/compare.py out.jpg before.png "Before" after.png "After"

, or three panels for start, key moment and result.

Motion: a still misses what moves. Take a short burst of frames through the effect, and slow the page clock if the app exposes one. Or send a strip of frames.
If the project names a specific capture tool (for example "use the Codex browser"), use it.
Keep capture scripts and output in a gitignored folder inside the project (such as
```
qa/captures/
```
), not a scratchpad the app wipes on restart.

只要应用内 browser pane 可见，就可以直接使用。隐藏的 pane 会导致
```
requestAnimationFrame
```
停摆，并返回过期或黑屏画面，因此此时应改用 headless capture。
Headless：
```
scripts/capture.mjs <url> <out.png>
```
，可使用
```
WIDTH
```
/
```
HEIGHT
```
、
```
MOBILE=1
```
、
```
WAIT_FOR="<ready expression>"
```
、
```
SETTLE=<ms>
```
，以及用于点击、打开或滚动的 JS 步骤。它会打印页面错误，因此损坏的页面能够被及时发现，而不是仅仅被拍下来。
- 桌面端使用 1600×900；使用
```
MOBILE=1
```
  设置 390×844 的手机 viewport。
- WebGL 或 3D 场景使用
```
SETTLE=3000
```
  –
```
5000
```
  ；它们在 headless 环境中渲染较慢，过早截图会遗漏模型、字体和图标。
- 每次只运行一个捕获任务。在繁忙的机器上并行运行 headless Chrome 会引发协议错误并漏掉帧。
并排对比：
```
scripts/capture.py out.jpg before.png "Before" after.png "After"
```
，也可以制作包含开始阶段、关键时刻和最终结果的三个面板。
动效： 静帧无法呈现运动过程。应在效果执行期间连续捕获一小段帧；如果应用提供页面时钟控制接口，可以减慢其运行速度。也可以发送帧序列图片。
如果项目指定了特定的截图工具（例如
```
use the Codex browser
```
），应使用该工具。
将截图脚本和输出保存在项目内部被 gitignore 的目录中（例如
```
qa/captures/
```
），而不是应用重启后会清空的 scratchpad 中。

In the final report

最终报告

The screenshots go inline, each with its caption, after the summary of what changed.
Say which were headless captures, and which viewport a phone check used.
If something couldn't be captured, say so and why. Don't substitute a description.

摘要说明变更内容后，依次内嵌展示截图，并为每张截图配上图注。
说明哪些截图来自 headless capture，以及手机尺寸检查使用了哪个 viewport。
如果某些内容无法捕获，应说明具体原因，不要用文字描述代替截图。