@mearl/cloud-client

@mearl/cloud-client

浏览器客户端 SDK。配置 cloud-server URL 且未指定默认 connector 时，browser_list 会同时列出当前机器和所有 cloud-connector 后的远程浏览器；未配置时直接调用当前机器上的浏览器。

所有具名 action 方法及其 TypeScript 类型均从 @mearl/client 自动生成；新增本地 client 方法后运行 pnpm generate:cloud-client-api 即可同步，构建和类型检查会校验生成结果。

安装

npm install @mearl/cloud-client
# 或
pnpm add @mearl/cloud-client

使用

方式一：使用 invoke 函数

import { browserLaunch, browserList, invoke, listCloudConnectors } from '@mearl/cloud-client';

// 设置环境变量
process.env.MEARL_SERVER_URL = 'ws://your-server.com/ws?token=xxx';

// 调用浏览器能力
const requests = await invoke('get_requests', { count: 5 });
console.log(requests);

// 获取截图
const screenshot = await invoke('page_screenshot', {});

// 同时列出当前机器和所有远端 connector 上的浏览器
const browsers = await browserList();
const connected = browsers.browsers.find(browser => browser.status === 'connected');
// 全局 browserId 可直接用于 action，客户端会自动选择本机或远端 connector
if (connected) await invoke('get_requests', { count: 5 }, { browser: connected.browserId });

// 仍可显式缩小到单个远端 connector
const connectors = await listCloudConnectors();
const connector = connectors.connectors[0]?.connectorId;
const managed = await browserLaunch({ name: 'account-a', accountId: 12345 }, { connector });

方式二：使用 CloudClient 类

import { CloudClient } from '@mearl/cloud-client';

const client = new CloudClient({
  serverUrl: 'wss://your-server.com/ws?token=xxx',
  connectTimeoutSec: 30,
  requestTimeoutSec: 60,
  defaultConnector: 'work-mac',
});

// 一次性使用
try {
  const logs = await client.invoke('get_logs', { limit: 10 });
  console.log(logs);
} finally {
  client.disconnect();
}

// 长连接复用
await client.invoke('tab_open', { url: 'https://example.com' });
await client.invoke('page_click', { selector: 'button' });
await client.invoke('page_screenshot', {});
await client.browserLaunch({ name: 'account-b', query: 'test_account' });
await client.browserList();
await client.selectBrowser({ browser: 'Edge' });
client.disconnect();

// 不提供 serverUrl 时直接使用当前机器的浏览器
const localClient = new CloudClient({});
await localClient.browserList();
await localClient.selectBrowser({ browser: 'Chrome' });
await localClient.getRequests({ count: 5 });

serverUrl 可省略，此时所有 action 直接使用本地浏览器。配置了 serverUrl 且未设置 defaultConnector 时，不传 connector 的 browser_list 会聚合本机与全部远端浏览器，并在名称前标记来源。 聚合结果中的 browserId 是全局目标 ID，把它传给 browser / --browser 即可自动 路由。未指定全局 browserId 的普通 action 仍走远端，不会在远端失败后改为操作本机。

命令行方式

mearl-cloud <action> [options]

示例：

# 检查 cloud-server 到浏览器的完整连接链路
mearl check

# 更新云端客户端环境
npx @mearl/setup update --cloud

# 同时列出当前机器和所有远端机器上的浏览器
mearl browser_list

# 使用 browser_list 返回的全局 browserId，自动路由到对应机器
mearl get_requests --browser "mearl:local:<browser-id>" --payload '{"count": 5}'
mearl get_requests --browser "mearl:remote:<connector-id>:<browser-id>" --payload '{"count": 5}'

# 也可以显式缩小到单个远端 connector
mearl connector_list
mearl browser_list --connector work-mac

# 获取请求
mearl get_requests --connector work-mac --browser edge --payload '{"count": 5}'

# 获取截图并保存
mearl page_screenshot --output screenshot.png

# 使用自定义服务器
mearl get_logs --server "ws://localhost:8080/ws?token=xxx" --payload '{"limit": 10}'

mearl check 会依次检查 server URL、cloud-server 连接及鉴权、cloud-connector、 远端 native-host 和浏览器清单，并输出各端版本与浏览器传输方式。只有一个 connector 时会自动选择；需要限制到某一台远端机器时，使用 --connector <id|name>。可通过 --server <url> 指定地址，通过 --timeout <seconds> 调整每项检查的超时时间。输出 server URL 时会隐藏 token。

环境变量：

• MEARL_SERVER_URL - WebSocket Server 地址（包含 token）

只使用本地浏览器时无需设置 MEARL_SERVER_URL。

支持的操作

与本地 @mearl/client 完全一致，包括：

API 调试

• get_requests - 获取网络请求
• get_logs - 获取控制台日志
• get_events - 获取埋点事件
• get_api_schema - 获取 API Schema

Mock & 请求规则

• set_mock - 设置 Mock
• get_mocks - 获取 Mock 列表
• set_rule - 添加请求规则
• get_rules - 查看请求规则
• send_request - 发送 HTTP 请求（自动携带浏览器 Cookie）

浏览器操作

• tab_open / tab_close / tab_list - 标签页管理
• page_click / page_type / page_scroll / page_press - 页面交互
• page_eval / page_navigate / page_wait - 页面控制
• page_upload - 文件上传

页面感知

• page_screenshot - 获取截图
• page_selected_element - 获取选中元素
• page_snapshot - 获取页面快照

详细参数说明请参考 SKILL.md

架构

Agent
  ↓
@mearl/cloud-client
  ├──────────────────────────────────────────────────→ native-host → Local Browser
  └─ 配置 serverUrl → cloud-server → cloud-connector → native-host → Remote Browser

错误处理

try {
  const result = await client.invoke('get_requests', { count: 5 });
} catch (error) {
  if (error.message.includes('Connection timeout')) {
    // 连接超时
  } else if (error.message.includes('Connection closed')) {
    // 连接断开
  } else if (error.message.includes('Request timeout')) {
    // 请求超时
  } else {
    // 其他错误
  }
}

注意事项

• 确保云端 Server 已启动且可访问
• 确保本地已运行 @mearl/cloud-connector
• browser_list 返回全局 browserId；后续通过 --browser <global-id> 自动选择本机或远端
• --connector <id|name> 仅用于显式限制到单个远端 connector
• 建议使用长连接复用 CloudClient 实例，避免频繁连接
• 使用完毕后调用 disconnect() 释放资源