pr-screenshot-comparison

PR 截图对比

创建一张便于评审的图片，让 UI 变更一目了然。

产品证据规则

PR 截图是产品证据，而不是设计示意图。每个面板都必须来自运行精确基础提交或 PR 提交的实际产品路由。必须使用真实的应用外壳、路由、身份验证边界和数据路径。

组件测试框架、Storybook 故事、静态重建页面、伪造的目标页面或模拟数据屏幕都不符合产品证据的要求。不要将它们附加到 PR，也不要将其描述为应用截图。

如果身份验证或数据阻止访问该路由：

1. 启动或复用项目的规范本地环境。
2. 如果有可用的已验证浏览器会话，则复用该会话。如果登录需要用户操作，请请求最少必要的协助。
3. 如果仍然无法访问实际路由，请停止并报告阻碍。没有截图比伪造证据更准确。

仅在用户明确要求提供组件级证据时才构建测试框架。请在图片和 PR 文案中将其标注为 组件测试框架。绝不要将其与产品截图混用，也不要用它替代产品截图。

内部数据政策

对于已确认的私有或内部 PR，请使用屏幕上的实际产品数据，包括 PHI。不要仅仅出于隐私考虑，将姓名、记录或内容替换为虚假数据。这些截图属于内部评审材料。

仍需排除凭据、访问令牌、密码、API 密钥及无关的敏感数据。对于公开或外部可见的 PR，请在截图前尽量减少或遮盖敏感数据。

捕获与合成

1. 定义证据：明确的基准提交和目标提交、产品路由、数据、以 CSS 像素为单位的视口、浏览器缩放比例、主题和必需的交互状态。列出重要变更；在 PR 说明中展示这些变更，或明确列出排除项。对于新的核心控件，使用 变更前、变更后（静止状态）、变更后（激活状态）。否则使用 变更前、变更后。
2. 批量捕获前，先捕获一个稳定状态。确认所服务的提交、已加载的记录、字体、图像和滚动位置。服务器就绪或导航完成并不能证明内容已稳定。除要展示的交互外，菜单、焦点、指针和面板都应保持一致。
3. 使用所选浏览器工具保存无损的完整视口 PNG。记录实际像素尺寸，并在旁边注明 CSS 视口尺寸。根据这些数值计算像素与 CSS 的缩放比例；不要假设 devicePixelRatio 或裁剪 API 使用相同的坐标系。重复捕获前先检查这张捕获图。捕获时如发现缩放异常、空白边距、加载状态或内容被裁切，应予以拒绝。
4. 在确切的提交上使用相同的视口、缩放比例、数据、主题和浏览器捕获方法，捕获其他状态。使用独立工作树，或进行可恢复的干净检出。之后恢复 PR 工作区，并确认其正在运行 PR 代码。
5. 从保存的原始图像裁剪，将相同的 CSS 矩形映射到图像像素。完整包含控件及其展开的菜单，并保留足够的周边背景以便识别变更。保留边缘留白；不要裁切标签、标题、菜单或提示框。如果这些状态合并后在 PR 中过宽而难以阅读，应缩小证据区域，或另做局部细节对比，而不是缩小整个屏幕。
6. 使用 scripts/compose.py 生成标准的纵向堆叠对比图。它会保留截图像素、验证尺寸和裁剪边界，并以一致的方式渲染标签和说明文字。它会生成用于上传的 PNG 和供审核的预览图。不要用临时编写的拼接脚本替代标准布局。如果这种布局无法展示变更，可以采用其他布局；但仍须遵守下方的标注规则，并说明例外原因。
7. 检查预览图，而不只是全分辨率图。在 Herdr 中，通过终端与浏览器的分屏打开合成 PNG，确保 Pete 在附件上传前能看到。必需的标签和 ID 必须无需缩放即可辨认。检查所有相关状态是否完整、裁剪是否对齐，以及标注是否遮挡证据。如果不符合要求，应在上传前重新捕获或调整画面。放大小尺寸捕获图、锐化图像或添加说明文字，都无法恢复丢失的证据。
8. 仅附加经过检查的 PNG，并使用所需的上传授权，按照下方的附件流程操作。重新加载 PR，并检查以实际嵌入尺寸呈现的图像；上传成功或图像尺寸非零都不等于完成了视觉检查。

标注规范

将标注放在产品像素区域之外。默认使用合成器的视觉样式：

• 垂直堆叠面板，让每个面板都充分利用可用的审查宽度。外侧留白为 20 CSS px，面板间距为 24 px，标题高度保持一致。让所有标签、说明文字和截图左边缘对齐。
• macOS 上使用 Arial 常规体／粗体，Linux 上使用 DejaVu Sans 常规体／粗体，或明确指定一组等效的无衬线字体。整个 PR 都使用选定的字体组合。不要悄悄回退到位图字体，也不要让不同面板的排版各不相同。
• 状态标签使用 16 px 粗体；说明文字使用 14 px 常规体，行距为 20 px，最多两行。将 Before／After 与说明分开。提交哈希和路由详情应写在 PR 正文中，而不是图片标题里。
• 根据截图中的 UI，统一使用合成器的浅色或深色中性色边框。文本对比度至少为 4.5:1。切勿给产品截图重新着色，也不要仅用红色／绿色传达状态。
• 说明可见差异，而不是实现方式。使用相互对应的说明文字，例如“列表祖先项”／“客户祖先项”；省略仅仅重复状态标签的说明。
• 仅当说明文字无法明确指出变更目标时才添加编号标注，通常不超过三个。使用直径 20 px 的圆形标记、12 px 粗体数字和 1.5 px 引导线，并随截图缩放。同一目标在不同面板中使用相同编号。在一致的外部图例中说明；引导线必须精确指向目标，且不能穿过文字或遮挡控件。默认情况下，合成器不会添加叠加层。如果需要标注，请保留其边框和排版，不要重新设计图片。

标准合成器

需要在可用的制品环境中安装 Python 3 和 Pillow。不要在产品仓库中安装依赖项。将截图清单、图片和输出文件存储在 Git 之外。清单中的路径可以是相对于清单文件的路径，也可以是绝对路径。

{
  "viewport": [1020, 971],
  "crop": [64, 6, 640, 172],
  "frame": "dark",
  "panels": [
    {"label": "Before", "caption": "List ancestor", "image": "before.png", "commit": "BASE_SHA", "route": "/appraisals/record-id"},
    {"label": "After at rest", "caption": "Customer ancestor; eyebrow retained", "image": "after.png", "commit": "HEAD_SHA", "route": "/appraisals/record-id"},
    {"label": "After activated", "caption": "Related records with IDs aligned right", "image": "open.png", "commit": "HEAD_SHA", "route": "/appraisals/record-id"}
  ]
}

crop 是以 CSS 像素为单位的 [x, y, width, height]。将所有示例尺寸、身份信息和说明文字替换为实测的截图信息。使用相对路由，以便不同的本地源保持可比。

python3 <skill-directory>/scripts/compose.py /tmp/comparison.json /tmp/comparison.png

合成器会拒绝尺寸不匹配、缩放比例不一致、缩小过的截图、超出边界的裁剪、过长的说明文字，以及宽度超过 680 CSS px 的裁剪区域。此宽度可为边框留出空间，适配约 720 px 宽的审查栏。它会在上传的 PNG 中保留原生图像密度，并另行生成 -preview.png 供检查。它无法验证提交来源、内容是否就绪、隐私状况或裁剪区域是否包含正确的控件；这些都需要检查实际产品和两份输出。

规则

• 每张产品截图都必须来自指定提交上的实际产品路由。不得伪造 UI、记录或目标页面。
• 遇到身份验证或数据受阻时，不要改用测试框架作为替代方案。只有在明确要求提供组件级证据后才可使用，并须清楚标注。
• 不要将 PNG 添加到仓库、.github/assets 或 PR 分支中。它属于 PR 上下文，而非产品源文件。
• 不要在 PR 图片中使用私有仓库文件的原始 URL；审阅者可能无法看到图片。GitHub 原生附件是持久可靠的选项。
• 不要在分支中留下截图测试框架、固定数据、Vite 更改或截图工具。确认 git diff <base>...HEAD 不包含图片资源或截图代码。
• 保持视口、缩放比例、主题和组件状态一致。如有差异且未明确说明，则比较无效。
• 不要仅为了标识可见主题，就在 PR 文案、标题、图片说明或替代文本中写“深色模式”或“浅色模式”。请描述变更。只有当主题特定行为属于变更内容，或比较依赖该差异时，才提及主题。

建议的 PR 文案

使用简短标题，然后添加本地路径引用的图片，再写一句话：

### Visual comparison

![Before and after: the hover state no longer clips the checkbox](./compare.png)

Before: [old behavior]. After: [new behavior].

用一句话描述有意义的视觉差异。如果图片只展示一种状态或主题，不要声称覆盖了所有视觉效果。

使用 gh 附加图片

上传、复用或修复图片链接前，请遵循 保持 GitHub 附件链接永久有效。 保留编辑器或 PR 正文原始内容中的上传 URL，切勿使用已渲染图片的 src、currentSrc，或跟随重定向后获取的 URL。

gh pr create、gh pr edit 和 gh pr comment 接受 --attach '<file>#<alt text>'（gh 2.99.0 或更高版本；请检查 gh --version）。gh 会上传文件，并将正文中匹配的本地路径替换为托管资源 URL，同时保留替代文本。如果未指定正文标志，它会将图片追加到现有正文末尾。

要将图片放在标题下方，请将上面的文案追加到当前正文，并在同一条命令中附加图片：

gh pr view <number> --json body --jq .body > "$TMPDIR/pr-body.md" || exit 1
cat >> "$TMPDIR/pr-body.md" <<'EOF'
<the PR copy above>
EOF
python3 "$HOME/.codex/skills/pr-description/scripts/check_attachment_urls.py" "$TMPDIR/pr-body.md" || exit 1
gh pr edit <number> --body-file "$TMPDIR/pr-body.md" --attach './compare.png#Before and after: ...' || exit 1
gh pr view <number> --json body --jq .body > "$TMPDIR/pr-body-saved.md" || exit 1
python3 "$HOME/.codex/skills/pr-description/scripts/check_attachment_urls.py" "$TMPDIR/pr-body-saved.md" || exit 1

正文中的路径必须与传递给 --attach 的路径匹配。要附加更多文件，可以重复使用该标志，每条命令最多 50 个。支持的格式：PNG、JPEG、GIF、WebP、SVG、MP4、MOV、WebM。图片大小上限为 10 MB。上传需要对该仓库具有写入权限，且不支持 GitHub Enterprise Server。

仅当 gh 版本低于 2.99.0，或仓库位于 GitHub Enterprise Server 上时，才改用网页编辑器：将 PNG 拖入描述中，保存并确认图片正常显示。