@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
mearl browser_launch --payload '{"name":"browser-a","url":"https://example.com"}'
mearl browser_launch --payload '{"name":"browser-b","persistent":true}'
mearl browser_launch --payload '{"name":"cookie-copy","copyCookieDomains":["example.com"]}'
mearl browser_launch --payload '{"name":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
mearl browser_list
mearl browser_release

外部浏览器 Provider

Provider 浏览器与扩展、CDP 浏览器一起出现在 browser_list 中，并使用同一个 全局 browserId 参与路由。Provider 的安装、更新和卸载由 @mearl/setup 管理：

npx @mearl/setup provider install @ali/mearl-provider-brow
npx @mearl/setup provider install @ali/mearl-provider-agentbay

# 查看 Provider 当前版本的能力、参数与使用流程
mearl brow
mearl agentbay --help

# Provider 启动参数统一放在 providerOptions
mearl browser_launch --payload '{"provider":"brow","providerOptions":{}}'
mearl browser_list

# 后续操作使用 browser_list 返回的全局 Browser ID
mearl page_snapshot --browser '<browserId>'

npx @mearl/setup provider update brow
npx @mearl/setup provider uninstall brow

browser_launch 创建 pairing 实例时会直接返回 pairing.url 和可选的配对码；Agent 应把 URL 直接渲染为 二维码交给用户，扫码后确认同一 Browser ID 变为 connected，再开始页面操作。在设备连入前 该实例不会成为默认操作目标；可用 browser_close 删除对应 Provider 实例。每个 Provider 只接收它为该浏览器显式声明支持的 actions，截图能力同时标明为原生截图、重建画面或不支持。

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

常用选项：

选项	说明
--payload <json>	直接传入 JSON 参数
--payload-file <path>	从文件读取 JSON 参数
--timeout <seconds>	请求超时时间
--compact	stdout 紧凑输出
--output <path>	将结果写入文件（如截图）
--browser <id|名称>	指定目标浏览器

Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通过 browser_list 返回的全局 browserId 自动路由。以下覆盖参数仅在限定宿主或连接、传输排障时使用，因此不出现在默认 help：

选项	说明
--connector <id|名称>	限制到一台远端机器
--local	只使用当前机器
--cdp	当前机器强制使用 CDP，并隐含 --local
--server <url>	覆盖自动读取的 cloud-server 地址

browser_list --help 和 browser_launch --help 会按场景展示宿主选择参数；连接或传输排障运行 mearl check --help。其中 --json 仅用于输出机器可读的检查结果。

Skill 插件

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

npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
npx @mearl/setup plugin install trip/mearl --skill buc-request --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)，可导出简短的 description 显示在 mearl 插件列表中，并通过 app.command(signature, handler, description?) 注册动作、app.invoke(action, payload, options?) 复用当前浏览器上下文，并用 app.progress(message) 报告可选进度。调用另一个插件时，payload 使用 { command, input } envelope；嵌套调用继承宿主选项并拒绝循环依赖。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 入口。

注册后的插件也可从 SDK 调用；实例方法 client.invokePlugin 复用既有连接和默认浏览器：

import { invokePlugin } from '@mearl/client';

const result = await invokePlugin(
  'yuque',
  { command: 'read', input: { url: 'https://aliyuque.antfin.com/group/book/doc' } },
  { browser: 'work' },
);

MCP Server 通过固定工具 mearl_plugin 接受同样的 plugin、command 和 input，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用官方目录中尚未注册的插件时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。未知名称仍返回 PLUGIN_NOT_REGISTERED。

注册记录在 ~/.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 的 Skill 插件规范。

需要 BUC 身份的内部 HTTP 接口通过官方 buc 插件调用。CLI 使用 mearl buc request，业务插件使用 app.invoke('buc', { command: 'request', input })；当前身份和人员资料分别使用 whoami 与 profile 子命令。BUC 插件按请求创建一次性凭据，只允许访问 HTTPS alibaba-inc.com 域名，过滤认证字段与 Cookie，并始终在运行 CLI、SDK 或 MCP Server 的机器上执行，不随浏览器或 connector 转发。

支持的操作

分类	Actions
API 调试	tab_checkpoint get_requests get_logs get_events
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
录制	record_start record_stop
浏览器	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 统一列出普通浏览器、Provider 浏览器和托管浏览器。type 区分 regular / managed，status 区分 connected / pairing / running_disconnected / stopped；只有 connected 的浏览器可作为常规操作目标。

browser_release 仅在用户明确要求结束调试、退出接管或清理会话资源时调用；它会释放 debugger/CDP 控制和会话级临时状态，保留浏览器及全部标签页。托管实例的启动、关闭、持久化、 接入和登录态同步语义由各 Provider 声明；运行 mearl <providerId> 获取当前说明。访问入口不在 browser_list 中，需要时显式运行 mearl check --browser <id|名称>，并把返回的 browserAccess.url 按敏感信息处理。

架构

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

基础设施组件必须避免递归路由：@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