Communitygithub.com

BrainLiuYH/ui-quality-workbench

本地 UI 走查工作台,可作为 Codex Skill 安装使用。用于比对设计图与实现截图,生成视觉差异候选列表,支持人工确认和导出。

ui-quality-workbench 是什么?

UI Quality Workbench 是一个面向开发者和设计质检人员的高效 UI 走查工具,支持作为 Codex Skill 集成。它通过在本地浏览器 Worker 中运行启发式算法,将设计图(支持本地图片或 Figma 框架导入)与实现截图(支持本地图片或通过无头浏览器抓取网页)进行像素级对比,自动识别可见差异并分组为待审查候选项。用户可以在直观的界面中逐一审查、标注严重程度和优先级,最终导出已验证的差异列表。该工具严格保护隐私:所有图片处理和比对均在本地浏览器中完成,不上传任何图片到外部服务器。它明确区分了“候选项”与“已确认缺陷”,强调人工验证的必要性,并内置了保守的比对兼容性检查,避免在输入差异过大时产生误导性结果。适用于路由、状态、内容、视口一致的场景下的精细化 UI 回归审查。

兼容平台✓Claude Code✓Codex CLI~Cursor
npx skills add BrainLiuYH/ui-quality-workbench

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

UI 走查工作台

使用此技能运行本地 UI 走查 模块。它会在浏览器 Worker 中将设计图与实现截图进行比对,将可见差异分组为待审查候选项,并支持人工确认与导出。

该分析器基于启发式算法。在人工确认设计意图、路由、状态、内容、视口一致之前,请将其输出称为候选项或可能的不匹配。切勿将未经审查的结果作为已确认的缺陷呈现。

启动工作台

  1. 从选定的 SKILL.md 文件中解析出本技能的目录。不要假定仓库根目录或硬编码安装位置。

  2. 在同一会话中首次启动前,验证 bundle 和本地源桥:

    python3 <skill-directory>/scripts/serve_workbench.py --check
    
  3. 以后台进程方式启动服务器:

    python3 <skill-directory>/scripts/serve_workbench.py
    

    启动器会输出一行 JSON,包含 event: "ready"、protocol: 2、一个动态的 loopback URL 以及进程元数据。请直接使用返回的 URL;其 fragment 部分包含浏览器应用所需的每次启动令牌。

  4. 如果可以控制浏览器且用户希望打开界面,则导航至该 URL。否则,将 URL 提供给用户。

  5. 在工作台使用期间保持进程运行。当用户要求关闭或会话不再需要时,按 Ctrl+C 停止进程。

如果启动失败并提示 EPERM 或明确的 loopback 套接字限制,请请求本地执行权限后重试同一命令。不要更改绑定地址、替换为托管副本或将本地图片上传到其他位置。

选择源

工作台需要一张设计图源和一张实现截图源。任一源变更都会使之前结果失效;替换源后请重新运行审查。

  • 本地图片: 点击选择或将 PNG、JPEG 或 WebP 格式图片拖入对应的设计/实现区域。解码、光栅比对和分组均在本地浏览器会话中进行。
  • Figma 框架: 提供包含一个 node-id 的 Figma design 或 file URL,以及一个个人访问令牌 (PAT),或在启动启动器时设置 FIGMA_ACCESS_TOKEN。这将通过 Figma API 导入该框架的 PNG 渲染;不会浏览文件内容或继承 Figma 登录状态。
  • 网页抓取: 提供一个 HTTP(S) URL、视口尺寸以及可选的渲染等待时间。桥接器会启动一个临时的无头 Chrome/Chromium/Edge 浏览器配置文件并抓取该视口。不会继承用户的浏览器配置文件、Cookie、扩展或已认证会话。

在操作或故障排除 Figma 导入或网页抓取功能之前,请阅读 references/source-imports.md。

运行和审查审查

  1. 确认设计图和实现截图代表尽可能相同的路由、UI 状态、语言、内容、视口和滚动位置。
  2. 检查显示的归一化预览。引擎会以较宽的源为基准宽度,保持 1× 比例,仅将较窄的源按比例放大至该宽度,然后将两张图片左上角对齐。它不会拉伸或裁剪任一源,对比结果中会保留底部剩余的垂直高度差。
  3. 开始审查。在本地分类之前,Worker 会检查归一化后的光栅图是否适合直接比对。低可比性的一对不会产生任何候选项;中等可比性的一对会继续但显示显式警告。这是一个保守的启发式门控,不是概率判断或对哪张图片正确性的语义判断。
  4. 在可视化对比图、列表和详情面板中检查候选项。单侧透明内容仅报告为区域存在/布局差异。对于模糊的媒体或内容变化,使用中性措辞,而非强制将其归类为颜色、文字、图标或几何缺陷。检查抗锯齿、字体加载、动画、动态数据、响应式行为或过时设计是否能解释差异。
  5. 仅确认已验证的候选项。当有意忽略真实差异或驳回误报时,需要说明原因。
  6. 独立分配严重程度和优先级,然后导出已审查列表。不要仅凭像素面积或颜色距离推断优先级。

在对候选项进行分类、确定优先级、更改审查状态或决定导出内容时,请阅读 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 走查是当前已实现的模块。不要声称计划中的交互体验、无障碍或协作模块已经可以运行。

相关技能