UI 走查工作台
使用此技能运行本地 UI 走查 模块。它会在浏览器 Worker 中将设计图与实现截图进行比对,将可见差异分组为待审查候选项,并支持人工确认与导出。
该分析器基于启发式算法。在人工确认设计意图、路由、状态、内容、视口一致之前,请将其输出称为候选项或可能的不匹配。切勿将未经审查的结果作为已确认的缺陷呈现。
启动工作台
-
从选定的
SKILL.md文件中解析出本技能的目录。不要假定仓库根目录或硬编码安装位置。 -
在同一会话中首次启动前,验证 bundle 和本地源桥:
python3 <skill-directory>/scripts/serve_workbench.py --check -
以后台进程方式启动服务器:
python3 <skill-directory>/scripts/serve_workbench.py启动器会输出一行 JSON,包含
event: "ready"、protocol: 2、一个动态的 loopback URL 以及进程元数据。请直接使用返回的 URL;其 fragment 部分包含浏览器应用所需的每次启动令牌。 -
如果可以控制浏览器且用户希望打开界面,则导航至该 URL。否则,将 URL 提供给用户。
-
在工作台使用期间保持进程运行。当用户要求关闭或会话不再需要时,按
Ctrl+C停止进程。
如果启动失败并提示 EPERM 或明确的 loopback 套接字限制,请请求本地执行权限后重试同一命令。不要更改绑定地址、替换为托管副本或将本地图片上传到其他位置。
选择源
工作台需要一张设计图源和一张实现截图源。任一源变更都会使之前结果失效;替换源后请重新运行审查。
- 本地图片: 点击选择或将 PNG、JPEG 或 WebP 格式图片拖入对应的设计/实现区域。解码、光栅比对和分组均在本地浏览器会话中进行。
- Figma 框架: 提供包含一个
node-id的 Figmadesign或fileURL,以及一个个人访问令牌 (PAT),或在启动启动器时设置FIGMA_ACCESS_TOKEN。这将通过 Figma API 导入该框架的 PNG 渲染;不会浏览文件内容或继承 Figma 登录状态。 - 网页抓取: 提供一个 HTTP(S) URL、视口尺寸以及可选的渲染等待时间。桥接器会启动一个临时的无头 Chrome/Chromium/Edge 浏览器配置文件并抓取该视口。不会继承用户的浏览器配置文件、Cookie、扩展或已认证会话。
在操作或故障排除 Figma 导入或网页抓取功能之前,请阅读 references/source-imports.md。
运行和审查审查
- 确认设计图和实现截图代表尽可能相同的路由、UI 状态、语言、内容、视口和滚动位置。
- 检查显示的归一化预览。引擎会以较宽的源为基准宽度,保持 1× 比例,仅将较窄的源按比例放大至该宽度,然后将两张图片左上角对齐。它不会拉伸或裁剪任一源,对比结果中会保留底部剩余的垂直高度差。
- 开始审查。在本地分类之前,Worker 会检查归一化后的光栅图是否适合直接比对。低可比性的一对不会产生任何候选项;中等可比性的一对会继续但显示显式警告。这是一个保守的启发式门控,不是概率判断或对哪张图片正确性的语义判断。
- 在可视化对比图、列表和详情面板中检查候选项。单侧透明内容仅报告为区域存在/布局差异。对于模糊的媒体或内容变化,使用中性措辞,而非强制将其归类为颜色、文字、图标或几何缺陷。检查抗锯齿、字体加载、动画、动态数据、响应式行为或过时设计是否能解释差异。
- 仅确认已验证的候选项。当有意忽略真实差异或驳回误报时,需要说明原因。
- 独立分配严重程度和优先级,然后导出已审查列表。不要仅凭像素面积或颜色距离推断优先级。
在对候选项进行分类、确定优先级、更改审查状态或决定导出内容时,请阅读 references/audit-model.md。在解释隐私、支持的集成、抓取行为或分析局限性之前,请阅读 references/v0-boundaries.md。
保持声明准确
- 比对引擎改编自
SemineChen/yangao的固定提交beac836ba3c81b9a1d40bac8fe75af08444ab742,已获得作者(由用户告知)的许可。详见 THIRD_PARTY_NOTICES.md。 - Figma 导入需要 PAT 和对 Figma 的出站访问权限。这不是 OAuth、账户关联、设计令牌提取或通用的 Figma 文件解析。
- 网页抓取是独立的当前视口截图。不是全页拼接、交互式浏览、登录状态继承、DOM 检查或计算样式提取。
- 本地浏览器处理并非安全认证。Figma 导入必然会向 Figma 发送 PAT 并下载所选框架;网页抓取必然会请求提供的 URL。
- 可比性门控不涉及 OCR、DOM 或产品语义。它可以阻止差异极大的输入并对局部变更发出警告,但无法证明两个屏幕是否代表相同的路由/状态,也无法确定权威方。
- UI 走查是当前已实现的模块。不要声称计划中的交互体验、无障碍或协作模块已经可以运行。