用途
Nebula 视觉验证技能用于对本地 Canvas Workbench 中已变更的 Canvas 组件和页面执行聚焦式视觉 QA。它只针对变更的 Workbench 目标，不默认扩展到整个应用的 QA；如需探索性测试，应使用 dogfood。
激活条件
仅在用户明确要求视觉验证时运行此技能。不要在组件或页面变更后自动运行，也不要从“验证”“运行检查”“完成任务”等泛化请求中推断同意。如果未明确要求视觉验证，则不要执行浏览器步骤，并报告未执行视觉验证。
前置条件
- 变更的界面必须能在 Workbench 中发现。
- 组件工作必须有足够的 component.yml 示例，以及审查所需的已编写 mocks.json 状态。
- 页面工作必须存在于该仓库的规范 pages/ 目录中。
- 在此技能开始浏览器审查之前，静态验证应已通过 nebula-component-validation 运行。
- 如果变更的界面在 Workbench 中不可审查，立即停止。缺少预览覆盖是阻塞项，不得视为已视觉验证。
强制确定性检查
每次视觉验证运行，在声称成功之前，必须为每个所需的目标/状态/视口组合运行以下浏览器侧辅助脚本：
node .agents/skills/nebula-visual-verification/scripts/collect-visual-signals.js \
--scope body \
--sample-limit 60 \
| agent-browser --session "$SESSION" eval --stdin
如果未执行此辅助脚本，验证不完整，必须报告为未完全验证。截图、人工检查和临时 eval 检查不能替代此要求。
目标解析
- 组件工作：验证变更的 /component/<component-id> 路由、任何相关的已编写 mocks.json 状态，以及当 prop 示例提供有意义基线时的 Default。
- 页面工作：验证变更的 /page/<slug> 路由。
- 保持审查范围紧凑。默认不要扫描无关组件或示例页面。
视口
在以下视口验证每个目标和命名状态：
- 桌面：1440x900
- 平板：768x1024
- 移动：390x844
浏览器工作流
- 使用 canvas-workbench 技能启动或复用 Canvas Workbench，并记录基础 URL。
- 查阅 agent-browser 技能，并在本工作流的所有浏览器交互中使用其命令模式。
- 从变更的组件或页面解析确切的审查目标和状态列表。
- 对每个目标/状态/视口组合，执行以下所有操作：
- 打开预览路由。
- 等待 networkidle 以及任何明显的加载 UI 稳定。
- 当需要记录失败时，捕获截图和带注释的截图。
- 使用 snapshot 进行结构审查。
- 运行“强制确定性检查”中的强制确定性检查命令。
- 在决定通过/失败之前审查辅助脚本输出。
- 当特定元素需要更多证据时，使用 get styles、get box 和聚焦的 eval 调用。
- 将渲染结果与 references/checklist.md 中的检查清单进行比较。
- 如果所有必需状态和视口的所有检查都通过，结束。
- 如果任何检查失败，仅修复变更的界面和直接依赖项，代码变更时重新运行静态验证，并针对相同的路由、状态和视口重新运行此技能。
自动修复循环
使用此循环直到变更的界面通过或卡住：
- 验证当前实现。
- 如果存在失败，仅修复变更的组件/页面和直接依赖项。
- 代码变更时重新运行 npm run code:fix。
- 重新打开相同的预览路由和命名状态。
- 对所有必需视口重新运行验证。
保持修复范围狭窄。不要将聚焦的视觉修正变成广泛重构或无关的设计重写。
判断规则
- 尽可能对对比度、溢出和视口级滚动问题使用确定性证据。
- 对间距、对齐、排版层次和图像相关性使用人工判断。
- 仅当图像/文案不匹配明显时才标记。不要仅基于品味或主观风格偏好拒绝图像。
- 当图像不匹配来自当前任务中新添加的图像时，可以获取更好的替代品。否则保持保守，避免推测性的图像变动。
完成门禁
除非辅助脚本已为每个所需的目标/状态/视口组合运行且结果已审查，否则不要说变更的界面“通过”“已验证”或“已视觉验证”。
如果截图或人工检查是在没有辅助脚本的情况下完成的，请将该结果报告为“仅人工审查”或“部分验证”，而不是完整视觉验证。
卡住规则
当以下任一情况为真时，停止自动修复循环并报告阻塞项：
- 相同的失败检查在连续两个循环中持续存在。
- 循环之间没有实质性代码变更。
- Workbench 无法启动或无法渲染变更的目标。
- 缺少预览覆盖。
- collect-visual-signals.js 无法为所需的目标/状态/视口组合成功运行。
- 剩余失败需要产品决策或未解决的图像来源。
卡住时，清楚解释阻塞项。不要声称任务通过。
必需收尾
每次验证收尾必须包括：
- 审查的目标路由
- 审查的视口
- 是否运行了 collect-visual-signals.js
- 确定性发现的简短摘要
- 人工视觉发现的简短摘要
如果未运行辅助脚本，明确说明：
确定性验证未完成。
产物
- 失败或卡住状态时，将截图和简短发现摘要保存在 ./visual-verification-output/<timestamp>/ 下。
- 成功时，保持收尾简洁，除非用户要求，避免产生嘈杂的产物输出。
参考映射
- 检查清单和通过/失败启发式：references/checklist.md
- 浏览器侧信号采集器：scripts/collect-visual-signals.js
- 浏览器 CLI 命令指南：agent-browser 技能
- 使用 canvas-workbench 技能启动或复用 Canvas Workbench
工具说明
在为此技能运行浏览器验证之前，始终查阅 agent-browser 技能。将其视为命令语义、会话行为和交互模式的规范来源。
不要假设需要单独的浏览器工具包装器。如果环境中可用 agent-browser，通过 shell 运行它，并将其视为此技能的有效浏览器自动化。