@mearl/client 2.5.1 → 2.6.0

package/README.md

@@ -1,6 +1,6 @@
 # @mearl/client
 
-本地客户端 SDK 与 CLI，通过 **Unix Domain Socket** 与 Chrome 扩展的 native host 通信，调用浏览器调试与操作能力。
+统一浏览器 SDK 与 CLI。它会发现当前机器及已配置 cloud-server 下所有 connector 的浏览器，并根据 `browser_list` 返回的全局 `browserId` 自动选择本地 Socket 或云端 WebSocket 链路。
 
 提供两种用法：类型安全的具名方法（`getRequests`、`sendRequest` 等），以及灵活的底层 `invoke(action, payload)`。
 
@@ -27,6 +27,10 @@ const result = await client.sendRequest({
 
 // 底层通用方法（灵活扩展）
 const data = await client.invoke('send_request', { url: '...' });
+
+// browser_list 默认聚合本机和所有远端 connector
+const browsers = await client.browserList();
+await client.getLogs({}, { browser: browsers.browsers[0].browserId });
 ```
 
 ## CLI 使用
@@ -78,6 +82,9 @@ mearl browser_release
 | `--compact`             | 紧凑输出                 |
 | `--output <path>`       | 将结果写入文件（如截图） |
 | `--browser <id\|名称>`  | 指定目标浏览器           |
+| `--connector <id\|名称>` | 限制到一台远端机器       |
+| `--local`               | 只使用当前机器           |
+| `--server <url>`        | 覆盖 cloud-server 地址   |
 
 ## 支持的操作
 
@@ -105,19 +112,18 @@ mearl browser_release
 
 `browser_release` 仅在用户明确要求结束调试、退出接管或清理会话资源时使用，不作为普通任务收尾。它会释放当前目标浏览器的 debugger/CDP 控制和会话级临时状态（包括设备/时区模拟），保留浏览器及全部标签页；后续浏览器操作可自动重新建立控制。
 
-托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`persistent: true` 会让本地实例保留 Profile，让 AgentBay 同名实例绑定稳定的云端 Browser Context；正常关闭时同步 Cookie、LocalStorage、IndexedDB 等状态，下次启动无需再次复制本地登录态。`deleteProfile: true` 会显式删除对应 Profile 或 Context。`copyCookieDomains` 可在首次启动或需要刷新登录态时把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 通过 `agentbayImageId`、`agentbayContextId` 和 `agentbayContextName` 返回 AgentBay 实例配置；当服务返回无影浏览器串流入口时，还会通过 `agentbayAccessUrl` 暴露，该地址可能包含临时访问凭据，应按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
+托管浏览器使用独立 Profile。控制浏览器需先登录 TDBank；生成的 SSO 地址在本地内部传递，本地实例可以使用 `headless: true`（默认）完成测试账号登录。AgentBay 固定为非 headless，传 `headless: true` 会被拒绝；`imageId` 可指定镜像别名或具体镜像 ID，省略时使用已验证的 Linux Browser Use 内网镜像。`persistent: true` 会让本地实例保留 Profile，让 AgentBay 同名实例绑定稳定的云端 Browser Context；正常关闭时同步 Cookie、LocalStorage、IndexedDB 等状态，下次启动无需再次复制本地登录态。`deleteProfile: true` 会显式删除对应 Profile 或 Context。`copyCookieDomains` 可在首次启动或需要刷新登录态时把控制浏览器指定域的 Cookie 复制到新实例，Cookie 值不会经过 cloud-server，也不会出现在命令结果或日志中；`userAgentMode: "desktop"` 让本地实例使用匹配本机 Chrome 版本的桌面 UA，AgentBay 则复用当前控制浏览器的桌面 UA。`browser_list` 仅通过 `agentbayImageId`、`agentbayContextId` 和 `agentbayContextName` 返回 AgentBay 实例的稳定配置。无影浏览器串流入口包含临时访问凭据且会过期，因此不会写入实例记录或列表结果；需要时运行 `mearl check --browser <id|名称>` 实时获取，并按敏感信息处理。完整设计见 [托管浏览器与 TDBank 多账号设计](../../docs/managed-browsers.md)。
 
 ## 架构
 
 ```
 @mearl/client (CLI / SDK)
-  ↓ (Unix Socket)
-@mearl/native-host
-  ↓ (Native Messaging)
-Chrome Extension / CDP
+  ├─ 本机 → @mearl/native-host → Chrome Extension / CDP
+  └─ WebSocket → @mearl/cloud-server → @mearl/cloud-connector
+                                      → @mearl/native-host → Chrome Extension / CDP
 ```
 
-> 云端远程调用场景请使用 [@mearl/cloud-client](../cloud/cloud-client)，其操作集与本包完全一致。
+基础设施组件必须避免递归路由：`@mearl/cloud-connector` 使用 `@mearl/client/local` 子路径直连所在机器的 native-host。普通 Agent、CLI 与 MCP 集成均使用包根入口。
 
 ## 构建
 

package/dist/check.d.ts

@@ -1 +1,22 @@
-export declare function runCheck(): Promise<void>;
+import { type UnifiedClientOptions, type UnifiedInvokeOptions } from './unified.js';
+interface CheckClient {
+    invoke(action: string, data?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+    disconnect(): void;
+}
+export interface UnifiedCheckOptions {
+    clientVersion: string;
+    serverUrl?: string;
+    serverUrlSource?: string;
+    timeoutSec?: number;
+    browser?: string;
+    connector?: string;
+    local?: boolean;
+    transport?: 'cdp';
+}
+export interface UnifiedCheckDependencies {
+    createClient?: (options: UnifiedClientOptions) => CheckClient;
+    writeLine?: (line: string) => void;
+}
+export declare function parseCheckTimeout(value: string | undefined): number | null;
+export declare function runUnifiedCheck(options: UnifiedCheckOptions, dependencies?: UnifiedCheckDependencies): Promise<boolean>;
+export {};

package/dist/check.js

@@ -1,146 +1,288 @@
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { execSync } from 'node:child_process';
-import { invoke, CLIENT_VERSION, SOCKET_PATH } from './socket.js';
-import { listLiveBrowsers, describeBrowser } from './browserRegistry.js';
-const EXTENSION_INSTALL_URL = 'https://chromewebstore.google.com/detail/mearl/aoehhjnofngknnjefamjbplchbolghkm';
-function resolveManifestDir() {
-    switch (process.platform) {
-        case 'darwin':
-            return path.join(os.homedir(), 'Library/Application Support/Google/Chrome/NativeMessagingHosts');
-        case 'linux':
-            return path.join(os.homedir(), '.config/google-chrome/NativeMessagingHosts');
-        case 'win32':
-            return path.join(process.env.PROGRAMDATA || 'C:\\ProgramData', 'Google\\Chrome\\NativeMessagingHosts');
-        default:
-            return '';
-    }
+import { UnifiedClient } from './unified.js';
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
 }
-function checkCommandExists(command) {
+function redactServerUrl(serverUrl) {
     try {
-        return execSync(`${command} --version`, { encoding: 'utf-8', timeout: 5000 }).trim();
+        const parsed = new URL(serverUrl);
+        for (const key of parsed.searchParams.keys()) {
+            if (key.toLowerCase().includes('token'))
+                parsed.searchParams.set(key, 'redacted');
+        }
+        return parsed.toString();
     }
     catch {
-        return null;
+        return serverUrl.replace(/([?&][^=&\s]*token[^=&\s]*=)[^&\s]*/gi, '$1redacted');
     }
 }
-export async function runCheck() {
-    const env = [];
-    // 1. native-host CLI on PATH
-    const cliVersion = checkCommandExists('mearl-native-host');
-    env.push(cliVersion
-        ? { ok: true, label: 'native-host CLI' }
-        : {
-            ok: false,
-            label: 'native-host CLI not found',
-            fix: ['npm install -g @mearl/native-host'],
-        });
-    // 2. Native Messaging manifest
-    const manifestDir = resolveManifestDir();
-    const manifestName = 'com.alibaba.mearl.skills.json';
-    const manifestPath = manifestDir ? path.join(manifestDir, manifestName) : '';
-    env.push(manifestPath && fs.existsSync(manifestPath)
-        ? { ok: true, label: 'Native Messaging manifest' }
-        : {
-            ok: false,
-            label: 'Native Messaging manifest not found',
-            fix: ['mearl-native-host --init'],
-        });
-    // 3. Socket file (Windows uses Named Pipes — assume present, probe via invoke)
-    const isWindows = process.platform === 'win32';
-    const socketExists = isWindows || fs.existsSync(SOCKET_PATH);
-    if (isWindows) {
-        env.push({ ok: true, label: `Socket (Named Pipe)` });
-    }
-    else if (socketExists) {
-        env.push({ ok: true, label: 'Socket file' });
-    }
-    else {
-        env.push({
-            ok: false,
-            label: `Socket file not found at ${SOCKET_PATH}`,
-            fix: [
-                'native host is not running',
-                'Extension mode: ensure Chrome is running and the extension is enabled',
-                'CDP mode: chrome://inspect/#remote-debugging → "Discover network targets"',
-            ],
-        });
+function browserMatches(browser, selector) {
+    const normalized = selector.trim().toLowerCase();
+    return (browser.browserId.toLowerCase() === normalized ||
+        browser.originalBrowserId?.toLowerCase() === normalized ||
+        browser.name.toLowerCase() === normalized ||
+        browser.originalName?.toLowerCase() === normalized);
+}
+function findBrowsers(browsers, selector) {
+    const exact = browsers.filter(browser => browserMatches(browser, selector));
+    if (exact.length > 0)
+        return exact;
+    const normalized = selector.trim().toLowerCase();
+    return browsers.filter(browser => browser.browserId.toLowerCase().includes(normalized) ||
+        browser.originalBrowserId?.toLowerCase().includes(normalized) ||
+        browser.name.toLowerCase().includes(normalized) ||
+        browser.originalName?.toLowerCase().includes(normalized));
+}
+function shortBrowserId(browserId) {
+    const parts = browserId.split(':');
+    const raw = decodeURIComponent(parts.at(-1) ?? browserId);
+    return raw.length > 12 ? `${raw.slice(0, 8)}…` : raw;
+}
+function formatBrowser(browser, isDefault) {
+    const transport = browser.transport === 'cdp'
+        ? ' [CDP]'
+        : browser.transport === 'extension'
+            ? ' [Extension]'
+            : '';
+    const type = browser.type === 'managed' ? ' [Managed]' : '';
+    return `  ${isDefault ? '★' : ' '} ${browser.name} [${shortBrowserId(browser.browserId)}]${type}${transport}`;
+}
+function formatConnector(connector) {
+    const id = connector.connectorId.length > 12
+        ? `${connector.connectorId.slice(0, 8)}…`
+        : connector.connectorId;
+    const version = connector.version ? ` [v${connector.version}]` : '';
+    return `    ${connector.name} [${id}]${version}`;
+}
+function printSection(writeLine, title, items) {
+    writeLine(title);
+    for (const item of items) {
+        const marker = item.status === 'ok' ? '✅' : item.status === 'warning' ? '⚠️ ' : '❌';
+        writeLine(`  ${marker} ${item.label}`);
+        for (const detail of item.details ?? [])
+            writeLine(`     ${detail}`);
     }
-    // 4. Connection + version fetch
-    let runtime = null;
-    let outdatedDaemon = false;
-    if (socketExists) {
+    writeLine('');
+}
+export function parseCheckTimeout(value) {
+    const input = value ?? '5';
+    if (!/^[1-9]\d*$/.test(input))
+        return null;
+    const timeoutSec = Number(input);
+    return Number.isSafeInteger(timeoutSec) ? timeoutSec : null;
+}
+export async function runUnifiedCheck(options, dependencies = {}) {
+    const timeoutSec = options.timeoutSec ?? 5;
+    const writeLine = dependencies.writeLine ?? (line => console.error(line));
+    const createClient = dependencies.createClient ??
+        ((clientOptions) => new UnifiedClient(clientOptions));
+    const client = createClient({
+        ...(options.serverUrl ? { serverUrl: options.serverUrl } : {}),
+        connectTimeoutSec: timeoutSec,
+        requestTimeoutSec: timeoutSec,
+    });
+    const environment = [
+        { status: 'ok', label: `Unified client v${options.clientVersion}` },
+    ];
+    let connectors = [];
+    let browserList = null;
+    try {
+        if (options.local) {
+            environment.push({
+                status: 'ok',
+                label: options.transport === 'cdp'
+                    ? 'Browser scope: this machine (forced CDP)'
+                    : 'Browser scope: this machine',
+            });
+        }
+        else if (options.serverUrl) {
+            const source = options.serverUrlSource ? ` (${options.serverUrlSource})` : '';
+            try {
+                const connectorList = (await client.invoke('connector_list', {}, { timeoutSec }));
+                connectors = Array.isArray(connectorList?.connectors) ? connectorList.connectors : [];
+                environment.push({
+                    status: 'ok',
+                    label: `Cloud server${source}`,
+                    details: [
+                        redactServerUrl(options.serverUrl),
+                        `${connectors.length} connector${connectors.length === 1 ? '' : 's'} connected`,
+                    ],
+                });
+            }
+            catch (error) {
+                environment.push({
+                    status: 'error',
+                    label: `Cloud server or connector discovery failed${source}`,
+                    details: [formatError(error), redactServerUrl(options.serverUrl)],
+                });
+            }
+        }
+        else {
+            environment.push({ status: 'ok', label: 'Local mode (no cloud-server configuration)' });
+        }
+        const inventoryOptions = {
+            timeoutSec,
+            ...(options.local ? { local: true } : {}),
+            ...(options.transport ? { transport: options.transport } : {}),
+            ...(!options.local && options.connector ? { connector: options.connector } : {}),
+        };
         try {
-            runtime = (await invoke('get_versions', {}, { timeoutSec: 5 }));
-            env.push({ ok: true, label: 'Connection' });
+            if (options.serverUrl &&
+                !options.local &&
+                environment.some(item => item.status === 'error')) {
+                browserList = (await client.invoke('browser_list', {}, {
+                    timeoutSec,
+                    local: true,
+                }));
+            }
+            else {
+                browserList = (await client.invoke('browser_list', {}, inventoryOptions));
+            }
+            environment.push({ status: 'ok', label: 'Browser inventory' });
+            if (browserList.warnings?.length) {
+                environment.push({
+                    status: 'warning',
+                    label: 'Some browser sources could not be inspected',
+                    details: browserList.warnings,
+                });
+            }
         }
         catch (error) {
-            const msg = error instanceof Error ? error.message : String(error);
-            if (msg.includes('Unknown action')) {
-                // Old native-host responded but doesn't know get_versions — connection itself is fine.
-                outdatedDaemon = true;
-                env.push({ ok: true, label: 'Connection' });
+            environment.push({
+                status: 'error',
+                label: 'Browser inventory failed',
+                details: [formatError(error)],
+            });
+        }
+        const connected = (browserList?.browsers ?? []).filter(browser => browser.status === 'connected');
+        let targets = connected;
+        if (options.browser) {
+            const matches = findBrowsers(connected, options.browser);
+            if (matches.length === 0) {
+                environment.push({
+                    status: 'error',
+                    label: `Browser "${options.browser}" is not connected`,
+                    details: ['Run `mearl browser_list` and use an exact global browserId.'],
+                });
+                targets = [];
+            }
+            else if (matches.length > 1) {
+                environment.push({
+                    status: 'error',
+                    label: `Browser selector "${options.browser}" is ambiguous`,
+                    details: matches.map(browser => browser.browserId),
+                });
+                targets = [];
             }
             else {
-                env.push({ ok: false, label: 'Connection failed', fix: [msg] });
+                targets = matches;
             }
         }
-    }
-    // Build versions list
-    const versions = [['client', `v${CLIENT_VERSION}`]];
-    const nhVersion = runtime?.nativeHost ?? cliVersion;
-    if (nhVersion)
-        versions.push(['native-host', `v${nhVersion}`]);
-    if (runtime?.extension) {
-        versions.push(['extension', `v${runtime.extension}`]);
-    }
-    if (runtime?.browser) {
-        versions.push(['browser', `Chrome ${runtime.browser}`]);
-    }
-    // Print Versions section
-    const nameWidth = Math.max(...versions.map(([n]) => n.length));
-    console.error('\nVersions');
-    for (const [name, value] of versions) {
-        console.error(`  ${name.padEnd(nameWidth)}  ${value}`);
-    }
-    console.error('');
-    // Print Environment section
-    console.error('Environment');
-    let hasError = false;
-    for (const e of env) {
-        console.error(`  ${e.ok ? '✅' : '❌'} ${e.label}`);
-        if (!e.ok) {
-            hasError = true;
-            for (const fix of e.fix ?? [])
-                console.error(`     ${fix}`);
+        if (!options.browser && connected.length === 0 && browserList) {
+            environment.push({
+                status: 'error',
+                label: 'No connected browser',
+                details: [
+                    'Open Chrome with the Mearl extension, start a managed browser, or connect a browser host.',
+                ],
+            });
         }
-    }
-    if (outdatedDaemon) {
-        console.error('  ⚠️  native-host daemon is outdated (missing get_versions). Restart Chrome or re-init: mearl-native-host --init');
-    }
-    console.error('');
-    // Connected browsers (multi-browser addressing)
-    const browsers = listLiveBrowsers();
-    if (browsers.length > 0) {
-        console.error('Connected browsers');
-        browsers.forEach((b, i) => {
-            const marker = i === 0 ? '★' : ' ';
-            const via = b.transport === 'cdp' ? ' [CDP]' : '';
-            console.error(`  ${marker} ${describeBrowser(b)}${via}`);
-        });
-        if (browsers.length > 1) {
-            console.error('  ★ = default target (most-recently focused). Use --browser to pick another.');
+        const browserChecks = [];
+        await Promise.all(targets.map(async (browser) => {
+            try {
+                const versions = (await client.invoke('get_versions', {}, {
+                    timeoutSec,
+                    browser: browser.browserId,
+                    ...(options.transport ? { transport: options.transport } : {}),
+                }));
+                const details = [
+                    versions.nativeHost ? `native-host v${versions.nativeHost}` : null,
+                    versions.extension ? `extension v${versions.extension}` : null,
+                    versions.browser ? `Chrome ${versions.browser}` : null,
+                ].filter((value) => value !== null);
+                let accessUrlWarning;
+                if (browser.provider === 'agentbay' && options.browser) {
+                    try {
+                        const access = (await client.invoke('get_agentbay_access_url', {}, {
+                            timeoutSec,
+                            browser: browser.browserId,
+                        }));
+                        if (!access.agentbayAccessUrl) {
+                            throw new Error('AgentBay did not return a browser access URL');
+                        }
+                        details.push(`AgentBay access URL (temporary, sensitive): ${access.agentbayAccessUrl}`);
+                    }
+                    catch (error) {
+                        accessUrlWarning = formatError(error);
+                        details.push(`AgentBay access URL unavailable: ${accessUrlWarning}`);
+                    }
+                }
+                browserChecks.push({
+                    browser,
+                    item: {
+                        status: accessUrlWarning ? 'warning' : 'ok',
+                        label: accessUrlWarning
+                            ? 'Browser command path ready; AgentBay access URL unavailable'
+                            : 'Browser command path',
+                        details,
+                    },
+                });
+            }
+            catch (error) {
+                const message = formatError(error);
+                browserChecks.push({
+                    browser,
+                    item: message.includes('Unknown action')
+                        ? {
+                            status: 'warning',
+                            label: 'Browser is reachable but runtime version details are unavailable',
+                            details: ['Update @mearl/native-host for complete diagnostics.'],
+                        }
+                        : {
+                            status: 'error',
+                            label: 'Browser command path failed',
+                            details: [message],
+                        },
+                });
+            }
+        }));
+        writeLine('');
+        printSection(writeLine, 'Environment', environment);
+        if (connectors.length > 0) {
+            writeLine('Cloud connectors');
+            for (const connector of connectors)
+                writeLine(formatConnector(connector));
+            writeLine('');
         }
-        console.error('');
-    }
-    // Summary
-    if (hasError) {
-        console.error('⚠️  Some checks failed. See above for fix instructions.');
-        console.error(`   Install extension: ${EXTENSION_INSTALL_URL}`);
-        process.exit(1);
+        const listedBrowsers = browserList?.browsers ?? [];
+        if (listedBrowsers.length > 0) {
+            writeLine('Browsers');
+            for (const browser of listedBrowsers) {
+                writeLine(formatBrowser(browser, browser.browserId === browserList?.defaultBrowserId));
+                const check = browserChecks.find(item => item.browser.browserId === browser.browserId);
+                if (check) {
+                    const marker = check.item.status === 'ok' ? '✅' : check.item.status === 'warning' ? '⚠️ ' : '❌';
+                    writeLine(`      ${marker} ${check.item.label}`);
+                    for (const detail of check.item.details ?? [])
+                        writeLine(`         ${detail}`);
+                }
+                else if (browser.status !== 'connected') {
+                    writeLine(`      ⚪ ${browser.status}`);
+                }
+            }
+            writeLine('');
+        }
+        const hasError = environment.some(item => item.status === 'error') ||
+            browserChecks.some(check => check.item.status === 'error');
+        if (hasError) {
+            writeLine('⚠️  Mearl checks failed. See the browser or source details above.');
+            return false;
+        }
+        writeLine(options.browser
+            ? '🎉 Selected browser is ready!'
+            : `🎉 All ${targets.length} connected browser${targets.length === 1 ? '' : 's'} are ready!`);
+        return true;
     }
-    else {
-        console.error('🎉 All checks passed!');
+    finally {
+        client.disconnect();
     }
 }

package/dist/cli.d.ts

@@ -1,14 +1,6 @@
 #!/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
- */
-export {};
+export interface MearlCliOptions {
+    commandName?: string;
+    clientVersion?: string;
+}
+export declare function runMearlCli(args: string[], options?: MearlCliOptions): Promise<number>;