# @mtop-devtools/cloud-client

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

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

## 安装

```bash
npm install @mtop-devtools/cloud-client
# 或
pnpm add @mtop-devtools/cloud-client
```

## 使用

### 方式一：使用 invoke 函数

```typescript
import { browserLaunch, browserList, invoke, selectBrowser } from '@mtop-devtools/cloud-client';

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

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

// 获取截图
const screenshot = await invoke('get_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 类

```typescript
import { CloudClient } from '@mtop-devtools/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('get_screenshot', {});
await client.browserLaunch({ name: 'account-b', query: 'test_account' });
await client.browserList();
await client.selectBrowser({ browser: 'Edge' });
client.disconnect();
```

### 命令行方式

```bash
mtop-devtools-cloud <action> [options]
```

**示例：**

```bash
# 获取请求
mtop-devtools get_requests --payload '{"count": 5}'

# 获取截图并保存
mtop-devtools get_screenshot --output screenshot.png

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

**环境变量：**

- `MTOP_DEVTOOLS_SERVER_URL` - WebSocket Server 地址（包含 token）

## 支持的操作

与本地 `@mtop-devtools/client` 完全一致，包括：

### API 调试

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

### Mock & 请求规则

- `set_mock` - 设置 Mock
- `get_mocks` - 获取 Mock 列表
- `add_rule` - 添加请求规则
- `proxy_request` - 代理 HTTP 请求

### 浏览器操作

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

### 页面感知

- `get_screenshot` - 获取截图
- `get_selected_element` - 获取选中元素
- `page_snapshot` - 获取页面快照

详细参数说明请参考 [SKILL.md](https://github.com/your-repo/packages/skills/mtop-devtools-socket/SKILL.md)

## 架构

```
云端 Agent
  ↓
@mtop-devtools/cloud-client (本进程)
  ↓ (WebSocket)
@mtop-devtools/cloud-server
  ↓ (WebSocket)
@mtop-devtools/cloud-connector (本地)
  ↓ (Unix Socket)
@mtop-devtools/native-host
  ↓
Chrome Extension / CDP
```

## 错误处理

```typescript
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 已启动且可访问
- 确保本地已运行 `@mtop-devtools/cloud-connector`
- 建议使用长连接复用 `CloudClient` 实例，避免频繁连接
- 使用完毕后调用 `disconnect()` 释放资源