dsh-tool-playwright

Readme

# dsh-tool-playwright

English | [中文](README.zh.md)

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](https://github.com/microsoft/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

```bash
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

```bash
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

```bash
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

```bash
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):

```yaml
# 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

```bash
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:

```bash
$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](https://github.com/microsoft/playwright-mcp) (Apache-2.0); the harness-facing implementation is original.