Visual Web QA 是一个面向网页视觉验证的技能，核心目标是在浏览器中验证渲染后的实际行为，而不是从代码推断视觉是否正确。它要求选择能够直接回答请求的最小证据集合。
用途 该技能用于验证用户可见的网页改动。它强调只报告截图、视频或状态检查所支持的内容，不夸大结论。
主要能力
- 对请求行为进行分类：稳定状态验证、时序行为验证或精确状态验证。
- 解析有效的目标 URL，包括本地、预览或明确指定的地址。
- 选择有代表性的页面、状态、视口和主题。
- 使用有意义的等待和最新的元素引用捕获浏览器证据。
- 通过 sendFiles 分享请求的产物并验证交付是否成功。
- 报告精确目标、证据、结果、发现和限制。
证据选择 技能提供了请求与证据的对应关系：布局、CSS、内容、排版优先使用截图，可选 DOM 文本或样式检查；明暗主题按相关主题分别截图，可选主题属性检查；响应式行为按相关断点分别截图，仅当调整尺寸的动效重要时才用视频；加载状态、动画、过渡使用短视频，若需确认最终状态可加截图；导航或交互序列使用短视频，针对具体缺陷可加截图；稳定的菜单、模态框、悬停或焦点状态使用截图，若过渡重要可加视频；精确文本、路由、ARIA 或属性使用 DOM 检查，若可见状态重要可加截图或视频。稳定渲染状态用截图，时序、动效、加载或序列用短视频。纯时序请求可以只用视频而不加冗余截图。DOM 检查用于支持视觉证据，当用户询问外观时不能替代视觉证据。
使用方式 技能中给出的 agent-browser 命令示例包括： agent-browser --session visual-qa screenshot /tmp/visual-qa.png agent-browser --session visual-qa screenshot --full /tmp/visual-qa-full.png agent-browser --session visual-qa screenshot --annotate /tmp/visual-qa-issue.png
范围控制 除非用户要求更广覆盖或改动跨越更多模板，否则检查一到四个有代表性的页面或状态。选择最可能暴露问题的视口与主题组合，而不是默认构建穷举矩阵。当只验证了请求范围的一部分时，要明确说明。
目标解析顺序
- 用户提供的 URL
- 正在运行的本地开发服务器
- 仓库原生服务器，例如 pnpm dev
- 预览部署
- 生产环境，作为明确请求或只读基线
- 仅当站点无需服务器即可正确渲染时，才使用 file:// 输出 不要检查生产环境并声称未合并的改动已存在。如果没有可达的有效目标，报告 blocked 并说明缺少的服务器、预览、构建或认证要求。
可靠状态捕获 等待能够证明进展的状态，而不是添加任意延迟： agent-browser --session visual-qa wait --url "**/expected-path" agent-browser --session visual-qa wait --text "Expected text" agent-browser --session visual-qa wait --load networkidle agent-browser --session visual-qa wait 100 路由和内容变化优先使用 URL 或文本等待。仅当操作触发真实网络活动时才使用 networkidle。仅当动画没有语义完成信号时才使用短的固定等待。导航或重大 DOM 变化后，在使用元素引用前运行 snapshot -i。
对于初始加载行为，在首次导航前开始录制： agent-browser --session visual-qa set viewport 1440 900 agent-browser --session visual-qa record start /tmp/visual-qa-load.webm "$URL" agent-browser --session visual-qa wait --load networkidle agent-browser --session visual-qa record stop
对于加载后的交互，先探索，再开始录制。record start 会创建新的浏览器上下文并重新加载页面，因此要丢弃之前的引用，并在交互前再次运行 snapshot -i。一旦捕获到目标行为就停止录制。绝不要在录制仍处于活动状态时结束 QA 运行。
分享证据 对用户应收到的每个产物使用 sendFiles： { "files": [ { "path": "/tmp/visual-qa.png" }, { "path": "/tmp/visual-qa-load.webm" } ] } 仅当 sendFiles 在本轮成功时，才声称产物已分享。如果交付失败或 sendFiles 不可用，报告错误和保存路径，不要声称附件成功。
保护敏感数据 绝不捕获或分享凭据输入、会话令牌、客户数据或不相关的敏感 UI 状态。如果到达目标需要暴露这些数据，使用现有的安全已认证会话，或将认证要求报告为限制或阻塞。
报告结果 报告内容：
- Target：验证的精确 URL
- Evidence：收集的截图、视频和状态检查，以及选择每项的原因
- Result：pass、issues found 或 blocked
- Findings：观察到的具体渲染行为
- Limitations：未验证的请求页面、状态、视口或主题 仅当捕获的证据与请求行为匹配且没有明显范围内的回归时，才使用 pass。对于布局损坏、动效错误、闪烁、缺失资源或无效状态，使用 issues found。当不存在安全可达目标时，使用 blocked。
限制 绝不超出所收集的证据进行泛化，也绝不在未打开浏览器并收集支持证据的情况下声称渲染改动看起来正确。