浏览器实况面板 shittass/dsh-gui-browser

dsh-gui-browser

在 GUI 右侧边栏里，实时查看并操作会话内置的 Chromium —— 就是模型那套 mcp__playwright-mcp__ 工具驱动的同一个浏览器。

环境要求

- DSH 0.2.0-rc.2 或更高的 0.2.x。 声明了两处 —— engines.dsh 和 @deepseek-ai/dsh- 的 peer 依赖 —— 所以插件管理器在旧运行时上会拒绝安装，启动时也会拒绝这一行，而不是装到一半才失败；dsh plugin allow-version 是刻意为之的按版本覆盖开关。
- Node ^22.19 || >=24。
- 基于 @deepseek-ai/dsh-base 和 @deepseek-ai/dsh-web-app 构建的配置档：这个面板是 Web 右侧边栏的一个标签页。
- 一套 browser-use 包。 本包自身不带浏览器。它依赖服务商包（@deepseek-ai/dsh-browser-use 和 @deepseek-ai/dsh-experimental-browser-use-playwright-mcp），好让服务商行能解析出来；它的补丁覆盖了 Playwright MCP 服务商那一行，把它指向启动器 —— 但行本身，以及它们背后隔离的无头 Chromium，都来自更早一层启用的 browser-use 包（本仓库的兄弟包 dsh-browser-use-playwright 正是这两行）。一个配置档同时只允许一个服务商：@deepseek-ai/dsh-browser-use 占着唯一的注册位，会拒绝第二个，所以千万别同时启用两个。一个都没有的话，面板会停在空闲状态并说明原因。

安装

dsh plugin --profile <profile> add dsh-gui-browser
dsh --profile <profile> --dump-config # the layer is listed as dsh-gui-browser

本包的 postinstall（launcher/install.mjs）会把平台启动器放进注册表目录；见启动器。pnpm ≥10 在获得许可前不会跑任何依赖生命周期脚本，所以安装会报告有一个待执行的构建脚本，插件管理器会来问你 —— 批准它，因为少了这一步，服务商就没有 launcher.sh/launcher.exe 可启动。这一步是幂等的，也绝不会让安装失败：在没有 C# 编译器的机器上，它会大声警告并让 Windows 启动器缺席，而不是把包弄坏。

dsh plugin --profile <profile> remove dsh-gui-browser 会移除依赖及其层。

装进正在运行的 Harness 需要重启。 插件管理器会尝试通过 HMR 激活新装的包，但 Host 只从启动时构建的包表里解析插件说明符：没见过的包名会报 failed to import，只有重启后才会挂载（实测过 —— 同一进程能导入启动前就存在的名字，而全新启动算出的解析结果指向正确目录）。之后面板会自己出现，它镜像的浏览器也能跨重启继续运行，因为浏览器的调试端口记在注册表目录里，而不是由插件持有。就地替换包也有同样的要求。
从检出发布时，npm pack 会构建 tarball；其内容恰好是 package.json 里的 files —— 源码、启动器的 .cs/.mjs/.sh，绝不包含编译后的二进制文件。

它做什么

- 与模型看到的像素完全一致。 Host 部分连接到 Chromium 启动时所用的浏览器（--remote-debugging-port，由 wrapper.sh 添加），并推送页面目标的 Page.startScreencast 帧。不会重新渲染、重新布局或调整大小：视口、页面状态和焦点都保持浏览器原有的样子。只有一处会被修正：Chromium 自行创建的页面（浏览器最后一个页面关闭后打开的新标签页，或网站打开的弹窗）出生时是 Chromium 未设定尺寸的 800x600 默认值，比大多数页面都窄，到达时已被裁剪，因此任何仍恰好是这个尺寸的页面都会被设为浏览器自身的视口（1280x720）。其他任何尺寸——模型自己调整的大小、网站弹窗的尺寸——都保持不动。
- 只在有人观看时产生帧。 编码一帧是这里最昂贵的操作，因此帧的产生跟随需求：有观看者连接时开始，最后一个观看者断开时停止，观看者表示其窗口隐藏时再次停止。隐藏的面板完全不会收到任何帧。
- 一次只显示一个页面。 有多个标签页的浏览器会绘制所有标签页；全部投屏正是曾经让面板在标签页之间来回切换的原因。只有显示的页面会被投屏，并且它遵循浏览器的行为：出现并落定的页面——包括出生为 about:blank、稍后才命名的页面——会取得视图，而从页面菜单手动选择的页面会保持视图，直到另一个页面出现或该页面关闭。
- Chrome 的界面元素。 标签页位于工具栏上方的条带中，最旧的在最左边，每个都有自己的 ✕，+ 会打开新标签页并把光标放进地址栏；条带可用滚轮横向滚动。地址栏显示当前显示页面的 URL，可以输入——带 scheme 的按原样处理，裸主机名会补上 https://，其他任何内容都会变成 Bing 搜索，与 Chrome 做出的同样三种猜测一致。面板对页面所做的一切都会报告给模型；⋮ 菜单里的帧质量行是观看者自己的偏好，不会报告。
- 后退和前进的含义与浏览器中一致。 当显示的页面有自己的历史记录时，它们在页面内部前进后退，否则在观看者曾被展示过的页面之间切换：由链接打开的标签页只有恰好一条历史记录（在 bilibili 上测得：index=0/0），因此那里的后退会恢复点击链接时所来自的页面，而不是什么都不做。面板获得焦点时，Alt+Left 和 Alt+Right 是同样的两个操作，工具栏会将不会产生任何效果的方向变暗。
- 帧会缩放到面板，而不是页面。 投屏帧始终是整个页面，因此每个观看者都会告诉 Host 多少设备像素它的窗格按以下方式绘制页面（fit 模式：适配后的尺寸；1:1：按显示器密度绘制页面，上限为页面自身的像素）。最宽的窗格胜出，因为画面可以缩小，却永远无法再放大；当宽度不再匹配时，cast 会重启——防抖 200 ms，所以拖动调整窗格大小时，每次停顿只触发一次重启。因此，窗格永远不会收到它又要缩放掉的像素：在 1280x720 的页面上滚动实测，按 160x90 而非全尺寸 cast，同一个浏览器从 1.69 核 / 81 Mbit/s 降到 0.76 / 1.2；而完全不报告尺寸的窗格，仍然拿到整页。
- 低延迟，而非高帧率。 帧是推送的，从不轮询；每个查看端在帧到达时确认，并在确认之后解码，于是 Host 在上一帧还在解码时就编码下一帧，不必等绘制完成——两项开销不再叠加。最多只可能有一帧在等待，所以落后的查看端会丢帧，而不是堆积队列。实测页面变化 → 查看端绘制，本地约 20 ms。
- 真实交互。 鼠标（移动、拖动、点击、右键/中键点击、滚轮）和键盘以 CDP 输入事件进入页面。输入经由一个不可见的可编辑表面，所以客户端的输入法（微软拼音、日文、死键、表情面板）在本地组合，提交的文本再插入上游，完全就是远程桌面客户端处理输入法的方式——包括提交候选词的那个按键，页面绝不能也收到它。Host 测量页面真实的光标位置并发布出来，于是平台的候选窗口出现在正在输入的字段上方。Ctrl+C 还会把页面选中的内容复制到客户端剪贴板。
- 上报给模型。 查看端的操作被合并成一份最小记录（点击、type"..."、按键、滚动、导航），再补充页面的 URL、标题和聚焦元素，作为一行运行时上下文，贡献给该 Session 的下一次模型步骤。

路由

仅限回环调用方。

| 路由 | 含义 |
| GET /gui-browser/list | 每个活动浏览器的状态 |
| GET /gui-browser/status?port= | 某个浏览器的状态 |
| GET /gui-browser/frame.jpg?port= | 最新一帧的静态图像 |
| GET /gui-browser/activity?session= | 模型将收到的确切文本 |
| GET /gui-browser/stream?port= | 给非 WebSocket 查看端的 MJPEG 回退 |
| POST /gui-browser/input?port=&session= | 与 socket 相同的命令 |
| WS /gui-browser/ws | 下行：帧和状态；上行：输入、光标、页面选择、帧质量、窗格可见性 |

文件

- host.js — 稳定入口；导入 engine.js?rev=<mtime>，这样 Host 进程的模块缓存不会在整个进程生命周期内钉住旧的一代。
- engine.js — 注册表监视器、CDP 管道、WebSocket 传输、输入
- client.js —— gui-browser 右侧边栏标签页：画布视图、socket、指针/键盘/输入法处理、缩放、自动打开。
- wrapper.sh —— POSIX 版 Chromium 启动器：每次启动分配一个空闲调试端口，并发布到 ~/.dsh/run/gui-browser/ 下。
- launcher/launcher.cs、launcher/install.mjs —— Windows 版同一启动器，以及把任一启动器放到位的安装步骤。

启动器

Playwright 通过服务商的 executablePath 指向启动器，因为这是 bundle 唯一能在 Playwright 自己的控制通道旁边加上 --remote-debugging-port 的钩子。补丁把它命名为 dshHomePath('run', 'gui-browser', 'launcher.exe' | 'launcher.sh')，这样它永远不必知道包安装在哪里，而 bundle 的 postinstall（launcher/install.mjs）会把对应平台的启动器放进那个目录：

- POSIX：把 wrapper.sh 复制为 launcher.sh，权限 755。
- Windows：用每个 .NET Framework 安装都提供的 csc.exe 把 launcher.cs 编译成 launcher.exe，失败时回退到 PowerShell 的 Add-Type。包里不带任何预编译产物，所以没有东西需要签名，也不需要按架构构建；机器上没有 C# 编译器会大声报错，除此之外忽略，模型照样有浏览器可用。

Windows 启动器有两点至关重要。Playwright 启动 executablePath 时不带 shell，所以 .cmd 完全不能用（spawn EINVAL）；而且它把浏览器的 DevTools 管道作为 CRT 文件描述符 3 和 4 传给浏览器，Windows 通过 STARTUPINFO.lpReserved2 传递它们——这是一张按进程划分的描述符表，子进程的 CRT 在启动时读取。因此启动器自己调用 CreateProcess，原样转发那个块，并把它命名的句柄标记为可继承；Process.Start 会丢掉这个块，Chromium 会拒绝启动，报 "Remote debugging pipe file descriptors are not open"。launcher.exe --gui-browser-handles 会打印继承来的表，用来区分这种失败和浏览器本身损坏。

限制

- Ctrl+wheel（页面缩放）不转发：它会让面板的几何尺寸与浏览器视口失步。
- 显示这个 GUI 自身的浏览器是只读的，所以嵌套面板无法永远转发自己的点击。
- 查看器的剪贴板在粘贴时到达页面，页面的选区在 Ctrl+C 时到达查看器；更丰富的剪贴板类型不做桥接。
- 默认不动 Chromium 的帧节奏。这里实测：默认 60 Hz 帧时钟给出 60 fps 重绘、59.3 fps 捕获、60 fps 投递，无丢帧——瓶颈不在流水线，而在帧时钟。--disable-frame-rate-limit --disable-gpu-vsync 把捕获提高到约 114 fps，但会把 requestAnimationFrame 推到约 3240 Hz，对模型而言每个动画的时序都变了。要在下次启动时启用，创建一个文件，名为注册表目录（~/.dsh/run/gui-browser/）里的 uncapped；删掉它就能恢复。页面需要重启，所以浏览器当前打开的标签页会丢失。

无损帧由每个观看者自行选择，默认关闭，因为它会牺牲这个窗格存在的意义——帧率。在 1280x720 下，用 bilibili 滚动并重绘时，从浏览器自己的进程树测得：

| 编码 | 帧/秒 | KB/帧 | Mbit/s | 核心数 |
| JPEG 88（默认） | 55.1 | 184 | 83 | 1.17 |
| JPEG 100 | 52.3 | 485 | 208 | 1.75 |
| PNG（无损） | 17.5 | 768 | 110 | 1.84 |

静态页面在两种模式下都不产生任何帧，而模型自己的截图是另一套按需捕获：同一时刻，该页面的全质量截图测得 JPEG 为 203 KB、PNG 为 654 KB，所以镜像的编码从不影响模型看到的内容。这些数字对应的是全尺寸投屏；由于投屏现在跟随窗格，窄窗格下无损的代价远低于表格所示——用同样方式测得，160x90 的屏幕共享在 2 KB 一帧、1.2 Mbit/s 下保持了 60 fps。