agent-browser

SKILL.md 节选

# Agent Browser

Use `agent-browser` CLI for full browser automation tasks. It is suitable when a page needs JavaScript rendering, real browser interaction, screenshots, or form automation.

Upstream project: https://github.com/vercel-labs/agent-browser

## Platform Support

`vercel-labs/agent-browser` provides native builds for:

- macOS ARM64 / x64
- Linux ARM64 / x64
- Windows x64

Windows support in this skill targets Windows 11 x64 with PowerShell and Node.js 18+.

## Prerequisites

- Node.js 18+
- npm available in PATH
- Network access to install `agent-browser` and download Chromium
- About 500 MB free disk space for Chromium
- **The `node` binary on PATH must actually execute code**, not just print a version. `agent-browser` spawns a Node child process internally; if that Node is broken, the daemon will crash with no useful output even when `agent-browser --version` works.

  Quick check:
  ```bash
  node -e "console.log('ok')"
  ```
  If this does not print `ok` (SIGILL / exit 133 / any crash), the Node on PATH is unusable. Fix it, or run `agent-browser` with a known-good Node prepended to PATH for that command only:
  ```bash
  PATH="/path/to/working-node/bin:$PATH" agent-browser open <url>
  ```
  Inspect which Node would be picked up with `which -a node`.

## Installation

> Inside the CodeBuddy marketplace, `scripts/setup.sh` auto-runs these steps on first load. The commands below are for manual setup or reinstall.

### Windows PowerShell

```powershell
npm install -g agent-browser
agent-browser install
```

### macOS / Linux

```bash
npm install -g agent-browser
agent-browser install
```

### Linux missing dependencies

```bash
agent-browser install --with-deps
```

## Required Command Sequence

The current upstream `agent-browser` CLI does not require a separate `launch` command. `agent-browser open <url>` starts or connects to the browser daemon automatically.

Always follow this order:

1. Open target URL.
2. Wait for page load when needed.
3. Inspect page with `snapshot` or `snapshot -i`.
4. Interact with the page.
5. Close browser when done.

```bash
agent-browser open https://example.com
agent-browser wait --load networkidle
agent-browser snapshot
agent-browser close
```

## Session Model

`agent-browser` runs a persistent background daemon. Understand this before planning multi-step tasks:

- The first `agent-browser open` starts a daemon; subsequent commands auto-connect to the same daemon.
- Within one session, cookies, localStorage and login state are preserved across commands.
- Multiple `open` calls in the same session navigate the existing browser (no need to close between URLs).
- `agent-browser close` ends the daemon. Only call it when the whole task is finished, not between steps of the same task.

Implication: for a task that visits N URLs, do **one** `open ... snapshot ...` chain per URL and **one** `close` at the very end, not N `open`/`close` pairs.

## Execution Principles

Apply these when running command sequences, especially in multi-step tasks:

- **`close` is mandatory in finally**: whether the task succeeds or fails midway, always run `agent-browser close` at the end to avoid zombie daemons and leaked Chromium processes.
- **`wait` is optional and degradable**: `wait --load networkidle` can hang on SPAs that never go idle. If a wait stalls, fall back to `wait --load load` or skip waiting and `snapshot` directly. Do not block the whole task on `wait`.
- **Reuse the daemon**: in the same task, do not `close` between intermediate steps. Open once, navigate/interact multiple times, close at the end.
- **Prefer `snapshot -i` for interaction**: when you need to click or type, get interactive element IDs first via `snapshot -i`, then act on them. Do not guess CSS selectors blindly.

SKILL.md 不止这些内容，安装后可阅读全文。

技能包内容

共 7 个文件，合计 16.5 KiB