@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 --browser '<本地来源 browserId>' --payload '{"sessionId":"<其他设备创建的 AgentBay sessionId>","copyCookieDomains":["example.com"]}'
mearl browser_launch --payload '{"name":"cloud-tools","provider":"agentbay","copyCookieDomains":"mearl-services"}'
mearl browser_launch --payload '{"name":"cloud-tools-plus","provider":"agentbay","copyCookieDomains":{"presets":["mearl-services"],"domains":["figma.com"]}}'
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	stdout 紧凑输出
--output <path>	将结果写入文件（如截图）
--browser <id|名称>	指定目标浏览器
--connector <id|名称>	限制到一台远端机器
--local	只使用当前机器
--cdp	当前机器强制使用 CDP
--server <url>	覆盖 cloud-server 地址

check 有独立的选项说明，运行 mearl check --help 查看。其中 --json 仅用于输出机器可读的检查结果。

Skill CLI 插件

安装 skill 并自动注册命令，或直接注册已有入口：

npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
npx @mearl/setup plugin yuque /absolute/path/to/yuque-doc-fetch
npx @mearl/setup plugin uninstall yuque
mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
mearl yuque --payload '{"command":"read","input":{"url":"https://aliyuque.antfin.com/group/book/doc"}}'
mearl yuque --help
mearl yuque --version

目录默认使用 scripts/main.mjs。入口默认导出 register(app)，通过 app.command(signature, handler, description?) 注册动作、app.invoke(action, payload, options?) 复用当前浏览器上下文，并用 app.progress(message) 报告可选进度。CLI 默认只输出最终结果，传入 --verbose 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 --output、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。 自动注册默认以 skill 安装目录名作为命令名，也可在入口导出 name 指定短名称。 setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。

需要单独检查插件时运行 mearl <name> --version。命令会解析注册记录并加载入口，但不连接浏览器； 退出码为 0 表示插件已注册且入口可加载，stdout 返回同目录 SKILL.md 的版本，缺少版本元数据时返回 unknown。 未注册、入口丢失或加载失败会以退出码 2 和对应的 PLUGIN_* 错误结束。普通业务调用无需预先检查，直接处理同样的错误即可。

插件接受位置参数或包含 command/input 的 --payload，两种形式不能混用。JSON 保留业务字段类型；正文等文件输入 按具体 skill 的字段约定处理。插件不使用上表中内置 action 的 --payload-file 入口。

注册记录在 ~/.mearl/plugins/<name>.json，只引用入口路径；skill 原地更新直接生效，换路径后重新注册。 plugin uninstall <name> 会对 ~/.agents/skills 中的全局 Skill 调用 ali-skills remove --global --yes， 成功后清除相关注册；即使入口目录已被手动删除，也会完成 Ali Skills 跟踪记录的清理。 手工路径只解除注册并保留源码。 PLUGIN_NOT_REGISTERED 表示插件尚未注册。PLUGIN_ENTRY_MISSING 会显示失效入口，并给出带有实际插件名的 卸载清理命令。其他错误按实际原因处理。 编写规范见 Mearl Skill Creator 的 CLI 插件规范。

支持的操作

分类	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 request_domain_permission
标签页	tab_open tab_close tab_list
页面操作	page_click page_drag page_type page_hover page_scroll page_eval page_press page_wait page_navigate page_upload
组合调用	run_actions
页面感知	page_snapshot page_screenshot page_selected_element page_frames
环境与 Cookie	set_device_emulation set_app_profile 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 的浏览器可作为操作目标。

按 sessionId 接入的 AgentBay 浏览器用 browser_release 收尾：它会移除本机 attachment 并退出对应宿主，但不会关闭云端 Session。其他浏览器仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放 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 只复用且不会意外创建计费会话。另一台设备已知确切 Session 时，可传 sessionId 直接通过 AgentBay CDP 接入，不需要 cloud-server；当前设备需配置能访问该 Session 的 AGENTBAY_KEY。provider-local ID 为 managed:agentbay:session:<sessionId>，跨 CLI 调用使用启动响应中的全局 browserId，且本机只持有 attachment。copyCookieDomains 传数组时复制指定域，传 "mearl-services" 时同步 Mearl 依赖平台登录态；需要同时复制基础登录态和额外站点时传 { "presets": ["mearl-services"], "domains": [...] }。Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；userAgentMode: "desktop" 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。browser_list 仅返回浏览器的稳定配置，不携带 AgentBay 串流入口或沙箱 noVNC 地址。需要时显式运行 mearl check --browser <id|名称>，由统一的浏览器访问入口能力实时返回 browserAccess；AgentBay、OpenSandbox 和 AONE Sandbox 地址都应按敏感信息处理。完整设计见 托管浏览器与 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