sg-visual-run

用途：在 UI 变更后执行视觉验证，运行或重跑 YAML 测试清单。基于 agent-browser（Playwright CLI），机械步骤（点击、填写、截图）直接执行，复杂断言委派给 LLM 评估。资料建议使用快速且能力足够的模型，顶级推理模型在此无可见质量提升。\n\n调用方式：/sg-visual-run 交互式询问测试内容；后接文本按自然语言判断；--from-audit、--from-logic、--from-process 分别读取 visual-tests/_results/ 下对应结果文件中的 impacted_ui_routes 执行；多来源可合并为并集；--diff=main 执行影响测试；--all 全量；--regressions 重跑上次失败。范围优先级与详细规则见 references/invocation-modes.md。\n\n执行前：确认 agent-browser --version 可用，读取 visual-tests/_config.yaml（缺失则提示运行 /sg-visual-discover），验证 base_url 可访问。若不可达且配置含 app.start，可用 node visual-tests/shipguard.mjs serve 启动（需先复制 cli/shipguard.mjs），结束时用 node visual-tests/shipguard.mjs stop 停止；仅当由 CLI 启动时才停止。serve 退出码 2 为基础设施错误，3 为配置错误。\n\n执行要点：所有测试在单一浏览器会话中串行运行，一次登录。每次导航后校验实际 URL，若跳回 / 或 /login 则判定会话过期并重登重试。每个截图必须用 Read 工具目视检查，空或 0 字节截图记为 ERROR。每个测试后采集 agent-browser errors 与 console，错误级条目会使本应通过的测试记 FAIL。严禁并行调用多个 agent-browser 命令，否则会产生错误 URL 与损坏截图。\n\n限制与规则：任何退出（成功、失败、中止、中断）都必须运行 agent-browser close，忽略其错误；使用命名会话时需 close --all。连续 3 个不同测试出现 ERROR 则中止整个运行。结果写入 visual-tests/_results/visual-results.json，并更新 _regressions.yaml（失败记录、连续 3 次通过则移除）。不要提交 review.html 或 .server.pid。serve 以本地权限通过 shell 执行 app.start，属信任边界，仅在信任配置时使用。具体动作语义、变量插值、截图规则等见 references/action-reference.md 与 report-formats.md。