wqty123/dsh-browser

文档

目标	入口
了解插件为什么存在、与无头方案的区别	为什么做共享真实浏览器
安装、配置与日常使用	用户指南
全部 20 个工具的参数、输出与示例	工具参考
了解 seam / provider / 工具三层与自托管实现	架构说明
查看全部文档与 README 分工	文档索引

这是什么

dsh-builtin-browser 给 DeepSeek Harness 提供浏览器能力:

• 真实视图,而非转播:浏览器是原生 WebContentsView,用户直接看到 agent 在做什么,随时可以上手接管;
• 装好即用:有桌面外壳时嵌入外壳视图;纯 dsh web 也能自托管——插件自己拉起一个 Electron 窗口,不需要任何额外配置;
• 一插件即一套工具:安装后 agent 自动获得 20 个 browser_* 工具(打开、查看、操作、填表、截图、下载、登录态管理……)。

一句话:安装插件 = 获得一个与用户共享、可被 agent 驱动的真实浏览器。

快速开始

# 方式一:从 npm 安装(已发布)
dsh plugin --profile web add dsh-builtin-browser

# 方式二:从源码目录安装(独立仓库,一插件一仓库)
dsh plugin --profile web add <本仓库路径>

安装后,agent 即可使用浏览器工具,例如:

想做什么	用哪个工具	说明
打开页面	browser_open	打开 URL,返回带编号元素的快照
了解页面	browser_snapshot	输入框/按钮/链接的编号清单,可据此定位
操作页面	browser_execute	在页面里执行 JS(原生 setter,框架友好)
填写表单	browser_fill	一次填写多个字段,可选提交
看到页面	browser_screenshot	PNG 截图,可存文件交给视觉模型

完整清单见工具参考。

主要功能

为什么选它

• 装好即用,零配置:不需要桌面外壳、不需要额外启动步骤;纯 dsh web 环境自托管拉起 Electron 窗口,browser_* 工具照常可用。
• 人机协同,互不干扰:用户能看到并接管 agent 的每一个动作;任务级会话隔离让多个并行任务各自拥有独立的标签页与历史。
• 面向真实世界的自动化:人机验证识别、登录态持久化、批量填表、带登录态下载、操作回放、动作限制——把"真实浏览器"变成可靠的 agent 能力。
• 可测试、可替换的架构:provider 与 Electron 通过 ElectronBrowserViewHost 接缝解耦,同一套工具层未来可对接无头转播 provider,无需改动模型侧。

工具参考

工具	用途	守卫
browser_open	打开 URL(可选新标签),返回页面快照	✅
browser_snapshot	交互元素(输入框/按钮/链接)带编号清单	–
browser_execute	在页面执行 JS;参数以 arguments[0..n] 传入	✅
browser_content	以 html / markdown / txt / json 抓取页面(selector、maxChars、timeoutMs)	–
browser_click	按视口坐标点击(配合截图做视觉定位)	✅
browser_type	向聚焦元素输入文本(CDP Input.insertText)	✅
browser_fill	批量填充表单(选择器/名称/标签匹配,受控输入、下拉、单选/复选,可选提交)	✅
browser_screenshot	PNG 截图,可选 fullPage 与 savePath	–
browser_list_tabs	当前会话的标签列表	–
browser_switch_tab	按 id 切换标签(自托管下同步切换可见视图)	✅
browser_close_tab	按 id 关闭标签;关闭活动标签后激活下一个	–
browser_reset	关闭本任务所有标签,回到一个空白标签	✅
browser_session	查看本任务的浏览器会话与标签	–
browser_reset_session	关闭并重建本任务的浏览器会话	✅
browser_history	操作日志(最新在后),含成功/失败与结果摘要	–
browser_replay	按序号回放某一步(navigate/execute/click/type)	✅
browser_download	带会话 cookie 下载 URL 到本地文件(上限 256MB)	✅
browser_auth	导出/恢复 cookie(登录态持久化,自托管可用)	✅
browser_challenge	检测人机验证(CAPTCHA / Cloudflare / reCAPTCHA / hCaptcha / Turnstile)	–
browser_restrict	限制允许的浏览器动作(白名单;空列表解除)	–

「守卫」列:打 ✅ 的动作受 browser_restrict 白名单约束;只读工具(snapshot/content/screenshot/list_tabs/session/challenge/history)永不拦截。

操作纪律(点击/填表)

• 优先用 DOM 语义而非坐标:表单提交优先 form.requestSubmit();点击优先 element.click();坐标点击是最后手段。
• 选中正确的元素:页面常有隐藏副本(如移动端按钮),用 browser_execute 过滤可见元素(getBoundingClientRect() 宽高 > 0、getComputedStyle 非 display:none),再取坐标。
• 取坐标后立即点击:中间不要插入其他操作(填表、滚动会移动元素,旧坐标立即失效)。
• 点击前验证命中:document.elementFromPoint(x, y) 确认该坐标确实是目标元素(按钮/链接),再执行真实点击。
• DPR 注意:CDP 输入使用 CSS 像素;高 DPI 屏上若点击落空,用 elementFromPoint 校准,不要盲试坐标。

配置

插件通过 cordis.patch.yml 挂载三行,各行配置:

行	配置项	类型	默认	说明
browser-electron	viewHost	对象	必填	宿主提供的 ElectronBrowserViewHost 实例(通常 !!js ctx.get('electronViewHost'))
browser-electron	httpOnly	布尔	true	仅允许 HTTP(S) 导航;其余协议(如 file:/data:)拒绝(BROWSER_NAVIGATION_BLOCKED)
browser-electron	snapshotMaxElements	数字	60	快照最多收录的交互元素数,超出截断
browser-electron	contentMaxChars	数字	100000	内容抓取默认字符上限
tool-browser	timeoutMs	数字	60000	工具协作超时(ms)
tool-browser	tabTools	布尔	true	是否注册标签管理工具(browser_list_tabs 等)

工作原理

agent (browser_* 工具)
  → ctx.browser (seam, dsh-builtin-browser/browser)
  → dsh-builtin-browser/browser-electron (provider)
  → ElectronBrowserViewHost (由宿主外壳提供)
  → WebContentsView + webContents.debugger (CDP)

• seam 层(browser 行)提供 ctx.browser 服务:provider 注册、会话生命周期、错误码,与具体实现解耦;
• provider 层(browser-electron 行)通过 ElectronBrowserViewHost 接缝操作视图(创建/销毁/显示/sendCommand),由真实外壳用 Electron 对象实现;
• 工具层(tool-browser 行)提供模型侧的 20 个 browser_* 工具,按调用方任务(DSH 会话)维护独立的浏览器会话。

自托管模式:没有桌面外壳时,插件自己拉起一个 Electron 子进程(host-main.js),通过本机 TCP JSON-RPC 驱动,窗口标题 dsh-browser。子进程崩溃会自动重启;截图优先走 Electron 原生 capturePage(CDP 截图在多视图下会挂起),并自动选择环境中最新版本的 Electron(33.x 有合成器缺陷,建议 ≥ 40)。

Electron 定位顺序:① require('electron')(peer 依赖)→ ② ELECTRON_PATH(显式覆盖)→ ③ DSH 安装锚点与 pnpm 虚拟仓库中版本最新者。找不到时工具会报清晰的错误提示。

与桌面外壳的分工

浏览器可见视图、浏览器列布局、列与视图的对齐都属于宿主外壳(如 dsh 的 apps/desktop),不在本插件内。本插件只消费外壳提供的 electronViewHost,负责 seam、provider 与工具。没有配套外壳时插件自托管,功能照常可用。

环境要求

• DeepSeek Harness(dsh)且安装了 web profile
• Electron 运行时(可选 peer 依赖):桌面外壳自带;纯 dsh web 下插件自动定位 Electron 二进制(见上,建议 ≥ 40)

验证过的版本

组件	版本
DeepSeek Harness(dsh)	0.1.0-rc.5
Electron	43.4.0(推荐 ≥ 40;33.x 存在合成器缺陷)
Node.js	22.20.0
dsh-builtin-browser	0.1.11
操作系统	Windows 10 (10.0.26200)

插件声明 electron >= 30;当前仅在 Windows 环境实测(macOS/Linux 未验证,暂不承诺)。

已知限制

• 截图仅 PNG(CDP JPEG 在 Electron 43 上挂起);JPEG 等待非 CDP 转换路径。
• 自托管截图优先走 Electron 原生 capturePage(CDP captureScreenshot 在多视图下会挂起);截图前自动把目标标签置顶。
• 部分主机在软件合成下 fullPage 截图不稳定。
• 人机验证(CAPTCHA)无法自动解决:快照会标注检测到的挑战,此时应请用户在共享窗口中人工完成,而不是反复重试。
• 无痕模式(privateMode)未实现:它需要 Electron 的 session 分区能力,属于宿主层,本插件不承诺。
• browser_download 在页面上下文内 fetch(带登录态),受同源/CORS 约束;单文件上限 256MB。
• browser_auth 的 cookie 往返不保留 hostOnly/sameSite 字段(host-only cookie 恢复后变成 domain cookie);仅自托管浏览器可用。
• 自托管浏览器子进程崩溃后会自动重启,但崩溃前已打开的会话视图已失效,调用 browser_reset_session 重建即可。
• 本插件不含浏览器列 UI——那是宿主外壳的配套,别把"浏览器列"当成插件能力。

开发

# 类型检查 + 构建(lib/)
pnpm run build

# 功能测试:启动本地页面服务器 + Electron probe(见仓库测试脚本)

代码结构:

目录	职责
src/browser/	ctx.browser seam 与全部请求/结果类型
src/browser-electron/	Electron CDP provider、自托管子进程(host-main.ts)与 RPC 层
src/tool-browser/	模型侧 browser_* 工具
src/types/	electron 环境类型(shim,避免强制依赖 electron 类型)

特别感谢

特别感谢 DeepSeek Harness 原始仓库 与 DeepSeek AI 团队:本插件的 seam、工具运行时与插件体系都构建在这个项目之上。

同时感谢 Cordis 提供的插件化基础,以及所有参与讨论、测试、反馈和插件开发的社区成员。

License

本项目遵循 MIT License。

本项目是 DeepSeek Harness 的社区插件,并非 DeepSeek 官方产品。