用途:为项目安装 visual-verify 技能的项目侧部分。技能本身可移植,各项目差异在于如何渲染 UI 状态;本设置负责检测渲染方式、将其写入文档并附带截图脚本。
主要步骤(1)检测渲染面:优先查看而不是先问,给出建议而非空白菜单。存在 .storybook/ 则选 Storybook(最佳,story 可枚举状态);有设计交接 studies 目录则用 studies(直接截图 HTML);有 dev/start 脚本提供 UI 则用 dev 服务器;多个同时存在时,组件用 Storybook、未构建设计用 studies,并向用户说明。需与用户确认选择及发现的非显而易见事项(自定义端口、鉴权墙、构建步骤)。
(2)安装截图脚本:将 templates/screenshot-states.mjs 复制到项目 scripts/screenshot-states.mjs。它依赖 Playwright:若项目已有 playwright devDependency 则复用,否则说明 visual-verify 技能将通过 npx playwright 运行,不新增依赖。
(3)在 AGENTS.md 中声明方法:追加一节,让任何智能体(包括未运行此向导的)都知道如何渲染状态。模板按检测结果适配,示例写到:通过 bun run build-storybook,在空闲端口提供 storybook-static/,状态为 story URL(iframe.html?id=<story-id>&viewMode=story);用 node scripts/screenshot-states.mjs <states.json> <out-dir> 截图;UI 工单以 visual-verify 技能收尾;截图发布到一次性 refs/pr-screenshots/<branch-slug> 引用(不提交到分支),并通过原始 URL 嵌入 PR 正文。
(4)可选的像素差异回归测试:独立层、单独选择加入。针对项目 story 提交截图基线(vitest 浏览器模式 toMatchScreenshot,或对静态 Storybook 构建用 Playwright toHaveScreenshot)并加 CI 门禁,防止已批准的 UI 静默漂移。仅当项目同时具备 Storybook 和 CI 时才提供;若接受,需在一个环境(CI 或容器,否则跨操作系统字体渲染会误报)生成基线,禁用动画并遮蔽动态区域。
限制:资料未提供具体价格、支持平台、失败处理等细节;截图脚本依赖 Playwright,像素差异层为可选项且需 Storybook 与 CI 同时存在。