@mearl/client

@mearl/client

本地客户端 SDK 与 CLI，通过 Unix Domain Socket 与 Chrome 扩展的 native host 通信，调用浏览器调试与操作能力。

提供两种用法：类型安全的具名方法（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: '...' });

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

# 更新本地环境
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":"figma","userAgentMode":"desktop","copyCookieDomains":["figma.com"]}'
mearl browser_list
mearl browser_release

通用选项：

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

支持的操作

分类	Actions
API 调试	capture_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_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_type / page_hover / page_scroll / page_press / page_upload）默认内置观察与原子诊断：同一次调用内执行动作、等待异步稳定，并返回 { action, observation, diagnostics }；diagnostics 默认包含新增 error logs 和全部业务 requests。传 observe: false 只关闭 DOM/导航观察并保留诊断；同时传 diagnostics: false 才仅执行裸动作。观察结果不替代完整页面理解：mode: "delta" 只返回主文档中的 effects.notifications、effects.interactives 和 effects.focus 等高置信度信号，并明确携带 scope: "main-document"；可交互节点会尽量携带真实 backend node.ref，后续动作优先使用 ref，缺少 ref 时使用 node.selector。mode: "navigation" 且 ready: true 时，页面已通过网络静默、骨架状态或保守的内容稳定判定，可在新页面重建快照。动作直接打开新标签页时，observation.openedTabs 返回新标签页的 tabId、URL、标题和加载状态，可直接把该 tabId 用于后续操作，不必调用 tab_list。通常仅在 fullSnapshotRecommended 为 true 时根据 snapshotReasons 回退；滚动后若下一步需要读取新视口内容，可按需获取 viewport 快照。page_eval 默认裸执行；显式传 observe 对象可启用观察，传 diagnostics: true 或对象可启用原子诊断。

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 子树；ref 指向滚动容器内的子节点时，可用 page_scroll.containerPolicy: "nearest" 自动解析最近可滚动祖先。page_click.clickMode 默认 auto：可见桌面页派发可信 mouse，移动模拟页派发可信 touch；隐藏页使用 DOM fallback，返回 dispatchMode: "dom" 和 fallbackReason: "page-hidden"，且不切换标签或还原窗口。可用 dom / mouse / touch 覆盖自动策略；可信输入返回实际 pointerType。点击结果的 resolvedTarget 和滚动结果的前后位置、边界字段可用于诊断实际派发目标与滚动效果。

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

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

托管浏览器使用独立 Profile 和动态 CDP 端口。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，新实例可以使用 headless: true（默认）完成测试账号登录。copyCookieDomains 可把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会出现在命令结果或日志中；userAgentMode: "desktop" 可让实例使用匹配本机 Chrome 版本的桌面 UA。完整设计见 托管浏览器与 TDBank 多账号设计。

架构

@mearl/client (CLI / SDK)
  ↓ (Unix Socket)
@mearl/native-host
  ↓ (Native Messaging)
Chrome Extension / CDP

云端远程调用场景请使用 @mearl/cloud-client，其操作集与本包完全一致。

构建

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

License

ISC