Visual verify
版本:1.1.0。1.0.0 之前的版本不在此仓库中跟踪。
在无头浏览器中查看真实运行的应用,并如实报告你看到的内容。 两种模式:
- 验证(默认)——捕捉当前状态的一张(或几张)截图,并自行阅读以确认某个功能渲染正常、修复有效或布局在给定宽度下正确。
- Before/After——对于视觉更改,关闭后再打开更改,生成一张带标签的并列 BEFORE/AFTER 合成图。
- 触控(iOS / Android)——模拟手机,用一根手指点击和拖动,并审计触摸目标大小。请参阅下面的移动端触控检查。
根据用户的请求选择模式。“这个看起来对吗/它工作正常吗/在手机宽度下展示给我看”→验证。“前后对比/这个视觉上修复了吗”→Before/After。
当用户要求时,立即执行
当用户要求你视觉验证某件事(或截图/检查外观)时,该请求就是你的行动信号——自行运行完整检查:捕捉、阅读图片,并直白地陈述是否正确。不要只是提供建议然后就停止。
不要在每次更改后主动主动运行此操作——它会驱动浏览器并读取图片,这会消耗令牌。在未经请求的视觉更改后,你可以提供它(“想要一个前后对比合成图吗——移动端、桌面端、还是两者都做?”),让用户决定。
每次都要展示你验证的内容
用户必须能够看到结果,而无需打开文件。在报告工作的回复中,为你验证的每个功能展示后置图片——每个功能一张图片,因此检查三项就意味着至少三张图片。将每张图片放在一行说明旁边,说明它显示的内容以及是否正确(例如,“删除确认,手机宽度——焦点在取消按钮上”)。
- 使用 Markdown 和绝对路径内联显示图片,格式为
,由客户端渲染。否则,附加它们(例如,使用 SendUserFile)。始终也要提供路径。 - 选择最清晰的截图:在全页截图会掩盖功能时进行裁剪或剪裁到功能区域。
- 对于 before/after,显示合成图。
- 如果某些内容无法如实显示(系统 UI、安全区域),请说明,而不是显示误导性的图片。
始终查看你捕捉的内容
截图不是交付物——你的经过验证的判断才是。在报告之前以及在发送合成图之前,阅读你捕捉的每一张图片,以便你确认它确实显示了你声称的内容。如果它没有显示出你预期的内容,进行调查;不要在未阅读的情况下就报告成功。
选择合适的视口——这很重要
响应式错误通常只会在特定的宽度下重现。匹配用户的设备。 如果他们发送了截图,请推导出 CSS 宽度:
css_width = 截图像素宽度 / devicePixelRatio
现代 iPhone 的 DPR 为 3(例如,1320px 宽的截图 ⇒ 440 CSS px;Pro Max 级别)。
常见 Android 的 DPR 约为 2.6–3。如果不确定,扫描几个宽度(例如 320、360、390、440)——截图脚本使这变得便宜。传递 --mobile 用于触控/移动端模拟。对于适用于所有宽度的常规设计更改,同时检查桌面端和移动端。
脚本(使用 Bash 运行;没有 MCP)
不要寻找 browser_* / Playwright MCP 工具——它没有安装。所有操作都通过普通的 Node 脚本运行。解析包含此已安装的 SKILL.md 的绝对目录,然后在你的 shell 中将 VISUAL_VERIFY_DIR 设置为该目录。这可能是一个项目安装或全局安装;使用你正在阅读其说明的副本,而不是硬编码的全局路径。保持工作目录为应用项目根目录。在每个 shell 命令中重用此变量(如果 shell 状态未保留,则重新设置):
VISUAL_VERIFY_DIR="/绝对/路径/到/已安装的/visual-verify"
捆绑的脚本是:
"$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" # 捕捉 URL → png
"$VISUAL_VERIFY_DIR/scripts/composite.mjs" # 两个 png → 带标签的 before/after
"$VISUAL_VERIFY_DIR/scripts/touch.mjs" # 手机触控:点击、拖动、目标审计
运行时和浏览器设置。 此技能拥有精确的 Playwright 依赖和锁定文件。它从不解析全局或项目中的 Playwright 包。在安装或更新技能后显式运行安装程序;常规检查不会下载包、图片或浏览器。使用 Node.js 20+、npm 和 Bash。不要为此技能安装主机系统包。
浏览器运行位置。 当 Docker 可用时,每次启动都会从精确匹配、已安装的 Playwright 镜像启动其自己的容器。Docker 分配一个唯一的回环端口;辅助程序验证其容器标识并连接到该端点。技能的已安装 Node 依赖项以只读方式挂载,因此服务器无需下载包。Playwright 将回环请求转发到客户端,从而允许在无需主机网络的情况下获取本地应用 URL。正常关闭、启动失败和已处理的终止仅会清理该运行时的容器。硬性终止或主机崩溃可能会留下一个带标签的容器;在显式清理之前检查所有权。不会替换或停止预先存在的容器。Docker Desktop/macOS 网络仍然需要单独验证;不要从 Linux 检查中声称它。
在没有 Docker 的情况下,辅助程序使用已安装的本地浏览器二进制文件。设置 VISUAL_VERIFY_DOCKER=0 以强制使用本地模式;启动 API 也接受显式后端。JSON 输出会命名实际的后端和版本。
项目脚本支持的启动器
// 相对于已安装的技能目录解析此导入。
const { launchBrowser } = await import("<installed-skill>/scripts/load-playwright.mjs");
const { browser, where } = await launchBrowser("chromium", {
backend: "auto", // auto, docker, local
timeout: 30000,
launchOptions: { headless: true },
});
try {
// 使用 browser.newContext() 等。用证据报告 `where`。
} finally {
await browser.close();
}
launchOptions 传递给本地 launch 或固定的 Docker 服务器浏览器启动请求。完整的 Playwright 服务器支持请求的客户端回环转发;Docker 拥有服务器主机和端口;主机特定的可执行路径和其他特定于机器的选项由调用方负责。现有的 loadChromium() 和 loadBrowser(name) 导出仍然是仅限本地的兼容性 API:它们既不启动 Docker,也不修复缺少的浏览器。有意迁移调用者,而不是假设设置会改变它们的行为。
Docker 启动会为每个调用使用一个新的、唯一命名的服务器容器。Docker 自动分配一个回环端口;客户端验证容器元数据并连接到其报告的 WebSocket 路径。Playwright 转发客户端回环流量,保留对本地开发应用的访问权限,而无需主机网络。容器在关闭、启动失败和已处理的终止时被移除。这牺牲了热服务器复用以换取端点隔离;较旧的共享端口容器保持不变。强制终止或 Docker 故障可能会留下遗弃容器。检查 doctor 输出并验证确切容器的所有权,然后再显式删除它;永远不要停止所有匹配的进程/容器。跨平台 Docker 行为仍然需要独立验证。
screenshot.mjs 标志:--url --out [--width 390] [--height 844] [--dpr 2] [--mobile] [--wait 2000] [--click "文本或选择器"] [--scroll-bottom "sel"] [--eval "js"] [--clip x,y,w,h] [--full]。--click 是可重复的,首先匹配按钮的可访问名称,然后匹配 CSS 选择器——用于到达选项卡/菜单/对话框后面的状态。
一次性安装(每台机器)
bash "$VISUAL_VERIFY_DIR/scripts/install.sh"
将锁定的依赖项安装到该技能自己的 node_modules 中。默认的 auto 设置在 Docker 可用时拉取匹配的 Docker 镜像;否则安装本地 Chromium。将 docker 或 local 传递给安装程序以显式选择。此命令不安装本地 WebKit。不会更改全局 npm 包或系统包。
在不启动浏览器、拉取镜像或更改容器的情况下检查先决条件:
node "$VISUAL_VERIFY_DIR/scripts/doctor.mjs"
Doctor 会报告技能/运行时版本、运行时路径、本地可执行文件的存在性、Docker 镜像可用性以及活动的 Visual Verify 容器/端点(包括旧名称)。其退出状态会检查所选默认后端的 Chromium 先决条件;它不证明浏览器启动或 WebKit 可用性。安装文件和成功启动浏览器是独立的证据。
验证:
node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
--url https://example.com --out /tmp/_vv_check.png --width 390 --height 844
检查图片和后端 JSON,确认此冒烟测试有效。
等待要检查的状态
截图和触控命令支持这些后置操作选项:
--ready-selector "<selector>":等待第一个匹配的元素可见。--ready-js "<expression>":轮询直到页面表达式(包括 promise)为真。--ready-timeout 10000:正数就绪超时(毫秒);由选择器和谓词等待共享。分别限制--eval和--report的评估。--settle 0:可选的、就绪后的非负延迟,用于动画。
这些条件在所有点击/触摸、滚动、评估和拖动之后,审计和捕捉之前运行。当提供两个条件时,两者都必须通过。失败时会以非零退出,并且不会写入新的成功截图(现有输出文件不会被删除)。选择唯一的输出路径。--wait 保留其传统的预操作延迟;固定的点击/拖动延迟仍然是兼容性的稳定措施,而不是就绪的证据。说明所选条件证明了什么。
node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \
--url "<local-app-url>" --out visual-checks/search-desktop.png \
--click "Search" --ready-selector "[data-search-results]" \
--ready-js "document.querySelectorAll('[data-result]').length > 0"
使用特定于预期新状态的条件,而不是页面上已有的陈旧元素。对于需要异步结果的中间步骤,使用启动 API 和 Playwright 定位器以及操作之间的断言。如果等待响应,请在触发其请求之前注册等待,然后断言渲染状态;仅凭响应不能证明渲染。不要将任意延迟或网络空闲视为去抖动应用的完成保证。
输出位置
将生成的图片写入仓库根目录下被 gitignore 的 visual-checks/(mkdir -p visual-checks)。如果你不在仓库中,或不想向其中添加文件,请改用临时目录。在将文件发送给用户时,引用稳定的路径。
为来自一次运行的所有图片提供一个共享的 <change> 前缀,描述所显示的内容(例如 import-export-tab、header-nav)——而不是通用的 before.png/after.png——这样一眼就能看出目录中一个文件属于哪次运行:
visual-checks/<change>-<viewport>.png # 验证模式:单次截图
visual-checks/<change>-<viewport>-before.png # before/after 模式
visual-checks/<change>-<viewport>-after.png
visual-checks/<change>-<viewport>-before-after.png # 合成图
其中 <viewport> 是 mobile 或 desktop。
工作流程——验证模式
- 确保应用正在运行,并且你拥有其 URL(按照项目运行的方式启动它——请参阅下面的运行应用)。
mkdir -p visual-checks。 - 捕捉要检查的状态,如果需要,使用
--click/--eval/--scroll-bottom到达该状态:根据需要扫描几个宽度,或删除node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \ --url "<running app url>" --out visual-checks/<change>-mobile.png \ --width 440 --height 800 --mobile --wait 2000--mobile并使用例如--width 1280 --height 800用于桌面端。 - 阅读每张图片并如实报告是否正确。如果验证修复,确认损坏的东西确实消失了;如果验证功能,确认它确实渲染了。
- 在你的回复中展示相关截图——每个功能一张(请参阅展示你验证的内容)。
工作流程——Before/After 模式
- 确认范围和视口。
mkdir -p visual-checks。选择共享的<change>前缀。 - 捕捉 AFTER——工作树已包含更改:
对于桌面端,删除node "$VISUAL_VERIFY_DIR/scripts/screenshot.mjs" \ --url "<running app url>" --out visual-checks/<change>-mobile-after.png \ --width 440 --height 800 --mobile --wait 2000--mobile,使用例如--width 1280 --height 800,并使用-desktop-after.png后缀。 - 捕捉 BEFORE——临时撤销仅视觉更改,截图到
<change>-<viewport>-before.png,然后恢复。最好使用 git,这样你不会忘记恢复:- 未提交的更改:
git stash push -- <file>→ 截图 →git stash pop - 已提交的更改:
git show HEAD~1:<path> > <path>(或git checkout <parent> -- <file>)→ 截图 →git checkout -- <file>在切换和截图之间等待开发服务器热重载(--wait)。
- 未提交的更改:
- 合成——相同前缀,
-before-after.png后缀:node "$VISUAL_VERIFY_DIR/scripts/composite.mjs" \ --before visual-checks/<change>-mobile-before.png --after visual-checks/<change>-mobile-after.png \ --out visual-checks/<change>-mobile-before-after.png \ --title "440px(iPhone 宽度)下的标题" \ --before-label "BEFORE — 标题被挤压" \ --after-label "AFTER — 标题全宽" - 阅读合成图,确认它显示了你声称的内容,然后在你的回复中展示它。
- 恢复 BEFORE 切换。 在完成之前,切勿提交或部署带有临时 BEFORE 更改的内容——重新检查
git status/git diff。
移动端触控检查
(…
[翻译截断]
