ego-webqa

ego-webqa

针对 AI 生成的网页、H5 演示和 PWA 的确定性粗粒度交付质量检查。

指定一个 URL 即可。默认情况下，它会在真实的 Chromium 浏览器中打开页面，检查零配置的窄屏移动设备矩阵，安全地探测主要行动号召，并留下截图和机器可读证据。Firefox 和 Playwright WebKit 可逐个选择。默认的八种变体组合包括：

• 360px 和 390px 宽度；
• 1.0x 和 1.5x 文本缩放；
• 0px 和 34px 模拟底部安全区域。

30 秒查看结果

想先检查一次已完成的运行？请打开 实时前后对比证据看板。

python -m pip install ego-webqa
ego-webqa setup
ego-webqa https://your-preview.example --out .qa/first

setup 会先检查所选浏览器。如果浏览器已经可以启动，setup 就会退出，不会下载任何内容；否则，它会使用当前激活的 ego-webqa Python 解释器安装固定版本的 Playwright 无头 shell，并验证其能在真实环境中无头启动。首次设置 Chromium 时不会安装完整的有头浏览器构建，因为审计仅以无头模式运行。普通的 doctor 和审计命令绝不会隐式下载浏览器。审计命令在通过或存在警告时以 0 退出，在存在阻塞性交付缺陷时以 1 退出，在审计或浏览器失败时以 2 退出。每次运行都会留下截图和结构化证据：

.qa/first/
├── agent_summary.json   # one aggregated, repair-ready item per root cause
├── feedback_bundle.json # privacy-safe summary for external issue reports
├── report.json
├── junit.xml
├── report.sarif
└── screenshots/

一次真实的内部试用发现如下：

{
  "dimension_id": "text_scale_layout_break",
  "selector": "body > div:nth-of-type(2) > div:nth-of-type(2) > a",
  "text_snippet": "我也要创建 →",
  "problem": "page is 9px wider than the viewport at 1.5x text scale",
  "trigger": "mobile-360-150-safe0 (360x800); mobile-360-150-safe34 (360x800)",
  "severity": "block"
}

报告会说明问题、发生位置、受影响的视口组合，并向 Agent 提供可复现故障的命令。

真实页面暴露的问题

v0.8.2 内部试用检查了所有 20 个由 Ego 所有、处于生产环境或已生成的规范页面，未发现运行时错误。将对网络敏感的性能观察与确定性交付问题分开后，十个页面没有问题，十个页面存在可采取行动的结构性问题。稳定复现的问题包括六处文本放大导致的布局损坏、四处底部安全区域穿透、五个文本裁切根本原因、四组尺寸不足的目标，以及一个加载缺失 Service Worker 的生成页面。在此语料中，没有已知的稳定阻塞性误报。这是一个规模较小且公开说明的语料，并非对整个市场准确性的声明；完整证据、原始混合配置文件计数和局限性见 docs/real-world-dogfood-2026-10-31-v0.8.2.md。

现在，布局问题会指出拥有溢出内容的最深层、未裁切元素，让 Agent 获得具体的修复选择器，而不是 html。

查看一个生成页面如何从三个根本原因减少到零个阻塞性缺陷，详见 词汇修复案例研究。 如果你想在自己的某个页面上测试同一流程，请遵循 15 分钟首次试用流程。 现场反馈流程规定了如何对真实案例进行分类，并将其转化为干净的对照样本或基准测试夹具。

为什么

生成的页面通常可以通过单元测试，却仍然会带有明显的交付缺陷：内容超出手机屏幕、按钮不可见、图片损坏、控制台报错、行动号召没有任何效果，或用户尝试点击时页面发生偏移。

ego-webqa 可将这些问题转化为确定性检查。它不是视觉回归服务，也不要求编写测试或保存已批准的屏幕截图。

安装

从 PyPI 安装已发布的包：

python -m pip install ego-webqa
ego-webqa setup

要在发布前安装当前检出版本：

git clone https://github.com/ROY32172310/qa.git
cd qa
python -m pip install .
ego-webqa setup

用于开发时，请使用已提交的锁定文件：

uv lock --check
uv sync --locked --all-extras
uv run --locked ego-webqa setup

不使用 uv 时，仍支持 python -m pip install -e '.[dev]'。

如果已安装 uv，且不希望持久安装 Python 包，可通过隔离且固定版本的 uvx 环境运行相同命令：

uvx --from ego-webqa==0.8.2 ego-webqa setup
uvx --from ego-webqa==0.8.2 ego-webqa https://your-preview.example

包会固定 Playwright 的版本，浏览器二进制文件则存放在 Playwright 的共享缓存中，因此临时 uvx 环境和后续 MCP 启动会复用同一浏览器修订版本。

如果 doctor 报告缺少 Linux 系统库，请使用 setup 安装这些库：

ego-webqa setup --with-deps

Setup 有意设计为独立的显式命令：wheel 安装可安全离线执行，而浏览器下载和操作系统更改则是可见、可重试的用户操作。setup 具有幂等性，并会复用已通过真实启动检查的浏览器。使用 setup --dry-run 查看与解释器绑定的准确命令，或使用 --force 重新安装受损的浏览器修订版本。

如需更底层的修复或显式安装命令，请使用：

ego-webqa install-browser
ego-webqa doctor

默认仅安装无头模式的 Chromium。如果同一台计算机上的其他工具需要完整的有头模式 Chromium 构建版本，请显式启用：

ego-webqa setup --full-chromium

使用系统 Chrome，而不是下载 Chromium：

ego-webqa https://example.com --browser-channel chrome

Firefox 和 WebKit

只安装所需的其他浏览器引擎，然后为整个审计选择该引擎：

ego-webqa setup --browser-engine firefox
ego-webqa https://example.com --browser-engine firefox

ego-webqa setup --browser-engine webkit
ego-webqa https://example.com --browser-engine webkit

Chromium 仍是默认引擎。每次审计只运行一个引擎；这不会悄悄增加浏览器开销，也不代表跨引擎一致性。webkit 选项使用 Playwright 的 WebKit 构建版本，可提供有用的 Safari 引擎证据，但并非在真实 iPhone、iPad 或 macOS Safari 上运行。如果交付决策有此要求，请进行真实设备测试。

使用

ego-webqa https://example.com
ego-webqa --dir ./dist --file index.html
ego-webqa https://example.com --preset quick
ego-webqa http://127.0.0.1:8000 --viewports 390x844:[email protected]~34,1280x800:desktop
ego-webqa https://example.com --browser-engine firefox
ego-webqa https://example.com --profile performance \
  --ready-selector "#app-ready" --wait-for-network-idle
ego-webqa https://example.com --smoke-success-selector "#thank-you"
ego-webqa https://example.com --smoke-scope all --smoke-require-assertion \
  --smoke-success-selector "#thank-you"
ego-webqa --dir examples/demo --config examples/webqa-demo-flow.json
ego-webqa https://example.com --profile accessibility
ego-webqa https://example.com --profile performance
ego-webqa https://example.com --profile full

退出代码：

• 0：通过或仅有警告
• 1：至少有一个阻塞错误
• 2：调用无效或浏览器／运行时故障

--viewports 接受 WIDTHxHEIGHT[:NAME][@TEXT_SCALE][~SAFE_BOTTOM_PX]。 显式指定的视口会替代默认矩阵。文本缩放必须介于 1.0 和 2.0 之间；模拟的底部安全区域必须介于 0 和 100px 之间。

--preset quick 会选择四种成对平衡的移动端变体，以加快 Agent 循环：每种宽度都涵盖两种文本缩放和两种安全区域状态，而交叉组合的缩放／安全区域状态则随宽度交替。--preset full 会显式选择默认的八变体矩阵。预设不能与 --viewports 同时使用。

每次运行都会生成自包含的证据。JSON 中的屏幕截图引用相对于报告目录，因此 Agent 和 CI 可以移动整个 产物目录，而无需重写路径：

webqa-report/
├── report.json
├── agent_summary.json
├── feedback_bundle.json
├── junit.xml
├── report.sarif
└── screenshots/

在 CI 门禁中添加 --fail-on-warn，即可要求报告完全无问题。

agent_summary.json 是面向 Agent 的精简视图。重复的问题会按已注册的维度汇总，因此，同一根因在多个 视口中出现时，只会生成一条修复项，并附上受影响的触发条件和可复现的命令。MCP 调用方会以结构化内容和简短文本结果的形式收到相同摘要。

feedback_bundle.json 是用于外部反馈的视图。默认情况下，它包含维度 ID、计数、经过清理的视口几何信息、浏览器引擎和目标类型，但不包含目标 URL、本地路径、自定义视口名称、选择器、页面文本、消息、原始证据、屏幕截图和配置内容。分享前请先检查。若要有意为私人问题添加上下文：

ego-webqa feedback --report webqa-report/report.json
ego-webqa feedback --report webqa-report/report.json \
  --include-target --include-selectors --include-messages \
  --out webqa-report/feedback-with-context.json

第一条命令会在报告旁重新生成默认反馈包。第二条命令需要显式选择启用，且可能包含页面敏感数据。

基线与回归门禁

将一次运行与已知良好的报告进行比较，无需维护屏幕截图。稳定指纹会结合已注册的维度及其选择器或根因：

ego-webqa https://your-preview.example \
  --out .qa/current \
  --baseline-report .qa/known-good/report.json \
  --gate new

ego-webqa delta \
  --baseline .qa/known-good/report.json \
  --current .qa/current/report.json

运行会生成包含 new、persistent、changed 和 resolved 根因的 delta.json。--gate new 仅当阻塞根因是新增、变为阻塞状态、阻塞出现次数增加或影响了额外视口时才会失败。现有且尚未解决的阻塞项仍会显示，但不会导致未发生变化的构建再次失败。添加 --fail-on-warn，也可对新增或变化的警告设置门禁。

两份报告必须使用相同的目标来源、配置方案、视口矩阵、浏览器引擎和浏览器通道。若要进行有意的跨目标或跨配置比较，必须使用 --allow-target-change 和／或 --allow-configuration-change。这是一种确定性问题差异比较，并非视觉回归基线。

每条修复项会保留第一个证据对象以兼容旧格式，并通过 evidence_by_viewport 映射完整记录跨视口证据。网络故障还会附带 failure_details，其中包含资源类型、框架 URL、同源状态、重定向来源、HTTP 状态或浏览器错误，以及发生次数。所有报告的 URL 都会移除查询字符串和凭据。

检查项

阻断性错误：

• 页面水平溢出
• 放大文本后布局错乱
• 底部控件侵入设备安全区域
• JavaScript 页面错误和 console.error
• 资源加载失败和 HTTP 错误
• 页面几乎空白
• 小于 10px 的文本无法阅读
• 可见图片损坏
• canvas/图片/视频的宽高比失真
• 主要 CTA 无响应
• 配置的冒烟流程目标或操作后断言失败
• 意外发生严重布局偏移

警告：

• DOM 已渲染，但 load 事件超出限定时限
• 小于 44px 的点击目标
• 小于 12px 的次要文本
• 尺寸过大的固定浮层
• 首次内容绘制缓慢
• 中度布局偏移
• 首次加载字节数或请求数过多

浏览器探测会报告事实。所有阈值和通过/失败判定都在 src/ego_webqa/config.py 中。 宽高比检查仅评估渲染尺寸至少为 aspect_min_rendered_px（默认为 48px）的媒体，以避免小图标产生像素舍入噪声。

维度

问题代码属于 src/ego_webqa/dimensions.py 中封闭且有版本控制的注册表。报告会拒绝未注册的代码，每条 Agent 摘要项都包含维度 ID、版本、检测器和默认严重程度。文档和集成可直接检查同一权威数据源，无需解析说明文字：

ego-webqa --list-dimensions

配置档案

baseline 是默认交付配置档案。它会检查页面是否渲染、是否有响应、是否适配视口，以及主要操作是否可用。它会刻意将对网络敏感的观测排除在交付门槛之外：首次绘制、load 事件时限、网络空闲超时，以及传输/请求预算都不会在 baseline 中产生问题。

performance 包含所有 baseline 检查，并增加这四项对网络敏感的观测。在受控网络环境中运行审计，或调用方明确希望设置观测性性能门槛时，请使用此配置档案。

accessibility 包含所有 baseline 检查，并增加以下确定性检查：

• 缺少文档语言或页面标题
• 控件没有可访问名称
• 可见图片没有 alt 属性
• 交互内容位于 aria-hidden 容器内
• ID 重复和标题级别跳跃
• 正 tabindex 值覆盖自然焦点顺序

此配置档案可发现常见的机器可检测缺陷。它不是 WCAG 符合性审计，也不能替代键盘和辅助技术测试。

full 会同时启用 baseline、performance 和 accessibility 类别。 所有配置档案的原始计时测量结果都会保留在 report.json 中；所选配置档案决定哪些已注册维度可以生成问题。

配置

ego-webqa https://example.com --config examples/webqa.json

{
  "profile": "full",
  "viewport_preset": "full",
  "min_tap_target_px": 44,
  "min_font_px": 12,
  "ready_selector": "#app-ready",
  "wait_for_network_idle": true,
  "smoke_mode": "safe",
  "smoke_scope": "all",
  "smoke_settle_ms": 800,
  "smoke_require_assertion": true,
  "smoke_success_selector": "#thank-you",
  "smoke_success_url_pattern": "/complete$",
  "ignore_selectors": [".third-party-chat-widget"],
  "ignore_console_patterns": ["third-party-widget"],
  "ignore_request_patterns": ["/analytics/"]
}

对于包含四种变体的首轮检查，请使用 "viewport_preset": "quick"；也可以将其替换为项目专用的显式 "viewports" 列表。预设和显式列表不能同时使用。

如果主要操作的文本与默认 CTA 词汇不匹配，请使用 --smoke-selector "#checkout"。安全冒烟测试会中止 HTTP 请求，并在初始加载后将隔离的浏览器上下文切换为离线状态。只有在确实需要产生实际副作用时才使用 --smoke-mode live；如果连仅操作 DOM 的点击也不希望发生，则使用 --no-smoke。

smoke_success_selector 和 smoke_success_url_pattern 会用显式的点击后契约替代通用的“状态发生变化”启发式判定。两者都已配置时，都必须从不匹配变为匹配。

将 smoke_scope 设为 all，即可在每种视口中独立测试 CTA。对于不得将模糊的 DOM 变化视为成功的交付门槛，请使用 smoke_require_assertion。

有界冒烟流程

对于简短的客户端路径，smoke_flow 可以描述一系列有序的确定性操作。它最多接受八个来自固定集合的步骤：

• click：点击一个选择器；
• fill：填写一个选择器，其值会在报告中脱敏；
• press：在一个选择器上按下某个按键；
• expect_visible：要求某个选择器变为可见；
• expect_url：要求当前 URL 与正则表达式匹配；
• expect_text：要求可见元素的渲染文本，或表单控件的当前值，与不区分大小写的正则表达式匹配。

{
  "smoke_mode": "safe",
  "smoke_flow": [
    {"action": "fill", "selector": "#email", "value": "[email protected]"},
    {"action": "click", "selector": "#continue"},
    {"action": "expect_visible", "selector": "#success"},
    {"action": "expect_url", "pattern": "#complete$"},
    {"action": "expect_text", "selector": "#status", "pattern": "^Ready$"}
  ]
}

流程必须包含一个 click、fill 或 press 操作，且后续至少包含一项 expect_visible、expect_url 或 expect_text 断言。流程不能与单 CTA 选择器／断言字段同时使用。默认的 safe 模式会在初始页面加载后阻止 HTTP 请求，因此除非将 smoke_mode 显式更改为 live，否则流程仅限于确定性的客户端行为。不接受任意 JavaScript 和用户定义的检测器。

expect_text 通过 Playwright 读取 input、textarea 和 select 的值；其他所有元素均使用可见元素的渲染文本。隐藏的后代元素不会被视为已交付内容。报告会保留匹配模式、来源类型和观测长度，但绝不会将观测到的文本复制到证据中。这样既能确保文本断言具有确定性，又不会暴露输入到页面中的值。

流程失败时，report.json 会包含每个已完成的步骤、失败的步骤及其错误。Agent 摘要会指出具体操作，而不是笼统地报告按钮失效。

项目可以在一个配置中保留多个固定流程，并按名称选择其中一个：

{
  "smoke_flow_name": "checkout",
  "smoke_flows": {
    "login": [
      {"action": "fill", "selector": "#email", "value": "[email protected]"},
      {"action": "click", "selector": "#continue"},
      {"action": "expect_visible", "selector": "#welcome"}
    ],
    "checkout": [
      {"action": "click", "selector": "#buy"},
      {"action": "expect_text", "selector": "#status", "pattern": "^paid$"}
    ]
  }
}

流程名称是固定标识符，须匹配 [A-Za-z0-9][A-Za-z0-9._-]{0,63}；最多接受 16 个定义。每个定义都会经过验证，但只会运行选定的流程。smoke_flows 与单个内联 smoke_flow 互斥；具名流程与单步 smoke_selector／成功断言也互斥，因为每个具名流程都必须包含自己的交互和断言。使用 --smoke-flow-name checkout 覆盖配置的默认流程；报告会保留选定的名称，并像之前一样对填入的值进行脱敏。

对于加载事件后才出现 SPA 内容的情况，请使用 ready_selector。可以通过正则表达式排除已知的第三方控制台和请求噪声，而不会隐藏基于 DOM 的发现项。被忽略的响应不会计入请求数和传输字节预算。报告会记录是否已达到就绪内容、字体和有界网络空闲状态。

需要身份验证的预览

支持通过 JSON 配置或环境变量访问受 HTTP Basic 身份验证、请求标头或已登录浏览器会话保护的预览：

export EGO_WEBQA_HTTP_USERNAME=preview-user
export EGO_WEBQA_HTTP_PASSWORD=preview-password
export EGO_WEBQA_EXTRA_HTTP_HEADERS='{"X-Preview-Key":"agent-key"}'
ego-webqa "$PREVIEW_URL" --storage-state ./auth/storage-state.json

凭据和标头值会在 JSON 报告中脱敏。通过环境变量传递这些值，也可以避免它们出现在 CLI 进程参数列表中。

平台与多 Agent 使用

审计引擎可在 Linux、macOS 和 Windows 上运行，要求 Python 3.10 或更高版本。 CI 会在这三种操作系统上运行相同的测试套件。

每次 audit() 或 CLI 调用都拥有自己的浏览器生命周期、浏览器上下文、 静态本地服务器和输出目录。审计状态不共享且可变，因此只要每个 Agent 都提供唯一的 --out 目录，多个 Agent 就可以并发运行：

ego-webqa "$PREVIEW_URL" --out "webqa/$AGENT_ID" --json \
  --smoke-scope all --smoke-require-assertion \
  --smoke-success-selector "#thank-you"

--json 会打印写入 report.json 的同一份稳定数据。 schema_version 决定兼容性；JUnit 和 SARIF 均从同一份内存中的问题列表生成。Agent 应将退出代码 0 视为通过/警告，1 视为存在阻断性发现，2 则表示调用或浏览器失败。

八种公开的 JSON 数据格式都附带打包的 Draft 2020-12 架构。使用 ego-webqa --print-schema report 打印其中一种；格式名称和 兼容性策略请参阅 docs/json-contracts.md。

在一次审计中，最多有三个视口在相互隔离的浏览器中并发渲染。 这样可以限制慢速网站带来的总耗时，同时避免在视口之间共享 Cookie、网络 状态、屏幕截图或可变证据。

MCP 服务

在 AI 编码 Agent 中直接启用此门禁：

python -m pip install ego-webqa
ego-webqa setup
ego-webqa mcp

ego-webqa-mcp 仍可用作兼容性别名。MCP 客户端可通过 stdio 启动任一命令。与注册表兼容的一次性调用形式为 uvx [email protected] mcp。该服务会公布一个工具 audit_web_page，并返回结构化的成功结果和阻断错误结果：

{
  "mcpServers": {
    "ego-webqa": {
      "command": "uvx",
      "args": ["[email protected]", "mcp"]
    }
  }
}

典型的工具参数如下：

{
  "url": "http://127.0.0.1:5173",
  "out_dir": ".qa/agent-a",
  "config": "/workspace/webqa-flow.json",
  "profile": "accessibility",
  "browser_engine": "webkit",
  "viewport_preset": "quick",
  "smoke_flow_name": "checkout",
  "smoke_scope": "all"
}

config 路径是 MCP 集成点，可用于配置有限的 smoke_flow 序列、身份验证请求、忽略策略，以及其他无需在每次工具调用中重复传入的设置。

当报告状态为 fail 时，MCP 结果会标记为错误，同时完整报告仍以结构化内容形式提供。身份验证环境变量由服务进程读取，而不是作为工具参数传入。此适配器有意仅作为交付可用性门禁；它不是安全扫描器、WCAG 认证工具或视觉回归系统。

受治理的值覆盖

项目可以临时调整已注册的维度，而无需禁用该维度或添加任意断言。每项覆盖都必须注明负责人、原因和到期时间；也可以更改有效的 block/warn 严重级别，并且只能使用该维度已声明且可安全覆盖的阈值：

{
  "overrides": [
    {
      "dimension_id": "tiny_fonts",
      "reason": "Typography migration tracked in DS-142",
      "owner": "design-system",
      "expires": "2026-11-30",
      "severity": "warn",
      "parameters": {
        "min_font_px": 13
      }
    }
  ]
}

UTC 审计日期是到期时间的计算基准。覆盖在其 expires 日期当天仍然有效，次日会自动恢复为注册表默认值。未知维度、未知或不安全的参数、重复的维度条目，以及针对同一共享阈值的冲突值，都会被拒绝。

report.json 会在每个受影响的问题中记录覆盖信息，并添加一个 governance 区块，其中包含有效和已过期的声明以及有效参数。agent_summary.json 会携带相同的来源元数据，并报告 overridden_dimensions、downgraded_blocks 和 expired_overrides。JUnit 和 SARIF 使用有效严重级别。已过期的覆盖仍会保留以供审计，但不再影响检测或状态。参阅 examples/webqa-governed.json。

DeepSeek Harness 可通过独立的声明式 dsh-ego-webqa bundle 安装相同的 MCP 工具。它复用 DSH 原生 MCP 客户端，而不另行添加一套 QA 实现；有关边界和验收标准，请参阅 docs/dsh-integration.md。

GitHub Actions

此仓库也是一个复合 GitHub Action。该 Action 会从 Action 引用安装软件包，安装选定的浏览器引擎（默认使用 Chromium），运行审计，即使审计失败也会上传报告，并在作业摘要中写入简洁且保护隐私的根因表：

jobs:
  delivery-qa:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v6
      - uses: ROY32172310/[email protected]
        with:
          url: ${{ vars.PREVIEW_URL }}
          browser-engine: webkit
          profile: accessibility
          viewport-preset: quick
          smoke-flow-name: checkout
          fail-on-warn: "true"
          smoke-scope: all
          baseline-report: .qa/known-good/report.json
          delta-gate: new
          http-username: ${{ secrets.PREVIEW_USERNAME }}
          http-password: ${{ secrets.PREVIEW_PASSWORD }}
          extra-http-headers: ${{ secrets.PREVIEW_HEADERS_JSON }}
          artifact-name: webqa-${{ github.run_id }}

在本地检出此仓库后，检出完成即可使用 uses: ./。该 Action 默认使用 safe 冒烟模式；只有在明确允许点击产生实际副作用时，才设置 smoke-mode: live。完整的输入集请参见 examples/github-action.yml 和 action.yml。只有在同一提交通过完整的跨平台 CI 矩阵后，才会创建 @v0.8.2 标签。

Python API

from ego_webqa import Settings, SmokeStep, audit

settings = Settings(
    smoke_flow=(
        SmokeStep("click", selector="#continue"),
        SmokeStep("expect_visible", selector="#success"),
    )
)
report = audit("https://example.com", settings=settings, output_dir="qa")
print(report.status)

范围与独立性

这是一个用于检测明显交付故障的确定性粗粒度门禁。有限的冒烟流程可以验证一条已配置的短客户端路径是否到达其声明的可见状态、文本／值或 URL；但它不能证明业务正确性、所有受支持的浏览器表现一致，也不能证明页面安全。

固定报告范围：

本报告仅覆盖多终端几何与基础体验的确定性粗检；业务主路径、跨浏览器兼容、安全合规需另行验证。

此仓库是从最初在 ego 项目中验证的通用交付检查中独立提取而来。它不依赖 ego_protocol、ego_uri、ego 分享、部署、小程序或产品外壳语义。特定产品的检查应放在插件中，而不是核心部分。

基准测试与可信度

此仓库将受控的本地回归基准测试与真实世界的公网上观测分开：

• benchmarks/ 在窄屏、移动设备、平板和桌面设备变体上运行 128 个独立的合成用例。它是串行 Chromium 延迟基线，也是全部 38 个已注册维度的正确性语料库。
• dogfood/ 运行固定的真实页面样本，并分别报告 url 和 local 结果。这是观察性证据，而非延迟阈值，因为网络和目标站点行为会在工具控制范围之外发生变化。

每个基准测试场景都会声明其真实结果；评估器不会导入检测器阈值来判断结果是否正确。

python benchmarks/run.py

评估器会报告维度精确匹配率、用例精确率／召回率／F1、阻断性误报率和漏报率、维度级别的 TP／FP／FN，以及完整审计延迟。它会生成机器可读的证据和 Markdown 摘要。0.7.0 基线在串行本地 Chromium 中为 128/128 精确匹配，阻断性 FP／FN 为 0%，P50 为 357ms，P95 为 1147ms，最大值为 3615ms： docs/benchmark-2026-10-30-v0.7.0.md。

这些结果衡量的是 Chromium 中精心设计的合成测试样例，而非真实网站覆盖情况或跨引擎一致性。Firefox 和 WebKit 有单独的真实浏览器 CI 测试样例，用于验证无故障页面和确定性溢出故障。基准测试的价值在于施加回归压力：首次运行发现了标准 <label> 标记会导致 accessibility 配置崩溃，以及 CTA 根因重复报告的问题；这两个问题都在记录基线前得到修复。有关测量规范和两类证据，请参见 docs/performance-baselines.md。

开发

uv sync --locked --all-extras
uv run --locked ego-webqa setup
uv run --locked python scripts/dev.py test
uv run --locked python scripts/dev.py coverage
uv run --locked python scripts/dev.py lint
uv run --locked python scripts/dev.py format-check
uv run --locked python scripts/dev.py typecheck
uv run --locked python scripts/dev.py benchmark
uv run --locked python scripts/dev.py package
uv run --locked python scripts/dev.py check   # lint + format + MyPy + coverage
uv run --locked python scripts/dev.py full    # check + Chromium benchmark

GitHub Actions 在 Linux、macOS 和 Windows 上也使用相同的 scripts/dev.py 入口和锁文件，避免本地与 CI 的依赖或命令出现偏差。覆盖率要求行覆盖率／分支覆盖率不低于 90%。添加规则前请参见 CONTRIBUTING.md。每条规则都需要一个正向对照和一种已观察到的故障模式。

许可证

MIT