前言¶

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 視覺）、內容與信息架構、真實性能採樣。這些內容在報告中顯式列爲“未覆蓋”。