@mearl/client 2.19.2 → 2.19.3

package/dist/plugin.js

@@ -1,11 +1,12 @@
-import { readFileSync, statSync } from 'node:fs';
+import { readFileSync } from 'node:fs';
 import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command } from 'commander';
 import { COMMAND_MAP } from './commands.js';
 import { findOfficialPlugin } from './officialPluginCatalog.js';
 import { ensureOfficialPluginRegistered, } from './officialPluginInstaller.js';
-import { findPluginRegistration, normalizePluginToolboxContribution, PluginError, } from './pluginRegistry.js';
+import { findPluginRegistration, pluginRegistrationNeedsRefresh, registerPlugin, pluginDirectory, normalizePluginToolboxContribution, PluginError, } from './pluginRegistry.js';
+import { pluginFileVersion } from './pluginSource.js';
 import { describePythonPlugin, runPythonPluginCommand } from './pythonPlugin.js';
 export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, } from './pluginRegistry.js';
 export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, } from './officialPluginCatalog.js';
@@ -67,14 +68,61 @@ function missingPluginEntryMessage(entry, pluginName) {
         `卸载命令：npx @mearl/setup plugin uninstall ${name}`,
     ].join('\n');
 }
+const registrationRefreshes = new Map();
+/** 工具列表仅检查入口；页面资源只在打开对应工具时检查。 */
+export async function refreshRegisteredPlugin(name, includePage = false) {
+    const key = `${pluginDirectory()}/${name}`;
+    const pending = registrationRefreshes.get(key);
+    if (pending) {
+        await pending;
+        return refreshRegisteredPlugin(name, includePage);
+    }
+    const registration = findPluginRegistration(name);
+    if (!registration)
+        return undefined;
+    const entryChanged = pluginRegistrationNeedsRefresh(registration);
+    if (!entryChanged && (!includePage || !pluginRegistrationNeedsRefresh(registration, true))) {
+        return registration;
+    }
+    const refresh = (async () => {
+        const entryVersion = pluginFileVersion(registration.entry);
+        const loaded = entryChanged
+            ? await loadPlugin(registration.entry, {
+                options: {},
+                invoke: async () => {
+                    throw new Error('注册时不能执行浏览器操作');
+                },
+                progress: () => {
+                    throw new Error('注册时不能报告执行进度');
+                },
+            }, name)
+            : registration;
+        // 异步加载期间其他进程可能卸载或重新绑定同名插件。
+        const current = findPluginRegistration(name);
+        if (JSON.stringify(current) !== JSON.stringify(registration))
+            return current;
+        if (pluginFileVersion(registration.entry) !== entryVersion) {
+            throw new PluginError('PLUGIN_SOURCE_CHANGED', `插件更新进行中，请重新打开工具: ${name}`);
+        }
+        registerPlugin(name, registration.entry, loaded.description, {
+            toolbox: loaded.toolbox,
+            ...(registration.managedBy ? { managedBy: registration.managedBy } : {}),
+        });
+        return findPluginRegistration(name);
+    })();
+    registrationRefreshes.set(key, refresh);
+    try {
+        return await refresh;
+    }
+    finally {
+        registrationRefreshes.delete(key);
+    }
+}
 /** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
 export async function loadPlugin(entry, context, pluginName) {
     let entryVersion;
     try {
-        const stat = statSync(entry);
-        if (!stat.isFile())
-            throw new Error('not a file');
-        entryVersion = `${stat.mtimeMs}-${stat.size}`;
+        entryVersion = pluginFileVersion(entry);
     }
     catch {
         throw new PluginError('PLUGIN_ENTRY_MISSING', missingPluginEntryMessage(entry, pluginName));
@@ -87,11 +135,15 @@ export async function loadPlugin(entry, context, pluginName) {
     let toolbox;
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
-        command(signature, handler, description = '') {
+        command(signature, handler, description = '', examples = []) {
             if (!registering)
                 throw new Error('命令只能在入口注册阶段声明');
             const [name, ...args] = signature.trim().split(/\s+/);
-            if (!/^[a-z][a-z0-9-]*$/.test(name) || commands.has(name) || typeof handler !== 'function') {
+            if (!/^[a-z][a-z0-9-]*$/.test(name) ||
+                commands.has(name) ||
+                typeof handler !== 'function' ||
+                !Array.isArray(examples) ||
+                examples.some((example) => typeof example !== 'string' || !example.trim())) {
                 throw new Error(`无效或重复的命令: ${signature}`);
             }
             const command = new Command(name).description(description);
@@ -104,7 +156,7 @@ export async function loadPlugin(entry, context, pluginName) {
             const names = command.registeredArguments.map(argument => argument.name());
             if (new Set(names).size !== names.length)
                 throw new Error(`参数名称重复: ${signature}`);
-            commands.set(name, { command, signature, handler });
+            commands.set(name, { command, signature, handler, examples: [...examples] });
         },
         invoke(action, payload = {}, options = {}) {
             if (!executing)
@@ -175,20 +227,13 @@ export async function loadPlugin(entry, context, pluginName) {
         },
         help(namespace, name) {
             const selected = name ? [find(name)] : [...commands.values()];
-            const example = selected[0].command;
-            const input = Object.fromEntries(example.registeredArguments.map(argument => [
-                argument.name(),
-                argument.variadic ? [`<${argument.name()}>`] : `<${argument.name()}>`,
-            ]));
+            const examples = selected.flatMap(({ examples }) => examples);
             return [
+                '用法：',
                 ...selected.map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`),
-                '',
-                `  ${namespace} --payload '${JSON.stringify({ command: example.name(), input })}'`,
-                '',
-                '常用选项: --browser --timeout --compact --output',
-                '连接或传输排障运行 mearl check --help。',
-                '插件选项: --name=value 传入字符串业务字段；--all 传入 all=true；--verbose; -h, --help; -v, --version',
-                '同名宿主选项及非字符串字段使用 --payload；业务字段与校验规则见对应 skill。',
+                ...(examples.length
+                    ? ['', '示例：', ...examples.map(example => `  ${namespace} ${example}`)]
+                    : []),
             ].join('\n');
         },
         async run(positionals, payload, namedInput = {}) {

package/dist/pluginPageBundle.d.ts

@@ -4,5 +4,6 @@ export interface BuiltPluginPageBundle {
     hash: string;
     size: number;
     chunks: number;
+    sources: Record<string, string>;
 }
 export declare function buildPluginPageBundle(entry: string, pageEntry: string): BuiltPluginPageBundle;

package/dist/pluginPageBundle.js

@@ -1,6 +1,7 @@
 import { createHash } from 'node:crypto';
 import { readFileSync, realpathSync } from 'node:fs';
 import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { pluginFileVersion } from './pluginSource.js';
 export const PLUGIN_PAGE_CHUNK_BYTES = 384 * 1024;
 const MAX_PAGE_SOURCE_BYTES = 16 * 1024 * 1024;
 const MAX_PAGE_BUNDLE_BYTES = 24 * 1024 * 1024;
@@ -578,6 +579,7 @@ export function buildPluginPageBundle(entry, pageEntry) {
     const root = realpathSync(pluginRoot(entry));
     let sourceBytes = 0;
     const countedFiles = new Set();
+    const sources = {};
     const resolveLocalFile = (reference, fromFile) => {
         const cleanReference = reference.trim().split(/[?#]/, 1)[0];
         if (!cleanReference || isEmbeddedReference(cleanReference))
@@ -585,14 +587,17 @@ export function buildPluginPageBundle(entry, pageEntry) {
         if (isRemoteReference(cleanReference) || isAbsolute(cleanReference)) {
             throw new Error(`toolbox.page 不允许远程或绝对资源: ${reference}`);
         }
-        const resolved = realpathSync(resolve(dirname(fromFile), cleanReference));
+        const sourcePath = resolve(dirname(fromFile), cleanReference);
+        const resolved = realpathSync(sourcePath);
         const relativePath = relative(root, resolved);
         if (relativePath === '..' || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
             throw new Error(`toolbox.page 资源超出插件目录: ${reference}`);
         }
+        sources[sourcePath] = pluginFileVersion(sourcePath);
         return resolved;
     };
     const readAsset = (path) => {
+        sources[path] ??= pluginFileVersion(path);
         const content = readFileSync(path);
         if (!countedFiles.has(path)) {
             countedFiles.add(path);
@@ -676,5 +681,6 @@ export function buildPluginPageBundle(entry, pageEntry) {
         hash: createHash('sha256').update(buffer).digest('hex'),
         size: buffer.byteLength,
         chunks: Math.ceil(buffer.byteLength / PLUGIN_PAGE_CHUNK_BYTES),
+        sources,
     };
 }

package/dist/pluginRegistry.d.ts

@@ -37,7 +37,12 @@ export interface PluginRegistration {
     managedBy?: string;
     toolbox?: PluginToolboxContribution;
     pageBundle?: PluginPageBundleRegistration;
+    source?: {
+        entry: string;
+        page?: Record<string, string>;
+    };
 }
+export declare function pluginRegistrationNeedsRefresh(registration: PluginRegistration, includePage?: boolean): boolean;
 export interface PluginRegistrationOptions {
     managedBy?: string;
     toolbox?: PluginToolboxContribution;

package/dist/pluginRegistry.js

@@ -4,6 +4,7 @@ import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { COMMAND_MAP } from './commands.js';
 import { buildPluginPageBundle, PLUGIN_PAGE_CHUNK_BYTES, } from './pluginPageBundle.js';
+import { pluginFileVersion } from './pluginSource.js';
 const RESERVED_NAMES = new Set([
     'check',
     'help',
@@ -19,6 +20,17 @@ export class PluginError extends Error {
         this.code = code;
     }
 }
+export function pluginRegistrationNeedsRefresh(registration, includePage = false) {
+    if (!registration.source)
+        return true;
+    if (pluginFileVersion(registration.entry) !== registration.source.entry)
+        return true;
+    if (!includePage || !registration.toolbox)
+        return false;
+    if (!registration.source.page)
+        return true;
+    return Object.entries(registration.source.page).some(([path, version]) => pluginFileVersion(path) !== version);
+}
 export function pluginDirectory() {
     return resolve(process.env.MEARL_PLUGIN_DIR || join(homedir(), '.mearl', 'plugins'));
 }
@@ -242,6 +254,7 @@ export function resolvePluginEntry(target) {
 export function registerPlugin(name, target, description, options = {}) {
     assertPluginName(name);
     const entry = resolvePluginEntry(target);
+    const entryVersion = pluginFileVersion(entry);
     const directory = pluginDirectory();
     mkdirSync(directory, { recursive: true, mode: 0o700 });
     const file = join(directory, `${name}.json`);
@@ -268,6 +281,7 @@ export function registerPlugin(name, target, description, options = {}) {
     }
     const record = {
         entry,
+        source: { entry: entryVersion, ...(builtPage ? { page: builtPage.sources } : {}) },
         ...(summary ? { description: summary } : {}),
         ...(managedBy ? { managedBy } : {}),
         ...(toolbox ? { toolbox } : {}),
@@ -324,12 +338,26 @@ export function findPluginRegistration(name) {
             : undefined;
         const toolbox = normalizePluginToolboxContribution(record.toolbox);
         const pageBundle = toolbox ? normalizePageBundle(record.pageBundle) : undefined;
+        const source = record.source;
+        if (source !== undefined &&
+            (!source ||
+                typeof source !== 'object' ||
+                Array.isArray(source) ||
+                typeof source.entry !== 'string' ||
+                (source.page !== undefined &&
+                    (!source.page ||
+                        typeof source.page !== 'object' ||
+                        Array.isArray(source.page) ||
+                        Object.entries(source.page).some(([path, version]) => !isAbsolute(path) || typeof version !== 'string'))))) {
+            throw new Error('invalid source');
+        }
         return {
             entry: record.entry,
             ...(description ? { description } : {}),
             ...(managedBy ? { managedBy } : {}),
             ...(toolbox ? { toolbox } : {}),
             ...(pageBundle ? { pageBundle } : {}),
+            ...(source ? { source } : {}),
         };
     }
     catch {

package/dist/pluginSource.d.ts

@@ -0,0 +1,2 @@
+/** 文件替换和同大小写入都需要使缓存失效；检测只读取文件元数据。 */
+export declare function pluginFileVersion(path: string): string;

package/dist/pluginSource.js

@@ -0,0 +1,8 @@
+import { statSync } from 'node:fs';
+/** 文件替换和同大小写入都需要使缓存失效；检测只读取文件元数据。 */
+export function pluginFileVersion(path) {
+    const stat = statSync(path);
+    if (!stat.isFile())
+        throw new Error(`插件资源不是文件: ${path}`);
+    return `${stat.dev}-${stat.ino}-${stat.mtimeMs}-${stat.ctimeMs}-${stat.size}`;
+}

package/dist/socket.js

@@ -96,12 +96,38 @@ function browserListFromProviderRecords(browsers) {
         browsers: providerBrowsers,
     };
 }
+function withDiscoveryWarning(result, error) {
+    const cause = error.cause ?? error;
+    const code = cause?.code;
+    const detail = code ?? (error instanceof Error ? error.message.split('\n')[0] : String(error));
+    return {
+        ...result,
+        warnings: [
+            ...(Array.isArray(result.warnings) ? result.warnings : []),
+            `Local CDP discovery could not complete: ${detail}`,
+        ],
+    };
+}
+function cdpOnlyBrowserList(result) {
+    const browsers = Array.isArray(result.browsers) ? result.browsers : [];
+    const cdpBrowsers = browsers.filter(browser => browser.transport === 'cdp');
+    return {
+        ...result,
+        count: cdpBrowsers.length,
+        connectedCount: cdpBrowsers.filter(browser => browser.status === 'connected').length,
+        browsers: cdpBrowsers,
+    };
+}
 function areInstalledProvidersRunning() {
     return listInstalledProviders().every(provider => readLiveProvider(provider.providerId));
 }
 function isConnectedBrowser(browser) {
     return browser.status === undefined || browser.status === 'connected';
 }
+function isOrdinaryLocalBrowser(browser) {
+    return (!browser.browserId.startsWith('managed:') &&
+        (browser.transport === 'extension' || browser.transport === 'cdp'));
+}
 function supportsAction(browser, action, data) {
     if (action === 'get_versions')
         return true;
@@ -141,47 +167,62 @@ function selectBrowserResult(data) {
 }
 /** Deduplicates concurrent recovery attempts in long-lived clients such as the MCP server. */
 let persistentSpawnPromise = null;
+let discoveryListPromise = null;
+let discoveryListCache = null;
+const DISCOVERY_STARTUP_TIMEOUT_MS = 3_000;
+const DISCOVERY_RETRY_INTERVAL_MS = 50;
+const DISCOVERY_MISS_CACHE_MS = 2_000;
+function instanceSocketPath(pid) {
+    return process.platform === 'win32'
+        ? `\\\\.\\pipe\\mearl-agent-${pid}`
+        : path.join(os.tmpdir(), `mearl-agent-${pid}.sock`);
+}
+function discoveryCacheKey() {
+    const browsers = listLiveBrowsers()
+        .map(browser => [
+        browser.browserId,
+        browser.pid,
+        browser.socketPath,
+        browser.status,
+        browser.updatedAt,
+    ])
+        .sort((a, b) => String(a[0]).localeCompare(String(b[0])));
+    const providers = listInstalledProviders()
+        .map(provider => provider.providerId)
+        .sort();
+    return JSON.stringify({ browsers, providers });
+}
+async function spawnNativeHost(args) {
+    const { spawn } = await import('node:child_process');
+    return new Promise((resolve, reject) => {
+        const child = spawn('mearl-native-host', args, {
+            detached: true,
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        child.once('error', reject);
+        child.once('spawn', () => {
+            child.unref();
+            resolve(child.pid);
+        });
+    });
+}
 /**
  * Attempt to spawn `mearl-native-host` in the background (detached).
- * Browser discovery hosts probe the default local CDP endpoint for browser_list and only
- * persist when a real browser is available.
  * Returns true if a spawn was attempted (regardless of success).
  */
-async function trySpawnNativeHost(mode = 'control') {
-    const persistent = mode === 'control';
-    if (persistent && persistentSpawnPromise)
+async function trySpawnNativeHost() {
+    if (persistentSpawnPromise)
         return persistentSpawnPromise;
     const spawnPromise = (async () => {
         try {
-            const { spawn } = await import('node:child_process');
-            return await new Promise(resolve => {
-                const args = persistent ? ['--daemon'] : ['--daemon', '--discover-cdp'];
-                const child = spawn('mearl-native-host', args, {
-                    detached: true,
-                    stdio: 'ignore',
-                    windowsHide: true,
-                });
-                let settled = false;
-                const finish = (ok) => {
-                    if (settled)
-                        return;
-                    settled = true;
-                    resolve(ok);
-                };
-                // `spawn ENOENT` 等错误会通过事件异步抛出；必须显式监听避免进程崩溃。
-                child.once('error', () => finish(false));
-                child.once('spawn', () => {
-                    child.unref();
-                    finish(true);
-                });
-            });
+            await spawnNativeHost(['--daemon']);
+            return true;
         }
         catch {
             return false;
         }
     })();
-    if (!persistent)
-        return spawnPromise;
     persistentSpawnPromise = spawnPromise;
     try {
         return await spawnPromise;
@@ -191,6 +232,54 @@ async function trySpawnNativeHost(mode = 'control') {
             persistentSpawnPromise = null;
     }
 }
+async function discoverLocalBrowserList(timeoutSec, controlSource) {
+    if (discoveryListPromise)
+        return discoveryListPromise;
+    const cacheKey = discoveryCacheKey();
+    if (discoveryListCache &&
+        discoveryListCache.key === cacheKey &&
+        Date.now() < discoveryListCache.until) {
+        if (discoveryListCache.error)
+            throw discoveryListCache.error;
+        return discoveryListCache.result;
+    }
+    discoveryListCache = null;
+    const request = (async () => {
+        const pid = await spawnNativeHost(['--daemon', '--discover-cdp']);
+        if (pid === undefined)
+            throw new Error('Native host did not report its process id');
+        const socketPath = instanceSocketPath(pid);
+        const deadline = Date.now() + Math.min(timeoutSec * 1_000, DISCOVERY_STARTUP_TIMEOUT_MS);
+        while (true) {
+            try {
+                return await invokeOnce('browser_list', {}, timeoutSec, undefined, socketPath, controlSource);
+            }
+            catch (error) {
+                if (!isConnError(error) || Date.now() >= deadline)
+                    throw error;
+                await new Promise(resolve => setTimeout(resolve, DISCOVERY_RETRY_INTERVAL_MS));
+            }
+        }
+    })();
+    discoveryListPromise = request;
+    try {
+        const result = await request;
+        if (!result.browsers?.some((browser) => browser.transport === 'cdp' &&
+            browser.status === 'connected' &&
+            !browser.browserId?.startsWith('managed:'))) {
+            discoveryListCache = { key: cacheKey, result, until: Date.now() + DISCOVERY_MISS_CACHE_MS };
+        }
+        return result;
+    }
+    catch (error) {
+        discoveryListCache = { key: cacheKey, error, until: Date.now() + DISCOVERY_MISS_CACHE_MS };
+        throw error;
+    }
+    finally {
+        if (discoveryListPromise === request)
+            discoveryListPromise = null;
+    }
+}
 function readOwnedLegacySocketIdentity() {
     if (process.platform === 'win32')
         return null;
@@ -240,7 +329,7 @@ export function invoke(action, data = {}, options = {}) {
     // 统一解析 payload 顶层字段中的 `@<path>` 文件引用（所有 action 通用）
     const resolvedData = resolveFileRefs(data);
     if (action === 'browser_list') {
-        return dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined, controlSource).then(result => decorateBrowserListResult(result));
+        return dispatchInvoke(action, resolvedData, timeoutSec, transport, undefined, controlSource).then(result => decorateBrowserListResult(transport === 'cdp' ? cdpOnlyBrowserList(result) : result));
     }
     const selector = browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
     return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector, controlSource);
@@ -252,6 +341,11 @@ function isConnError(error) {
 function isSocketSandboxError(error) {
     return error?.code === 'EPERM';
 }
+function isUnavailableConnection(error) {
+    const cause = error.cause ?? error;
+    const code = cause?.code;
+    return isConnError(cause) || isSocketSandboxError(cause) || code === 'EACCES';
+}
 async function dispatchInvoke(action, data, timeoutSec, transport, selector, controlSource) {
     const configuredSocketPath = process.env.MEARL_SOCKET_PATH?.trim();
     if (!selector && configuredSocketPath) {
@@ -269,6 +363,44 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     }
     const browsers = listLiveBrowsers();
     const controllableBrowsers = browsers.filter(isConnectedBrowser);
+    if (action === 'browser_list' && transport === 'cdp') {
+        const registeredCdp = controllableBrowsers.find(browser => browser.transport === 'cdp' && isOrdinaryLocalBrowser(browser));
+        if (registeredCdp) {
+            try {
+                return await invokeOnce(action, data, timeoutSec, transport, registeredCdp.socketPath, controlSource);
+            }
+            catch (error) {
+                if (!isConnError(error))
+                    throw error;
+            }
+        }
+        try {
+            return await discoverLocalBrowserList(timeoutSec, controlSource);
+        }
+        catch (error) {
+            if (isUnavailableConnection(error) &&
+                browsers.some(browser => browser.transport === 'provider') &&
+                areInstalledProvidersRunning()) {
+                return withDiscoveryWarning(browserListFromProviderRecords(browsers), error);
+            }
+            throw error;
+        }
+    }
+    // A Provider record can keep the registry nonempty without representing a local
+    // browser transport. Let the discovery daemon probe CDP before returning that inventory.
+    if (action === 'browser_list' && !controllableBrowsers.some(isOrdinaryLocalBrowser)) {
+        try {
+            return await discoverLocalBrowserList(timeoutSec, controlSource);
+        }
+        catch (error) {
+            if (isUnavailableConnection(error) &&
+                browsers.some(browser => browser.transport === 'provider') &&
+                areInstalledProvidersRunning()) {
+                return withDiscoveryWarning(browserListFromProviderRecords(browsers), error);
+            }
+            throw error;
+        }
+    }
     // Explicit target: must match a live browser; do not silently fall back.
     if (selector) {
         const match = findBrowser(browsers, selector);
@@ -301,7 +433,8 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
     }
     // No explicit target: prefer the most-recently-focused live browser; on a
     // stale socket, fall through to the legacy path + auto-spawn.
-    const routableBrowsers = controllableBrowsers.filter(browser => !(transport === 'cdp' && browser.transport === 'provider') &&
+    const routableBrowsers = controllableBrowsers.filter(browser => (action !== 'browser_list' || browser.transport !== 'provider') &&
+        !(transport === 'cdp' && browser.transport === 'provider') &&
         supportsAction(browser, action, data));
     if (routableBrowsers.length > 0) {
         const target = routableBrowsers[0];
@@ -318,10 +451,18 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
                 throw error;
         }
     }
-    if (action === 'browser_list' &&
-        browsers.some(browser => browser.transport === 'provider') &&
-        areInstalledProvidersRunning()) {
-        return browserListFromProviderRecords(browsers);
+    if (action === 'browser_list') {
+        try {
+            return await discoverLocalBrowserList(timeoutSec, controlSource);
+        }
+        catch (error) {
+            if (isUnavailableConnection(error) &&
+                browsers.some(browser => browser.transport === 'provider') &&
+                areInstalledProvidersRunning()) {
+                return withDiscoveryWarning(browserListFromProviderRecords(browsers), error);
+            }
+            throw error;
+        }
     }
     return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, /* isRetry */ false);
 }
@@ -337,15 +478,9 @@ async function invokeViaLegacy(action, data, timeoutSec, transport, controlSourc
         if (shouldAttemptSpawn && !isRetry) {
             if (err.code === 'ECONNREFUSED')
                 removeStaleLegacySocket(legacySocketIdentity);
-            const spawned = await trySpawnNativeHost(action === 'browser_list' ? 'discovery' : 'control');
+            const spawned = await trySpawnNativeHost();
             if (spawned) {
-                // Wait for the native host to start listening. Discovery retries the legacy socket directly
-                // so the spawned host receives the probe even if another browser registers in the meantime.
                 await new Promise(r => setTimeout(r, 1200));
-                if (action === 'browser_list') {
-                    return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, 
-                    /* isRetry */ true);
-                }
                 const browsers = listLiveBrowsers();
                 const target = browsers.find(browser => isConnectedBrowser(browser) &&
                     !(transport === 'cdp' && browser.transport === 'provider') &&
@@ -453,7 +588,8 @@ function formatConnectError(error, socketPath) {
     if (error.code === 'ENOENT') {
         return [
             `未找到 Socket: ${socketPath}`,
-            'native host 自动拉起失败，请手动排查：',
+            'native host 自动拉起失败。先运行 mearl check --local；缺少命令时运行 npx @mearl/setup --local --yes。',
+            '自动拉起只使用默认 daemon 参数；自定义 CDP/Profile/浏览器参数需手工启动，参见 mearl-native-host --help。',
             '',
             '【方式一：浏览器插件模式】',
             `1. 确认已安装 Mearl 浏览器插件（${EXTENSION_INSTALL_URL}）`,
@@ -469,7 +605,7 @@ function formatConnectError(error, socketPath) {
     if (error.code === 'ECONNREFUSED') {
         return [
             `Socket 连接被拒绝: ${socketPath}`,
-            'native host 自动恢复失败。',
+            '已尝试处理 stale socket，但 native host 自动恢复仍失败。请运行 mearl check --local 定位故障。',
             '请确认 Chrome 浏览器正在运行，可尝试在 chrome://extensions 重新加载插件。',
             '',
             installHint,

package/dist/unified.js

@@ -449,7 +449,8 @@ export class UnifiedClient {
     connect() {
         return new Promise((resolve, reject) => {
             if (!this.options.serverUrl) {
-                reject(new Error('Cloud server URL is required. Start cloud-server, pass --server, or set MEARL_SERVER_URL.'));
+                reject(new Error('Cloud server URL is required. Run mearl-cloud-server status on the Agent machine. ' +
+                    'Resolution order: --server > MEARL_SERVER_URL > ~/.mearl/cloud-server.json.'));
                 return;
             }
             const ws = new WebSocket(this.options.serverUrl);

package/package.json

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