a11y-audit

无障碍审计

已认证目标

对于明确授权的已认证扫描，请在执行前阅读 references/authenticated-scans.md。要求提供配对的存储状态，以及针对每个目标的 URL／就绪状态断言。不得仅凭持有状态文件推断已获准访问。认证失败时停止；不得将登录页面视为成功目标。发现过程仍须未经认证。不得将状态数据纳入版本控制或构件。

架构

此技能作为单层运行。它读取项目环境，运行自动化无障碍工具，将发现结果映射到合规标准，并以可配置格式生成输出。无需依赖外部技能。

将项目专属审计状态存储在目标工作区中，而非已安装的技能目录中。默认路径： 工作区根目录下的 .a11y-audit/PROJECT_CONTEXT.md。该文件存在时，使用其中的项目专属配置：输出模式、其他合规标准、问题跟踪器设置、路由列表、配色方案，以及指向现有文档的交叉引用。若文件不存在，则仅采用 WCAG 2.1 AA 标准，使用 markdown 作为输出模式，其余均采用通用默认值。

将 references/project-context-template.md 作为该文件的规范架构，其中包含最简示例和 markdown+issues 示例。

适用时，优先使用随附的辅助工具，而非临时生成：

• scripts/bootstrap-context.js 根据简单输入，在工作区本地创建 .a11y-audit/PROJECT_CONTEXT.md。
• scripts/scan.js 运行可复用的基于 axe 的扫描，并记录可选的 Lighthouse 执行意图。使用 --summary 可缩减输出大小（保留完整的违规详情，并从通过／不适用项中移除节点数据）。
• scripts/report.js 根据 scan.js 的输出生成 Markdown 报告和 JSON 数据文件。以确定性方式处理 WCAG 证据矩阵、违规聚合和颜色对比度详情提取。
• scripts/discover.js 识别大型网站上的模板组，并选择具有代表性的页面进行扫描。优先读取 sitemap.xml，否则回退到 HTML 导航爬取。输出包含模板组和可直接用于 scan.js 的 URL 列表的扫描计划。默认情况下，发现仅限同源；只有在用户批准站点地图声明的跨源目标后，才使用 --allow-cross-origin-sitemaps。 对于扁平或不规则的路由结构，请使用经过审核的路由分组映射，而不要依赖路径深度。编写或审核该映射时，请阅读 references/route-grouping.md。
• scripts/select-changed-surfaces.js 将明确的、项目自有的源前缀映射到精确的发现组。只有当每个变更路径都能安全映射时，才会缩小现有计划。Schema-v2 映射还可包含变更页面，前提是经过审核的源到路由转换能够解析为已发现的同源 URL。否则，它会保留完整的代表性样本，并记录回退原因。配置或审核此路径时，请阅读 references/changed-surfaces.md。
• scripts/run-audit.js 是面向供应商中立的流程适配器，供外部 Agent 系统和 CI runner 使用；这些系统只需发送一个 JSON 请求，即可组合发现、选择、扫描和报告生成。配置此边界时，请阅读 references/interoperability.md。若要选择加入终端 JSON 和退出状态试点，请先阅读 references/cli-contract.md，再选择 --contract posix-json-v1。

网络和浏览器策略

在扫描远程目标、使用跨源站点地图内容或配置沙盒覆盖项之前，请阅读 references/network-policy.md。保持默认的 Chromium 沙盒启用；任何额外目标源都必须明确批准。

依赖项

需要 Node.js 22.12.0 或更高版本。扫描前运行 node --version； 如果运行时版本不受支持，请先升级，再安装依赖项。托管套件固定使用 Puppeteer 25.16.0。有关浏览器缓存、跳过下载和 v3 迁移说明，请阅读 references/runtime-compatibility.md。

scan.js 需要 axe-core 和 puppeteer。它按以下顺序查找这两个依赖：

1. 技能本地 deps/ 目录（与 scripts/ 同级）
2. 目标项目 node_modules/（以及常见的工作区子目录）
3. 全局 npm 模块

如果在任何位置都找不到其中一个包，scan.js 会自动将完整的扫描器依赖集 一次性安装到技能本地 deps/ 目录。如果已存在的技能本地 Puppeteer 版本与固定版本不同，也会触发此次安装，以替换旧的托管浏览器包。 默认版本通过 npm ci 使用已提交的锁定文件；如果有意使用 --axe-version 覆盖，则会安装指定的两个版本，但不会重写已提交的清单。 安装会进行三次有间隔的尝试，并跳过 npm audit 和 funding 网络请求。 deps/node_modules/ 目录已加入 git 忽略。

同一锁定文件也为可复用的 Action 固定了 http-server。设置 serve-path 时，Action 会先完成 npm ci，再启动本地服务器并开始计算就绪 时间；不会将访问注册表所花的时间误报为服务器启动失败。

每次尝试的默认超时时间为 120000 毫秒。在运行器较慢时，可通过 --install-timeout-ms <milliseconds> 或 A11Y_AUDIT_INSTALL_TIMEOUT_MS 延长。 超时诊断信息会指出依赖集、已用时间、限制和设置项；npm 非零退出仍会单独报告。

由于 scan.js 可能自动安装缺失的依赖项，或替换过时的技能本地 Puppeteer， 如果尚未获得对该安装范围的授权，请先征求同意，再调用 scan.js。浏览器下载 也应纳入该范围。

捆绑的扫描器仅支持 Puppeteer。请将 --browser 视为固定选项，而非由用户控制的包安装器。

版本固定与差异完整性。 不同版本的 axe-core 规则集和浏览器行为会有所变化， 因此 scan.js 会将 axe-core 和 Puppeteer 的自动安装版本固定为经过验证的版本 （--axe-version <x.y.z|latest> 可用于有意覆盖 axe-core 版本）。每次 扫描都会在输出 JSON 中记录解析出的 axe_version 和 browser_version； report.js 会将 axe_version 写入审计 JSON；“与上次审计的差异”部分会标记 两个审计使用不同 axe-core 版本的对比。不得将版本间规则集的变化说成网站的回归或修复。 如果依赖查找时使用了项目解析到的 axe-core，也会以相同方式记录其版本。 在项目级别只提供一个依赖项，不会阻止安装缺失的包：完整的固定版本依赖集会安装在 技能本地，并一起使用。

平台专属参考资料

• 如果在 Claude Code 中运行，请阅读 references/claude-code.md，了解 .claude/launch.json 的处理方式和 Preview 工具的用法。
• 如果在 Codex 中运行，请阅读 references/codex.md，了解工作区本地状态的处理方式和执行假设。
• references/output-contract.md 和 references/output-schema.json 已编码在 scripts/report.js 中。只有在修改报告脚本时才阅读它们。
• 仅当 output_mode 为 markdown+issues 时，才阅读 references/issue-trackers.md。
• 如果用户希望在 CI 中将定期审计付诸实施，请从 assets/ci/github-actions/accessibility-audit.yml 开始。上游 Action 会作为真实使用方进行测试，并通过 actionlint 和 zizmor 检查。发现流程优先使用站点地图；如果必须从 discover-url 开始爬取已部署的构建，请在 Action 中设置 discover-no-sitemap: true，然后调整输入，不要将其实现复制到目标仓库中。若要缩小拉取请求的范围，请复制路由组和所有权映射示例，提供 changed-base 和 changed-head，并保留发现和选择两类产物。
• 如果需要安全地审查并去重后再创建实际工单，请优先使用 scripts/plan-issues.js。

此技能不会修改源代码。 它是审计工具，而非修复工具。报告中会列出发现的问题及修复指导；用户决定采取哪些措施。

输出模式

此技能支持三种输出模式，通过 .a11y-audit/PROJECT_CONTEXT.md 中的 output_mode 字段进行配置：

模式	输出	使用场景
markdown	仅 Markdown 报告	人工审查、文档
markdown+json	Markdown 报告 + JSON 数据文件	CI 集成、仪表板、趋势跟踪
markdown+issues	Markdown 报告 + 工单系统工单	主动修复工作流

首次运行时，如果 .a11y-audit/PROJECT_CONTEXT.md 中未设置 output_mode，请询问用户偏好的模式，并在该文件中追加 ## Output Configuration 章节以保存其选择。如果上下文文件不存在，请按照 references/project-context-template.md 在默认路径创建该文件。如果只需生成简单文件，首次创建上下文时优先使用 scripts/bootstrap-context.js。

markdown+json 模式会在报告旁写入一个配套文件：audit-YYYY-MM-DD.json，其中包含原始 axe-core 结果、Lighthouse 评分以及结构化的证据矩阵。该文件为机器可读，可供 CI 流水线、仪表板或趋势跟踪工具使用。

markdown+issues 模式需要在上下文文件中进行额外配置（参见第 6 阶段）。

回归门禁

当验收标准要求当前不存在严重或重大标准问题时，使用 --fail-on major。此模式会评估完整的当前扫描结果，因此已接受的基线无法屏蔽现有的重大问题。中等、轻微以及明确仅属最佳实践的问题仍会显示，但不会阻止通过。最佳实践标签不会降低同时带有 WCAG、EN 301 549、Section 508 或无法识别标签的规则级别。只有明确带有 best-practice 标签，且除此之外仅带有 axe cat.* 标签，才属于仅限最佳实践的问题。

影响级别未知的违规，以及影响级别为严重、重大或未知的 axe incomplete 候选项，会导致结果无法确定且返回非零值。中等和轻微的 incomplete 候选项仍仅作提示。自动化扫描通过仅适用于已扫描的范围，不能证明完全符合标准。

在重大模式下，若请求的 URL 返回 HTTP 错误或非 HTML 响应，则视为未满足必需的覆盖范围。扫描器会记录页面错误和无法确定的门禁结果，而不会把错误响应内容当作请求的页面进行审计。现有模式仍保留其既定的响应行为。

在证据矩阵中，已确认的违规优先显示为 Fail；axe incomplete 候选项优先于自动化通过结果，显示为 Needs review。对于存在尚未解决的 incomplete 证据的标准，不要显示无条件的通过结果。

对于已有无障碍问题待解决的成熟网站，优先采用已接受的基线，而不是非此即彼的门禁：

# Create a baseline only after reviewing the current findings.
node a11y-audit/scripts/scan.js \
  --urls http://127.0.0.1:3000/ \
  --write-baseline .a11y-audit/baseline.json

# Fail only when the current scan introduces a finding outside it.
node a11y-audit/scripts/scan.js \
  --urls http://127.0.0.1:3000/ \
  --baseline .a11y-audit/baseline.json \
  --fail-on new

扫描器根据 axe 规则、规范化路由和规范化 axe 目标，为每条发现生成指纹。基线会记录 axe-core 版本；版本不匹配时会停止比较，除非有意覆盖。切勿在 CI 中自动刷新基线。应将基线变更作为明确的接受决定进行审核并提交。

---

流程

无障碍审计分为六个阶段。每个阶段都会生成供下一阶段使用的数据。阶段 1-4 始终运行。阶段 5 根据配置的输出模式生成结果。阶段 6 仅在 markdown+issues 模式下运行，且需要用户明确确认。

用户可以请求部分运行。常见模式：

• “快速扫描”：仅运行阶段 1-2，并在对话中汇总结果
• “完整审计”：运行阶段 1-5，按配置的模式输出
• “审计并创建问题”：运行阶段 1-6，生成报告并创建跟踪工单

阶段 1 -- 环境发现

目的： 扫描前了解项目。

1. 如果 .a11y-audit/PROJECT_CONTEXT.md 存在，则读取它（标准、路由、 输出模式、标签）。如果不存在，则通过 scripts/bootstrap-context.js 创建，或使用 references/project-context-template.md 创建。
2. 读取 package.json，了解技术栈、现有的 a11y 工具，以及 可用的浏览器自动化工具（puppeteer / playwright）。
3. 根据路由器配置或 HTML 文件 glob，生成可扫描的 URL 列表。 对于页面较多（>15 条路由）的网站，优先使用 scripts/discover.js 将页面归类为模板组并选出代表页面。 与用户审核扫描计划后，再继续阶段 2。
4. 确认开发服务器可以访问。检查 .claude/launch.json 和 平台特定的参考资料，寻找启动提示。如果应用启动后的 URL 与预期不同， 则切换到实际 URL，记录不一致情况，并更新上下文文件。
5. 确认 Node.js 版本为 22.12.0 或更高，并确认是否有权限安装缺失的 依赖、替换过期的托管 Puppeteer，以及下载浏览器。

输出： 在继续之前向用户报告结构化摘要。

阶段 2 -- 自动化扫描

目的： 对运行中的页面执行自动化无障碍检查。

前提条件： 正在运行的开发服务器（或用户提供的生产环境 URL）。

axe-core 扫描

在编写临时扫描脚本之前，优先使用随附的 scripts/scan.js。只有当工作区需要的行为尚未得到随附脚本支持时，才使用临时脚本。

可复用的扫描器应：

1. 导入 puppeteer 和 axe-core
2. 启动无头浏览器
3. 对每个目标 URL： a. 导航到页面 b. 等待网络空闲（waitUntil: 'networkidle0'） c. 注入 axe-core：从 node_modules/axe-core/axe.min.js 读取 axe-core 源文件，并通过 page.evaluate() 注入 d. 运行审计：page.evaluate(() => axe.run()) e. 收集结果 JSON
4. 关闭浏览器
5. 将原始结果写入 JSON

调用示例：

node a11y-audit/scripts/scan.js \
  --root . \
  --discover /tmp/a11y-discover.json \
  --output /tmp/a11y-scan.json \
  --summary

根据项目调整。 如果依赖位于前端子目录中，请将 --root 指向工作区根目录；随附脚本已检查常见的前端路径。如果仍然失败，请改用临时脚本，或直接在前端目录中运行。

常见错误： 在 ES 模块项目中不要使用 require()。检查 package.json 中是否有 "type": "module"。如果有，请使用 import 语法，并在任何临时脚本中采用 __dirname 解决方法。如果没有，使用 require() 即可。

Playwright 替代方案： 随附扫描器仅接受 Puppeteer。如果单独限定范围的审计使用现有的 Playwright 安装，请编写项目本地适配器，并说明该方案不属于经过验证的随附扫描器路径。请保持已安装的技能及其固定清单不变。

Lighthouse 扫描

针对每个目标 URL 运行 Lighthouse CLI：

npx lighthouse <url> \
  --output=json \
  --output-path=stdout \
  --only-categories=accessibility \
  --chrome-flags="--headless --no-sandbox" \
  --quiet

解析 JSON 输出。提取：

• categories.accessibility.score（范围为 0-1，乘以 100）
• score !== 1 的 audits（失败或部分通过的审计）
• 每项审计的 description 和 details.items

如果 Lighthouse 不可用或运行失败（在 CI 环境中很常见），请跳过并在报告中注明这一缺口。在执行摘要和方法说明中，明确说明跳过 Lighthouse 的原因是 CLI 缺失、Chrome 启动失败，还是发生了其他运行时错误。仅使用 axe-core 结果也足以完成有效审计。

范围控制

• 默认：扫描 Phase 1 中发现的路由
• 如果存在 discover.js 扫描计划，请使用 --discover 传入该计划。报告的方法说明将记录抽样策略。
• 如果路由超过 10 个且没有可用的 discover 计划，请询问用户要扫描哪些路由，或是否扫描全部路由
• 用户可以提供特定 URL 列表，以覆盖自动发现结果
• 对于 SPA：通过路由器导航，而不是重新加载页面（某些路由可能无法作为直接 URL 使用）

结果结构

对于每个页面，收集：

• url：扫描的 URL
• violations：axe 违规项数组，每项包含 id、impact（critical/serious/moderate/minor）、description、help、helpUrl、tags（WCAG 标准）、nodes（包含选择器的受影响元素）
• passes：通过的规则数量
• incomplete：无法完整评估的规则
• lighthouseScore：0-100（如果可用）
• lighthouseAudits：失败的审计详情（如果可用）

阶段 3——标准证据映射

目的： 将自动化检查结果映射到所配置标准的成功准则，以及任何项目特定标准。

scripts/report.js 会以确定的方式处理证据矩阵。准则矩阵是 references/standards/ 中的数据文件，通过 --standard <id> 选择：

• wcag21-aa（默认）：全部 50 项 WCAG 2.1 A 级和 AA 级准则。 ADA Title II 最终规则和 EN 301 549 V3.2.1 均引用了该标准。
• wcag22-aa：全部 55 项 WCAG 2.2 A 级和 AA 级准则（移除了 4.1.1 Parsing；新增了 2.4.11、2.5.7、2.5.8、3.2.6、3.3.7、3.3.8）。
• en301549：EN 301 549 V3.2.1 第 9 条（Web），即《欧洲无障碍法案》下的协调标准；在一对一映射的 WCAG 2.1 准则旁显示条款编号。

将 .a11y-audit/PROJECT_CONTEXT.md 中的 standards 值映射到对应的 id（例如，WCAG 2.2 AA → wcag22-aa；EN 301 549 为首要标准时 → en301549），并通过 --standard 传入。该脚本会将 axe 标签映射到成功准则，并在 Markdown 和 JSON 输出中生成矩阵；JSON 会记录所用标准。你无需手动构建矩阵。

如果 .a11y-audit/PROJECT_CONTEXT.md 指定了这些标准之外的其他标准（例如 CAN-ASC-6.2），请构建辅助映射。如果该标准映射到 WCAG 准则，请交叉引用自动化检查结果。对于超出 WCAG 范围的要求（公平性、组织流程、透明度），请将其列为人工审查项，并引用项目现有的符合性文档。

阶段 4——人工检查指南

目的： 针对自动化无法验证的内容生成重点检查清单，并根据自动化检查结果确定优先级。

对于阶段 3 矩阵中标记为“人工”的每项 WCAG 准则，都生成一个测试项。按测试方法分类：键盘导航、屏幕阅读器、视觉检查、认知和计时／动态效果。

动态确定优先级： 不要生成静态检查清单。根据阶段 2 的结果聚焦人工检查：

• 如果 axe 发现颜色对比度违规，优先检查视觉相关项（SC 1.4.1、1.4.11、1.4.10、1.4.12、1.4.13）
• 如果 axe 发现 ARIA 或地标违规，优先检查屏幕阅读器相关项（SC 1.3.1、4.1.3、3.3.1、3.3.2）
• 如果 axe 发现标题或结构违规，优先检查键盘导航相关项（SC 2.4.3、2.4.7、2.1.1）
• 如果未发现与表单相关的违规，将表单测试（SC 3.3.3、3.3.4）的优先级调低，并注明自动化检查已通过
• 始终包含计时相关项（SC 2.2.1、2.2.2、2.3.1），因为这些内容完全无法自动化检查

每个检查清单项都应注明：WCAG 准则、测试内容、测试方法，以及重点检查的页面（优先检查发现了自动化问题的页面）。

如果 .a11y-audit/PROJECT_CONTEXT.md 引用了现有测试指南，请交叉链接到该指南，而不是重复其中的操作步骤。

阶段 5 —— 输出生成

目的： 根据配置的输出模式生成输出。

运行 scripts/report.js，根据阶段 2 的扫描输出生成 Markdown 报告和 JSON 数据文件：

node a11y-audit/scripts/report.js \
  --input /tmp/a11y-scan.json \
  --output-dir docs/accessibility/audits \
  --project-name "Project Name" \
  --runtime-url http://127.0.0.1:3000 \
  --expected-url http://localhost:3000 \
  --discover /tmp/a11y-discover.json

如果使用了 discover.js 扫描计划，请传入 --discover。这会在报告方法论中添加“抽样策略”小节，记录模板组和覆盖率。

传入 --previous <prior-audit.json>，生成“与上次审计的差异”部分，展示已修复规则、新增规则、实例数量变化和净进展。

该脚本会生成 audit-YYYY-MM-DD.md 和 audit-YYYY-MM-DD.json，并遵循 references/output-contract.md 和 references/output-schema.json 中的约定。除非要修改报告脚本，否则无需阅读这些参考文件。

运行 report.js 后，请检查其输出，并使用阶段 4 的指导填写手动测试建议部分（report.js 会为此留出占位内容，因为这需要结合具体的问题发现模式进行判断）。

.a11y-audit/PROJECT_CONTEXT.md 可覆盖输出路径。

如果用户需要定期运行或按需触发的 CI 作业，请将 assets/ci/github-actions/accessibility-audit.yml 调整为适用于目标工作区的配置，而不是从头编写工作流。 将基线更新放在 CI 之外，并保留 Action 的发现和扫描产物，以便失败的门禁仍可供审查。使用变更范围选择时，也要保留其选择产物。不要根据框架名称推断归属：请使用 references/changed-surfaces.md 和经过审查的映射。

阶段 6 —— 创建问题（有条件）

目的： 为发现的问题创建问题跟踪器工单。仅当输出模式为 markdown+issues 时运行。

此阶段需要用户明确确认。 创建任何工单之前，请告知用户将创建的工单数量和优先级，并征求批准。

阅读 references/issue-trackers.md，了解跟踪器配置、去重、优先级映射和工单结构。使用 .a11y-audit/PROJECT_CONTEXT.md 中的跟踪器设置。

---

验证

完成审计后，请检查以下质量项：

1. axe 结果有效： 将违规数量与在同一页面上手动运行 axe DevTools 浏览器扩展所得的结果进行比较。数量应在容差范围内一致（axe 版本可能略有不同）。

2. Lighthouse 评分一致： 实际运行 Lighthouse 时，将结果与手动运行的 Chrome DevTools Lighthouse 进行比较。分数应相差不超过 5 分。

3. 标准矩阵完整： 配置的证据矩阵包含预期的准则数量：wcag21-aa 为 50 项，wcag22-aa 为 55 项，或 en301549 为按条款映射的 50 项。不得缺少任何准则。

   将矩阵视为面向证据的状态报告。不要将其描述为完全符合标准的证明，因为即使自动化运行效果良好，许多 WCAG 准则仍需手动检查。

4. 报告结构： 包含所有必需部分。表格在 Markdown 查看器中正确呈现。

5. JSON 有效性（markdown+json 模式）：JSON 文件可无错误解析。违规数量与 Markdown 报告一致。

6. 问题去重（markdown+issues 模式）：连续运行两次该技能。第二次运行不应创建任何重复工单。

7. 输出模式持久化： 首次运行后，确认输出模式已保存到 .a11y-audit/PROJECT_CONTEXT.md，并会在下次运行时自动使用。

8. 运行时 URL 对照： 如果应用启动时使用的本地 URL 与预期不同，请确认报告记录了该差异，且上下文文件中的 base_url 反映了实际可用的地址。

---

此 Skill 不会做什么

• 视觉回归测试：不会比较不同运行之间的屏幕截图。请使用 Percy、Chromatic 或 BackstopJS。
• PDF 无障碍审计：不会审计 PDF 文档的标签结构、阅读顺序或替代文本。
• 真实设备/辅助技术测试：仅在无头 Chromium 中运行。无法在真实 iOS/Android 设备上或使用真实屏幕阅读器进行测试。第 4 阶段会为此生成手动检查清单。
• 代码修复：会报告发现的问题，但不会修改源代码。
• VPAT 生成：不会生成《自愿产品无障碍模板》（特定法律格式）。
• 托管式持续监控：不提供定时扫描服务或仪表板。支持 CI 门禁：仓库附带一个复合 GitHub Action（.github/actions/scan），可在推送/PR 时运行扫描器，并可针对所有违规项或仅针对不在已接受基线中的发现项进行失败处理；此外还提供工作流模板 assets/ci/github-actions/accessibility-audit.yml。上游仓库会端到端运行该复合 Action，并执行工作流语义和安全检查。markdown+json 输出模式可提供结构化数据，以便构建更多集成。
• 第三方审计：只审计项目自身的前端，不审计嵌入的第三方服务。