UI 改动后需要真实浏览器验证时：用 Shiplight…

在完成会影响 UI 渲染的代码改动后，需要目视确认页面布局、样式、交互行为正常并排查控制台错误时使用。

适用场景

解决思路

1. 开始前，每天最多一次机会性刷新 Shiplight skills：检查当前项目中的 `.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. 如果更新命令失败，继续使用当前已安装的技能，并简要说明失败。
5. 理解改动内容：分析代码改动并制定验证计划，包括哪些文件/组件改了、要检查哪些页面和交互、通过/失败标准（正确是什么样）。这是最重要的一步，决定测试覆盖范围；平衡彻底性和成本。
6. 启动开发服务器（如果尚未运行）：检查应用 dev server 是否正在运行；如果没有，用适当命令在后台启动，例如 `npm run dev`、`yarn dev`，等待几秒使其就绪。
7. 打开浏览器会话：调用 `new_session`，将 `starting_url` 指向要验证的页面；如果要随后生成报告，设置 `record_evidence: true`。支持多个并发会话——可以打开多个以比较不同页面或状态。
8. 检查页面：调用 `inspect_page` 获取带元素索引的 DOM 树和截图。始终先读 DOM 文件——它提供 `act` 所需的元素索引，且消耗的 token 少得多。只在特别需要视觉信息（布局、颜色、图片）时查看截图，因为截图比 DOM 消耗显著更多 token。
9. 交互并验证：根据 `inspect_page` 给出的元素索引，用 `act` 模拟用户操作；用 `act` 的 verify actions 断言预期 UI 状态，例如文本可见、元素存在。
10. 检查错误：调用 `get_browser_console_logs` 检查可能引入的 JavaScript 错误。
11. 报告发现：总结验证了什么，包括检查了哪些页面/组件、UI 是否正确渲染、发现任何控制台错误或视觉问题、展示已验证状态的截图。
12. 关闭会话：完成后调用 `close_session`；它返回 `local_video_path` 和 `local_trace_path`。
13. 生成报告：如果会话以 `record_evidence: true` 启动，调用 `generate_html_report`，传入 `session_id`、`local_video_path`、`local_trace_path`、`title`、`summary`、`checks` 等参数；将返回的 `file_path` 展示给用户，以便打开和审阅。
14. 上传报告用于分享：当用户想要可分享链接（例如附加到 PR），且 `upload_html_report` 可用时，调用 `upload_html_report`，传入 `report_path`（来自 `generate_html_report` 的 `file_path`）、`local_video_path`、`local_trace_path`；该操作会上传视频、trace 和报告 HTML 到 Shiplight 云，用云 URL 修补 HTML，并返回永久可分享的 `report_url`。
15. 如果应用需要登录，在应用登录页用 `new_session` 打开浏览器会话。
16. 请用户切换到浏览器并手动登录，等待他们确认。
17. 调用 `save_storage_state` 将 cookies 和 localStorage 保存到 `~/.shiplight/<site_url>/storage-state.json`，例如 `~/.shiplight/http_localhost_3000/storage-state.json`。
18. 对于未来所有会话，将同一路径作为 `storage_state_path` 传给 `new_session`，以即时恢复已认证状态。
19. 如果已保存的 storage state 文件已存在，自动使用它；如果使用已保存状态认证失败（页面重定向到登录、控制台出现认证错误），该状态很可能已过期——请用户重新登录并重新保存。

适用边界 · 注意事项

• 后端-only 变更（API 逻辑、数据库、配置）等不影响 UI 渲染时跳过 `/verify`。
• 没有 UI 影响的依赖版本升级时跳过 `/verify`。
• 文档、注释或仅测试变更时跳过 `/verify`。