隔离浏览器 machine202502/dsh-browser

dsh-browser

DSH 插件：每个会话一个隔离的 Playwright 浏览器——在编辑器停靠栏里显示实时标签页缩略图，侧边栏里有一个 Browser 分区，按站点配置代理，并为智能体提供 DevTools 级别的工具。16 个工具、33 个 browser_run 命令（包括 list/help 和网络预设）、一个设置表单，以及一套回归测试。

为每个 DSH 会话提供隔离的浏览器：真正的 Chromium（Playwright）、停靠栏里的实时缩略图、侧边栏里的 Browser 分区、站点级代理，以及对 DevTools 的完整访问。

安装

一条命令搞定——它会写入来自 GitHub 的依赖，并启动包管理器：

npx --yes github:machine202502/dsh-browser

然后重启 DSH：侧边栏会出现 Browser 分区，停靠栏里会出现浏览器卡片。

常用选项：

node install.mjs --profile desktop --dry-run # показать, что будет изменено
node install.mjs --home /path/to/.dsh # другой каталог DSH
node install.mjs --uninstall # убрать плагин

Chromium 需要单独安装，playwright-core 不会自动拉取：

npx playwright install chromium

手动安装（如果 pnpm 不可用）——在 ~/.dsh/profiles/desktop/package.json 中：

{
"dependencies": { "dsh-browser": "github:machine202502/dsh-browser" },
"dsh": { "profile": { "bundles": ["…", "dsh-browser"] } }
}

验证：在插件目录中运行 npm test（需要先启动 node tests/qa-page.mjs 页面）。

功能

- 每个智能体有自己的浏览器。 独立进程、独立临时配置档、独立标签页。
子代理拿到自己的浏览器，看不到别人的。
- 上下文。 ctx1、ctx2、……——同一个浏览器内隔离的 Cookie 和 storage，方便在同一个服务器上测试两个客户端。
- 实时画面。 停靠栏里的卡片显示标签页缩略图和虚拟指针；执行操作（open、navigate、click、resize、drag）后，聊天流里会收到一帧画面。
- 侧边栏的 Browser 分区。 按会话分组的已打开浏览器列表：会话名、标签页数量、跳转到会话、关闭单个浏览器。
- 按站点代理。 内置路由代理监听 127.0.0.1:49222：它检查每个连接的主机，只把列表中的站点转发到 Hiddify，其余直连。
Chromium 156 忽略 PAC（无论是 --proxy-pac-url 还是扩展里的 chrome.proxy），所以决策在浏览器之外完成。站点列表和代理地址在重启之间保存在数据目录： %LOCALAPPDATA%\dsh-browser（Windows）、~/.local/share/dsh-browser（Linux）、 ~/Library/Application Support/dsh-browser（macOS）。
- 调试。 网络、控制台、Cookie、storage、IndexedDB、覆盖率、可访问性快照、Lighthouse。

工具

| 工具 | 用途 |
| browser_open | 打开标签页（可以指定 ctx） |
| browser_navigate | 跳转到地址 |
| browser_click | 按 CSS 选择器点击（不会被对话框阻塞） |
| browser_fill | 填写字段 |
| browser_hover / browser_drag | 指针与拖拽（视口内） |
| browser_resize | 视口尺寸 |
| browser_text | 页面文本 |
| browser_tabs | 标签页列表 |
| browser_close | 关闭标签页（最后一个会关掉浏览器） |
| browser_cdp | 直接调用 Chrome DevTools Protocol |
| browser_run | 命令调度器（见下文） |
| browser_proxy_enable / browser_proxy_disable / browser_proxy_status / browser_proxy_list | 代理 |

所有工具都接受 timeout（毫秒）。默认 10–45 秒，视操作而定。

browser_run 命令

browser_run({ command: "list" }) —— 命令目录；{ command: "help", args: { name: "network" } } —— 查看详情。

| 命令 | 作用 |
| console | console. 与页面错误，包括异步错误 |
| network | 请求，含状态码、类型和错误 |
| cookies | get / set / clear |
| storage | localStorage / sessionStorage |
| idb | IndexedDB：数据库、存储、记录 |
| eval | 执行 JS，返回结果 |
| dom | 元素的 html / text / attrs / styles / count |
| snapshot | 无障碍树（角色与名称） |
| keyboard | press、type、down、up |
| dialog | accept / dismiss / 为 prompt 提供文本 |
| emulate | 网络、配色方案、CPU、时区、地理位置 |
| metrics | 页面性能指标 |
| perf | 录制主线程 N 秒：时间花在哪里 |
| slow3g / fast3g / offline / off | 一个词切换网络预设 |
| trace | 录制 Playwright 追踪 |
| coverage | start 与 stop 之间的 JS 覆盖率 |
| downloads | 浏览器下载的文件 |
| lighthouse | 审计：评分、指标、未通过的检查 |
| report | 解析已保存的报告：列表或单条审计 |
| css | 元素命中的规则：选择器、属性、媒体查询、字体 |
| assets | 按类型列出页面资源，download: true 则保存到磁盘 |
| html | 把完整 HTML 文档写入文件 |
| screenshot | 把页面或元素截图写入文件（用 read_image 打开） |
| diff | 两张截图的像素级对比 |
| ws | WebSocket 连接与双向帧 |
| wait | 等待选择器或文本 |
| ctx | 按上下文列出标签页 |
| cdp | 任意协议方法 |

配置

- id: browser
name: 'dsh-browser'
config:
headless: true
bridgePort: 49221
idleTimeoutMs: 900000
viewport: { width: 1280, height: 800 }
proxy:
server: 127.0.0.1:10901
shots:
enabled: true
on: [open, navigate, click, resize, drag]
quality: 55
minIntervalMs: 1500

平台

插件不含平台相关调用：Chromium 按 Playwright 在 Windows、Linux、macOS 上的路径查找（或用 DSH_BROWSER_EXE 指定），进程守护通过 CDP 与浏览器通信，不走 taskkill 或 kill，路径用 node:path 拼接。

Windows %LOCALAPPDATA%\ms-playwright\chromium-/chrome-win64/chrome.exe
Linux ~/.cache/ms-playwright/chromium-/chrome-linux/chrome
macOS ~/Library/Caches/ms-playwright/chromium-/chrome-mac*/Chromium.app/Contents/MacOS/Chromium

架构

- Host（index.js）为每个智能体各持一个管理器，注册工具，并为客户端部分提供 127.0.0.1:49221 桥接。
- 管理器（src/browser-manager.js）通过 launchPersistentContext 在临时配置档中启动 Chromium，浏览器关闭时该配置档会被删除。
- 桥接（src/bridge.js）向客户端提供标签页、帧和代理状态。
- 客户端（client.js）在 Dock 中绘制卡片、在侧边栏绘制分区，并绘制带帧缩略图的工具行视图。
- 代理（src/routing-proxy.js）按桥接中的规则路由连接。

限制

- lighthouse 需要安装对应包；未安装时命令会返回清晰的错误，插件其余部分继续工作。

要求

- Playwright 提供的 Chromium（ms-playwright），路径可通过 DSH_BROWSER_EXE 指定。
- lighthouse 是可选依赖：未安装该包时，lighthouse 命令会返回清晰的错误。
插件其余部分无需它也能工作。

结束进程

浏览器不会比宿主活得更久。除了通过 dispose 正常关闭之外，每个浏览器旁边还会启动一个独立的看门狗（src/watchdog.mjs）：一旦 DSH 进程消失，它就通过 Chromium 自己的 DevTools 端点关闭 Chromium。平台无关——用的是 Node 和 CDP，不用 taskkill。