egnmosk/dsh-browser-bridge

dsh-browser-bridge

一个 DeepSeek Harness 插件 + 浏览器扩展 组合，让 DSH 智能体能够读取并控制你的浏览器——相当于 Kimi 的 WebBridge 扩展或 Claude 的浏览器扩展，但用于你自己的本地 harness。

+-----------------------------+        WebSocket         +--------------------------+
|  DeepSeek Harness (dsh)    |  ws://127.0.0.1:3080/     |  Your browser            |
|                             |  bridge                  |  (Chrome / Edge / Yandex)|
|  browser_* tools           |  |  DSH Browser Bridge      |
|  (this plugin)             |   commands / responses    |  extension (MV3)         |
+-----------------------------+                          +--------------------------+

DSH 一侧暴露 13 个面向模型的工具；扩展一侧在浏览器中执行它们（标签页、DOM、点击、输入、滚动、截图、eval）。

智能体工具

| 工具 | 作用 |
|---|---|
| browser_status | 扩展是否已连接？桥接 URL、待处理命令。 |
| browser_list_tabs | 列出打开的标签页（id、title、url、active）。 |
| browser_activate_tab | 将某个标签页置于前台。 |
| browser_navigate | 打开 URL，或重新加载 / 后退 / 前进；可选新标签页。 |
| browser_snapshot | 交互元素（按钮、链接、输入框……）及其稳定的 CSS 选择器。 |
| browser_read_page | 可见页面文本（或某个子树），按字符数上限截断。 |
| browser_click | 通过 CSS 选择器点击元素。 |
| browser_type | 填充 input / textarea / contenteditable（原生事件）。 |
| browser_press | 发送按键（Enter、Tab、Escape、方向键……）。 |
| browser_scroll | 滚动页面或某个可滚动元素。 |
| browser_wait | 等待某个选择器出现/消失，或仅让页面稳定下来。 |
| browser_screenshot | 将当前标签页的 PNG/JPEG 保存到磁盘（~/.dsh/browser-bridge/）。 |
| browser_eval | 在页面中求值一个 JS 表达式（content-script 世界）。 |

当扩展未连接时，每个工具都会以一条清晰的消息失败，告诉模型（以及用户）如何连接它。

目录结构

dsh-browser-bridge/
|-- lib/            # the DSH plugin (node side)
|   |-- index.js    # plugin entry: tools + WS upgrade route + /bridge/info
|   |-- ws.js       # minimal RFC 6455 WebSocket server (no dependencies)
|   |-- bridge.js   # connection registry, request/response correlation, timeouts
|   -- tools.js    # the 13 browser_* tool definitions
|-- extension/      # the browser extension (Manifest V3)
|   |-- manifest.json
|   |-- background.js   # WebSocket client + chrome.tabs / messaging dispatch
|   |-- content.js      # DOM actions in pages (top frame only)
|   |-- popup.html/js   # connection status, read-this-page preview
|   |-- options.html/js # server URL, auto-connect, "Test connection"
|   -- icons/
-- test/run-test.mjs   # standalone protocol test (no harness boot required)

安装
1. 该包位于 web 配置文件的 node_modules 中
(~/.dsh/profiles/node_modules/dsh-browser-bridge)。
2. 在 ~/.dsh/profiles/web/cordis.patch.yml 中注册为行
browser-bridge (name: dsh-browser-bridge)。
3. 记录在 ~/.dsh/profiles/web/package.json 的 dependencies 中。

随时验证组合：

dsh --profile web --dump-config | grep -A 3 browser-bridge

激活

该插件在启动时加载，因此安装后重启一次 dsh web
（重启会使 GUI 中断几秒钟；它会以相同的 URL 恢复）。
重启后，服务器
会打印 [browser-bridge] bridge ready - point the DSH Browser Bridge extension
at ws://127.0.0.1:3080/bridge，并且 http://127.0.0.1:3080/bridge/info
会返回 JSON。用以下命令验证：

dsh --profile web --dump-config | grep -A 3 browser-bridge
curl http://127.0.0.1:3080/bridge/info   # -> {"name":"dsh-browser-bridge",...}

加载扩展

1. 打开你的浏览器：Chrome、Edge 或 Yandex（均为 Chromium 内核）。
2. 前往 chrome://extensions（Edge：edge://extensions，Yandex：
browser://extensions）。
3. 启用 开发者模式（右上角开关）。
4. 点击 加载已解压的扩展程序，然后选择本包的 extension 文件夹。
5. 点击扩展图标——弹出窗口应显示 Connected to DeepSeek
Harness。

默认服务器 URL 是 ws://127.0.0.1:3080/bridge，与运行在默认端口上的 dsh web
相匹配。如果你的 harness 监听其他端口，请打开
扩展的 选项 页面，设置 URL，并使用 测试连接。

然后只需向 agent 提问，例如：

使用浏览器打开 example.com，读取页面，并点击第一个链接。

配置（cordis.patch.yml）

| 键 | 默认值 | 含义 |
|---|---|---|
| path | /bridge | Web 服务器上的 WebSocket 端点路径。 |
| commandTimeoutMs | 60000 | 工具等待扩展应答的时长。 |
| screenshotDir | ~/.dsh/browser-bridge | 截图保存位置。 |
| maxMessageBytes | 8 MiB | 最大 WS 消息大小（截图通过 WS 传输）。 |

开发

- node test/run-test.mjs - 启动一个真实服务器 + 模拟扩展客户端，并
测试每个工具、超时、断开连接以及 /bridge/info 路由
（40 个断言，无需启动 harness）。
- 协议：JSON 文本帧。服务器 -> 客户端 request/ping/welcome；
客户端 -> 服务器 hello/response/pong。命令在
扩展协议中为 camelCase（listTabs、snapshot、click、...），在
面向模型的工具中为 snake_case。

安全说明

- 该桥接仅绑定到 Web 服务器的回环主机（默认 127.0.0.1），
且没有身份验证：任何本地进程都可以连接到
/bridge 并驱动浏览器。请像对待 shell 访问权限一样对待它。
- browser_eval 会在页面中执行 JavaScript——按设计即功能强大；请仅将其授予
受信任的 agent。
- 该扩展具有  主机权限（读取标签页 URL 所必需
并在任意页面中生效）。它仅与配置的 localhost URL 通信。