xkzm123/dsh-browser-bridge

一句话：装好之后，你可以在 DeepSeek Harness 里说「帮我点那个按钮」，它就去点屏幕上真的那个浏览器——不是另开一个空白浏览器，就是你正在用的那个。

不用重启浏览器，不用装 Python 或 Node 环境，不用记命令。

---

目录

• 它到底能干什么
• 三步装好
• 要不要装油猴脚本
• 油猴脚本怎么装
• 它怎么省钱
• 它是怎么做到的
• 20 个工具
• 常见问题
• 卸载

---

它到底能干什么

以前的 AI 只能告诉你「你应该点这里」。现在它能自己点。

你说的话	它做的事
「看看我浏览器现在开着什么」	读出所有浏览器窗口和标签页
「把这个页面的正文念给我听」	抽取整页可见文字
「把那个登录按钮点了」	找到叫「登录」的按钮，把鼠标移过去真点一下
「搜索框里填上显卡价格，回车」	点进输入框，输入中文，按回车
「B 站搜一下 xxx，给第一条点赞」	搜索 → 按标题挑结果 → 点赞 → 回报状态
「把页面上所有链接收集起来」	返回全部链接地址

它操作的是你已经登录的浏览器。所以需要登录才能看到的页面、买了会员才能看的内容，它都看得到——你不用把账号密码交给任何人。

---

三步装好

第一步：装插件

打开一个终端（开始菜单搜「PowerShell」也行），粘这一条回车：

dsh plugin --profile web add github:xkzm123/dsh-browser-bridge

web 是什么？ 你的 DSH 运行配置的名字。多数人就是 web，照抄即可。 不知道的话，看一眼 C:\Users\你\.dsh\profiles\ 下面有哪个文件夹，把它填进去。

用桌面版 DSH 的看这里：直接打开 设置 → 插件，搜 dsh-browser-bridge 装上就行，不用命令行。

装完会显示类似这样：

+ dsh-browser-bridge 1.3.0
Done in 5.1s

第二步：重启一次 DSH

插件只在 DSH 启动的时候加载，所以装完要重启一次。

• dsh web 用户：关掉终端里的进程，再 dsh web 开一次
• 桌面版用户：退出应用再打开

浏览器不用重启，标签页和登录状态都还在。

第三步：跟它说一句话

回到对话里，直接说：

看看我浏览器现在开着什么

它会调用 browser_windows，把窗口列表念给你听，比如：

* pid=14664 msedge 1920x1040 (frontmost) · 哔哩哔哩 — Microsoft Edge
  pid=22180 chrome  1440x900   · 工作台

* 是当前目标窗口。看到这种输出，就说明装好了。

怎么确认装得对不对

dsh --profile web --dump-config | Select-String -Context 0,3 browser-bridge

能看到 - id: dsh-browser-bridge 这几行就是对的。

---

要不要装油猴脚本

答案：不装能用，装了更强。先看这张对比图。

• 只装插件 → 14 个工具。读页面、点按钮、打字、滚动、截图、切标签，够日常用。
• 再装油猴脚本 → 20 个工具。多出来的都是又快又省的那一类：按文字点击、批量执行、等待元素、读页面状态。

油猴（Tampermonkey）是什么：一个浏览器扩展，专门用来跑「用户脚本」——一小段注入到网页里运行的代码。我们要装的那个脚本，负责把 AI 的指令送进页面内部执行。

依赖它的 6 个工具：

工具	作用
browser_click_text	按文字点击，点完直接回报状态
browser_page_query	用固定词表查询页面
browser_wait_for	等元素/文字出现，替代反复截图
browser_batch	一串动作一次调用
browser_run_js	跑任意 JavaScript
browser_bridge	启动本地桥

---

油猴脚本怎么装

脚本就在本仓库里：bridge/bridge.user.js。任何一台电脑都能装，不依赖你本机有没有跑什么服务。

1. 装 Tampermonkey 扩展（装过的跳过）

• Edge：microsoftedge.microsoft.com/addons
• Chrome：chromewebstore.google.com

装不上（国内网络常见）就从 tampermonkey.net 下载 crx 手动拖进扩展页。

2. 装用户脚本

方式 A：点这一行链接（推荐）

https://raw.githubusercontent.com/xkzm123/dsh-browser-bridge/main/bridge/bridge.user.js

把上面这串地址粘进浏览器地址栏回车。Tampermonkey 认 .user.js 结尾，会自动弹出安装页：

图上扫一眼这四处：

位置	内容	含义
左上	dsh-browser-bridge v1.3.0	脚本名和版本
作者	xkzm123	谁写的
源	githubusercontent.com/.../bridge.user.js	从仓库取的，源码可查
包含 URL	*://*/*	在所有网页上生效——它需要能在任何页面里干活

点 「安装」。

图里显示「重新安装」是因为演示机已经装过一次；第一次装显示的是 「安装」。

方式 B：手动导入（网络打不开上面那个链接时）

1. 在仓库里点开 bridge/bridge.user.js，点右上角 Raw
2. 全选复制（Ctrl+A Ctrl+C）
3. 浏览器点 Tampermonkey 图标 → 管理面板 → +（新建脚本）
4. 把编辑器里的内容整个删掉，粘贴刚复制的代码，Ctrl+S 保存

方式 C：本机快捷入口（只对已经装好插件的人）

插件自带一个本地服务，会把同一个脚本直接吐出来：

http://127.0.0.1:8737/install.user.js

这只是个方便入口，不是所有人都有——它要求你本机的桥服务正在运行、端口是 8737。所以文档里主推方式 A，方式 C 只是给已经配好的人省事。

3. 确认桥的端口

脚本里写死连 127.0.0.1:8737。如果你的插件配置改了端口（cordis.patch.yml 里的 bridgePort），脚本里这一行也要跟着改，然后重新安装：

const PORT = 8737;

4. 启动桥 + 验证

# 插件装好之后，脚本在这里：
C:\Users\你\.dsh\profiles\web\node_modules\dsh-browser-bridge\scripts\bctl.ps1 bridge start

看到 bridge running on port 8737 就成了。这个服务只监听 127.0.0.1，只有本机能连，不需要管理员权限，也不弹防火墙。

也可以直接说「启动浏览器桥」，让它调 browser_bridge 帮你起。

然后随便开个网页，说：

等页面的搜索框出现（最多 10 秒）

能返回 {"found": true, ...} 就全通了。

---

它怎么省钱

你在对话里花的每一个 token、每一次往返，都是钱和时间。所以这套工具按**「先用最便宜的，不够再升级」**设计：

层	手段	成本	什么时候用
1	browser_page_query / browser_get_text	纯文本，最省	能读到答案就读 —— 状态、标题、属性、列表
2	browser_snapshot	文本但更大	需要元素的名字和位置才上这一层
3	browser_screenshot	图片 token，最贵	文字答不了：布局问题、canvas 内容、用户明确要图

三个专门用来减少往返的工具：

• browser_wait_for — 等元素/文字出现，出现即返回。替代「点一下 → 截图 → 看看出没出 → 再截图」这种循环。轮询在页面里做，不消耗对话 token。
• browser_batch — 一串动作一次调用。两种模式：commands 走无障碍层，在一个 PowerShell 进程里连跑 N 条 bctl 命令（5 步 ~0.8s，独立调用要 ~6.2s）；steps 走油猴桥做页面内操作。
• browser_click_text — 按文字点，点完顺手把元素的新状态（class / aria-pressed）一起带回来。大多数「点成功了吗」的问题在这一步就答完了，不用再查一次。

为什么快：一次进程，N 条命令

bctl 的每条命令都是一次 powershell.exe 冷启动（实测 ~800ms）+ 现场编译 C#（~265ms）， 真正干活只要 ~150ms。所以 20 条命令 = 24 秒纯开销。

改法有三处，都已落地：

改动	效果
batch 把 N 条命令放进同一进程	1250ms/条 → 73ms/条（17×）；5 条命令 6.2s → 1.8s
C# 编译产物缓存成 DLL（%LOCALAPPDATA%\dsh-browser-bridge）	每次进程少花 ~200ms 编译
pixel / at 让「验证」不再需要截图	判一个按钮状态：35ms 一个像素，而不是 3MB 一张图

js 也做了两级探活：/ping 只证明服务在，/stats.lastPollUtc 才证明有页面在领任务。 油猴脚本没装时立刻报错（~200ms），不再白等满 20 秒超时。

一次典型任务长这样：

1. browser_navigate        打开搜索页
2. browser_wait_for        等结果列表出现         ← 替代若干次截图
3. browser_page_query      取标题+链接，按标题挑   ← 纯文本，模型能看到全部候选
4. browser_batch           点进去 + 点赞 + 取色验证 ← 一次往返，一个进程
5. 完成                     点赞状态从返回值就看得见（pixel 颜色翻转）

五步、零截图。

---

它不会做什么

这三条是硬约束，写在代码里而不是文档里：

不做	原因
不会关闭你的浏览器或标签页	CTRL+W、CTRL+F4、ALT+F4 直接拒绝执行（要关得显式加 allowClose）。关掉最后一扇窗会让浏览器变成「进程在、窗口没、任务栏没图标、声音还在放」的状态——看起来就是浏览器消失了
不会点浏览器自己的按钮	所有点击只搜网页内容（无障碍树的 Document 子树）。标题栏的「最小化/还原/关闭」不在搜索范围里，甚至在快照里都不会出现
不会启动浏览器	找不到窗口就报错让你去开；它从不执行 msedge.exe / chrome.exe。重开一个只会多一个窗口和一个新标签

浏览器真的没了的时候，bctl.ps1 ensure 会告诉你是哪种状态：

bctl.ps1 ensure
# state : absent        ← 进程都没有，需要你自己开
# state : windowless    ← 进程在、窗口没了，点任务栏图标恢复
# state : hidden        ← 窗口被隐藏，已自动恢复
# state : ok            ← 正常

每一步动作都记在 ~\.dshrowser-bridgeudit.log，出问题用 bctl.ps1 audit tail 20 就能看到是哪一步之后窗口没的。

它是怎么做到的

为什么不用最常见的「调试端口」方案

多数浏览器自动化工具（Playwright、Puppeteer）靠 Chrome 的调试端口（--remote-debugging-port=9222）。这条路有个死结：

调试端口只能在浏览器启动的那一刻打开。 浏览器已经跑起来了，就没法再从外面接进去。

所以那些工具要么让你重启浏览器，要么另开一个干净的浏览器实例——后者意味着登录状态、会员、Cookie 全都没有。

这个插件换了个思路：不接浏览器的调试接口，而是操作 Windows 本身。

三条通道

通道	白话解释	负责什么
① UI Automation	Windows 自带的「无障碍接口」。原本是给读屏软件用的，能把任何程序的界面结构念出来——包括网页	读页面文字、列出元素和位置、按名字点
② SendInput	Windows 自带的「模拟输入」。把鼠标移动、点击、按键注入进系统，效果和你自己动手一样	坐标点击、拖拽、滚轮、快捷键、中文输入
③ 篡改猴桥	一段跑在页面内部的脚本，通过 127.0.0.1:8737 和本机的小服务通信	页面内查询、按文字点击、批量执行、等待

前两条操作「窗口」，第三条操作「页面内部」。三条一起，基本没有够不着的地方。

关于「不要重开浏览器」

Windows 上，浏览器关掉最后一个窗口后，进程通常不会退出，而是留在后台——这时它的窗口对象还在，只是变成了不可见，任务栏也没有图标。

这种状态最容易被误判成「浏览器没开」，然后重开一个，结果多出一个窗口和一个新标签页。

插件的处理是：

1. browser_windows 会把这种窗口标出来（(no window — will be restored)）
2. 真要操作时，先把它恢复显示（ShowWindow），而不是退出重开
3. 插件代码里没有任何启动浏览器的路径——找不到窗口就报错让你去点任务栏，绝不自己开

一个真实的技术细节

无障碍接口和模拟输入都是 Win32 的老接口，返回物理像素坐标。多显示器时虚拟屏幕原点可能是负的（左边那块屏是 -1920,0），所以脚本启动时会主动设成「DPI 感知」，否则坐标整体偏掉。

另外同一进程往往有多个顶层窗口（工具提示、隐藏的辅助窗口），按 pid 找窗口时必须挑面积最大的那个，否则会绑到一个 146×21 的 helper 上，然后所有操作都落到错误窗口。

---

20 个工具

工具	一句话	需要油猴
browser_use	选定目标窗口，之后不用再传 pid
browser_windows	列出浏览器窗口
browser_tabs	列出标签页
browser_switch_tab	切换标签页
browser_page_info	当前页标题和网址
browser_navigate	打开网址；已打开过就直接复用，不重复加载
browser_snapshot	导出网页内容的元素清单（类型、名字、坐标）
browser_get_text	抽整页文字
browser_click_element	按名字点击
browser_click_text	按文字点击 + 回报状态	✅
browser_click_at	按坐标点击
browser_type_text	输入文本（中文可直接输入）
browser_press_key	发送快捷键
browser_scroll	滚轮
browser_screenshot	截图存成 PNG
browser_pixel	读一个像素的颜色，判状态不花图像成本
browser_element_at	坐标反查元素，点之前先确认落点
browser_wait_for	等元素/文字出现	✅
browser_batch	一串动作一次调用（commands 走无障碍层，一个进程跑完）	✅
browser_page_query	固定词表查询页面	✅
browser_run_js	执行任意 JavaScript	✅
browser_bridge	启动/查看/停止本地桥	✅

不用记住它们——正常说话就行，模型会自己挑。

命令行也有同一套能力：

bctl.ps1 doctor                       # 体检
bctl.ps1 browsers                     # 列浏览器窗口（自动排除宿主窗口）
bctl.ps1 wake                         # 把后台常驻的浏览器显示回来
bctl.ps1 uia 14664 --type Button      # 列页面按钮
bctl.ps1 clickel 14664 "登录"          # 按名字点
bctl.ps1 at 220 978 --pid 14664       # 这个坐标上是哪个元素
bctl.ps1 pixel 220 978                # 这个坐标什么颜色
bctl.ps1 batch --file plan.txt        # 一次进程跑完整条链
bctl.ps1 js --op items --args '{"selector":"a[href]"}'   # 取标题+链接

详见 references/commands.md。

---

常见问题

1. 能用在 Mac 或 Linux 上吗？

不能。底层是 Windows 专有的无障碍接口和输入注入。package.json 里写了 os: win32，别的系统装不上。

2. 会不会很危险？它能看到我所有东西吗？

能看到界面上显示出来的东西；看不到密码明文，也读不到别的程序的数据。

不想用了就停桥、删插件、删脚本，都有对应命令。

3. 它会不会自己乱点？

不会自己动。每次都是你提要求，它才调工具。危险动作（删除、提交、支付）建议让它先告诉你要点哪里。

4. 浏览器不见了 / 任务栏没图标

大概率是「关了最后一个窗口但进程还在」。在对话里说「把浏览器窗口恢复出来」，它会调 wake 把那个隐藏窗口显示回来——不会重开一个。

5. 油猴装了，但「执行 JS」一直超时

按顺序查三件事：桥在跑吗（bridge status）；篡改猴里能看到这个脚本吗；那个标签页是当前可见的那个吗（后台标签页不抢任务）。

6. GitHub 这种站点报 CSP 错误

正常。这类站禁止页面里执行动态代码，任何扩展都绕不过去。插件会明确告知，并让你改用 browser_page_query——固定词表不经过 eval，照样能读。

7. 输入中文变成乱码？

插件用 Unicode 直送字符，不经过输入法，正常不会乱码。如果乱，多半是输入框还在输入法组合状态——先按一次 Esc。

8. 装完插件 DSH 起不来了？

dsh plugin --profile web remove dsh-browser-bridge

把报错贴到 Issues。

---

卸载

bctl.ps1 bridge stop
dsh plugin --profile web remove dsh-browser-bridge

油猴那边：Tampermonkey 图标 → 管理面板 → 找到 dsh-browser-bridge → 删除。

---

给开发者

├── package.json          # dsh.bundle manifest，dsh plugin add 靠它识别
├── cordis.patch.yml      # 插件在 profile 里的那一行
├── lib/index.js          # 20 个工具的定义，纯 ESM，无构建步骤
├── scripts/
│   ├── bctl.ps1          # CLI 主程序（UTF-8 BOM，PS 5.1 必需）
│   ├── BctlLib.ps1       # Win32 P/Invoke + UI Automation + DPI 感知
│   └── bctl.cmd
├── bridge/
│   ├── server.ps1        # 本地 TCP 桥（TcpListener，不需要管理员）
│   └── bridge.user.js    # 篡改猴脚本（eval + 无 eval 词表）
├── assets/               # README 的图
└── references/           # 命令手册、排障

两个踩过的坑，写在这里省得别人再踩：

• PowerShell 5.1 读 UTF-8 无 BOM 的脚本会按 GBK 解码，中文注释的字节可能拼出反引号，把下一行并进注释——变量赋值就这么被静默吞掉了。所有 .ps1 必须存成 UTF-8 with BOM。
• 同一个 pid 有多个顶层窗口，按 pid 找窗口要按面积挑最大的，否则会绑到工具提示那种 146×21 的小窗口上。

---

License

MIT