@mearl/client 2.7.0 → 2.7.2

package/README.md

@@ -73,6 +73,9 @@ mearl browser_list
 mearl browser_release
 ```
 
+输入不存在或拼写有误的 action 时，CLI 会基于可用命令和常见别名直接返回最多三个候选及调用示例，
+不连接浏览器，也不会自动执行推荐命令。例如 `mearl tab new` 会优先推荐 `mearl tab_open`。
+
 **通用选项：**
 
 | 选项                     | 说明                     |
@@ -91,7 +94,7 @@ mearl browser_release
 
 | 分类        | Actions                                                                                                               |
 | ----------- | --------------------------------------------------------------------------------------------------------------------- |
-| API 调试    | `capture_checkpoint` `get_requests` `get_logs` `get_events` `get_api_schema`                                          |
+| 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`                                                                                     |
@@ -103,11 +106,11 @@ mearl browser_release
 | 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, 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_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 子树；ref 指向滚动容器内的子节点时，可用 `page_scroll.containerPolicy: "nearest"` 自动解析最近可滚动祖先。`page_click.clickMode` 默认 `auto`：可见桌面页派发可信 mouse，移动模拟页派发可信 touch；隐藏页使用 DOM fallback，返回 `dispatchMode: "dom"` 和 `fallbackReason: "page-hidden"`，且不切换标签或还原窗口。可用 `dom` / `mouse` / `touch` 覆盖自动策略；可信输入返回实际 `pointerType`。点击结果的 `resolvedTarget` 和滚动结果的前后位置、边界字段可用于诊断实际派发目标与滚动效果。
+重复文本点击可用 `page_click.scope` 限定 CSS / ref 子树；ref 指向滚动容器内的子节点时，可用 `page_scroll.containerPolicy: "nearest"` 自动解析最近可滚动祖先。点击结果的 `resolvedTarget` 和滚动结果的前后位置、边界字段可用于诊断实际目标与效果。
 
 `browser_list` 统一列出普通浏览器和托管浏览器。`type` 区分 `regular` / `managed`，`status` 区分 `connected` / `running_disconnected` / `stopped`；只有 `connected` 的浏览器可作为操作目标。
 

package/dist/actionTimeouts.js

@@ -1,5 +1,7 @@
 import { PAGE_ACT_ACTIONS } from './generated-browser-action-protocol.js';
 const SEND_REQUEST_FILE_TRANSFER_TIMEOUT_MS = 120_000;
+// AgentBay staging can spend up to 60s transferring bytes and then 120s syncing the session disk.
+const PAGE_UPLOAD_FILE_TRANSFER_TIMEOUT_MS = 180_000;
 // AgentBay context sync can poll for about 12 minutes before session deletion waits up to 5 more.
 const BROWSER_CLOSE_TIMEOUT_SEC = 18 * 60;
 function boundedNumber(value, fallback, minimum, maximum) {
@@ -56,6 +58,10 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
     const observationEnabled = action === 'page_eval'
         ? data.observe !== null && typeof data.observe === 'object' && !Array.isArray(data.observe)
         : data.observe !== false;
+    if (action === 'page_upload') {
+        const actionTimeoutSec = observationEnabled ? resolveObservedActionTimeoutSec(data) : fallback;
+        return Math.max(fallback, actionTimeoutSec + Math.ceil(PAGE_UPLOAD_FILE_TRANSFER_TIMEOUT_MS / 1000));
+    }
     if (observedAction && observationEnabled) {
         return Math.max(fallback, resolveObservedActionTimeoutSec(data));
     }

package/dist/cli.js

@@ -2,14 +2,15 @@ import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
 import { runUnifiedCheck, parseCheckTimeout } from './check.js';
-import { COMMAND_MAP } from './commands.js';
+import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from './commandSuggestions.js';
+import { COMMANDS, COMMAND_MAP } from './commands.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
 const CATEGORIES = [
     {
         title: 'API 调试',
-        names: ['capture_checkpoint', 'get_requests', 'get_logs', 'get_events', 'get_api_schema'],
+        names: ['tab_checkpoint', 'get_requests', 'get_logs', 'get_events', 'get_api_schema'],
     },
     { title: 'Mock & 规则', names: ['set_mock', 'get_mocks', 'set_rule', 'get_rules'] },
     { title: '网络代理', names: ['send_request', 'send_mtop_request'] },
@@ -45,6 +46,15 @@ const CATEGORIES = [
         names: ['browser_list', 'browser_release', 'browser_launch', 'browser_close'],
     },
 ];
+const BUILTIN_COMMANDS = [
+    {
+        name: 'check',
+        description: '检查指定浏览器，未指定时检查全部已连接浏览器',
+        examples: ['check'],
+    },
+];
+const SUGGESTABLE_COMMANDS = [...COMMANDS, ...BUILTIN_COMMANDS];
+const ADVANCED_BUILTIN_COMMANDS = new Set(['connector_list']);
 function optionValue(args, name) {
     const index = args.indexOf(name);
     return index >= 0 ? args[index + 1] : undefined;
@@ -76,7 +86,6 @@ function printUsage(commandName, version) {
         '',
         '内置命令：',
         '  check                 检查指定浏览器，未指定时检查全部已连接浏览器',
-        '  connector_list        列出 cloud-server 下的 connector',
     ];
     for (const category of CATEGORIES) {
         lines.push('', `  ${category.title}`);
@@ -89,6 +98,17 @@ function printUsage(commandName, version) {
     lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
+function printAdvancedCommandHelp(commandName, action) {
+    if (action !== 'connector_list')
+        return;
+    console.error([
+        'connector_list',
+        '  列出 cloud-server 下的 connector（高级诊断）',
+        '',
+        '用法：',
+        `  ${commandName} connector_list [--server <url>] [--timeout <seconds>]`,
+    ].join('\n'));
+}
 function printCommandHelp(commandName, command) {
     const lines = [
         `${command.name}`,
@@ -102,7 +122,7 @@ function printCommandHelp(commandName, command) {
         lines.push('参数（--payload JSON 字段）：');
         for (const parameter of command.params) {
             const required = parameter.required ? '必填' : '可选';
-            lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}${parameter.description}`);
+            lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}  ${parameter.description}`);
         }
         lines.push('');
     }
@@ -113,6 +133,18 @@ function printCommandHelp(commandName, command) {
     }
     console.error(lines.join('\n'));
 }
+function printUnknownCommand(commandName, args) {
+    const input = commandInput(args) || args[0] || '';
+    const suggestions = findCommandSuggestions(args, SUGGESTABLE_COMMANDS);
+    const lines = [`不支持的命令: ${input}`];
+    if (suggestions.length > 0) {
+        lines.push('', '你可能想用：', ...formatCommandSuggestions(commandName, suggestions));
+    }
+    else {
+        lines.push(`运行 ${commandName} --help 查看所有可用命令`);
+    }
+    console.error(lines.join('\n'));
+}
 function parsePositiveTimeout(value, fallback) {
     if (value === undefined)
         return fallback;
@@ -230,6 +262,8 @@ function writeOutput(action, result, outputPath) {
 export async function runMearlCli(args, options = {}) {
     const commandName = options.commandName ?? 'mearl';
     const clientVersion = options.clientVersion ?? CLIENT_VERSION;
+    if (args[0] === 'capture_checkpoint')
+        args = ['tab_checkpoint', ...args.slice(1)];
     if (args.includes('--version') || args.includes('-v')) {
         console.log(clientVersion);
         return 0;
@@ -242,10 +276,22 @@ export async function runMearlCli(args, options = {}) {
         const command = COMMAND_MAP.get(args[0]);
         if (command)
             printCommandHelp(commandName, command);
-        else
+        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])) {
             printUsage(commandName, clientVersion);
+        }
+        else {
+            printUnknownCommand(commandName, args);
+            return 2;
+        }
         return 0;
     }
+    if (args[0] !== 'check' && args[0] !== 'connector_list' && !COMMAND_MAP.has(args[0])) {
+        printUnknownCommand(commandName, args);
+        return 2;
+    }
     let parsed;
     try {
         parsed = parseArgs(args);
@@ -272,11 +318,6 @@ export async function runMearlCli(args, options = {}) {
         });
         return ok ? 0 : 1;
     }
-    if (parsed.action !== 'connector_list' && !COMMAND_MAP.has(parsed.action)) {
-        console.error(`不支持的 action: ${parsed.action}`);
-        console.error(`运行 ${commandName} --help 查看所有可用命令`);
-        return 2;
-    }
     if (parsed.action === 'page_selected_element' && parsed.outputPath) {
         parsed.payload = { ...parsed.payload, includeScreenshot: true };
     }
@@ -298,7 +339,7 @@ export async function runMearlCli(args, options = {}) {
         else {
             process.stdout.write(`${parsed.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2)}\n`);
         }
-        return 0;
+        return result?.action?.success === false ? 1 : 0;
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));

package/dist/commandSuggestions.d.ts

@@ -0,0 +1,13 @@
+export interface SuggestableCommand {
+    readonly aliases?: readonly string[];
+    readonly description: string;
+    readonly examples?: readonly string[];
+    readonly name: string;
+}
+export interface CommandSuggestion {
+    command: SuggestableCommand;
+    score: number;
+}
+export declare function commandInput(args: readonly string[]): string;
+export declare function findCommandSuggestions(args: readonly string[], commands: readonly SuggestableCommand[], limit?: number): CommandSuggestion[];
+export declare function formatCommandSuggestions(commandName: string, suggestions: readonly CommandSuggestion[]): string[];

package/dist/commandSuggestions.js

@@ -0,0 +1,59 @@
+import { distance } from 'fastest-levenshtein';
+const MIN_SIMILARITY = 0.5;
+const MAX_SCORE_GAP = 0.1;
+function normalizeCommand(value) {
+    return value
+        .normalize('NFKC')
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '_')
+        .replace(/^_+|_+$/g, '');
+}
+function leadingCommandParts(args) {
+    const parts = [];
+    for (const arg of args) {
+        if (arg.startsWith('-'))
+            break;
+        parts.push(arg);
+    }
+    return parts;
+}
+function commandQueries(args) {
+    const parts = leadingCommandParts(args);
+    const queries = new Set();
+    for (let length = parts.length; length > 0; length -= 1) {
+        const query = normalizeCommand(parts.slice(0, length).join('_'));
+        if (query)
+            queries.add(query);
+    }
+    return [...queries];
+}
+function similarity(left, right) {
+    const length = Math.max(left.length, right.length);
+    return length === 0 ? 0 : (length - distance(left, right)) / length;
+}
+export function commandInput(args) {
+    return leadingCommandParts(args).join(' ');
+}
+export function findCommandSuggestions(args, commands, limit = 3) {
+    const queries = commandQueries(args);
+    if (queries.length === 0 || limit <= 0)
+        return [];
+    const ranked = commands
+        .map(command => {
+        const keys = [command.name, ...(command.aliases ?? [])].map(normalizeCommand);
+        const score = Math.max(...queries.flatMap(query => keys.map(key => similarity(query, key))));
+        return { command, score };
+    })
+        .filter(suggestion => suggestion.score >= MIN_SIMILARITY)
+        .sort((left, right) => right.score - left.score || left.command.name.localeCompare(right.command.name));
+    const bestScore = ranked[0]?.score;
+    if (bestScore === undefined)
+        return [];
+    return ranked.filter(suggestion => bestScore - suggestion.score <= MAX_SCORE_GAP).slice(0, limit);
+}
+export function formatCommandSuggestions(commandName, suggestions) {
+    return suggestions.map(({ command }) => {
+        const invocation = command.examples?.[0] ?? command.name;
+        return `  ${commandName} ${invocation}\n    ${command.description}`;
+    });
+}

package/dist/commands.d.ts

@@ -8,6 +8,8 @@ export interface ParamDef {
 export interface CommandDef {
     name: BrowserCommandAction;
     description: string;
+    /** CLI 中用于推荐 canonical action 的常见表达，不会作为可执行 action。 */
+    aliases?: readonly string[];
     /** payload 字段说明 */
     params?: ParamDef[];
     /** 是否支持 --output */
@@ -15,14 +17,14 @@ export interface CommandDef {
     examples?: string[];
 }
 export declare const COMMANDS: readonly [{
-    readonly name: "capture_checkpoint";
-    readonly description: "为目标标签页建立 console/network 增量边界";
+    readonly name: "tab_checkpoint";
+    readonly description: "为目标标签页建立日志、请求和埋点增量边界";
     readonly params: [{
         readonly name: "tabId";
         readonly type: "number";
         readonly description: "目标标签页 ID，从 tab_open 获取";
     }];
-    readonly examples: ["capture_checkpoint --payload '{\"tabId\":12345}'"];
+    readonly examples: ["tab_checkpoint --payload '{\"tabId\":12345}'"];
 }, {
     readonly name: "get_requests";
     readonly description: "获取最近的网络请求（mtop 或普通 xhr/fetch）";
@@ -49,7 +51,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "after";
         readonly type: "string";
-        readonly description: "只返回指定 capture cursor 之后的请求";
+        readonly description: "只返回指定 tab checkpoint 或同类查询 cursor 之后的请求";
     }, {
         readonly name: "includeBody";
         readonly type: "boolean";
@@ -82,7 +84,7 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "after";
         readonly type: "string";
-        readonly description: "只返回指定 capture cursor 之后的日志";
+        readonly description: "只返回指定 tab checkpoint 或同类查询 cursor 之后的日志";
     }];
     readonly examples: ["get_logs --payload '{\"limit\":10,\"level\":\"error\"}'"];
 }, {
@@ -108,6 +110,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "since";
         readonly type: "number";
         readonly description: "只返回最近 N 秒内的事件";
+    }, {
+        readonly name: "after";
+        readonly type: "string";
+        readonly description: "只返回指定 tab checkpoint 之后的事件";
     }, {
         readonly name: "limit";
         readonly type: "number";
@@ -383,6 +389,7 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "tab_open";
     readonly description: "打开或按 URL 规则复用 Tab，并等待新页面加载完成";
+    readonly aliases: readonly ["tab_new", "new_tab", "tab_create", "create_tab"];
     readonly params: [{
         readonly name: "url";
         readonly type: "string";
@@ -425,6 +432,7 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "tab_close";
     readonly description: "关闭指定标签页";
+    readonly aliases: readonly ["tab_remove", "remove_tab", "tab_delete", "delete_tab"];
     readonly params: [{
         readonly name: "tabId";
         readonly type: "number";
@@ -435,10 +443,11 @@ export declare const COMMANDS: readonly [{
 }, {
     readonly name: "tab_list";
     readonly description: "获取当前窗口所有标签页列表";
+    readonly aliases: readonly ["tabs", "list_tabs", "show_tabs"];
     readonly examples: ["tab_list"];
 }, {
     readonly name: "page_click";
-    readonly description: "点击页面元素，支持 selector / text / point 三种定位方式；auto 在可见页按设备模拟状态使用可信 mouse/touch，隐藏页使用 DOM fallback；点击直接打开新标签页时 observation.openedTabs 返回目标信息";
+    readonly description: "点击页面元素，支持 CSS/@ref、可见文本或视口坐标定位";
     readonly params: [{
         readonly name: "selector";
         readonly type: "string";
@@ -466,12 +475,8 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "clickMode";
         readonly type: "\"auto\" | \"dom\" | \"mouse\" | \"touch\"";
-        readonly description: "点击模式；auto 在可见页按设备模拟状态选择可信 mouse/touch、隐藏页走 DOM，checkbox/radio 校验状态；其他值强制指定派发方式";
-    }, {
-        readonly name: "observe";
-        readonly type: "object | false";
-        readonly description: "观察选项（quietMs/firstChangeTimeoutMs/timeoutMs/navigationGraceMs/navigationTimeoutMs/networkIdleMs/contentReadyAfterMs）；传 false 只关闭 DOM/导航观察，默认诊断仍会返回";
-    }, ParamDef, {
+        readonly description: "默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式";
+    }, ParamDef, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";
         readonly required: true;
@@ -480,7 +485,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["page_click --payload '{\"text\":\"提交\"}'", "page_click --payload '{\"text\":\"退款明细\",\"role\":\"button\"}'", "page_click --payload '{\"text\":\"确定\",\"scope\":\"@e12\"}'", "page_click --payload '{\"selector\":\"@e3\"}'", "page_click --payload '{\"selector\":\".submit-btn\"}'", "page_click --payload '{\"selector\":\".gesture-btn\",\"clickMode\":\"touch\"}'", "page_click --payload '{\"point\":{\"x\":336,\"y\":117}}'"];
 }, {
     readonly name: "page_drag";
-    readonly description: "在页面内执行可信拖动手势；from/to 均可使用视口坐标或 CSS/@ref，auto 按设备模拟状态选择 mouse/touch，并默认观察拖动后的页面变化";
+    readonly description: "拖动页面元素或视口坐标，适用于轮播图、滑块和拖放";
     readonly params: [{
         readonly name: "from";
         readonly type: "string | { x: number; y: number }";
@@ -493,17 +498,13 @@ export declare const COMMANDS: readonly [{
         readonly description: "终点：原生 CSS、@eN ref，或 { x, y } 视口坐标（CSS 像素）";
     }, {
         readonly name: "dragMode";
-        readonly type: "\"auto\" | \"mouse\" | \"touch\"";
-        readonly description: "拖动输入类型；默认 auto，移动模拟页使用 touch，其余使用 mouse";
+        readonly type: "\"auto\" | \"dom\" | \"mouse\" | \"touch\"";
+        readonly description: "默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式";
     }, {
         readonly name: "durationMs";
         readonly type: "number";
         readonly description: "拖动持续时间，0–5000ms，默认 400ms；内部自动分段移动";
-    }, {
-        readonly name: "observe";
-        readonly type: "object | false";
-        readonly description: "观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回";
-    }, ParamDef, {
+    }, ParamDef, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";
         readonly required: true;
@@ -512,7 +513,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["page_drag --payload '{\"from\":{\"x\":350,\"y\":80},\"to\":{\"x\":80,\"y\":80}}'", "page_drag --payload '{\"from\":\"@e3\",\"to\":\"#drop-zone\",\"dragMode\":\"mouse\"}'"];
 }, {
     readonly name: "page_type";
-    readonly description: "向输入框填写文本，兼容 React 受控组件；默认观察校验提示等异步变化";
+    readonly description: "向输入框填写文本，兼容 React 受控组件";
     readonly params: [{
         readonly name: "selector";
         readonly type: "string";
@@ -527,11 +528,7 @@ export declare const COMMANDS: readonly [{
         readonly name: "clearFirst";
         readonly type: "boolean";
         readonly description: "是否先清空原有内容，默认 true";
-    }, {
-        readonly name: "observe";
-        readonly type: "object | false";
-        readonly description: "观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回";
-    }, ParamDef, {
+    }, ParamDef, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";
         readonly required: true;
@@ -540,17 +537,13 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["page_type --payload '{\"selector\":\"@e6\",\"text\":\"搜索关键词\"}'"];
 }, {
     readonly name: "page_hover";
-    readonly description: "将鼠标悬停在元素上，默认观察下拉菜单、提示信息等 hover 后变化";
+    readonly description: "将鼠标悬停在页面元素上";
     readonly params: [{
         readonly name: "selector";
         readonly type: "string";
         readonly required: true;
         readonly description: "原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）";
-    }, {
-        readonly name: "observe";
-        readonly type: "object | false";
-        readonly description: "观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回";
-    }, ParamDef, {
+    }, ParamDef, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";
         readonly required: true;
@@ -559,7 +552,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["page_hover --payload '{\"selector\":\".nav-menu\"}'"];
 }, {
     readonly name: "page_scroll";
-    readonly description: "滚动页面或指定容器，默认观察懒加载等滚动后变化";
+    readonly description: "滚动页面或指定容器";
     readonly params: [{
         readonly name: "direction";
         readonly type: "\"up\" | \"down\" | \"top\" | \"bottom\"";
@@ -577,11 +570,7 @@ export declare const COMMANDS: readonly [{
         readonly name: "containerPolicy";
         readonly type: "\"self\" | \"nearest\"";
         readonly description: "默认 self，要求 selector 本身可滚动；nearest 会在其不可滚动时使用最近的可滚动祖先";
-    }, {
-        readonly name: "observe";
-        readonly type: "object | false";
-        readonly description: "观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回";
-    }, ParamDef, {
+    }, ParamDef, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";
         readonly required: true;
@@ -613,7 +602,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["page_eval --payload '{\"expression\":\"document.title\"}'"];
 }, {
     readonly name: "page_press";
-    readonly description: "在页面中按下键盘按键，默认观察提交、关闭弹窗等结果";
+    readonly description: "在页面中按下键盘按键或组合键";
     readonly params: [{
         readonly name: "key";
         readonly type: "string";
@@ -623,11 +612,7 @@ export declare const COMMANDS: readonly [{
         readonly name: "modifiers";
         readonly type: "string[]";
         readonly description: "修饰键数组：ctrl/alt/shift/meta/cmd";
-    }, {
-        readonly name: "observe";
-        readonly type: "object | false";
-        readonly description: "观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回";
-    }, ParamDef, {
+    }, ParamDef, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";
         readonly required: true;
@@ -688,7 +673,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["page_navigate --payload '{\"tabId\":12345,\"url\":\"https://example.com/page2\"}'", "page_navigate --payload '{\"tabId\":12345,\"refresh\":true}'", "page_navigate --payload '{\"tabId\":12345,\"history\":\"back\"}'"];
 }, {
     readonly name: "page_upload";
-    readonly description: "向 <input type=\"file\"> 元素上传文件，默认观察上传状态变化";
+    readonly description: "向 <input type=\"file\"> 元素上传一个或多个文件";
     readonly params: [{
         readonly name: "selector";
         readonly type: "string";
@@ -699,11 +684,7 @@ export declare const COMMANDS: readonly [{
         readonly type: "string[]";
         readonly required: true;
         readonly description: "本地文件路径数组";
-    }, {
-        readonly name: "observe";
-        readonly type: "object | false";
-        readonly description: "观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回";
-    }, ParamDef, {
+    }, ParamDef, ParamDef, {
         readonly name: "tabId";
         readonly type: "number";
         readonly required: true;

package/dist/commands.js

@@ -1,15 +1,20 @@
 const PAGE_DIAGNOSTICS_PARAM = {
     name: 'diagnostics',
     type: 'object | boolean',
-    description: '交互动作默认在执行前原子建立边界，并返回新增 error logs/全部业务 requests；传 false 关闭，或传对象自定义过滤',
+    description: '默认关闭；传 true 返回动作期间新增的 error logs/业务 requests，或传对象自定义通道与过滤',
+};
+const PAGE_OBSERVE_PARAM = {
+    name: 'observe',
+    type: 'object | false',
+    description: '默认开启 DOM/导航观察；传 false 关闭，不影响显式请求的 diagnostics',
 };
 export const COMMANDS = [
     // ── API 调试 ──────────────────────────────────────────────────────────────
     {
-        name: 'capture_checkpoint',
-        description: '为目标标签页建立 console/network 增量边界',
+        name: 'tab_checkpoint',
+        description: '为目标标签页建立日志、请求和埋点增量边界',
         params: [{ name: 'tabId', type: 'number', description: '目标标签页 ID，从 tab_open 获取' }],
-        examples: [`capture_checkpoint --payload '{"tabId":12345}'`],
+        examples: [`tab_checkpoint --payload '{"tabId":12345}'`],
     },
     {
         name: 'get_requests',
@@ -24,7 +29,11 @@ export const COMMANDS = [
             },
             { name: 'filter', type: 'string', description: '按 URL 或 API 名称过滤，支持正则' },
             { name: 'since', type: 'number', description: '只返回最近 N 秒内的请求' },
-            { name: 'after', type: 'string', description: '只返回指定 capture cursor 之后的请求' },
+            {
+                name: 'after',
+                type: 'string',
+                description: '只返回指定 tab checkpoint 或同类查询 cursor 之后的请求',
+            },
             { name: 'includeBody', type: 'boolean', description: '是否包含请求/响应体，默认 true' },
         ],
         examples: [
@@ -41,7 +50,11 @@ export const COMMANDS = [
             { name: 'level', type: 'string', description: '按日志级别过滤：log/info/warn/error' },
             { name: 'filter', type: 'string', description: '按内容过滤，支持正则' },
             { name: 'since', type: 'number', description: '只返回最近 N 秒内的日志' },
-            { name: 'after', type: 'string', description: '只返回指定 capture cursor 之后的日志' },
+            {
+                name: 'after',
+                type: 'string',
+                description: '只返回指定 tab checkpoint 或同类查询 cursor 之后的日志',
+            },
         ],
         examples: [`get_logs --payload '{"limit":10,"level":"error"}'`],
     },
@@ -58,6 +71,7 @@ export const COMMANDS = [
             { name: 'event_type', type: 'string', description: '按事件类型过滤，支持正则，如 CLK/PV' },
             { name: 'filter', type: 'string', description: '按 name 或 url 过滤，支持正则' },
             { name: 'since', type: 'number', description: '只返回最近 N 秒内的事件' },
+            { name: 'after', type: 'string', description: '只返回指定 tab checkpoint 之后的事件' },
             { name: 'limit', type: 'number', description: '返回条数，默认 20' },
             {
                 name: 'includeRaw',
@@ -311,6 +325,7 @@ export const COMMANDS = [
     {
         name: 'tab_open',
         description: '打开或按 URL 规则复用 Tab，并等待新页面加载完成',
+        aliases: ['tab_new', 'new_tab', 'tab_create', 'create_tab'],
         params: [
             { name: 'url', type: 'string', required: true, description: '要打开的 URL' },
             { name: 'active', type: 'boolean', description: '是否激活新 Tab，默认 false' },
@@ -360,18 +375,20 @@ export const COMMANDS = [
     {
         name: 'tab_close',
         description: '关闭指定标签页',
+        aliases: ['tab_remove', 'remove_tab', 'tab_delete', 'delete_tab'],
         params: [{ name: 'tabId', type: 'number', required: true, description: '要关闭的标签页 ID' }],
         examples: [`tab_close --payload '{"tabId":123}'`],
     },
     {
         name: 'tab_list',
         description: '获取当前窗口所有标签页列表',
+        aliases: ['tabs', 'list_tabs', 'show_tabs'],
         examples: ['tab_list'],
     },
     // ── 页面操作 ──────────────────────────────────────────────────────────────
     {
         name: 'page_click',
-        description: '点击页面元素，支持 selector / text / point 三种定位方式；auto 在可见页按设备模拟状态使用可信 mouse/touch，隐藏页使用 DOM fallback；点击直接打开新标签页时 observation.openedTabs 返回目标信息',
+        description: '点击页面元素，支持 CSS/@ref、可见文本或视口坐标定位',
         params: [
             {
                 name: 'selector',
@@ -406,13 +423,9 @@ export const COMMANDS = [
             {
                 name: 'clickMode',
                 type: '"auto" | "dom" | "mouse" | "touch"',
-                description: '点击模式；auto 在可见页按设备模拟状态选择可信 mouse/touch、隐藏页走 DOM，checkbox/radio 校验状态；其他值强制指定派发方式',
-            },
-            {
-                name: 'observe',
-                type: 'object | false',
-                description: '观察选项（quietMs/firstChangeTimeoutMs/timeoutMs/navigationGraceMs/navigationTimeoutMs/networkIdleMs/contentReadyAfterMs）；传 false 只关闭 DOM/导航观察，默认诊断仍会返回',
+                description: '默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式',
             },
+            PAGE_OBSERVE_PARAM,
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
@@ -428,7 +441,7 @@ export const COMMANDS = [
     },
     {
         name: 'page_drag',
-        description: '在页面内执行可信拖动手势；from/to 均可使用视口坐标或 CSS/@ref，auto 按设备模拟状态选择 mouse/touch，并默认观察拖动后的页面变化',
+        description: '拖动页面元素或视口坐标，适用于轮播图、滑块和拖放',
         params: [
             {
                 name: 'from',
@@ -444,19 +457,15 @@ export const COMMANDS = [
             },
             {
                 name: 'dragMode',
-                type: '"auto" | "mouse" | "touch"',
-                description: '拖动输入类型；默认 auto，移动模拟页使用 touch，其余使用 mouse',
+                type: '"auto" | "dom" | "mouse" | "touch"',
+                description: '默认 auto：可见页使用匹配设备的可信输入，隐藏页使用 DOM；dom/mouse/touch 可强制指定派发方式',
             },
             {
                 name: 'durationMs',
                 type: 'number',
                 description: '拖动持续时间，0–5000ms，默认 400ms；内部自动分段移动',
             },
-            {
-                name: 'observe',
-                type: 'object | false',
-                description: '观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回',
-            },
+            PAGE_OBSERVE_PARAM,
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
@@ -467,7 +476,7 @@ export const COMMANDS = [
     },
     {
         name: 'page_type',
-        description: '向输入框填写文本，兼容 React 受控组件；默认观察校验提示等异步变化',
+        description: '向输入框填写文本，兼容 React 受控组件',
         params: [
             {
                 name: 'selector',
@@ -477,11 +486,7 @@ export const COMMANDS = [
             },
             { name: 'text', type: 'string', required: true, description: '要填写的文本' },
             { name: 'clearFirst', type: 'boolean', description: '是否先清空原有内容，默认 true' },
-            {
-                name: 'observe',
-                type: 'object | false',
-                description: '观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回',
-            },
+            PAGE_OBSERVE_PARAM,
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
@@ -489,7 +494,7 @@ export const COMMANDS = [
     },
     {
         name: 'page_hover',
-        description: '将鼠标悬停在元素上，默认观察下拉菜单、提示信息等 hover 后变化',
+        description: '将鼠标悬停在页面元素上',
         params: [
             {
                 name: 'selector',
@@ -497,11 +502,7 @@ export const COMMANDS = [
                 required: true,
                 description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀）',
             },
-            {
-                name: 'observe',
-                type: 'object | false',
-                description: '观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回',
-            },
+            PAGE_OBSERVE_PARAM,
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
@@ -509,7 +510,7 @@ export const COMMANDS = [
     },
     {
         name: 'page_scroll',
-        description: '滚动页面或指定容器，默认观察懒加载等滚动后变化',
+        description: '滚动页面或指定容器',
         params: [
             {
                 name: 'direction',
@@ -528,11 +529,7 @@ export const COMMANDS = [
                 type: '"self" | "nearest"',
                 description: '默认 self，要求 selector 本身可滚动；nearest 会在其不可滚动时使用最近的可滚动祖先',
             },
-            {
-                name: 'observe',
-                type: 'object | false',
-                description: '观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回',
-            },
+            PAGE_OBSERVE_PARAM,
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
@@ -565,7 +562,7 @@ export const COMMANDS = [
     },
     {
         name: 'page_press',
-        description: '在页面中按下键盘按键，默认观察提交、关闭弹窗等结果',
+        description: '在页面中按下键盘按键或组合键',
         params: [
             {
                 name: 'key',
@@ -574,11 +571,7 @@ export const COMMANDS = [
                 description: '按键名称：Enter/Tab/Escape/Backspace 等',
             },
             { name: 'modifiers', type: 'string[]', description: '修饰键数组：ctrl/alt/shift/meta/cmd' },
-            {
-                name: 'observe',
-                type: 'object | false',
-                description: '观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回',
-            },
+            PAGE_OBSERVE_PARAM,
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],
@@ -638,7 +631,7 @@ export const COMMANDS = [
     },
     {
         name: 'page_upload',
-        description: '向 <input type="file"> 元素上传文件，默认观察上传状态变化',
+        description: '向 <input type="file"> 元素上传一个或多个文件',
         params: [
             {
                 name: 'selector',
@@ -647,11 +640,7 @@ export const COMMANDS = [
                 description: '原生 CSS 选择器，或 page_snapshot / 页面动作 observation 返回的 @eN ref（必须带 @ 前缀），必须指向 input[type=file]',
             },
             { name: 'filePaths', type: 'string[]', required: true, description: '本地文件路径数组' },
-            {
-                name: 'observe',
-                type: 'object | false',
-                description: '观察选项；传 false 只关闭 DOM/导航观察，默认诊断仍会返回',
-            },
+            PAGE_OBSERVE_PARAM,
             PAGE_DIAGNOSTICS_PARAM,
             { name: 'tabId', type: 'number', required: true, description: '目标标签页 ID' },
         ],

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

@@ -4,7 +4,7 @@ export interface GetRequestsParams {
     filter?: string;
     /** Relative time window in seconds. */
     since?: number;
-    /** Opaque cursor returned by capture_checkpoint or a previous query. */
+    /** Opaque cursor returned by tab_checkpoint or a previous query. */
     after?: string;
     includeBody?: boolean;
     includeHeaders?: boolean;
@@ -19,7 +19,7 @@ export interface GetLogsParams {
     level?: 'log' | 'warn' | 'error' | 'info' | 'all';
     /** Relative time window in seconds. */
     since?: number;
-    /** Opaque cursor returned by capture_checkpoint or a previous query. */
+    /** Opaque cursor returned by tab_checkpoint or a previous query. */
     after?: string;
     limit?: number;
     filter?: string;
@@ -39,6 +39,8 @@ export interface GetEventsParams {
     event_type?: string;
     filter?: string;
     since?: number;
+    /** Opaque cursor returned by tab_checkpoint or a previous event query. */
+    after?: string;
     limit?: number;
     includeRaw?: boolean;
 }
@@ -299,6 +301,7 @@ export interface PageObservationWaitOptions {
 export interface PageDiagnosticsOptions {
     logs?: boolean | Pick<GetLogsParams, 'level' | 'limit' | 'filter'>;
     requests?: boolean | Pick<GetRequestsParams, 'count' | 'filter' | 'includeBody' | 'includeHeaders' | 'maxBodySize' | 'fields' | 'keysOnly' | 'source'>;
+    events?: boolean | Pick<GetEventsParams, 'source' | 'event_type' | 'filter' | 'limit' | 'includeRaw'>;
 }
 export type PageDiagnosticsSetting = PageDiagnosticsOptions | boolean;
 export interface PageClickParams {
@@ -325,7 +328,7 @@ export interface PageDragParams {
     tabId?: number;
     from: PageDragEndpoint;
     to: PageDragEndpoint;
-    dragMode?: 'auto' | 'mouse' | 'touch';
+    dragMode?: 'auto' | 'dom' | 'mouse' | 'touch';
     durationMs?: number;
     observe?: PageObservationWaitOptions | false;
     diagnostics?: PageDiagnosticsSetting;
@@ -471,6 +474,11 @@ export interface RunActionsParams {
     tabId: number;
 }
 export interface BrowserActionMap {
+    tab_checkpoint: {
+        request: CaptureCheckpointParams;
+        response: CaptureCheckpointResult;
+    };
+    /** Compatibility alias for tab_checkpoint. */
     capture_checkpoint: {
         request: CaptureCheckpointParams;
         response: CaptureCheckpointResult;
@@ -652,6 +660,7 @@ export type ExtensionBrowserAction = Exclude<BrowserCommandAction, 'browser_list
 export declare const PAGE_ACT_ACTIONS: readonly ["page_click", "page_drag", "page_type", "page_hover", "page_scroll", "page_press", "page_upload", "page_eval"];
 export type PageActAction = (typeof PAGE_ACT_ACTIONS)[number];
 export declare const BROWSER_ACTIONS: {
+    readonly tab_checkpoint: true;
     readonly capture_checkpoint: true;
     readonly get_requests: true;
     readonly get_logs: true;
@@ -697,6 +706,7 @@ export declare const BROWSER_ACTIONS: {
     readonly run_actions: true;
 };
 export declare const BROWSER_COMMAND_ACTIONS: {
+    readonly tab_checkpoint: true;
     readonly capture_checkpoint: true;
     readonly get_requests: true;
     readonly get_logs: true;
@@ -741,6 +751,7 @@ export declare const BROWSER_COMMAND_ACTIONS: {
     readonly run_actions: true;
 };
 export declare const EXTENSION_BROWSER_ACTIONS: {
+    readonly tab_checkpoint: true;
     readonly capture_checkpoint: true;
     readonly get_requests: true;
     readonly get_logs: true;

package/dist/generated-browser-action-protocol.js

@@ -17,6 +17,7 @@ export const PAGE_ACT_ACTIONS = [
     'page_eval',
 ];
 export const BROWSER_ACTIONS = {
+    tab_checkpoint: true,
     capture_checkpoint: true,
     get_requests: true,
     get_logs: true,
@@ -62,6 +63,7 @@ export const BROWSER_ACTIONS = {
     run_actions: true,
 };
 export const BROWSER_COMMAND_ACTIONS = {
+    tab_checkpoint: true,
     capture_checkpoint: true,
     get_requests: true,
     get_logs: true,
@@ -106,6 +108,7 @@ export const BROWSER_COMMAND_ACTIONS = {
     run_actions: true,
 };
 export const EXTENSION_BROWSER_ACTIONS = {
+    tab_checkpoint: true,
     capture_checkpoint: true,
     get_requests: true,
     get_logs: true,

package/dist/index.d.ts

@@ -10,7 +10,9 @@ export { BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PA
 export type { ActionStep, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserLaunchParams, BrowserListResult, BrowserReleaseFailure, BrowserReleaseResult, BrowserSource, BrowserStatus, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetApiSchemaParams, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, GetUserInfoParams, ManagedBrowserAccount, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSelectedElementParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RecordParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, TdbankAccountParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';
 import type * as Protocol from './generated-browser-action-protocol.js';
-export declare function captureCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'capture_checkpoint'>>;
+export declare function tabCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
+/** Compatibility wrapper for tabCheckpoint. */
+export declare function captureCheckpoint(params?: Protocol.CaptureCheckpointParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'tab_checkpoint'>>;
 export declare function getRequests(params?: Protocol.GetRequestsParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_requests'>>;
 export declare function getLogs(params?: Protocol.GetLogsParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_logs'>>;
 export declare function getEvents(params?: Protocol.GetEventsParams, options?: UnifiedInvokeOptions): Promise<Protocol.BrowserActionResponse<'get_events'>>;

package/dist/index.js

@@ -7,8 +7,12 @@
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, listCloudConnectors, } from './unified.js';
 export { BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
 import { invoke } from './unified.js';
+export function tabCheckpoint(params = {}, options) {
+    return invoke('tab_checkpoint', params, options);
+}
+/** Compatibility wrapper for tabCheckpoint. */
 export function captureCheckpoint(params = {}, options) {
-    return invoke('capture_checkpoint', params, options);
+    return tabCheckpoint(params, options);
 }
 export function getRequests(params = {}, options) {
     return invoke('get_requests', params, options);

package/dist/unified.js

@@ -205,7 +205,12 @@ export class UnifiedClient {
         if (!localAvailable && connectors.length === 0) {
             throw new Error('No browser host is available. Install @mearl/native-host locally or connect a cloud connector.');
         }
-        throw new Error('The browser host for browser_launch is ambiguous. Pass --local, --connector <id|name>, or --browser <global-id>.');
+        const availableHosts = [
+            ...(localAvailable ? ['this machine [--local]'] : []),
+            ...connectors.map(connector => `${connector.name} [${connector.connectorId}]`),
+        ].join(', ');
+        throw new Error('The browser host for browser_launch is ambiguous. ' +
+            `Pass --local, --connector <id|name>, or --browser <global-id>. Available: ${availableHosts}`);
     }
     async selectDefaultBrowser(data, options, timeoutSec) {
         const selector = typeof data.browser === 'string' ? data.browser.trim() : '';
@@ -261,11 +266,14 @@ export class UnifiedClient {
     async resolveConnector(selector, timeoutSec) {
         const connectors = (await this.listConnectors(timeoutSec)).connectors;
         const selection = resolveCloudConnectorSelector(connectors, selector);
+        const available = connectors
+            .map(connector => `${connector.name} [${connector.connectorId}]`)
+            .join(', ');
         if (selection.status === 'ambiguous') {
-            throw new Error(`Cloud connector selector "${selector}" is ambiguous. Use an exact connectorId.`);
+            throw new Error(`Cloud connector selector "${selector}" is ambiguous. Use an exact connectorId. Available: ${available}`);
         }
         if (selection.status !== 'matched') {
-            throw new Error(`No cloud connector matches "${selector}".`);
+            throw new Error(`No cloud connector matches "${selector}". Available: ${available}`);
         }
         return selection.connector;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.7.0",
+  "version": "2.7.2",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -48,8 +48,9 @@
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
+    "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.7.0"
+    "@mearl/cloud-types": "2.7.2"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",