共享浏览器面板imroc/dsh-browser-panel

dsh-browser-panel

一个住在 DSH 宿主里的浏览器：每个 DSH 会话都拥有它自己的标签页，AI 用 browser_panel_ 工具驱动自己那一页，而你在 DSH Web UI 的会话页面里看同一个标签页，随时可以接手。

它为一个顽固的问题而生：agent 跑在没有显示器的机器上，而它要用的站点都在登录后面。无头浏览器可以被脚本驱动，但它扫不了二维码、收不了短信验证码、过不了人机校验。有了这个插件，这些环节由你在 DSH Web UI 里完成，而且就在 AI 正在操作的那个标签页上；结果落进持久 profile，所以登录一次，所有会话都能用，重启之后也还在。

要解决的问题

- agent 宿主（容器、虚机、CI 机器）没有 GUI，无法把登录页展示给人看。
- 纯无头自动化会在"需要真人"的第一步卡死：SSO 跳转、一次性验证码、扫码登录、图形验证码、硬件密钥。
- 把 cookie / storageState 搬进容器很脆：设备绑定凭据（DBSC）、指纹、WebAuthn 都搬不过去。

能力

一个浏览器、每个会话一个标签页、两个控制面：AI 在自己那一页上走 CDP，人类在面板里操作同一个标签页；人类登录出来的会话，正是 AI 继续使用的会话——而且因为所有会话共用一个 profile，其余会话也一并处于登录态。

| 能力 | 工具 | 说明 |
|---|---|---|
| 查状态 | browser_panel_status | 是否在运行、本会话标签页的 URL/标题、有没有待人类处理的动作 |
| 打开网址 | browser_panel_navigate | 首次调用即启动浏览器；newTab 用新标签页替换本会话当前页面 |
| 读页面 | browser_panel_snapshot | 标题、URL、带编号的可交互元素清单、可见正文 |
| 点击 | browser_panel_click | 按元素编号或可见文字；派发真实输入事件 |
| 填字段 | browser_panel_type | 兼容 React/Vue 受控输入；submit 顺带回车 |
| 按键 | browser_panel_press | Enter、Tab、Escape、方向键、PageUp/Down 等 |
| 滚动 | browser_panel_scroll | down/up/left/right/top/bottom |
| 看渲染 | browser_panel_screenshot | PNG 以图片附件形式返回给模型 |
| 请人帮忙 | browser_panel_ask_human | 带你的说明打开本会话的面板，并等待人类点「我已完成」 |
| 关标签页 | browser_panel_close | 关闭本会话的标签页；profile（含所有登录态）保留 |

面板侧（DSH Web UI）：

- 会话视图栏里有一个 浏览器 / Browser 标签页，就是这个会话那一页的实时画面；每个会话各看各的；
- 侧边栏的浏览器入口是全局总览：每一行是一个会话的标签页——标题、URL、最近使用时间，该会话在等人时显示「待接管」角标，每行都有「结束并清理」；
- 画布接受真实鼠标、滚轮、键盘与输入法事件——它不是截图查看器，事件会被回灌进 AI 正在用的那个 CDP 会话；
- 接管横幅只出现在发起请求的那个会话的面板里，点「我已完成」即让等待中的工具调用返回（还可以顺手给 AI 留言）；
- 工具栏有后退/前进/刷新/重绘，Tab / ⇧Tab / Enter 三个按钮可以不用鼠标走完一个表单，以及「结束并清理」。

工作原理

flowchart LR
AI["AI 回合（browser_panel_ 工具）"] -->|"CDP · 本会话的标签页"| B["Chrome（持久 profile）"]
H["你，在 DSH Web UI 里"] -->|"鼠标 · 键盘 · 输入法"| P["会话浏览器面板（client 半）"]
P -->|"WebSocket /api/dsh-browser-panel/stream?session=…"| S["宿主半（screencast + 输入回灌）"]
S -->|"Page.startScreencast（被观看的那一页）"| B
S -->|"Page.captureScreenshot（约 7fps，其余标签页）"| B
S -->|"Input.dispatch（该面板自己的标签页）"| B
B -->|"JPEG 帧"| S --> P
B -.->|"同一个 profile：cookies、localStorage"| D[("profile 目录$DSH_HOME/browser-panel/profile")]

- 宿主半为每个 DSH 宿主进程启动一个 Chrome。mode: auto 下若有 Xvfb 就在私有 Xvfb 上跑 headed（指纹比 headless 好），否则自动退回 --headless=new。
- 会话的标签页是懒创建的：该会话第一次调用 browser_panel_ 时，或人类在面板里点「在此会话打开浏览器」时，才开；会话被销毁、AI 调用 browser_panel_close、或人类点「结束并清理」时关闭。会话之间隔离的是页面状态，不是身份：它们共用 profile，所以登录一次到处可用。
- 每个标签页在创建时只激活一次。一个从未被激活过的 Chrome target 会在余生里静默丢弃每一次注入的输入事件，而激活一次即可永久修复；此后即使标签页在后台，注入的输入也照样生效——所以 AI 永远不会抢你的前台。
- Chrome 只为当前活动标签页推流。你正在看的那个面板会发 focus，由它独占真正的 Page.startScreencast；其余已连接的会话由轮询的 Page.captureScreenshot 供帧（目标约 7fps；当别的标签页占着 screencast 时，它的第一帧可能很慢，要几秒）。新打开的面板总会先补种一帧，因为静态页面自己不会产生任何帧。
- 工具不带 session 参数：每个 handler 从自己的执行上下文（exec.agent.id）读会话 id，所以工具名与参数保持简单，会话之间也永远不可能互相操作对方的标签页。没有归属会话的调用直接报错。
- 面板由宿主 webserver 提供，与 Web UI 同源、同一套会话认证（connection.requestRejection）。属于某个会话的路由带上它的 id——GET /api/dsh-browser-panel/state?session=…、POST /open|/close（session 在 body 里）、以及 /stream?session=… 这个 WebSocket upgrade；GET /sessions 与 GET /health 描述整个宿主，POST /human-done 按 request id 结算。不需要额外端口、额外 token 或隧道。
- 人类接管是按会话的：两个会话可以同时等人，请求只会送到它自己那个会话的面板。
- 画面以 JPEG 走一条 WebSocket，输入以小 JSON 消息回传；连接跟不上时丢帧而不是排队。
- 不往 DSH 核心里写任何东西：插件就是组合树里的一行。
- 这些取舍背后的实测约束记在 references/PITFALLS.md（#11–#13）。

环境要求

- DSH >= 0.1.5-rc.2，Node >= 22.19。
- 一个 Chromium 系浏览器。自动探测顺序：browserPath 配置 → PATH 上的 google-chrome-stable / google-chrome / chromium / chromium-browser / chrome → Playwright 缓存（~/.cache/ms-playwright/chromium-/…）→ Puppeteer 缓存。
- 可选：headed 模式需要 PATH 上有 Xvfb；没有就自动用 headless。

安装

版本 0.2.0。这个版本是故意破坏性的：插件原先是整个宿主共用一个页面，0.2.0 之后不再有共享浏览器模式——每个会话都有自己的标签页。0.1.x 是上一个「单页面」版本。

npm
dsh plugin --profile web add dsh-browser-panel

直接从 GitHub
dsh plugin --profile web add github:imroc/dsh-browser-panel

如果你的 registry 还解析到 0.1.x，就显式指定版本（dsh-browser-panel@0.2.0）或直接从 GitHub 装。

包里带的是已构建好的 JavaScript，安装时不需要编译。

装完需要重启 Web UI（新增插件行属于启动期组合变更）：

systemctl --user restart dsh-web      # 或你启动 dsh web 的方式

验证

1. 打开 DSH Web UI，会话视图栏里出现 浏览器 / Browser 标签页，点它；侧边栏也会多一个浏览器入口，里面列出所有会话的标签页。
2. 标签页会告诉你会话还没打开浏览器，并给一个打开按钮；浏览器按需启动（调用任意 browser_panel_ 工具同样会启动），第一帧就是宿主 Chrome 里本会话自己那一页。
3. 在对话里让 AI 打开一个网址，页面会出现在同一个标签页里：

用 browser_panel_navigate 打开 https://example.com，然后 browser_panel_snapshot。

4. 让 AI 把控制权交给你，然后你自己在面板里完成登录：

调用 browser_panel_ask_human，说明写「请在面板里完成登录，然后点我已完成」。

5. 登录完成点 我已完成 —— 工具调用返回，AI 带着已登录的会话继续往下做。
6. 再开一个会话，打开它自己的浏览器标签页：那是另一个标签页，但已经处于登录态，因为 profile 是共享的。关掉某个会话的标签页（browser_panel_close，或点「结束并清理」）再打开：仍然是登录态。

配置

在你自己的 patch 层里覆盖任意字段（~/.dsh/cordis.patch.yml 或 profile 的 cordis.patch.yml）。config 是整键替换，需要什么就写全：

- id: browser-panel
config:
mode: headless            # auto | headed | headless
viewport: 1280x800
idleShutdownMinutes: 30

| 字段 | 默认 | 含义 |
|---|---|---|
| browserPath | '' | 显式指定 Chrome/Chromium 路径；空 = 自动探测。 |
| profileDir | '' | 持久 profile；空 = $DSH_HOME/browser-panel/profile。所有会话共用。 |
| mode | auto | auto = 有 Xvfb 时 headed，否则 headless。 |
| screen | 1440x900x24 | 私有 Xvfb 的分辨率。 |
| windowSize | 1440x900 | headed 模式的窗口尺寸。 |
| viewport | 1440x900 | 模拟的页面视口，所有会话标签页一致，也是面板画布的坐标空间。 |
| xvfbDisplay | :99 | 首选 X display；被占用则顺延。 |
| port | 0 | 固定 DevTools 端口；0 表示自动挑空闲端口。 |
| startUrl | about:blank | 每个会话新标签页的首个地址。 |
| extraArgs | [] | 额外的 Chrome 启动参数。 |
| snapshotMaxChars | 4000 | 每次快照的正文预算。 |
| maxElements | 80 | 每次快照列出的可交互元素上限。 |
| screencastQuality | 60 | 推流 JPEG 质量（轮询快照同样用它）。 |
| screencastMaxWidth | 1440 | 推流画面的最大宽度。 |
| pollFrameMs | 140 | 拿不到前台 screencast 的面板用轮询供帧的间隔（约 7fps）；小于 60 会被夹到 60。 |
| askHumanTimeoutSeconds | 600 | browser_panel_ask_human 的默认等待预算。 |
| idleShutdownMinutes | 0 | 空闲多久后关闭浏览器（连同所有会话的标签页）；0 表示从不关。 |
| autoStart | false | 随宿主启动浏览器，而不是等第一次调用。 |
| startTimeoutMs | 20000 | 启动后等待 DevTools 端点的上限。 |

安全须知

- 面板及其 WebSocket 与 DSH Web UI 同一套认证。能看到面板的人，本来就能操作宿主浏览器——请按这个标准看待 Web UI 的访问控制。
- 会话之间隔离的是页面状态，不是身份：所有会话共用同一个浏览器 profile，也就共用同一批 cookie 与登录态。这正是插件的意义所在，但同时也意味着某个会话的 AI 能够访问 profile 已登录的任何站点。
- profile 里是真实会话。它只留在宿主上（DSH home 目录下），不会上传，也不在 Git 仓库里。
- 浏览器流量从容器出去。数据中心 IP 比你的笔记本更"像机器人"；对付严格的站点，mode: headed（有 Xvfb 时的默认值）是这点上更划算的一半。
- 尽量用非 root 用户跑 Chrome 并保留沙箱；插件只在宿主进程是 root 时才自动补 --no-sandbox。

回退

dsh plugin --profile web remove dsh-browser-panel   # 或直接从 cordis.patch.yml 删掉那一行

然后重启 Web UI。profile 目录会保留，所以重装后登录态还在；想彻底忘掉就删 $DSH_HOME/browser-panel/profile。

License

MIT