可视化浏览器 RestRegular/dsh-visual-browser

dsh-visual-browser

一个 DeepSeek Harness 插件，给智能体一个真正的 Chrome，也给你一个实时窗口——就在右侧边栏里，紧挨着内置的 Browser 条目下方，作为一个标签页。

- 智能体从不读 DOM。它读的是一份编号列表，列出可见的交互元素，外加一小段文本摘录——每页几百个 token，而不是整份 DOM 快照。
- 标签页直接串流 Chrome 自己的投屏（CDP Page.startScreencast），以带长度前缀的 JPEG 流传输，在主线程之外解码到 canvas。不轮询截图，不逐帧发请求，不逐帧重绘面板。
- 你的指针、滚轮和键盘输入直接进入 DevTools 输入域，按动画帧批量发送：点击、拖拽、滚动、输入都是正常延迟，而不是「事后截图」的延迟。
- 每个操作——智能体的和你的——都记进一份可折叠、可滚动的操作日志，高度可以拖动调整。只记录：没有回放；日志变长时点清除按钮清空。
- 智能体操作时，面板会把操作画出来：一层带色调的锁定遮罩盖住画面（那一刻浏览器被锁定），一个模拟指针移向目标，点击处泛起水波纹，滚动时出现大箭头沿方向淡入，拖拽时指针换成握拳，按键时出现键帽。画出的光标、波纹和操作图形都随窗格缩放，和画面里其他东西一样。
- Cookie 跨重启保留（一个专用 Chrome 配置档），所以智能体登录一次，之后一直有效。
- 不属于页面内容的本机控件，填真值而不是造假：文件选择器收到真实路径，日期 / 时间 / 月 / 周 / 颜色 / 范围输入拿到真实值，所以它们的系统对话框和浏览器弹窗永远不会卡住无头会话。

安装

dsh plugin add @restregular/dsh-visual-browser

或者在 Harness 界面里：Plugins → Add → @restregular/dsh-visual-browser。

要求：机器上装有 Google Chrome、Microsoft Edge 或 Chromium（自动检测），以及 Node.js 22 或更新版本（插件不带运行时依赖；它通过内置 WebSocket 与 CDP 通信）。

使用

1. 打开右侧边栏。内置的浏览器 / Browser 卡片下方就是 Visual Browser 一行——点它，或者点浏览器卡片本身，再点它下面多出来的那一行。标签页打开，替换掉该窗格里的引导内容。
2. 让智能体做点需要网站的事，比如 「打开 example.com 看看首页写了什么」。智能体调用 browser_open。
3. 看画面。直接在里面点击、拖拽、滚轮、输入；工具栏有后退 / 前进 / 刷新 / 新建页面 / 停止，地址栏可以打开任意 URL。一旦有多个页面，工具栏下方会出现标签条：＋ 新建页面，点标签切换，点 × 关闭（最后一个页面保留）。每个页面都是真正的 Chrome 标签页，有自己的历史；只有当前一个流式传输并接收输入。画面上原生指针隐藏，由面板绘制光标，所以你看到的是页面自身的位置；拖拽可以选中文本、拖动滑块、平移真实滚动条（浏览器保留自己的滚动条）。

底部的操作日志记录智能体的动作和你的动作。点击它的标题栏可以折叠，列表超出面板时可以滚动。垃圾桶按钮清空整个日志。拖动日志上方的把手可以选择它占多大空间（画面保留最小预留）；双击把手恢复默认，或聚焦后使用 ↑ / ↓（Shift 加大步长，Home / End 到两端）。选定的高度按浏览器分别记住。

观察智能体操作

工具开始动作时，面板在输入发出之前收到提示（帧流旁边一条小的 NDJSON 流）。它升起带色遮罩，把自己的指针移到目标上，然后才确认——真正的点击发生在绘制的指针到达时。同一条通道还驱动：

| 操作 | 画面显示 |
| click / hover | 指针移动，然后水波纹点击 |
| upload | 同样的指针移动到控件，然后填入文件选择器 |
| scroll | 大箭头沿滚动方向漂移并淡出 |
| drag | 从按下点到落点的一只握拳手，然后释放 |
| type | 指针移动到输入框，并显示输入徽标 |
| key / select | 一个键帽，显示键名或选项 |
| open、back、forward、reload | 遮罩和操作标签，直到页面就绪 |

遮罩拦截画面的指针、滚轮、键盘、地址栏和页面标签，所以用户手势无法与智能体抢跑；操作结束时它自行升起。每个绘制元素都随显示的画面对齐缩放，所以无论侧边栏窄还是宽，面板看起来都正常。prefers-reduced-motion 会缩短动画，但不会移除锁定。

页面打开的标签

带 target="_blank" 的链接或按钮（或 window.open）不会被晾在一边：宿主监听新的页面目标，挂接它们，并且——当标签是在输入手势期间打开时——把面板切换到它，位置与 Chrome 放置的完全一致。新页面在标签条上显示为一个标签块，保留自己的历史，关闭原来的打开者后它仍然存活。同标签导航也会跟随；始终加载不完的页面只会让动作等待一段有限的宽限期，而不会冻结会话。

深色模式

面板只使用 --dsw-alias-* 主题 token 处理表面、文本、边框、悬停和聚焦，所以浅色和深色（以及主题切换）无需额外规则。包中唯一的字面颜色是 --dsw-alias-label-primary-foreground 之后的 #fff 回退值。

智能体获得的工具

| 工具 | 用途 |
| browser_open | 打开 URL（首次使用时启动 Chrome）并返回带编号的视图。 |
| browser_see | 重新生成当前页面的带编号视图。 |
| browser_act | click / upload / drag / type / key / hover / scroll / select / back / forward / reload / wait / close，然后返回新视图。 |
| browser_text | 读取页面或某个元素的文本（链接还会返回它的 href）。 |
| browser_screenshot | 把 PNG/JPEG 存到磁盘并返回路径（可交给 read_image 使用）。 |

原生控件：不属于页面内容的部分

有些控件由浏览器或操作系统绘制，所以永远不会出现在截图里，CDP 输入也到不了它们。插件直接写入值，而不是假装点击：

| 控件 | 行为 |
| 文件选择器（、任何「上传」按钮） | 用 upload 加 files: ['/abs/a.png'] 拦截选择器，把真实路径交给浏览器——页面收到的事件，和人工选文件产生的 change 事件完全一样。如果普通 click 想要文件，会报告 that click opened a file chooser，而不是让操作系统对话框挡在无头浏览器前面。 |
| 只用来隐藏 的控件 | 文件直接写入 input，无需点击。 |
| input type=date / time / month / week / datetime-local | type 直接写入值（2026/10/6 → 2026-10-06），所以完全不需要日历弹窗。 |
| input type=color | type 接受 #1a2，写入 #11aa22。 |
| input type=range | type 写入数字，按 min/max 截断，并对齐到 step；drag 也照常可用。 |
| | select 写入选项，并触发 input + change。 |

智能体看到的内容

URL: https://example.com/login
TITLE: 登录 - Example VIEW: 1280x800 scroll 0/2400 · 4/6 interactive [1] textbox "手机号" value=13800000000 [2] textbox "密码" value=•••••• [3] button "登录" [4] link "忘记密码" → /forgot HEADINGS: 用户登录 | 没有账号?
TEXT: 用户登录 手机号 密码 登录 忘记密码
ACTIVE: [1] textbox "手机号"

每次生成视图都会重新分配编号，所以操作总是使用最新的编号；过期的编号会以清晰的「take a fresh snapshot」消息失败，而不是点错元素。

按坐标操作

截图里能看到的东西也可以只靠位置驱动——x / y 用 CSS 像素，和 browser_screenshot 同一比例——适用于元素视图无能为力的场景：canvas 应用、地图，以及跨域 iframe 里的所有控件。在这些地方，querySelector 被同源策略挡住，而 DevTools 输入域仍然能命中指针下方的任何东西。

drag 是真实手势，不是两次点击：按下、N 次插值移动、释放。每次按住移动都报告 button: 'left' 和 buttons: 1，因为正是这个位掩码让 Chrome 的输入管线区分悬停和拖拽；没有它，滑块照样收到 mousedown/mousemove，却就是不动。steps（默认 16）和 duration_ms（默认 420）决定 path、to_x / to_y 是拖放落点，ref 可以代替起始的 x / y：

browser_act({ action: 'drag', x: 486, y: 421, to_x: 704, to_y: 421 })
browser_act({ action: 'click', x: 640, y: 400 })

配置

行配置写在配置档的 cordis.patch.yml 里，按行 id dsh-visual-browser 覆盖：

- id: dsh-visual-browser
config:
headless: true # false = visible Chrome window
executablePath: '' # explicit chrome.exe path
userDataDir: '' # default: ~/.dsh/visual-browser/chrome-profile
viewport:
width: 1280
height: 800
maxElements: 100 # cap on the numbered list
maxTextChars: 320 # cap on the text excerpt
streamQuality: 60 # JPEG quality of the live screencast
allowUserControl: true # allow clicks/typing from the panel
reuseExisting: true # adopt a Chrome that already owns the profile
actionTimeoutMs: 12000
navigationTimeoutMs: 30000

工作原理

- 宿主（index.js、lib/）：用 --remote-debugging-port=0 --user-data-dir=<profile> 启动 Chrome，从 stderr 解析出 DevTools 端点，挂上一个扁平化的 CDP 会话，然后对外提供：
- 五个工具，通过 tools 服务注册（注册作用域跟随 effect），
- 一条同源前缀路由 /visual-browser/api：
| 路由 | 用途 |
| GET /state | 状态、视口和操作日志（很小的 JSON 轮询）。 |
| GET /stream | 一个长响应，持续推送 [len][seq][jpeg] 帧。 |
| POST /input | 一批指针 / 滚轮 / 按键 / 文本事件。 |
| POST /start、POST /stop、POST /nav | 打开 URL、关闭 Chrome、后退/前进/刷新。 |
- 实时画面（lib/browser.js）：Page.startScreencast 每绘制一帧就推一张 JPEG；管理器逐帧 ack，再把同一份 buffer 分发给每个面板。第一个订阅者会重启 screencast，静止页面也能立刻出画面；最后一个订阅者退出时停掉它，面板关掉就不占任何开销。每次点击都不截图，画面也完全不进模型上下文。
- 输入（lib/browser.js）：面板事件转成 Input.dispatchMouseEvent / Input.dispatchKeyEvent / Input.insertText 命令。整个过程不等快照、不等截图，输入延迟只有一个往返；客户端按动画帧批量发送，一次拖拽或滑动只发一个请求，而不是三十个。
- 快照（lib/page-scripts.js）：在页面里跑一个序列化函数，把可交互元素过滤到视口范围内，分配 data-dsh-vb-ref 编号，返回结构化 JSON。DOM 的其他信息一概不出页面。
- 宿主重启后仍能接上：Chrome 会把 DevToolsActivePort 写进自己的配置档，所以重启后的宿主（或上一个宿主崩溃、Chrome 还活着的情况）会直接挂到这个浏览器上，而不是在配置档锁上失败。接管的浏览器只会被断开连接，进程不会被杀掉。
插件卸载时，Chrome 会连同它的进程树一起结束。

注意事项与限制

- 跨域 iframe 只计数，不检查内容；如果某个流程位于 iframe 内，请直接打开对应 URL。
- 阻塞式 JS 对话框会自动接受，并记录到操作日志。
- 面板路由由 Harness web 服务器在原有 origin 上提供，不做额外鉴权，与其他本地面板路由一致。
- 流式响应刻意采用原始二进制格式：multipart/x-mixed-replace 的解析方式在不同浏览器版本间存在差异，因此面板自行解析帧。
- 面向模型的工具作用于活动页面：browser_open 会导航到该页面，所有读取和操作也都作用于它，因此「当前页面」始终含义明确，你仍可在标签栏中保留其他页面。
- 请求会超时，面板总会重试，因此即使连接因休眠或宿主重启而中断，也能自行恢复，无需刷新页面。
- 默认使用无头模式。部分站点在无头模式下表现不同；如果站点强制要求窗口，请设置 headless: false。

开发

npm test # syntax checks + snapshot/format/route/package smoke tests

.dsh-probe/（已被 git 忽略）存放开发期间使用的手动探针：live-probe.mjs 端到端驱动真实浏览器，ui-probe.mjs 在 Chrome 中渲染真实客户端 bundle，对接真实宿主 API，并用真实 DOM 事件驱动面板，build-css.mjs 为该测试环境复制面板 CSS 和主题 token。

MIT © RestRegular