dsh-browser-bridge

Readme

# dsh-browser-bridge

DeepSeek Harness（DSH）浏览器桥接插件：让 DSH Agent 通过本地 WebSocket 读取和控制真实浏览器。

```
+--------------------------+        WebSocket         +--------------------------+
| DeepSeek Harness (dsh)   |  ws://127.0.0.1:3080/   |  Firefox / Chrome / Edge |
| browser_* 工具           |        bridge           |  DSH Browser Bridge      |
+--------------------------+ <---------------------> +--------------------------+
```

## 功能

服务端提供 13 个模型端工具：

- `browser_status`
- `browser_list_tabs`
- `browser_activate_tab`
- `browser_navigate`
- `browser_snapshot`
- `browser_read_page`
- `browser_click`
- `browser_type`
- `browser_press`
- `browser_scroll`
- `browser_wait`
- `browser_screenshot`
- `browser_eval`

浏览器扩展负责执行这些命令：标签页管理、DOM 操作、键盘输入、滚动、等待、截图、页面 JS 求值。

本仓库同时提供：

- `lib/`：DSH 服务端插件（npm 包）
- `extension/`：Firefox WebExtension 源码（Manifest V2）
- `cordis.patch.yml`：DSH 插件安装补丁
- `package.json`：带 `dsh.bundle` 声明的 npm 包

## npm 安装

```sh
dsh plugin --profile web add dsh-browser-bridge
```

或手动注册到 `~/.dsh/profiles/web/cordis.patch.yml`：

```yaml
- insert:
    - id: browser-bridge
      name: 'dsh-browser-bridge'
```

## 浏览器扩展安装

### Firefox

1. 打开 `about:debugging#/runtime/this-firefox`
2. 「临时加载附加组件...」选择 `extension/manifest.json`

### Chrome / Edge（原 Chromium MV3 变体）

可使用原仓库对应的 Chromium 扩展，或参照 `extension/` 适配。

## 默认配置

| 配置 | 默认值 | 说明 |
|---|---|---|
| `path` | `/bridge` | WebSocket 路径 |
| `commandTimeoutMs` | `60000` | 命令超时 |
| `screenshotDir` | `~/.dsh/browser-bridge` | 截图保存目录 |
| `maxMessageBytes` | `8 MiB` | WebSocket 最大消息 |

## 快速开始

1. 安装服务端插件：
   ```sh
   dsh plugin --profile web add dsh-browser-bridge
   ```
2. 加载 Firefox 扩展：
   - 打开 `about:debugging#/runtime/this-firefox`
   - 「临时加载附加组件...」选择 `extension/manifest.json`
3. 在 DSH 对话中调用：
   ```text
   browser_status
   ```
4. 应看到：
   ```text
   Browser bridge: connected
   ```

## 插件市场

- npm 包：`dsh-browser-bridge`
- DSH 插件市场收录：通过
  [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin)
  提交。
- Firefox 扩展：可上传 Mozilla AMO 发布，或临时加载本仓库 `extension/`。

## 安全说明

- 桥接默认只绑定 `127.0.0.1`，无鉴权，只建议本机使用。
- `browser_eval` 可执行页面 JS，功能强大，请仅授权可信 Agent。
- 扩展需要 `<all_urls>` 权限以读取标签页和操作任意网页。

## License

MIT