dsh-tool-playwright

English | 中文

A plugin for DeepSeek Harness that lets the AI actually open a browser and use the web — visit pages, click buttons, fill forms, switch tabs, and read page content, the way a person would.

It is a native port of Microsoft's playwright-mcp: no separate server process, it runs directly inside the harness.

What it does

| What you want to do | Tools | |---|---| | Open a page, go back/forward, reload, wait for the page to settle | browser_navigate, browser_back, browser_forward, browser_reload, browser_wait_for | | Click, type, pick from a dropdown, hover, press keys, drag, upload files | browser_click, browser_type, browser_type_submit, browser_select_option, browser_hover, browser_focus, browser_press_key, browser_drag, browser_upload_file | | See what's on the current page | browser_snapshot | | Open / switch / close / list tabs | browser_tab_new, browser_tab_switch, browser_tab_close, browser_tab_list | | Resize the window, take a screenshot, save as PDF | browser_resize, browser_screenshot, browser_pdf | | Read console errors, see which URLs the page requested | browser_console_messages, browser_network_requests | | Advanced features (off by default, opt in) | browser_evaluate, browser_storage_state, browser_init_script, browser_tracing_start, browser_tracing_stop |

Two terms, in plain words:

• Snapshot is not a screenshot. It is how the AI "sees" a page: a structured list of what is on it — buttons, links, input boxes, their text, and a number (the ref) for each one.
• ref — the number from that list. The AI says "click item 3" and the plugin clicks item 3. A CSS selector (like #search) works too.

Installing

Step 1: Know your profile

A harness profile is one named set of configuration — on disk it is a folder: C:\Users\<your-user-name>\.dsh\profiles\<name>\. The web GUI uses the profile called web. The commands below install into web.

Step 2: Clone the plugin code from GitHub

git clone https://github.com/cheng-nan01/dsh-tool-playwright.git

This gives you a plugin folder named dsh-tool-playwright with all the code. Don't move or delete that folder afterwards.

Step 3: Install from the local folder

dsh plugin --profile web add link:/full/path/to/the/cloned/plugin/folder

Replace the path after link: with the folder you just cloned (e.g. link:D:\my-plugins\dsh-tool-playwright).

The command does three things:

1. Registers the plugin in the profile's package.json (an installed-package list);
2. Creates a shortcut in the profile's node_modules pointing at your plugin folder — your code is not copied;
3. Adds the plugin to the startup list (dsh.profile.bundles) — this is what makes the harness load it on the next start.

link: means "create a shortcut, don't copy". You can also write add ./relative/path (relative to the directory you are standing in).

Step 4: Restart the harness

The startup list is only read once at boot, so a restart is required: stop pnpm dsh web (Ctrl+C), then run pnpm dsh web again.

Step 5: Verify

dsh --profile web --dump-config    # look for a "# == dsh-tool-playwright" layer

After the restart, ask the AI at http://127.0.0.1:3080 to open a page with browser_navigate — if it opens, the plugin is live.

Uninstalling

dsh plugin --profile web remove dsh-tool-playwright   # removes the registration + startup-list entry

If you wrote an override block in the profile's cordis.patch.yml, remove that too.

Troubleshooting

• dsh command not found: run pnpm dsh ... from the harness source checkout (the folder where the DeepSeek Harness code lives).
• Installed but nothing happens: you almost certainly forgot the restart.
• Moved the plugin folder: the shortcut is broken — run add again.
• A "declares no dsh.bundle" warning during install: that package is a plain dependency and won't auto-activate — this plugin declares a bundle so you won't see that warning for it; it is normal for third-party libraries.

Changing settings

The plugin ships with sensible defaults (see the table below). To change them, edit the harness's cordis.patch.yml and rewrite the whole settings block (a patch replaces the whole config, it does not merge — anything you omit falls back to its default):

# append to $DSH_HOME/profiles/<name>/cordis.patch.yml:
- id: dsh-tool-playwright
  config:
    browser: chromium        # which browser: chromium / firefox / webkit / msedge
    headless: false          # false = a visible browser window; true = run invisibly in the background
    executablePath: ''       # optional: which browser program to use (empty = Playwright's own build)
    viewport:
      width: 1280            # window width (pixels)
      height: 720            # window height (pixels)
    timeoutMs: 30000         # how long to wait for one action, in milliseconds
    capabilities:
      screenshot: true       # allow screenshots
      pdf: true              # allow PDF export
      network: true          # allow inspecting network requests

Common settings:

| Setting | What it does | Default | |---|---|---| | browser | Which browser engine to use | chromium | | headless | false shows a window, true runs in the background | true | | channel | Use a system-installed Chrome/Edge (e.g. chrome, msedge) | unset | | executablePath | Point at a specific browser program | unset (own build) | | userDataDir | Keep login state (cookies) in a fixed folder across restarts | unset (temporary) | | isolated | true = a fresh browser for every action (no traces) | false | | viewport | Window size | 1280×720 | | outputDir | Where screenshots / PDFs are saved | .dsh/playwright | | timeoutMs | Per-action waiting limit (ms) | 30000 | | evaluate | Allow the AI to run arbitrary code inside pages (risky — enable only if you trust the setup) | false |

FAQ

1. The AI can't launch a browser after installing? Install the browser binaries once: npx playwright install chromium. Or set executablePath to a browser already on your machine.

2. I want to watch the AI operate the browser. Set headless: false and restart the harness. Every action will then run in a visible window.

3. Can the plugin folder live anywhere? Yes. Install it with link: plus the full path; the harness finds it through the shortcut. Any drive, any folder — as long as the path matches.

4. How is this different from the original playwright-mcp? No separate server process, no extra name prefixes on tools, and the risky features (like evaluate) are off by default. Usage is otherwise the same.

For developers

pnpm typecheck   # type-check the code
pnpm smoke       # run an end-to-end self-test against a real browser

The smoke test really opens a browser and runs the full flow: open a page → inspect its structure → click a button → type text. If Playwright's managed browser is not installed, point at an existing one via the environment:

$env:DSH_PLAYWRIGHT_EXECUTABLE = "C:\path\to\chrome.exe"; pnpm smoke

During local development the dependencies resolve through shortcuts (junctions) in node_modules that point at the harness source checkout, so no network install is needed.

License

MIT. Tool semantics ported from playwright-mcp (Apache-2.0); the harness-facing implementation is original.