visionaire-engine

# Visionaire 引擎 > **哪条规则、哪个文件、哪行代码 — 以及为什么它赢了。** [](https://www.npmjs.com/package/visionaire-engine) [](https://github.com/mi60dev/visionaire-engine/actions/workflows/ci.yml) [](LICENSE) [](https://glama.ai/mcp/servers/mi60dev/visionaire-engine)  **问题：** 某些东西看起来不对劲。你截图并解释，LLM 猜测错误，你重新解释。 **解决方案：** Visionaire 读取实时页面并为 LLM 提供确切的规则、文件和行。正确的修复，第一次尝试。  **您不必撰写一段文字来解释 2px 边距错误——现在您不必这样做。** 更少的解释，更多的修复：为开发者、Vibe 编码器和任何与 LLM 合作以交付网站设计变更的人员而建。 **状态：v0.7** — 28 个工具，435 个测试（252 个单元测试 + 183 个端到端测试，基于真实 Chrome），24 个案例种子错误基准测试（`npm run bench`），针对 wordpress.org 进行实时验证。 <details> <summary><strong>更新内容，按版本划分</strong></summary> - **v0.7 — 验证层：** `assert_visual`（17 种断言语法 — PASS/FAIL 结果与测量像素、违规 UID 和可重运行的命名套件），`visual_diff`（与模型或记录基线相比的像素差异，差异区域映射到元素 UID），`impact_preview`（编辑共享选择器之前的辐射范围 + 沙盒试运行），`diagnose`（排名“为什么这会损坏”的罪魁祸首与测量证据），`responsive_sweep`（一次调用 → 每视口判决矩阵），`capture_proof`（具有判决增量的前后证据包）；用于 Claude Code 和 Cursor 的验证后编辑机制（`npx visionaire-engine init-harness`）；`style_diff { capture_pixels }` 基线；`check_alignment` 弃用，改为 `assert_visual` - **v0.6 — 像素完美包：** `check_alignment`（组对齐 / 间隙节奏 / 网格 / 像素快照审计）和 `pick_color`（实际绘制像素采样 + WCAG 对比度判决） - **v0.5:** `inject_css` — 实时修复循环（在页面上试运行修复，查看更改，收敛，编写源代码一次）；`navigate { bypassCache }` 用于静态样式表硬重载；`explain_styles` 上的辐射范围 + 作用域修复报告（更改 *该* 按钮，而不是所有按钮） - **v0.4（现场报告项目）：** `interact` 以驱动 UI 进入状态并检查它；`measure_element` 用于子像素字形/文本墨水居中；`evaluate` 出口；`annotated_screenshot` 上的元素作用域裁剪/缩放；`find_elements` 上的 `match:"any"` / `visibleOnly:false`；零配置冷启动 Chrome 发现 - **v0.3:** 时间维度 — 事件监听器归属，动画诊断，源归属交互时间线 - **强化为不受信任的页面：** 提示注入净化，失败快速看门狗，对话框自动关闭 </details> ## 问题，在野外 AI 编码代理在结构上对它们渲染的内容是盲目的。它们将 CSS 作为文本发出，但从未看到返回的像素 — 所以它们猜测，坚持认为猜测有效，然后循环。社区现在有一个名称：**“CSS 幻觉。”** Visionaire 为代理提供确定性的眼睛来查看实时渲染 — 测量的几何形状，实际的级联获胜者，PASS/FAIL 结果 — 因此循环结束。 如果您想先听听其他人怎么说，请从这里开始： - **[为什么 AI 不擅长前端](https://nerdy.dev/why-ai-sucks-at-front-end)** — Adam Argyle 解释为什么模型无法推理他们无法感知布局。 > *"这是一个大型语言模型，而不是渲染引擎！它对数学非常糟糕，给它截图几乎没什么用。它是在黑暗中摸索。"* - **[AI 是否导致前端失去十年？](https://mastrojs.github.io/blog/2026-05-23-is-AI-causing-a-repeat-of-frontends-lost-decade/)** — Mauro Bieg 讨论 AI 生成前端的更广泛成本。 > *"AI 正在启用很多 AI 垃圾 — 但这并不意味着我们仍然不需要了解自己在做什么的人。"* ## 缺口 今天要求 LLM 修复视觉错误，它会收到两个不完整的图片：像素，没有链接回代码，或者代码，没有关于实际屏幕上赢的是什么的渲染真相。现有的浏览器 MCP 使设计工作变得更糟 — 它们提供可访问性快照，刻意删除所有样式。 缺少的是 **解释和归属**: - *哪* 个 CSS 规则赢得该属性的级联，为什么其他规则会输？ - *哪个* 文件、*哪行* 代码是赢家所在 — 或者哪个 Elementor 小工具控件，或者哪个 Customizer 条目？ - *为什么* 元素不可见、未对齐或大小错误？ Visionaire 用零 AI 回答这些问题 — 所有内容都从 Chrome DevTools Protocol 和封闭规则集确定计算。模糊的部分（将“英雄下的按钮看起来不对劲”匹配到实际元素）留在调用 LLM，它获得 uid 键控快照、搜索工具和注释截图，以便便宜地完成。 ## 输出是什么样子 实时对抗 wordpress.org： ``` 为什么 color = rgb(255, 255, 255): WINNER [class*=wp-block] .wp-block-button__link { color: var(--wp--custom--button--color--text) } spec(0,2,0) → themes/wporg-parent-2021/build/style.css:499 [line | theme: wporg-parent-2021 — edit themes/wporg-parent-2021/build/style.css] lost (specificity) :root :where(.wp-element-button, .wp-block-button__link) { color: #fff } spec(0,1,0) → global-styles-inline-css:2 [db-entity | Global Styles — Site Editor → Styles (theme.json / wp_global_styles)] lost (origin) a:-webkit-any-link { color: -webkit-link } spec(0,1,1) → user-agent stylesheet ``` 获胜者、失败者及其决定性失败原因，以及每个获胜者的诚实编辑指针 — 包括 WordPress 感知答案，如“站点编辑器 → 样式”而不是无用的路径到生成的 文件。 ## 快速开始 需要 Node ≥ 20 和已安装的 Chrome/Chromium。 最快的路径 — 直接从 npm 注册到 Claude Code（无需克隆，无需构建）： ```bash claude mcp add visionaire -- npx -y visionaire-engine ``` 或者，从克隆（用于开发或固定本地构建）： ```bash git clone https://github.com/mi60dev/visionaire-engine && cd visionaire-engine npm install && npm run build claude mcp add visionaire -- node "$PWD/dist/index.js" ``` 使用 **GitHub Copilot, Cursor, Claude Desktop, Google Antigravity** 或其他客户端？请参阅 **[docs/clients.md](docs/clients.md)** 以获取每个客户端的复制粘贴配置，以及 Linux/WSL/Docker 的浏览器安装帮助。 **从您的项目根目录运行** — Visionaire 在代理拥有正在运行的站点 *和* 其源代码磁盘时效果最佳，因此它可以交叉引用两者。在搜索之前先进行 `page_snapshot`（或读取源代码），以获取实际的元素名称而不是猜测选择器。如果选择器匹配的内容为空，则错误提示最接近的实际 ID/类。 然后，在会话中： 1. `connect { url: "https://your-site.com" }` — 启动 Chrome（或 `{ browserUrl: "http://127.0.0.1:9222" }` 以附加到您真实的、已登录的浏览器） 2. `page_snapshot {}` — 具有 uid 的可见内容的修剪树 — 几何形状、布局提示、不可见原因 3. `explain_styles { uid: "e17", property: "margin-bottom" }` — 属性的级联判决与文件：行 在没有 MCP 客户端的情况下试用： ```bash npm run demo # 捆绑的固定装置 npm run demo -- https://wordpress.org --selector "a.wp-block-button__link" ``` ## 28 个工具 **会话和接地** — 连接并找到正确的元素，而无需猜测。 | 工具 | 目的 | |---|---| | `connect` / `navigate` / `set_viewport` | 启动或附加到 Chrome，前往 URL（`bypassCache` 用于硬重载），模拟视口 | | `page_snapshot` | 修剪的、uid 键控的可见内容树 — 几何形状、布局提示、不可见原因 | | `page_origins` | 样式表清单 + 平台检测（WordPress 版本、主题、构建器、优化器） | | `find_elements` | 通过文本、选择器、角色或屏幕区域确定搜索 — 默认 AND 组合，`match:"any"` 用于联合，`visibleOnly:false` 包括隐藏元素 | | `node_at_point` | x, y → 元素 uid + 祖先链 | | `pick_element` | 人机协作接地：DevTools 样式悬停高亮，用户点击看起来错误的元素 | **解释** — “为什么”，附带收据。 | 工具 | 目的 | |---|---| | `inspect_element` | “是什么”：盒模型、计算值、可见性判决 | | `explain_styles` | **楔形。** 属性的级联获胜者/失败者与文件：行 + 来源归属，每个获胜者的 **辐射范围** （影响多少其他元素），以及仅针对该元素的范围修复选择器 | | `inspect_ancestors` | 约束链遍历：哪个祖先约束宽度/溢出/堆叠 | | `get_listeners` | 元素及其祖先上的事件监听器，附带处理程序文件：行和捕获/被动/一次性标志 | | `explain_animations` | 触及元素的动画/过渡：实时普查、声明规则附带文件：行和封闭的“为什么不流畅”的规则集 | **像素级检查** — v0.6 新增。 | 工具 | 目的 | |---|---| | `measure_element` | 子像素渲染几何形状：内容框 + 真实文本墨水框（字形范围）附带居中判决 — “这个 × 实际居中吗？” | | `check_alignment` | *(弃用 → `assert_visual`)* 组像素审计：哪些元素中的 N 个偏移了多少像素、间隙节奏异常、大小一致性、N 像素网格一致性、像素快照警告 | | `pick_color` | 实际绘制像素（复合真值：渐变、图像、不透明度）+ 计算颜色 + WCAG AA/AAA 对比度判决 | **交互与时间** — 状态，而不仅仅是快照。 | 工具 | 目的 | |---|---| | `interact` | 驱动 UI 进入状态（打开菜单/弹出窗口/模态框，显示选项卡）并 **将其留在那里** 以便您可以检查新状态 — 报告操作后可见性 + 盒模型 | | `record_interaction` | 一次交互 → 源归因因果时间线：处理程序、突变、已取消的过渡、布局偏移 | **修复和验证** | 工具 | 目的 | |---|---| | `inject_css` | 实时修复循环：元素的试用声明（或页面范围规则）而无需触摸源代码 — 查看更改、收敛、一次编写源代码、恢复 | | `style_diff` | 记录样式、比较后验证 — 验证我的修复循环 | | `evaluate` | 出口：运行代理编写的 JavaScript 页面并获取 JSON 结果，对于没有其他工具涵盖的真正定制情况 | | `annotated_screenshot` | 带有编号标记的截图，等于快照 uid — 或通过 `clipTo` 使用 `padding`/`scale` 缩放和可选 `annotate:false` 的元素范围裁剪 | **验证和证明** — v0.7 新增。 | 工具 | 目的 | |---|---| | `assert_visual` | **验证门控。** 状态渲染几何声明（相等高度、对齐、间隙、裁剪、颜色、z 顺序 — 17 种断言类型）→ 确定性 PASS/FAIL 带有测量像素和违规 uid；注册命名套件并在每次编辑后重新运行 | | `visual_diff` | 将实时页面（或一个元素）与模型 PNG 或记录的基线进行像素差异比较 — MATCH/DIVERGENT 带有差异区域映射回元素 uid，可选热图伪影 | | `impact_preview` | 编辑共享选择器之前的辐射范围报告：谁 else 匹配，带有 uid 的分组 + 沙盒试运行，预测哪些元素会更改 | | `diagnose` | 一次性“为什么看起来损坏了” — 带有测量证据的排名罪魁祸首，用于剪辑、溢出、偏离中心、不可见性、重叠、大小错误 | | `responsive_sweep` | 跨多个视口的验证负载 → 每个视口的判决矩阵（“在桌面上修复，但在移动设备上仍然损坏”在一调用中捕获） | | `capture_proof` | 前后证据包：带判决增量的注释截图 + 判决增量，证明修复翻转 FAIL → PASS | 完整参考：[docs/tools.md](docs/tools.md) ## 验证循环（停止 CSS 幻觉） 代理编辑样式表，读取自己的差异，并声明“现在卡片等高” — 而不เคย看到一个渲染像素。Visionaire 为您的代理提供确定性的渲染真相验证循环： 1. **预览** 共享类辐射范围 → `impact_preview`。 2. **编辑** 最小更改。 3. **断言** 您的声明 → `assert_visual`（或重新运行命名 `suite_id`）。您获得 PASS/FAIL + 实际测量像素 + 违规元素 uid。 4. **诊断** 任何 FAIL → `diagnose` 返回带有证据的排名罪魁祸首。 5. **扫描** 响应式 → `responsive_sweep` 返回每个视口的判决矩阵。 6. **证明** 它 → `capture_proof` 捆绑前后截图 + 判决增量。 实际输出 — 修复前后的相同套件： ```json { "verdict": "FAIL", "summary": "1 assertion: 0 PASS, 1 FAIL — registered as suite 'cards' (re-run with just {\"suite_id\":\"cards\"})", "results": [ { "type": "equal_height", "verdict": "FAIL", "id": "cards-equal", "measured": { "values": [412, 388], "unit": "px", "delta": 24, "tolerance_px": 1 }, "offending_uids": ["e1", "e2"] }, ], "truncated": false, "suite_id": "cards" } ``` …修复 CSS，重新运行仅 `{ "suite_id": "cards" }`: ```json { "verdict": "PASS", "summary": "1 assertion: 1 PASS, 0 FAIL", "results": [ { "type": "equal_height", "verdict": "PASS", "id": "cards-equal", "measured": { "values": [412, 412], "unit": "px", "delta": 0, "tolerance_px": 1 } }, ], "truncated": false, "suite_id": "cards" } ``` 从项目根目录运行 `npx visionaire-engine init-harness` 以启用包含的 Claude Code 钩子（或 Cursor 规则），以便代理无法在没有记录验证的情况下结束调用“它已修复”。 如何标记、钩子和停止门控：[docs/harness.md](docs/harness.md)。 ## 文档 - [docs/clients.md](docs/clients.md) — 在 Claude、Copilot、Cursor、Antigravity 等 MCP 客户端中安装 - [docs/tools.md](docs/tools.md) — 1.0) — 工具逐一介绍及实际示例 - [docs/harness.md](docs/harness.md) — 验证后编辑机制（钩子、标记、`init-harness`） - [docs/architecture.md](docs/architecture.md) — 确定性管道工作原理 - [docs/wordpress.md](docs/wordpress.md) — WordPress 源解析指南 - [docs/development.md](docs/development.md) — 构建、测试、扩展 ## 设计原则 1. **无内部 LLM** — 确定性、可缓存、可测试、主机无关。 2. **调用 LLM 的模糊定位属于调用 LLM 的范畴**；我们使其便宜。 3. **补充现有的浏览器 MCP（相同的 uid 标识符）**，而不是竞争。 4. **每个属性的诚实阶梯**：`line > file > db-entity > component > generated > unknown`。 5. **基于令牌的输出预算** — 一个档案是 300–800 个令牌，从不倾倒。 ## 安全姿态 Visionaire 指向任意不受信任的页面，因此它将页面内容视为敌对的： - **提示注入防御。** 页面派生字符串（元素文本、类名、ID、属性值）在单个阻塞点（它们进入工具输出的地方）被净化 — 折叠为一行，剥夺控制和双向覆盖字符，并根据长度上限进行长度限制。页面无法走私指令形状的文本，格式为“系统消息”到达调用 LLM；此类内容只能作为惰性、引用、截断的片段出现。 - **快速失败，永不挂起。** 每个工具调用都包裹在一个监护人中（默认 60 秒，`VISIONAIRE_TOOL_TIMEOUT_MS` 来覆盖；`pick_element`/`record_interaction` 获得其声明的等待 + 松弛）。卡住的浏览器返回一个可操作的错误，告诉你重新连接`connect`，而不是阻塞客户端。 - **不死锁对话框。** 页面 `alert()`/`confirm()`/`prompt()` 调用会自动关闭 — 否则它们将无限期阻塞每个 CDP 调用。 Visionaire 从不执行页面作者的代码作为指令；它只读取和属性。 调用 LLM 仍应将工具输出视为页面的数据，而不是命令。 ## 已知限制 - 仅限 Chromium（CDP 是匹配规则源位置的唯一路径；`getMatchedCSSRules` 已从浏览器中删除多年前的功能）。 - `@layer`：无层叠顺序与分层顺序相同；不同层链之间的顺序是确定性代理（CDP 不公开层声明顺序）。 - 我们依赖的一些 CDP 字段（`specificity`、`layers`）是实验性的；引擎检测它们并回退（例如到它自己的特定度解析器），并且合约烟雾测试在 `test/e2e.test.ts` 中失败时会大声失败（实验字段记录为存在/不存在）。 ## 支持 Visionaire 是免费且开源的。如果它为您节省了时间，并且您想帮助保持开发持续进行，您可以在 [Ko-fi](https://ko-fi.com/mishonyai) 或 [Patreon](https://www.patreon.com/cw/MishonyAI) 上捐款。这完全是可选的，但非常感谢。错误报告和现场笔记也同样有帮助 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 许可证 **[Apache License 2.0](LICENSE)** — 免费提供给所有人，包括商业用途，附带专利许可。 版权所有 © 2026 mi60dev ([NOTICE](NOTICE)). 由 [@mi60dev](https://github.com/mi60dev) 构建和维护。 欢迎在 Apache-2.0 条款下贡献 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md).