DSH browser-use 插件

dsh-browser-use-native 在 DSH Host 进程内通过 Playwright 提供 17 个浏览器工具。 工具通过 ctx.tools 注册，模型侧名字为 browser_<name>（例如 browser_take_snapshot）。 配置只包含浏览器参数；Playwright 负责发现可用的 Chromium。

功能

• 17 个工具：导航、可裁剪快照、点击、填写、悬停、拖拽、按键、上传、原生下载、脚本执行、多页面、 console、network、弹窗处理。
• 每个 live Agent 一个 Chromium/context：首次浏览器工具调用时惰性启动，同一 Agent 的 工具调用串行执行，Agent 释放时关闭。
• a11y 快照：逐 frame 读取 Chrome Accessibility Tree，给可操作节点分配稳定 uid； 支持 selector/uid 聚焦和字符/行/深度上限。
• 截图可以落盘，也可以作为附件返回给模型。
• 持久化 profile（userDataDir，默认 ~/.dsh/browser-profile）：登录态、cookie、扩展跨会话保留， 可在 Plugins 页里图形化修改。
• 只在 take_snapshot 对当前 Agent 可见时注入浏览器操作说明。

文件

文件	说明
package.json	bundle 清单、dsh.bundle.patch、engines.dsh、playwright-core 依赖、locale/icon 导出
cordis.patch.yml	插入 browser-use-native 行；只含可调参数
index.js	Host 插件入口：17 个工具定义、Config schema、每 Agent 会话管理、附件、系统提示
lib/browser.js	BrowserSession / BrowserTools：Chromium 生命周期、profile、页面、日志、弹窗、动作
lib/client.js	浏览器半侧：Plugins 页里的 profile 目录表单（plugins.row.config 槽）
lib/snapshot.js	AX 树渲染、uid 分配、CDP 注入 data-ba-uid
selftest.mjs	不依赖 DSH 的端到端自测（本地 HTTP 页面 + 真实 Chromium）
locale/en.json / locale/zh.json	插件管理器里的标题与描述
icon.svg	插件图标
LICENSE	MIT

安装 / 更新

从 npm 安装（推荐）

通常不需要额外安装：插件优先使用系统 Chrome，没有 Chrome 时回退到 Windows 自带的 Edge； 两者都没有时才需要处理（默认给出明确提示，或设置 autoDownloadBrowser: true 自动下载 Playwright Chromium）。也可以随时在配置里指定 executablePath。

在 DSH 的 Plugins 页点 Add plugin，填入包名：

dsh-browser-use-native

或者用 CLI 装进某个 profile（desktop 由桌面应用独占管理，只能用插件页）：

dsh plugin --profile <profile> add dsh-browser-use-native

安装/更新后以 plugin_manager（或插件页）返回的 application 为准；Host 模块已经加载时需要重启 DSH，或在插件管理器里停用再启用该插件。

从本地目录安装（开发）

在 DSH 会话里由插件管理器执行：

plugin_manager action=install_bundle target=<本仓库>/dsh-plugin

首次 clone 后先在 dsh-plugin/ 里安装 Node 依赖：

cd dsh-plugin
npm install --omit=dev

这个目录是 link: 到 profile 的；linked package 使用自己的 node_modules。

• 改 cordis.patch.yml 里的配置：HMR 会重组并生效。
• 改 index.js / lib/*.js：Host 已经加载了模块，需要重启 DSH，或在插件管理器里先停用 再启用该插件（set_plugin enabled=false/true）以重新导入。

配置

所有可调值都在 patch 的 config 里；插件激活时会校验（非法值会让该行加载失败并给出原因）。

字段	默认	说明
headless	true	false 显示浏览器窗口
channel	''	优先使用的浏览器通道，如 chrome / msedge；空串表示按 Chrome → Edge → Playwright Chromium 自动选择
executablePath	''	可选：指定 Chromium 可执行文件；为空表示自动发现
autoDownloadBrowser	false	系统里没有 Chrome/Edge 时，是否自动下载 Playwright Chromium（约 300 MB）
userDataDir	~/.dsh/browser-profile	持久化 profile 目录（登录态/cookie/扩展），首次使用自动创建；设为空串则每次用临时 profile
slowMo	0	每步操作延迟（ms）
viewportWidth	1280	视口宽
viewportHeight	800	视口高
actionTimeoutMs	5000	点击/填写/悬停等单步超时
navigationTimeoutMs	30000	导航超时
dialogPolicy	manual	manual / auto-dismiss / auto-accept
dialogTimeoutMs	5000	manual 模式下弹窗兜底处理时间

userDataDir 支持 ~、%USERPROFILE%（Windows）和 ${HOME} 这类环境变量写法；相对路径按 Host 工作目录解析。 默认值用可移植的 ~ 形式：Windows 解析成 %USERPROFILE%\.dsh\browser-profile，macOS/Linux 解析成 $HOME/.dsh/browser-profile，所以同一份 patch 换机器也能用。

图形化设置

userDataDir 是 volatile 字段，可以在 GUI 里改，不用手写 YAML：

1. 侧边栏打开 Plugins，进入 dsh-browser-use-native 这个 bundle；
2. 在该行上点 Configure（行页面）；
3. 填 profile 目录，保存。留空表示临时 profile，恢复默认回到 ~/.dsh/browser-profile。

保存会写进当前 profile 的 cordis.patch.yml，并触发插件回收现有浏览器；下一次浏览器工具调用就使用新目录，不需要重启 DSH。页面右下角会显示「当前生效」的值，方便确认没有被更高优先级的 patch 覆盖。

实现方式是：Host 导出 Config（userDataDir 标了 .volatile()），client 半侧（lib/client.js）注册进插件管理器的 plugins.row.config 槽。普通字段（视口、超时等）不会出现在表单里，仍在 YAML 里改。

浏览器发现顺序：executablePath → channel → chrome → msedge → Playwright 管理的 Chromium。 失败时会列出每次尝试的错误摘要，并提示安装 Chrome/Edge、配置 channel/executablePath，或打开 autoDownloadBrowser。因此换机器不需要改 patch 里的任何路径。

profile 与浏览器族的关系：

• 新 profile（目录不存在或为空）：按上面的顺序逐个尝试；Chrome 没装而 Edge 在，就直接用 Edge。 成功后在 profile 目录写入 .dsh-browser.json，记录使用的浏览器族。
• 已有 profile：只使用 .dsh-browser.json 记录的浏览器族，避免 Chrome 和 Edge 互相迁移/损坏 同一份 profile。要换浏览器，请把 userDataDir 指向新的或空的目录（见下面提示）。
• 已有数据但没有标记（例如手工复制的日常 profile）：只尝试配置的 channel/executablePath， 不再猜其它浏览器。Edge 的 profile 副本必须显式写 channel: msedge。
• 一个都没有时：默认返回明确错误，不会静默卡住。打开 autoDownloadBrowser 会先下载 Playwright Chromium（约 300 MB，共享 ms-playwright 缓存）；下载 90 秒仍未完成时本次调用先返回“稍后重试”， 下载在后台继续。CDN 被墙时可给 Host 设置 PLAYWRIGHT_DOWNLOAD_HOST 镜像，或直接装 Chrome/Edge。
• 配置了 channel 但 profile 已由另一个浏览器创建时，工具结果会说明正在复用 profile 的浏览器族。

复用日常 Chrome/Edge 的 profile

默认的 ~/.dsh/browser-profile 是一个独立的 Chrome profile：干净、可写、登录一次就长期保留。 想直接带上日常浏览器的登录态，再把它指到日常 profile 的副本：

- id: browser-use-native
  config:
    channel: chrome
    headless: false
    userDataDir: '~/.dsh/browser-profile-daily'

要点：

• 不要指向正在使用的默认 profile。Chrome 136+ 拒绝在默认 User Data 目录上启用远程调试 （Playwright 正是通过调试通道驱动浏览器），运行中的 Chrome 也会锁住 cookie/LevelDB。
• 复制方法：关掉 Chrome，把 %LOCALAPPDATA%\Google\Chrome\User Data 整个复制到目标目录。 副本里 Local State 与 Default\Network\Cookies 齐全时多数登录态可直接复用；受 Chrome 127+ 的 App-Bound Encryption 影响，个别 cookie 可能解不开，在副本上手动登录一次即可。
• 一个 profile 目录同时只能有一个浏览器实例。插件按 Agent 各起一个会话，第二个 Agent 抢同一 目录时会自动退回临时 profile，并在该次工具结果开头说明原因。需要多 Agent 就各自配独立目录。
• Edge 同理：channel: msedge + Edge 的 User Data 副本。已有数据的 profile 只使用自己的浏览器族 （profile 目录绑定浏览器家族，用 Edge 打开 Chrome 的 profile 会被迁移甚至损坏）；新目录则可以让 插件自动选 Edge，不必显式写 channel。
• 该目录等同于你的登录凭据，不要提交进仓库，也不要共享给不可信插件。

运行时行为

• 每 Agent 一个浏览器：第一次浏览器工具调用时惰性启动；同一 Agent 的工具调用串行执行； Agent 释放时关闭它拥有的 context/browser；插件卸载时关闭全部。
• 快照：逐 frame 调 Accessibility.getFullAXTree，渲染为文本并给可操作节点分配 uid； uid 通过 CDP 写成 data-ba-uid，同时登记进 window.__baUidLookup（evaluate_script 也能取到 shadow DOM 里的元素）。同进程 iframe 走 page 级 CDP + frameId，OOPIF 走独立 CDP session。
• 快照裁剪：selector 在 frame 内打临时标记，经 CDP DOM 解析成 backend node id，只渲染 该 AX 子树；uid 直接复用已有 backend node id。默认 20000 字符 / 1200 行上限，支持 maxDepth、maxChars、maxLines、includeFrames，截断时在末尾报告。
• 稳定 uid：uid 按 DOM backend node id 分配并在快照间复用；未变化的元素不会因为无关 DOM 更新而换 uid。页面级导航清空 uid，iframe 导航只清空该 frame。动作前检查节点是否还在， 节点消失时返回明确提示。
• 动作回退：普通 click 失败后，依次尝试命中检测、forced click、关联 label click、脚本 click；响应会注明实际使用的回退方式。checkbox/radio 的 fill 同样有 label/脚本回退。
• 原生下载：download 用 context.request（共享 cookie）取 URL 响应体，失败回退页面内 fetch；uid 模式捕获 Playwright 的 download 事件，无事件时用链接 href 兜底。
• 等待：wait_for 轮询所有 frame 的文本/selector/JS 谓词，支持 textGone 与 visible/hidden/attached/detached，不再依赖单次 waitForFunction 的旧文本。
• 观察：console / network 由 Playwright 事件采集；主 frame 导航时归档到 preserved 缓冲区， 默认列表只显示“上次导航之后”的条目。
• 弹窗：dialog 事件被保留给 handle_dialog；manual 模式下超时 watchdog 会自动 dismiss， 避免串行客户端卡死。
• 截图：给了 filePath 就落盘；否则通过 ctx.attachments.saveImages 存成附件并返回 image content block。没有附件服务时返回提示，要求显式传 filePath。
• 路径：filePath 相对路径按当前 Session 工作目录解析，~ 展开到用户目录；插件本身没有 任何固定 workspace 路径。
• 系统提示：只在 take_snapshot 工具对当前 Agent 可见时注入浏览器操作说明。

自测

node dsh-plugin/selftest.mjs

自测会启动本地 HTTP server 和 headless Chrome，覆盖 navigate、snapshot、selector/uid 聚焦 快照、稳定 uid、fill（input/select/隐藏 checkbox）、hover、覆盖层点击回退、click、wait_for （text/textGone/selector/谓词/iframe）、原生下载（URL 与 uid 点击）、evaluate_script、 upload_file、iframe、drag、press_key、截图（页面/元素/落盘）、console、network、多页面、 dialog、过期 uid 失效，以及 17 个工具方法是否齐全。共 54 项检查，产物写在仓库 artifacts/。

工具

17 个工具：click、download、fill、hover、drag、press_key、upload_file、evaluate_script、 navigate_page、take_snapshot、take_screenshot、wait_for、list_pages、select_page、 list_console_messages、list_network_requests、handle_dialog。暴露给模型的名字统一为 browser_<name>。

排错

现象	处理
playwright-core is not installed	本地 link: 安装时在 dsh-plugin/ 执行 npm install --omit=dev；从 npm 安装会自带依赖
Could not start a browser	装 Chrome/Edge；或在 patch 里设 channel/executablePath；或打开 autoDownloadBrowser 让插件下载 Chromium
The profile … is bound to channel …	该 userDataDir 由另一种浏览器创建；装回该浏览器，或换一个新的/空的 userDataDir
The profile … already contains browser data	手工复制的 profile 没有浏览器标记；显式设成它所属的 channel（如 msedge），或换新目录
Downloading Playwright Chromium took longer than 90s	下载仍在后台继续，稍后重试；网络受限时给 Host 设 PLAYWRIGHT_DOWNLOAD_HOST 镜像，或直接装 Chrome/Edge
Could not open the browser profile at …	关掉占用该目录的 Chrome/Edge；确认 userDataDir 不是默认 User Data
Plugins 页里没有 Configure	浏览器半侧没加载：确认 package.json 里有 dsh.client 与 ./client 导出，然后重启 DSH
表单显示「保存失败」	该配置被更高优先级的 patch 覆盖，或路径非法；看「当前生效」确认实际值
工具结果开头提示 profile 已被占用	同一 userDataDir 只能有一个浏览器实例，本次已退回临时 profile；给每个 Agent 配独立目录
工具列表中没有 browser_*	确认插件已安装并启用；改过 JS 后停用再启用或重启 DSH
截图没有图片	当前模型路由不接受图片，或没有 attachment 服务；传 filePath 落盘
改了代码但行为没变	重启 DSH，或停用再启用插件，才能重新导入 linked package 的 JS

安全边界

这是 Host 进程内插件，拥有 Host 的进程权限；它启动的 Chromium 不受 workspace 文件沙箱约束。 只安装可信来源的插件代码；浏览器会按模型指令访问页面并执行 evaluate_script 中的 JavaScript。