用途
website-visual-testing 用于在浏览器中运行网站并对其 UI 进行可视化验证。它适用于本地开发服务器、预览服务器、Storybook 或长时间运行的测试目标，也适用于已托管的远程 URL。该技能的核心目标是通过 agent-browser 打开页面、检查布局与视觉状态，并给出可复现的检查结论。
主要能力
- 使用 opencode-pty 启动、监控和停止本地站点，避免使用 shell 后台方式（如 &、nohup 或作业控制）。
- 通过 pty_read 等待真实就绪信号（如 localhost URL、ready 消息、编译错误）后再打开浏览器。
- 使用 agent-browser 进行稳定导航、快照、截图与状态检查。
- 支持带注释截图（annotated screenshots），便于检查布局、间距、图标、浮层或无标签控件。
- 支持设置视口、设备模拟与明暗主题，覆盖桌面、移动、light/dark 等视觉维度。
- 支持在导航或重大 DOM 变化后重新快照，避免引用失效。
使用方式
- 确认目标：判断用户需要本地站点、远程 URL 还是两者；确定本地启动命令；明确关注的路由、组件、断点、主题或 bug 复现路径。若站点已托管，跳过 PTY 启动流程，直接进行浏览器测试。
- 使用 opencode-pty 启动站点：查看项目脚本或文档找到最窄的正确启动命令，用 pty_spawn 启动，提供清晰标题、正确 workdir，必要时设置 notifyOnExit: true。用 pty_read 观察 localhost URL、ready 消息或编译错误。端口不明确时读取 PTY 输出而非猜测。启动失败应先修复阻塞问题，不要对损坏或半启动的应用继续浏览器测试。
- 在 agent-browser 中打开页面：使用稳定显式导航，例如： agent-browser open http://127.0.0.1:3000 agent-browser wait --load networkidle agent-browser snapshot -i 优先使用 127.0.0.1 或开发服务器输出的确切主机。在资源密集页面截图前，等待应用特定加载指示消失、等待证明页面已渲染的文本，必要时用 agent-browser eval 等待 document.fonts.ready。
- 交互前先做视觉检查：用 agent-browser snapshot -i 识别可操作引用；用 agent-browser screenshot --annotate 检查布局、间距、图标、浮层或无标签控件；用 agent-browser get title 和 agent-browser get url 确认页面正确。带注释截图特别适用于响应式断点、模态/下拉/提示定位、纯图标控件以及无障碍树描述不足的 canvas 类或视觉丰富区域。
- 覆盖目标状态：走最小路径证明视觉行为。常见模式包括：每次导航或状态变更点击后重新运行 agent-browser snapshot -i；表单按引用填写，并在相关时捕获空、聚焦、无效和已提交状态；菜单或模态捕获关闭与打开状态；bug 复现捕获操作前与操作后截图。
- 覆盖关键视觉维度：至少检查与请求匹配的视图。常见维度包括桌面视口、移动视口或命名设备模拟、明暗模式、正常路径以及与 bug 或功能相关的视觉风险状态。典型命令： agent-browser set viewport 1440 900 agent-browser screenshot shots/home-desktop.png agent-browser set device "iPhone 14" agent-browser screenshot shots/home-mobile.png agent-browser set media dark agent-browser screenshot shots/home-dark.png
- 清晰报告结果：报告使用的 PTY 会话及站点是否干净启动、检查过的 URL/视口/主题、带路由与状态上下文的具体发现、相关截图，以及未验证的内容及原因。
适用场景
- 检查本地开发服务器或预览服务器的 UI。
- 验证 Storybook 或组件级视觉状态。
- 复现并记录前端视觉 bug。
- 检查响应式断点、模态/下拉/提示定位、纯图标控件。
- 检查明暗主题下的页面表现。
限制
- 该技能用于视觉浏览器测试和手动 UI 验证。
- 不替代功能测试、无障碍检查或跨浏览器认证，除非用户明确要求。
- 若任务需要像素差异基线或 CI 级回归套件，建议在手动浏览器检查后添加专门的视觉回归自动化。
- 避免依赖固定 sleep，应使用就绪信号或 DOM 条件。
- 若视觉噪声来自时间戳、广告、轮播横幅或实时计数器，应明确指出并避免过度断言。
- 不再需要时用 pty_kill 停止 PTY 会话。
参考文档
- 安全启动、监控和停止本地站点：references/pty-workflow.md
- 使用稳定 agent-browser 命令驱动浏览器：references/agent-browser-workflow.md
- 进行彻底视觉审查并避免不稳定检查：references/visual-qa-checklist.md
- 快速启动常见本地前端应用：examples/vite.md、examples/nuxt.md