ultra11y

ultra11y — 审核 WCAG 2.2 AA 并编写无障碍标记

在无障碍方面，自动化工具只能看到问题的一部分。ultra11y 通过分工协作来解决这一问题：确定性、无需安装的引擎（node scripts/ultra11y.mjs <command> — 无需 npm install，也无需密钥；JSX/TSX 解析器已嵌入软件包）负责机械性工作——检测可由机器检查的不符合项，并将每一项关联到正确的 WCAG 成功准则；而活跃的编码 Agent 则静态地自行裁定判断性准则——替代文本的相关性、上下文中的链接目的、阅读顺序——依据引擎采集的证据（verify --manual），并由 verify/check 对每项判定进行门控。只有真正需要渲染后 DOM 的准则（计算后的对比度、可见焦点、缩放/重排、悬停时显示的内容）才交由 scan 层处理（在真实浏览器中运行 axe-core）；人工审核至多是可选的监督。门控会阻止任何臆造的不符合项通过，且绝不会默默将任何内容标记为“符合”。

不要混淆规则和准则。 软件包附带 93 项静态检查，WCAG AA 有 55 项成功准则，RGAA 有 106 项准则。多项规则可能为一项准则提供依据，一项规则可能关联多个规范包中的准则，而大多数准则在扫描或裁定前仍处于未定状态。诚实反映每次运行覆盖情况的唯一方式，是网格中实时显示的来源统计（moteur + scan + agent，以及任何列出的未决余项），而不是“48 项由 Agent 判定”这类固定承诺。因此，GitHub 摘要显示的是 decided/total，而非以少量已判定项为分母计算的百分比。

WCAG 2.2 AA 是全球通用的核心标准。 各国标准——法国的 RGAA、美国的 Section 508、欧盟的 EN 301 549——是可插拔的标准规范包，可将各自的准则映射到 WCAG。添加 --standard rgaa，即可重新定义每条命令和每项输出——包括 audit、发现的问题及其他所有内容；也可通过 --pack ./pack.json（或 .ultra11yrc.json）在运行时接入外部规范包，无需重新构建；或者贡献你所在国家的规范（参见 references/standards.md）。规范包（及其具体的实施指南——RGAA SocialGouv/etalab 的正反示例模式）可以由 AI 摄取，并通过 pack check 进行门控，确保虚构的映射无法通过——参见 references/packs.md 和 references/guidance.md。

大部分工作由你完成。 在 WCAG 2.2 AA 的 55 项成功准则中，引擎可直接判定 3 项；14 项需要渲染后的页面（scan），另有 38 项属于需要由 Agent 裁定的判断项。因此，引擎运行结果干净只是起点，绝非最终结论——而 references/adjudication.md 才是你实际开展工作的页面。

核心规则：

1. 绝不虚构不符合项：每个 NC 都引用一个真实且可解析的元素（check 会验证它）。
2. 优先使用原生 HTML，最后才用 ARIA；绝不重复隐式语义。
3. 也绝不虚构符合项：C 的引用方式与 NC 完全相同——在 citations[] 中列出其通过审核的已采集证据，每个锚点都必须可解析，且必须取自 实际展示该准则时所依据的证据。如果展示某项准则时没有任何证据，就绝不能将其 标记为 C；它仍为 manual。如果其读取不完整（evidenceComplete: false）， 也不能标记为 C：对于展示了部分内容的准则，仍可根据已看到的内容判定其不符合， 但绝不能对未看到的内容判定其符合。而且，经裁定的 C 绝不会与引擎判定的 C 合并：报告会将其单独列出，并将其排除在自动通过率之外。 3b. 展示给你的内容就是完整的总体，每种事物只展示一次。 证据按内容类别各提供 一个代表项，并附带 occurrences、alsoAt 中的其他锚点，以及该内容出现的 pages——在 38 个已捕获页面上的 887 个链接，实际上只有 97 个不同的 （文本，href）组合。对代表项作出的裁定适用于所有这些内容，因此可以作出诚实的 C；而且，只要引用的是该准则所涵盖类别中的任一出现位置，就会被接受，所以请 引用你实际打开的那个位置。
4. 明确标记未决项，绝不默认符合：AI Agent 自行裁定每项判断类准则 （通过 verify --manual，并受门控）；渲染类准则交由 scan 处理——现在， 如果某项准则涵盖的每条规则都已在范围内的每个页面上运行且未发现问题，scan 就会判定为 C（decidedBy: "scan"）；即使只有一个页面的信号不完整，也会 保持未决。任何尚未证明的准则仍为“待手动评估”——没有记录且有理据的裁定，就 不得设置状态。要将其设为门控而非寄望于此，check --in <audit.json> --require-decided 会在仍有待评估项时失败；--allow-undecided <file> 则接收 你确实无法裁定的准则及各自的原因（明确列出准则，绝不使用阈值）。--require-decided=pages 会要求每个页面各自的网格都达到同一标准：某条路由上失败的准则会在本次运行中 得到裁定，但对于从未触发该准则的路由，仍可能没有任何裁定；而这正是按页面交付 内容时实际采用的评判方式。 生成的工作清单具有权威性。 其中可能有意包含运行全局状态已为 NC 的准则， 因为该失败并未在其他页面上裁定该准则。此类条目并非冗余：请为其提供一个有依据的 裁定（或明确说明 manual 的原因）；绝不要因为全局统计看起来已有结论就将其留空。
5. 查询准则；绝不凭记忆。 criteria [--standard <pack>] <id>——或通过 MCP 调用 ultra11y_criteria——会返回准则的原文、其编号测试，以及这些测试所引用 的术语表定义。RGAA 8.3 并不是“页面需要一个 lang 属性”；它是测试 8.3.1， 包含两个可选条件，术语表则决定这些术语的含义。审计人员在阅读后引用 8.3.1， 才有依据；凭记忆引用，则只是披着参考文献外衣的猜测。根据某个国家标准进行审计 前，请运行计划（ultra11y_method）：它会告诉你，为了达到 C，仍需裁定多少项 准则——对于 RGAA，106 项中有 104 项。参见 references/mcp.md。
6. 最终渲染出的语义 HTML 必须正确。 引擎只能看到源码；组件库（DSFR/MUI…） 或 .vue/.svelte/.astro SFC 会隐藏实际标记，因此源码审计通过并不能证明 页面正确。请验证生成的语义 HTML——安装零接触式 capture 采集器 （render --setup），这样测试所渲染的每个组件都会序列化到 .ultra11y/captures 并接受审计，同时通过 audit --require-captures 对盲区进行门控。参见 references/automation.md / rendered.md。
7. 语言：务必传入 --lang，并使其与您和用户对话所用的语言一致；如果不确定， 请询问用户。未指定该标志时，CLI 会自动检测（仓库中的 <html lang> → 当前标准的 默认区域设置 → 英语）——这是脚本/CI 的回退机制，不能替代你自行传入 --lang。
8. 技术标记始终使用英文，即使法语正文也是如此。 在你撰写的任何法语交付内容中 （报告说明、PRD、跟踪工单、判断结果），属性/元素/角色名称及其值都属于代码， 而非正文——绝不要翻译它们：aria-live 仍为 aria-live（绝不能写成“实时区域”）， tabindex、alt、role="alert" 和地标角色名称也一样。引擎自身的法语目录遵循 这一规则；请与其保持一致。规范标准中的术语（例如 RGAA 的“跳过链接”）则保留其 官方法语表述。

参考资料库

先了解领域知识，再看工具。根据当前问题阅读相应资料。

无障碍知识
references/adjudication.md	如何判定引擎交给你的 52 项标准——判定规则、可合理判为 NA 的情况以及相关问题
references/naming.md	可访问名称的计算、2.5.3 名称中的标签、视觉隐藏 CSS、图像／SVG／图形的命名
references/widgets.md	ARIA APG 复合模式、键盘约定、焦点管理、SPA 路由变更、实时区域
references/forms-and-errors.md	标签和说明、autocomplete 令牌列表、错误识别／建议／预防、重复输入、无障碍身份验证
references/structure.md	标题、地标、列表和 dl、简单表格和复杂表格、有意义的顺序
references/media-and-motion.md	字幕／音频描述／文字记录、指针手势、目标尺寸、方向、重排、减少动态效果
references/forbidden-patterns.md	15 种反模式：错误做法 → 原因 → 原生修复方案 → 对应标准
references/focus-and-logic.md	你负责的焦点／键盘标准，以及如何进行推理
references/criteria.md	55 项标准：级别、自动化分类、引擎规则、套件映射（自动生成）
references/rgaa-automation.md	RGAA 4.1.2：生成的 106 项标准／258 项测试矩阵、决定性规则、候选信号和静默策略
references/act.md	引擎经测量可发现的问题，以及明确无法发现的问题（自动生成）
运行工具
---	---
references/runbook.md	可靠运行指南：唯一的操作方案、要使用的传输方式及其原因，以及一次通过需要付出的成本。在支付裁决费用前请先阅读
references/claude-code-report.md	Claude Code 的详细发布流程：渲染后的范围、直接裁决、对抗性验证、Markdown + HTML + 每页证据
references/audit.md	端到端审计循环，以及规范页面示例
references/judgment.md	裁决与反驳工作清单、判定术语、失败即关闭的汇总机制
references/verify.md	check/verify 门禁
references/false-positives.md	哪些发现仍可能有误，以及如何反驳
references/rendered.md · references/automation.md	审计生成的 HTML、捕获内容、钩子和 CI
references/harnesses.md	运行环境：Claude Code、Codex CLI、OpenCode，以及 AGENTS.md 回退方案
references/orchestrators.md	从工作流引擎／非 GitHub CI 驱动引擎：固定版本、六步管线、退出代码，以及适用于任何跟踪系统的 JSON 格式工单集
references/ci.md	--format sarif|github：PR 内联批注、代码扫描、作业摘要
references/pages.md	页面快照 + 每页标准网格（pages），以及相关诚信规则
references/e2e.md	render --e2e：在运行 Playwright/Cypress 时审计页面
references/devtools.md	dev：构建时的实时叠加层，以及逐页仪表板
references/extension.md	浏览器扩展：通过侧边栏审计当前查看的页面
references/dynamic.md	scan 层级：运行时、探测器、经过身份验证的页面
references/scale.md	将审计重点放在大型代码库上
references/fix.md · references/correction.md	按优先级应用修复，避免回归
references/prd.md	将审计器区块作为待办事项列表（Markdown）
references/tickets.md	将待办事项列表登记为工单：GitHub、GitLab、Jira，以及工单粒度
references/standards.md · references/packs.md · references/guidance.md	国家标准、编写规则包、实施指南
references/mcp.md	将标准作为规则引擎：查询标准，而非依赖记忆——包括编号测试、定义的术语、修复方案和工作计划。可用作 MCP 工具和 std:// 资源，也可通过 CLI 获取相同数据
references/methodology.md	状态、通过率、严重级别、报告格式
references/cross-file.md	--graph：导入和跨文件规则
references/orchestration.md	将裁决阶段分派给多个子 Agent

按情况选择

• “在 Claude Code 中生成详细审计报告” → 将当前 Claude 会话用作审计员，明确渲染和判定标准，质疑其结论，然后发布带日期的 Markdown 报告、可打印 HTML 和附有证据的逐页档案。请阅读 references/claude-code-report.md。这是交互式发布配置；请完成全部交付物。精简摘要对应下方的 CI 分支。
• “审计／合规报告” → node scripts/ultra11y.mjs audit … --json，然后运行 report（综合表格 + 每项 NC 标准对应一个审计员符合性区块——与 prd 和 tickets 使用的区块相同），再运行 check；请阅读 references/audit.md。
• “由库（DSFR、MUI……）渲染的代码，或 .vue/.svelte/.astro 单文件组件／避免假阴性” → 审计生成的 HTML，而不是源模板。最简单的方法是安装零接触式 capture 采集器（render --setup），让测试将每个已渲染组件序列化到 .ultra11y/captures（自动摄取，发现的问题归属到源组件；render --coverage 和 audit --require-captures 用于跟踪盲区）。或者运行 render（构建→审计配方或 SSR 快照 --scaffold），然后对输出运行 audit，并运行 scan 检查计算后的渲染结果。单文件组件源代码中的发现会标记为 preliminary（带有 scope.sourceTemplate 注意事项）；请阅读 references/rendered.md。
• “某个组件上的发现似乎有误／是假阳性” → 引擎会自动抑制大多数组件假阳性（插槽／属性注入的名称、组件子项、动态绑定、条件标题），并将单文件组件／库源代码中的发现标记为 preliminary；使用 verify --apply 确认或驳斥其余发现；请阅读 references/false-positives.md。
• “大型仓库／智能审计” → 聚焦：--changed（git diff）、模板优先级排序、去重、--max-files；请阅读 references/scale.md。
• “跨文件分析（树 + 依赖项）、将 JSX/TSX 作为真正的 AST 处理” → audit --graph 会解析导入并应用跨文件规则（仅图标组件在未提供名称时被使用、锚点目标位于其他文件中……），无需浏览器；请阅读 references/cross-file.md。
• “生成修复 Markdown／PRD” → prd（呈现 report 的 NC 部分所用的同一个审计员符合性区块——使用当前标准的词汇，包含主题／标准／测试／WCAG+级别／发现／预期结果／验证——作为待办事项列表）； --split criterion，使用 --format doc 生成产品需求文档，使用 --format remediation 生成旧版开发待办列表。它只会写入 Markdown；请阅读 references/prd.md。
• “为此创建工单／问题（GitHub · GitLab · Jira）” → tickets，这是一个独立命令，会读取审计结果并创建工单，不写入 Markdown。--grain 用于选择每个工单的粒度：每项标准（默认）、每个页面、每个页面+标准、每个文件，或合并为一个。按精确标题去重，因此重复运行不会产生重复项。请务必先运行 --dry-run；请阅读 references/tickets.md。
• “接入或编写标准包（RGAA 及其他），让 AI 摄取外部规则” → 使用 --pack/.ultra11yrc.json 在运行时加载，使用 pack check 对其进行门控（防幻觉护栏），使用 pack scaffold 开始创建；具体的实现前后指导会附加到发现项／PRD；请阅读 references/packs.md 和 references/guidance.md。
• “裁定判定标准（判定阶段）” → verify --manual --in audit.json 会生成裁定工作清单（ADJUDICATE.todo.json + ADJUDICATE.md），每项剩余标准对应一个条目，并预先载入引擎收集的证据（所有替代文本、链接文本 + 上下文、字面颜色对、控件标签、标题大纲、ARIA 状态、tabindex、各部分语言）；AI Agent 填写每项的 verdict——C/NA（附带 justification）、NC（附带可据以核实的发现），或 manual（附带 reason）——然后运行 verify --apply … --in audit.json 将结果合并回去，并执行失败关闭；请阅读 references/judgment.md。
• “有许多项目需要裁定／验证（将判定任务分派给子 Agent）” → orchestrate --run <dir> 会根据本次运行当前的工作清单，为每个就绪阶段生成一个可启动的多 Agent 工作流，以及 agents/<role>.md 分派约定和顺序执行的 RUNBOOK.md——这是支持子 Agent 的运行环境中的默认执行路径；请参阅下方的编排——按运行环境选择路径。
• “聚焦、键盘和交互逻辑（交互逻辑部分）” → 引擎会将焦点顺序／可见性／陷阱，以及聚焦时／输入时的标准标记为剩余风险；AI Agent 会阅读完整的组件源代码并裁定键盘／焦点行为（可见焦点和其他渲染标准交由 scan 处理）；请阅读 references/focus-and-logic.md。
• “落实修复” → fix（默认试运行，--write 会应用安全的 codemod，并在不凭空捏造内容的前提下提出其余修复建议）；请阅读 references/fix.md。
• “按优先级修复，避免回归（修正阶段）” → fix（--write、 --iterate）+ prd 待办列表，按阻塞→主要→次要的顺序处理；请阅读 references/correction.md。
• “自动仓库门控（钩子／CI）” → init --hook 会基于严格的暂存快照写入 git 提交前门控（审计索引中的精确 blob，自动应用安全修复并重新暂存，仅阻止判定问题）；init --baseline/--ci 是选择性启用的“仅阻止新的不符合项”变体。作为 Claude Code 插件安装后，还有第三种门控：在待提交／推送／PR 时运行 review-a11y 技能（不只是引擎）——此功能由插件提供，而非 init。对于库／单文件组件代码，请提交已渲染的采集文件（render --setup）并将其暂存，以检查真正的语义 HTML（audit --require-captures）；请阅读 references/automation.md。
• “构建页面时显示问题” → dev --next 会写入单行覆盖层组件，而 dev 会启动一个回环辅助服务：浮动面板会列出当前页面的不符合项，每项都能在编辑器中打开对应的 file:line；你浏览页面时，http://127.0.0.1:4111 会累积逐页网格。开发环境之外不会渲染任何内容；请阅读 references/devtools.md。
• “在 E2E 测试期间检查页面” → render --e2e 会写入 Playwright/Cypress fixture，按测试留下的页面状态审计页面（已登录、表单已填写、模态框已打开）——这些状态是单独运行 scan 无法获取的——并将每个检查过的页面保存为快照。failOn 会对测试进行门控；failOn: false 会记录结果但不使测试失败，适合在已有待办列表的项目中采用；请阅读 references/e2e.md。
• “审计真实页面，而非组件” → 页面快照（.ultra11y/pages/<id>/）包含完整的已渲染文档和仅浏览器可获取的信号（计算样式、框、无障碍树、屏幕截图），并由 audit 自动摄取。由于这是完整文档，页面级规则会在其上运行——只有这样，RGAA 8.3（语言）、8.5/8.6（标题）和 12.6 才能判定；请阅读 references/pages.md。
• “在 CI 中不使用浏览器判定渲染标准” → 创建页面快照后，渲染层级会在常规 audit 中运行：计算样式对比度（RGAA 3.2/10.5）、针对渐变／图片上文本的屏幕截图测量对比度（与 axe-core 一样存在的 CSSOM 盲区），以及仅凭颜色识别链接（RGAA 10.6，此前无法判定）。无法测量时，每项都会保留为 manual；绝不猜测；请阅读 references/pages.md。
• “逐页显示 RGAA 网格” → pages --in audits/audit-latest.json --standard rgaa（也嵌入在 report 中）：每项标准一行，每个页面 URL 一列，仅根据已提交的 audit.json 重建。遵循两项规则：只有在证据明确指出归属时，才将发现归属到页面（否则会报告为未归属，绝不扩散）；只有审计过真实 DOM 的页面，才可凭沉默判为 C——仅有源代码的页面，其未决标准仍标记为“待评估”；请阅读 references/pages.md。
• “我需要逐页报告，而不是矩阵” → pages --in audits/audit-latest.json --standard rgaa --format report --split page --out audits/pages：每页生成一个档案——页面信息、屏幕截图、符合率、该标准的每一项标准在该页面上的状态，然后是每项不符合项对应的常规审计员区块。不会重新判定任何内容（与网格采用相同投影），也不会发明新格式（与报告采用相同审计员区块），因此页面报告和合规报告不会相互矛盾。与其他报告一样，check 会检查是否存在虚构标准；请阅读 references/pages.md。
• “我应该审计哪些页面？” → pages discover --crawl http://localhost:3000 --write（或 --sitemap <url>）会为你写入 sample.pages 区块，从每个页面提供的 <title> 中提取名称，并且绝不会覆盖已声明的 auth/storageState/notes。然后运行 sample check 检查覆盖范围，并运行 scan --sample 扫描并生成快照。客户端渲染的 SPA 不会在其提供的 HTML 中公开路由——请改用站点地图；请阅读 references/dynamic.md。
• “在 CI 中逐页审计这些 URL” → 随附的 Action 接受 urls、sitemap、crawl 或 sample，为访问的每个页面生成快照，并在作业摘要和 audits/pages-status.md 中记录每个页面的每项标准状态。使用 pages-report: compact 生成仅含状态的报告包：只包含 Markdown、页面 JSON、源审计和判定记录（不含裁定工作清单、修复报告、HTML 或裁剪图）；或者保留默认值 true，同时生成详细的页面档案。若要在拉取请求中显示同一网格，请请求 pages/full PR 评论；请阅读 references/ci.md。
• “没有人可以裁定判定标准” → judge --in audits/audit-latest.json --standard rgaa [--apply] 会使用模型裁定这些标准，适用于没有编码 Agent 参与的运行（CI、扩展、E2E 运行）。它是调用方，不是第二个裁定者：使用相同的工作清单、证据、提示词，判定结果也会经过与你相同的失败关闭门控。使用带 API 密钥的 --runner api，或使用该本地 CLI 现有订阅登录的 --runner claude|codex（--runner cli 仍是 Claude 的别名）。在 Agent 中，优先使用 verify --manual 并自行裁定工作清单；请阅读 references/judgment.md。
• “在拉取请求中显示发现项，而不只是让作业标红” → --format sarif（上传到代码扫描 → 在正确的 file:line 添加内联注释），或 --format github（::error:: 工作流命令 + $GITHUB_STEP_SUMMARY 表格）——若要使用标准包中的标准，而非 WCAG 的标准，请从 report --standard rgaa 运行；请阅读 references/ci.md。
• “让此代码具备无障碍性／检查代码” → 以原生优先方式审计代码片段（audit - < component.html）；请阅读 references/authoring.md 和 references/forbidden-patterns.md。
• “标准 X 的含义是什么？” → criteria（例如 criteria 1.4.3，或 criteria --standard rgaa 8.3）；请参阅 references/criteria.md。
• “某项检查有多可信／引擎不会检测什么？” → 引擎使用 W3C ACT-Rules 测试语料库（约 1 100 个第三方示例）进行评分：哪些检查结果一致、哪些召回率不完整、哪些偏差是刻意为之，以及哪些静态可判定规则仍未实现——请阅读 references/act.md。在裁定之前，请用它校准引擎实际判定了多少标准内容。
• “国家标准（RGAA、Section 508、EN 301 549）” → 在 report/prd/criteria/check/verify 上使用 --standard <pack>；请参阅 references/standards.md 和 references/methodology.md。对于国家标准审计，默认应建议执行扫描：此类审计在规范上以声明的页面样本为准，而未扫描的 --standard rgaa 报告会标记为不完整——请明确说明，而不要暗示覆盖完整。样本工作流（sample check、scan --sample、--merge）见 references/audit.md。
• “高保障审计” → verify --report … --semantic；请参阅 references/verify.md。
• “检查对比度／渲染（动态层级）” → scan <url> --merge … 会在无头浏览器中运行 axe-core，并在本地运行环境中检查焦点可见性、200% 缩放、文本间距和悬停时的内容，同时支持有界的有状态交互和经过身份验证的页面；请阅读 references/dynamic.md。
• “判定状态为 needs-rendered-dom 的标准” → 它们不需要更好的模型，而是需要浏览器。scan 会将测量结果与每个快照一同保存（probes.json、axe.json），因此经过缩放、重排和 Tab 导航的页面可以得到符合判定，而非“待评估”——RGAA 3.2/3.3/10.4/10.11/10.12 会依据测量结果判定，10.1/12.8 则可根据真实 DOM 进行裁定。verify --manual 会在你耗费一轮之前发出警告，check --require-rendered 会拒绝未渲染的页面，而爬取默认不设上限（--max 0 / --depth 0），并会公布访问的每个页面。请阅读 references/dynamic.md 和 references/pages.md。

编排——按执行框架路由

判定阶段会拆分处理：ADJUDICATE.todo.json（每项对应一个剩余判据）和 VERIFY.todo.json（每项对应一条 NC 声明）是相互独立的逐项工作列表；orchestrate --run <dir> 会根据当前存在的工作列表生成可启动的工作流、各角色的分派约定以及按顺序执行的 RUNBOOK。拆分处理是一种优化，而非必需：各门禁与执行框架无关，每个阶段都有产物完全相同的顺序执行后备方案，而 fail-closed 的 verify --apply 汇总始终由你负责。路由表和规则请参阅 references/orchestration.md。

命令速查表

完整命令列表请查看 --help；以下是最常用的命令。

node scripts/ultra11y.mjs audit "src/**/*.tsx" --graph --out audits --json   # the default audit (AST + cross-file, persisted)
node scripts/ultra11y.mjs audit - < component.html                           # a snippet via stdin
node scripts/ultra11y.mjs audit --changed --json                             # only the git diff (large repo)
node scripts/ultra11y.mjs audit --staged --fail-on blocking                  # gate EXACTLY the staged snapshot (pre-commit)
node scripts/ultra11y.mjs audit "dist/**/*.html"                             # the RENDERED HTML (reliable for DSFR/MUI…)
node scripts/ultra11y.mjs render --setup                                     # install the capture harvester (tests → .ultra11y/captures)
node scripts/ultra11y.mjs audit --require-captures                           # gate the components with no rendered capture
node scripts/ultra11y.mjs scan http://localhost:3000 --runtime local --cwd . --merge audits/audit-latest.json
node scripts/ultra11y.mjs check --in audits/audit-latest.json --require-rendered              # gate: a rendering criterion left open by a run that rendered nothing
node scripts/ultra11y.mjs pages --in audits/audit-latest.json --standard rgaa --json --out audits  # the per-page grid, for a machine (audits/pages.json)
node scripts/ultra11y.mjs verify --report audits/wcag-YYYY-MM-DD.md --in audits/audit-latest.json --manual --out audits
node scripts/ultra11y.mjs verify --apply audits/ADJUDICATE.todo.json --in audits/audit-latest.json --out audits
node scripts/ultra11y.mjs orchestrate --run audits                           # fan the judgment phases out (--eco for the sequential path)
node scripts/ultra11y.mjs report --in audits/audit-latest.json --out audits  # → audits/wcag-YYYY-MM-DD.md
node scripts/ultra11y.mjs prd     --in audits/audit-latest.json              # the same auditor block as a backlog
node scripts/ultra11y.mjs tickets --in audits/audit-latest.json --dry-run    # file it: GitHub/GitLab/Jira
node scripts/ultra11y.mjs check  --report audits/wcag-YYYY-MM-DD.md          # integrity gate
node scripts/ultra11y.mjs criteria 1.4.3                                     # one success criterion (--list for all)
node scripts/ultra11y.mjs fix "src/**/*.html" --write --iterate               # apply the safe codemods to a fixpoint
node scripts/ultra11y.mjs init --hook                                        # pre-commit gate (--baseline for the regression variant)
node scripts/ultra11y.mjs pack check ./packs/section508.json                  # gate an (AI-)authored standards pack

audit 也要加上 --standard rgaa，这样所有输出都会采用 RGAA 标准。 该选项适用于 audit/scan/fix，也适用于 report/prd/tickets/criteria/check/verify/judge； 使用 .ultra11yrc.json { "standard": "rgaa" } 可将其设为所有命令的默认值。在此模式下， audit 会输出以 RGAA 为标题、按主题分类汇总的结果，发现项标记为 [8.4]， 而不是 [3.1.1]，并使用规则包自身的语言；--json 和 --out 会写入一份以规则包为键的 文档（包含 106 项判据、13 个主题），并在 core 中保留 WCAG 核心内容供流水线使用；CI 注释、SARIF、报告、PRD 和逐页工作表只列出 RGAA 判据，不会在规则包的任何交付物中 出现 WCAG 交叉引用。引擎内部仍以成功准则为键，因为规则包判据被定义为这些准则的映射； 这是内部机制，读者不会看到。添加 --pack ./pack.json 可在运行时加载标准，并可在任何位置 添加 --json 以输出机器可读内容。 --lang 遵循对话语言（请明确传入——核心规则 7）。

工作循环：audit → render → judge → fix → re-audit

要逐步实现符合性（而非只执行一次），请串联这些步骤，让 Agent 驱动判定和内容阶段：

1. 审计源代码（audit … --graph），建立初步全貌；对于由库渲染的代码， 应先审计渲染结果（render → 构建/SSR → audit），才能得出可靠结论（否则 范围风险说明会提醒你）。 1b. 先渲染，再判定——只要有渲染判定标准尚未处理，此步骤就不是可选项。运行 scan <url|file> --runtime local --merge audits/audit-latest.json --out audits （或 scan --sample），通过真实浏览器逐页扫描，将每个页面及测量结果保存到 .ultra11y/pages/<id>/（probes.json、axe.json），并合并扫描结果。跳过此步骤 并不会让这些标准仅仅处于未处理状态——而是会让任何人都无法判定：无论如何阅读 源代码，都无法确定计算后的对比度、200 % 缩放、320 px 重排或文本间距，因此，每次 对这些标准进行判定都会耗费模型资源，并返回 needs-rendered-dom。在一个包含两个 文件的样例上运行 RGAA 审计时测得：仅凭源代码需要判定 80 项标准，扫描单个页面后 则为 41 项；三轮、$24.90 的级联判定最终留下的七项中，有六项在测量后得以结案。 verify --manual 现在会在你花费任何资源之前说明这一点，而 check --in <audit.json> --require-rendered 会将其设为门槛。
2. 使用 verify 进行判定与反证，生成两个待办清单。(a) verify --manual --in audit.json 会生成 ADJUDICATE.todo.json——每项尚待判断的标准对应一条任务，并预先填入引擎 收集的证据——由 AI Agent 作出判定（C/NC/NA；如果确实 needs-rendered-dom，则标为 manual 并提供 reason），每项判定都须附上 justification 或有依据的发现；verify --apply … --in audit.json 会以失败关闭方式 将结果合并回来（Agent 判定为 NC 的项会成为真实的 agent:<sc> 发现，并在 §2 中 重新渲染）。(b) verify --report … [--semantic] 会生成 VERIFY.todo.json，对两个 方向都进行检验。它会反驳任何被渲染 DOM 推翻的 preliminary/SFC/库源码不符合项； 若存在判定记录（默认如此），也会将记录中由 Agent 判定为符合项的条目送审， 每条引用对应一项任务，并反向提问：这项证据能证明符合该标准，还是只能证明其对象 存在？ 过去没有任何机制质疑 C，因此，若某项标准仅因其对象存在而非正确就被判为 符合，该符合性声明便会直接发布。判定选项相同 （supported/partial/refuted/unsupported）；verify --apply 会移除被推翻或 不受支持的不符合项，并将被推翻的符合项所对应的标准退回“待评估”——绝不会改判为 NC，因为推翻符合性并不能证明该标准不符合。可使用 --no-conformities 选择退出。 此流程还包括焦点与交互逻辑（阅读完整组件源码：键盘可操作性、焦点顺序/可见性、 焦点陷阱、焦点/输入时发生的变化；参见 references/focus-and-logic.md），以及 references/false-positives.md 中针对各规则的陷阱。两个待办清单都可分派并行处理 （orchestrate --run <dir> --phase adjudicate|verify-report——参见 编排——根据运行框架选择路径）；--apply 合并操作始终由你执行。 判定每项标准时，都要依据该标准本身的文本，而不是凭记忆。verify --manual 还会 为每项标准生成一份简短说明（adjudicate/<criteriaId>.md），其中包含标准的官方措辞、 编号测试；若采用国家标准，还包含该标准自己的测试方法（RGAA 为其全部 258 项 测试都发布了测试方法），以及相关术语表、技术说明和具体案例。请阅读这份说明；使用 --standard rgaa 时，以 RGAA 为准，绝不能以其背后的 WCAG 成功标准为准。每份说明 还会引用该标准的官方页面：如果措辞仍有歧义且你有网页工具，可以查阅该页面——但 绝不能用它来反驳随附的文本，网页也绝不能作为可接受的 normativeRef （--no-web 会取消此选项；CI 默认会将其禁用）。
3. 按优先级修复：先运行 fix --write --iterate 处理机械性问题（防回归门槛）， 然后参照 references/correction.md，手动应用判断与内容修复（替代文本、标签、结构）。
4. 重新审计（相关时审计渲染结果），并重复此流程。
5. 提供审计员区块。report（合规文档：综合摘要，以及每项 NC 标准对应的一个审计员 合规区块——主题/标准/测试/WCAG+级别/发现/预期/验证）和 prd（将相同区块整理成 可执行的待办列表；tickets 则为每项标准创建一个 GitHub issue，并附上相同区块）， 是同一个基础构建块的两种呈现形式，语言采用本次对话的语言（请明确传入 --lang—— 核心规则 7）。
6. 在子 Agent 中将变更交给 review-a11y。 交付物完成后， 你刚修复的代码仍须作为一项变更接受审查，而这正是另一个 技能的职责——见下文移交给 review-a11y。

当 check 和 verify --apply 再次通过，且只剩明确列出的风险时，停止。（要自动化外层循环节奏，可使用 harness 的 /loop 命令 重新运行此循环。）

移交给 review-a11y

此技能会端到端地完成分析：审计、渲染、判定、修复、重新审计、交付。 完成修复后，将待变更的代码作为子 Agent 任务派发给 review-a11y， 并报告它的返回结果。

使用宿主原生的子 Agent 功能：Codex 使用下方提示词派发子 Agent； Claude Code 可使用 Agent(...)。如果宿主两者都不支持，请按下方的顺序流程执行。

Use the review-a11y skill on the working diff. Return its report verbatim.

两个技能、两种范围，这种划分并非表面功夫：

	范围	要回答的问题
ultra11y（本技能）	仓库、页面样本、标准	此产品是否符合要求，证据在哪里？
review-a11y	恰好是待变更的代码（暂存区、差异，或分支与合并基点的比较）	这项变更是否可以安全合并？

为何使用子 Agent，而不是内联审查。 完整审计会让上下文被 3 MB 引擎的输出、 数十个参考文件和页面样本填满；审查则必须仔细阅读差异，不能受这些内容干扰。 移交后，审查判断便能独立于刚刚执行的审计——这与 verify 反驳发现结果而不是盲目采信的原因相同。如果 harness 没有子 Agent 工具，请直接调用 review-a11y：references/orchestration.md 中的路由表列出了备用方式，两种方式的审查结果 完全相同。

不要改写它的结论。 它返回按严重性排序的审查结果，其中包含 file:line 和 一行结论；这就是交付物，而不是摘要。

综合引擎结果、判断与剩余风险

audit 会将每项标准标记为 C/NC/NA（静态子集）或 manual（其余部分），并为每项标注一个说明为何需要人工处理以及如何完成的 automatability 类别： static（由引擎判定）、needs-rendering（使用 scan）、judgment（根据收集到的证据和判定协议作出判断）。引擎给出的 NC 是已确认的候选项，并附有引用的 file:line；preliminary: true 的发现（SFC/库源代码）属于暂定结果——请通过渲染确认，或予以反驳。不得默默地将标准标记为符合：只有每项适用标准都被合理标记为 C/NC/NA，且所有剩余风险都已列明，报告才算完整。参见 references/methodology.md。

建议性意见是独立类别。 如果良好实践信号没有任何未通过的规范性测试，就会显示在专门章节中，绝不能将标准改判为 NC，也不能计入 conformancePct。NC 必须有 normativeRef；建议则不需要。不要将两者混为一谈——参见 references/false-positives.md。

请勿

• 臆造引擎未发现且你也无法观察到的不符合项（内联字面量颜色的对比度由静态方式判定；计算后的对比度——外部 CSS、变量——通过 scan（Docker 层级）处理，或在声明之前通过渲染验证）。
• 添加与原生语义重复的 ARIA。
• 未记录并经过门控的合理依据（通过 Agent 判定的 verify --manual，或 scan 证据），就将渲染/判断类标准标记为“符合”。
• 手动编辑 references/criteria.md（该文件由 WCAG 数据集通过 criteria --generate 生成）。

范围

静态引擎：离线、确定性、无需安装；输入包括 HTML + JSX/TSX（真实 AST，通过 --graph 进行跨文件分析）+ stdin。渲染标准（计算对比度、重排）由可选的 scan 层级覆盖（axe-core、Docker 或 --runtime local）。 本地运行时还会探测焦点可见性（2.4.7）、200% 文本缩放（1.4.4）、文本间距（1.4.12）和悬停时显示的内容（1.4.13）——在渲染后的页面中观察，仅在发现故障时才报告为 NC（探测结果正常时，SC 仍为 manual，绝不静默判定为符合）；阅读顺序和替代文本相关性由 AI Agent 判断，根据采集的证据进行裁定，并设有门控（verify --manual）。 数据：WCAG 2.2 © W3C（W3C 文档许可）；RGAA 软件包为 RGAA 4.1.2 © DINUM，Licence Ouverte / Etalab 2.0（参见 NOTICE）。