browser

Files (2)

• SKILL.md
• tools.ts

SKILL.md (first lines)

# Browser Skill

通过 CDP 连接系统 Brave 浏览器，提供网页自动化能力。

## 派给 browser-agent 还是自己干？

- **≤ 3 步操作 + 需要实时判断结果**（如"截这个页面给我看看"、"打开网页点一下登录看下报错"）→ 主 loop 自己操作 browser 工具
- **≥ 5 步固定流程**（自动登录、刷连胜、跑测试用例、批量填表）→ `spawn_subagent`，task 里写清流程步骤和退出条件，把 40 轮截图循环外包出去，主上下文不被淹

## 基本原则

**浏览器内的所有交互必须走 ref（来自 snapshot），不要用屏幕坐标。**

- ✅ 浏览器内点击/输入：`browser` skill 的 `act` + `ref`
- ✅ 浏览器外操作（地址栏右侧的扩展、系统弹窗、其他 App）：用 `desktop` skill

Ref 模式的优势：跨 frame 自动处理、不受滚动/DPR/窗口位置影响、稳定可调试。

## Tab 管理

- MaxClaw 按 `ToolContext.sessionId` 维护独立 browser session state；每个 session 拥有自己的 current page、ref 映射、tab 映射和 network capture buffer。
- 领域 skill 需要复用 Brave 登录态但不能干扰通用 browser current page 时，调用 `acquireBrowserPage(context, namespace)` / `releaseBrowserPage(context, namespace)`；owner 会变成 `<sessionId>::<namespace>`。
- 所有 action（除 tabs/focus/prune/network_get/network_clear）作用于当前 session 的 current page，不会因为别的 session 调用 `focus` 而切走。
- **进程重启自愈**：进程退出后 Brave 不重启。下次 `getPage()` 时会先扫描 `browser.pages()`，优先复用：
  1. 带 MaxClaw 标记且 owner 匹配当前 session 的 tab
  2. `about:blank` tab
  3. legacy 无 owner 的 MaxClaw tab（会被当前 session 认领）
  4. 都没有才 `newPage()`
- 所有 MaxClaw 创建/认领的新 page 都会通过 `evaluateOnNewDocument` 注入 `window.__maxclawTab` 和 owner 标记，跨刷新/导航保留。
- 共享系统 Brave profile，自带登录态和扩展。

### 页面生命周期

- 临时查证、自动化测试、一次性表单流：任务完成后调用 `browser({ action: 'close' })` 关闭当前 session 的 page。
- 需要 Max 继续看、保留登录/调试现场、或用户明确要求打开给他看：不要关闭。
- browser-agent 在成功、失败、STUCK、需要人工介入前，若页面不需要保留，应先关闭当前 session 的 page 再收尾。
- 不要用 `prune` 代替正常 close；`prune` 是清理孤儿 tab 的维护动作。

### prune action

`browser({ action: 'prune' })` 默认只关闭当前 session owner 下**带 MaxClaw 标记**的非 current page。用户手动开的 tab（没有标记）一律不动。适合定期清理当前任务累积下来的孤儿 tab。

需要全局清理时显式传 `scope: "all-maxclaw"`，会关闭所有 owner 的 MaxClaw tab（仍不会动用户手动 tab）。这是跨 session 维护动作，别在普通任务里用。

返回 `{ closedCount, closed: [...urls], skipped: [{ url, reason }] }`，reason 包括 `current` / `not-maxclaw` / `other-owner:<id>` / `legacy-unowned` / `internal` / `close-failed: ...`。

### tabs / focus

- `tabs` 调用 `browser.pages()` 列出所有真实 tab，过滤掉 `chrome://` / `devtools://` 等内部页面，返回 `[{ id: 't1', title, url, isCurrent, isMaxclaw, owner }]`。每次调用会重建当前 session 的 tabMap，t1/t2 编号在两次 `tabs` 调用之间稳定。
- `focus` 通过 `tabIndex`（如 `t2`）切换当前 session 的 current page，会清空当前 session 的 ref 映射，并把未归属页面认领给当前 session。
- `focus` 默认不 `bringToFront()`，避免多个 session 抢 Brave 前台；确实需要用户可见时传 `bringToFront: true`。
- 如果目标 tab 已属于另一个 session，`focus` fail-loud，不会偷切。
- **约定**：`focus` 之前必须先调用一次 `tabs` 刷新编号。

## 工具：browser

单一工具，通过 `action` 字段区分操作。

### 标准工作流

1. `navigate` 到目标页
2. `snapshot` 拿可访问性树 + ref 映射（输出形如 `[e3] button "Submit"`）
3. `act` + `ref` 执行点击/输入
4. 必要时再 `snapshot` 确认结果

### action 列表

| action | 必填 | 可选 | 说明 |
|--------|------|------|------|
| `navigate` | `url` | `waitUntil` | 导航到 URL |
| `snapshot` | — | `interactive` | 获取可访问性树 + ref 映射 |
| `screenshot` | — | `savePath`, `fullPage`, `maxWidth`, `grid`, `region` | 截图（base64） |
| `act` | `kind` | `ref`, `text`, `key`, `submit`, `values`, `timeMs` | 执行交互操作 |
| `tabs` | — | — | 列出所有打开的 tab（含 isCurrent/isMaxclaw 标记） |
| `focus` | `tabIndex` | `bringToFront` | 切换当前 session 到指定 tab（如 `t2`），默认不抢前台 |
| `close` | — | — | 关闭当前 session 的 current page；下次调用再按 owner 复用或新建 |
| `prune` | — | `scope` | 关闭 MaxClaw 标记的非 current tab，默认仅当前 session |
| `evaluate` | `script` | `frameUrl` | 执行任意 JS。`frameUrl` 用于 cross-origin iframe |
| `extract_image` | `ref`, `savePath` | — | 抓 `<img>` 元素的**当前显示**像素（如动态验证码）写到本地文件。`ref` 可以是 CSS selector（`"#imgValidCode"`）或 snapshot ref（`"e38"`）。base64 永不进 LLM 协议层，比 evaluate+canvas+exec decode 流程便宜得多。验证码识别等场景必用。 |
| `frames` | — | — | 列出所有 frame |
| `preinject` | `preinjectScript` | — | 注册脚本，每次新文档加载前自动执行（含 iframe） |
| `network_start` | — | `domains`, `excludeTypes` | 开始捕获网络流量（HTTP+WS）|
| `network_get` | — | `filter`, `type`, `method`, `limit` | 获取已捕获的请求 |
| `network_clear` | — | — | 清空捕获缓冲区 |

### act kind 列表

| kind | 必填 | 说明 |
|------|------|------|
| `click` | `ref` | 点击元素 |
| `type` | `ref`, `text` | 输入文字（`submit:true` 提交） |
| `fill` | `ref`, `text` | 清空后填入文字 |
| `press` | `key` | 按键（`Enter`, `Tab`, `Escape` 等） |
| `select` | `ref`, `values` | 选择 option |
| `hover` | `ref` | 悬停 |
| `wait` | `timeMs` 或 `text` | 等待时间或文字出现 |

## 注意事项

- Snapshot 中的 `[eN]` ref 在下次 snapshot 调用前有效
- Brave CDP 未响应时会自动尝试启动 Brave
- `interactive: true` 只返回可交互元素（按钮/链接/输入框），减少 token

From maxesisn/maxclaw-oss, MIT.

More from maxesisn/maxclaw-oss