accessibility

无障碍 — 技能入口

此技能是 HVE Core 的规范性无障碍参考契约。Agent 和指令会按名称调用此技能，并依赖它处理框架参考资料解析、阶段指南解析和扫描器 CLI 入口。

框架参考资料

• WCAG 2.2
• ARIA Authoring Practices Guide
• 认知无障碍指南
• Section 508
• EN 301 549
• 图形 ARIA 和 SVG-AAM

评估参考资料（跨领域，并非一致性框架）：

• 辅助技术播报模型 — 在确定播报类别的判定标准（WCAG 1.3.1、4.1.2、4.1.3）时阅读此文：屏幕阅读器用户应该听到什么，以及如何通过无障碍树断言或手动辅助技术测试来判定。

无障碍规划器工作流

无障碍规划器分六个阶段运行，每个阶段对应一个状态 ID：

1. 阶段 1 — 探索（discovery）
2. 阶段 2 — 框架选择（framework-selection）
3. 阶段 3 — 标准映射（standards-mapping）
4. 阶段 4 — 计划风险评估（plan-risk-assessment）
5. 阶段 5 — 影响与证据（impact-evidence）
6. 阶段 6 — 待办事项移交（backlog-handoff）

阶段参考索引

• 阶段 1 — 探索：capture-coaching.md — 以探索优先的方式提出信息收集问题时阅读此文。
• 阶段 2 — 框架选择：framework-selection.md — 选择适用的框架和一致性等级时阅读此文。
• 阶段 3 — 标准映射：遍历框架参考资料汇总表，生成 controlMappings；阶段 5 会使用这些映射。没有专门文件 — 映射由框架汇总表驱动。
• 阶段 4 — 计划风险评估：当升级触发条件重新开启范围界定时，capture-coaching.md规定了提问方式；根据无障碍规划器身份指令应用分级标准，并记录为 riskClassification.tier。没有专门文件 — 无障碍风险范围较窄，适合以内联方式呈现。
• 阶段 5 — 影响与证据：impact-assessment.md — 构建证据登记表、权衡日志和初始工作项时阅读此文。
• 阶段 6 — 待办事项移交：backlog-handoff.md — 呈现工作项并验证移交关卡时阅读此文。

方法充分性（判定与提示）

方法充分性原则规定：只有当某种验证方法确实能够判定成功标准时，才能记录为满足该标准。能够观察相关信号、却无法确认面向用户的结果的方法，只能为该标准提供提示；它可以提高或降低疑虑，但无法据此判定标准已满足。本节是规范性定义；规划器证据登记表、审核者判定逻辑和运行时探测测试框架都会依据此定义评估方法是否充分。

机器可读的方法充分性来源是 scripts/runtime_a11y/probe-criteria-map.json。每个探测条目都会列出它能够判定的标准，以及只能提示的标准。只有当最终采用的方法出现在该标准和状态对应的 decides 列表中时，结果才算充分。

缺陷类别与充分的方法

无障碍缺陷分为五类。静态分析（axe、eslint-plugin-jsx-a11y、快照结构计数）只能判定第一类；其余四类需要通过交互状态探测或辅助技术（AT）检查来判定，而不能仅提供参考。

类别	代表性 WCAG 成功准则	静态分析的能力	判定所需的充分方法
静态可判定的结构	1.1.1、1.4.3、4.1.2（名称存在）、2.4.2、3.1.1	判定	axe / 静态扫描
交互行为	2.1.1、2.1.2、2.4.3、2.4.7、2.4.11	仅提供参考	使用键盘/交互探测，在 focus/open 状态间按键操作，或手动进行键盘检查
播报正确性	1.3.1、4.1.2（计算所得的名称/角色）、4.1.3	仅提供参考	对无障碍树中的计算所得名称/角色/实时状态进行断言，或手动进行 AT 检查（Windows NVDA 或由人工操作的 JAWS）
自适应渲染	1.4.4、1.4.10、1.4.12、2.4.11	仅提供参考	在 200% 缩放、320px 重排和文本间距状态下进行渲染探测
伪语义	1.3.1（伪标题）、2.4.3（伪控件）	无法检测	启发式源代码检查并辅以无障碍树断言；不存在可供规则引擎标记的元素

对于播报类别，辅助技术播报模型规定了用户针对每项准则应听到的内容，以及如何进行判定。对于交互和伪语义类别，焦点管理反模式目录列出了静态扫描能够通过、却会影响键盘和屏幕阅读器用户的缺陷。

充分性规则

• 交互、播报、自适应渲染或伪语义类别中的控件，不能仅凭静态证据记录为完全满足。在附加充分的方法之前，静态证据最多只能将此类控件标记为部分满足。
• 如果某项准则的首选方法只能提供参考，就绝不能将其作为符合性判定；它只能作为线索，引导至充分的方法或人工检查。
• 应将充分性判定与状态一并保留，以免后续规划人员和审核人员再次将验证不足的控件提升为已满足。

本准则及其类别体系为仓库原创内容，依据 CC BY 4.0 许可；底层成功准则的定义仍归 WCAG 2.2 所有，详见 wcag-22.md。

校准衡量的是证据质量，而非符合性判定

校准用于确认辅助技术栈的行为符合预期，然后再信任其输出。对于通过的操作流程，校准检查点会记录驱动程序身份、配置文件指纹和构件哈希值。

检查点刻意不作为矩阵输入。覆盖率或结果流水线都不会读取检查点，这是有意为之，而非尚未完成。校准通过说明测试框架运行正常；但这并不表示该界面满足某项成功标准。将检查点接入覆盖率计算，会把对工具的说明变成对产品的说明。

如果校准证据将来需要影响覆盖率，这就属于新的设计工作，需要单独评审：必须明确规定从操作流程到标准、界面和状态的映射，并遵循与其他证据相同的方法充分性规则。

根据评估等级调整门禁严格程度

交互、公告、自适应渲染和伪语义类别的执行策略，会随着 riskClassification.tier 中记录的评估深度等级逐步提升。因此，门禁会继承项目选择的严谨程度，而不是采用一个全局开关：

• basic — 方法充分性探测（keyboard、widget-keyboard、live-region、aria-tree、virtual-sr）仅提供建议（只警告）；始终可判定的核心探测仍会阻止通过。
• standard（默认）— 渐进收紧：方法充分性探测会阻止新界面或发生变化的界面通过，对于现有积压问题则仅提供建议。这样一来，这些类别不会出现新的缺陷，同时也能呈现遗留内容，而不冻结项目。
• comprehensive — 方法充分性探测会对每个范围内的界面一律阻止通过。

始终可判定的核心探测（axe、DOM 卫生、失效链接、控制台错误、目标尺寸、对比度、重排/缩放）在每个等级都会阻止通过。CI 工作流模板通过 A11Y_TIER 和 A11Y_RATCHET_SURFACES 输入实现此调节；Accessibility Reviewer 对其 FAIL 和 PARTIAL 判定也采用相同的逐级提升策略。

工具

扫描器 CLI（scripts/scan.py）封装了基于 Node 的 axe-core 扫描器，并将其发现结果规范化为稳定的 JSON 格式。

前置条件

• Python 3.11+，且 PATH 中可用 uv。
• Node.js，且 PATH 中可用 npx。
• 首次运行时需要网络连接，以便 npx 获取 @axe-core/cli。

快速开始

uv run scripts/scan.py https://example.com --allow-host example.com
uv run scripts/scan.py ./page.html --output results.json
uv run scripts/scan.py file:///path/to/page.html

环回 HTTP(S) 目标无需额外选项。其他所有远程主机都必须提供匹配的、可重复使用的 --allow-host HOST 值，或使用范围更广的 --allow-external 确认。本地路径和本地 file: URI 必须解析为现有的普通文件。在 axe CLI 启动前，网络共享、远程文件权限、目录、缺失文件、凭据、以连字符开头的目标以及非 HTTP(S) 的远程协议都会被拒绝。

参数参考

参数	必需	默认值	说明
target	是	—	经授权的 HTTP(S) URL 或现有的本地普通文件，用于扫描。
--output	否	stdout	写入规范化 JSON 结果的路径。
--allow-host	否	none	授权一个非环回 HTTP(S) 主机；需要时可重复使用。
--allow-external	否	false	确认可访问任何非环回 HTTP(S) 主机。

远程授权仅适用于扫描器的初始目标。它不会限制浏览器重定向、DNS 地址变更、子资源、WebSocket、Service Worker、下载或其他由浏览器发起的请求。请仅在网络信任级别与目标相匹配的工作站上运行扫描器。

脚本参考

• 入口：scripts/scan.py

• 输出格式：

  {
    "target": "<scanned target>",
    "summary": {
      "violations": 0,
      "passes": 0,
      "incomplete": 0,
      "inapplicable": 0
    },
    "violations": [
      { "id": "", "impact": "", "description": "", "nodes": 0 }
    ]
  }
  

• 退出代码：

  • 0 — 扫描成功完成。
  • 1 — 扫描失败或返回了无效输出。
  • 2 — 扫描器不可用（缺少 Node.js 或 @axe-core/cli）。

故障排除

症状	可能原因	处理方式	退出代码
出现 scanner unavailable 错误	PATH 中找不到 Node.js 或 npx	安装 Node.js，确保 npx 可用，然后重新运行。	2
首次运行时暂停较久或进行下载	npx 正在获取 @axe-core/cli	首次运行时允许网络访问；后续运行会使用缓存。	—
Refusing to probe non-loopback host	未明确授权远程主机	添加 --allow-host HOST，或使用 --allow-external 确认。	2
Local scan target does not exist	无法解析本地路径或文件 URI	提供一个确实存在的本地普通文件，而非目录或共享位置。	2
scan failed or returned invalid output	axe-core CLI 出错或输出了非 JSON 内容	确认目标 URL 或文件可访问且格式正确。	1
violations 为空，但预期应有问题	页面在扫描完成后才渲染，或规则不适用	确认目标已完全加载；检查 summary.inapplicable。	0

将发现映射到框架

每个违规项的 impact 为 minor、moderate、serious 或 critical 之一。axe 规则标签会去掉 wcag 前缀并插入小数点，以解码为 WCAG 成功标准：

axe 标签	WCAG 成功标准
wcag111	1.1.1 非文本内容
wcag143	1.4.3 对比度（最低）

WCAG 成功标准具有规范性；揭示这些标准的 axe 技术则具有参考性。应将扫描器输出视为指向某项标准的证据，而非符合性判定。

运行时探测工具

运行时探测工具（scripts/runtime_a11y）会针对项目特定的界面清单运行基于 Playwright 的无障碍探测，并将结果汇总为覆盖矩阵。对于工作流编排，请让用户运行仅限手动操作的 accessibility-coverage-matrix 技能（/accessibility-coverage-matrix）；该技能无法由模型调用。使用 Accessibility Surface Inventory 子 Agent 作为运行时配置的权威生成方。请按名称启用它；如果无法解析，请告知用户该功能不可用，并停止依赖该功能的步骤。

Harness 前置条件

运行任何运行时 Harness 命令之前，请先完成以下步骤。这些步骤与上述 scan.py 的前置条件相互独立。

• Python 3.11+，并确保 uv 可通过 PATH 使用。
• 确保 Node.js 可通过 PATH 使用，并安装系统级 Google Chrome，因为探测会以 channel: 'chrome' 为目标。
• 在 scripts/runtime_a11y 下安装此技能本地的 Node 依赖。缺少依赖时，CLI 会快速失败并提示安装。
• 自动化 Windows NVDA 运行还需要清单所选的 Guidepup NVDA 资源。配置计算机与安装资源是 npm ci 之外的独立操作。

从 scripts/runtime_a11y 目录安装 Harness 依赖：

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 npm ci

$env:PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD = '1'; npm ci

PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1 可避免下载 Harness 不会使用的捆绑浏览器。

对于自动化 NVDA 运行，请先配置 Windows 计算机，然后安装技能本地 Guidepup 软件包所选的资源。更新 Guidepup 后，请再次运行资源命令：

Set-Location <skill-root>/scripts/runtime_a11y
npx --yes --registry=https://registry.npmjs.org/ @guidepup/[email protected] setup
npx --yes --registry=https://registry.npmjs.org/ @guidepup/[email protected] install nvda

这些命令会配置计算机，并将带版本号的资源写入 Guidepup 用户缓存。它们不属于常规依赖安装流程。校准会话前，请运行仅检查前置条件的探测：

uv run scripts/runtime_a11y/__main__.py run-calibration --config <path-to>/a11y-runtime.config.json --prerequisite-only

预检会分别报告技能本地库、清单所选的 NVDA 资源以及任何冲突的 NVDA 进程。自动化运行前请勿启动个人 NVDA 实例；Harness 会启动隔离会话，并拒绝在已有进程运行时继续。

与产品无关的屏幕阅读器用例位于 scripts/runtime_a11y/screen-reader-cases.json。下游绑定会提供命名路由、目标、状态和明确的执行方案。目录摘要不匹配、目标范围不完整、身份重复、不支持的命令、包含密钥的绑定键以及推断出的操作，都会在浏览器启动前导致失败。

对于经授权的实时子集，请使用可重复的 run-calibration --journey <id> 参数。在产品用例之前运行下游完整性方案，并将真实 NVDA 用作建议性或手动测试。若要获得确定性证据，请结合表面／状态筛选条件使用 run-all --probe <probe-id>，或使用经审查的 probeScoping 配置；不得将常规 run-all 视为启动真实屏幕阅读器的许可。

调用

通过脚本入口点运行 Harness。从技能根目录（即包含 pyproject.toml 的目录）调用，以便 uv 解析技能自己的环境。此调用约定与 scan.py 和其他 Python 技能一致，无需设置 PYTHONPATH。

uv run scripts/runtime_a11y/__main__.py run-all --config a11y-runtime.config.json --out results.json
uv run scripts/runtime_a11y/__main__.py probe <probeId> --config a11y-runtime.config.json
uv run scripts/runtime_a11y/__main__.py render-artifacts --matrix coverage-matrix-repo.json --output-dir .copilot-tracking/accessibility/coverage --repo-slug repo
uv run scripts/runtime_a11y/__main__.py compose-evidence --help

若要从其他工作目录运行，请将该技能固定为 uv 项目，并使用相同的脚本路径：

uv run --project <skill-root> <skill-root>/scripts/runtime_a11y/__main__.py run-all --config a11y-runtime.config.json --out results.json

• --config 相对于当前工作目录解析。
• --out 将聚合的 JSON 文档写入磁盘。
• --base-url 会覆盖配置的基础 URL。除非主机已加入允许列表或提供了 --allow-external，否则该 URL 必须保持为环回源。
• --trace 会捕获 Playwright 跟踪记录和屏幕截图。
• --allow-external 表示确认有意探测非环回主机。
• render-artifacts 会将渲染后的矩阵 JSON 文档转换为完整的覆盖率证据包。

证据包组成

compose-evidence 会将下游拥有的目录、节奏范围、运行上下文、规范化来源信封、状态证明和可选的合格审阅者补充内容组合成一个确定性证据包。它与 render-artifacts 分开：渲染会根据矩阵生成覆盖范围、EARL 和手动计划视图，而组合会在不同证据生成方之间创建与修订版本绑定的信任信封。

此命令要求显式指定输入路径，且绝不会推断产品范围、Git 状态、时间、保留策略、分支策略或发布结论。这些决策由使用方项目负责。组合器会验证 --artifact-root 下的制品字节，保留冲突和隔离结果，并始终输出非证明元数据。自动化、审阅者证据和发布证据分别具有独立的完整性状态。

对于拉取请求，有效的初始证据包可以将审阅者证据报告为待处理。合格审阅者之后可以提供经过隐私最小化、与摘要绑定的补充内容和注册表快照，以便根据先前的证据包进行确定性重新组合。重新组合必须同时提供 --prior-bundle 和独立保留的 --prior-bundle-digest；省略或篡改先前历史记录都会导致安全失败。缺少必需的审阅者证据会阻止发布完整性，但不会阻止普通证据包的生成。普通证据包中禁止包含屏幕阅读器原始短语和受限的转录路径；只有经批准的计数、已脱敏元数据和摘要可以跨越此边界。

仅当下游工作流有意将相应维度设为门槛时，才使用 --require-completeness automated、reviewer 或 release。有效但不完整的证据包仍会写入，以供诊断。新增的退出码如下：

退出码	含义
5	自动化证据不完整。
6	审阅者证据待处理或无效。
7	发布证据不完整。

现有退出码 0 到 4 的含义保持不变。JSON 合约与运行时文件位于同一目录，文件名为 evidence-bundle.schema.json、evidence-source.schema.json、evidence-scope.schema.json、screen-reader-method-cell.schema.json 和 qualified-human-result.schema.json。

有关从未启用的模板到首次保留证据包及确定性重新组合的完整采用流程（包括每种自创输入的符合架构示例），请阅读 references/evidence-composition-adoption.md。

视觉审阅捕获

capture-visual-review 会为已配置的界面和状态记录确定性屏幕截图证据。运行时配置中的 visualReview.enabled 必须为 true。

uv run scripts/runtime_a11y/__main__.py capture-visual-review \
  --config <path-to>/a11y-runtime.config.json \
  --run-root .copilot-tracking/accessibility/local-runs/<run-name>

• --run-root 用于选择证据目录。该路径相对于仓库根目录解析，且必须位于 .copilot-tracking/accessibility/local-runs 内部的子路径下。此根目录以外的路径以及路径遍历片段均会被拒绝。
• 省略 --run-root 时，会在同一根目录下分配一个带时间戳的运行目录。
• --visual-surface 和 --visual-state 用于将捕获范围缩小到指定的已配置 ID。
• 命令所针对的服务遵循 serveMode。请参阅服务模式。

服务模式

运行时配置中的 serveMode 决定测试框架是否为 capture-visual-review 管理服务。

serveMode	行为
auto	复用配置的环回源上运行正常的服务；否则构建并启动由其管理的服务，并在之后停止。
served	要求配置的环回源上已有服务响应；若无响应，则失败并显示预期源和启动命令。
external	从不探测或启动服务。配置的目标必须已可访问。
off	从不探测或启动服务。

auto 和 served 仅接受环回源，因为测试框架不会管理或健康探测远程服务。非环回目标仍需加入允许列表或使用 --allow-external，且仅在 external 或 off 模式下有效。

在 auto 模式下，启动由其管理的服务前会先构建站点，因此需要自行启动服务的截图任务在截取第一张截图前会耗费数分钟。让服务继续运行在配置的源上即可跳过这段耗时，这就是复用路径。

此存储库中的 Docusaurus 站点配置为在 http://127.0.0.1:3001 上使用 auto 模式，这与 Playwright 端到端测试套件使用的生产构建源相同。针对生产构建进行截图，可确保视觉证据与持续集成验证的内容保持一致。

配置摘要

测试框架会加载 scripts/runtime_a11y/config-schema.json，并要求运行时配置包含 baseUrl、serveMode、allowlist、routes、surfaces 和 probeScoping 等字段。配置定义探测器执行的表面和交互状态。运行时保护机制会阻止访问非环回目标，除非主机已加入允许列表，或调用方提供 --allow-external。serveMode 控制视觉审查截图的服务所有权，详见服务模式。

真实 NVDA 旅程支持三种截图模式：

• single 在命令执行后及配置的等待间隔结束后读取累计语音日志。
• clear-and-capture 在等待间隔前清除先前的语音，然后读取累计日志。
• action 使用 Guidepup 操作截图包装现有的启动后声明式触发器。断言可以选择 actionSpeech 或 actionNormalizedSpeech，仅评估归因于该触发器的输出。

操作截图会等待 Guidepup 一秒钟的语音静默窗口。它适用于由即时交互触发的播报，但不涵盖任意延迟更新，也无法生成 NVDA 未发出的语音。对于这类情况，请保留 single、clear-and-capture、无障碍树证据和手动辅助技术证据。如果旅程缺少 triggerAfterDriverStart、声明式触发器、真实的 Guidepup 驱动程序或操作截图支持，操作模式会安全地失败。

探测项清单与充分性映射

当前，测试框架在 scripts/runtime_a11y/runner 下包含以下探测项：

WCAG 和 ARIA APG 探测项：

• probe-axe
• probe-keyboard-traversal
• probe-focus-visible
• probe-focus-obscured
• probe-live-region
• probe-aria-tree
• probe-widget-keyboard
• probe-reflow-resize
• probe-target-size
• probe-contrast
• probe-forced-colors
• probe-reduced-motion
• probe-structure-crawl
• probe-name-in-label
• probe-use-of-color（1.4.1）
• probe-text-spacing（1.4.12）
• probe-hover-focus（1.4.13）
• probe-link-purpose（2.4.4）
• probe-input-purpose（1.3.5）
• probe-forms（3.3.2，可为 3.3.1/3.3.3 提供信息）
• probe-context-change（3.2.1、3.2.2）
• probe-orientation（1.3.4）
• probe-audio-control（1.4.2）
• probe-timing（2.2.1）
• probe-zoom-blocker（1.4.4，可为 1.4.10 提供信息）
• probe-virtual-sr（从虚拟屏幕阅读器的语音短语日志中捕获 4.1.2 名称/角色播报；可为 1.3.1 提供信息）
• probe-real-sr（通过 Guidepup 适配器断言真实 Windows NVDA 播报；仅当存在已配置的预期且辅助技术栈可用时才会作出判断）

非 WCAG 缺陷扫描探测项（框架 defect-scan）：

• probe-console-errors（控制台/页面错误）
• probe-broken-links（同源 404）
• probe-dom-hygiene（重复 id、正数 tabindex、缺失/重复的地标）
• probe-title-lang（标题为空、lang 无效）

方法充分性编码在 scripts/runtime_a11y/probe-criteria-map.json 中。每个条目都记录探测项可以判定哪些准则，以及只能为哪些准则提供信息。只有当胜出方法符合该映射的许可时，结果才计为充分。

覆盖率引擎输出

scripts/runtime_a11y/matrix 中的矩阵引擎会展开准则 x 界面 x 状态网格，以确定性方式合并更新，并保留优先级较低的自动化结果无法覆盖的人工确认发现。它会按框架及整体计算充分覆盖率。render-artifacts 命令会生成一个确定性文件包，其中包含 coverage-matrix-{repo-slug}.json、coverage-matrix-{repo-slug}.md、accessibility-results-{repo-slug}.earl.jsonld、manual-at-testplan-{repo-slug}.md、manual-at-testplan-{repo-slug}.yaml 和 accessibility-artifacts-{repo-slug}.json。

EARL（评估与报告语言）JSON-LD 导出是标准化结果契约，可用于与 ACT Rules 生态系统及下游 VPAT 或 EAA 审查互操作。每个评估过的单元格都会成为一个稳定的 earl:Assertion，记录主体、准则、状态、方法、方法充分性、结果日期和证据。若胜出方法只能为其准则提供信息，该结果将标记为 earl:cantTell，绝不会错误地标记为 earl:passed。不适用的单元格标记为 earl:inapplicable；未评估的单元格则会省略。配套的人工计划包含仍需人工判定方法处理的单元格，并提供空白结果字段以便回填证据。

公共 ARIA-AT 与执行约定

scripts/runtime_a11y/aria-at-catalog.json 中的目录是仓库为生成面向 AT 的用例指定的文档化事实来源。其溯源字段严格且不可更改：每个映射都会记录本地目录版本、规范上游 URL、固定到提交的上游 URL，以及经审查后刷新所用的上游提交 SHA。仓库不会复制上游断言表或文字说明；它会转述 W3C 和 ARIA-AT 的官方意图，并在生成的产物中引用来源。

当前的公开策略刻意保持保守。五个入门默认项（模态对话框、复选框、仅选择型组合框、菜单按钮和标签页）都是带引用的仅手动映射，因为这些模式可能需要更丰富的 AT 模式和快速导航语义，而当前结构化命令边界无法忠实地对其建模。运行时覆盖可以创建明确的合成契约测试，但这些始终只是非通过的候选证据，绝不是无障碍符合性证据。解析器采用文档规定的回退顺序：state -> surface -> catalog；命令和断言以原子数组存储，而显式空数组则会有意禁用特定用例的执行。

未知模式仍会作为通用手动草稿或项目细化标记，而不会被伪装成自动化通过结果。若具体程度相同的选项存在歧义，则会在渲染或启动驱动程序之前将其视为配置错误。公共 CLI 提供 render-artifacts 作为可选的映射配置步骤，并将 run-at-plan 作为列出、选择、执行和报告生成的 AT 用例的受支持路径。当前真实驱动程序边界支持基于 Guidepup 的 Windows NVDA 自动化，以及仅手动的 JAWS 和其他由操作员主导的流程；合成执行属于单独的证据渠道，绝不声称通过。生成的手动计划仍与共享的真实屏幕阅读器测试运行手册关联，而特定用例的命令仅保留在生成的计划输出中，不会写回矩阵或覆盖率产物。

生成的手动用例、合成或真实执行证据、ACT 风格的结果推理、EARL 结果，以及后续的合格人工审查，是彼此不同的层。公共工作流通过文档化的 CLI 渲染代表性 fixture，并检查生成的六个产物，但不会为检查包提交黄金输出。

退出代码

• 0 表示测试框架成功完成，即使探测报告了发现项也如此。
• 非零退出代码表示测试框架出错，例如配置无效、探测失败、缺少 Node.js、未安装测试框架依赖、缺少浏览器支持，或目标被阻止。

verify-intent 额外提供两个设计意图代码，供使用方项目的 CI 区分：

退出代码	含义	典型响应
3	阻塞性预期解析为 failed	视为意图偏移；界面出现回归
4	阻塞性预期从未得到评估	视为覆盖率偏移；检查未运行

这两种情况分开处理，因为检查失败和检查未运行需要不同的响应。若复用一个代码，就可能把覆盖缺失误读为回归，或让问题悄然通过。

运行时依赖

该测试框架从技能本地软件包 scripts/runtime_a11y（package.json 及已提交的 package-lock.json）中解析 Node 依赖，并固定使用 [email protected]、@axe-core/[email protected]、@guidepup/[email protected]，还可通过 @guidepup/[email protected] 集成真实辅助技术（AT）。请按照测试框架前置条件中的说明，安装 Node 依赖以及单独管理的 NVDA 资源。随后，各项探测会从本地 node_modules 解析依赖；若缺少 node_modules，CLI 会立即退出并提示安装，不会探测或启动任何服务。

测试

该测试框架分两个层级进行测试。无浏览器的判定与纯辅助函数单元测试通过 node --test（仓库脚本 test:node）运行，覆盖 runner/_core.mjs 中的判定逻辑（例如 virtualSrNameRoleStatus 和 liveRegionStatus）。浏览器冒烟测试位于 tests/runtime_a11y/runner/probe-smoke/，会启动系统 Chrome，并针对内联测试样例运行真实捕获流程，以验证从 DOM 到判定的完整流程，包括无名称控件、实时区域触发、强制颜色计算样式以及 CDP 无障碍节点结构。这些测试的文件名为 *.smoke.mjs，因此默认的无浏览器测试会跳过它们。PR 验证会通过 CI 管理的入口 npm run ci:test:a11y:smoke 运行这些测试。若要在本地复现，需要系统 Chrome 和技能本地的 node_modules。

CI 回归门禁

使用现成可复制的工作流模板 references/ci/accessibility-coverage.workflow-template.yml 作为目标项目以文档为先的集成入口。只有在目标项目提交了 a11y-runtime.config.json，并且具备模板可调用的构建/服务路径后，才将模板复制到目标仓库的 GitHub Actions 工作流目录。一旦存在编写完成的 *.intent.yaml 记录，如果配置或当前运行结果缺失，模板就会采取失败关闭策略。

模板遵循 Docusaurus 工作流方案：配置系统 Chrome、安装 Node 24 以及 Python 和 uv、构建目标项目、在可配置的基础 URL 下提供服务，并使用固定在 vendored skill 根目录的 uv run --project 运行工具脚本入口。核心高置信度探测始终会阻断：probe-axe、probe-dom-hygiene、probe-broken-links、probe-console-errors、probe-target-size、probe-contrast 和 probe-reflow-resize。交互状态与播报探测（probe-keyboard-traversal、probe-widget-keyboard、probe-live-region、probe-aria-tree、probe-virtual-sr、probe-real-sr）是评估静态分析只能提供参考的类别时所采用的适当方法，其阻断策略遵循 按评估层级设置门禁严格程度 中定义的 A11Y_TIER 档位：basic 将它们报告为建议项，standard 逐步收紧（对 A11Y_RATCHET_SURFACES 中列出的界面进行阻断），comprehensive 则在所有界面上阻断。其余启发式探测，如 use-of-color、hover-focus、link-purpose、name-in-label 和 focus-*，会作为信息性结果呈现，以便指导后续工作，而不阻碍初期采用。默认情况下，真实屏幕阅读器探测仍为建议项，除非项目通过配置预期断言和受支持的 OS/AT 技术栈选择启用；如果平台或 AT 不可用，它会返回 candidate，而不会假装通过或失败。要对自适应渲染类别进行决定性覆盖，目标项目必须在其 a11y-runtime.config.json 中提交 zoom-200、reflow-320 和文本间距状态。

references/ci/probe-spec-parity.md 中的对照参考将每个运行时探测映射到最接近的现有 Docusaurus e2e 规范，并指出目前没有对应规范的缺口。

references/ci/act-rule-format.md 参考文档说明了工具的探测、生成的测试用例和 EARL 结果如何与 W3C ACT Rules Format（适用性、预期、通过/失败/不适用）保持一致，从而使结果能够与 ACT Rules 生态系统和符合性报告互操作。

设计意图验证

使用该技能的项目可以声明某个界面必须传达什么，并让 CI 检查已发布的内容是否仍然符合要求。此声明称为设计意图记录，由人工编写并提交到该项目的 design-intent/<surface-id>.intent.yaml。每条意图都说明该界面必须传达什么、原因以及面向的对象，并将每项声明绑定到一个命名检查。

记录字段约定见 references/design-intent/record-contract.md。编写或审查记录时请阅读该文档。本节介绍验证。

此技能提供一个步骤，用于将探测运行结果转化为针对该声明的判定。

调用方式

uv run --project <skill-root> <skill-root>/scripts/runtime_a11y/__main__.py verify-intent \
  --record design-intent/<surface-id>.intent.yaml \
  --results results.json

• --record 是编写完成的记录。除读取其中的声明外，绝不会将其用于其他用途，也不会对其进行重写。
• --results 是来自 run-all 的结果文档。
• --out 可覆盖输出路径；默认路径为记录旁边的 design-intent/.verification/<surface-id>.earl.json。

结果如何解析为结论

当结果行的表面、状态、发出该结果的探针和判定标准都与记录声明的内容匹配时，该结果行便与一项预期匹配。由于不同探针覆盖的判定标准可能重叠，因此联接时必须包含发出结果的探针。

情况	结论	模式
所有匹配的判定标准均通过	passed	automatic
任一匹配的判定标准未通过	failed	automatic
已收集证据，但不足以作出判定	cantTell	automatic
没有结果行与该预期匹配	untested	automatic
该预期使用 assert: custom	untested	manual

一项预期是针对一个或多个判定标准提出的一项主张，因此由最差的判定结果决定该预期的结论。对于本次运行未覆盖的预期，报告为 untested，而不是直接省略，这样缺失的检查会明确显示出来，不会悄然消失。

对于探针只能提供参考的判定标准，在正常运行中，其预期结论为 cantTell。这是预期行为：探针收集了证据，但未能确定该主张是否成立。

无论记录是否包含人工 override，custom 预期都会报告为 untested。适配器在生成的产物中只记录观测到的运行时结论。人工覆盖仍以记录本身为准，不会合并到生成的产物结论中。

根据约定，解读分为两层；现在生成的产物会在每项断言上同时包含这两层：

• observedOutcome 是生成的产物字段 outcome。覆盖值永远不会取代它。
• effectiveOutcome 按安全优先级规则确定结果。观测结论或人工结论中任一为 failed，结果就是 failed；人工 passed 仅能确定 untested、cantTell 或 inapplicable；否则保留观测结论。这是门禁采用的值。
• 仅当观测结论和记录中声明的覆盖结论均为 passed 或 failed 且二者不同时，overrideConflict 才为 true。通过覆盖值确定 untested、cantTell 或 inapplicable 预期属于文档说明的正常用法，不构成冲突。

出现明确冲突时，系统会按失败处理。对于每项冲突断言，verify-intent 会向 stderr 写入一行 Warning:，注明意图、预期、观测结论和覆盖结论；若冲突的预期会阻止通过，则返回设计意图偏差。

随附的 Python 验证器会拒绝重复的 YAML 键，验证完整的记录声明架构，并在写入产物之前，对日期、文件名与运行时配置的绑定、重复标识符、方法配对及探针充分性进行语义检查。本仓库的 PowerShell 验证器会独立执行相同的约定，用于验证源文件和生成的产物。

退出代码

• 0 — 已写入产物，且没有阻止通过的预期未通过。
• 1 — 记录或结果文档格式错误。不会写入任何内容。
• 2 — 无法读取记录或结果文档。
• 3 — 已写入产物，但有阻止通过的预期未通过。
• 4 — 已写入产物，但有阻止通过的预期从未经过评估。

退出代码 3 和 4 是强制执行信号。消费方项目的 CI 步骤会像处理任何其他命令一样，在遇到任一非零退出代码时使构建失败。产物仍会写入，以便运行结果可以发布。由哪些预期阻止通过，取决于记录中的决定，即每项预期的 blocking 标志。

图形和图表语义没有运行时探针。这些预期使用 assert: custom，并通过人工审核得出结论；关于自动化能判断和不能判断的边界，请参阅 Graphics ARIA 和 SVG-AAM 参考。

渲染供审查的记录

记录说明必须满足什么条件以及如何检查，但不包含实现或交付范围。审查者若想查看正文而非 YAML，可以渲染记录：

uv run --project <skill-root> <skill-root>/scripts/runtime_a11y/__main__.py project-intent \
  --record design-intent/<surface-id>.intent.yaml \
  --out handoff.md

输出是确定性的，只会渲染记录中已有的内容，不会添加分析或验证结果。按需生成，而不是提交渲染结果，以免其与所描述的记录不一致。如果不使用 --out，Markdown 将输出到 stdout。

使用说明

• 将此技能作为规划和审查工作流的默认无障碍入口。
• 通过此技能获取框架和阶段指导，而不是在 Agent 或指令中重复其内部参考路径。
• 需要获取无障碍扫描的标准化结果时，请使用扫描器 CLI。