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。
No comments yet. Be the first to write one.