verify

用途

Verify 用于在真实浏览器中直观验证代码改动是否按预期渲染和运行。它基于 Shiplight MCP 浏览器工具，适合在完成 UI 改动后确认页面显示正确。

何时使用

在做出 UI 改动后使用 /verify 确认渲染正确，适用于：

直观检查布局、样式或组件改动
验证交互行为（点击、表单输入、导航）
对 UI 工作进行提交前检查
调试视觉回归

何时不使用

当改动不影响 UI 渲染时跳过 /verify：

仅后端改动（API 逻辑、数据库、配置）
无 UI 影响的依赖版本升级
文档、注释或仅测试改动

每日技能更新检查

在开始本技能工作前，每天最多一次机会性地刷新 Shiplight 技能：

检查当前项目中的时间戳文件 .shiplight-agent-skills-last-update。
如果时间戳文件缺失，用当前时间戳创建它，并继续，不运行 npx -y skills@latest update -y。将 .shiplight-agent-skills-last-update 视为本地缓存，不要提交。
如果时间戳文件存在且超过 24 小时，运行 npx -y skills@latest update -y，然后创建/更新时间戳文件，即使命令失败也要更新。
如果更新命令失败，继续使用当前已安装的技能，并简要提及失败。

使用方式

以下步骤为通用指南，可根据具体改动灵活调整：

理解改动内容——分析代码改动并制定验证计划：
- 哪些文件/组件发生了改动
- 需要检查哪些页面和交互
- 通过/失败标准（“正确”是什么样）
- 这是最重要的一步，决定测试覆盖范围。需在彻底性与成本之间取得平衡。
启动开发服务器（如果尚未运行）——检查应用的开发服务器是否在运行。如果没有，使用相应命令（如 npm run dev、yarn dev）在后台启动。等待几秒使其就绪。
打开浏览器会话——调用 new_session，将 starting_url 指向要验证的页面。如果之后想生成报告，设置 record_evidence: true。支持多个并发会话——可以打开多个会话比较不同页面或状态。
检查页面——调用 inspect_page 获取带元素索引的 DOM 树和截图。始终先读取 DOM 文件——它提供 act 所需的元素索引，且消耗的 token 远少于截图。仅在特别需要视觉信息（布局、颜色、图片）时才查看截图，因为截图消耗的 token 显著多于 DOM。
交互并验证——根据 inspect_page 返回的元素索引，使用 act 模拟用户操作。使用带 verify 动作的 act 断言预期 UI 状态（如文本可见、元素存在）。
检查错误——调用 get_browser_console_logs 检查是否引入了任何 JavaScript 错误。
报告发现——总结验证内容：
- 检查了哪些页面/组件
- UI 是否正确渲染
- 发现的任何控制台错误或视觉问题
- 显示已验证状态的截图
关闭会话——完成后调用 close_session。它返回 local_video_path 和 local_trace_path。
生成报告——如果会话以 record_evidence: true 启动，使用本地路径调用 generate_html_report：

{
  "session_id": "<session_id>",
  "local_video_path": "<local_video_path from close_session>",
  "local_trace_path": "<local_trace_path from close_session>",
  "title": "...",
  "summary": "...",
  "checks": [...]
}

向用户显示返回的 file_path，以便他们打开并查看。

上传报告以便分享——当用户想要可分享链接（例如附加到 PR）且 upload_html_report 可用时：

{
  "report_path": "<file_path from generate_html_report>",
  "local_video_path": "<local_video_path from close_session>",
  "local_trace_path": "<local_trace_path from close_session>"
}

这会将视频、追踪和报告 HTML 上传到 Shiplight 云端，用云端 URL 修补 HTML，并返回永久可分享的 report_url。

需要登录的应用

如果应用需要身份验证，登录一次并保存会话，以便后续会话跳过登录步骤：

使用 new_session 在应用登录页打开浏览器会话。
请用户切换到浏览器并手动登录。等待其确认。
调用 save_storage_state 将 cookies 和 localStorage 保存到 ~/.shiplight/<site_url>/storage-state.json（例如 ~/.shiplight/http_localhost_3000/storage-state.json）。
对于所有后续会话，将相同路径作为 storage_state_path 传给 new_session，以立即恢复已认证状态。

如果已存在保存的存储状态文件，自动使用它。如果使用保存的状态认证失败（页面重定向到登录、控制台出现认证错误），该状态可能已过期——请用户重新登录并重新保存。

适用场景

前端 UI 改动后的视觉与交互验证
提交前的 UI 健全性检查
视觉回归调试
需要生成可分享验证报告（含视频、追踪）的场景

限制

不适用于仅后端改动、无 UI 影响的依赖升级、文档/注释/仅测试改动
需要 Shiplight MCP 浏览器工具支持
报告上传功能依赖 upload_html_report 是否可用
需要登录的应用需手动完成一次登录并保存状态