DSH browser-use 插件

English | 简体中文

@local/browser-use-native 是 DSH（DeepSeek Harness）的 Host 侧浏览器插件： 在 Host 进程内通过 Playwright 驱动真实 Chromium，向模型暴露 17 个 browser_* 工具。 工具通过 ctx.tools 注册，配置只包含浏览器参数，Playwright 负责发现可用的 Chromium。

它面向“能真正操作网页”的 Agent：用可裁剪的无障碍树（AX tree）快照代替整页 HTML， 给可操作节点分配跨快照稳定的 uid，再通过 uid 点击、填写、拖拽、下载。

包名保留 @local/ 作用域：这是作为本地 bundle 通过 link: 安装的 DSH 插件， 不发布到 npm。private: true 也能防止误发布。

特性

• 17 个工具：导航、可裁剪快照、点击、填写、悬停、拖拽、按键、上传、原生下载、脚本执行、 多页面、console、network、弹窗处理。
• 每个 live Agent 一个浏览器：首次浏览器工具调用时惰性启动，同一 Agent 的工具调用串行执行， Agent 释放时关闭。
• a11y 快照：逐 frame 读取 Chrome Accessibility Tree，给可操作节点分配稳定 uid； 支持 selector / uid 聚焦，以及字符、行、深度上限。
• 稳定 uid：uid 按 DOM backend node id 分配并在快照间复用；页面导航清空 uid， iframe 导航只清空该 frame；过期 uid 会返回明确错误而不是误点别的元素。
• 动作回退：普通 click 失败后依次尝试命中检测、forced click、关联 label click、脚本 click， 并在响应里注明实际使用的回退方式。
• 原生下载：download 用 context.request（共享 cookie）取响应体，失败回退页面内 fetch； uid 模式捕获 Playwright 的 download 事件，无事件时用链接 href 兜底。
• 截图：可以落盘，也可以作为附件返回给模型。
• 无硬编码路径：相对路径按当前 Session 工作目录解析，~ 展开到用户目录。

安装

要求：DSH（支持 Host bundle 插件）、Node.js >= 20、本机已安装 Chrome 或 Edge。

git clone https://github.com/AythyaCrispus/dsh-browser-use-native.git
cd dsh-browser-use-native
npm install --omit=dev

然后在 DSH 会话里由插件管理器安装这个目录：

plugin_manager action=install_bundle target=<克隆下来的目录>

插件以 link: 方式注册，因此它使用自己的 node_modules。

更新

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

配置

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

字段	默认	说明
headless	true	false 显示浏览器窗口
channel	chrome	Playwright 的浏览器通道，如 chrome / msedge；设为空则直接尝试自动发现
executablePath	''	可选：指定 Chromium 可执行文件；为空表示自动发现
slowMo	0	每步操作延迟（ms）
viewportWidth	1280	视口宽
viewportHeight	800	视口高
actionTimeoutMs	5000	点击/填写/悬停等单步超时
navigationTimeoutMs	30000	导航超时
dialogPolicy	manual	manual / auto-dismiss / auto-accept
dialogTimeoutMs	5000	manual 模式下弹窗兜底处理时间

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

运行时行为

• 每 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，截断时在末尾报告。
• 动作回退：见上文；checkbox / radio 的 fill 同样有 label / 脚本回退。
• 等待：wait_for 轮询所有 frame 的文本、selector、JS 谓词，支持 textGone 与 visible / hidden / attached / detached 状态。
• 观察：console / network 由 Playwright 事件采集；主 frame 导航时归档到 preserved 缓冲区， 默认列表只显示“上次导航之后”的条目。
• 弹窗：dialog 事件被保留给 handle_dialog；manual 模式下超时 watchdog 会自动 dismiss， 避免串行客户端卡死。
• 截图：给了 filePath 就落盘；否则通过 ctx.attachments.saveImages 存成附件并返回 image content block。没有附件服务时返回提示，要求显式传 filePath。
• 系统提示：只在 take_snapshot 工具对当前 Agent 可见时注入浏览器操作说明。

工具

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>。

自测

node selftest.mjs

自测不依赖 DSH：它启动本地 HTTP server 和无头 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 个工具方法是否齐全。共 49 项检查， 产物写在 artifacts/。

文件

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

排错

现象	处理
playwright-core is not installed	在仓库目录执行 npm install --omit=dev
Could not launch a Chromium browser	安装 Chrome/Edge，或在 patch 里设置 channel / executablePath
工具列表中没有 browser_*	确认插件已安装并启用；改过 JS 后停用再启用或重启 DSH
截图没有图片	当前模型路由不接受图片，或没有 attachment 服务；传 filePath 落盘
改了代码但行为没变	重启 DSH，或停用再启用插件，才能重新导入 linked package 的 JS

安全边界

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

许可

MIT