前言¶
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 合規性檢查效率。
