前言¶
在 DSH（DeepSeek Harness）里做能真正操作网页的 Agent，常见做法是向模型暴露浏览器工具。若把整页 HTML 直接塞进上下文，体积大、噪声多，模型也容易点错元素。不少实现依赖 CSS 选择器或坐标，页面一改或跨快照就容易失效。
dsh-browser-use-native（GitHub：AythyaCrispus/dsh-browser-use-native）是 Host 侧插件：在 Host 进程内用 Playwright 驱动本机 Chromium，向模型注册 17 个 browser_* 工具。它用可裁剪的无障碍树（AX tree）快照代替整页 HTML，给可操作节点分配跨快照相对稳定的 uid，再通过 uid 完成点击、填写、拖拽、下载等动作。维护者为 AythyaCrispus，分类为联网工具；包名 @local/browser-use-native，当前版本 0.3.0，MIT 许可。
这是什么¶
@local/browser-use-native 通过 ctx.tools 注册工具，配置只包含浏览器参数；Playwright 负责发现可用的 Chromium。包名保留 @local/ 作用域，作为本地 bundle 以 link: 方式安装，不发布到 npm。
面向场景可以概括为：需要「能操作真实网页」的 Agent——导航、快照、交互、观察 console/network、多页面与弹窗处理，并在 Host 内与 DSH 会话生命周期对齐（每个 live Agent 一个浏览器实例）。
核心功能¶
17 个 browser_* 工具¶
暴露给模型的名称统一为 browser_<name>，共 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。能力覆盖导航、可裁剪快照、点击、填写、悬停、拖拽、按键、上传、原生下载、脚本执行、多页面、console、network、弹窗处理。
无障碍快照与稳定 uid¶
快照逐 frame 读取 Chrome Accessibility Tree，渲染为文本并为可操作节点分配 uid。uid 按 DOM backend node id 分配并在快照间复用；页面导航会清空 uid，iframe 内导航只清空该 frame。过期 uid 会返回明确错误，而不是误点其他元素。支持用 selector 或 uid 聚焦子树，以及字符、行、深度上限（默认约 20000 字符 / 1200 行，可配 maxDepth、maxChars、maxLines、includeFrames）。
运行时与会话¶
每个 live Agent 在首次浏览器工具调用时惰性启动浏览器；同一 Agent 的工具调用串行执行，Agent 释放时关闭。动作在普通 click 失败时会依次尝试命中检测、forced click、关联 label click、脚本 click，并在响应里注明实际回退方式。原生 download 优先用 context.request（共享 cookie）取响应体，失败可回退页面内 fetch；uid 模式可捕获 Playwright 的 download 事件。截图可落盘，也可通过附件返回给模型。相对路径按当前 Session 工作目录解析，~ 展开到用户目录。
依赖与环境¶
要求 Node.js >= 20，本机已安装 Chrome 或 Edge；依赖 playwright-core 1.64.1。浏览器发现顺序为：executablePath → channel → chrome → msedge → Playwright 管理的 Chromium。
安装与启用¶
官方 README 给出的步骤如下（需支持 Host bundle 插件的 DSH）。
先获取代码并安装生产依赖：
git clone https://github.com/AythyaCrispus/dsh-browser-use-native.git
cd dsh-browser-use-native
npm install --omit=dev
在 DSH 会话中由插件管理器安装该目录（target 为克隆后的路径）：
plugin_manager action=install_bundle target=<克隆下来的目录>
插件以 link: 方式注册，使用自己的 node_modules。安装或更新后以 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 模式下弹窗兜底处理时间 |
修改 cordis.patch.yml 后 HMR 会重组并生效；修改 index.js 或 lib/*.js 后需重启 DSH，或在插件管理器中先停用再启用（set_plugin enabled=false/true）以重新导入。
典型用法与自测¶
工作流上通常是：用 browser_navigate_page 打开目标 URL，用 browser_take_snapshot 获取带 uid 的快照，再按 uid 调用 browser_click、browser_fill 等；需要等待时用 browser_wait_for；观察行为时用 browser_list_console_messages、browser_list_network_requests。系统提示仅在 take_snapshot 对当前 Agent 可见时注入浏览器操作说明。
不依赖 DSH 的端到端自测可在仓库根目录执行：
node selftest.mjs
自测启动本地 HTTP server 与无头 Chrome，覆盖导航、快照、uid、填写、点击、下载、iframe、多页面、dialog 等，共 49 项检查，产物写在 artifacts/。
适用场景与注意¶
适合需要在 DSH Host 内、以真实 Chromium 操作网页的 Agent 开发：表单填写、多步导航、文件上传与下载、跨 frame 交互、多标签页切换等。与「整页 HTML + 脆弱选择器」相比，AX 快照 + uid 更利于控制上下文体积并减少误点。
务必了解安全边界：这是 Host 进程内插件，拥有 Host 的进程权限；启动的 Chromium 不受 workspace 文件沙箱约束，且会按模型指令访问页面并执行 evaluate_script 中的 JavaScript。只应从可信来源安装并审阅源码与 MIT 许可证。常见排错包括：在仓库目录执行 npm install --omit=dev 以解决 playwright-core is not installed；安装 Chrome/Edge 或配置 channel / executablePath 以解决无法启动 Chromium；改过 JS 后需重启或停用再启用插件。
DSH 生态强调「一切皆插件」；社区目录站点与 DeepSeek / 幻方无官方从属关系。若需进一步了解，可查看目录页与仓库 README。
- 目录页：https://www.skillhub.cn/plugins/AythyaCrispus/dsh-browser-use-native
- GitHub：https://github.com/AythyaCrispus/dsh-browser-use-native
