Preface¶

When connecting a browser to a DSH agent, the common paths are two-fold: either have the model guess CSS selectors, or hand the entire page DOM over to the model for processing. The former is prone to mismatches, while the latter inflates the context window. dsh-browser-playwright reduces the model-visible interaction surface to an accessibility snapshot and stable element refs, with Playwright driving the real browser underneath.

What This Is¶

dsh-browser-playwright is a browser capability plugin for the DeepSeek Harness, positioned as a Playwright-powered browser capability for DeepSeek Harness. The GitHub repository path is ChenyuHeee/dsh-browser-playwright, licensed under MIT. It allows an agent to use a single browser session within one harness session, handling navigation, interaction, screenshots, and structured extraction around stable refs.

Core Features¶

• Uses Playwright to drive a real browser.
• Exposes elements via accessibility snapshots, providing stable refs.
• No CSS selector guessing; does not output the full DOM.
• One browser session per harness session.
• Supports tab management, screenshots as durable image attachments, structured extraction, and gated JavaScript evaluation.
• Provides 17 tool schemas prefixed with browser_.
• The Playwright provider automatically detects chromium, chrome, msedge, and edge channels.
• Other providers can register to ctx.browser while keeping the tool schemas unchanged.

Installation¶

1. Add the plugin to the target profile:

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

This command adds the plugin to the specified profile.

Browser Binaries¶

The provider automatically detects available channels in the order chromium, chrome, msedge, edge.

To use the Playwright-managed Chromium, run:

npx playwright-core install chromium

This command installs the Chromium available for use by Playwright.

In restricted networks, you can set the download host before installing:

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

This step specifies the download source via PLAYWRIGHT_DOWNLOAD_HOST.

Typical Usage¶

The plugin defaults to using browser_ as the tool prefix. Below, we first open a page, then perform a click based on the ref from the snapshot.

First, call browser_navigate to open an http or https URL:

browser_navigate
url: https://example.com/

browser_navigate only accepts http/https URLs and returns a snapshot.

The snapshot lists the URL, title, visible elements, and ref= markers, as shown below:

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]

Invisible content is excluded. The snapshot result has boundaries; truncation is marked in the result.

After the snapshot, you can call browser_click with ref: e2:

browser_click
ref: e2

This step performs a click based on the element reference from the latest snapshot.

The plugin also provides these browser_ tools:

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

They cover snapshots, interaction, history navigation, waiting, tab management, screenshots, structured extraction, controlled JavaScript execution, and closing the browser.

Configuration¶

Navigation and tool behavior can be adjusted through configuration options.

To restrict navigation domains, use allowedDomains:

allowedDomains:
  - example.com

This configuration constrains the domains accessible to browser_navigate.

To enable browser_extract, you need to provide a helper model route:

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

browser_extract requires both extract.provider and extract.model; if either is missing, an actionable error is returned.

To enable browser_evaluate, you must turn on allowEvaluate:

allowEvaluate: true

browser_evaluate is disabled by default; when enabled, it executes arbitrary page JavaScript and should be used in conjunction with DSH’s approval or permission policies.

Use Cases and Considerations¶

Suitable for scenarios where you are already using DSH, want the agent to operate a real browser, and prefer stable refs over selector guessing. It is also suitable for workflows that need to preserve browser session state, use screenshot attachments, or swap out providers on ctx.browser.

Before installation, review the source code, license, and network egress. The plugin loads as a DSH plugin and runs with the current dsh process permissions at runtime; enabling browser_evaluate or relaxing allowedDomains requires stricter constraints on available capabilities.

Known Limitations¶

• Selector-free does not mean vision-free: interactions based on the accessibility tree may not cover purely visual controls such as canvas, WebGL, or custom-drawn widgets; in such cases, browser_screenshot with a vision-capable model can be used as a fallback.
• Cross-origin iframes appear as leaf (frame) nodes without a ref; same-origin frames are traversed up to two levels.
• browser_navigate only supports http and https.
• The browser session retains cookies, storage, and login state, but only for the duration of a single harness session.
• Tool schemas are static; browser tool results vary with page content, which may affect KV cache reuse.

Conclusion¶

dsh-browser-playwright reduces browser interactions to accessibility snapshots and stable refs, minimizing the uncertainty of selector guessing and full-page DOM processing. It preserves ctx.browser as an integration point, allowing other providers to extend functionality under the same tool schema.

Community directory page: https://www.skillhub.cn/plugins/ChenyuHeee/dsh-browser-playwright
GitHub: https://github.com/ChenyuHeee/dsh-browser-playwright