ui-verification

概览

UI Verification 针对运行中的 Web 应用提供两种并行模式：

1. 视觉验证 — 检查页面是否符合设计规范。将设计声明转换为 CSS 规则检查，并通过 getComputedStyle() 对运行中的 DOM 执行检查。结果具有确定性；浏览器计算后的样式是事实依据。
2. 流程验证 — 检查用户旅程是否正确完成。通过 Nova Act 的 act()（操作）和 act_get()（断言），执行 .feature 文件中的 Gherkin 场景。结果具有不确定性；每次运行的结果会随网络时序和实时 UI 变化而异。

两种模式共用同一技能、MCP 服务和浏览器会话。一次运行可以同时生成两种输出，并合并为一份报告。也可以单独运行任一模式；合并报告中会省略另一部分。

每次运行会生成：

1. 结构化产物 — 视觉验证按类别生成 JSON；流程验证生成各流程的执行数据
2. 标注截图 — 在页面上用红色边界框突出显示视觉验证失败项
3. 验证报告 — Markdown 格式，包含视觉验证摘要、流程验证摘要（各流程状态表）以及各流程详细报告的链接

verify_* 工具具有确定性——不使用视觉模型，浏览器计算后的样式是事实依据。视觉验证的编译和审计阶段由 LLM 驱动（尽力而为），用于协调设计意图与应用的实际结构。每次运行时，Nova Act 都会解读流程步骤；流程运行本质上具有不确定性。

协调输入

视觉验证。 5 个已编译的类别文件（.ui-verification/specs/*.md）会根据最多三种输入进行协调：

输入	提供内容	必需？
design.md	自由形式的设计意图——设计令牌、文字说明、设计语言、组件定义	必需
运行中的应用	通过 start_browse + verify_* 观察到的实时 DOM——真实选择器、真实计算值	验证所需（用于确定选择器并验证规则）
应用源代码	组件、主题/令牌、CSS 文件——实现层面的事实依据	可选。有源代码时，选择器更具确定性，偏差分类也更准确

流程验证。 流程以 .feature 文件的形式编写或生成于 .ui-verification/flows/：

输入	提供内容	必需？
.feature 文件	包含元数据标头的 Gherkin 场景（流程 ID、类型、应用 URL，以及可选的身份验证和清理信息）	流程验证所需
运行中的应用	场景的目标；Nova Act 会针对实时 URL 执行场景	必需
身份验证凭据	当流程的 # user: 元数据声明需要登录时提供	有条件必需

如果可以访问源代码（用户是正在开发自己应用的开发者），Agent 应检测源代码，并在编译、审计和规范生成过程中使用。源代码可以位于项目根目录（output_dir 下有 package.json + src/），也可以位于深一层的目录中（例如 output_dir/<package-name>/package.json——工作区布局，验证器在工作区根目录打开，一个或多个应用包位于子目录中）。两种位置都要检查。如果没有源代码（验证外部网站、黑盒检查），技能将以仅 DOM 模式运行——选择器尽力而为，审计仅依赖 design.md + DOM。

随着应用开发，5 个类别文件会逐步扩充：

• design.md 通过 Scribe 扩充（用户在聊天中表达设计意图 → 编辑 design.md）
• 编译器在应用和源代码中发现更多可验证的界面后，5 个 md 文件会逐步扩充

这两层都可以扩充，但只能通过各自的编写途径进行。绝不能通过编辑这 5 个 md 文件来记录观察结果或冻结与实时网站不一致的值——请参阅下方的硬性规则。

三个名称——不要混淆

名称	标识对象
ui-verification	此技能（Agent 的操作手册）
nova-act-mcp	提供浏览器和 verify_* 工具的 MCP 服务
.ui-verification/	项目根目录下的产物目录（编译后的规范、断言 JSON、报告）

尽管名称中有重叠的词语，它们彼此无关。此技能不位于产物目录内；产物目录位于项目根目录下，而非技能目录内。

功能

功能	工具	源文件	检查内容
视觉样式	verify_visual_style	specs/visual-style.md	颜色、字体排印、间距、圆角、阴影
组件	verify_components	specs/component-rules.md	组件是否存在、变体、属性
无障碍	verify_accessibility	specs/accessibility.md	Aria 角色、地标、标题层级
项目规则	verify_project_rules	specs/project-rules.md	布局结构、间距系统、约定
平台约定	verify_platform_conventions	specs/platform-conventions.md	导航模式、页面结构
用户流程	act + act_get	flows/<flow-name>.feature	端到端用户旅程、功能正确性

视觉规则可以按路由范围限定：每个类别文件都可以包含 ## Scope: any（默认）和 ## Scope: route=<glob> 小节。参见 references/spec_authoring.md。流程场景以其 # app: 元数据中声明的 URL 为目标；路由范围按流程设置，而非按规则设置。

可用的 MCP 工具（共 19 个）

会话管理

• start_browse(url, intent, browser_mode) — 打开 URL，获取 session_id。验证时使用 browser_mode="local"。
• session_close(session_id) — 终止浏览器会话
• session_list() — 列出活动会话

验证——仅限视觉（均需 session_id 和 rules JSON；始终将 output_dir 设为项目根目录的绝对路径）

• verify_visual_style(session_id, rules, output_dir)
• verify_components(session_id, rules, output_dir)
• verify_accessibility(session_id, rules, output_dir)
• verify_project_rules(session_id, rules, output_dir)
• verify_platform_conventions(session_id, rules, output_dir)

这些是视觉模式验证工具。对于流程验证，主要使用 act() 和 act_get()（见下文）——verify_* 不适用于 Gherkin 步骤。

如果省略 output_dir，服务会将断言写入 /tmp/ 临时目录，后续报告和标注步骤将无法找到它们。

浏览器交互（均需 session_id）

• navigate(session_id, url) — 前往 URL
• click(session_id, selector) — 点击元素
• scroll(session_id, direction, selector?) — 向上或向下滚动
• hover(session_id, selector) — 悬停于元素上
• press_key(session_id, key) — 键盘输入
• type_text(session_id, selector, text, clear_first?) — 在输入框中输入

内容与捕获（均需 session_id）

• evaluate_js(session_id, script) — 在页面上下文中运行 JavaScript
• get_page_content(session_id, format?) — 以 "text" 或 "html" 格式获取页面内容
• screenshot(session_id, destination?) — 将视口捕获到文件路径

自然语言（均需 session_id）

• act(session_id, prompt) — 指示浏览器执行操作（滚动、点击、导航、填写表单）。对于流程验证，这是驱动 Given 和 When 步骤的主要工具。对于视觉验证，不要使用 act() 检查 CSS；请改用 verify_*。
• act_get(session_id, prompt, schema?) — 提取结构化数据或验证状态。对于流程验证，这是驱动 Then 以及 Then 之后的 And 断言的主要工具；可使用 evaluate_js 补充确定性检查。对于视觉验证，不要使用 act_get() 检查 CSS；页面感知和推理应由 Agent 使用 screenshot + get_page_content 完成，CSS 判定则由 verify_* 给出。

产物结构

<project_root>/
  visual/design.md                   ← visual source spec (or .ui-verification/design.md)
  .ui-verification/
    .integrity.json                  ← compile-state ledger (visual only — see spec_sync.md)
    specs/                           ← compiled visual category files (INPUT to verify_*)
      visual-style.md                  (clean markdown — integrity tracked in .integrity.json)
      component-rules.md
      accessibility.md
      project-rules.md
      platform-conventions.md
    flows/                           ← flow .feature files (INPUT to act() / act_get())
      <flow-name>.feature
    sessions/                        ← per-session output (MCP-owned)
      <session_id>/
        <category>_assertions.json    (visual assertion JSON, write-once)
    reports/                         ← per-run output (skill-owned)
      <YYYYMMDD-HHmmssZ>/            ← UTC run-timestamp (a run can span multiple sessions)
        report.md                    ← combined visual + flow summary
        screenshots/                 ← visual annotated failures
        flow-reports/                ← per-flow reports
          <flow-name>.report.md
        sessions.json                ← manifest of session IDs in this run

每次运行都必须遵守的硬性规则

默认模式为“both”，除非用户缩小范围

当用户说“verify [url]”“run verification on [url]”或提出任何未限定范围的验证请求时，本次运行 MUST 同时包含视觉验证和流程验证。不要默认只进行视觉验证。只有用户明确要求（“仅检查样式”“仅运行流程”），或消歧表明确匹配单一模式时，才缩小到一种模式。

如果不存在 .feature 文件，则生成这些文件（参见 references/flow_generation.md）。如果不存在 design.md，则生成该文件（参见 references/spec_generation.md）。缺少产物时应触发生成，而不是缩小范围。

完整性账本触发时执行审计

调用任何 verify_* 工具前，检查完整性账本（触发条件参见下文“完整性账本涵盖无问题的情况”）。执行审计时，针对每条适用规则，核对其与输入（design.md、可访问的应用源代码、运行中应用的 DOM）是否一致。这是尽力而为的 LLM 检查，而非子字符串匹配，因为 Compiler 本身由 LLM 驱动，规则可以合理地表达 design.md 中没有逐字出现的信息。

对于每条规则（{Name, Selector, Property, Constraint, Scope}），回答以下三个问题：

1. 意图可追溯——规则所表达的主张（断言的内容：令牌值、属性/值对、元素是否存在）是否对应 design.md 中明确陈述或隐含表达的内容，或源代码中的组件定义/主题令牌，或运行中应用里的惯用模式？
2. 约束一致——约束值是否与 design.md 为此元素/属性组合指定的值一致，或与源代码主题/令牌文件指定的值一致，或与运行中应用的组件静止状态下渲染的值一致？从实时网站提取、但没有 design.md 或源代码依据的约束属于污染。
3. 选择器合理——选择器是否指向 design.md（或源代码）所描述的元素？选择器可以来自应用（比单靠 design.md 能指定的更具体），但目标必须与所描述的元素一致。

将每条规则归类为：

• PASS——三个问题都至少与一个输入一致
• ORPHAN——规则的主张没有来源。design.md 中没有此断言；源代码没有定义此赋值；唯一的“证据”只是实时网站恰好渲染出的内容。这属于污染情形。
• DIVERGENT——design.md 中确实有此主张（定义了令牌、引用了组件），但规则的约束与 design.md 中的指定值矛盾。例如，design.md 规定组件 X 使用令牌 Y，但规则断言组件 X 使用令牌 Z 的值。

本次运行跳过 ORPHAN 和 DIVERGENT 规则，并在报告的 Audit Findings 部分列出这些规则（参见 references/verification_report.md）。验证这些规则要么会通过（默默确认污染），要么会失败（但理由不正确）。继续验证 PASS 规则。用户可自行选择以下三种方式解决污染：删除规则，将主张补充到 design.md 并重新编译，或从头重新编译。

何时写入完整性账本。 只有一种判断标准：磁盘上的类别文件与 Compiler 根据当前 design.md 此刻生成的文件完全一致时，才写入。

• 编译顺利完成，且没有跳过任何规则 → 写入。
• 选择器修复或约束语法修复已完成 → 写入（已知原始内容存在问题后，这些修复就是 Compiler 此刻会生成的内容）。
• 审计跳过了任何规则（ORPHAN/DIVERGENT） → 不要写入。这些规则仍保留在文件中，但它们并非重新编译会生成的内容。让账本保持缺失或过期，以便下次运行时重新审计。
• 仅验证的运行，文件未更改 → 不执行任何操作；不要修改现有账本。 选择器的来源（启发式模式下的 DOM 观察，源代码感知模式下的源代码）不会决定是否符合台账条件。只要规则的声明和约束可追溯到 design.md（审计会验证这一点），台账就反映了有效且经 Compiler 批准的状态。完整案例表请参见 references/spec_sync.md 中的 Compilation 步骤 7。

完整性台账（.integrity.json）涵盖干净状态。 如果台账显示所有哈希都匹配——design.md 和每个类别文件均如此——那么可以证明文件状态就是 Compiler 上次写入的状态，无需审计。请参见 references/spec_sync.md § Integrity Ledger。

以下情况会运行审计：

• 任一类别文件的哈希与台账不匹配（文件在 Compiler 之外被编辑——例如之前有缺陷的运行、手动编辑或部分写入）
• 台账缺失（没有完整性基线，因此采取保守做法）
• 用户明确要求重新审计（手动正确性检查；即使内容有效，哈希也可能过时，例如 Compiler 的 bug 写入了错误规则并更新了自身哈希）

哈希匹配时跳过审计，能显著提升重复运行的效率。但建议在大型编译后或出现可疑变更后，定期手动重新审计（“re-audit visual-style”）。

审计成本。 每个指定范围内的类别文件需要进行一次大模型推理（也可以按规则批次进行，由 Agent 决定）。这并非免费，但成本有上限：与待验证的规则数量成正比，且不调用 MCP。审计使用的推理方式与 Compiler 编写规则时相同；审计只是检查：“如果现在从头编译，我会写出这条规则吗？”

断言 JSON 不可更改

<output_dir>/.ui-verification/sessions/<session_id>/*_assertions.json 中的文件是 verify_* 一次性写入的输出。**绝对不要编辑这些文件。**没有例外。

这些 JSON 记录了 verify_* 针对实时 DOM 的检查结果。不要重写值、改变通过／失败状态、添加范围、“注释”检查结果或添加说明。如果某个字段似乎缺失（例如范围），报告层会从其来源（例如类别文件）合并该字段——断言 JSON 本身必须保持 MCP 服务写入时的原样。

如果你发现自己正在打开断言 JSON 来修复问题，请停下——这是报告的工作。Agent 会读取 JSON；verify_* 写入后，JSON 不会再改变。

5 个分类文件是 design.md 的映射结果

这 5 个编译生成的 .ui-verification/specs/*.md 文件源自 design.md。它们不是草稿、工作记忆，也不是记录观察结果的地方。

验证模式（存在 design.md）：

仅在以下情况下编辑分类文件：

• design.md 已更改（或聊天内容已变为编辑 design.md）→ 重新编译受影响的规则
• 选择器修复：现有规则的选择器返回了“selector not found”，且你找到了可用的替代选择器（仅更新选择器——名称／属性／约束保持不变）

请勿编辑分类文件来：

• 记录对线上站点的观察（那是报告的职责）
• 添加一条规则来“记录某个差异”，并使用与线上站点差异值相匹配的约束（这会悄悄把站点错误编码成事实，导致后续无法检测到）
• 通过放宽约束让失败的规则通过
• 记录发现、备注或上下文

对于部分／限定范围的验证，从正确的分类文件中选择现有规则——除非某条规则可以追溯到先前编译时遗漏的 design.md 声明（这是需要指出的 Compiler 错误，而不是常规操作），否则不要编写新规则。

生成模式（从线上站点冷编译，尚无 design.md）：

生成期间会放宽上述规则，因为这 5 个 md 文件正在首次初始化。生成过程会观察正在运行的应用，并在一次操作中同时写入 design.md 和这 5 个 md 文件。生成结束时，5 个 md 文件中的约束与观察到的 DOM 值一致——这是逆向工程约定，不是污染。

“禁止记录观察结果”这一限制会在生成完成且用户审阅过 design.md 后生效。从那时起，适用上述验证模式规则：编辑必须通过 design.md + 重新编译完成，绝不能直接编辑这 5 个 md 文件。

生成模式规则见 references/spec_generation.md § 阶段 5。生成期间，如果可以访问源代码，它会提供名称（令牌名称、组件名称）的信息，但不会提供值的信息——值以 DOM 为准。生成期间不存在“源代码与 DOM 不一致”的情况：DOM 是所有源 CSS 经级联解析后的结果，任何看似不一致的情况，都是 Agent 读取的某个源文件与浏览器编译同一源文件后的结果之间的差异。

每次运行彼此独立

请勿读取先前 sessions/<session_id>/ 或 reports/<run-timestamp>/ 目录中的断言 JSON 或 report.md。运行间唯一保留的状态是编译生成的 specs/*.md 文件和 .integrity.json 台账（如果台账哈希与当前文件全部匹配，则跳过重新编译）。先前的断言和报告是历史记录，不会影响当前运行。

如果你发现自己正在读取先前会话的断言来进行“比较”，请停止——这是跨会话热启动，目前已延期。请重新运行，并生成一份新报告。

flows/ 中的流程文件是唯一的流程输入

<output_dir>/.ui-verification/flows/ 下的 .feature 文件是流程验证的唯一输入。运行过程中，绝不要根据聊天输入临时编写流程，也绝不要修改 .feature 文件。如果用户想更改场景，必须在下次运行前通过 Scribe 完成修改（参见 references/flow_sync.md）。

流程运行具有非确定性

请勿在不同运行之间沿用先前流程会话的结果。Nova Act 每次运行都会重新解读步骤，网络时序各不相同，线上 UI 也会变化。沿用“通过”的判定会掩盖真实的不稳定性或环境漂移。每次运行都要运行所有流程。流程方面的回归会通过综合报告中的逐流程状态表体现，而不是通过热启动机制。

每次运行都会生成报告

此规则没有例外。无论用户要求验证整个网站，还是只检查 design.md 中的一行，运行都必须满足以下条件才算完成：

1. 规则已持久化到磁盘 — 在验证时（第 6 步）传递给 verify_* 的每条规则，都必须已存在于正确 ## Scope: 部分下的类别文件中。（编译时选择器验证是 verify_* 的另一种用途；参见 verification.md 第 4 步。）
2. 在生成报告时合并范围，而不是将范围标记到断言上 — 报告会同时读取断言 JSON（用于判定结果）和类别文件（用于获取范围），并按规则名称将两者合并。断言 JSON 必须与 MCP 服务写入时完全一致。合并方式请参见 references/verification_report.md。
3. 已生成报告 — <output_dir>/.ui-verification/reports/<run-timestamp>/report.md，其中包含失败表格和所有已标注的截图。格式请参见 references/verification_report.md。即使所有检查都通过，也必须生成报告。
4. 面向用户的摘要应链接到报告，而不是断言 JSON。JSON 是中间输出；报告才是交付物。

对一两项声明进行“快速检查”仍属于验证运行。上述四条规则同样适用。

工作流

对于视觉验证任务，请加载 references/verification.md。对于流程验证任务，请加载 references/flow_verification.md。这两份参考文档都包含各自模式的完整决策流程。

用户意图	参考文档
根据设计规范验证线上网站（视觉）	references/verification.md
在线上网站运行用户流程	references/flow_verification.md
根据线上网站生成规范（不存在 design.md）	references/spec_generation.md
根据线上网站生成流程（不存在 .feature 文件）	references/flow_generation.md
编译 design.md → 类别文件；同步聊天编辑内容	references/spec_sync.md
将用户意图同步到 .feature 文件	references/flow_sync.md
设置 MCP 服务和浏览器会话	references/setup.md
编写/编辑设计规范文件	references/spec_authoring.md
编写 .feature 文件	references/flow_authoring.md
生成验证报告（视觉 + 流程）	references/verification_report.md
在页面上直观标注失败项	references/annotate_failures.md
约束语法参考	references/constraint_reference.md
各类别的翻译模式	references/verify_visual_style.md、references/verify_components.md、references/verify_accessibility.md、references/verify_project_rules.md、references/verify_platform_conventions.md
跨会话预热（延期 — 不在范围内）	references/warm_start.md

所有参考文档都位于相对于此 SKILL.md 文件的 ./references/<name>.md 路径下。绝对路径取决于技能的安装位置：

• 全局安装： ~/.<agent>/skills/ui-verification/references/<name>.md
• 工作区安装： <project_root>/.<agent>/skills/ui-verification/references/<name>.md

解析参考文档时，请以包含此 SKILL.md 的目录为基准，而不是工作区根目录。如果技能加载器的渐进式披露机制在会话中尚未显示这些文档，请使用相应的绝对路径，通过 Read 工具直接读取；切勿使用 find 搜索文件系统。

消歧：视觉验证、流程验证或两者兼有

根据用户的请求选择正确的模式：

短语模式	模式	操作
"verify design", "check styles", "match the spec", "is it on-brand"	仅视觉验证	加载 references/verification.md
"run flows", "test the user journey", "verify login works"	仅流程验证	加载 references/flow_verification.md
"verify [url]", "run verification on [url]"，且没有进一步限定	两者兼有	先进行视觉验证，再进行流程验证，并生成一份合并报告
用户指定了某个 .feature 文件或流程 ID	仅流程验证	加载 references/flow_verification.md，并仅运行该流程
用户选中了 design.md 中的文本或指定了一个类别	仅视觉验证	加载 references/verification.md，并使用部分选择流程

如有疑问，只询问用户一次：“运行视觉验证、流程验证，还是两者都运行？”如果请求确实存在歧义，不要自行猜测范围。

此技能的位置

对于工作区本地安装，此技能位于 <output_dir>/.<agent>/skills/ui-verification/；对于全局安装，则位于 ~/.<agent>/skills/ui-verification/——技能加载器从何处加载，此处就是它的安装位置。**不要搜索文件系统来查找它。**不要运行 find ~/.<agent> 或 find /。激活由运行时负责；如果你已经打开了此 SKILL.md，运行时就已经知道你的位置。

确定参考资料目录

references/ 文件夹始终与此 SKILL.md 文件位于同一目录，而不是与工作区或输出目录放在一起。使用运行时加载此文件时所用的路径作为基础路径：

安装类型	SKILL.md 位置	参考资料位置
全局	~/.<agent>/skills/ui-verification/SKILL.md	~/.<agent>/skills/ui-verification/references/
工作区	<project>/.<agent>/skills/ui-verification/SKILL.md	<project>/.<agent>/skills/ui-verification/references/

读取参考资料时，请根据技能的安装位置构造绝对路径。全局安装示例：

~/.<agent>/skills/ui-verification/references/verification.md
~/.<agent>/skills/ui-verification/references/spec_sync.md

如果技能是从全局位置加载的，不要假设参考资料位于 <output_dir>/.<agent>/skills/ui-verification/references/；工作区中可能没有副本。

如果你是新一轮对话中刚启动的 Agent，且当前没有可用的 nova-act-mcp 工具，MCP 服务可能仍在启动——请等待运行时在下一轮用户对话中提供该工具，不要搜索文件系统来“查找”技能。技能已经加载；工具不一定会在技能激活时同步就绪。

不要搜索工具的实现代码

绝不要使用 find 搜索 MCP 服务源代码、约束引擎源代码或任何其他工具实现。verify_* 的行为、约束语法、选择器匹配算法——这些内容都记录在 references/constraint_reference.md 和各类别的深度说明中。如果运行时某项约束或属性的行为出乎意料，**请阅读参考资料，而不是实现代码。**参考资料是面向 Agent 的权威文档；使用 find 深入探查引擎，说明参考资料需要更新，用户可以处理此事——但在当前会话中，请依据文档说明操作。