前言¶
在 DeepSeek Harness（DSH）的沙箱环境中，直接启动浏览器进程往往受限于管道限制（EPERM/EINVAL），导致插件无法正常输出或通信。同时，常规的视觉验证方案通常需要调用视觉模型或重复审批，增加了延迟与成本。为了解决这两个问题，插件 zaiwenj/dsh-cdp-browser 提供了一种替代方案：通过 CDP 协议操控用户本地已启动的浏览器，利用 Node 内置的 fetch 和 WebSocket 实现零子进程的自动化与像素级检查。
插件简介¶
zaiwenj/dsh-cdp-browser 是一个 DeepSeek Harness 插件，定位为 Zero-spawn CDP 浏览器自动化 + 像素级视觉验证工具。它驱动已经运行的 Chrome 或 Edge 浏览器，不依赖 child_process，也不包含 npm 依赖。由于连接用户启动的浏览器属于网络 I/O，在受限模式下依然可行，且模型无需为每次视觉检查再次获得人工批准。
安装与启用¶
安装该插件需要确保 Node.js 版本在 22.0.0 以上。在终端中执行以下命令将插件添加到 web 配置文件：
dsh plugin --profile web add file:<path>
安装完成后，重启 Web GUI，工具栏中会出现 cdp_* 系列命令。
核心功能与工具¶
插件提供了一套命令集，用于管理连接、页面操作及验证：
- cdp_status：列出 CDP 浏览器的标签页/目标及浏览器版本。
- cdp_open：打开或复用指定 URL 的标签页，并返回目标 ID。
- cdp_eval：在页面上下文中执行 JavaScript，支持
awaitPromise和returnByValue参数。 - cdp_shot：导航到指定 URL 并保存 PNG 截图到绝对路径。
- cdp_assert：结合脚本交互与确定性检查（像素/CSS/DOM/JS），生成通过/失败报告。
典型用法：像素与样式断言¶
cdp_assert 支持多种检查类型。以下是一个示例配置，包含相对坐标像素检查、CSS 属性检查以及 DOM 文本检查：
checks: [
{ type: 'pixel', x: 0.5, y: 0.96, color: '#245edb', tolerance: 16 },
{ type: 'css', selector: '#taskbar', property: 'background-color', equals: 'rgb(36, 94, 219)' },
{ type: 'css', selector: '.xp-window', property: 'border-radius', matches: '^\\d+px' },
{ type: 'dom', selector: '.xp-desk-icon', text: 'My Computer' },
{ type: 'js', expression: 'window.__XP.selfTest()', equals: { ok: true } },
]
上述配置中的 checks 数组每一项都支持 click 参数（如 click: '#start-btn'）或 waitMs，用于在检查前进行交互或等待。
注意事项：确定性与渲染¶
为了保证测试结果的稳定性，需注意以下几点：
- 页面重载：每次测试运行前应重新加载页面。长期存活的标签页会积累状态（如弹窗、菜单状态），可能导致脚本在后续运行中失败。
- 合成点击：
el.click()会触发真实的处理程序。对于开关类控件，需确保只点击一次，避免状态翻转。 - 渐变采样：对渐变背景进行像素检查时，建议在渐变停止点（stops）附近采样，而非混合区域，否则可能因容差设置导致误判。
启动浏览器¶
使用插件前，需手动启动浏览器并开启调试端口。例如，启动 Edge 浏览器：
msedge.exe --remote-debugging-port=9222 --remote-allow-origins=* --user-data-dir=<dir> <url>
完成上述步骤后，DSH 即可通过本地端口与浏览器通信。
结语¶
zaiwenj/dsh-cdp-browser 解决了在沙箱环境中通过子进程启动浏览器的兼容性问题，并提供了无需视觉模型、无需重复审批的视觉验证能力。对于需要高确定性且对本地浏览器环境有控制权的场景，该插件是一个实用的选择。
