dsh-builtin-browser

<p align="center">_{中文 · <a href="README.en.md">English</a>}</p> <h3 align="center">为 DeepSeek Harness 生态打造的<b>共享真实浏览器</b>插件（装好即用，人机同页）</h3> <h4 align="center">agent 驱动一个真实、可见、可随时人工接管的浏览器——人与 agent 操作的是<b>同一个页面</b>。</h4>

文档

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

这是什么

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

• 真实视图,而非转播:浏览器是原生 WebContentsView,用户直接看到 agent 在做什么,随时可以上手接管;
• 装好即用:有桌面外壳时嵌入外壳视图;纯 dsh web 也能自托管——插件自己拉起一个 Electron 窗口,不需要任何额外配置;
• 一插件即一套工具:安装后 agent 自动获得 33 个 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 截图,可存文件交给视觉模型

完整清单见工具参考。

主要功能

  <h3>共享真实浏览器</h3>
  <p>原生视图而非无头截屏。用户与 agent 操作同一个页面:用户能看到每一步,随时接管;agent 驱动的就是用户眼前那个窗口。</p>
  <h3>DOM 级驱动,框架友好</h3>
  <p><code>browser_snapshot</code> 返回带编号的交互元素;<code>browser_execute</code> 在页面内执行 JS(受控输入用原生 setter + input/change 事件),React/Vue 页面也能可靠交互。</p>
  <h3>多标签会话</h3>
  <p>并行打开 URL,查看/切换/关闭/重置标签,每个会话的状态独立保持。</p>
  <h3>多格式内容</h3>
  <p>以 html / markdown / txt / json 抓取页面,支持 CSS selector 限定、字符上限与超时控制。</p>
  <h3>任务级会话隔离</h3>
  <p>每个 DSH 任务(会话)拥有独立的浏览器会话(独立标签页与历史),并发任务互不抢页面、互不污染;同一任务内多次调用复用同一会话。</p>
  <h3>登录态持久化</h3>
  <p><code>browser_auth</code> 导出/恢复 cookie,重启后登录态不丢;自托管实例的 cookie 本身也落盘持久。</p>
  <h3>人机验证识别</h3>
  <p>自动检测 Cloudflare / reCAPTCHA / hCaptcha / Turnstile 等挑战(<code>browser_challenge</code>,快照也会标注),提示人工在共享窗口完成,不再盲目重试。</p>
  <h3>批量表单填充</h3>
  <p><code>browser_fill</code> 一次填写多个字段:按选择器/名称/标签匹配,支持受控输入、下拉、单选/复选,可选提交;单个字段失败不影响其余字段。</p>
  <h3>操作历史与回放</h3>
  <p><code>browser_history</code> 记录操作日志(打开/执行/点击/输入/填表/下载/登录),<code>browser_replay</code> 可按序号回放某一步。</p>
  <h3>带登录态下载</h3>
  <p><code>browser_download</code> 在页面上下文内携带会话 cookie 拉取文件并落盘,登录后才能访问的内容也能直接下载。</p>
  <h3>安全限制</h3>
  <p><code>browser_restrict</code> 限制允许的浏览器动作(白名单),防止 agent 误点、误导航;只读工具(snapshot/content/screenshot)不受限。</p>
  <h3>截图即存即读</h3>
  <p><code>browser_screenshot</code> 支持 <code>savePath</code> 直接落盘 PNG,交给视觉模型(modlens 等)做基于视觉的元素定位。</p>

为什么选它

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

工具参考

…