内容
<div align="center">
# 一次性 UI
### 捕捉肉眼无法察觉的细节。
**用于 AI 编程代理的确定性截图差异检测。**
将参考截图转化为结构化数据，将任何构建版本与其进行差异检测 - 像素、布局、颜色和类型 - 然后获取确切的 CSS 进行修复。
[](https://www.npmjs.com/package/one-shot-ui)
[](./LICENSE)
[](https://www.npmjs.com/package/one-shot-ui)
<img src="https://raw.githubusercontent.com/TN0123/one-shot-ui/main/assets/hero.png" alt="one-shot-ui 将代理的构建版本与参考截图进行差异检测，并标记确切的差异" width="100%">
</div>
## 问题所在
AI 代理在 UI 上 **几乎完成** - 然后停滞不前。布局看起来是正确的，但某个卡片高了 8 像素，某个面板颜色不对，阴影是扁平的，间隙偏移了 24 像素。要求模型“再看一下截图并修复”很慢，而且每次得到的结果都不同。
`one-shot-ui` **确定性地** 解决了最后 10% 的问题。它从参考截图中提取结构化数据 - 布局区域、颜色、排版、间距、设计令牌 - 将您的实现与其进行差异检测，并返回 **具体的、排名的修复**，而不是“使其看起来更像这样”。
```
将宽度设置为 616px（当前为 640px）
将填充颜色更改为 #303040。
将 box-shadow 设置为 -3px 0px 24px 0px rgba(28, 29, 38, 0.32)。
gap: 176px; /* 当前约为 152px */
```
> 复制并粘贴 CSS，按视觉影响排名 - 上面的每个示例都是下面运行的实际输出。
## 观察其收敛
<div align="center">
<img src="https://raw.githubusercontent.com/TN0123/one-shot-ui/main/assets/converge.gif" alt="one-shot-ui 运行循环：差异热图从剧烈到静止" width="100%">
</div>
`运行` 命令循环执行 **提取 → 捕获 → 比较 → 修复**，直到热图静止。在上面的运行中，代理的第一个构建版本看起来与肉眼相同 - `one-shot-ui` 标记了 **15 个具体的差异**（位置、大小、颜色、阴影、间距），并且循环驱动构建版本达到 **约 2.5% 的像素差异**，在约 0.5% 的范围内达到该工具自己的估计 **不可减少的** 底线（≈2%，亚像素字体渲染）。
## 为什么选择 one-shot-ui
- **确定性，而不是凭感觉。** 稳定的像素 + 结构差异分数 - 相同的输入，相同的数字 - 因此您可以根据“是否足够接近？”来控制 CI。
- **确切的修复，而不是微调。** 它返回具体的 CSS（`width: 616px`，`#303040`，`gap: 176px`），按组件分组并按视觉影响排名。
- **结构性，而不仅仅是像素。** 检测缺失/额外的元素、位置和大小变化、颜色、阴影、间距和排版 - 并标记哪些差异是 **不可减少的**（抗锯齿、摄影内容），以便代理不会追逐幽灵。
- **代理原生。** 随附一个 `AGENTS.md`（由 Claude Code、Cursor、Codex 等自动发现）以及一个 Claude Code 技能，以便您的代理在无需人工干预的情况下驱动它。
- **本地且私有。** 像素差异检测、OCR 和布局提取都在您的机器上运行。没有图像离开您的电脑，也不需要 API 密钥。
## 安装
```sh
npm install -g one-shot-ui
```
对于需要浏览器的命令（`capture`、`run`）：
```sh
npx playwright install chromium
```
## 快速入门
```sh
# 将您的实现与参考进行差异检测，并查看具体的问题
one-shot-ui compare reference.png build.png --json --heatmap heatmap.png
# 获取按影响排名的复制粘贴 CSS 修复
one-shot-ui suggest-fixes reference.png build.png --json
# 达到像素完美的步骤：在实时浏览器中进行试验性修复，并仅保留那些能够证明减少像素差异的修复 - 输出一个已验证的补丁
one-shot-ui converge reference.png --impl ./index.html
# 或者运行完整的自动化循环，直到收敛
one-shot-ui run reference.png --impl ./index.html --max-passes 5 --threshold 0.02
```
每个命令都支持 `--json` 以获取结构化、代理友好的输出。
## 与您的编码代理一起使用
`one-shot-ui` 随附一个 `AGENTS.md`（由 Claude Code、Cursor、Codex 等自动发现）以及一个 `skill/SKILL.md` 用于 Claude Code。
通过一行命令安装技能：
```sh
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](https://modelcontextprotocol.io) 服务器运行，因此任何支持 MCP 的代理（Claude Code、Cursor、Cline、Windsurf、VS Code）都可以调用 `compare`、`suggest_fixes`、`extract`、`tokens` 和 `plan` 作为工具 - 无需 shell 粘合剂。它通过 stdio 运行，不进行网络调用，也不需要 API 密钥。
```sh
claude mcp add one-shot-ui -- npx -y one-shot-ui mcp
```
或添加到任何客户端的 MCP 配置：
```json
{
"mcpServers": {
"one-shot-ui": {
"command": "npx",
"args": ["-y", "one-shot-ui", "mcp"]
}
}
}
```
有关每个客户端的设置和注册表发布的详细信息，请参见 [docs/MCP.md](./docs/MCP.md)。
## 命令
| 命令 | 目的 | 关键标志 |
|---------|---------|-----------|
| `extract` | 将截图分解为布局、颜色和文本数据 | `--json`、`--no-ocr`、`--overlay`、`--fine` |
| `compare` | 两个截图之间的像素 + 结构差异 | `--json`、`--heatmap`、`--dom-diff` |
| `tokens` | 提取设计令牌（颜色、间距、半径） | `--json` |
| `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` | 多次传递提取 → 捕获 → 比较 → 修复循环 | `--impl`、`--max-passes`、`--threshold` |
| `benchmark` | 运行基准测试套件 | `--json`、`--output` |
## 工作原理
1. **extract** - 将参考分成布局区域，采样颜色/令牌，并进行 OCR 文本。
2. **capture** - 在匹配的视口中截图您的实现（URL 或本地 HTML）。
3. **compare** - 对齐两个，计算像素热图 **和** 结构差异，并分类每个问题（布局 / 颜色 / 排版 / 间距）以及它是否可操作。
4. **suggest-fixes** - 将问题转化为具体的、排名的 CSS 编辑。
`run` 将这四个步骤在一个循环中链接起来，直到差异低于 `--threshold`。
## 开发
需要 [Bun](https://bun.sh)。
```sh
bun install
bun run install:browsers # Playwright Chromium
bun run typecheck
```
开发脚本直接从源代码运行：
```sh
bun run dev:extract -- ./reference.png --json
bun run dev:compare -- ./reference.png ./build.png --json
```
为 npm 构建：
```sh
bun run build
```
## 许可证
MIT
