@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, 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', {});

// 托管浏览器也提供具名方法
const managed = await browserLaunch({ name: 'account-a', accountId: 12345 });

// 浏览器列表和默认目标选择也是异步 API
const browsers = await browserList();
const connected = browsers.browsers.find(browser => browser.status === 'connected');
if (connected) await selectBrowser({ browser: connected.browserId });

方式二：使用 CloudClient 类

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

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

// 一次性使用
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]

示例：

# 获取请求
mearl get_requests --payload '{"count": 5}'

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

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

环境变量：

• 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
• 建议使用长连接复用 CloudClient 实例，避免频繁连接
• 使用完毕后调用 disconnect() 释放资源