imuratalpay/ui-diff
开发工具对比 PR 改动前后的 UI 截图,高亮像素差异并生成一条粘性评论,适合需要审查界面改动的团队。
这是一个 Agent 技能包 · 1 个技能看技能清单和安装方法 →项目介绍
ui-diff 针对会改动界面的 Pull Request,抓取改动路由在改动前后的截图,做像素级对比,并生成一段简短的用户体验说明,作为一个粘性 PR 评论发布。它既是 Claude Code、Cursor、Codex 的 Agent 技能,也提供 TypeScript CLI,供人或 CI 直接运行。
它通过 ui-diff.config.json、框架路由约定(Next.js、SvelteKit、Nuxt、Astro、Remix、TanStack Router、纯 HTML)和 import 图把改动文件映射到路由。base 和 head 分别在临时 git worktree 中运行,Playwright 以确定性的方式截图:等待动画和字体、固定随机数、屏蔽选择器、滚动复位,并反复截图直到连续结果一致。pixelmatch 标出变化像素并合成 前后 | 后 | 差异 图片,Agent 再根据图片和测量结果写出 UX 摘要。
可选能力包括:对查询参数做并排变体对比、改动路由的动效 GIF/WebM、设计 token 审计、基于 axe-core 的无障碍差异,以及受保护的预览地址。
快速使用
准备 git 和 Node.js 20.10+,平台为 macOS/Linux,Windows 需 WSL2。仅在发布和 --pr 时需要 gh auth login。
git clone https://github.com/imuratalpay/ui-diff.git ~/src/ui-diff
~/src/ui-diff/install.sh --claude # Cursor 也会读取;Codex 用 --codex
alias ui-diff='node ~/src/ui-diff/skills/ui-diff/bin/ui-diff.mjs'
cd ~/src/my-app # 在功能分支上
ui-diff init # 生成 ui-diff.config.json,检查 startCommand 和 routes
ui-diff run # 工作区与默认分支对比
首次 run 会构建技能并下载 Playwright 的 Chromium(约 150 MB)。结果在 .ui-diff/ 下:.ui-diff/comment.local.md 是评论预览,.ui-diff/compare/ 是对比图片。执行 ui-diff publish --pr <number> 之前不会发布任何内容。在 Agent 会话中可以直接要求它对某个 PR 运行技能并更新粘性评论。
CI 方面,示例工作流在每次 PR 推送时用仓库自己的 token 运行 run 和 publish;它要求技能已提交到应用仓库,并跳过 fork PR。
配置与可选功能
配置覆盖 startCommand、路由与文件的映射、全局文件、主题、截图屏蔽和固定时钟,完整选项见配置参考和 JSON Schema。变体对比、动效、token 审计、无障碍和受保护预览等可选功能见扩展说明。
图片托管与隐私
截图默认留在同一仓库:publish 把图片提交到孤立分支 ui-diff-assets,并以只有具备读权限的用户才能查看的方式链接。命令会先检查仓库可见性,对公开仓库默认拒绝,除非传入 --allow-public-repo。代价是:有仓库读权限的人都能打开图片;完整克隆会下载当前资源快照;已删除图片可能在 GitHub 缓存中保留一段时间;GitHub Mobile 和邮件通知可能不渲染。替代方案包括纯文本评论、CI 产物或单独的私有资源仓库,细节见隐私说明。
使用约束
- 需要 macOS 或 Linux,Windows 需 WSL2,以及 Node.js 20.10+;首次截图会下载 Chromium,除非设置
UI_DIFF_BROWSER_CHANNEL=chrome。 - 被测应用需要可用的
startCommand和端口绑定;只绑定 IPv6 或屏蔽127.0.0.1的服务器需按故障排查调整baseUrl。 - 发布需要已登录的
gh;默认拒绝向公开仓库发布。 - 受保护的预览只从环境变量读取凭据,并只发送到预览来源。
- 许可证为 MIT。
已验证示例
仓库自带一个在两个提交上保存的示例站点。对这两个提交运行 ui-diff 后生成了示例评论:在桌面/移动和亮/暗主题下共 4 个变化截图,按钮变高导致页面下移 4px,暗色模式新增 1 个无障碍问题和 3 个越界间距值。这次验证使用本地裸远程仓库完成,没有接触真实 PR。
HotRepo 点评
在 2026-11-21 的 TypeScript 新项目榜中,ui-diff 记录到 102 个 Star、7 个 Fork,在一小时统计窗口内净增 2 个 Star。样本很小,不足以判断趋势。技术内容比数字更能说明问题:路由识别、确定性截图和单条粘性评论的工作流能嵌入现有 PR 审查流程,把截图留在同一仓库也是刻意的设计选择,而不是依赖外部图床。路线图中的测量式样式变更、Figma 保真检查和设计签核门禁说明项目仍处在早期,当前能力应以已实现的功能为准。
本文由 AI 根据项目公开资料和 HotRepo 的记录撰写,更新于 ,以项目官方文档为准。
相关推荐
- anthropics/claude-code-security-review用 Claude 分析 PR 代码差异、发现安全问题并在 PR 中留言的 GitHub Action,适合需要对合并前变更做语义安全审查的团队。
- init-co-jp/diff-tour把一次 git 改动变成由大模型撰写、可逐步浏览的讲解,帮助工程师理解改动的来龙去脉。
- smokeeaasd/flawless-ui-ux为编程 Agent 提供 UI/UX 设计规范与检查 CLI,用于创建、重设计、精修和审查界面。
- anthropics/claude-code-action把 Claude 接入 GitHub PR 与 Issue,回答问题并直接修改代码的 Action。
- DEEIX-AI/Winc用 Rust 构建的桌面代码编辑器,主打快速启动、低内存占用,并集成 Git 差异与终端。