safety-eval-service-frontend/.cursor/skills/browser-use/SKILL.md

---
name: "browser-use"
description: "Connect to and control the user's external Chrome browser. Invoke when user wants to open/use their browser, browse websites, test UI, scrape content, or interact with web pages."
---

# Browser Use - 外部浏览器控制

通过 TRAE Chrome 扩展连接并控制用户的外部 Chrome 浏览器，支持导航、点击、输入、截图、提取数据等操作。

---

## 连接流程（必须按顺序执行）

### 第 1 步：检查 Chrome 扩展连接状态

**必须单独调用，不能放入 Exec，不能与其他工具并行。**

```
run_mcp(server_name="integrated_code_mode", tool_name="browser_connect_plugin", args={})
```

- 返回 `connected: true` → 连接成功，继续执行后续浏览器操作
- 返回 `connected: false` → 未连接，执行第 2 步

### 第 2 步（仅未连接时）：引导用户安装扩展

**必须单独调用，不能放入 Exec，不能与其他工具并行。**

```
run_mcp(server_name="integrated_code_mode", tool_name="browser_setup_plugin", args={})
```

根据返回提示引导用户完成 Chrome 扩展安装。如果用户选择使用内置浏览器，则改用不带 `external_` 前缀的标准浏览器工具。

### 第 3 步：连接成功后的首次操作（快速启动）

连接成功后，会话尚无活动标签页，**直接 snapshot 会报错**。必须在首个 Exec 中一次完成：列出标签页 → 激活 → 等待 → 快照。

```
run_mcp(server_name="integrated_code_mode", tool_name="Exec", args={"code": "const tabs = await tools.external_browser_tabs({ action: \"list\" });\nawait tools.external_browser_tabs({ action: \"activate\", index: 0 });\nawait tools.external_browser_wait_for({ time: 1 });\nconst snap = await tools.external_browser_snapshot();\ntext(\"Tabs: \" + JSON.stringify(tabs) + \"\\n\\nSnapshot:\\n\" + snap);"})
```

- 默认激活 index 0（第一个标签页），如需切换其他标签页，根据 list 返回结果在后续 Exec 中 activate 对应 index
- 这一步将原本的 list → activate → snapshot 合并为单次调用，节省 2 次往返

### 第 4 步：使用浏览器工具

所有浏览器操作通过 `integrated_code_mode` 的 `Exec` 工具调用，使用 `external_browser_*` 前缀。

```
run_mcp(server_name="integrated_code_mode", tool_name="Exec", args={"code": "<js_code>"})
```

---

## Exec 调用规范

- `args` 必须是 JSON 对象，唯一接受字段为 `code`（非空 JavaScript）
- 沙箱环境全局变量：`tools`（工具调用）、`text`（输出结果）、`exit`（终止执行）
- 用 `await tools.<name>(args)` 调用浏览器工具
- 用 `text(value)` 将结果输出给模型
- 单次 Exec 建议 2-5 个工具调用，不超过 10 个
- 如果下一步依赖上一步结果（如读取 snapshot 选择 ref），必须结束当前 Exec，下一轮再继续

---

## 常用工具

### 标签页管理

```javascript
// 列出所有标签页
const tabs = await tools.external_browser_tabs({ action: "list" });
text(tabs);

// 激活指定标签页（index 为位置序号，非 tabId）
await tools.external_browser_tabs({ action: "activate", index: 0 });

// 新建标签页
await tools.external_browser_tabs({ action: "new" });

// 关闭标签页
await tools.external_browser_tabs({ action: "close", index: 1 });
```

### 页面导航

```javascript
// 导航到 URL
await tools.external_browser_navigate({ url: "https://example.com" });
await tools.external_browser_wait_for({ time: 2 });
const snap = await tools.external_browser_snapshot();
text(snap);

// 新标签页打开
await tools.external_browser_navigate({ url: "https://example.com", newTab: true });

// 后退
await tools.external_browser_navigate_back();
```

### 页面观察

```javascript
// 获取页面快照（推荐，成本低）- 返回带 [ref=N] 的元素树
const snap = await tools.external_browser_snapshot();
text(snap);

// 精简模式（仅交互元素）
const snap = await tools.external_browser_snapshot({ interactive: true, compact: true });

// 截图（成本高，用于 canvas/复杂 CSS/视觉确认）
const shot = await tools.external_browser_take_screenshot({ fullPage: true });
text(shot);
```

### 元素交互

```javascript
// 点击（ref 来自 snapshot）
await tools.external_browser_click({ ref: "42" });

// 输入文本（clear 清空已有内容，submit 回车提交）
await tools.external_browser_type({ ref: "3", text: "hello", clear: true, submit: true });

// 滚动
await tools.external_browser_scroll({ direction: "down", amount: 300 });

// 按键
await tools.external_browser_press_key({ key: "Enter" });

// 下拉选择
await tools.external_browser_select_option({ ref: "5", values: ["option1"] });
```

### 执行页面 JS

```javascript
// 提取数据
const data = await tools.external_browser_evaluate({
  script: `JSON.stringify({ title: document.title, url: location.href })`
});
text(data);
```

### 等待

```javascript
// 等待 2 秒
await tools.external_browser_wait_for({ time: 2 });

// 等待元素出现
await tools.external_browser_wait_for({ selector: ".content", timeout: 10000 });

// 等待文本出现
await tools.external_browser_wait_for({ text: "加载完成", timeout: 30000 });
```

---

## 常用模式

### 模式 A：导航 → 等待 → 快照

```javascript
await tools.external_browser_navigate({ url: "https://example.com" });
await tools.external_browser_wait_for({ time: 2 });
const snap = await tools.external_browser_snapshot();
text(snap);
```

### 模式 B：点击 → 等待 → 快照

```javascript
await tools.external_browser_click({ ref: "42" });
await tools.external_browser_wait_for({ time: 2 });
const snap = await tools.external_browser_snapshot();
text(snap);
```

### 模式 C：访问 iframe 内容

当页面内容在 iframe 中（snapshot 只显示外层），用 evaluate 访问：

```javascript
const result = await tools.external_browser_evaluate({
  script: `(function() {
    var iframe = document.getElementById('appIframe-qa');
    if (!iframe) return JSON.stringify({error: 'iframe not found'});
    try {
      var doc = iframe.contentDocument || iframe.contentWindow.document;
      return JSON.stringify({
        title: doc.title,
        bodyText: doc.body ? doc.body.innerText.substring(0, 5000) : 'no body'
      });
    } catch(e) {
      return JSON.stringify({error: e.message});
    }
  })()`
});
text(result);
```

---

## 注意事项

1. **工具命名**：操作外部 Chrome 必须使用 `external_browser_*` 前缀，不带前缀的会路由到内置浏览器
2. **连接检查**：`browser_connect_plugin` 和 `browser_setup_plugin` 不带 `external_` 前缀，且必须单独调用
3. **连接后必须先 activate**：连接成功后会话无活动标签页，直接 snapshot/click 等操作会报错 "No active tab"，必须先 `tabs({action:"activate"})` 建立活动标签页
4. **Ref 生命周期**：ref 在任何 DOM 变化后失效（导航、点击、AJAX），操作后需重新 snapshot
5. **iframe 限制**：snapshot/click 等工具无法直接访问 iframe 内容，需通过 `external_browser_evaluate` 用 JS 访问
6. **等待策略**：优先短等待 + snapshot 检查（如 2s -> snapshot -> 不行再 2s），避免单次长等待
7. **安全规则**：不要自动输入密码等敏感信息，需要用户登录时用 `browser_waiting_for_user_interaction` 暂停等待用户操作