@mearl/cloud-client

@mearl/cloud-client

云端客户端 SDK，用于在云端环境中调用本地浏览器能力。

所有具名 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,
  selectBrowser,
} 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 connectors = await listCloudConnectors();
const connector = connectors.connectors[0]?.connectorId;

// 具名方法的最后一个参数接受 cloud 调用选项
const managed = await browserLaunch({ name: 'account-a', accountId: 12345 }, { connector });

// browser_list 只返回目标 connector 下的浏览器
const browsers = await browserList({ connector });
const connected = browsers.browsers.find(browser => browser.status === 'connected');
if (connected) await selectBrowser({ browser: connected.browserId }, { 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();

命令行方式

mearl-cloud <action> [options]

示例：

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

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

# 列出接入当前 cloud-server 的浏览器侧 connector
mearl connector_list

# 多个 connector 同时在线时，先选机器，再列该机器的浏览器
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 同时在线时，使用 --connector <id|name> 选择目标。可通过 --server <url> 指定地址，通过 --timeout <seconds> 调整每项 检查的超时时间。输出 server URL 时会隐藏 token。

环境变量：

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

支持的操作

与本地 @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 (本进程)
  ↓ (WebSocket)
@mearl/cloud-server
  ↓ (WebSocket)
@mearl/cloud-connector (本地)
  ↓ (Unix Socket)
@mearl/native-host
  ↓
Chrome Extension / CDP

错误处理

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
• 多个 connector 同时在线时，每次 CLI 调用都传 --connector <id|name>；--browser 只在该 connector 的浏览器列表中解析
• 建议使用长连接复用 CloudClient 实例，避免频繁连接
• 使用完毕后调用 disconnect() 释放资源