988hj7tczd-oss/dsh-a11y-scan

dsh-a11y-scan

[!IMPORTANT]
依赖前置：相邻 dsh-src 检出（link: 依赖）
本项目在开发形态下使用 link: 依赖指向相邻的 DeepSeek Harness 源码检出（dsh-src），
与当前仓库保持同一父目录布局（/dsh-src）。克隆本仓库后：
1. 先把官方 deepseek-ai/deepseek-harness 检出到与本仓库同级的 dsh-src/ 目录，并执行其 pnpm install && pnpm run build；
2. 再按下方「安装」一节执行本仓库的 pnpm install --offline && pnpm build 与测试。
发布到 npm 的版本会尽量把 link: 依赖替换为 registry 真实版本；无法替换的内部包保持 link:，见各包 README 说明。

DSH 原生无障碍（WCAG）扫描工具：扫描前端项目的 HTML（单文件 / 目录，含 vite/next 构建产物 / 用户确认后的 URL），用 axe-core 按 WCAG 2.1 A/AA/AAA 自动检测违规，输出 规则 id、impact 严重度、WCAG 2.1 关联（如 1.4.3 对比度）、元素定位（nodes：选择器/摘要/failureSummary）、修复建议，并可生成 Markdown / 自包含 HTML / JSON 报告。

- 只读扫描：绝不自动修改代码或文件；写报告文件需显式 reportFile 参数。
- 可编程独立工具：调用即得结构化结果，可进 CI / Workflow / Agent 循环。
- 自动化 + 人工复核并存：axe 扫不到或无法判定的项（焦点顺序语义、键盘操作、朗读顺序等）输出为「需人工复核清单」与 incomplete 项。

定位边界（避免与 dsh-frontend-engineer-agent 混淆）

| | dsh-a11y-scan（本插件） | dsh-frontend-engineer-agent |
| --- | --- | --- |
| 形态 | 可编程调用的独立工具（a11y_scan） | Agent 预设（含 80 个技能之一「无障碍审查」） |
| 用法 | a11y_scan 工具调用 / CI / Workflow | 对话式前端工程师会话 |
| 输出 | 结构化违规 JSON + 报告 | 自然语言审查意见 |

本插件与现有预设不重叠：预设负责「人机对话式审查」，本插件负责「确定性的自动化扫描」。二者可协同：先用本插件扫出规则命中清单，再请预设做人工复核位的解读。

安装与挂载

1) 安装运行时依赖（前置依赖见下节）
npm install

2) 构建
npm run build        # 产出 lib/（tsc）

3) 挂载到 profile
dsh plugin --profile  add /path/to/dsh-a11y-scan

package.json 声明 dsh.bundle.patch: ./cordis.yml；cordis.yml 以 insert 行将
dsh-a11y-scan/lib/index.js（Cordis name/inject/apply 插件）挂入会话注册表。默认注入
tools（注册）、fs（文件读写）、subprocess（axe 扫描后端）。

前置依赖（扫描后端）

| 依赖 | 用途 | License |
| --- | --- | --- |
| @axe-core/cli（含 axe-core 与 puppeteer/Chrome 无头浏览器） | 实际扫描引擎 | MPL-2.0（不随本包分发，按需安装；见下） |
| @deepseek-ai/cordis / dsh-fs / dsh-subprocess / dsh-tools | DSH 插件运行时 | MIT（DSH 内部包，link 安装） |

在待扫描的前端项目里（或目标目录可达的 node_modules 中）安装引擎：
npm i -D @axe-core/cli

未安装时 a11y_scan 返回明确的 prerequisite 错误并给出安装命令（绝不自动安装、
不静默失败）。工具对本地文件优先，云扫描只在本机无头浏览器内进行。

axe-core License 声明：axe-core 为 MPL-2.0。本包不打包、不修改 axe-core 源码，
运行时子进程调用用户安装的 @axe-core/cli；分发义务说明见 NOTICE。

工具：a11y_scan

参数

| 参数 | 类型 | 默认 | 说明 |
| --- | --- | --- | --- |
| path | string | 工作区根 | 项目目录 / 单个 HTML 文件 / URL。目录会递归发现 .html（含 dist/out 构建产物，跳过 node_modules/.git 等，最多 50 页）；URL 需 confirmUrl |
| level | 'A'\|'AA'\|'AAA' | 'AA' | 决定 axe runOnly 标签族（A/AA/AAA） |
| wcag21 | bool | true | true 用 wcag21a/aa/aaa 标签；false 用经典 wcag2a/aa/aaa |
| out | 'md'\|'html'\|'json' | 'md' | 报告格式；html 为自包含单文件（可离线打开） |
| confirmUrl | bool | false | URL 目标的显式用户确认；缺省时 URL 扫描被拒绝 |
| reportFile | string | 无 | 可选：把渲染报告写入此路径（只读默认，显式 opt-in） |

返回值（结构化值）

scanned   目标/类别/级别/规则集/引擎/时间/页面
violations 按 impact 排序（critical→…→minor）：规则id、impact、
WCAG 2.1 引用、修复建议(fix.steps+链接)、nodes[](selector/html/summary/failureSummary)、page
axe 无法自动判定项（需人工复核）
summary  total/critical/serious/moderate/minor/unknown + byRule 计数
manualReview 固定人工复核清单（焦点顺序、键盘陷阱、朗读顺序、alt 质量、颜色非唯一通道等 9 项，各带 WCAG 章节）
errors   url-confirmation-required / prerequisite / empty-file / no-html / axe / fs（含 retryable）
rendered 按 out 渲染的 Markdown / 自包含 HTML / 漂亮 JSON

行为要点

- axe 调用链：本机静态服务（127.0.0.1 临时端口，防路径穿越）→
npx --no-install @axe-core/cli  --format json --tags （经 ctx.subprocess，逐页顺序执行）；
- 修复建议：每条违规给常见修法 + axe 规则链接 + WCAG 2.1 quickref 链接（对照
wcag-audit-patterns 思路：给出「2.1 章节链接 + 常见修法」）；
- 人工复核：axe 的 incomplete 结果 + 固定 9 项感知/操作清单（焦点顺序语义、键盘操作等自动化覆盖不了项）；
- URL 确认：未设 confirmUrl: true 时返回 url-confirmation-required 错误且引擎不会运行；
- 前置提示：目标无 HTML（no-html）、文件为空（empty-file）、非 HTML 文件、axe 未装（prerequisite）均有明确中文提示。

CI 示例

.github/workflows/a11y.yml（示意）
- run: npm ci && npm i -D @axe-core/cli
- run: dsh tool run a11y_scan '{"path": "dist", "level": "AA", "out": "html", "reportFile": "reports/a11y.html"}'
- uses: actions/upload-artifact@v4
with: { path: reports/a11y.html }

测试

pnpm typecheck        # tsc --noEmit（src + tests）
pnpm test             # 离线冒烟：本地 fixture 页面 + 录制 axe 结果驱动全管线
pnpm test:live        # 已安装 @axe-core/cli 时，对 fixture 跑真实 axe（未装则跳过）

离线测试覆盖（对照验收标准）：

1. fixture 违规页命中 color-contrast + aria 错误，impact/nodes（selector/失败摘要）字段正确；
2. 按 impact 排序，汇总计数与实际一致；HTML 报告自包含（内嵌 JSON 可往返解析、
无外部资源，assets/report-template.html 与代码内嵌模板逐字节一致）；
3. level/wcag21 切换改变 runOnly 规则集（runOnlyTags 单测 + 引擎收到的标签断言）；
4. URL 无确认被拒（引擎零调用），confirmUrl: true 放行；
5. 全离线可跑（本地静态页面/文件，无浏览器、无网络）。

目录结构

dsh-a11y-scan/
├── cordis.yml                # DSH bundle 挂载层（insert 行）
├── package.json              # dsh.bundle.patch 声明；MIT
├── tsconfig.json / tsconfig.build.json
├── LICENSE / NOTICE          # MIT + axe-core MPL-2.0 声明
├── assets/report-template.html  # 自包含 HTML 报告模板（与内嵌模板保持字节一致）
├── src/
│   ├── index.ts              # 装配：name/inject/apply + 注册 a11y_scan
│   ├── runner.ts             # 目标解析/页面发现/URL 门/静态服务/axe-CLI 引擎/编排
│   ├── report.ts             # 归一化/WCAG 映射/排序/汇总/MD·HTML·JSON 渲染（纯函数）
│   └── tools/a11y-scan.ts    # defineTool + 输出 schema + presentationMeta
└── tests/
├── smoke.e2e.ts          # 离线冒烟 + 可选 live（DSH_A11Y_LIVE=1）
├── support/simulated-engine.ts
└── fixtures/             # 违规页/干净页/空文件/无 HTML 目录/多页项目 + 录制 axe JSON

License

本插件代码 MIT（见 LICENSE）。扫描后端 axe-core 为 MPL-2.0，
不随本包分发，分发义务声明见 NOTICE。扫描流程「自动化 → 人工复核 →
修复建议 → CI」字段模型参考 wshobson/agents accessibility-compliance（MIT），
仅复用流程与字段模型，未复制其源码。

只读声明：本工具不自动修改代码；所有修复建议需人工确认后执行。

权限、失败边界与 DSH STORE 状态

- PERMISSIONS.md：运行时读取面 / 命令面（固定 argv，非 shell）/ 写面 / 外部服务 / 失败边界 / 供应链 / 文件权限信号（无 chmod/chown、644、无 setuid/setgid）。
- docs/store-evidence.md：一次性 Profile 安装 → 启动（工具注册清单）→ 卸载步骤、本地离线证据、待宿主补录真实运行记录说明，并逐项回应 DSH STORE 五类审查信号（仓库 canonical 匹配 / Node 声明 / 供应链 / 文件权限 / 命令权限）。
- STORE 复检由 dsh-safe-plugin-manager 每 3 小时自动执行；本仓库已按清单契约声明（package.json 的 repository / engines.node / dsh.compatibility / dsh.permissions）。