ChenyuHeee/dsh-browser-playwright

dsh-browser-playwright

为 DeepSeek Harness 提供由 Playwright 驱动的浏览器能力：智能体通过带有稳定元素引用的无障碍快照来驱动真实浏览器——无需猜测 CSS 选择器，也无需转储整个 DOM。每个 harness 会话对应一个浏览器会话，支持标签页、作为持久图像附件保存的截图、结构化提取，以及受门控的 JavaScript 求值。

安装

dsh plugin --profile  add dsh-browser-playwright

该 bundle 挂载三行：ctx.browser 接缝（service）、Playwright 提供方（playwright），以及面向模型的工具族（tool）。

浏览器二进制文件

提供方会自动探测 chromium → chrome → msedge → edge 通道；任何已安装的 Chromium 系浏览器均可使用，零下载。若要改用由 Playwright 管理的 Chromium：

npx playwright-core install chromium
受限网络（例如中国大陆）：
PLAYWRIGHT_DOWNLOAD_HOST=https://cdn.npmmirror.com/binaries/playwright npx playwright-core install chromium

或者固定某个二进制文件：在插件配置中设置 launch.executablePath / launch.channel。

工具

默认的 toolPrefix 为 browser_。每个操作都会返回一份新的快照，因此引用始终来自最新的结果。

| 工具 | 用途 |
|---|---|
| browser_navigate | 打开一个 URL（仅限 http/https）并返回快照 |
| browser_snapshot | 对当前页面生成快照：URL、标题、带 ref= id 的可见元素 |
| browser_click | 点击最新快照中某个 ref 对应的元素 |
| browser_fill | 替换输入框的值；下拉选择框按选项标签匹配 |
| browser_press | 在某个元素上按键（Enter、Tab、Escape、ArrowDown 等） |
| browser_scroll | 滚动页面或将某个 ref 滚动到视图中 |
| browser_back / browser_forward | 历史导航 |
| browser_wait | 等待一段有界时长以加载惰性内容 |
| browser_tabs / browser_open_tab / browser_switch_tab / browser_close_tab | 标签页管理 |
| browser_screenshot | 捕获 PNG 并保存为模型可查看的持久图像附件 |
| browser_extract | 结构化提取：自然语言指令 → 一个解析后的 JSON 值 |
| browser_evaluate | 在页面中运行一个 JavaScript 表达式（默认禁用） |
| browser_close | 关闭该会话的浏览器；下次调用会打开一个新的 |

快照示例

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]

随后模型会以 ref: e2 调用 browser_click。不可见内容会被排除，节点和文本上限会限制 token 开销，截断情况会在结果中标记。

配置

所有可调项均可通过配置文件的 cordis.patch.yml 进行补丁式修改（后层按行覆盖前层）。

- id: browser
config:
provider: playwright                # 显式指定提供方
- id: browser-playwright
config:
launch:
channel: chrome                   # 或 chromium / msedge / edge
headless: true
viewport: { width: 1280, height: 800 }
navigationTimeoutMs: 30000
ignoreHTTPSErrors: false
allowedDomains: []                  # 例如 ['github.com'] 限制导航
idleTimeoutMs: 600000               # 空闲上下文在 10 分钟后关闭；0 = 从不
maxSessions: 8                      # 超过此数量时进行 LRU 淘汰
snapshot:
maxNodes: 500                     # 每个快照树的 token 预算
maxNameLength: 120
maxTextLength: 300

- id: browser-tool
config:
toolPrefix: browser_                # 面向模型的工具名称前缀
allowEvaluate: false                # browser_evaluate 开关
maxWaitMs: 60000                    # browser_wait 上限
extract:
provider: deepseek-official       # 可选：启用 browser_extract
model: deepseek-v4-flash
maxInputChars: 20000
maxOutputTokens: 2000

browser_extract 需要一条辅助 LLM 路由（extract.provider + extract.model）；没有它就会以可操作的错误失败。browser_evaluate 在 allowEvaluate: true 之前保持关闭，因为它会执行任意页面 JavaScript。

架构

一个可替换的能力接缝，一个包：

- service — ctx.browser：提供者注册表，具有已配置或自动选择的语义（已配置的 id 必须存在；一个可用提供者会自动选择；多个则需要显式选择）。
- playwright — 提供者：一个共享浏览器，每个调用会话一个 BrowserContext，LRU 淘汰，空闲释放，URL 策略，以及注入的快照引擎。
- tool — 消费者：由 defineTool 构建的工具，其规范值是结构化 JSON，其渲染文本是快照树。

其他提供者（远程浏览器、Browserbase、Steel 等）可以注册到 ctx.browser；工具 schema 保持不变。浏览器会话在工具调用之间持续存在，并在一个 harness 会话内保留 cookie、存储和登录状态。

开发
sh
pnpm install
pnpm test          # 完整套件：在真实 Chrome 上的引擎/动作集成、策略、渲染、
schema 组装，以及下面的真实场景套件
pnpm run build     # tsc → lib/

测试套件

| 套件 | 命令 | 覆盖内容 |
|---|---|---|
| 单元 + 引擎集成 | pnpm test（包含） | 快照渲染、schema 组装、URL 策略、真实 Chrome 上的提供者动作 |
| 真实场景 | pnpm test:scenarios | 在真实本地商店 fixture 上的脚本化代理旅程：带优惠券和验证的访客结账、登录/会话持久化、多标签页研究、懒加载内容、无限滚动、模态对话框、弹窗、截图、策略、所有者隔离、空闲释放、快照预算——在 BrowserSession 层面和面向模型的 ctx.tools.execute 层面（使用伪造的附件/LLM 服务） |
| 实时冒烟测试 | pnpm test:live | 针对真实互联网（example.com、Wikipedia REST）的可选检查。除非设置 DSH_BROWSER_LIVE=1，否则跳过；不属于 CI 的一部分 |

场景测试套件是该插件最贴近真实的测试：它们像智能体一样驱动浏览器——快照、查找 ref、执行操作、重新快照——因此同时也可作为模型体验的可执行文档。

从 DeepSeek Harness 源代码检出中，通过 TypeScript 加载此插件：
sh
pnpm dsh web --patch ./browser-plugin/dev.cordis.yml

模型体验

工具 schema

这 17 个工具 schema 通过 ctx.tools.register() 加入系统提示词组装流程；每个都带有一行面向任务的描述。快照结果是有界的：最多 maxNodes 个节点，名称上限为 maxNameLength，并且截断标志是显式的。

Token 影响

每个工具一个工具 schema 块（小且固定），加上每次调用的结果文本，其大小与可见页面成正比，并受 snapshot.maxNodes 以及名称/文本限制的约束。操作会返回新的快照，因此交互流程大致每步消耗一次快照。

KV 缓存影响

工具 schema 在每次注册时是静态的，可保持提示词前缀稳定。结果内容随页面变化，在每次浏览器工具调用后都会使复用失效，这与任何工具结果一样。

浏览器状态

页面状态本身（DOM、cookie、存储）存在于浏览器上下文中，除非通过快照或页面数据结果，否则绝不会进入提示词。

已知限制与推迟的工作

- 无选择器，但并非无视觉 —— 交互基于无障碍树；纯视觉控件（canvas、WebGL、自定义绘制的控件）可能不暴露任何 ref。browser_screenshot + 具备图像能力的模型是后备方案。
- 跨源 iframe 会显示为没有 ref 的叶子 (frame) 节点；同源 iframe 最多向上遍历两层。
- Evaluate 门控是配置，而非审批 —— 启用 allowEvaluate 即信任模型执行任意页面 JavaScript；请将其与 harness 的审批/权限策略组合使用，以实现更严格的控制。
- 仅限 Chromium 系列 —— 不探测 Firefox/WebKit 通道；如果需要其他引擎，提供程序是可替换的。
- Extract 需要专用的模型路由 —— 它不会复用主请求的路由；配置错误会在调用时明确失败。
- JS 驱动的导航无法静态检查 —— allowedDomains 现在覆盖 browser_navigate、browser_open_tab 和链接点击，但某个按钮的处理程序若执行 location.href = …，仍可能离开允许的主机；请部署外部网络防护以实现硬隔离。

Ref 与生命周期安全（已修复）

场景测试套件最初暴露出四个隐患，现已修复并进行了回归测试：

- 过期 ref 快速失败 —— ref 携带每次快照的 nonce，因此在客户端重新渲染后，过期 ref 不会匹配任何内容，browser_click 会以 REF_NOT_FOUND 失败，而不是静默地对另一个元素执行操作。
- 链接点击遵循 allowedDomains — 点击指向不允许主机的页内链接会被拒绝，并返回 URL_NOT_ALLOWED。
- 空闲释放在操作期间延迟 — 比 idleTimeoutMs 更慢的导航会正常完成；只有当会话真正空闲时才会触发释放。
- 导航中途的快照会稳定下来 — 与 JS 导航竞争的 browser_snapshot 会等待新文档并重试，而不是抛出原始的 "Execution context was destroyed" 错误。

许可证

MIT