agentic-awesome-skills 无障碍扫描技能 accesslint-scan 实战：基于选择器的 WCAG 违规定位与修复清单生成

AI 技能AI 插件【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/gh_mirrors/an/agentic-awesome-skills点击查看免费下载导读accesslint-scan是 agentic-awesome-skills 仓库中面向真实运行页面的无障碍Accessibility审计技能它不依赖静态源码猜测而是启动真实 Chrome 对线上页面执行 WCAG 扫描逐条定位每个违规发生的确切 DOM 位置并输出一份选择器锚定selector-grounded的修复工作清单——只定位、不修改。阅读本文后你将掌握该技能的完整执行流程Audit → Report → Tear down、每个 CLI 参数的作用与注意事项并能与同族的accesslint-audit审计修复和accesslint-diff变更回归对比组合成完整的无障碍质量闭环。一、技能定位只定位、不修复的无障碍审计入口在仓库中accesslint-scan以 SKILL.md 的形式存在于两处插件目录plugins/agentic-awesome-skills-claude/skills/accesslint-scan/SKILL.md本文关联文档plugins/agentic-awesome-skills/skills/accesslint-scan/SKILL.md主插件目录中的同技能版本数据目录中的技能索引与目录也收录了该技能data/catalog.json 中记录了它的元数据risk: safe、category: uncategorizedtags 与 triggers 覆盖accesslint、scan、audit、live page、wcag violation、locate、precisely等关键词描述与 SKILL.md frontmatter 完全一致Audit a live page for accessibility issues, locate each WCAG violation precisely, and return a selector-grounded fix worklist without editing.技能的边界极其明确作用对象一个真实运行live的页面 URL而非静态 HTML 字符串或源码文件目标审计并精确定位每个 WCAG 违规violation产物选择器锚定的修复工作清单fix worklist红线不编辑任何文件Dont edit。如果$ARGUMENTS中没有提供 URL技能会要求你先给出目标地址。这种只审计、不越界修改的设计使其适合在开发流水线中作为独立的检测关口或作为修复前的事实收集步骤。二、完整执行流程三步走技能将一次审计拆分为三个明确阶段推荐按顺序执行。2.1 第一步Audit启动浏览器并扫描首先用accesslint/chrome的ensure命令确保存在一个可用的 Chrome 调试会话并动态解析出调试端口随后用accesslint/cli对目标 URL 执行扫描PORT$(npx -y accesslint/chromelatest ensure | node -e process.stdin.on(data,dprocess.stdout.write(JSON.parse(d).port))) npx -y accesslint/clilatest url --port $PORT --format json这两行命令的核心机制值得拆解ensure负责确保存在可用浏览器。它可能复用已运行的 Chrome 调试会话也可能自动启动一个最小化minimized的 Chrome并把会话信息含port字段以 JSON 形式输出到 stdout内联的node -e一行代码从该 JSON 中提取port字段写入PORT变量——端口永远由ensure动态决定绝不能硬编码Gotchas 中明确强调 never hardcode 9222CLI 通过--port $PORT连接该调试端口对url执行无头审计并以--format json输出结构化结果。ensure返回的 JSON 中还有一个关键字段managed。如果ensure报告managed: false说明它复用的是外部已有的浏览器会话不由本技能管理此时收尾阶段不应执行 stop 清理。可选 Flags按需追加Flag作用--selector仅对指定 CSS 选择器命中的元素做审计缩小扫描范围--wait-for selector等待页面中出现指定选择器后再开始审计用于单页应用SPA异步渲染或需要登录后的状态--include-aaa默认审计基线为 WCAG AA追加此参数可额外启用 AAA 级别规则--disable rules禁用指定的规则 ID用于排除与当前目标无关或已知噪音的规则--format json以 JSON 输出结果便于后续程序化处理报告中按 impact 汇总这些参数与同族的accesslint-diff技能完全对齐后者的文档中同样要求--selector、--include-aaa等参数在两次运行中保持一致以保证基线可比。2.2 第二步Report生成修复工作清单扫描完成后输出一份结构化报告先按影响级别impact统计数量再为每一条违规单独给出一个条目条目由三要素组成where在哪里——违规元素的选择器原文verbatim如果结果中存在source字段则附加file:line (symbol)形式的源码定位信息。绝不臆造source如果没有任何违规带source则明确注明 source mapping unavailable — located by selector only仅凭选择器定位evidence证据——触发该规则的具体事实例如对比度比值contrast ratio、缺失的属性missing attribute、空的可访问名称empty namefix怎么修——给出机械式mechanical修改建议或标注NEEDS HUMAN需要人工介入。evidence 必须是可验证的客观事实这一点在同族accesslint-audit技能中有更详细的展开对于mechanical类规则要逐字引用引擎给出的Fix:指令对于visual/contextual类规则不臆造修复内容而是留下带规则 ID 的TODO。不编辑原则本阶段严禁修改任何文件。对于报告中发现的机械式修复mechanical fixes正确的做法是在外部应用修复后重新运行本技能验证效果如果需要大批量bulk修复则把工作移交给accesslint:audit该技能支持 audit→edit→verify 的修复闭环。2.3 第三步Tear down清理浏览器会话npx -y accesslint/chromelatest stop --all # skip if ensure reported managed:falsestop --all会关闭由本技能启动的全部 Chrome 调试会话。注释给出了唯一例外如果前面ensure报告managed: false说明会话是外部管理的跳过本步骤避免关闭用户自己的浏览器。三、三个易踩的坑Gotchas技能文档明确列出两条高频问题实战中几乎每次都会遇到端口必须动态获取ensure的输出每次都可能不同端口由它决定并写入PORT。硬编码 9222 在端口被占用或外部会话存在时会直接失败。CLI 退出码 2 页面未加载当npx -y accesslint/clilatest url返回退出码 2 时表示 URL 无效或页面从未成功加载。此时应检查开发服务器dev server是否在运行、URL 是否可达而不是怀疑扫描器本身。四、技能族协同scan / audit / diff 的分工accesslint-scan不是孤立的技能。仓库的 docs/users/bundles.md 将它与另外两个技能并列介绍accesslint-audit支持 report全库/页面审计出报告与 fix审计→编辑→验证循环两种模式适合大批量修复accesslint-scan对界面做无障碍回归扫描只定位不修改本文主题accesslint-diff基于 git stash 或分支对比只报告新增 / 已修复 / 存量的违规变化。三者的推荐组合方式是日常巡检 / 回归用accesslint-scan全量扫描当前页面拿到选择器锚定的修复清单修改前基线、修改后验证用accesslint-diff对比改动前后确认没有引入新违规new为空、目标违规确实被修复-fixed覆盖目标批量修复把 scan/diff 发现的问题移交accesslint:audit的 fix 模式执行 audit→edit→verify 闭环。从accesslint-audit的文档还可以看到更深的机制细节live-DOM 审计针对 React 开发构建时会通过 DevTools fibers 为每条违规附加Source: file:line (Symbol)信息当source缺失时退化策略是稳定 hookdata-testid、id、aria-label→ 可见文本 → 树位置。这与 scan 技能有source就附加、没有就明说仅按选择器定位的规则完全一致印证了source字段只在特定条件下出现、不可依赖更不可编造。五、适用边界与注意事项技能文档在 Limitations 中给出了三条明确边界使用时应遵守仅当任务与上述范围完全匹配时使用本技能专精于对 live 页面做 WCAG 定位审计不适用于静态源码审阅、HTML 字符串审计等其他形态那些场景应改用accesslint-audit的audit_html流程输出不能替代环境级验证自动扫描只能捕获机制上可检测的问题。内容清晰度、屏幕阅读器播报质量、键盘操作连贯性、复杂视觉对比度等需要人工判断的维度必须交给专家复审不要用扫描结果直接下结论输入不完整时先澄清如果缺少必要的输入、权限、安全边界或成功标准应停下来向用户询问而不是自行假设。六、总结accesslint-scan为 Agent 提供了一条零侵入的无障碍审计路径ensure动态管理 Chrome 调试端口CLI 全量扫描 WCAG 规则报告以选择器 证据 修复建议三要素逐条呈现stop干净收尾。它与accesslint-audit、accesslint-diff形成扫描定位 → 批量修复 → 变更对比的完整技能族可作为无障碍质量保障流水线的检测关口——定位交给它修复交给 audit回归交给 diff人工判断永远保留在流程的最后一环。赞分享AI 技能AI 插件【免费下载链接】agentic-awesome-skillsAAS Core is the local, agent-first control plane for complete catalog discovery, agent-owned selection, stack validation, and planning, backed by 2,115 agentic skills. Includes CLI, local MCP, catalog, plugins, and Workbench.项目地址https://gitcode.com/gh_mirrors/an/agentic-awesome-skills点击查看免费下载相关推荐Playwright 无障碍测试实战指南用 AxeBuilder 与 axe-core/playwright 扫描整页、局部与 WCAG 违规Playwright 无障碍测试实战指南用 AxeBuilder 与 axe core/playwright 扫描整页、局部与 WCAG 违规 本篇指南基于测试开发工具浏览器控制JupyterLab无障碍测试清单WCAG合规性检查与修复方案JupyterLab无障碍测试清单WCAG合规性检查与修复方案 引言 你是否曾在使用JupyterLab时遇到过键盘导航困难、屏幕阅读器无法正确识别内容的问题前端后端数据科学开发工具WebdriverIO 无障碍测试集成指南使用 TestMu AI原 LambdaTest实现 WCAG 合规扫描WebdriverIO 无障碍测试集成指南使用 TestMu AI原 LambdaTest实现 WCAG 合规扫描 导读 本指南介绍如何在 Webdriv测试质量保障上一篇be-a-professional-programmer自动化测试从Selenium到JMeter下一篇UniTask性能优化使用ReadOnlySpan减少内存分配创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考