前言¶

DeepSeek Harness（DSH）的插件生态中，从 0 到 1 的设计生成与从截图到 UI 还原已有成熟方案。但在“发现问题 → 给出修复 → 证明修复”的审查与优化闭环上，目前存在空白。dsh-design-audit 插件填补这一缺口，它聚焦于可测量的客观判据，提供无头 Chrome 取证、确定性规则校验、可粘贴 CSS 修复以及复测差值验证的一整套流程。

核心设计¶

插件将“测量”与“判据”分离。collect.js 负责几何计算、样式采集等客观证据的获取；checks.js 负责应用 WCAG 2.2、平台指南等确定性阈值进行分级判定。工具不越界假扮视觉评审官，而是将客观证据与截图路径摆好，将审美判断留给人工复核。

工具与能力¶

插件提供三个核心命令，构成完整的审查闭环。

1. 无头 Chrome 取证：使用无头 Chrome 打开 URL 或本地 HTML，支持多视口整页截图。产物落盘于 <工作区>/.design-audit/<时间戳>/。
2. 确定性判据与报告：运行 design_review，依据 WCAG 2.2 和平台指南生成分级问题清单，输出逐元素的 CSS 修复建议。支持生成 HTML 或 Markdown 报告，包含首屏图内嵌可读与整页长图链接存档。
3. CSS 修复与复测：使用 design_fix 生成可粘贴的 CSS 补丁，支持自动备份原文件。通过 design_review compare=<before 目录> 进行复测，输出差值验证结果。

检测范围¶

插件覆盖以下可测量判据：

• 无障碍：对比度、焦点可见、目标尺寸（44×44px）、可访问名称、图片替代文本（alt）、表单标签、页面语言、标题层级、地标区域。
• 排版：字号下限、行高（1.4.12）、行长、字号/字族阶梯。
• 布局与交互：横向溢出、间距基准网格、色彩数量、图片尺寸预留（CLS）。
• 动效检测：
  • CSS 动效兜底：检测 animation/transition 是否有 prefers-reduced-motion: reduce 兜底。
  • JS 驱动动效：检测 GSAP、WAAPI、rAF 等在 prefers-reduced-motion: reduce 下仍在动的元素。由于 JS 写的内联样式不受 CSS animation-duration: 0.01ms 控制，修复建议直接给出 JS 侧的 matchMedia 或 gsap.matchMedia() 写法。
• 遮挡检测：采用中心点命中测试。若元素部分遮挡但中心可点，则不报错（保守取值，避免误报）。

典型用法¶

执行审查闭环的典型步骤如下：

# 1. 截取证
design_capture target=... label=before

# 2. 生成报告与问题清单
design_review

# 3. 视觉复核（人工使用 read_image 或直接看报告中的首屏图）
read_image <首屏截图>

# 4. 生成并应用 CSS 补丁（会自动备份原文件）
design_fix apply=true cssFile=styles.css

# 5. 再次取证
design_capture label=after

# 6. 对比修复前后的差值
design_review compare=<before 目录>

安装¶

安装命令如下：

dsh plugin --profile web add dsh-design-audit

本插件为 bundle 形态，依赖 DSH 版本 >= 0.1.0-rc.6。开发期可使用 dev_inject_plugin 注入源码。

注意事项¶

• 依赖环境：依赖本机 Chrome 或 Edge（可通过环境变量 DSH_DESIGN_BROWSER 覆盖）。使用 Node 内置模块与全局 WebSocket，零 npm 依赖，要求 Node ≥ 22。
• SPA 支持：对于单页应用（SPA），需传 waitFor 参数指定标志性选择器。若元素数量小于 20，会告警“可能只抓到空壳”。
• 动效采样：动效检测需要跨时间采样（每视口约 250ms，两视口约 0.5s）。若动画时长短于采样窗且不重复，可能无法被检测到。
• 无头 Chrome 偏好：无头 Chrome 默认开启 prefers-reduced-motion: reduce。因此，“观察到在动”等同于“该元素无视了 reduce 偏好”，这正是要找的违规。
• 构建缓存：若被审项目采用“哈希名 + 运行中进程缓存构建清单”的打包方式（如 Flask 的 dist_url），修改 CSS 或 JS 后必须重启其服务，否则复测会显示修复为 0。
• 不可覆盖内容：插件不覆盖审美判断、交互态视觉（hover/focus 视觉）、内容与信息架构、真实性能采样。这些内容在报告中显式列为“未覆盖”。