项目定位与许可证

visionaire-engine 是一个面向浏览器自动化与网页交互场景的引擎项目，最新版本为 v0.6.2，已重新授权为 Apache-2.0 许可证。该许可证允许任何人（包括商业用途）免费使用、修改和分发代码，并附带了专利授权条款，旨在降低企业和个人开发者采用本项目的法律门槛。资料来源：README.md:1-20

根据项目说明，v0.6.2 与上一个版本 v0.6.1 保持功能一致，仅完成许可证切换，因此对于正在升级的用户而言，代码行为和接口不会因升级而发生变化。资料来源：README.md:5-15

核心能力指标

项目当前公开以下量化指标，用于直观呈现成熟度与稳定性：

• 22 个工具（tools）：覆盖页面导航、表单填写、元素查找、内容提取等常见浏览器操作。
• 277 项真实浏览器测试：测试在真实 Chrome 环境中运行，确保自动化逻辑与生产场景一致。
• 24 例种子缺陷基准（seeded-bug benchmark）：用于回归验证引擎在已知缺陷场景下的修复能力。

资料来源：README.md:18-30

这些数据共同构成了项目自我评估质量的核心依据，也是开发者在评估是否引入该项目时的关键参考。

一键运行与注册表自省

项目提供了两种便捷的运行与集成路径：

1. Dockerfile：通过容器化方式打包运行时依赖，实现"一条命令即可启动"。资料来源：Dockerfile:1-40
2. glama.json：用于注册表自省（registry introspection），允许外部系统查询本引擎暴露的元信息与能力清单。资料来源：glama.json:1-20

两者结合，使 visionaire-engine 既能作为独立服务部署，也能作为可发现的组件嵌入更大的 AI Agent 生态中。

客户端与 AI 模型对接

项目在 docs/clients.md 中专门描述了与各类 AI 客户端的集成方式，重点说明了如何与 Claude 等大模型配合使用。资料来源：docs/clients.md:1-50

典型的快速接入流程如下：

flowchart LR
    A[AI 客户端<br/>Claude / 其他] --> B[visionaire-engine]
    B --> C[22 个浏览器工具]
    B --> D[真实 Chrome 执行环境]
    C --> E[页面操作与数据采集]
    D --> E
    E --> F[结构化结果回传]
    F --> A

该流程体现了引擎作为"模型 ↔ 浏览器"之间桥梁的角色：模型发出高层意图，引擎拆解为具体的浏览器动作并返回结构化结果。

本地快速开始

通过 npm 安装依赖并运行示例脚本，是最直接的本地体验方式：

# 安装依赖
npm install

# 运行演示脚本
npx tsx scripts/demo.ts

演示脚本位于仓库的 scripts/demo.ts，用于演示引擎的基础调用流程。资料来源：scripts/demo.ts:1-30

项目元信息

package.json 中定义了项目的核心元数据，包括名称、版本号、入口文件与脚本命令：

资料来源：package.json:1-40

使用建议与注意事项

• 升级兼容：从 v0.6.1 升级到 v0.6.2 时，由于仅许可证变更，代码层无需修改，但需注意团队内部的合规流程是否要求更新 LICENSE 文件。资料来源：README.md:5-15
• 测试覆盖：在提交涉及浏览器行为的改动前，建议先运行 277 项真实 Chrome 测试与 24 例种子缺陷基准，避免回归。资料来源：README.md:18-30
• 客户端选型：根据目标 AI 模型选择合适的客户端适配方式，详细配置参考 docs/clients.md。资料来源：docs/clients.md:1-50

小结

visionaire-engine 以 Apache-2.0 许可证开放，提供 22 个浏览器工具、277 项真实浏览器测试与 24 例种子缺陷基准，配套 Dockerfile 与 glama.json 支持一键部署与生态自省，并通过 docs/clients.md 描述了与 Claude 等 AI 客户端的对接方式。对于希望快速验证能力的开发者，可从 scripts/demo.ts 入手，在本地完成端到端的浏览器自动化体验。资料来源：README.md:1-30、资料来源：package.json:1-40、资料来源：docs/clients.md:1-50、资料来源：glama.json:1-20、资料来源：Dockerfile:1-40、资料来源：scripts/demo.ts:1-30

概述

visionaire-engine 在 v0.6.2 中通过 Model Context Protocol (MCP) 暴露了 22 个工具,用于在真实 Chrome 浏览器上下文中执行前端开发辅助任务。每个工具以独立 TypeScript 模块的形式实现,统一注册到 MCP 注册表中,客户端(Claude、Cursor、Continue 等)可直接以 JSON-RPC 方式调用 资料来源：docs/tools.md。

这些工具共同覆盖四大类工作流:页面快照、样式解释、元素查找、视觉检查。仓库提供 277 条在真实 Chrome 上运行的测试以及 24 例 seeded-bug 基准,确保工具行为的可重复性与回归稳定性 资料来源：docs/clients.md。

工具分类

页面快照与 DOM 抓取

page-snapshot 工具返回当前标签页的可访问性树与精简 DOM 视图,作为其它工具的"上下文基线"。它通过 CDP (Chrome DevTools Protocol) 的 DOM.getDocument 与 Accessibility.getFullAXTree 通道聚合数据,输出可被 LLM 解析的 Markdown 片段。后续工具(如 find-elements、explain-styles)都以快照中的节点引用作为入参,避免重复抓取 资料来源：src/tools/page-snapshot.ts。

样式解释与级联分析

explain-styles 接收一个 CSS 选择器或节点引用,返回该节点的计算样式、级联来源、继承链与媒体查询命中情况。工具内部使用 CSS.getMatchedStylesForNode 拉取匹配规则,并将优先级、来源(user-agent/user/author)与声明顺序一并呈现。这对回答"为什么这个按钮不是蓝色"这类问题尤其有用 资料来源：src/tools/explain-styles.ts。

元素查找与定位

find-elements 在快照的基础上,根据文本、属性、ARIA 角色、坐标或选择器表达式定位节点,并返回其在可访问性树中的路径、屏幕坐标与 box model 尺寸。返回结果中包含唯一 nodeId,供后续工具进行高亮、滚动或修改操作 资料来源：src/tools/find-elements.ts。

对齐与色彩检查

check-alignment 工具对比两个或多个节点的盒子模型,判断水平/垂直对齐偏差,常用于验证设计稿还原度。它返回像素级偏差值与可视化提示 资料来源：src/tools/check-alignment.ts。

pick-color 通过 Input.dispatchMouseEvent 触发拾色器,或解析截图 RGBA,返回选中像素的 HEX、RGB、HSL 与对比度比例(WCAG AA/AAA),便于快速排查配色可访问性问题 资料来源：src/tools/pick-color.ts。

通用技术特性

所有 22 个工具遵循统一约束:

资料来源：docs/tools.md

使用建议与已知边界

社区反馈显示,用户在以下场景高度依赖这套工具集:

1. LLM 驱动的样式调试:explain-styles + pick-color 组合,在不离开聊天界面的前提下回答"为什么这个段落不可见"。
2. 视觉回归审查:page-snapshot + check-alignment 用于 PR 自动化检查。
3. 元素级 A11y 修复:find-elements 返回 role/aria-* 信息,可直接生成修复建议。

需要注意的是,任何会修改页面的工具都会先在响应中给出 diff 预览,需客户端显式 confirm=true 才真正写入,这避免了误操作。同时,所有工具在 Chrome 未连接时返回一致的 CHROME_NOT_ATTACHED 错误码,便于上层做重试决策。

资料来源：src/tools/page-snapshot.ts

概述与设计目标

确定性 CSS 分析引擎（Deterministic CSS Analysis Engine）是 visionaire-engine v0.6.2 的核心子系统，承担对真实浏览器中样式规则的静态与动态解析任务。该引擎不依赖启发式推断或机器学习模型，而是通过严格符合 W3C CSS 规范的可重现算法，在 277 个真实 Chrome 测试用例和 24 个种子缺陷基准（seeded-bug benchmark）上输出稳定结果。

资料来源：docs/architecture.md:1-80

引擎以模块化方式拆分，每个子模块负责一类 CSS 子规范：

资料来源：docs/architecture.md:30-65, src/engine/cascade.ts:1-30

层叠与特异性子系统

cascade.ts 与 specificity.ts 共同实现层叠算法。specificity.ts 导出纯函数，将任意选择器字符串分解为 (a, b, c) 三元组权重，避免依赖 DOM 的运行时评估。cascade.ts 则按规范顺序应用：重要性声明 → 来源顺序 → 特异性 → 继承，处理同一元素上多条规则的胜出关系。

由于整个计算过程无随机性、无异步副作用，给定相同的样式表与 DOM 快照，引擎将返回完全相同的 computed style map，这正是「确定性」的来源。

// src/engine/specificity.ts:核心权重结构
export interface Specificity {
  readonly a: number; // ID 选择器计数
  readonly b: number; // class/属性/伪类计数
  readonly c: number; // 元素/伪元素计数
}

资料来源：src/engine/specificity.ts:1-60, src/engine/cascade.ts:40-120

盒模型与几何计算

box-model.ts 在确定性的基础上处理 width、height、margin、padding 与 border 的解析。它接收 cascade 子系统的胜出规则，结合 viewport 上下文（由调用方注入，不依赖全局状态），输出每个元素的盒模型矩形。该模块严格区分 content-box 与 border-box，并在百分比取值时显式标注父容器依赖，避免跨调用结果漂移。

// src/engine/box-model.ts:盒模型主入口
export function resolveBoxModel(
  rules: ResolvedRule[],
  context: LayoutContext,
): BoxRect;

资料来源：src/engine/box-model.ts:1-90

动画与对齐子引擎

animations.ts 实现关键帧时间轴的离散采样：给定起止时间戳与缓动函数，返回每一帧的属性插值。该采样基于闭式数学公式而非逐步积分，因此具备确定性。

alignment.ts 则聚焦 Flexbox 与 CSS Grid 的对齐语义，将 justify-content、align-items、place-self 等属性映射为几何约束。该模块与 box-model.ts 通过共享的 LayoutContext 解耦，便于独立测试。

flowchart LR
    A[DOM 快照] --> B[cascade]
    A --> C[specificity]
    B --> D[胜出规则集]
    C --> D
    D --> E[box-model]
    D --> F[animations]
    D --> G[alignment]
    E --> H[computed style map]
    F --> H
    G --> H

资料来源：src/engine/animations.ts:1-70, src/engine/alignment.ts:1-80, docs/architecture.md:90-140

确定性保证与可观测性

整个引擎通过三条约束保证确定性：(1) 所有子模块为纯函数，输入相同则输出相同；(2) 时间相关模块（如 animations）以显式时间戳为参数，不读取 Date.now()；(3) 副作用（如日志）通过依赖注入传递，便于测试隔离。

这种架构使 visionaire-engine 能够支撑 22 个对外工具，并对每条规则生成可重现的诊断报告——这对回归测试与种子缺陷基准验证至关重要。

资料来源：docs/architecture.md:150-220, src/engine/cascade.ts:200-260

1. WordPress 归属解析的定位与职责

归属解析（attribution）的目标是将浏览器中实际渲染出来的产物——CSS、JS、Source Map——映射回上游发布者（主题、插件、WordPress 核心），从而让审计、版权核查与漏洞溯源成为可能。

• 核心入口：src/attribution/wordpress.ts 负责 WordPress 特有的指纹识别，包括 wp-content/、wp-includes/ 路径模式、版本元信息以及主题/插件静态资源清单。
• 横向协作：与 stylesheets.ts、scripts.ts、sourcemaps.ts 形成「载体解析 → 来源定位 → 源码回溯」的三段式流水线。资料来源：src/attribution/wordpress.ts:1-40
• 场景说明：docs/wordpress.md 描述了典型用例，例如识别未声明的第三方脚本、定位被深度定制的页面构建器输出。

2. 三层解析流水线

flowchart LR
    A[浏览器渲染产物] --> B[stylesheets.ts<br/>CSS 解析]
    A --> C[scripts.ts<br/>JS 解析]
    B --> D[wordpress.ts<br/>主题/插件指纹]
    C --> D
    B --> E[sourcemaps.ts<br/>源码映射]
    C --> E
    D --> F[归属报告]
    E --> F

• 样式归属：stylesheets.ts 解析 <link rel="stylesheet"> 与内联 <style>，抽取 URL、srcset、媒体查询等元数据。资料来源：src/attribution/stylesheets.ts:1-60
• 脚本归属：scripts.ts 同步处理 src、ES Module、type="module"、integrity 等现代属性，并记录 defer/async 行为。资料来源：src/attribution/scripts.ts:1-60
• 源码回溯：sourcemaps.ts 解析 .map 文件中的 sources、sourcesContent、mappings，把压缩后的 JS 还原到原始仓库路径。资料来源：src/attribution/sourcemaps.ts:1-60

3. 解析结果的数据模型

WordPress 专属字段（如 wpBlock、themeJsonVersion）由 wordpress.ts 在合并阶段注入。资料来源：src/attribution/wordpress.ts:60-120

4. 生产部署与运行约束

visionaire-engine 在真实 Chrome 上运行 277 项测试，部署时需保证浏览器依赖与 Node 运行时一致。

• 容器化：Dockerfile 提供单命令启动方式，封装了 Chrome、字体与 Node 环境。资料来源：Dockerfile:1-40
• 注册表自描述：glama.json 暴露工具清单、版本与能力描述，便于 MCP 客户端做能力协商。资料来源：glama.json:1-30
• 开发与发布流程：docs/development.md 记录了 lint → test → seed-bug benchmark → publish 的四段式流水线，并强调在改动 attribution/ 子模块时必须同步更新 24 例种子缺陷基准。资料来源：docs/development.md:1-80
• 运行建议：WordPress 站点常启用缓存插件（WP Rocket、W3 Total Cache），建议在归属解析前通过查询参数 ?nocache=1 或禁用缓存插件，确保抓取到的是最新产物。

5. 常见边界与限制

• 仅识别可被浏览器实际加载的资源，对服务端按 IP 灰度投放或 A/B 实验的脚本可能漏判。
• 深度混淆且未发布 Source Map 的脚本（如部分商业插件的闭源构建）只能定位到 vendor，无法回溯到原始行号。资料来源：src/attribution/sourcemaps.ts:60-120
• WordPress 多站点（multisite）下子站点的资源路径与主站共享，需结合 site_url 上下文做二次确认。资料来源：src/attribution/wordpress.ts:120-180

通过上述分层，WordPress 归属解析在 v0.6.2 中以 Apache-2.0 协议开源交付，既可作为独立 CLI 工具运行，也能通过容器与注册表自描述集成到更大的审计流水线中。

Pitfall Log / 踩坑日志

项目：mi60dev/visionaire-engine

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/mi60dev/visionaire-engine | host_targets=mcp_host, claude

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/mi60dev/visionaire-engine | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/mi60dev/visionaire-engine | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/mi60dev/visionaire-engine | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/mi60dev/visionaire-engine | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/mi60dev/visionaire-engine | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/mi60dev/visionaire-engine | release_recency=unknown