CDP 浏览器控制 zaiwenJ/dsh-cdp-browser

dsh-cdp-browser

零进程启动的浏览器自动化 + 像素级视觉验证，作为 DeepSeek Harness 插件。仅使用 Node 内置模块，通过 CDP 驱动已在运行的 Chrome/Edge：全局 fetch + 全局 WebSocket（Node ≥ 22）+ zlib PNG 解码。无需 child_process，无 npm 依赖，无需每次使用审批。

为什么零进程启动

那些启动引擎并通过管道传输其 stdio 的插件（例如 modlens）在每次调用时都会与 harness 沙箱的管道禁令（EPERM/EINVAL）冲突。连接到用户自己启动的浏览器是普通的网络 I/O —— 在受限模式下是允许的。唯一的手动步骤（启动浏览器）发生在 harness 之外，因此模型在进行视觉检查时再也不需要审批。

设置（一次性）

1. 安装到配置文件中（通过 dsh plugin --profile web add file: 完成）。
2. 使用 CDP 启动浏览器（提供的 edge-debug.cmd 可完成此操作）：

msedge.exe --remote-debugging-port=9222 --remote-allow-origins=* --user-data-dir=

3. 重启 Web GUI。cdp_* 工具会在下一个会话中出现。

工具

| 工具 | 功能 |
| cdp_status | 列出 CDP 浏览器的标签页/目标 + 浏览器版本 |
| cdp_open | 为某个 url 打开（或复用）一个标签页；返回目标 id |
| cdp_eval | 在页面中执行 JS（awaitPromise、returnByValue） |
| cdp_shot | 导航 + PNG 截图，保存到绝对路径 |
| cdp_assert | 脚本化交互 + 确定性检查（pixel / css / dom / js），并生成通过/失败报告 |

cdp_assert 检查形态

checks: [
{ type: 'pixel', x: 0.5, y: 0.96, color: '#245edb', tolerance: 16 }, // 相对坐标 0..1 或绝对像素 { 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 } }, ] // 每个检查都接受 click: '#start-btn' | { selector } | { x, y } 和 waitMs

开发

node plugins/dsh-cdp-browser/test/e2e.mjs # 需要开发服务器 + CDP Edge，不启动任何东西

确定性注意事项（从 XP 应用的第一个插件 e2e 中学到）：

- 每次测试运行都重新加载页面。 长期存在的标签页会在脚本化扫描（窗口、对话框、菜单）中累积状态，并可能卡住 openApp；每个测试套件使用全新的 navigate + skipBoot 是确定性的。当某个应用出现回归时，probe-apps.mjs 会逐个二分定位每个应用的挂起问题。
- 合成点击会切换状态。 el.click() 会运行真实的事件处理器 —— 点击一个切换开关两次会翻转两次。每个断言只点击一次。
- 渐变表面需要感知色标的采样。 在某个渐变色标占主导的位置（平坦区域或边缘）采样，而不是在渐变中间混合处采样，或者针对计算样式值使用感知容差的 nearColor。

该包暴露了 ./cdp（targets、openTarget、withPage、Cdp， decodePng、samplePixel、nearColor、runChecks、savePng）以便在测试框架之外复用