7.3 KiB

Raw Blame History

name	description
browser-use	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，下一轮再继续

常用工具

标签页管理

// 列出所有标签页
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 });

页面导航

// 导航到 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();

页面观察

// 获取页面快照（推荐，成本低）- 返回带 [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);

元素交互

// 点击（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

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

等待

// 等待 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：导航 → 等待 → 快照

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：点击 → 等待 → 快照

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 访问：

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);

注意事项

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

7.3 KiB Raw Blame History Unescape Escape