@mearl/client

@mearl/client

统一浏览器 SDK 与 CLI。它会发现当前机器及已配置 cloud-server 下所有 connector 的浏览器，并根据 browser_list 返回的全局 browserId 自动选择本地 Socket 或云端 WebSocket 链路。

提供两种用法：类型安全的具名方法（getRequests、sendRequest 等），以及灵活的底层 invoke(action, payload)。

安装

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

SDK 使用

import * as client from '@mearl/client';

// 具名方法（类型安全）
const requests = await client.getRequests({ count: 5 });
const result = await client.sendRequest({
  url: 'https://api.example.com',
  method: 'GET',
  withCookies: true,
});

// 底层通用方法（灵活扩展）
const data = await client.invoke('send_request', { url: '...' });

// browser_list 默认聚合本机和所有远端 connector
const browsers = await client.browserList();
await client.getLogs({}, { browser: browsers.browsers[0].browserId });

CLI 使用

安装后提供 mearl 命令：

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

# 代理一个 HTTP 请求
mearl send_request --payload '{"url":"https://api.example.com","method":"GET"}'

# 以 multipart/form-data 上传本地文件
mearl send_request --payload '{"url":"https://api.example.com/upload","method":"POST","formData":{"folder":"assets"},"files":[{"fieldName":"file","filePath":"/absolute/path/image.png"}]}'

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

# 从文件读取大体积参数（如 mock 数据）
mearl set_mock --payload-file ./mock-data.json

# 环境自检
mearl check
mearl check --local --json

# 更新本地环境
npx @mearl/setup update --local

# 查看某个 action 的帮助
mearl <action> --help

# 启动两个隔离的 headless Chrome，并分别登录不同 TDBank 账号
mearl browser_launch --payload '{"name":"account-a","accountId":12345}'
mearl browser_launch --payload '{"name":"account-b","query":"test_account"}'
mearl browser_launch --payload '{"name":"cookie-copy","copyCookieDomains":["example.com"]}'
mearl browser_launch --payload '{"name":"cloud-login","provider":"agentbay","persistent":true,"userAgentMode":"desktop","copyCookieDomains":["example.com"],"url":"https://example.com/account"}'
mearl browser_launch --browser '<控制浏览器 browserId>' --payload '{"name":"cloud-login","provider":"agentbay","reuse":"require","copyCookieDomains":["example.com"]}'
mearl browser_launch --payload '{"name":"cloud-tools","provider":"agentbay","copyCookieDomains":"mearl-services"}'
mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
mearl browser_list
mearl browser_release

输入不存在或拼写有误的 action 时，CLI 会基于可用命令和常见别名直接返回最多三个候选及调用示例， 不连接浏览器，也不会自动执行推荐命令。例如 mearl tab new 会优先推荐 mearl tab_open。

通用选项：

选项	说明
--payload <json>	直接传入 JSON 参数
--payload-file <path>	从文件读取 JSON 参数
--timeout <seconds>	请求超时时间
--compact	紧凑输出
--output <path>	将结果写入文件（如截图）
--browser <id|名称>	指定目标浏览器
--connector <id|名称>	限制到一台远端机器
--local	只使用当前机器
--server <url>	覆盖 cloud-server 地址

支持的操作

分类	Actions
API 调试	tab_checkpoint get_requests get_logs get_events get_api_schema
Mock & 规则	set_mock get_mocks set_rule get_rules
网络代理	send_request send_mtop_request
标签页	tab_open tab_close tab_list
页面操作	page_click page_drag page_type page_scroll page_eval page_press page_wait page_navigate page_upload
页面感知	page_snapshot page_screenshot page_selected_element page_frames
环境与状态	set_device_emulation set_timezone get_cookie set_cookie
用户信息	get_user_info
录制	record_start record_stop
TDBank	tdbank_account
浏览器	browser_list browser_release browser_launch browser_close

页面交互动作（page_click / page_drag / page_type / page_hover / page_scroll / page_press / page_upload）默认等待异步稳定并返回 { action, observation }。参数、ref 或目标解析在派发前失败时返回 action.stage: "precondition"，省略无意义的 observation / diagnostics，CLI 退出码为 1。传 observe: false 可执行裸动作；需要同一动作期间的新增 error logs 和业务 requests 时传 diagnostics: true，埋点通过 diagnostics.events 按需开启。page_eval 默认裸执行，可按需开启观察或诊断。

page_snapshot 默认返回完整 AX Tree；长列表可传 mode: "viewport"，只需要当前视口内的控件时传 mode: "interactive"，已知 CSS 区域时传 rootSelector，已有 ref 时传 rootRef（可用 ancestorDepth 向上补充上下文），只查找特定文案或角色时传 query。视口内缺少 AX 控件语义时，interactive 会自动回退到 viewport，并返回 fallbackMode: "viewport"。maxNodes / maxChars 截断会同时保留首尾内容。

重复文本点击可用 page_click.scope 限定 CSS / ref 子树；浏览器扩展后端中，容器或 iframe 内的点坐标使用 coordinateSpace: "active-frame"，CSS/text 查询可用 frameId 显式指定 frame。点击结果通过 requestedTarget、resolvedTarget、dispatchTarget、hitTarget 和 coordinates 区分请求语义、DOM 解析、派发节点与可信输入实际命中；ref 指向滚动容器内的子节点时，可用 page_scroll.containerPolicy: "nearest" 自动解析最近可滚动祖先。

browser_list 统一列出普通浏览器和托管浏览器。type 区分 regular / managed，status 区分 connected / running_disconnected / stopped；只有 connected 的浏览器可作为操作目标。

browser_release 仅在用户明确要求结束调试、退出接管或清理会话资源时使用，不作为普通任务收尾。它会释放当前目标浏览器的 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页；后续浏览器操作可自动重新建立控制。

托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 headless: true（默认）完成测试账号登录。AgentBay 固定为非 headless，传 headless: true 会被拒绝；imageId 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。persistent: true 会让本地实例保留 Profile，让 AgentBay 同名实例绑定稳定的云端 Browser Context；正常关闭时同步 Cookie、LocalStorage、IndexedDB 等状态，下次启动无需再次复制本地登录态。deleteProfile: true 会显式删除对应 Profile 或 Context。AgentBay 的 reuse 支持 never（默认）、prefer 和 require：prefer 存在运行实例时复用、否则创建，require 只复用且不会意外创建计费会话。copyCookieDomains 传数组时把控制浏览器指定域的 Cookie 写入目标，传 "mearl-services" 时同步 Mearl 依赖平台登录态。Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；userAgentMode: "desktop" 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。browser_list 仅通过 agentbayImageId、agentbayContextId 和 agentbayContextName 返回 AgentBay 实例的稳定配置。无影浏览器串流入口包含临时访问凭据且会过期，因此不会写入实例记录或列表结果；需要时运行 mearl check --browser <id|名称> 实时获取，并按敏感信息处理。完整设计见 托管浏览器与 TDBank 多账号设计。

架构

@mearl/client (CLI / SDK)
  ├─ 本机 → @mearl/native-host → Chrome Extension / CDP
  └─ WebSocket → @mearl/cloud-server → @mearl/cloud-connector
                                      → @mearl/native-host → Chrome Extension / CDP

基础设施组件必须避免递归路由：@mearl/cloud-connector 使用 @mearl/client/local 子路径直连所在机器的 native-host。普通 Agent、CLI 与 MCP 集成均使用包根入口。

构建

pnpm build      # tsc 编译到 dist/，并赋予 cli.js 执行权限
pnpm dev        # tsc --watch
pnpm typecheck  # 仅类型检查

License

ISC