@mearl/client 2.9.0 → 2.9.1

package/README.md

@@ -85,28 +85,32 @@ mearl browser_release
 | `--payload <json>`       | 直接传入 JSON 参数       |
 | `--payload-file <path>`  | 从文件读取 JSON 参数     |
 | `--timeout <seconds>`    | 请求超时时间             |
-| `--compact`              | 紧凑输出                 |
+| `--compact`              | stdout 紧凑输出          |
 | `--output <path>`        | 将结果写入文件（如截图） |
 | `--browser <id\|名称>`   | 指定目标浏览器           |
 | `--connector <id\|名称>` | 限制到一台远端机器       |
 | `--local`                | 只使用当前机器           |
+| `--cdp`                  | 当前机器强制使用 CDP     |
 | `--server <url>`         | 覆盖 cloud-server 地址   |
 
+`check` 有独立的选项说明，运行 `mearl check --help` 查看。其中 `--json` 仅用于输出机器可读的检查结果。
+
 ## 支持的操作
 
-| 分类        | 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`                                                     |
+| 分类          | 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` 默认裸执行，可按需开启观察或诊断。
 

package/dist/check.js

@@ -190,6 +190,13 @@ export async function runUnifiedCheck(options, dependencies = {}) {
         const browserChecks = [];
         await Promise.all(targets.map(async (browser) => {
             try {
+                if (options.transport === 'cdp') {
+                    await client.invoke('tab_list', {}, {
+                        timeoutSec,
+                        browser: browser.browserId,
+                        transport: 'cdp',
+                    });
+                }
                 const versions = (await client.invoke('get_versions', {}, {
                     timeoutSec,
                     browser: browser.browserId,
@@ -243,7 +250,9 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                         status: accessUrlWarning ? 'warning' : 'ok',
                         label: accessUrlWarning
                             ? 'Browser command path ready; AgentBay access URL unavailable'
-                            : 'Browser command path',
+                            : options.transport === 'cdp'
+                                ? 'CDP command path'
+                                : 'Browser command path',
                         details,
                     },
                     versions: publicVersions,

package/dist/cli.js

@@ -15,7 +15,7 @@ const CATEGORIES = [
     },
     { title: 'Mock & 规则', names: ['set_mock', 'get_mocks', 'set_rule', 'get_rules'] },
     {
-        title: '网络代理',
+        title: '网络请求',
         names: ['send_request', 'send_mtop_request', 'request_domain_permission'],
     },
     { title: '标签页', names: ['tab_open', 'tab_close', 'tab_list'] },
@@ -67,18 +67,17 @@ function printUsage(commandName, version) {
         '用法：',
         `  ${commandName} <action> [选项]`,
         `  ${commandName} <action> --help`,
-        `  ${commandName} check [--browser <id|名称>] [--connector <id|名称>]`,
+        `  ${commandName} check [选项]`,
         '',
         '统一目标发现：',
-        '  browser_list 默认列出当前机器和 cloud-server 下所有 connector 的浏览器。',
-        '  后续操作使用列表返回的全局 browserId，客户端会自动选择本地或远端传输。',
+        '  browser_list 默认聚合当前机器及已配置 cloud-server 下的浏览器。',
+        '  后续操作通过 --browser <browserId> 指定目标，客户端会自动选择本地或远端传输。',
         '',
         '通用选项：',
         '  --payload <json>      直接传入 JSON 参数',
         '  --payload-file <path> 从文件读取整个 JSON 参数',
         '  --timeout <seconds>   超时时间（默认按 action 推导）',
-        '  --compact             输出紧凑格式 JSON',
-        '  --json                check 输出机器可读 JSON',
+        '  --compact             stdout 输出紧凑格式 JSON',
         '  --output <path>       保存输出或截图',
         '  --browser <id|名称>   指定 browser_list 返回的浏览器',
         '  --connector <id|名称> 限制到一台远端 connector',
@@ -86,6 +85,10 @@ function printUsage(commandName, version) {
         '  --cdp                 当前机器强制使用 CDP（隐含 --local）',
         '  --server <url>        覆盖 cloud-server WebSocket URL',
         '',
+        '其他选项：',
+        '  -h, --help            查看帮助',
+        '  -v, --version         查看版本',
+        '',
         '内置命令：',
         '  check                 检查指定浏览器，未指定时检查全部已连接浏览器',
     ];
@@ -94,12 +97,31 @@ function printUsage(commandName, version) {
         for (const name of category.names) {
             const command = COMMAND_MAP.get(name);
             if (command)
-                lines.push(`    ${name.padEnd(26)}${command.description}`);
+                lines.push(`    ${name.padEnd(26)}${command.summary ?? command.description}`);
         }
     }
     lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
+function printCheckHelp(commandName) {
+    console.error([
+        'check',
+        '  检查指定浏览器，未指定时检查全部已连接浏览器',
+        '',
+        '用法：',
+        `  ${commandName} check [选项]`,
+        '',
+        '选项：',
+        '  --browser <id|名称>   只检查指定浏览器',
+        '  --connector <id|名称> 限制到一台远端 connector',
+        '  --local               只检查当前机器，不能与 --connector 同时使用',
+        '  --cdp                 当前机器强制使用 CDP（隐含 --local）',
+        '  --server <url>        覆盖 cloud-server WebSocket URL',
+        '  --timeout <seconds>   单项检查超时时间，默认 5 秒',
+        '  --json                输出机器可读 JSON',
+        '  -h, --help            查看帮助',
+    ].join('\n'));
+}
 function printAdvancedCommandHelp(commandName, action) {
     if (action !== 'connector_list')
         return;
@@ -112,12 +134,13 @@ function printAdvancedCommandHelp(commandName, action) {
     ].join('\n'));
 }
 function printCommandHelp(commandName, command) {
+    const payloadUsage = command.params?.length ? ' [--payload <json> | --payload-file <path>]' : '';
     const lines = [
         `${command.name}`,
         `  ${command.description}`,
         '',
         '用法：',
-        `  ${commandName} ${command.name} [--payload <json>] [--browser <id|名称>]`,
+        `  ${commandName} ${command.name}${payloadUsage} [通用选项]`,
         '',
     ];
     if (command.params?.length) {
@@ -133,6 +156,7 @@ function printCommandHelp(commandName, command) {
         for (const example of command.examples)
             lines.push(`  ${commandName} ${example}`);
     }
+    lines.push('', `运行 ${commandName} --help 查看通用选项。`);
     console.error(lines.join('\n'));
 }
 function printUnknownCommand(commandName, args) {
@@ -282,10 +306,12 @@ export async function runMearlCli(args, options = {}) {
         const command = COMMAND_MAP.get(args[0]);
         if (command)
             printCommandHelp(commandName, command);
+        else if (args[0] === 'check')
+            printCheckHelp(commandName);
         else if (ADVANCED_BUILTIN_COMMANDS.has(args[0])) {
             printAdvancedCommandHelp(commandName, args[0]);
         }
-        else if (args[0]?.startsWith('-') || BUILTIN_COMMANDS.some(item => item.name === args[0])) {
+        else if (args[0]?.startsWith('-')) {
             printUsage(commandName, clientVersion);
         }
         else {

package/dist/commands.d.ts

@@ -8,6 +8,8 @@ export interface ParamDef {
 export interface CommandDef {
     name: BrowserCommandAction;
     description: string;
+    /** 顶层命令列表使用的简短描述；完整说明保留在 action help。 */
+    summary?: string;
     /** CLI 中用于推荐 canonical action 的常见表达，不会作为可执行 action。 */
     aliases?: readonly string[];
     /** payload 字段说明 */
@@ -372,10 +374,12 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "browser_list";
     readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像与持久化 Context";
+    readonly summary: "列出本地及远端浏览器与连接状态";
     readonly examples: ["browser_list"];
 }, {
     readonly name: "browser_release";
     readonly description: "按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），保留浏览器和全部标签页；不用于普通任务收尾";
+    readonly summary: "释放浏览器调试控制及会话级临时效果";
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
     readonly name: "browser_launch";
@@ -529,7 +533,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["tab_close --payload '{\"tabId\":123}'"];
 }, {
     readonly name: "tab_list";
-    readonly description: "获取当前窗口所有标签页列表";
+    readonly description: "列出目标浏览器所有窗口中的标签页";
     readonly aliases: readonly ["tabs", "list_tabs", "show_tabs"];
     readonly examples: ["tab_list"];
 }, {
@@ -830,7 +834,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["page_snapshot", "page_snapshot --payload '{\"tabId\":1,\"mode\":\"viewport\"}'", "page_snapshot --payload '{\"tabId\":1,\"rootSelector\":\"[role=dialog]\"}'", "page_snapshot --payload '{\"tabId\":1,\"rootRef\":\"@e8\",\"ancestorDepth\":1}'", "page_snapshot --payload '{\"tabId\":1,\"query\":{\"text\":\"保存\",\"role\":\"button\"}}'"];
 }, {
     readonly name: "page_screenshot";
-    readonly description: "获取当前页面或指定元素截图";
+    readonly description: "获取当前视口或指定元素截图";
     readonly outputFlag: true;
     readonly params: [{
         readonly name: "selector";
@@ -872,7 +876,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["page_selected_element", "page_selected_element --output ./element.png"];
 }, {
     readonly name: "get_user_info";
-    readonly description: "获取当前登录用户的信息";
+    readonly description: "获取当前浏览器登录的阿里员工信息";
     readonly params: [{
         readonly name: "detail";
         readonly type: "boolean";
@@ -891,6 +895,7 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "record_stop";
     readonly description: "停止录制并返回完整结果（操作 + 关联请求）；未在录制时不报错，返回 wasRecording: false";
+    readonly summary: "停止录制并返回操作和关联请求";
     readonly params: [{
         readonly name: "tabId";
         readonly type: "number";
@@ -900,6 +905,7 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "set_device_emulation";
     readonly description: "把目标 tab 切换为移动端模拟（视口/UA/触摸），等价 DevTools 设备工具栏，作用域 per-tab；需保持调试控制才持续生效";
+    readonly summary: "设置或清除目标标签页的设备模拟";
     readonly params: [{
         readonly name: "enabled";
         readonly type: "boolean";
@@ -951,6 +957,7 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "set_app_profile";
     readonly description: "把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射 + 自适应系统标题栏），系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；用于桌面浏览器近似实机验证 App 内 H5，需保持调试控制才持续生效";
+    readonly summary: "设置或清除目标标签页的 App 容器模拟";
     readonly params: [{
         readonly name: "enabled";
         readonly type: "boolean";
@@ -1067,7 +1074,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["set_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\",\"value\":\"enabled\"}'", "set_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"value\":\"3.6.63\",\"domain\":\"taobao.com\",\"reload\":true}'"];
 }, {
     readonly name: "page_frames";
-    readonly description: "获取页面所有 iframe 列表";
+    readonly description: "获取页面主 frame 与所有 iframe 列表";
     readonly params: [{
         readonly name: "tabId";
         readonly type: "number";
@@ -1077,7 +1084,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["page_frames --payload '{\"tabId\":12345}'"];
 }, {
     readonly name: "request_domain_permission";
-    readonly description: "申请访问指定域名的权限（弹窗让用户授权）";
+    readonly description: "申请访问指定域名的权限（必要时弹窗让用户授权）";
     readonly params: [{
         readonly name: "domain";
         readonly type: "string";
@@ -1088,6 +1095,7 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "run_actions";
     readonly description: "批量顺序执行多个 action，减少往返延迟。遇错即停，返回已完成步骤结果；步骤内的页面动作不带内置观察";
+    readonly summary: "批量顺序执行多个 action，遇错即停";
     readonly params: [{
         readonly name: "actions";
         readonly type: "Array<{action: string, data?: object}>";

package/dist/commands.js

@@ -266,11 +266,13 @@ export const COMMANDS = [
     {
         name: 'browser_list',
         description: '列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像与持久化 Context',
+        summary: '列出本地及远端浏览器与连接状态',
         examples: ['browser_list'],
     },
     {
         name: 'browser_release',
         description: '按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），保留浏览器和全部标签页；不用于普通任务收尾',
+        summary: '释放浏览器调试控制及会话级临时效果',
         examples: ['browser_release', 'browser_release --browser chrome-a'],
     },
     {
@@ -445,7 +447,7 @@ export const COMMANDS = [
     },
     {
         name: 'tab_list',
-        description: '获取当前窗口所有标签页列表',
+        description: '列出目标浏览器所有窗口中的标签页',
         aliases: ['tabs', 'list_tabs', 'show_tabs'],
         examples: ['tab_list'],
     },
@@ -772,7 +774,7 @@ export const COMMANDS = [
     },
     {
         name: 'page_screenshot',
-        description: '获取当前页面或指定元素截图',
+        description: '获取当前视口或指定元素截图',
         outputFlag: true,
         params: [
             { name: 'selector', type: 'string', description: 'CSS 选择器，提供后只截取该元素区域' },
@@ -806,7 +808,7 @@ export const COMMANDS = [
     },
     {
         name: 'get_user_info',
-        description: '获取当前登录用户的信息',
+        description: '获取当前浏览器登录的阿里员工信息',
         params: [
             {
                 name: 'detail',
@@ -826,6 +828,7 @@ export const COMMANDS = [
     {
         name: 'record_stop',
         description: '停止录制并返回完整结果（操作 + 关联请求）；未在录制时不报错，返回 wasRecording: false',
+        summary: '停止录制并返回操作和关联请求',
         params: [{ name: 'tabId', type: 'number', description: '目标标签页 ID，从 tab_list 获取' }],
         examples: ['record_stop'],
     },
@@ -833,6 +836,7 @@ export const COMMANDS = [
     {
         name: 'set_device_emulation',
         description: '把目标 tab 切换为移动端模拟（视口/UA/触摸），等价 DevTools 设备工具栏，作用域 per-tab；需保持调试控制才持续生效',
+        summary: '设置或清除目标标签页的设备模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
             {
@@ -863,6 +867,7 @@ export const COMMANDS = [
     {
         name: 'set_app_profile',
         description: '把目标 tab 切换为 App 容器模拟态（客户端 UA + JSBridge 托管 + 页面跳转 iframe 容器栈 + scheme 唤端映射 + 自适应系统标题栏），系统栏由 iframe 外层统一渲染，并根据页面协议与桥调用切换普通、沉浸或隐藏状态；用于桌面浏览器近似实机验证 App 内 H5，需保持调试控制才持续生效',
+        summary: '设置或清除目标标签页的 App 容器模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
             {
@@ -975,13 +980,13 @@ export const COMMANDS = [
     // ── 其他 ──────────────────────────────────────────────────────────────────
     {
         name: 'page_frames',
-        description: '获取页面所有 iframe 列表',
+        description: '获取页面主 frame 与所有 iframe 列表',
         params: [{ name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' }],
         examples: [`page_frames --payload '{"tabId":12345}'`],
     },
     {
         name: 'request_domain_permission',
-        description: '申请访问指定域名的权限（弹窗让用户授权）',
+        description: '申请访问指定域名的权限（必要时弹窗让用户授权）',
         params: [
             {
                 name: 'domain',
@@ -996,6 +1001,7 @@ export const COMMANDS = [
     {
         name: 'run_actions',
         description: '批量顺序执行多个 action，减少往返延迟。遇错即停，返回已完成步骤结果；步骤内的页面动作不带内置观察',
+        summary: '批量顺序执行多个 action，遇错即停',
         params: [
             {
                 name: 'actions',

package/dist/generated-browser-action-protocol.d.ts

@@ -271,7 +271,7 @@ export interface BrowserEmulationOptions {
     orientation?: 'portrait' | 'landscape';
     touch?: boolean;
 }
-export type AppBridgeConfigBehavior = 'navigate' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'networkInfo' | 'geolocation' | 'permission' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest';
+export type AppBridgeConfigBehavior = 'navigate' | 'closeAll' | 'closeBackData' | 'postMessage' | 'notifySubscribe' | 'notifyUnsubscribe' | 'notifyPost' | 'sharedFileRead' | 'sharedFileWrite' | 'sharedDataGet' | 'sharedDataSet' | 'legacyBroadcastCreate' | 'legacyBroadcastPost' | 'legacyBroadcastClose' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'networkInfo' | 'geolocation' | 'permission' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest';
 /** 单个桥方法的声明式覆盖；行为、固定回包、成功空实现三选一。 */
 export interface AppBridgeMethodConfig {
     behavior?: AppBridgeConfigBehavior;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.9.0",
+  "version": "2.9.1",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -55,7 +55,7 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.9.0"
+    "@mearl/cloud-types": "2.9.1"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",