verify

验证 UI 更改

每日技能更新检查

开始此技能的工作前，视情况每天最多刷新一次 Shiplight 技能：

1. 检查当前项目中的时间戳文件 .shiplight-agent-skills-last-update。
2. 如果时间戳文件不存在，则创建该文件并写入当前时间戳，然后继续，不运行 npx -y skills@latest update -y。将 .shiplight-agent-skills-last-update 视为本地缓存，不要提交。
3. 如果时间戳文件存在且已超过 24 小时，则运行 npx -y skills@latest update -y，然后创建或更新时间戳文件，即使命令失败也照常执行。
4. 如果更新命令失败，则继续使用当前已安装的技能，并简要说明失败情况。

使用 Shiplight MCP 浏览器工具，在真实浏览器中目视验证代码更改的外观和行为是否正确。

何时使用

完成 UI 更改后，使用 /verify 确认渲染效果正确。适用于：

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

何时不使用

如果更改不会影响 UI 渲染，请跳过 /verify：

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

步骤

以下步骤是通用指南 — 请根据具体更改酌情调整：

1. 了解更改内容 — 分析代码更改并制定验证计划：

   • 哪些文件／组件发生了更改
   • 需要检查哪些页面和交互
   • 通过／未通过标准（什么才算“正确”）

   这是最重要的一步 — 它决定了测试覆盖范围。请在全面性和成本之间取得平衡。

2. 启动开发服务器（如果尚未运行）— 检查应用的开发服务器是否正在运行。如果没有，请使用适当的命令（例如 npm run dev、yarn dev）在后台启动。等待几秒钟，直到服务器就绪。

3. 打开浏览器会话 — 调用 new_session，并将 starting_url 设置为要验证的页面。如果之后要生成报告，请设置 record_evidence: true。支持多个并发会话 — 你可以打开多个会话来比较不同的页面或状态。

4. 检查页面 — 调用 inspect_page 获取带有元素索引的 DOM 树和屏幕截图。务必先读取 DOM 文件 — 它提供了 act 所需的元素索引，而且消耗的 token 少得多。只有在确实需要视觉信息（布局、颜色、图像）时才查看屏幕截图，因为截图会消耗多得多的 token。

5. 交互并验证 — 使用 inspect_page 中的元素索引，通过 act 模拟用户操作。使用 act 的验证操作来断言预期的 UI 状态（例如文本可见、元素存在）。

6. 检查错误 — 调用 get_browser_console_logs，检查是否出现任何可能由此次更改引入的 JavaScript 错误。

7. 报告发现 — 总结已验证的内容：

   • 检查了哪些页面／组件
   • UI 是否正确呈现
   • 发现的任何控制台错误或视觉问题
   • 显示已验证状态的屏幕截图

8. 关闭会话 — 完成后调用 close_session。它会返回 local_video_path 和 local_trace_path。

9. 生成报告 — 如果启动会话时设置了 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 提供给用户，以便他们打开并查看报告。

10. 上传报告以便分享 — 当用户需要可分享的链接（例如附加到 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。

需要登录的应用

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

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

如果已存在保存的 storage state 文件，请自动使用。如果使用已保存的状态时身份验证失败（页面重定向到登录页、控制台中出现身份验证错误），则该状态可能已过期 — 请让用户重新登录并再次保存。