vlmkit

vrt

vlmkit 是一款基于 Playwright + pixelmatch 构建的 TypeScript 视觉回归工具包。除了原始像素差异，它还会呈现适合 Agent 的 信号：将计算样式差异拆分为通用差异与受断点限制的差异、针对组件边界框计算各分区的 diffRatio、内嵌最差视口的截图路径，以及（可选）由 VLM 输出的 CHANGE 列表，供 LLM CSS 修复步骤使用。

源码：https://github.com/mizchi/vlmkit。CHANGELOG + 旧 CLI 到新 CLI 的映射：CHANGELOG.md。

何时调用此技能

• Agent 修改了 CSS / HTML / 组件，而你需要了解“哪些内容发生了可见变化，以及变化在哪里”。
• 你正在审查重构 PR，检查是否出现非预期的布局偏移。
• 你正在比较两个 URL（开发服务器与预览部署；基线与变体）。
• 你想设置一个 CI 门禁，用于标记 PR 中的回归。
• 你正在替换框架 / CSS 库，需要验证重写后的视觉效果是否等同。

何时不应调用

• 对纯数据结构进行快照测试（使用 Jest 快照）。
• 检查 CLS/LCP/FCP 以外的 Lighthouse / Web Vitals（直接使用 Lighthouse）。
• 不涉及差异组件的纯浏览器驱动流程（使用 Playwright Test）。
• 检查 AI 生成的截图是否内容正确（使用 review-image 之类的视觉 LLM 工具）。

安装

前置条件：Node 24+。 CLI 和工作区软件包都依赖 Node 的 --experimental-strip-types（在 24+ 中默认启用）。 Node 22 无法运行——安装前请使用 node --version 检查。使用 nvm install 24 && nvm use 24（或 fnm / volta / 你偏好的版本管理器）进行升级。

安装前检查：运行 scripts/doctor.sh，一次性验证 Node 版本、Playwright Chromium、可选 API 密钥和已安装的子技能。根据安装阶段有两种调用方式：

• 安装前（尚未安装 apm）：通过 curl 一次性运行 — bash <(curl -sSL https://raw.githubusercontent.com/mizchi/skills/main/vlmkit/scripts/doctor.sh)
• 安装后（已完成 apm install -g mizchi/skills/vlmkit/vlmkit）：运行本地副本 — bash ~/.claude/skills/vlmkit/scripts/doctor.sh

严重性规则：只有 Node 24+ 和 Playwright Chromium 属于 FAIL 级（会阻止以 0 退出）。其他所有项目——包括尚未加入 PATH 的 vrt CLI——都按设计列为 WARN，因为该脚本需要能够在安装过程中运行（首次运行时，vlmkit CLI 出现 WARN 是预期情况；先解决所有 FAIL，安装 vrt，然后重新运行，WARN 就会消失）。

# CLI (global)
pnpm add -g @mizchi/vrt
# or per-project
pnpm add -D @mizchi/vrt
npx playwright install chromium

# Library packages (deep imports via .ts source)
pnpm add @mizchi/vlmkit-core @mizchi/vlmkit-capture @mizchi/vlmkit-markup @mizchi/vlmkit-ai

CLI 速查表（0.5.0 动词组）

以下命令使用的 I/O 约定：--output <dir> 始终接受目录路径（引擎会在其中写入 diff-report.json 和各视口的 PNG）。vlmkit diff agent 默认将 Markdown 写入标准输出；传入 --out <path> 可改为写入文件。 接受两个位置参数的命令（例如 vlmkit diff html <baseline> <variant>）可以接受两个本地文件路径或两个 URL；如果想明确指定，请使用 --url/--current-url。

# Diff
vlmkit diff html <baseline> <variant> --output reports/        # → reports/diff-report.json + PNGs (dir output)
vlmkit diff agent reports/diff-report.json [--out diff.md]     # → stdout (default) or --out path
vlmkit diff png  base.png current.png                          # Direct PNG diff (positional files)
vlmkit diff elements --selector .card …                        # Element-level shift isolation
vlmkit diff browsers <url>                                     # Chromium / Firefox / WebKit parity
vlmkit diff runs <dirs...>                                     # Aggregate N VRT runs

# Snapshot (baseline + diff lifecycle)
vlmkit snapshot <url1> [url2]... --output snapshots/
vlmkit snapshot approve                                        # Promote current → baseline
vlmkit snapshot stability <url...> --iterations 5              # FP-rate measurement
vlmkit snapshot flipbook --output snapshots/                   # Embed PNGs in a self-contained HTML

# Check (CI gates)
vlmkit check a11y contrast|touch|focus <html>                  # WCAG scans
vlmkit check tokens <html>                                     # Design-token scale conformance
vlmkit check theme  <html>                                     # prefers-color-scheme parity
vlmkit check perf   <html>                                     # CLS / LCP / FCP

# Inspect / Stress / Scan / Build
vlmkit inspect interact|explore|smoke <html|url>
vlmkit stress  i18n|media  <html>
vlmkit scan    component|breakpoints  <…>
vlmkit build   component <target.png> <current.html>           # Markup-from-screenshot loop

# Migration (framework / CSS-library swap audit). Three modes:
#   compare  — deterministic side-by-side audit; the default. Start here.
#   blind    — variant agent never sees baseline pixels (forces convergence from spec text alone).
#   subagent — dispatched subagent runs `compare` + writes a verdict.
# `--mask` and `--output` work identically across all three modes.
vlmkit migration compare|blind|subagent <baseline> <variant> --output reports/

# Long-running / stateful
vlmkit watch       <baseline> <variant>                        # File-watcher inner loop
vlmkit manifest    add|list|rm|check                           # Approval rules
vlmkit diff-pr     pin|verify|post                             # PR CI gate
vlmkit baseline    pin|verify|post|list|rm                     # Canonical alias of diff-pr

0.4.x 中的单词元命令（vrt compare、vrt png-diff、vrt theme-parity 等）仍会作为弃用兼容命令保留，输出一行提示后转发执行。

子技能路由

按设计分为两个仓库：此引导技能位于 mizchi/skills（通用 技能）；五个 vrt 专用子技能位于 mizchi/vlmkit/vlmkit 的 .claude/skills/ 下。下面两个 apm install 路径看起来不同， 是因为它们指向不同的仓库——这是有意为之，并非笔误。

即使未安装任何子技能，CLI 也能完整运行—— 子技能是面向 Agent 的参考资料，可针对特定任务类型扩展路由能力。只有在 Agent 需要额外上下文时才安装；从命令行运行 vrt 的终端用户永远不需要安装。

范围边界：此引导技能仅负责路由。确定要加载哪个子技能后，更深入的操作细节——完整的标志列表、 持久化路径（例如回归监控所用的 .vrt/last-diff-for-agent.json）、 各模式的语义、输出架构——都在对应的子技能中。Agent 需要这些详细内容时，可通过上面的 apm 命令安装。

apm install mizchi/vlmkit/.claude/skills/<skill-name>

根据任务类型选择：

子技能	适用场景	入门工作流
vrt-visual-diff	一次性确认“这次 CSS 编辑是否改变了像素，以及改动在哪里？”	vlmkit diff html → vlmkit diff agent
vrt-regression-watch	跨多次运行的 CI 门禁 / 定期漂移检测	vlmkit diff agent --previous --fail-on-regression
vrt-migration-eval	框架 / CSS 库 / 构建系统替换审计（有意产生较大差异）	vlmkit migration compare|blind|subagent
vrt-markup-synth	截图 → HTML/CSS、令牌 / 主题 / i18n / a11y 审计	vlmkit build|scan|check|stress
vrt-css-fix-loop	使用 VLM + LLM 自动修复 CSS 的循环	fix-loop.ts (VRT_VLM_MODEL=…)

路由启发式（用户说明任务后，问自己一次）：

Is the markup deliberately different (rewrite / framework swap)?
├─ yes → vrt-migration-eval
└─ no
   ├─ Need to detect change between runs over time? → vrt-regression-watch
   ├─ Want a CSS-fix loop (auto-repair)?          → vrt-css-fix-loop
   ├─ Building from a screenshot / token audit?   → vrt-markup-synth
   └─ One-shot "what changed"                     → vrt-visual-diff

输出结构

vlmkit diff html 会写入：

<output>/
├── diff-report.json            # canonical machine input for diff agent
├── migration-report.json       # legacy alias, byte-identical (will be removed)
├── diff-mobile.png             # per-viewport pixel diff
├── diff-desktop.png
└── diff-wide.png

随后，vlmkit diff agent <report.json> 会生成以下结构的 Markdown：

# VRT diff (for agent)

### Diff by viewport (worst first)
| Viewport | Diff | Dominant category | Categories | Shift bands |
| ...

### Verified deltas (computed-style) × viewport     ← HOISTED to #2
#### Universal pairs         ← fix the base rule
#### Breakpoint-gated pairs  ← fix or add @media rule

### Per-section diffRatio
### Heuristic fix candidates

置顶的 已验证差异 是最关键的信号——先查看通用配对项，再查看断点条件项，最后深入查看各分区。

常见问题

• 遮罩至关重要。 对于任何在多次运行间会波动的内容，都传入 --mask ".marquee,.timestamp, [data-testid='live-counter']"。 意外的基线噪声差异几乎总是因为缺少遮罩， 而不是真正的回归。
• 输出是目录，而不是文件。 --output reports/ 会生成 reports/diff-report.json 和 PNG。将 JSON 路径（而非目录） 传给 vlmkit diff agent。
• 必须安装 Playwright。 首次运行报错 "browser not found" → npx playwright install chromium。
• 不加遮罩、对同一 URL 进行自比较，就是误报基线。 在依赖差异百分比阈值之前， 可用它验证 --mask 是否确实捕获了所有波动元素。
• dist 二进制已打包。 dist/vlmkit.mjs 包含所有经代码拆分的叶节点。 安装时不依赖源代码。

环境变量

变量	用途	默认值
VRT_LLM_PROVIDER	fix-loop 的 LLM 提供方（gemini / openrouter / anthropic）	gemini
VRT_LLM_MODEL	覆盖 LLM 模型	提供方默认值
VRT_VLM_MODEL	VLM 模型（OpenRouter ID，或 gemini:/claude: 前缀）	bytedance/ui-tars-1.5-7b
OPENROUTER_API_KEY / GEMINI_API_KEY / ANTHROPIC_API_KEY	各提供方的身份验证	—
VRT_CAPTURE_BACKEND	local（默认 Playwright）或 cloudflare（Browser Run）	local
DEBUG_VRT	详细日志输出	未设置

库的使用（vrt-core / vrt-capture / vrt-markup / vrt-ai）

当 CLI 提供的功能不够用时，可深度导入相关软件包：

import { compareScreenshots } from "@mizchi/vlmkit-core/heatmap.ts";
import { discoverViewports }  from "@mizchi/vlmkit-capture/viewport-discovery.ts";
import { extractComponents }  from "@mizchi/vlmkit-markup/component/component-extract.ts";
import { askVlm }             from "@mizchi/vlmkit-ai";

轻量级功能（图像 / DOM / a11y 基元）中，@mizchi/vlmkit-core 不依赖 Playwright。其他三个软件包会传递引入 Playwright。

报告问题 / 贡献

• 问题 / 功能请求：https://github.com/mizchi/vlmkit/issues
• 源码：https://github.com/mizchi/vlmkit
• 提交 PR 前的冒烟测试门槛：bash scripts/smoke-dist.sh（严格模式，针对打包后的 dist/vlmkit.mjs 进行 11 项探测）。