前言¶

给 DSH agent 接浏览器时，常见路径是两类：让模型猜 CSS 选择器，或者把整页 DOM 交给模型处理。前者容易失配，后者会扩大上下文。dsh-browser-playwright 把模型可见的交互面收敛为 accessibility snapshot 和稳定元素 ref，由 Playwright 在底层驱动真实浏览器。

这是什么¶

dsh-browser-playwright 是面向 DeepSeek Harness 的浏览器能力插件，定位为 Playwright-powered browser capability for DeepSeek Harness。GitHub 仓库路径为 ChenyuHeee/dsh-browser-playwright，许可证为 MIT。它让 agent 在一次 harness session 内使用一个 browser session，围绕稳定 ref 完成导航、交互、截图和结构化抽取。

核心功能¶

• 使用 Playwright 驱动真实浏览器。
• 通过 accessibility snapshot 暴露元素，并提供稳定 ref。
• 不做 CSS selector 猜测，不输出完整 DOM。
• 每个 harness session 对应一个 browser session。
• 支持标签页管理、截图作为 durable image attachments、结构化抽取，以及 gated JavaScript evaluation。
• 提供 17 个 browser_ 前缀的工具 schema。
• Playwright provider 会自动探测 chromium、chrome、msedge、edge 渠道。
• 其他 provider 可以注册到 ctx.browser，工具 schema 保持不变。

安装¶

1、给目标 profile 添加插件：

dsh plugin --profile <name> add dsh-browser-playwright

这一步把插件添加到指定 profile。

浏览器二进制¶

provider 会按 chromium、chrome、msedge、edge 的顺序自动探测可用渠道。

如果想使用 Playwright 管理的 Chromium，执行：

npx playwright-core install chromium

这条命令安装 Playwright 可使用的 Chromium。

在受限网络下，可以设置下载主机后再安装：

PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright npx playwright-core install chromium

这一步通过 PLAYWRIGHT_DOWNLOAD_HOST 指定下载源。

典型用法¶

插件默认使用 browser_ 作为工具前缀。下面先打开页面，再根据快照中的 ref 执行点击。

先调用 browser_navigate 打开一个 http 或 https URL：

browser_navigate
url: https://example.com/

browser_navigate 只接受 http/https URL，并返回快照。

快照中会列出 URL、标题、可见元素和 ref= 标记，示例如下：

URL: https://example.com/
Title: Example Domain
Refs: 12

- navigation "Main"
  - link "Home" [ref=e1] -> /
  - button "Go" [ref=e2]
- heading "Welcome" [level=1]
- textbox "Search" [ref=e3]

不可见内容会被排除。快照结果有边界，截断情况会在结果中标记。

在快照后，可以调用 browser_click 并使用 ref: e2：

browser_click
ref: e2

这一步基于最新快照中的元素引用执行点击。

插件还提供这些 browser_ 工具：

browser_snapshot
browser_click
browser_fill
browser_press
browser_scroll
browser_back
browser_forward
browser_wait
browser_tabs
browser_open_tab
browser_switch_tab
browser_close_tab
browser_screenshot
browser_extract
browser_evaluate
browser_close

它们覆盖快照、交互、历史导航、等待、标签页管理、截图、结构化抽取、受控 JavaScript 执行和关闭浏览器。

配置¶

可以通过配置项调整导航和工具行为。

限制导航域名时，使用 allowedDomains：

allowedDomains:
  - example.com

该配置项用于约束 browser_navigate 可访问的域名。

启用 browser_extract 时，需要提供辅助模型路由：

extract:
  provider: <provider>
  model: <model>

browser_extract 要求 extract.provider 和 extract.model；缺少任一项时，会返回可操作的错误。

启用 browser_evaluate 时，需要打开 allowEvaluate：

allowEvaluate: true

browser_evaluate 默认关闭；启用后会执行任意页面 JavaScript，应结合 DSH 的审批或权限策略使用。

适用场景与注意¶

适合已经使用 DSH、希望 agent 操作真实浏览器，并且偏好稳定 ref 而非选择器猜测的场景。它也适合需要保留浏览器会话状态、使用截图附件、或在 ctx.browser 上替换 provider 的流程。

安装前应检查源码、许可证和网络出口。插件按 DSH 插件方式加载，运行时会以当前 dsh 进程权限执行；启用 browser_evaluate 或放宽 allowedDomains 时，需要更严格地限制可用能力。

已知限制¶

• Selector-free 不等于 vision-free：基于 accessibility tree 的交互可能覆盖不到纯视觉控件，例如 canvas、WebGL、自定义绘制控件；此时可用 browser_screenshot 加图像能力模型作为回退。
• 跨域 iframe 会显示为没有 ref 的叶子 (frame) 节点；同域 frame 会遍历到两层。
• browser_navigate 只支持 http 和 https。
• browser session 会保留 cookies、storage 和登录状态，但只在一个 harness session 内有效。
• 工具 schema 是静态的；浏览器工具结果随页面变化，可能影响 KV cache 复用。

结语¶

dsh-browser-playwright 把浏览器交互收敛到可访问性快照和稳定 ref 上，减少选择器猜测和整页 DOM 带来的不确定性。它保留 ctx.browser 这个接入点，让其他 provider 可以在同一工具 schema 下扩展。

社区目录页：https://www.skillhub.cn/plugins/ChenyuHeee/dsh-browser-playwright
GitHub：https://github.com/ChenyuHeee/dsh-browser-playwright