dsh-explorers

dsh-explorers

安装包见仓库 Releases：-chrome.zip / -edge.zip / -qq.zip 三个浏览器专用包

把你自己的浏览器接进 DSH：dsh 能开网页、读页面、点按钮、填表单、截图 —— 用的是你日常那个 Chrome / Edge / QQ 浏览器（带登录态、带插件），不是另起一个无头浏览器。

Chrome ｜ Edge ｜ QQ 浏览器 —— 同一份 MV3 扩展，装任意一个就够；一个桥可以同时接多个浏览器，命令里用 browser 指定走哪个。

它是怎么工作的

DSH 插件进程 (Electron Host, Node 24)
  lib/index.js            cordis 插件：注册 tools，spawn 桥进程
  lib/bridge-client.js    HTTP 客户端 → 桥
        │ HTTP  POST /command   (Bearer token)
        ▼
  lib/bridge.mjs          独立桥进程（detached，父进程死后自杀）
        │ 127.0.0.1:17731   HTTP + WebSocket
        │ WS /ws            扩展反向连入
        ▼
  extension/background.js  MV3 Service Worker（Chrome / Edge / QQ 浏览器都装同一份）
        │ chrome.tabs / chrome.scripting / chrome.debugger
        ▼
  网页（page-agent.js 注入到 ISOLATED world）

关键点：

• 扩展主动连桥，桥是唯一固定端口（默认 17731，被占用时 17732…17740）。
• 同一桥可同时接 Chrome + Edge + QQ 浏览器各一条 WebSocket。
• 桥只监听 127.0.0.1；token 每次桥启动重新生成。

安装

分两段：① DSH 插件；② 浏览器扩展。完整步骤（含 QQ 浏览器兼容判断、故障排查表）见 docs/INSTALL-zh.md，English: docs/INSTALL.md。

① DSH 插件

一条命令搞定（会备份 profile 的 package.json，幂等，可重复跑；等价于下面手改）：

node scripts/install-profile.mjs            # 默认装进 desktop profile
node scripts/install-profile.mjs --uninstall

手改的话是这样：

// %USERPROFILE%\.dsh\profiles\<profile>\package.json
{
  "dependencies": { "dsh-explorers": "link:<插件目录>" },
  "dsh": { "profile": { "bundles": [ /* …原有条目… */ "dsh-explorers" ] } }
}

cd $env:USERPROFILE\.dsh\profiles\<profile>
pnpm install      # 然后重启 DSH（本机实测：DSH 桌面端常会监听 profile 变更自动重载，先等 5–10 秒看 bridge.json 是否出现，没有再重启）

桥起来后 %USERPROFILE%\.dsh\dsh-explorers\bridge.json 里能读到 port 与 token。自检：

node scripts/selfcheck.mjs        # 插件/桥/扩展/安装页 18 项逐条检查

② 浏览器扩展

1. 打开安装页 http://127.0.0.1:17731/install（端口以 bridge.json 的 port 为准）。 备选入口：http://127.0.0.1:<DSH web 端口>/plugins/dsh-explorers/ —— 第三方 /plugins/... 路由不保证可用，打不开就用桥那个地址，两个入口是同一份页面。 打不开安装页 → 检查 %USERPROFILE%\.dsh\dsh-explorers\bridge.json 是否存在、DSH 是否已启动；文件不在说明桥没跑起来。
2. 在对应浏览器的卡片上点「下载 Chrome / Edge / QQ 版扩展」（三个包代码相同，只是包内附带各自浏览器的 INSTALL-<浏览器>.txt 安装说明）→ 解压到固定目录 → 打开扩展页（chrome://extensions / edge://extensions / qqbrowser://extensions）→ 开「开发者模式」→「加载已解压的扩展程序」→ 选含 manifest.json 的文件夹。
3. 点扩展图标 →「自动配对」；失败就把安装页的「复制配对码」粘进扩展设置页。 （桥重启换了 token 时，扩展收到 WS 关闭码 4401 会自己重新配对，一般不用手动操作。）
4. 回安装页，状态条变绿 = 已连接。

工具（模型可见）

工具	作用
browser_status	看连接状态与标签页（可用 browser 指定）
browser_tabs	标签页：list / new / activate / close / reload / back / forward
browser_navigate	打开 URL，可等 load / domcontentloaded
browser_snapshot	抓页面：可交互元素 + ref（后续 click/type 用它），或正文 / HTML
browser_click	点击：ref / selector / text / 坐标，四种定位
browser_type	往输入框输入（React/Vue 兼容的原生 setter），可清空、可提交
browser_key	给当前焦点发按键 / 组合键（Control、Shift、Alt、Meta）
browser_scroll	滚动页面，或滚到某个 ref
browser_extract	提取文本 / HTML / 属性，单条或全部
browser_screenshot	视口或全页截图，落盘后交给模型看图
browser_wait	等元素 / 文本 / URL，或固定时长；超时返回 matched:false 不报错
browser_eval	页面主世界执行 JS，返回可序列化值

典型用法

你：打开 example.com，在页面里找到第一个链接，点进去，然后截图给我。

dsh：browser_navigate  { url: "https://example.com" }
     browser_snapshot  { mode: "interactive" }        → elements: e1 "More information..."
     browser_click     { ref: "e1" }
     browser_extract   { selector: "h1" }
     browser_screenshot{ fullPage: false }            → .dsh-explorers/shots/shot-*.png

安全边界

1. 桥只监听 127.0.0.1，token 防的是浏览器网页误打和端口串用，不防本机同用户进程（同用户进程本来就能读 bridge.json）。
2. browser_eval / browser_type 能把页面内容和按键送进网页 —— 只在用户明确要求时用，不要主动填密码。
3. 扩展申请了 debugger 权限（全页截图用），使用时浏览器会显示"正在调试此浏览器"提示条，这是预期行为。
4. 扩展不采集、不上传任何数据；命令只来自本机桥。

开发与验证

node scripts/build-extension.mjs      # 打包 dist/dsh-explorers-<version>.zip
node --test                           # 协议单测（自动发现）：桥 HTTP / WS / 工具面，50 项
node tests/e2e-edge.mjs               # 真实 Edge 端到端（本机需已装扩展）

安装页是自包含 HTML，可直接离线渲染检查：

node --check pages/install-page.js

目录结构

dsh-explorers/
├─ lib/                  DSH 插件：tools 注册、桥进程、HTTP 客户端（cordis）
├─ extension/            MV3 扩展，Chrome / Edge / QQ 浏览器共用一份
├─ pages/install-page.js 安装页：自包含 HTML，DSH webServer 与桥两个宿主共用
├─ scripts/              构建与开发脚本（含扩展打包、图标生成）
├─ tests/                协议测试（桥 HTTP / WS / 工具面）+ 真实浏览器 E2E
├─ docs/                 INSTALL-zh.md（中文详细指南）· INSTALL.md（English）
├─ dist/                 构建产物 dsh-explorers-<version>.zip（不入库）
├─ PROTOCOL.md           协议契约：端口 / token / action / 错误码 / 安全边界
└─ README.md

已知限制（v1）

• iframe 内元素：只操作顶层文档，跨 frame 的元素暂不支持。
• 多标签并发：一次命令只作用于一个标签页；没有批量并行。
• 下载 / 上传文件：不代管浏览器下载，也不能给 <input type=file> 塞文件。
• 网络抓包：不拦截、不导出请求（没有 devtools 级网络能力）。
• 应用商店上架：只支持「加载已解压的扩展程序」，没有商店包与自动更新。

许可

MIT © 2026 dsh-explorers contributors