dsh-plugin-browser-probe

English | 中文

给 DeepSeek Harness(dsh)的视觉验收工具。它跑一个无头浏览器,把三类 UI 检查转成数值,让纯文本 agent 靠读指标验证,而不必"看"页面:

工具	回答的问题	返回
flicker_detect	页面闪不闪?	有多少帧对在变、变多少
visual_diff	我的改动动到了不该动的地方吗?	差异多少、在哪个屏幕分区
contrast_probe	有没有文字太浅看不清?	每个文字元素的 WCAG 对比度、哪些不达标

每个都返回数据而非图片——agent 读数值自己判断。基于 Playwright + pngjs。

运行环境:dsh 0.1.x 开发者预览,接口可能随 dsh 迭代变动。

安装

依赖重(Playwright 会下载浏览器),故独立成一个包。

dsh plugin --profile web add -w dsh-plugin-browser-probe
npx playwright install chromium-headless-shell   # 一次性下载浏览器

在 profile 的 cordis.patch.yml 挂载(用 - insert: 插入新行,不是裸 - id:):

- insert:
    - id: browser-probe
      name: dsh-plugin-browser-probe
      config:
        frames: 10        # flicker:采集帧数,默认 10
        intervalMs: 150   # flicker:帧间隔毫秒,默认 150
        settleMs: 400     # 加载后、截帧前的等待,默认 400

重启 dsh web 生效。dsh --profile web --dump-config 可确认插件行已在。

工具

flicker_detect

采集页面连续帧,量帧间变化的像素比例。判定为 FLICKER 需变化反复出现(≥2 个帧对超阈)——单个变化帧对是一次性的加载过渡,不算闪烁。

参数	说明
url	要检查的页面(file:// 或 http://)。
frames	采集帧数。默认 10。
intervalMs	帧间隔毫秒。默认 150。
settleMs	加载后、首帧前的等待。默认 400。
selector	可选 CSS 选择器;把测量裁到该元素的包围盒——抓小控件闪烁的可靠办法。
region	可选 {x, y, width, height} 矩形;四值 ≤1 为视口分数,否则为像素。

整帧测量能可靠抓到覆盖约 ≥8% 屏面积的闪烁。对小元素闪烁(光标、细线),传 selector 或 region,比例便在该区域内计算。

返回 hotPairs/totalPairs、maxChangedRatio、isFlickering、scope、verdict。

visual_diff

比对两个渲染状态——两个 URL,或两张已存 PNG——报差异有多少以及在哪。整帧切成 8×6 网格,变化的分区以上/中/下 × 左/中/右报出,小改动也能带位置浮现。

参数	说明
a	基准状态:http/file URL,或一张 .png 的路径。
b	对照状态:同上。
settleMs	URL 输入时,加载后截图前的等待。默认 400。

返回 changedRatio、changedZones、changedCells(最严重在前)、dimensionsMatch、verdict。典型用法:留一个已知良好的 URL(或改动前先截一张),改动后 diff 对照,确认只有预期分区变化。

contrast_probe

从 DOM 读每个文字元素的字色与有效背景色,按 WCAG 公式算客观对比度,报哪些文字不达标(AA 正常字需 4.5:1、大字 3:1)。大字按字号/字重识别;半透明前景先按 alpha 混合到背景上。

参数	说明
url	要检查的页面(file:// 或 http://)。
selector	可选 CSS 选择器,把扫描限定在一块区域。省略则全页扫。
standard	AA(默认,4.5/3)或 AAA(7/4.5)。
settleMs	加载后、读样式前的等待。默认 400。

返回 checked(数量)、worstRatio、failures(各含对比度、要求值、实际前景/背景色)、verdict。

命令行

各工具核心也能独立跑,便于快速检查或 CI:

node src/flicker-detect.mjs <url> [frames] [intervalMs] [settleMs] [region:x,y,w,h | sel:CSS]
node src/visual-diff.mjs <a-url-or-png> <b-url-or-png> [settleMs]
node src/contrast-probe.mjs <url> [selector] [AA|AAA]

testpages/ 有可直接指过去的样例页(会闪的页、改动前后一对、分级对比度文字)。

说明

• 零 @deepseek-ai/dsh-* import:dsh 0.1.x-rc 的加载器不为第三方插件解析 host 内部 import,故用 ctx.tools.register 手工构造工具对象注册。
• 截图前不用 networkidle——会轮询的实时应用可能永不 idle;改用固定 settleMs 等待。

License

MIT