前言¶
DSH 插件生态旨在通过组合独立工具解决开发中的具体问题。在进行前端项目开发与审查时，确保无障碍合规（WCAG）通常依赖人工检查或复杂的静态分析工具。dsh-a11y-scan 是一个原生插件，通过集成 axe-core 扫描引擎，对本地 HTML 文件、构建输出目录或确认后的 URL 进行自动化检测，并输出结构化的违规报告。
核心能力¶
本插件主要提供以下能力：
* 自动化扫描：基于 axe-core 对本地 HTML 文件、Vite/Next.js 等构建产物目录，或用户确认后的 URL 进行扫描。
* 多格式输出：支持将违规结果报告为 Markdown、HTML（自包含单文件）或 JSON 格式。
* 只读模式：插件为只读工具，不自动修改代码；所有文件写操作需通过显式参数配置。
* 可编程独立工具：可独立于对话流在 CI/Workflow 中调用，输出结构化数据。
* 自动化与人工复核并存：对于 axe 无法自动判定的项（如焦点顺序、键盘操作、朗读顺序等），输出为 incomplete 清单供人工复核。
* 详细报告信息：每条违规包含规则 ID、Impact 严重度、WCAG 2.1 映射、元素定位信息及修复建议。
安装与启用¶
安装插件需要将本地路径挂载到指定的 Profile。
dsh plugin --profile <name> add /path/to/dsh-a11y-scan
使用方法¶
工具名为 a11y_scan，通过 dsh tool run 调用。主要参数如下：
* path：扫描目标，支持项目目录、单个 HTML 文件或 URL（URL 模式需 confirmUrl: true）。
* level：WCAG 合规级别，支持 A、AA、AAA，默认为 AA。
* wcag21：是否使用 WCAG 2.1 标签族，默认为 true。
* out：报告格式，支持 md、html 或 json，默认为 md。
* confirmUrl：扫描 URL 时是否需要显式确认，默认为 false。
* reportFile：指定生成的报告文件路径（可选）。
示例：
dsh tool run a11y_scan '{"path": "dist", "level": "AA", "out": "html", "reportFile": "reports/a11y.html"}'
注意事项¶
- 前置依赖：插件依赖
@axe-core/cli（MPL-2.0 许可证）作为扫描后端，该依赖需在目标项目目录下单独安装（npm i -D @axe-core/cli），插件本体不打包此依赖。 - 开发模式依赖：在开发形态下，插件依赖相邻的
dsh-src目录（Link 依赖）。 - 权限与安全：插件以当前 DSH 进程权限运行。URL 扫描需要显式开启
confirmUrl；本地文件扫描不会访问网络。 - 授权说明：插件本体代码遵循 MIT 协议，扫描引擎
axe-core遵循 MPL-2.0 协议。
总结¶
dsh-a11y-scan 通过将 axe-core 集成到 DSH 生态中，提供了一种确定性的自动化无障碍审查方案。它不仅能输出结构化的违规清单，还通过 incomplete 项标记了需要人工复核的边界情况。结合 CI 流程与人工复核，能够有效提升前端项目的 WCAG 合规性检查效率。
