#Chrome 桥接模式（Bridge Mode）

Midscene Chrome 插件的桥接模式允许你使用本地脚本来控制桌面版 Chrome。脚本既能连接新标签页，也可以附着到当前激活的标签页。

这种方式能复用本地浏览器的 cookies、插件和页面状态，与自动化脚本协作完成任务；在自动化领域也被称作 “man-in-the-loop”。

#配置 AI 模型服务

通过环境变量设置模型。选择模型时，请参考模型策略。

export MIDSCENE_MODEL_BASE_URL="https://替换为你的模型服务地址/v1"
export MIDSCENE_MODEL_API_KEY="替换为你的 API Key"
export MIDSCENE_MODEL_NAME="替换为你的模型名称"
export MIDSCENE_MODEL_FAMILY="替换为你的模型系列"

全部配置项请参考模型配置。

桥接模式下，AI 模型配置需要写在 Node.js 侧（终端环境变量），而不是浏览器侧。

#快速开始

#第一步：在 Chrome 应用商店安装 Midscene 插件

安装 Midscene Chrome 插件。

#第二步：安装依赖

npm install @midscene/web tsx --save-dev

yarn add @midscene/web tsx --save-dev

pnpm add @midscene/web tsx --save-dev

bun add @midscene/web tsx --save-dev

deno add npm:@midscene/web npm:tsx --save-dev

#第三步：编写脚本

将以下代码保存为 ./demo-new-tab.ts。

import { AgentOverChromeBridge } from "@midscene/web/bridge-mode";

const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
Promise.resolve(
  (async () => {
    const agent = new AgentOverChromeBridge();

    // 连接到桌面 Chrome 的新标签页
    await agent.connectNewTabWithUrl("https://www.bing.com");

    // 与普通 Midscene agent 的 API 相同
    await agent.ai('type "AI 101" and hit Enter');
    await sleep(3000);

    await agent.aiAssert("there are some search results");
    await agent.destroy();
  })()
);

#第四步：运行脚本

运行脚本：

tsx demo-new-tab.ts

脚本运行后，Chrome 扩展会弹出一个确认窗口，询问是否允许连接。点击 "Allow" 允许本次连接，或点击 "Always Allow" 以后自动允许所有连接请求（可在 Bridge Mode 面板中重置）。确认后你会看到桌面 Chrome 打开一个新标签页并交由脚本控制。

#在 YAML 自动化脚本中使用桥接模式

YAML 自动化脚本 让你用更易读的方式描述流程。要启用桥接模式，在 web 中设置 bridgeMode：使用当前标签页填 currentTab，新建标签页填 newTabWithUrl。如需销毁时自动关闭新建标签页，可配置 closeNewTabsAfterDisconnect: true。

web:
  url: https://www.bing.com
+ bridgeMode: newTabWithUrl
+ closeNewTabsAfterDisconnect: true
tasks:

midscene ./bing.yaml

运行脚本后，在弹出的确认窗口中点击 "Allow" 即可。

#不支持的选项

桥接模式会复用桌面浏览器配置，以下选项将被忽略：

• userAgent
• viewportWidth
• viewportHeight
• deviceScaleFactor
• waitForNetworkIdle
• cookie
• extraHTTPHeaders
• downloadPath
• chromeArgs

#远程访问配置

默认情况下，Bridge Server 只监听 127.0.0.1，仅允许本机 Chrome 扩展连接。如需跨机器通信（例如脚本运行在机器 A，浏览器在机器 B），可启用远程访问。

Server 端（Node.js 脚本）

// 启用远程访问（推荐）
const agent = new AgentOverChromeBridge({
  allowRemoteAccess: true, // 监听 0.0.0.0:3766
});

// 或指定特定网卡
const agent = new AgentOverChromeBridge({
  host: '192.168.1.100',
  port: 3766,
});

Client 端（Chrome 插件）

1. 打开插件的 Bridge Mode 页面
2. 在 "Bridge Server URL" 输入框中填写服务器地址
   • 本地：ws://localhost:3766（默认）
   • 远程：ws://192.168.1.100:3766（替换成你的服务器 IP）
3. 运行脚本后，在弹出的确认窗口中点击 "Allow" 即可

#FAQ

• 模型配置（如 MIDSCENE_MODEL_API_KEY）应该配置在浏览器还是终端？

  使用桥接模式时，请在终端（Node.js 环境）中配置模型参数。更多配置信息请参考模型策略文档。

#更多

• 更多 Agent 的 API 请参考 API 参考。
• 完整的 Chrome 桥接 API 可参阅 API 参考（Web）。
• 样例项目
  • 桥接模式示例：https://github.com/web-infra-dev/midscene-example/blob/main/bridge-mode-demo