前言¶
DeepSeek Harness (DSH) 的插件化架构允许开发者扩展 Web GUI 的能力。在调试浏览器自动化或远程运行 Chromium 时，开发者需要一个可视化的窗口来观察页面状态并进行交互。dsh-cdp-live-view 插件在 DSH 的侧边栏中注册了一个「CDP 实时视图」标签页，通过 Chrome DevTools Protocol (CDP) 将远程页面的像素流（JPEG）实时渲染到画布上，并提供受控的输入交互功能。
核心功能¶
该插件提供以下核心能力：
- 侧边栏实时视图：在 DSH Web GUI 的侧边栏注册标签页，将远程页面渲染为实时的 JPEG 像素流，支持 contain-fit 缩放和设备像素比适配。
- 目标管理：自动列出并切换页面目标（Targets），支持创建新页面和关闭现有页面。
- 地址栏导航：支持在地址栏输入 URL 并回车，提供前进、后退和刷新按钮。
- 受控交互：支持鼠标点击、拖拽、滚轮以及键盘输入。输入通过严格的白名单协议（基于 zod discriminated union）发送，确保安全性。
- 双重控制门控：交互功能受「交互输入」总开关和标题栏「键盘与鼠标控制」复选框的双重控制，只有两者同时开启，视图才会进入交互模式。
- 设置面板：支持配置 CDP 地址，并调整截图质量、帧率、最大宽高等参数。
安装与启用¶
使用该插件前，请确保环境满足以下条件：
* DSH 主进程运行在 Node.js ≥ 20 上。
* 已安装并启动支持 CDP 的 Chromium（例如 --remote-debugging-port=9222）。
* 已安装 dsh-better-sidebar 插件（本插件依赖它）。
安装命令如下：
dsh plugin --profile web add dsh-better-sidebar dsh-sidebar-cdp-browser
安装完成后，必须重启 dsh web 进程以加载插件。
配置与使用¶
插件安装并重启后，在 DSH Web GUI 的侧边栏中会出现「CDP 实时视图」标签页。
配置 CDP 地址¶
CDP 地址不在 profile 数组中配置，而是在 Web UI 的设置中配置：
1. 打开 设置 → 侧边栏卡片 → 侧边栏内容 → CDP实时视图。
2. 点击该卡片右上角的齿轮图标。
3. 填入 CDP 地址。留空则默认为 127.0.0.1:9222。
4. 支持格式包括 host:port、http://host:port、ws://.../devtools/browser/... 等。
5. 保存后，主进程会断开旧连接并尝试自动重连。
启用交互控制¶
要在视图中操作鼠标或键盘，需要同时满足两个条件：
1. 在设置面板中开启「交互输入」总开关。
2. 在实时视图的标题栏中勾选「键盘与鼠标控制」复选框。
适用场景与注意¶
适用场景¶
- 远程/无头 Chromium 可视化：在服务器或容器中运行浏览器，通过 DSH 界面查看和操作。
- 观察自动化过程：在 DSH 会话中实时监控智能体驱动的浏览器行为。
- 轻量级 VNC 替代品：无需安装额外客户端的远程桌面方案。
- 演示与调试：将浏览器会话投影给多人，或进行受限的演示。
注意事项¶
- 安全模型：目标页面永远不会以 iframe 形式嵌入。CDP 连接由 DSH 主进程独占拥有，浏览器端无法得知 CDP 地址，因此不存在任意 CDP 透传漏洞。
- 构建依赖：如果使用 pnpm 构建或安装插件时遇到原生依赖（如
node-pty）被阻止，请在 profile 的pnpm-workspace.yaml中添加对应的包名到allowBuilds。 - 当前限制：目前尚不支持复制（Copy/Ctrl+C）功能。
- 配置位置：CDP 地址配置存储在 better-sidebar 的偏好设置中，而非 DSH profile 数组。
总结¶
dsh-cdp-live-view 插件为 DSH 提供了一个安全、低延迟的浏览器可视化方案，特别适合需要在 Web 界面深度调试浏览器自动化或远程监控场景。其严格的权限控制和即插即用的特性，使其成为 DSH 生态中的实用工具。
