UI Verify

---

什么是 UI Verify？

UI Verify 是一项托管式视觉测试服务，可接入你的 CI。每个 PR 中，它都会：

1. 捕获你的 UI：从 Storybook stories、通过即插即用的捕获 SDK 从现有的 Playwright 或 Vitest 浏览器模式测试中捕获，或者直接上传由你自己的测试工具生成的成品截图（原生、移动端、React Native），以进行差异比较。
2. 渲染并比较差异：在云端渲染每个状态，并与默认分支的基线进行比较。
3. 报告：通过 GitHub 检查返回判定结果，并据此拦截 PR。
4. 分类检查：编码 Agent（Claude Code、Codex 等）会区分真实回归和外观噪声，还可以通过 MCP 批量接受新基线。

此仓库包含开源客户端包，也就是运行在你的仓库中的所有内容。所有渲染、差异比较和判定都在服务端完成；这些包只负责构建 bundle、通过 HTTP 上传并读取状态，因此你可以放心查看、分叉并自行托管它们。

快速入门

# 1. Install the CLI in your project
npm i -D uiverify

# 2. Point it at your account
export UIVERIFY_API_KEY=...        # from uiverify.ai

# 3. Build your Storybook, then upload; the exit code reflects the visual verdict
npm run build-storybook
npx uiverify upload --static-dir storybook-static

已经有截图了？如果你的测试工具已经生成截图（Detox、Maestro、原生快照测试或其他任何方式），可以直接上传 PNG，无需 Storybook，也无需渲染。UI Verify 会以同样的方式对它们进行差异比较、判定并管理基线：

npx uiverify upload --screenshots ./screenshots

原生、移动端和 React Native 项目就是这样使用 UI Verify 的：每张图片都以其在目录下的路径作为键，因此每次构建时，同一个屏幕都会对应到同一基线；你只需上传有变更的屏幕，其余屏幕则沿用现有基线。

想通过 Agent 来驱动？安装技能（如下），然后运行 /uiverify:setup-visual-testing。它会检测你的捕获方式、配置 CI，并为你编写第一批 stories。

面向编码 Agent 的编辑中检查：uiverify check

Agent 编辑期间，可以只渲染正在修改的 stories，并与集群中的真实 CI 基线进行差异比较——无需等待 CI，就能知道“这样能通过吗”：

npm run build-storybook
npx uiverify check --story 'components-button--*' --static-dir storybook-static

它只会渲染你指定的 stories（可重复使用 --story，支持 glob 或精确 ID），不会发布 PR 检查，也绝不会移动 CI 基线。changed 结果仅供参考（退出码为 0）——通过 UI Verify MCP（get_build / render_diff_image）查看像素差异，然后在控制台中接受，或使用 accept_build 设置限定分支的预览基线，这样你自己已接受的变更在下一次检查中就不会再次触发标记。只有 CI 可以设置 main 基线。

Packages

Package	安装	功能
uiverify	npm i -D uiverify	CLI。uiverify upload 是 CI 上传工具（Storybook 包、Playwright/Vitest 归档文件或已完成截图的目录），会流式显示渲染进度，并通过退出代码反映视觉判定结果。uiverify check 是用于 Agent 编辑循环的检查工具：针对你指定的故事，与真实的 CI 基线进行渲染，不会发布检查结果，也不会移动基线。
@uiverify/playwright	npm i -D @uiverify/playwright	Playwright 截图 SDK。用它替换 @playwright/test，每项测试都会归档最终 UI 状态（序列化后的 DOM + 资源字节），供 UI Verify 重放和对比。
@uiverify/vitest	npm i -D @uiverify/vitest	Vitest 截图 SDK。在 Vitest 配置中添加 uiverifyPlugin()，每项浏览器模式测试都会归档最终 DOM（序列化后的 DOM + 资源字节），供 UI Verify 重放和对比；takeSnapshot() 则用于获取命名快照。
@uiverify/skills	npx skills add，见下文	Agent 技能：编码 Agent 可在仓库中运行的 SKILL.md 工作流，用于设置视觉测试、编写经济且确定的故事，以及排查构建问题。作为 Claude Code 或 Cursor 插件，或 Gemini CLI 扩展，它还会连接 UI Verify MCP 服务。
@uiverify/workflow-skills	Claude Code 插件，见下文	我们构建 UI Verify 时使用的 Agent 开发循环：factory、design、review-loop、e2e-verify、babysit-pr，以及用于调整该循环的技能。

Agent 技能

只需一条命令，即可将技能安装到任何编码 Agent 中（skills.sh）：

npx skills add uiverify/uiverify

适用于 Claude Code、Cursor、Codex、Copilot、Gemini，以及任何能够读取技能文件夹的 Agent。添加 --list 可选择单项技能；运行 npx skills update 可获取最新版本。

或者，在 Claude Code 中将其安装为插件，以便自动接收更新：

/plugin marketplace add uiverify/uiverify
/plugin install uiverify@uiverify

无论使用哪种方式，都可以按名称调用技能：/uiverify:setup-visual-testing、/uiverify:triage-visual-changes 等。完整列表及手动复制安装的替代方法，请参阅 packages/skills。

在 Gemini CLI 中，将相同的技能和 MCP 服务作为扩展安装，然后登录一次：

gemini extensions install https://github.com/uiverify/uiverify

在 Gemini CLI 会话中，运行 /mcp auth uiverify，并在浏览器中登录 UI Verify。

我们构建 UI Verify 时使用的 Agent 开发循环（factory、design、review-loop、e2e-verify、babysit-pr）是同一插件市场中的另一个插件：/plugin install uiverify-workflow@uiverify，然后运行 /uiverify-workflow:factory。请参阅 packages/workflow-skills。

通过 MCP 进行分类

连接 UI Verify MCP 服务后，你的编码 Agent（Claude Code、Cursor、Codex 等）便能将拉取请求中的 UI 变更带入对话，逐项查看差异、阅读 AI 评审的结论，并接受预期的基线——全程无需离开终端。

claude mcp add --scope project --transport http uiverify https://uiverify.ai/mcp

如果你已安装上面的插件，它已经连接了此服务，因此跳过命令，直接从 /mcp 登录即可。否则，添加服务后重启 Claude Code，运行 /mcp，选择 uiverify，然后在浏览器中登录 UI Verify。登录一次后，你所属团队中每个项目的连接都会建立。--scope project 会将配置写入已提交的 .mcp.json，让整个团队都能使用；该文件不包含机密信息，因为每位团队成员都会使用自己的账户登录。在 Cursor 中，将 { "mcpServers": { "uiverify": { "url": "https://uiverify.ai/mcp" } } } 添加到 .cursor/mcp.json，然后从其 MCP 设置中登录。在 Gemini CLI 中，上面的扩展会连接服务，运行 /mcp auth uiverify 即可登录。完整指南：从编码 Agent 中分类视觉变更。

该服务是远程服务（可流式传输的 HTTP）——无需安装或运行任何内容。它提供以下工具：

工具	功能
list_projects	列出你有权访问的项目；有多个项目时，提供要传入的 projectId
list_builds	列出近期的 UI Verify 构建
get_build	获取构建中的变更
list_build_stories	按状态分页查看构建中的故事
get_pr_changeset	获取某个 PR 相对于其基准分支对 UI 所做的变更
list_pr_stories	按类型分页查看 PR 与基准分支的变更集
get_diff	获取单个故事的差异详情及图片 URL
render_diff_image	获取故事图片的实际像素
review_diff	接受、拒绝或忽略某个故事的变更
accept_build	接受构建中的所有变更故事

示例

examples/ 下提供完整、可运行的项目，每种采集方式各一个。复制文件夹，添加项目 API 密钥，即可使用。

示例	采集方式
examples/storybook	Storybook 故事（无需 SDK，使用 upload --static-dir）
examples/vitest	使用 @uiverify/vitest 的 Vitest 浏览器模式测试
examples/playwright	使用 @uiverify/playwright 的 Playwright 端到端测试
examples/react-native	完成后的截图（原生 / 移动端 / React Native），使用 upload --screenshots

前三个示例采集的是同一 Shoppy 店面的不同部分；React Native 示例是一个由 Maestro 驱动的小型 Expo 应用。每个文件夹都有自己的 CI 工作流。

开发

pnpm install
pnpm -r build        # CLI builds dist/uiverify.js, playwright builds dist/
pnpm -r test
pnpm -r typecheck

CLI 需要 UIVERIFY_API_KEY，默认连接 https://uiverify.ai（可使用 --api-url / UIVERIFY_API_URL 覆盖，以用于自托管或本地开发）。内部实现请参阅各软件包的 README 和 DEVELOPMENT.md。

许可证

MIT © UI Verify