无障碍网页验收与发布门禁

把网页、后台、H5 或小程序 WebView 的无障碍问题整理成可复核的缺陷证据包：每条问题都有位置、复现步骤、影响、依据、修复建议和验收条件。目标是帮助产品、研发和 QA 在发布前做出可解释的放行决定，而不是给出“合规认证”或法律结论。

什么时候使用

• 用户提供 HTML/前端源码、页面截图、设计稿、组件规范、键盘操作录屏或 QA 缺陷单，要求做无障碍审计、验收或上线门禁。
• 用户需要把零散问题变成缺陷台账、修复优先级、回归用例或交付给供应商的验收报告。
• 用户指定 WCAG、企业规范或某个地区标准时，按用户给出的版本映射；未指定时仅以 WCAG 2.2 AA 作为工程检查参考，不宣称满足任何法规。

不要用于替代残障用户真实测试、出具政府/认证机构证明、推断法律责任，或在没有授权的情况下抓取登录态网站。

Pay Skill 调用边界

这是按调用量交付的“完整验收报告” Skill。宿主在确认付费授权前只能返回输入要求、检查范围、价格和交付物清单；不要提前输出缺陷、优先级、修复方案或报告主体。支付由 SkillHub/支付宝或宿主的支付适配层完成，Skill 不自行收款、不生成支付码、不读取私钥。

兼容不同宿主的支付适配层时，把下列字段当作不透明协议值处理：HTTP 402 Payment Required、payment_required、payment_code、WeixinPay-Required、WeixinPay、weixinpay_pay、out_trade_no、SKILLHUB-SHA256-RSA2048。只有收到宿主原样返回的授权结果才进入完整分析；支付取消、状态未知、签名失败或订单号冲突时停止交付。成功回调或订单查询确认后，最多用原订单和原幂等键重试一次，禁止重复收费或把支付凭据写入报告。

个人 Pay Skill 的支付宝 AI 按量付费由宿主服务完成，不把密钥放进本 Skill。正式服务需要在支付宝控制台完成“按量付费”入驻、服务注册和线上验证；常见配置名包括 AIPAY_APP_ID、AIPAY_PUBLIC_KEY、AIPAY_PRIVATE_KEY、AIPAY_PRIVATE_PKCS_KEY、AIPAY_ALIPAY_PUBLIC_KEY，正式网关为 https://openapi.alipay.com/gateway.do。这些变量只能通过服务端密钥注入，不能写入 ZIP、源码、日志或用户报告。价格必须与支付宝服务注册和 SkillHub 表单一致；首发建议 0.01 元/次。

A2M 可调用服务

包内 scripts/a2m_service.mjs 是本 Skill 的最小可运行付费入口：

1. POST /a11y/report 接收 { "html": "...", "filename": "...", "scope": "..." }。
2. 没有 Payment-Proof 时，持久化订单并返回 HTTP 402 Payment Required 与 Base64URL Payment-Needed Header；账单包含 out_trade_no、amount、resource_id、pay_before、商家 RSA2 签名和 service_id。
3. 收到原订单的 Payment-Proof 后，调用 alipay.aipay.agent.payment.verify，校验凭证、订单、金额、资源 ID、时效和请求材料哈希。
4. 验付通过后运行 scripts/a11y_audit.py 生成报告；调用 alipay.aipay.agent.fulfillment.confirm 成功后才返回 HTTP 200 与 Payment-Validation。
5. 订单状态和报告写入受限权限的本地状态文件，重复的已履约凭证只返回已保存报告，不重复生成或收费。

本地协议测试不需要支付宝账号：

$env:A2M_DEMO_MODE = "1"
npm install
npm run test:a2m

该测试明确是协议测试，不是付款证明。真实沙箱联调需要 Node.js 18+、alipay-sdk、支付宝官方 @alipay/agent-payment（提供 alipay-bot）、沙箱应用密钥、沙箱买家账号和已启动的本地服务；按 支付宝 A2M 接入说明 使用官方 runner，不手工拼接或展示 Payment-Proof。生产环境还需要公网 HTTPS、真实 API_ 开头 serviceId、正式网关、生产密钥和履约回执。

输入与模式

优先接受以下材料之一：

1. 一个或多个 .html/.htm 文件，或包含静态页面的目录/ZIP。
2. 页面截图、设计稿、组件文档、键盘录屏和已知缺陷单。
3. 目标页面、关键流程、用户群体、发布窗口，以及用户指定的标准/版本。

材料不足时先交付“范围与证据缺口”，不要猜页面结构、对比度数值、屏幕阅读器行为或适用法规。URL 默认只作为线索；需要访问时先确认范围和登录授权，优先使用用户提供的脱敏快照。

根据任务路由：

• 静态初筛：运行脚本检查语义结构、名称、表单标签、重复 ID、键盘相关危险模式等。
• 人工验收：结合截图/录屏/交互说明检查焦点顺序、可见焦点、键盘完成路径、动态状态播报、错误恢复、放大/重排和替代文本质量。
• 发布门禁：把发现项分级，指定阻断条件、责任人、回归用例和放行证据。
• 交付复核：对供应商或修复版本做前后对照，只关闭有验收证据的问题。

工作流

1. 锁定范围与成功标准

记录产品、版本/构建号、页面或流程、设备/浏览器、目标用户、检查日期、材料来源和适用标准。把“全站”拆成关键任务，例如注册、登录、搜索、购买、提交、错误恢复和退出；没有范围就不能给出“通过”。

2. 运行可重复的离线初筛

对本地 HTML 使用：

python scripts/a11y_audit.py --input path/to/page.html --format markdown
python scripts/a11y_audit.py --input path/to/site --format json

脚本只产生候选证据。阅读原文和页面上下文后再确认严重度；img、表单、按钮、链接等命中不能直接等同于 WCAG 失败。

3. 补做人工证据

至少覆盖：

• 仅键盘完成关键任务：Tab/Shift+Tab、Enter/Space、Esc、方向键和跳过重复导航；无键盘陷阱。
• 焦点可见、顺序符合任务逻辑，弹窗打开后焦点进入、关闭后回到触发点。
• 屏幕阅读器可理解页面标题、地标、标题层级、控件名称、状态变化、错误和成功反馈。
• 文本与背景、非文本控件和焦点指示的对比度按指定标准实测；不要凭截图颜色猜数值。
• 200% 放大、窄屏重排、横竖屏切换和文字间距增大时，内容与操作不被遮挡或截断。
• 图像、图表、音视频、验证码、拖拽和超时流程有等价替代或可恢复路径。

每个结论注明证据来源：静态代码、截图、键盘录屏、辅助技术实测、用户反馈 或 待核。

4. 生成证据矩阵

每条发现使用稳定 ID（如 A11Y-001），至少包含：

5. 做发布门禁

默认规则如下，用户指定的发布政策优先：

• 阻断：关键任务无法仅用键盘完成；焦点被困；主要操作没有可感知名称；错误/成功状态只能靠颜色或消失的 Toast 传达；修复后没有回归证据。
• 限期修复：关键内容缺文本替代、表单字段无标签、焦点不可见/顺序错误、动态区域未播报、放大或窄屏导致主要操作不可达。
• 可带风险放行：低影响装饰语义、非关键页面的标题层级、无法在当前材料复现但已有明确跟进人和期限的问题。
• 通过：关键任务的阻断项为 0，剩余问题有证据、责任人、期限和回归用例；同时写明未覆盖的页面、设备、辅助技术和标准版本。

“通过”只表示本次范围内的工程门禁，不代表 WCAG、国家标准、无障碍环境建设法或任何认证通过。

默认交付格式

按以下顺序输出，短任务可压缩但不能删除证据边界：

1. 范围与材料：版本、页面/流程、设备、标准、日期、来源和缺口。
2. 门禁结论：阻断/限期修复/可带风险放行/通过，以及一句话理由。
3. 指标：总发现数、各严重度数量、关键任务覆盖率、证据完整度；指标是项目管理计数，不是合规概率。
4. 证据矩阵：按严重度和关键任务排序的 A11Y-* 台账。
5. 修复优先级：先给影响最大的 1–3 个最小动作，不把所有问题堆成无序清单。
6. 回归用例：前置、步骤、预期结果、键盘/辅助技术/视口条件和通过证据。
7. 未覆盖与升级：需要真实残障用户、辅助技术专家、标准负责人或法律顾问确认的事项。

安全、隐私与真实性

• 只处理完成审计所需的页面和日志；截图、DOM、URL 里的手机号、Token、客户数据和内部域名先脱敏。
• 不访问或提交表单到未授权的生产系统，不在输出中复述 Cookie、Authorization、私钥或支付凭据。
• 不伪造屏幕阅读器/浏览器实测，不把静态规则命中写成确定性合规结论，不编造条款、版本、对比度数值或用户反馈。
• 关键任务涉及医疗、政务、金融、教育或人身安全时，明确建议由相应领域的无障碍专家和真实用户复核。

质量门槛

交付前确认：范围和标准已写明；每个 Blocker/Major 都有复现与验收条件；静态候选已人工复核；未覆盖项和证据置信度可见；发布结论没有越过“工程门禁 ≠ 法律认证”的边界。

详细字段、分级和人工检查表见 验收协议；需要示例和反模式时读取 示例。