浏览器桥接 ShallBay/dsh-bridge-browser

dsh-bridge-browser

让 dsh（DeepSeek Harness）直接操作你正在用的 Chrome 标签页：读取页面、点击、填表、导航、管理标签页，同时保留你的登录态、会话与 Cookie。

这是什么

本仓库是 dsh 的浏览器桥插件源码，npm 包名为 @shallbay/dsh-bridge-browser。

它是 @yuxianglin/dsh-bridge-browser（作者 Yuxiang Lin）的再打包版：运行时逻辑来自上游，本仓库只维护「让它能从 npm 安装、并能在 dsh Desktop 0.2.x 上跑起来」所需的差异（详见 NOTICE.md）。

浏览器侧是一个随 npm 包分发的 Chrome MV3 扩展（构建产物，不在本仓库内）。

能力

| 工具 | 作用 |
| browser_snapshot | 结构化文本快照：标题 / URL / 正文 / 带编号的交互元素 / 表单字段 |
| browser_click | 按编号点击链接、按钮、复选框等 |
| browser_type | 输入文本（兼容 React/Vue 受控组件），replace 可清空重填 |
| browser_press | 按键（Enter / Tab / Escape / 方向键…） |
| browser_scroll | 视口滚动（up / down / top / bottom） |
| browser_navigate / browser_open_tab / browser_back / browser_forward / browser_reload | 导航 |
| browser_list_tabs / browser_follow_tab / browser_close_tab | 标签页枚举与绑定 |
| browser_get_text | 读取局部文本 / 懒加载内容 |
| browser_wait | 等待页面加载与渲染稳定 |

页面以纯文本呈现（不截图），模型靠编号定位元素；密码与支付卡字段始终显示为 ••••，其值不会离开页面。

安装

前提：已安装 dsh。桌面端请先启动过一次（这样 profiles/desktop 才会被初始化）。

桌面端
dsh plugin --profile desktop add @shallbay/dsh-bridge-browser

或 web / CLI 端
dsh plugin --profile web add @shallbay/dsh-bridge-browser

装完重启桌面端（菜单 Restart App and Host）。

卸载

桌面端
dsh plugin --profile desktop remove @shallbay/dsh-bridge-browser

或 web / CLI 端
dsh plugin --profile web remove @shallbay/dsh-bridge-browser

卸载后建议顺带清理：

- 残留目录 ~/.dsh/profiles/<profile>/node_modules/@shallbay/dsh-bridge-browser
- 浏览器里已加载的扩展：chrome://extensions → 该扩展 → 移除
- 如果之前手动加过端口固定 / 兼容豁免，按需从 cordis.patch.yml / compatibility.json 里删掉

加载浏览器扩展（必做一次）

扩展随 npm 包发布在 extension/ 目录，包内附带一键脚本：

$pkg = Join-Path $HOME '.dsh\profiles\desktop\node_modules\@shallbay\dsh-bridge-browser'
powershell -ExecutionPolicy Bypass -File "$pkg\scripts\setup-extension.ps1"

脚本会把扩展复制到 %USERPROFILE%\.dsh\browser-extension（旧版自动备份）并尝试打开 chrome://extensions。
然后：开发者模式 → 加载已解压的扩展程序 → 选择该目录。

不要直接从 node_modules 里加载：那个路径会随 profile 切换 / 依赖重装而变化，Chrome 里的扩展会变成「已损坏」。

把桌面端口固定下来

DSH Desktop 0.2.1 起用 --port 0 启动，端口每次随机分配，浏览器扩展无法自动发现。在 profile 的 cordis.patch.yml 里追加：

- id: webserver
name: "@deepseek-ai/dsh-host-webserver"
config:
host: '127.0.0.1'
port: 19387

本包附带的扩展把 19387 加进了自动探测端口，所以扩展里的「桥接地址」留空即可。

每次触发「禁用第三方插件」恢复流程都会重写该 patch，恢复后需要重新加回这段。

从源码构建

需要 Node ^22.19 或 >=24（tsdown 依赖现代 Node 内建模块）。

npm install
npm run build # 产物在 lib/

lib/ 与 extension/ 都是构建产物，已被 .gitignore 排除。本仓库不含扩展源码——扩展来自上游仓库的 extensions/dsh-browser，随 npm 包发布。

与上游的差异

1. 包标识：改为 @shallbay/dsh-bridge-browser，去掉 private，让 dsh plugin add 能从 registry 解析。
2. peerDependencies 放宽到 >=0.1.7-rc.2 <0.3.0。dsh 的兼容闸门会校验插件声明的 @deepseek-ai/dsh* peer，上游的 ^0.1.x-rc.n 会被 0.2.x 直接拒绝。
3. 适配 DSH 0.2.1 的 Peer 校验：0.2.1 的 Gateway 对 wireStream.open 和 unary invoke 都要求传入 Peer（peer.signal、peer.interactions === 'answer'）。本包用 connection.createPeer({ principal: { kind: 'owner' } }) 铸造一个 in-process Peer 并透传，避免 Cannot read properties of undefined (reading 'signal')。
4. 客户端 bundle 的插件 id 同步为包名，避免 client-modules: duplicate factory registration 导致 web boot 失败。
5. 扩展自动探测 19387（桌面端端口），并随 npm 包一起分发。

版本记录

| 版本 | 说明 |
| 1.0.0 | 首个 npm 版本 |
| 1.0.1 | 修正客户端 bundle 的插件 id（重复注册导致 web boot 失败） |
| 1.0.2 | 基于上游 main 适配 DSH 0.2.x；修复 wire stream 的 peer 校验 |
| 1.0.3 | 回归修复：客户端 id（1.0.2 重新构建时被覆盖） |
| 1.0.4 | 补齐 unary invoke 的 peer —— 修复 session.list / settings.describe 报 Cannot read properties of undefined |

已知限制

- 桥只接受一个活动扩展连接；桌面端与 dsh web 不能同时运行。
- 点击、输入、导航等写操作默认需要在浏览器侧边栏确认；页面读取按需进行。
- Chrome 需 116+；Firefox 需 140+ 且必须手动填写 ~/.dsh/ext-bridge-token（moz-extension:// 的 UUID 每次安装都不同，无法零配置）。
- 受保护页面（扩展商店、chrome:// 等）只能读取标签页元数据，不能操作 DOM。

许可与归属

- 许可证：MIT，见 LICENSE。
- 上游项目：Lum1104/dsh-browser，作者 Yuxiang Lin。
- 本仓库为再打包，运行时逻辑版权归上游作者所有；改动清单见 NOTICE.md。

目录结构

src/ TypeScript 源码（插件、协议、工具、远程 Host 适配） scripts/ setup-extension.ps1（复制扩展并打开 chrome://extensions） cordis.patch.yml 插件 bundle patch（注册 bridge-browser 行） tsconfig.json TS 配置 tsdown.config.ts 打包配置 NOTICE.md 上游归属与改动清单