前后对比 (Before and After)
生成一张 PNG 图片:表格的每一行对应一个视觉变更,每行包含变更名称、一行备注、基础分支截图和特性分支截图。即使没有看过代码的读者,也能仅凭这张图片判断出哪些地方发生了变化、变化在哪里。
图片的质量取决于变更列表的完整性。如果一张表格只显示了五个变更中的三个,或者展示了因数据不同而非代码不同导致的差异,就会误导读者。大部分工作在于找出每一个视觉变更,并捕获每对截图,确保唯一不同的因素是代码。
图片存放位置。 本技能产生的所有内容都存储在用户的 Documents 文件夹中,路径为 ~/Documents/before-after/<仓库>/<分支>/:包括截图、清单、shots.mjs 副本以及最终的 before-after.png。脚本会自动选择该文件夹,不接受输出路径参数;如果用户希望使用 ~/Documents/before-after 以外的根目录,可设置 BEFORE_AFTER_DIR 环境变量——该变量由用户自行设置,不是你设置的。请勿将图片写入其他位置,之后也不要移动或复制它们;临时工作区仅用于基础工作目录和草稿 shots.mjs。同一分支的后续运行会复用该文件夹。
本文件同级目录下的 scripts/ 文件夹中有两个脚本:capture.mjs 负责截图,compose.mjs 负责构建并检查表格。每个脚本在其头部文档中都说明了输入格式。开始之前,请先阅读两者的头部注释。
本地说明。 如果本文件同级目录下存在名为 LOCAL.md 的文件,请在开始前阅读它。该文件包含用户针对其项目设置的默认配置(命令、主机、账户、路径),不属于已发布的技能内容。如果其中涉及当前项目的内容,则将其视为项目指令的一部分;若不涉及,则忽略。
1. 收集变更
如果未指定基础分支,则使用 PR 的基础分支(gh pr view --json baseRefName --jq .baseRefName),否则使用默认分支(git symbolic-ref --short refs/remotes/origin/HEAD),否则使用 origin/main。优先使用远程跟踪引用。包括未提交的工作:
base=$(git merge-base <base> HEAD)
git diff --stat "$base"; git diff "$base"; git status --short # 同时读取未跟踪文件
git log --oneline "$base"..HEAD
同时阅读 PR 描述和相关 Issue(如果有)。它们通常会说明变更涉及哪些屏幕,并包含人们期望看到的截图。
2. 列出每个视觉变更
将每个代码变更追溯到用户可见的界面:
- 查看代码、样式、令牌、图标、文案、翻译。 每一项都可能是候选。对于共享代码(UI 组件、格式化辅助函数、CSS 令牌),搜索其调用方并列出所有渲染该代码的屏幕。对共享代码的变更通常比分支本身的变更影响范围更广。
- 数据状态。 对于每个屏幕,读取变更代码可能覆盖的分支:已加载、加载中、空数据、错误、缺失值、零和负数、长文本、单项和多项、每种模式或设置。仅保留那些渲染会因 diff 而改变的状态。
- 交互状态。 悬停、聚焦、按下、禁用、选中;打开的弹出框、菜单、面板或对话框;显示验证错误的字段。这些需要截图前的操作步骤(步骤 4)。
- 分支新增或删除的屏幕。 这些只有一侧有截图,该行另一侧会显示占位符。
- 项目支持的环境,其中变更可能呈现不同效果:深色主题、移动端和桌面端宽度、其他区域设置。
将候选变更分为三类:
- 视觉: 屏幕上的内容确实不同。这些将构成表格行。
- 非视觉: 变更仅影响无障碍树、属性、屏幕阅读器专用文本、行为或代码结构。这些不作为表格行。在报告中列出它们的名称,以便读者知道已经考虑过并未遗漏。如果用户仍希望展示它们,则可以在行中展示以无障碍树摘录形式捕获的图片,并注明为无障碍相关。
- 不确定: 标记或类名变更,本意是不可见的,但可能导致布局或颜色变动(新的包装元素、定位类、替换的辅助函数)。对这些进行截图,让像素检查来判断。
涉及动画的变更(动画、过渡及其时序)无法在静态图片中展示。将其归入报告中的“未显示”部分,并说明如何查看。
合理地对行进行分组:每个不同的外观作为一行,而不是每个调用位置。如果十个屏幕以相同方式使用了变更的单元格,则只展示其中一两个,并在备注中列出其余屏幕的名称。目标是生成一张人们愿意阅读的表格;超过大约十二行时,按区域分拆为多个子图片,并在报告中说明。
如果视觉列表和不确定列表都为空,则在此停止。 告知用户该分支没有视觉变更,列出已考虑过的每个项目及其为何不属于视觉变更,并且不生成图片。如果只有不确定列表中的项目,且每对截图经检查完全相同,则结果相同,相同的截图对即为证据:报告它们已检查且无变化。
3. 本地构建基础分支和特性分支
两个分支的截图均从本地构建获取,绝不使用部署环境:部署环境滞后于工作树,且无法展示未提交的工作。
-
特性分支: 当前工作树,在最后一次变更后构建。
-
基础分支: 在合并基础处的一个单独的工作目录,以确保绝不触动用户的工作树。切勿在用户的检出目录中切换分支或执行 stash 操作。
git worktree add --detach <临时工作区>/before-after-base "$base"在那里安装依赖。仅在 diff 未涉及锁定文件时,才可以将主检出目录的依赖目录符号链接过去。完成后清理该工作目录(
git worktree remove)。
使用项目文档中记录的命令(阅读其 README、AGENTS.md、CLAUDE.md、开发文档以及任何 run 技能)。两边都必须连接到相同的 Staging 或测试后端,绝不能是生产环境。如果不清楚哪个命令对应哪个后端,请阅读构建配置;若仍有疑问,则停止并询问。在截图之前,检查每侧发出的真实 API 请求的主机地址。
优先使用项目的生产构建并通过静态服务器提供(build 后跟 preview 或任意静态服务器),而不是开发服务器。开发服务器会增加热更新客户端和覆盖层,可能需要为每个工作目录维护一个监视进程,并且渲染效果可能与最终发布的版本不同。如果你使用的构建工具并非项目自身的构建命令,请检查页面是否正常渲染:项目可能对其构建产物进行了后处理。另外,构建可能会清空或覆盖用户工作目录中的输出目录。这些属于生成文件,但需要在报告中说明你重新构建了哪些内容,如果构建移除了开发环境所需的文件,请将其恢复。
在信任任何截图之前,确认两个构建存在差异:在每侧读取变更元素的标记,并查看 diff 中实际发生的改变。两个提供相同代码的服务端会产生完全相同的截图对,这证明不了任何东西。
选择如何提供两个构建版本:
- 同时运行在两个空闲端口上。 这是最简单的方式,一对截图之间仅相差几秒。适用于屏幕无需登录,或登录状态在端口变化后仍然保持的情况。Cookie 在同一个主机的不同端口间共享,但本地存储不共享,且后端可能只接受特定的来源。在依赖此方法之前,请检查登录后的屏幕是否能在第二个端口正常加载。
- 顺序运行在同一个端口上。 在项目常用端口上提供基础分支服务,使用
--side=before截图,然后停止,再在该端口上提供特性分支服务,使用--side=after截图。这样,保存的登录状态和允许的来源对两者都有效。但截图间隔几分钟,因此数据必须被 mock 或是已知稳定的。
如果项目拥有组件目录(Storybook、“workshop”应用或类似工具),且变更位于共享组件中,那么在组件目录中截图比在完整应用中更简单、更稳定,且通常无需登录。但需尽量为每个变更至少捕获一个真实应用中的屏幕,以便在上下文中展示变更。如果某个真实屏幕无法访问(例如没有测试登录账号),则在报告中说明“未显示”。
4. 在相同条件下捕获每对截图
在临时工作区中编写 shots.mjs,格式应符合 scripts/capture.mjs 头部注释的要求,并从项目根目录运行,以便 Playwright 能够正确解析,且输出文件夹能获得正确的仓库和分支名称:
node <本技能目录>/scripts/capture.mjs <临时工作区>/shots.mjs --before=http://localhost:<p1> --after=http://localhost:<p2>
该脚本会针对两个 URL 执行相同的操作步骤。它使用已安装的 Chrome 浏览器、2 倍设备像素比、减少动画模式。它会关闭过渡效果、将无限动画(如闪烁、旋转)重置到第一帧并结束有限动画、等待字体和网络稳定,如果提供了时间参数还会冻结时钟。它会将 shots/<slug>.before.png、shots/<slug>.after.png 以及供步骤 5 使用的 manifest.json 写入前面所述的 Documents 文件夹,并将 shots.mjs 复制到该文件夹,同时最后一行打印该文件夹路径。使用 --only=<slug> 可重新捕获某一行。失败的截图会生成 <slug>.<side>.FAILED.png,展示整个视口的实际页面状态。
如果项目有已保存的登录状态,可以将其作为 storageState 传入(请阅读项目文档了解如何生成)。在 Orca 中,嵌入式浏览器(orca-cli 技能)也可用于捕获一两对,但使用脚本才能使截图对可重复。
在 shots.mjs 中需要正确配置的内容:
- 两边使用相同的数据。 真实数据会在两次截图之间发生漂移:价格变动、列表重新排序。建议在截图的
mock中 mock 屏幕依赖的响应:先从 staging 捕获一个真实负载,然后用它对两边进行 fulfill。有两个限制:- 如果分支更改了请求或响应结构(新端点、新字段、改变的解析器),则一个负载无法同时服务两边。请为每边提供其代码所期望的负载,但基于相同的底层值构建,并在副标题中说明。
- 通过 WebSocket 或服务器推送事件到达的数据不会受
page.route影响。请使用page.routeWebSocket,或选择流空闲的屏幕或时刻,或隐藏非主题的实时元素。
- 有意识地触发目标状态。 加载中、错误、缺失值等状态在测试账号中很少自然出现:请在
mock中构造它们(延迟响应、使响应失败、将字段设为 null)。请求路径和字段名需从代码中推导,而非猜测。在steps中通过操作触发交互状态(悬停、聚焦、点击打开)。 - 裁剪到包含上下文的变化区域。 将
target设置为能够显示变化且仍可识别为其所属屏幕的最小元素:卡片、表格、面板,而非整个页面。目标元素的宽度尽量不超过约 650 CSS px,这样能够在全尺寸下并排显示。更宽的区域会上下堆叠(前图在上、后图在下),超过约 1300 CSS px 时会被缩小,导致文本难以阅读。两侧使用相同的 target,确保裁剪对齐。 - 在
steps中使用 style 标签隐藏非主题且持续移动的元素(如滚动条、时钟、加载延迟的头像),并在两侧都应用。
5. 合成并检查
node <本技能目录>/scripts/compose.mjs <文件夹>/manifest.json [--diff] [--stack]
生成的图片将保存在清单文件旁边,命名为 before-after.png,其路径为命令行输出的最后一行。--diff 参数会为每行额外生成一张图片,用洋红色标记发生变化的像素。当变化微小或细微时(间距、颜色、单个字符)使用此参数;当变化明显时则无需使用。当某行的两张截图尺寸不同时,比较将从左上角对齐,因此偏移后的所有像素都会被标记为变化;该行会显示相关说明,此时 diff 图片仅作为粗略参考。
脚本会以相同比例绘制每行的两张截图。它会输出每行变化像素的比例以及每行的布局方式,如果存在任何一对完全相同的截图,则退出并返回错误码 3。在这种情况下:
- 相同的一对意味着截图未捕获到变化(错误的状态、错误的屏幕、缓存问题、基础构建实际上并非基础分支)。请查明原因。修正截图,或将该行从清单中移除,并将该项目移至非视觉列表,注明“已检查,无像素差异”。切勿在图片中保留包含相同截图的行。
- 查看图片(读取 PNG 文件)并检查每一行:你看到的差异应该与备注描述的一致,且没有其他差异。不在 diff 解释范围内的差异(不同的价格、缺失的行、其他位置的布局偏移)属于数据漂移或意外的回归。请重新截图,或向用户报告可能存在的回归。不要隐藏它。
- 检查每个截图中的文本是否可读。 如果脚本输出任何“文本可能无法阅读”的警告,请裁剪得更窄,并使用
--only重新捕获该行。 - 如果图片非常长,请按区域拆分:在分支文件夹内为每个区域创建子文件夹,每个子文件夹包含自己的
manifest.json,其路径指向../shots/...,然后分别合成每个区域。
6. 报告
向用户提供:
- PNG 图片的完整绝对路径。
- 表格行,每行一行。
- 未显示: 非视觉变更、经像素检查确认无变化的不确定项目、动画变更、你无法捕获的视觉变更(以及原因),以及因与已显示行重复而被省略的调用位置。
- 像素检查或你自己查看时发现的任何意外情况。
- 截图对的生成方式(使用的是真实 staging 数据还是 mock 了哪些响应;是组件目录还是真实应用),以便读者了解图片的证明效力。
停止你启动的开发服务器,并清理基础分支的工作目录。截图、shots.mjs 副本和清单文件保留在输出文件夹中,以便后续运行可以使用 --only 重新捕获某一行。