@mearl/client 2.13.0 → 2.15.0

package/dist/cli.js

@@ -8,13 +8,13 @@ import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from
 import { COMMANDS, COMMAND_MAP } from './commands.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
-import { findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, PluginError, } from './plugin.js';
+import { findPluginEntry, findPluginRegistration, listPluginNames, loadRegisteredPlugin, PluginError, } from './plugin.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
 const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
     {
         title: 'API 调试',
-        names: ['tab_checkpoint', 'get_requests', 'get_logs', 'get_events', 'get_api_schema'],
+        names: ['tab_checkpoint', 'get_requests', 'get_logs', 'get_events'],
     },
     { title: 'Mock & 规则', names: ['set_mock', 'get_mocks', 'set_rule', 'get_rules'] },
     {
@@ -46,9 +46,7 @@ const CATEGORIES = [
         title: '环境与 Cookie',
         names: ['set_device_emulation', 'set_app_profile', 'set_timezone', 'get_cookie', 'set_cookie'],
     },
-    { title: '用户信息', names: ['get_user_info'] },
     { title: '录制', names: ['record_start', 'record_stop'] },
-    { title: 'TDBank', names: ['tdbank_account'] },
     {
         title: '浏览器',
         names: ['browser_list', 'browser_release', 'browser_launch', 'browser_close'],
@@ -126,6 +124,78 @@ function printUsage(commandName, version) {
     lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
+function providerSchemaLine(name, schema, required, indent = 2) {
+    const detail = [
+        required ? '必填' : '可选',
+        schema.type,
+        schema.type === 'string' && schema.secret ? '敏感' : undefined,
+        schema.title,
+        schema.description,
+        schema.default === undefined ? undefined : `默认 ${JSON.stringify(schema.default)}`,
+    ].filter(Boolean);
+    return `${' '.repeat(indent)}${name.padEnd(Math.max(1, 24 - indent))}${detail.join(' · ')}`;
+}
+function providerSchemaLines(name, schema, required, indent = 2) {
+    const lines = [providerSchemaLine(name, schema, required, indent)];
+    if (schema.type === 'object') {
+        const childRequired = new Set(schema.required ?? []);
+        for (const [childName, childSchema] of Object.entries(schema.properties)) {
+            lines.push(...providerSchemaLines(childName, childSchema, childRequired.has(childName), indent + 2));
+        }
+    }
+    else if (schema.type === 'array' && schema.items.type === 'object') {
+        const childRequired = new Set(schema.items.required ?? []);
+        for (const [childName, childSchema] of Object.entries(schema.items.properties)) {
+            lines.push(...providerSchemaLines(childName, childSchema, childRequired.has(childName), indent + 2));
+        }
+    }
+    return lines;
+}
+function printProviderHelp(commandName, provider) {
+    const browserType = provider.browserType;
+    const lines = [
+        `${provider.providerId} — ${provider.name} v${provider.version}`,
+        '',
+        ...(browserType.help ?? []).map(line => String(line)),
+    ];
+    if (browserType.help?.length)
+        lines.push('');
+    lines.push('创建：', `  ${commandName} browser_launch --payload '{"provider":"${provider.providerId}","providerOptions":{}}'`, '', '启动参数（providerOptions）：');
+    const required = new Set(browserType.inputSchema.required ?? []);
+    const properties = Object.entries(browserType.inputSchema.properties);
+    if (properties.length === 0)
+        lines.push('  （无）');
+    else {
+        for (const [name, schema] of properties) {
+            lines.push(...providerSchemaLines(name, schema, required.has(name)));
+        }
+    }
+    if (browserType.inputSchema.oneOf?.length) {
+        lines.push('', '可选模式：');
+        browserType.inputSchema.oneOf.forEach((schema, index) => {
+            const mode = schema.title || `模式 ${index + 1}`;
+            const requiredFields = schema.required?.length ? schema.required.join(', ') : '无必填字段';
+            lines.push(`  ${mode}（必填：${requiredFields}）`);
+        });
+    }
+    lines.push('', '发现与检查：', `  ${commandName} browser_list`, `  ${commandName} check --browser <browserId>`, '', '管理：', `  npx @mearl/setup provider update ${provider.providerId}`, `  npx @mearl/setup provider uninstall ${provider.providerId}`);
+    if (browserType.configuration) {
+        lines.push('', 'Provider 配置（在 Mearl 浏览器管理器中填写）：');
+        const configurationRequired = new Set(browserType.configuration.inputSchema.required ?? []);
+        for (const [name, schema] of Object.entries(browserType.configuration.inputSchema.properties)) {
+            lines.push(...providerSchemaLines(name, schema, configurationRequired.has(name)));
+        }
+    }
+    if (browserType.documentationUrl) {
+        lines.push('', `文档：${browserType.documentationUrl}`);
+    }
+    console.error(lines.join('\n'));
+}
+function installedProvider(name) {
+    if (!name)
+        return undefined;
+    return listInstalledProviders().find(provider => provider.providerId === name);
+}
 function printCheckHelp(commandName) {
     console.error([
         'check',
@@ -341,7 +411,7 @@ export function parseClientArgs(args, plugin = false) {
             : {}),
     };
 }
-async function runPluginCli(args, entry, commandName) {
+async function runPluginCli(args, commandName) {
     let parsed;
     try {
         parsed = parseClientArgs(args, true);
@@ -359,23 +429,23 @@ async function runPluginCli(args, entry, commandName) {
             ...(parsed.local ? { local: true } : {}),
             ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
         };
-        const plugin = await loadPlugin(entry, {
-            options: invokeOptions,
-            progress(message) {
-                if (parsed.verbose) {
-                    process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
-                }
-            },
+        const plugin = await loadRegisteredPlugin(parsed.action, {
             async invoke(action, payload, options) {
                 client ??= new UnifiedClient({
                     ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
                 });
-                const result = await client.invoke(action, payload, { ...invokeOptions, ...options });
-                if (result?.action?.success === false)
-                    throw new Error(result.action.error || `${action} failed`);
-                return result;
+                return client.invoke(action, payload, options);
             },
-        }, parsed.action);
+        }, {
+            ...invokeOptions,
+            ...(parsed.verbose
+                ? {
+                    onProgress(message) {
+                        process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
+                    },
+                }
+                : {}),
+        });
         if (parsed.version) {
             console.log(plugin.version ?? 'unknown');
             return 0;
@@ -435,6 +505,12 @@ export async function runMearlCli(args, options = {}) {
     const clientVersion = options.clientVersion ?? CLIENT_VERSION;
     if (args[0] === 'capture_checkpoint')
         args = ['tab_checkpoint', ...args.slice(1)];
+    const provider = installedProvider(args[0]);
+    if (provider &&
+        (args.length === 1 || args.slice(1).every(arg => arg === '--help' || arg === '-h'))) {
+        printProviderHelp(commandName, provider);
+        return 0;
+    }
     if (args[0] &&
         !args[0].startsWith('-') &&
         !args[0].startsWith('__') &&
@@ -444,7 +520,7 @@ export async function runMearlCli(args, options = {}) {
         try {
             const entry = findPluginEntry(args[0]);
             if (entry)
-                return await runPluginCli(args, entry, commandName);
+                return await runPluginCli(args, commandName);
         }
         catch (error) {
             console.error(error instanceof Error ? error.message : String(error));

package/dist/commands.d.ts

@@ -142,24 +142,6 @@ export declare const COMMANDS: readonly [{
         readonly description: "返回完整 URL、_raw 和 _context；默认 false";
     }];
     readonly examples: ["get_events --payload '{\"source\":\"aplus\",\"event_type\":\"CLK\",\"limit\":10}'", "get_events --payload '{\"filter\":\"order\",\"includeRaw\":true,\"limit\":1}'", "get_events --payload '{\"tabId\":12345,\"source\":\"all\",\"limit\":20}'"];
-}, {
-    readonly name: "get_api_schema";
-    readonly description: "获取 API 接口 schema（出入参定义）";
-    readonly params: [{
-        readonly name: "api";
-        readonly type: "string";
-        readonly required: true;
-        readonly description: "API 名称";
-    }, {
-        readonly name: "version";
-        readonly type: "string";
-        readonly description: "API 版本，用于精确匹配接口定义";
-    }, {
-        readonly name: "fields";
-        readonly type: "(\"schema\" | \"hsf\")[]";
-        readonly description: "指定返回内容；不填时返回全部可用内容";
-    }];
-    readonly examples: ["get_api_schema --payload '{\"api\":\"mtop.trade.order.detail\"}'"];
 }, {
     readonly name: "set_mock";
     readonly description: "设置 API mock 数据";
@@ -334,100 +316,43 @@ export declare const COMMANDS: readonly [{
         readonly description: "超时毫秒数，默认 10000";
     }];
     readonly examples: ["send_mtop_request --payload '{\"api\":\"mtop.trade.order.detail\",\"data\":{\"orderId\":\"123\"}}'"];
-}, {
-    readonly name: "tdbank_account";
-    readonly description: "TDBank 账号操作：获取扫码登录二维码、当前账号、账号列表、切换账号、快速借用并切换账号";
-    readonly params: [{
-        readonly name: "tabId";
-        readonly type: "number";
-        readonly description: "login 首次不传；后续传上次响应的 tabId；无法恢复待扫码状态时会返回新的 tabId；其他操作在 CDP 模式下用于读取 Cookie";
-    }, {
-        readonly name: "operation";
-        readonly type: "\"current\" | \"list\" | \"login\" | \"switch\" | \"borrow\"";
-        readonly description: "操作类型，默认 current";
-    }, {
-        readonly name: "refresh";
-        readonly type: "boolean";
-        readonly description: "list 时是否强制刷新账号列表";
-    }, {
-        readonly name: "pageIndex";
-        readonly type: "number";
-        readonly description: "list 时的页码，默认 1";
-    }, {
-        readonly name: "accountId";
-        readonly type: "string | number";
-        readonly description: "switch 时使用账号列表中的 id";
-    }, {
-        readonly name: "havanaId";
-        readonly type: "string | number";
-        readonly description: "switch 时直接指定 havanaId；TDBank 方式需配合 site，免密方式需配合 ssoKey";
-    }, {
-        readonly name: "site";
-        readonly type: "string | number";
-        readonly description: "TDBank 方式直接指定 havanaId 时必填";
-    }, {
-        readonly name: "ssoKey";
-        readonly type: "string";
-        readonly description: "switch 免密方式的秘钥；必须同时传 havanaId，site 固定为 taobao";
-    }, {
-        readonly name: "query";
-        readonly type: "string";
-        readonly description: "borrow 时输入要借用的账号 loginId/关键词";
-    }, {
-        readonly name: "identityId";
-        readonly type: "string | number";
-        readonly description: "login 返回 identity_required 后，传用户明确选择的 identityId";
-    }];
-    readonly examples: ["tdbank_account --payload '{\"operation\":\"login\"}'", "tdbank_account --payload '{\"operation\":\"login\",\"tabId\":12345}'", "tdbank_account --payload '{\"operation\":\"login\",\"tabId\":12345,\"identityId\":\"10001\"}'", "tdbank_account --payload '{\"operation\":\"current\"}'", "tdbank_account --payload '{\"operation\":\"list\",\"refresh\":true}'", "tdbank_account --payload '{\"operation\":\"switch\",\"accountId\":12345}'", "tdbank_account --payload '{\"operation\":\"switch\",\"havanaId\":\"1234567890\",\"ssoKey\":\"<secret>\"}'", "tdbank_account --payload '{\"operation\":\"borrow\",\"query\":\"test_account\"}'"];
 }, {
     readonly name: "browser_list";
-    readonly description: "列出所有浏览器及其连接状态、类型和托管实例信息；AgentBay 可包含镜像与持久化 Context";
+    readonly description: "列出所有浏览器及其连接状态、类型和 Provider 托管实例信息";
     readonly summary: "列出本地及远端浏览器与连接状态";
     readonly examples: ["browser_list"];
 }, {
     readonly name: "browser_release";
-    readonly description: "sessionId 接入的 AgentBay 浏览器用它解除本机 attachment且不关闭云端 Session；其他浏览器仅按用户明确要求释放调试控制和会话级临时效果（含设备/时区模拟），不用于普通任务收尾";
-    readonly summary: "释放浏览器控制或解除 Session attachment";
+    readonly description: "释放当前浏览器的调试控制和会话级临时效果（含设备/时区模拟）；不用于普通任务收尾，Provider 实例的行为以 mearl <providerId> 为准";
+    readonly summary: "释放浏览器调试控制和会话级临时效果";
     readonly examples: ["browser_release", "browser_release --browser chrome-a"];
 }, {
     readonly name: "browser_launch";
-    readonly description: "启动本地 Chrome、创建/复用 AgentBay 云浏览器，或通过已注册 Provider 创建浏览器实例";
+    readonly description: "启动本地 Chrome，或通过已注册 Provider 创建浏览器实例";
     readonly params: [{
         readonly name: "name";
         readonly type: "string";
-        readonly description: "实例名称，创建浏览器时必填；按 sessionId 接入时可省略";
+        readonly description: "本地实例名称；使用 local Provider 时必填";
     }, {
         readonly name: "provider";
         readonly type: "string";
-        readonly description: "运行环境，默认 local；可传 agentbay 或 mearl --help 中展示的已注册 Provider ID";
+        readonly description: "运行环境，默认 local；可传 mearl --help 中展示的已注册 Provider ID";
     }, {
         readonly name: "providerOptions";
-        readonly type: "Record<string, string>";
-        readonly description: "外部 Provider 注册时声明的实例创建参数";
-    }, {
-        readonly name: "sessionId";
-        readonly type: "string";
-        readonly description: "显式接入现有 AgentBay Session；不会创建、初始化或取得其生命周期所有权";
-    }, {
-        readonly name: "reuse";
-        readonly type: "\"never\" | \"prefer\" | \"require\"";
-        readonly description: "AgentBay 运行实例复用策略：never 默认不复用；prefer 同名运行实例存在则复用、无记录则创建；require 只复用、不创建";
-    }, {
-        readonly name: "imageId";
-        readonly type: "string";
-        readonly description: "AgentBay 镜像别名或具体镜像 ID；默认使用已验证的 Linux Browser Use 内网镜像";
+        readonly type: "Record<string, JSON value>";
+        readonly description: "所选 Provider 声明的结构化启动参数；不能与顶层启动字段混用";
     }, {
         readonly name: "headless";
         readonly type: "boolean";
-        readonly description: "本地 provider 是否无头运行，默认 true；AgentBay 固定为 false，不支持 true";
+        readonly description: "本地 Provider 是否无头运行，默认 true";
     }, {
         readonly name: "userAgentMode";
         readonly type: "\"default\" | \"desktop\"";
-        readonly description: "UA 模式：default 使用 provider 默认 UA；desktop 本地使用匹配本机版本的 UA，AgentBay 复用控制浏览器的桌面 UA";
+        readonly description: "本地 UA 模式：default 使用默认 UA；desktop 使用匹配本机版本的 UA";
     }, {
         readonly name: "persistent";
         readonly type: "boolean";
-        readonly description: "关闭后是否保留浏览器状态，默认 false；本地保留 Profile，AgentBay 同名实例复用云端 Context";
+        readonly description: "本地实例关闭后是否保留 Profile，默认 false";
     }, {
         readonly name: "url";
         readonly type: "string";
@@ -436,35 +361,15 @@ export declare const COMMANDS: readonly [{
         readonly name: "executablePath";
         readonly type: "string";
         readonly description: "自定义 Chrome 可执行文件路径";
-    }, {
-        readonly name: "accountId";
-        readonly type: "string | number";
-        readonly description: "登录账号列表中的 accountId";
-    }, {
-        readonly name: "havanaId";
-        readonly type: "string | number";
-        readonly description: "直接登录 havanaId；需要同时传 site";
-    }, {
-        readonly name: "site";
-        readonly type: "string | number";
-        readonly description: "havanaId 对应的站点";
-    }, {
-        readonly name: "query";
-        readonly type: "string";
-        readonly description: "搜索、借用并登录匹配的 TDBank 账号";
-    }, {
-        readonly name: "tabId";
-        readonly type: "number";
-        readonly description: "CDP 控制浏览器中用于读取 TDBank Cookie 的标签页";
     }, {
         readonly name: "copyCookieDomains";
         readonly type: "string[] | \"mearl-services\" | { presets?: [\"mearl-services\"]; domains?: string[] }";
         readonly description: "从控制浏览器复制 Cookie：可传域名数组、Mearl 登录态预设，或组合预设与额外域名";
     }];
-    readonly examples: ["browser_launch --payload '{\"provider\":\"brow\",\"providerOptions\":{}}'", "browser_launch --payload '{\"name\":\"cloud-a\",\"provider\":\"agentbay\",\"userAgentMode\":\"desktop\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-public\",\"provider\":\"agentbay\",\"imageId\":\"browser_latest\",\"url\":\"https://example.com\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"persistent\":true,\"copyCookieDomains\":[\"example.com\"],\"url\":\"https://example.com/account\"}'", "browser_launch --payload '{\"name\":\"cloud-login\",\"provider\":\"agentbay\",\"reuse\":\"require\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --browser '<本地浏览器 browserId>' --payload '{\"sessionId\":\"<AgentBay sessionId>\",\"copyCookieDomains\":[\"example.com\"]}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":\"mearl-services\"}'", "browser_launch --payload '{\"name\":\"cloud-tools\",\"provider\":\"agentbay\",\"copyCookieDomains\":{\"presets\":[\"mearl-services\"],\"domains\":[\"figma.com\"]}}'", "browser_launch --payload '{\"name\":\"account-a\",\"headless\":true,\"accountId\":12345}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"account-b\",\"query\":\"test_account\",\"url\":\"https://www.taobao.com\"}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
+    readonly examples: ["browser_launch --payload '{\"provider\":\"brow\",\"providerOptions\":{}}'", "browser_launch --payload '{\"name\":\"figma\",\"userAgentMode\":\"desktop\",\"copyCookieDomains\":[\"figma.com\"]}'", "browser_launch --payload '{\"name\":\"with-cookies\",\"copyCookieDomains\":[\"example.com\",\"sub.example.org\"]}'"];
 }, {
     readonly name: "browser_close";
-    readonly description: "关闭指定托管浏览器并按策略保留或清理本地 Profile / AgentBay Context";
+    readonly description: "关闭指定托管浏览器，并按 Provider 策略保留或清理持久化数据";
     readonly params: [{
         readonly name: "browser";
         readonly type: "string";
@@ -473,9 +378,9 @@ export declare const COMMANDS: readonly [{
     }, {
         readonly name: "deleteProfile";
         readonly type: "boolean";
-        readonly description: "强制删除持久化本地 Profile 或 AgentBay Context，默认 false";
+        readonly description: "强制删除持久化数据，默认 false";
     }];
-    readonly examples: ["browser_close --payload '{\"browser\":\"managed:account-a\"}'", "browser_close --payload '{\"browser\":\"managed:agentbay:cloud-a\"}'", "browser_close --payload '{\"browser\":\"account-b\",\"deleteProfile\":true}'"];
+    readonly examples: ["browser_close --payload '{\"browser\":\"managed:account-a\"}'", "browser_close --payload '{\"browser\":\"account-b\",\"deleteProfile\":true}'"];
 }, {
     readonly name: "tab_open";
     readonly description: "打开或按 URL 规则复用 Tab，并等待新页面加载完成";
@@ -885,15 +790,6 @@ export declare const COMMANDS: readonly [{
         readonly description: "目标标签页 ID";
     }];
     readonly examples: ["page_selected_element", "page_selected_element --output ./element.png"];
-}, {
-    readonly name: "get_user_info";
-    readonly description: "获取当前浏览器登录的阿里员工信息";
-    readonly params: [{
-        readonly name: "detail";
-        readonly type: "boolean";
-        readonly description: "是否获取完整用户信息，默认 false（只返回工号）";
-    }];
-    readonly examples: ["get_user_info", "get_user_info --payload '{\"detail\":true}'"];
 }, {
     readonly name: "record_start";
     readonly description: "开始录制用户操作";
@@ -1034,7 +930,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["set_timezone --payload '{\"tabId\":12345,\"timezone\":\"America/New_York\"}'", "set_timezone --payload '{\"tabId\":12345,\"timezone\":\"\"}'"];
 }, {
     readonly name: "get_cookie";
-    readonly description: "读取当前标签页的一个指定非分区 Cookie；拒绝返回 HttpOnly Cookie";
+    readonly description: "从目标浏览器读取一个指定非分区 Cookie；拒绝返回 HttpOnly Cookie";
     readonly params: [{
         readonly name: "tabId";
         readonly type: "number";
@@ -1045,16 +941,20 @@ export declare const COMMANDS: readonly [{
         readonly type: "string";
         readonly required: true;
         readonly description: "要读取的 Cookie 名称；不支持列举全部 Cookie";
+    }, {
+        readonly name: "url";
+        readonly type: "string";
+        readonly description: "可选 Cookie 查询 URL；省略时使用当前标签页 URL";
     }, {
         readonly name: "domain";
         readonly type: "string";
-        readonly description: "可选精确域过滤，只允许当前 host 或其父域";
+        readonly description: "可选精确域过滤，只允许 Cookie 查询 URL 的 host 或其父域";
     }, {
         readonly name: "path";
         readonly type: "string";
         readonly description: "可选精确 path 过滤";
     }];
-    readonly examples: ["get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"domain\":\"taobao.com\"}'"];
+    readonly examples: ["get_cookie --payload '{\"tabId\":12345,\"name\":\"feature_flag\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"edith_switch_br.rx-vehicle-search_home\",\"domain\":\"taobao.com\"}'", "get_cookie --payload '{\"tabId\":12345,\"name\":\"tracknick\",\"url\":\"https://www.taobao.com/\",\"domain\":\"taobao.com\",\"path\":\"/\"}'"];
 }, {
     readonly name: "set_cookie";
     readonly description: "设置当前标签页域下的一个指定非分区 session Cookie，可选刷新页面";