one-shot-ui

问题所在

AI Agent 能把 UI 做到大约 90%，然后就停滞不前。布局看起来没问题，但卡片高了 8px，面板的灰色深浅不对，阴影显得扁平，间距差了 24px。让模型“再看一遍截图并修好”既慢，而且每次得到的答案都不一样。

one-shot-ui 以确定性的方式补上最后 10%。它会从参考截图中提取结构化数据——布局区域、颜色、字体排版、间距、设计令牌——将你的实现与其进行对比，并返回具体且按优先级排序的修复方案，而不是“让它看起来更像这个”。

Set width to 616px (currently 640px)
Change the fill color to #303040.
Set box-shadow to -3px 0px 24px 0px rgba(28, 29, 38, 0.32).
gap: 176px; /* currently ~152px */

可直接复制粘贴的 CSS，按视觉影响排序——上方每个示例都来自下面这次运行的真实输出。

观察它逐步收敛

run 命令会循环执行提取 → 截图 → 对比 → 修复，直到热力图平静下来。在上方的示例中，Agent 的第一个构建版本肉眼看起来与参考图完全相同，但 one-shot-ui 标出了 15 处具体差异（位置、尺寸、颜色、阴影、间距），并通过循环将构建版本的像素差异率降到了约 2.5%，与该设计下工具自身估算的不可消除下限（约 2%，亚像素字体渲染）相差约 0.5%。

为什么选择 one-shot-ui

• 确定性，而非凭感觉。 稳定的像素和结构差异分数——相同输入，相同数值——因此你可以在 CI 中设置门槛，检查“像素差异是否足够小？”
• 精确修复，而非微调建议。 返回具体的 CSS（width: 616px、#303040、gap: 176px），按组件分组并按视觉影响排序。
• 结构对比，而不只是像素对比。 检测缺失或多余元素、位置和尺寸偏移、颜色、阴影、间距及字体排版；还会标记哪些差异是不可消除的（抗锯齿、摄影内容），避免 Agent 徒劳追逐。
• 无法投机取巧。 converge 评估的是结构保真度——参考图中的内容是否存在、位置是否正确、是否清晰可读？——而不只是像素差异；它不会通过隐藏、重叠文本或将文本改成与背景相同的颜色来降低像素差异。它甚至会标出参考图中有、但你的构建版本渲染后被裁切到视野之外的文本（例如固定高度的 overflow:hidden 容器）——像素对比会奖励这种问题，因为裁切文本会降低差异率。
• 原生适配 Agent。 随附 AGENTS.md（可由 Claude Code、Cursor、Codex 等自动发现）以及 Claude Code 技能，因此 Agent 无需手把手指导即可使用。
• 本地运行，保护隐私。 像素对比、OCR 和布局提取都在你的设备上运行。图像不会离开你的设备，也不需要 API 密钥。

复制 UI 的风格，而不只是匹配它

逐像素匹配截图是一项工作。另一项工作是：构建一个不同的屏幕，同时让它看起来像是同一套设计系统的一部分。one-shot-ui 会从参考图中提取设计语言，并以确定性的方式验证新 UI 是否符合要求，无需依赖像素基准。

# Extract a reusable style system — palette, spacing scale, type ratio, radii, elevation
one-shot-ui tokens reference.png --emit shadcn      # or: tailwind | json

# Build a different screen in that style, then check it conforms
one-shot-ui style-check reference.png ./pricing.html

它会报告实测数据，把审美判断留给 Agent：它不会指定你的“主”色，也不会判断整体氛围——这些由你根据图像来决定（你是视觉模型；这个工具就是你精准、不会产生幻觉的双眼）。一致性评估基于截图能够可靠呈现的内容——调色板、间距节奏、字体大小比例；而圆角程度和层次感则仅作为建议提示，因为光栅图像无法确定这些特征。

安装

npm install -g one-shot-ui

对于需要浏览器的命令（capture、run）：

npx playwright install chromium

快速开始

# Diff your implementation against a reference and see exactly what's off
one-shot-ui compare reference.png build.png --json --heatmap heatmap.png

# Get copy-paste CSS fixes, ranked by impact
one-shot-ui suggest-fixes reference.png build.png --json

# The step that gets you pixel-perfect: trial fixes in a live browser and keep
# only the ones that provably reduce pixel mismatch — outputs a verified patch,
# a structural fidelity score, and any reference text your build hides or clips
one-shot-ui converge reference.png --impl ./index.html

# Or run the full automated loop until it converges
one-shot-ui run reference.png --impl ./index.html --max-passes 5 --threshold 0.02

每条命令都支持 --json，以便输出结构化且适合 Agent 使用的结果。

与编码 Agent 搭配使用

one-shot-ui 附带一个 AGENTS.md（Claude Code、Cursor、Codex 和其他 Agent 工具可自动发现）以及一个供 Claude Code 使用的 skill/SKILL.md。

只需一行即可安装技能：

mkdir -p .claude/skills/one-shot-ui && cp "$(npm root -g)/one-shot-ui/skill/SKILL.md" .claude/skills/one-shot-ui/

将其用作 MCP 服务

one-shot-ui 也可以作为本地 MCP 服务运行，因此任何支持 MCP 的 Agent（Claude Code、Cursor、Cline、Windsurf、VS Code）都可以将 compare、converge、suggest_fixes、extract、tokens、plan 和 style_check 作为工具调用——无需编写 Shell 胶水代码。它通过 stdio 运行，不会发起网络请求，也不需要 API 密钥。

claude mcp add one-shot-ui -- npx -y one-shot-ui mcp

也可以将其添加到任意客户端的 MCP 配置中：

{
  "mcpServers": {
    "one-shot-ui": {
      "command": "npx",
      "args": ["-y", "one-shot-ui", "mcp"]
    }
  }
}

请参阅 docs/MCP.md，了解各客户端的配置方法和注册表发布说明。

命令

命令	用途	主要标志
extract	将截图分析为布局、颜色和文本数据	--json、--no-ocr、--overlay、--fine
compare	对两张截图进行像素级和结构差异比较	--json、--heatmap、--dom-diff
tokens	设计令牌和可复用的样式系统（调色板、间距、字体、圆角）	--json、--emit shadcn|tailwind|json
style-check	检查新 UI 是否符合参考图的设计语言	--json（新 UI 可以是 URL / HTML / 截图）
plan	生成实施策略	--json
capture	截取 URL 或本地 HTML 文件的屏幕截图	--url、--file、--output
suggest-fixes	根据差异提供 Tailwind/CSS 修复建议	--json、--top、--dom-diff、--framework
converge	闭环优化器：经过像素验证的 CSS 补丁 + 结构保真度评分，并标记隐藏或裁切的文本	--impl、--out、--json、--budget-seconds
run	多轮执行 extract→capture→compare→fix 循环	--impl、--max-passes、--threshold
benchmark	运行基准测试套件	--json、--output

工作原理

1. extract — 将参考图分割为布局区域，采样颜色和令牌，并对文本进行 OCR。
2. capture — 在匹配的视口下截取你的实现（URL 或本地 HTML）的屏幕截图。
3. compare — 对齐两张截图，计算像素热力图和结构差异，并对每个问题进行分类（布局 / 颜色 / 字体 / 间距），同时判断其是否可操作。
4. suggest-fixes — 将问题转化为具体的 CSS 编辑建议，并按优先级排序。

run 会循环串联以上四个命令，直到差异低于 --threshold。

开发

需要 Bun。

bun install
bun run install:browsers   # Playwright Chromium
bun run typecheck

开发脚本可直接从源代码运行：

bun run dev:extract -- ./reference.png --json
bun run dev:compare -- ./reference.png ./build.png --json

构建用于 npm 的版本：

bun run build

许可证

MIT