Community编程与开发github.com

visual-verify

在无头浏览器(Playwright:Chromium,或 iPhone 的 WebKit;安装了 Docker 时在 Playwright 的 Docker 镜像中运行)中驱动真实的浏览器,对正在运行的 Web 应用在选定的设备视口下截图,查看结果,并确认某些内容确实渲染/正常工作——或者生成带标签的并列 BEFORE/AFTER 合成图来展示视觉变化。

visual-verify 是什么?

该技能允许 AI 助手通过 Playwright 在无头浏览器中驱动真实的浏览器引擎,对正在运行的 Web 应用进行视觉验证。它支持三种模式:验证(默认)——截取一个或多个当前状态的截图并自行读取,以确认功能渲染正常、修复有效或布局在给定宽度下正确;Before/After——通过切换更改状态,生成一张带标签的并列对比合成图,直观展示视觉变化前后的差异;以及移动端触摸检查(iOS/Android)——模拟手机并进行点击、拖动以及触摸目标大小审计。它能根据用户请求自动选择合适的模式,例如“检查这个看起来是否正确”对应验证模式,“展示前后对比”对应 Before/After 模式。该技能通过 Node.js 脚本(位于 scripts/ 目录下)使用 Playwright 库,不支持 Playwright MCP;它可以运行在 Docker 容器或本地浏览器二进制文件上,并能在多种视口(桌面端或移动端设备)下工作。

兼容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/conorjwryan/skills/tree/main/visual-verify

Installed? Explore more 编程与开发 skills: steipete/bluebubbles, steipete/eightctl, steipete/blucli · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

预览

来自技能 README

说明

文档

Visual verify

版本:1.1.0。1.0.0 之前的版本不在此仓库中跟踪。

在无头浏览器中查看真实运行的应用,并如实报告你看到的内容。 两种模式:

  • 验证(默认)——捕捉当前状态的一张(或几张)截图,并自行阅读以确认某个功能渲染正常、修复有效或布局在给定宽度下正确。
  • Before/After——对于视觉更改,关闭后再打开更改,生成一张带标签的并列 BEFORE/AFTER 合成图。
  • 触控(iOS / Android)——模拟手机,用一根手指点击和拖动,并审计触摸目标大小。请参阅下面的移动端触控检查。

根据用户的请求选择模式。“这个看起来对吗/它工作正常吗/在手机宽度下展示给我看”→验证。“前后对比/这个视觉上修复了吗”→Before/After。

当用户要求时,立即执行

当用户要求你视觉验证某件事(或截图/检查外观)时,该请求就是你的行动信号——自行运行完整检查:捕捉、阅读图片,并直白地陈述是否正确。不要只是提供建议然后就停止。

不要在每次更改后主动主动运行此操作——它会驱动浏览器并读取图片,这会消耗令牌。在未经请求的视觉更改后,你可以提供它(“想要一个前后对比合成图吗——移动端、桌面端、还是两者都做?”),让用户决定。

每次都要展示你验证的内容

用户必须能够看到结果,而无需打开文件。在报告工作的回复中,为你验证的每个功能展示后置图片——每个功能一张图片,因此检查三项就意味着至少三张图片。将每张图片放在一行说明旁边,说明它显示的内容以及是否正确(例如,“删除确认,手机宽度——焦点在取消按钮上”)。

  • 使用 Markdown 和绝对路径内联显示图片,格式为 ![说明](/绝对/路径/图片.png),由客户端渲染。否则,附加它们(例如,使用 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。

工作流程——验证模式

  1. 确保应用正在运行,并且你拥有其 URL(按照项目运行的方式启动它——请参阅下面的运行应用)。mkdir -p visual-checks。
  2. 捕捉要检查的状态,如果需要,使用 --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 用于桌面端。
  3. 阅读每张图片并如实报告是否正确。如果验证修复,确认损坏的东西确实消失了;如果验证功能,确认它确实渲染了。
  4. 在你的回复中展示相关截图——每个功能一张(请参阅展示你验证的内容)。

工作流程——Before/After 模式

  1. 确认范围和视口。mkdir -p visual-checks。选择共享的 <change> 前缀。
  2. 捕捉 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 后缀。
  3. 捕捉 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)。
  4. 合成——相同前缀,-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 — 标题全宽"
    
  5. 阅读合成图,确认它显示了你声称的内容,然后在你的回复中展示它。
  6. 恢复 BEFORE 切换。 在完成之前,切勿提交或部署带有临时 BEFORE 更改的内容——重新检查 git status / git diff。

移动端触控检查

(…

[翻译截断]

相关技能