@mearl/client 2.5.1 → 2.6.1

package/dist/cli.js

@@ -1,22 +1,11 @@
-#!/usr/bin/env node
-/**
- * mearl CLI — 通过命令行调用 Mearl 浏览器插件能力
- *
- * 用法：
- *   mearl <action> [--payload <json> | --payload-file <path>] [--timeout <seconds>] [--compact] [--output <path>]
- *
- * 示例：
- *   mearl get_requests --payload '{"count":5}'
- *   mearl send_request --payload '{"url":"https://api.example.com","method":"GET"}'
- *   mearl page_screenshot --output ./screenshot.png
- *   mearl set_mock --payload-file ./mock-data.json
- */
-import fs from 'node:fs';
-import { invoke, CLIENT_VERSION } from './socket.js';
-import { COMMAND_MAP } from './commands.js';
-import { runCheck } from './check.js';
+import { readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
-// ─── Usage / Help ─────────────────────────────────────────────────────────────
+import { runUnifiedCheck, parseCheckTimeout } from './check.js';
+import { 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 调试',
@@ -56,275 +45,266 @@ const CATEGORIES = [
         names: ['browser_list', 'browser_release', 'browser_launch', 'browser_close'],
     },
 ];
-function printUsage() {
+function optionValue(args, name) {
+    const index = args.indexOf(name);
+    return index >= 0 ? args[index + 1] : undefined;
+}
+function printUsage(commandName, version) {
     const lines = [
+        `${commandName} v${version}`,
+        '',
         '用法：',
-        '  mearl <action> [选项]',
-        '  mearl <action> --help',
-        '  mearl check',
+        `  ${commandName} <action> [选项]`,
+        `  ${commandName} <action> --help`,
+        `  ${commandName} check [--browser <id|名称>] [--connector <id|名称>]`,
+        '',
+        '统一目标发现：',
+        '  browser_list 默认列出当前机器和 cloud-server 下所有 connector 的浏览器。',
+        '  后续操作使用列表返回的全局 browserId，客户端会自动选择本地或远端传输。',
         '',
         '通用选项：',
         '  --payload <json>      直接传入 JSON 参数',
-        '  --payload-file <path> 从文件读取整个 JSON 参数（适合大体积 payload）',
-        '  --timeout <seconds>   超时时间（默认按 action 推导，普通 action 为 15 秒）',
+        '  --payload-file <path> 从文件读取整个 JSON 参数',
+        '  --timeout <seconds>   超时时间（默认按 action 推导）',
         '  --compact             输出紧凑格式 JSON',
-        '  --output <path>       输出文件路径（page_screenshot / page_selected_element 可用）',
-        '  --cdp                 强制使用 CDP 模式（跳过插件通道）',
-        '  --browser <id|名称>   指定目标浏览器（多浏览器时；缺省用最近聚焦的那个）',
-        '',
-        '文件引用（任意 action 通用，减少上下文占用）：',
-        '  payload 顶层字段写成 "@<path>"（@ 开头的字符串）即从文件读取该字段值，',
-        '  默认按 JSON 解析、失败按原始文本；找不到文件则原样保留该字符串。',
-        `  例：set_mock --payload '{"apiName":"x","mockData":"@/abs/resp.json"}'`,
+        '  --output <path>       保存输出或截图',
+        '  --browser <id|名称>   指定 browser_list 返回的浏览器',
+        '  --connector <id|名称> 限制到一台远端 connector',
+        '  --local               只使用当前机器上的浏览器',
+        '  --cdp                 当前机器强制使用 CDP（隐含 --local）',
+        '  --server <url>        覆盖 cloud-server WebSocket URL',
         '',
         '内置命令：',
-        '  check                 检测环境配置，排查连接问题',
+        '  check                 检查指定浏览器，未指定时检查全部已连接浏览器',
+        '  connector_list        列出 cloud-server 下的 connector',
     ];
-    for (const cat of CATEGORIES) {
-        lines.push('');
-        lines.push(`  ${cat.title}`);
-        for (const name of cat.names) {
-            const cmd = COMMAND_MAP.get(name);
-            if (cmd) {
-                lines.push(`    ${name.padEnd(26)}${cmd.description}`);
-            }
+    for (const category of CATEGORIES) {
+        lines.push('', `  ${category.title}`);
+        for (const name of category.names) {
+            const command = COMMAND_MAP.get(name);
+            if (command)
+                lines.push(`    ${name.padEnd(26)}${command.description}`);
         }
     }
-    lines.push('');
-    lines.push('运行 mearl <action> --help 查看某个命令的详细参数');
+    lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
-function printCommandHelp(cmd) {
-    const outputOption = cmd.outputFlag ? ' [--output <path>]' : '';
+function printCommandHelp(commandName, command) {
     const lines = [
-        `${cmd.name}`,
-        `  ${cmd.description}`,
+        `${command.name}`,
+        `  ${command.description}`,
         '',
         '用法：',
-        `  mearl ${cmd.name} [--payload <json>] [--timeout <seconds>]${outputOption}`,
+        `  ${commandName} ${command.name} [--payload <json>] [--browser <id|名称>]`,
         '',
     ];
-    if (cmd.params && cmd.params.length > 0) {
+    if (command.params?.length) {
         lines.push('参数（--payload JSON 字段）：');
-        for (const p of cmd.params) {
-            const req = p.required ? '必填' : '可选';
-            lines.push(`  ${p.name.padEnd(22)}${req.padEnd(6)}${p.type.padEnd(28)}${p.description}`);
+        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('');
     }
-    if (cmd.outputFlag) {
-        lines.push('CLI 选项：');
-        lines.push('  --output <path>       将截图保存到本地文件');
-        lines.push('');
-    }
-    if (cmd.examples && cmd.examples.length > 0) {
+    if (command.examples?.length) {
         lines.push('示例：');
-        for (const ex of cmd.examples) {
-            lines.push(`  mearl ${ex}`);
-        }
-        lines.push('');
+        for (const example of command.examples)
+            lines.push(`  ${commandName} ${example}`);
     }
     console.error(lines.join('\n'));
 }
-function parseArgs(argv) {
-    if (argv.includes('--version') || argv.includes('-v')) {
-        console.log(CLIENT_VERSION);
-        process.exit(0);
+function parsePositiveTimeout(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    const parsed = Number(value);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        throw new Error('--timeout 必须是大于 0 的数字');
     }
-    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
-        return { showHelp: true, action: COMMAND_MAP.has(argv[0]) ? argv[0] : undefined };
+    return parsed;
+}
+function parsePayload(args) {
+    const payloadRaw = optionValue(args, '--payload');
+    const payloadFile = optionValue(args, '--payload-file');
+    if (payloadRaw !== undefined && payloadFile !== undefined) {
+        throw new Error('--payload 与 --payload-file 不能同时使用');
     }
-    const action = argv[0];
-    let payloadRaw = '{}';
-    let payloadFile = null;
-    let timeoutSec;
-    let compact = false;
-    let outputPath = null;
-    let forceCdp = false;
-    let browser;
-    let i = 1;
-    while (i < argv.length) {
-        const arg = argv[i];
-        if (arg === '--payload') {
-            if (i + 1 >= argv.length)
-                throw new Error('缺少 --payload 的参数值');
-            payloadRaw = argv[i + 1];
-            i += 2;
-            continue;
-        }
-        if (arg === '--payload-file') {
-            if (i + 1 >= argv.length)
-                throw new Error('缺少 --payload-file 的参数值');
-            payloadFile = argv[i + 1];
-            i += 2;
-            continue;
+    if (payloadRaw !== undefined) {
+        try {
+            return JSON.parse(payloadRaw);
         }
-        if (arg === '--timeout') {
-            if (i + 1 >= argv.length)
-                throw new Error('缺少 --timeout 的参数值');
-            const value = Number(argv[i + 1]);
-            if (!Number.isFinite(value) || value <= 0)
-                throw new Error('--timeout 必须是大于 0 的数字');
-            timeoutSec = value;
-            i += 2;
-            continue;
+        catch (error) {
+            throw new Error('无效的 JSON payload', { cause: error });
         }
-        if (arg === '--compact') {
-            compact = true;
-            i += 1;
-            continue;
+    }
+    if (payloadFile !== undefined) {
+        try {
+            return JSON.parse(readFileSync(resolve(payloadFile), 'utf8'));
         }
-        if (arg === '--cdp') {
-            forceCdp = true;
-            i += 1;
-            continue;
+        catch (error) {
+            throw new Error(`无法读取或解析 payload 文件: ${payloadFile}`, { cause: error });
         }
-        if (arg === '--browser') {
-            if (i + 1 >= argv.length)
-                throw new Error('缺少 --browser 的参数值');
-            browser = argv[i + 1];
-            i += 2;
+    }
+    return {};
+}
+function validateOptions(args) {
+    const optionsWithValues = new Set([
+        '--payload',
+        '--payload-file',
+        '--timeout',
+        '--output',
+        '--browser',
+        '--connector',
+        '--server',
+    ]);
+    const flags = new Set(['--compact', '--local', '--cdp', '--help', '-h']);
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        if (optionsWithValues.has(arg)) {
+            if (!args[index + 1] || args[index + 1].startsWith('--')) {
+                throw new Error(`缺少 ${arg} 的参数值`);
+            }
+            index += 1;
             continue;
         }
-        if (arg === '--output') {
-            if (i + 1 >= argv.length)
-                throw new Error('缺少 --output 的参数值');
-            outputPath = argv[i + 1];
-            i += 2;
+        if (flags.has(arg))
             continue;
-        }
         throw new Error(`未知参数: ${arg}`);
     }
+}
+function resolveServer(args) {
+    const explicit = optionValue(args, '--server');
+    if (explicit)
+        return { serverUrl: explicit, serverUrlSource: '--server' };
+    if (process.env.MEARL_SERVER_URL) {
+        return { serverUrl: process.env.MEARL_SERVER_URL, serverUrlSource: 'MEARL_SERVER_URL' };
+    }
+    const config = loadCloudServerConfig();
+    return config?.server
+        ? { serverUrl: config.server, serverUrlSource: getCloudServerConfigPath() }
+        : {};
+}
+function parseArgs(args) {
+    validateOptions(args);
+    const action = args[0];
+    const payload = parsePayload(args);
+    const fallbackTimeout = resolveActionTimeoutSec(action, payload, 60);
+    const forceCdp = args.includes('--cdp');
+    const local = forceCdp || args.includes('--local');
+    const connector = optionValue(args, '--connector');
+    if (local && connector)
+        throw new Error('--local/--cdp 不能与 --connector 同时使用');
     return {
-        showHelp: false,
         action,
-        payloadRaw,
-        payloadFile,
-        timeoutSec,
-        compact,
-        outputPath,
+        payload,
+        timeoutSec: parsePositiveTimeout(optionValue(args, '--timeout'), fallbackTimeout),
+        compact: args.includes('--compact'),
         forceCdp,
-        browser,
+        local,
+        ...(optionValue(args, '--output') ? { outputPath: optionValue(args, '--output') } : {}),
+        ...(optionValue(args, '--browser') ? { browser: optionValue(args, '--browser') } : {}),
+        ...(connector ? { connector } : {}),
+        ...resolveServer(args),
     };
 }
-function parsePayload(payloadRaw) {
-    try {
-        return JSON.parse(payloadRaw);
+function screenshotData(action, result) {
+    if (typeof result === 'string' && result.startsWith('data:image')) {
+        return result.split(',')[1] ?? null;
     }
-    catch (error) {
-        throw new Error(`无效的 JSON payload: ${payloadRaw}`, { cause: error });
+    if (action === 'page_screenshot' && typeof result?.data === 'string')
+        return result.data;
+    if (action === 'page_selected_element' && typeof result?.screenshot?.data === 'string') {
+        return result.screenshot.data;
     }
+    return null;
 }
-function saveBase64Image(outputPath, base64Data) {
-    fs.writeFileSync(outputPath, Buffer.from(base64Data, 'base64'));
-}
-function extractScreenshotResult(action, result) {
-    if (action === 'page_screenshot' && result?.meta && result?.data) {
-        return {
-            label: 'Screenshot',
-            meta: result.meta,
-            data: result.data,
-            extraLines: [`  Page: ${result.meta.title}`, `  URL: ${result.meta.url}`],
-        };
+function writeOutput(action, result, outputPath) {
+    const image = screenshotData(action, result);
+    if (image) {
+        writeFileSync(outputPath, Buffer.from(image, 'base64'));
     }
-    if (action === 'page_selected_element' && result?.screenshot?.meta && result?.screenshot?.data) {
-        return {
-            label: 'Selected element screenshot',
-            meta: result.screenshot.meta,
-            data: result.screenshot.data,
-            extraLines: [
-                `  Element: ${result.tagName || 'unknown'}`,
-                `  Selector: ${result.selector || 'N/A'}`,
-            ],
-        };
+    else {
+        writeFileSync(outputPath, typeof result === 'string' ? result : `${JSON.stringify(result, null, 2)}\n`, 'utf8');
     }
-    return null;
+    console.error(`✓ Output saved to: ${outputPath}`);
 }
-async function main() {
-    // Handle built-in subcommands before normal arg parsing
-    if (process.argv[2] === 'check') {
-        await runCheck();
-        return;
+export async function runMearlCli(args, options = {}) {
+    const commandName = options.commandName ?? 'mearl';
+    const clientVersion = options.clientVersion ?? CLIENT_VERSION;
+    if (args.includes('--version') || args.includes('-v')) {
+        console.log(clientVersion);
+        return 0;
+    }
+    if (args.length === 0) {
+        printUsage(commandName, clientVersion);
+        return 1;
+    }
+    if (args.includes('--help') || args.includes('-h')) {
+        const command = COMMAND_MAP.get(args[0]);
+        if (command)
+            printCommandHelp(commandName, command);
+        else
+            printUsage(commandName, clientVersion);
+        return 0;
     }
-    let args;
+    let parsed;
     try {
-        args = parseArgs(process.argv.slice(2));
+        parsed = parseArgs(args);
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
-        printUsage();
-        process.exit(2);
+        return 2;
     }
-    if (args.showHelp) {
-        if (args.action) {
-            printCommandHelp(COMMAND_MAP.get(args.action));
+    if (parsed.action === 'check') {
+        const timeoutSec = parseCheckTimeout(optionValue(args, '--timeout'));
+        if (timeoutSec === null) {
+            console.error('--timeout 必须是正整数秒');
+            return 2;
         }
-        else {
-            printUsage();
-        }
-        return;
+        const ok = await runUnifiedCheck({
+            clientVersion,
+            timeoutSec,
+            ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
+            ...(parsed.serverUrlSource ? { serverUrlSource: parsed.serverUrlSource } : {}),
+            ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.connector ? { connector: parsed.connector } : {}),
+            ...(parsed.local ? { local: true } : {}),
+            ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
+        });
+        return ok ? 0 : 1;
     }
-    if (!COMMAND_MAP.has(args.action)) {
-        console.error(`不支持的 action: ${args.action}`);
-        console.error(`运行 mearl --help 查看所有可用命令`);
-        process.exit(2);
+    if (parsed.action !== 'connector_list' && !COMMAND_MAP.has(parsed.action)) {
+        console.error(`不支持的 action: ${parsed.action}`);
+        console.error(`运行 ${commandName} --help 查看所有可用命令`);
+        return 2;
     }
-    let data;
+    if (parsed.action === 'page_selected_element' && parsed.outputPath) {
+        parsed.payload = { ...parsed.payload, includeScreenshot: true };
+    }
+    const client = new UnifiedClient({
+        ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
+        requestTimeoutSec: parsed.timeoutSec,
+    });
     try {
-        if (args.payloadFile) {
-            if (!fs.existsSync(args.payloadFile)) {
-                throw new Error(`Payload file not found: ${args.payloadFile}`);
-            }
-            const fileContent = fs.readFileSync(args.payloadFile, 'utf-8');
-            data = JSON.parse(fileContent);
+        const result = await client.invoke(parsed.action, parsed.payload, {
+            timeoutSec: parsed.timeoutSec,
+            ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.connector ? { connector: parsed.connector } : {}),
+            ...(parsed.local ? { local: true } : {}),
+            ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
+        });
+        if (parsed.outputPath) {
+            writeOutput(parsed.action, result, parsed.outputPath);
         }
         else {
-            data = parsePayload(args.payloadRaw);
+            process.stdout.write(`${parsed.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2)}\n`);
         }
+        return 0;
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
-        process.exit(2);
-    }
-    try {
-        if (args.action === 'page_selected_element' && args.outputPath) {
-            data = { ...data, includeScreenshot: true };
-        }
-        const result = await invoke(args.action, data, {
-            timeoutSec: args.timeoutSec ?? resolveActionTimeoutSec(args.action, data),
-            transport: args.forceCdp ? 'cdp' : undefined,
-            browser: args.browser,
-        });
-        const screenshot = extractScreenshotResult(args.action, result);
-        if (screenshot) {
-            const sizeKB = Math.round(screenshot.meta.size / 1024);
-            if (args.outputPath) {
-                try {
-                    saveBase64Image(args.outputPath, screenshot.data);
-                    console.error(`✓ ${screenshot.label} saved to: ${args.outputPath}`);
-                }
-                catch (err) {
-                    console.error(`✗ Failed to save ${screenshot.label.toLowerCase()}: ${err instanceof Error ? err.message : String(err)}`);
-                    process.exit(1);
-                }
-            }
-            console.error(`✓ ${screenshot.label} captured`);
-            console.error(`  Format: ${screenshot.meta.format.toUpperCase()}`);
-            console.error(`  Size: ${screenshot.meta.width}x${screenshot.meta.height}`);
-            console.error(`  File size: ~${sizeKB}KB`);
-            screenshot.extraLines.forEach(line => console.error(line));
-            if (!args.outputPath) {
-                const output = args.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2);
-                process.stdout.write(output + '\n');
-            }
-            return;
-        }
-        const output = args.compact ? JSON.stringify(result) : JSON.stringify(result, null, 2);
-        process.stdout.write(output + '\n');
+        return 1;
     }
-    catch (error) {
-        console.error(error instanceof Error ? error.message : String(error));
-        process.exit(1);
+    finally {
+        client.disconnect();
     }
 }
-main();

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

@@ -118,10 +118,19 @@ export interface TdbankAccountParams {
     tabId?: number;
 }
 export type BrowserStatus = 'connected' | 'running_disconnected' | 'stopped';
+export interface BrowserSource {
+    kind: 'local' | 'remote';
+    connectorId?: string;
+    connectorName?: string;
+}
 export interface BrowserInfoBase {
     browserId: string;
     name: string;
     status: BrowserStatus;
+    /** Source-local values retained when the unified client returns a global browser id and label. */
+    originalBrowserId?: string;
+    originalName?: string;
+    source?: BrowserSource;
     extensionVersion?: string;
     nativeHostVersion?: string;
     transport?: 'extension' | 'cdp';
@@ -148,8 +157,6 @@ export interface ManagedBrowserInfo extends BrowserInfoBase {
     agentbayContextId?: string;
     /** Stable AgentBay browser context name derived from the managed browser name. */
     agentbayContextName?: string;
-    /** Browser-accessible AgentBay session URL when returned by the provider. */
-    agentbayAccessUrl?: string;
     createdAt: string;
     account?: ManagedBrowserAccount;
     copiedCookies?: {
@@ -163,6 +170,8 @@ export interface BrowserListResult {
     connectedCount: number;
     defaultBrowserId: string | null;
     browsers: BrowserInfo[];
+    /** Partial discovery failures; successfully inspected browser sources remain in the result. */
+    warnings?: string[];
 }
 export interface SelectBrowserParams {
     browser?: string;