@mearl/client 3.0.0-beta.1 → 3.0.0-beta.10

package/dist/actionTimeouts.js

@@ -26,9 +26,6 @@ export function resolveActionTimeoutSec(action, data, fallback = 15) {
             : 0;
         return Math.max(fallback, Math.ceil(((data.timeout ?? 30000) + transferTimeoutMs + 5000) / 1000));
     }
-    if (action === 'send_mtop_request') {
-        return Math.max(fallback, Math.ceil(((data.timeout ?? 10000) + 5000) / 1000));
-    }
     if (action === 'page_download')
         return Math.max(fallback, Math.ceil((Number(data.timeout ?? 30000) + 10000) / 1000));
     if (action === 'page_wait') {

package/dist/autoUpdate.js

@@ -4,6 +4,7 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync,
 import { homedir } from 'node:os';
 import { delimiter, dirname, join, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { npmExecEnvironment } from '@mearl/daemon-core';
 import { isNewerRelease, parseReleaseVersion } from './check.js';
 import { loadCliAutoUpdateIntervalDays } from './unifiedConfig.js';
 const CONFIG_DIR = join(homedir(), '.mearl');
@@ -207,7 +208,7 @@ export function setupUpdateCommand(version, packageRoot, profiles, updateClient)
     if (!parseReleaseVersion(version))
         throw new Error('A valid Mearl release is required');
     const [major, minor] = version.split('.');
-    const env = { ...process.env };
+    const env = npmExecEnvironment();
     delete env.MEARL_AUTO_UPDATE_CLIENT_ROOT;
     delete env.MEARL_AUTO_UPDATE_CLIENT_ONLY;
     delete env.MEARL_AUTO_UPDATE_PROFILES;
@@ -223,6 +224,7 @@ export function setupUpdateCommand(version, packageRoot, profiles, updateClient)
         command: 'npx',
         args: [
             '--yes',
+            '--@mearl:registry=https://registry.npmjs.org',
             `@mearl/setup@${version}`,
             'update',
             '--yes',

package/dist/bin.js

@@ -1,6 +1,13 @@
 #!/usr/bin/env node
-import { runMearlCli } from './cli.js';
-import { CLIENT_VERSION } from './socket.js';
-import { scheduleCliAutoUpdate } from './autoUpdate.js';
-process.exitCode = await runMearlCli(process.argv.slice(2));
-scheduleCliAutoUpdate(CLIENT_VERSION);
+import { CLIENT_VERSION } from './runtimePaths.js';
+const args = process.argv.slice(2);
+if (args[0] === 'guide') {
+    const { runGuideCli } = await import('./guide.js');
+    process.exitCode = await runGuideCli(args.slice(1));
+}
+else {
+    const { runMearlCli } = await import('./cli.js');
+    process.exitCode = await runMearlCli(args);
+    const { scheduleCliAutoUpdate } = await import('./autoUpdate.js');
+    scheduleCliAutoUpdate(CLIENT_VERSION);
+}

package/dist/capabilityHelp.d.ts

@@ -0,0 +1,4 @@
+import type { BrowserCapabilityCatalog } from '@mearl/browser-core';
+/** Help reads an existing target with a short budget; it never installs an environment. */
+export declare function readHelpCapabilities(args: string[]): Promise<BrowserCapabilityCatalog | undefined>;
+export declare function formatCapabilityHelp(catalog: BrowserCapabilityCatalog | undefined, detailed?: boolean): string;

package/dist/capabilityHelp.js

@@ -0,0 +1,68 @@
+import { resolveServer } from './unifiedConfig.js';
+import { listLiveBrowsers } from './browserRegistry.js';
+import { UnifiedClient } from './unified.js';
+/** Help reads an existing target with a short budget; it never installs an environment. */
+export async function readHelpCapabilities(args) {
+    const value = (flag) => {
+        const index = args.indexOf(flag);
+        return index < 0 ? args.find(arg => arg.startsWith(`${flag}=`))?.slice(flag.length + 1) : args[index + 1];
+    };
+    const browser = value('--browser');
+    const session = value('--session');
+    const connector = value('--connector');
+    const { serverUrl } = resolveServer(value('--server'));
+    const local = args.includes('--local') || args.includes('--cdp');
+    if (local && connector || session === 'new')
+        return;
+    if (!browser && !connector && (local || !serverUrl) && !session && !listLiveBrowsers().length)
+        return;
+    const client = new UnifiedClient({ connectTimeoutSec: 1, requestTimeoutSec: 1, ...(serverUrl ? { serverUrl } : {}) });
+    let timer;
+    try {
+        const result = await Promise.race([
+            client.invoke('get_capabilities', {}, {
+                ...(browser ? { browser } : {}), ...(session ? { session } : {}),
+                ...(connector ? { connector } : {}), ...(local ? { local: true } : {}),
+                ...(args.includes('--cdp') ? { transport: 'cdp' } : {}),
+            }),
+            new Promise(resolve => { timer = setTimeout(() => resolve(undefined), 1500); }),
+        ]);
+        if (result && Array.isArray(result.actions) && Array.isArray(result.apps?.entries))
+            return result;
+    }
+    catch {
+        // Static help remains usable when the target is offline or does not expose a catalog.
+    }
+    finally {
+        clearTimeout(timer);
+        client.disconnect();
+    }
+}
+export function formatCapabilityHelp(catalog, detailed = false) {
+    if (!catalog)
+        return '当前浏览器能力暂不可读；以下为静态帮助。连接后再次运行 --help 可查看已安装 App。';
+    const lines = [
+        '当前浏览器已安装的 App：',
+    ];
+    if (!catalog.apps.entries.length)
+        lines.push(catalog.apps.status === 'available' ? '  暂无 App 档案；设备模拟可独立使用。' : '  App 目录暂不可读，不代表未安装。');
+    for (const app of catalog.apps.entries) {
+        lines.push(`  ${app.id} — ${app.label}${app.available ? '' : '（暂不可用）'}`);
+        if (!detailed)
+            continue;
+        lines.push(`    能力：${app.features.join(', ')}`);
+        if (app.usage?.skills?.length)
+            lines.push(`    Skill：${app.usage.skills.join(', ')}`);
+        if (app.usage?.description)
+            lines.push(`    ${app.usage.description}`);
+        if (app.usage?.limitations?.length)
+            lines.push(...app.usage.limitations.map(line => `    限制：${line}`));
+        if (app.usage?.documentation?.length)
+            lines.push(...app.usage.documentation.map(doc => `    说明：${doc.title} ${doc.url}`));
+    }
+    if (detailed)
+        lines.push(...catalog.limitations.map(line => `  ${line}`));
+    else
+        lines.push('  App 用法与限制：mearl set_app_profile --help');
+    return lines.join('\n');
+}

package/dist/check.d.ts

@@ -15,13 +15,12 @@ export interface ProviderVersionInfo {
     version: string;
     protocolVersion: number;
 }
-export type BrowserAccessCapability = {
-    kind: 'sandbox-novnc';
-    environment: 'opensandbox' | 'aone';
-    port: number;
-} | {
+export interface BrowserAccessCapability {
     kind: string;
-};
+    label?: string;
+    environment?: string;
+    port?: number;
+}
 export type BrowserAccess = BrowserAccessCapability & {
     url: string;
 };

package/dist/check.js

@@ -4,7 +4,7 @@ const UPDATE_SOURCES = {
     client: 'https://registry.npmjs.org/@mearl%2Fclient/latest',
     'native-host': 'https://registry.npmjs.org/@mearl%2Fnative-host/latest',
     'cloud-connector': 'https://registry.npmjs.org/@mearl%2Fcloud-connector/latest',
-    extension: 'https://github.com/F-loat/mearl/releases/latest/download/config.json',
+    extension: 'https://github.com/mearlhq/mearl/releases/latest/download/config.json',
 };
 export function parseReleaseVersion(value) {
     if (typeof value !== 'string')
@@ -46,10 +46,7 @@ function formatError(error) {
     return error instanceof Error ? error.message : String(error);
 }
 function browserAccessLabel(access) {
-    if (access.kind === 'sandbox-novnc' && 'environment' in access) {
-        return access.environment === 'opensandbox' ? 'OpenSandbox noVNC' : 'AONE Sandbox noVNC';
-    }
-    return access.kind;
+    return access.label || access.kind;
 }
 async function getBrowserAccess(client, browser, capability, timeoutSec) {
     const result = (await client.invoke('get_browser_access_url', {}, { timeoutSec, browser: browser.browserId }));

package/dist/cli.js

@@ -1,3 +1,4 @@
+import { readHelpCapabilities, formatCapabilityHelp } from './capabilityHelp.js';
 import { readFileSync, writeFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 import { Command, CommanderError } from 'commander';
@@ -6,10 +7,11 @@ import { resolveActionTimeoutSec } from './actionTimeouts.js';
 import { runUnifiedCheck, parseCheckTimeout } from './check.js';
 import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from './commandSuggestions.js';
 import { COMMANDS, COMMAND_MAP } from './commands.js';
+import { formatCommandHelp } from './commandHelp.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
 import { findPluginEntry, findPluginRegistration, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugins/sdk/plugin.js';
-import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
+import { resolveServer } from './unifiedConfig.js';
 const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
     {
@@ -19,7 +21,7 @@ const CATEGORIES = [
     { title: 'Mock & 规则', names: ['set_mock', 'get_mocks', 'set_rule', 'get_rules'] },
     {
         title: '网络请求',
-        names: ['send_request', 'send_mtop_request', 'request_domain_permission'],
+        names: ['send_request', 'request_permission'],
     },
     { title: '标签页', names: ['tab_open', 'tab_list', 'tab_group', 'tab_close'] },
     {
@@ -59,6 +61,12 @@ const CATEGORIES = [
     },
 ];
 const BUILTIN_COMMANDS = [
+    { name: 'guide', description: '按需读取与当前 CLI 配套的本地指南', examples: ['guide', 'guide environment'] },
+    {
+        name: 'run',
+        description: '执行预注入 mearl SDK 的 Node.js 脚本',
+        examples: ['run --file task.mjs'],
+    },
     {
         name: 'check',
         description: '检查指定浏览器，未指定时检查全部已连接浏览器',
@@ -120,6 +128,8 @@ function printUsage(commandName, version) {
         `  ${commandName} <action> [选项]`,
         `  ${commandName} <action> --help`,
         `  ${commandName} check [选项]`,
+        `  ${commandName} run [--file <path>] [选项]`,
+        `  ${commandName} guide [topic]`,
         '',
         '常用选项：',
         '  --payload <json>      直接传入 JSON 参数',
@@ -135,6 +145,8 @@ function printUsage(commandName, version) {
         '  -v, --version         查看版本',
         '',
         '内置命令：',
+        `  ${'guide'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}读取本地核心流程或单个专题；--list 查看主题`,
+        `  ${'run'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}执行 Node.js 脚本，支持浏览器 API 与 Skill 命令`,
         `  ${'check'.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}检查指定浏览器，未指定时检查全部已连接浏览器`,
     ];
     for (const category of CATEGORIES) {
@@ -300,46 +312,6 @@ function printAdvancedCommandHelp(commandName, action) {
         '结果包含 count 与 connectors；每项包含 ID、名称、可选版本、连接时间和最后心跳。',
     ].join('\n'));
 }
-function printCommandHelp(commandName, command) {
-    const payloadUsage = command.params?.length ? ' [--payload <json> | --payload-file <path>]' : '';
-    const lines = [
-        `${command.name}`,
-        `  ${command.description}`,
-        '',
-        '用法：',
-        `  ${commandName} ${command.name}${payloadUsage} [常用选项]`,
-        '',
-    ];
-    if (command.params?.length) {
-        lines.push('参数（--payload JSON 字段）：');
-        for (const parameter of command.params) {
-            const required = parameter.required ? '必填' : '可选';
-            lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}  ${parameter.description}`);
-            for (const detail of parameter.details ?? [])
-                lines.push(`    ${detail}`);
-        }
-        lines.push('');
-    }
-    if (command.name === 'browser_list') {
-        lines.push('目标范围（按需）：', '  --local               只列出当前机器上的浏览器', '  --connector <id|名称> 只列出指定远端 connector 的浏览器', '');
-    }
-    else if (command.name === 'browser_launch') {
-        lines.push('宿主选择（本机与远端同时可用时）：', '  --local               在当前机器启动', '  --connector <id|名称> 在指定远端 connector 启动', '  --browser <id|名称>   在控制浏览器所在宿主启动，并可作为 Cookie/UA 来源', '');
-    }
-    if (command.notes?.length) {
-        lines.push('约束与行为：', ...command.notes.map(note => `  ${note}`), '');
-    }
-    if (command.result?.length) {
-        lines.push('结果：', ...command.result.map(line => `  ${line}`), '');
-    }
-    if (command.examples?.length) {
-        lines.push('示例：');
-        for (const example of command.examples)
-            lines.push(`  ${commandName} ${example}`);
-    }
-    lines.push('', `运行 ${commandName} --help 查看常用选项。`);
-    console.error(lines.join('\n'));
-}
 function printUnknownCommand(commandName, args) {
     const input = commandInput(args) || args[0] || '';
     const suggestions = findCommandSuggestions(args, SUGGESTABLE_COMMANDS);
@@ -383,17 +355,6 @@ function parsePayload(payloadRaw, payloadFile) {
     }
     return {};
 }
-function resolveServer(explicit) {
-    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 normalizeScreenshotOutput(action, payload, explicitOutput) {
     if (action !== 'page_screenshot' || !Object.hasOwn(payload, 'output')) {
         return { payload, ...(explicitOutput ? { outputPath: explicitOutput } : {}) };
@@ -555,7 +516,7 @@ async function runPluginCli(args, commandName) {
             console.log(plugin.version ?? 'unknown');
             return 0;
         }
-        if (parsed.help || (!parsed.pluginArgs?.length && !parsed.hasPayload)) {
+        if (parsed.help || (!plugin.defaultCommand && !parsed.pluginArgs?.length && !parsed.hasPayload && !Object.keys(parsed.pluginInput ?? {}).length)) {
             console.error(plugin.help(`${commandName} ${parsed.action}`, parsed.pluginArgs?.[0]));
             return 0;
         }
@@ -605,6 +566,14 @@ function writeOutput(action, result, outputPath) {
 export async function runMearlCli(args, options = {}) {
     const commandName = options.commandName ?? 'mearl';
     const clientVersion = options.clientVersion ?? CLIENT_VERSION;
+    if (args[0] === 'guide') {
+        const { runGuideCli } = await import('./guide.js');
+        return runGuideCli(args.slice(1), commandName, clientVersion);
+    }
+    if (args[0] === 'run') {
+        const { runScriptCli } = await import('./scriptCli.js');
+        return runScriptCli(args.slice(1), commandName);
+    }
     if (args[0] === 'capture_checkpoint')
         args = ['tab_checkpoint', ...args.slice(1)];
     const provider = installedProvider(args[0]);
@@ -640,8 +609,11 @@ export async function runMearlCli(args, options = {}) {
     }
     if (args.includes('--help') || args.includes('-h')) {
         const command = COMMAND_MAP.get(args[0]);
-        if (command)
-            printCommandHelp(commandName, command);
+        if (command) {
+            console.error(formatCommandHelp(commandName, command));
+            if (command.name === 'set_app_profile' || command.name === 'tab_open')
+                console.error(formatCapabilityHelp(await readHelpCapabilities(args), true));
+        }
         else if (args[0] === 'check')
             printCheckHelp(commandName);
         else if (ADVANCED_BUILTIN_COMMANDS.has(args[0])) {
@@ -649,6 +621,7 @@ export async function runMearlCli(args, options = {}) {
         }
         else if (args[0]?.startsWith('-')) {
             printUsage(commandName, clientVersion);
+            console.error(formatCapabilityHelp(await readHelpCapabilities(args)));
         }
         else {
             printUnknownCommand(commandName, args);

package/dist/commandHelp.d.ts

@@ -0,0 +1,3 @@
+import { type CommandDef } from './commands.js';
+export declare function getCommandHelp(target?: string): string;
+export declare function formatCommandHelp(commandName: string, command: CommandDef): string;

package/dist/commandHelp.js

@@ -0,0 +1,79 @@
+import { COMMANDS, COMMAND_MAP } from './commands.js';
+import { SDK_METHOD_ACTIONS, SDK_OPTIONS_ONLY_METHODS } from './sdkMethods.js';
+import { listPluginNames } from './plugins/pluginRegistry.js';
+const HELPER_HELP = {
+    invoke: 'invoke(action, payload?, options?) — 调用浏览器 action，返回普通 action 的原始结果',
+    invokePlugin: 'invokePlugin(name, { command, input }, options?) — 调用已注册 Skill 命令，返回该命令的原始结果',
+    help: 'help(methodOrAction?) / help({ plugin, command? }) — 返回共享命令帮助文本；无参数时列出方法；用 console.log 输出',
+    structure: 'structure(value, { maxDepth=5, maxKeys=50, arraySamples=1, maxNodes=2000 }?) — 同步返回有界结构样本；叶子值替换为类型，标注数组样本、循环引用和截断；不能证明未采样内容或业务语义',
+    saveArtifact: 'saveArtifact(artifact, absolutePath, options?) — 保存浏览器文件产物，返回保存结果',
+    selectBrowser: 'selectBrowser({ browser? }, options?) — 选择默认目标；返回 { selected }；browser 使用 browserList 返回的 ID 或名称，空字符串清除默认目标',
+};
+export function getCommandHelp(target) {
+    if (!target)
+        return [
+            ...COMMANDS.map((command) => `${[...SDK_METHOD_ACTIONS].find(([, action]) => action === command.name)?.[0] ?? command.name} (${command.name}) — ${command.summary ?? command.description}`),
+            ...Object.values(HELPER_HELP),
+            ...listPluginNames().map(plugin => `Skill ${plugin} — help({ plugin: '${plugin}' })`),
+        ].join('\n');
+    if (Object.hasOwn(HELPER_HELP, target))
+        return HELPER_HELP[target];
+    const resolved = SDK_METHOD_ACTIONS.get(target) ?? target;
+    const action = resolved === 'capture_checkpoint' ? 'tab_checkpoint' : resolved;
+    if (action === 'browser_select_browser')
+        return HELPER_HELP.selectBrowser;
+    const command = COMMAND_MAP.get(action);
+    if (!command)
+        throw new Error(`Unknown command or SDK method: ${target}`);
+    return formatCommandHelp('mearl', command);
+}
+export function formatCommandHelp(commandName, command) {
+    const payloadUsage = command.params?.length ? ' [--payload <json> | --payload-file <path>]' : '';
+    const lines = [
+        `${command.name}`,
+        `  ${command.description}`,
+        '',
+        '用法：',
+        `  ${commandName} ${command.name}${payloadUsage} [常用选项]`,
+        '',
+    ];
+    const method = [...SDK_METHOD_ACTIONS].find(([, action]) => action === command.name)?.[0];
+    if (method)
+        lines.push('SDK：', ...(method === 'browserRelease' || method === 'browserList'
+            ? [
+                `  await mearl.${method}(options?)`,
+                `  await mearl.${method}(params, options)`,
+            ]
+            : [
+                `  await mearl.${method}(${SDK_OPTIONS_ONLY_METHODS.has(method) ? 'options?' : 'params, options?'})`,
+            ]), '');
+    if (command.params?.length) {
+        lines.push('参数（--payload JSON 字段）：');
+        for (const parameter of command.params) {
+            const required = parameter.required ? '必填' : '可选';
+            lines.push(`  ${parameter.name.padEnd(22)}${required.padEnd(6)}${parameter.type.padEnd(28)}  ${parameter.description}`);
+            for (const detail of parameter.details ?? [])
+                lines.push(`    ${detail}`);
+        }
+        lines.push('');
+    }
+    if (command.name === 'browser_list') {
+        lines.push('目标范围（按需）：', '  --local               只列出当前机器上的浏览器', '  --connector <id|名称> 只列出指定远端 connector 的浏览器', '');
+    }
+    else if (command.name === 'browser_launch') {
+        lines.push('宿主选择（本机与远端同时可用时）：', '  --local               在当前机器启动', '  --connector <id|名称> 在指定远端 connector 启动', '  --browser <id|名称>   在控制浏览器所在宿主启动，并可作为 Cookie/UA 来源', '');
+    }
+    if (command.notes?.length) {
+        lines.push('约束与行为：', ...command.notes.map(note => `  ${note}`), '');
+    }
+    if (command.result?.length) {
+        lines.push('结果：', ...command.result.map(line => `  ${line}`), '');
+    }
+    if (command.examples?.length) {
+        lines.push('示例：');
+        for (const example of command.examples)
+            lines.push(`  ${commandName} ${example}`);
+    }
+    lines.push('', `运行 ${commandName} --help 查看常用选项。`);
+    return lines.join('\n');
+}

package/dist/commandSuggestions.d.ts

@@ -1,5 +1,7 @@
 export interface SuggestableCommand {
     readonly aliases?: readonly string[];
+    /** Suggestion-only expressions whose canonical invocation needs a specific payload. */
+    readonly aliasExamples?: Readonly<Record<string, string>>;
     readonly description: string;
     readonly examples?: readonly string[];
     readonly name: string;
@@ -7,6 +9,7 @@ export interface SuggestableCommand {
 export interface CommandSuggestion {
     command: SuggestableCommand;
     score: number;
+    example?: string;
 }
 export declare function commandInput(args: readonly string[]): string;
 export declare function findCommandSuggestions(args: readonly string[], commands: readonly SuggestableCommand[], limit?: number): CommandSuggestion[];

package/dist/commandSuggestions.js

@@ -40,9 +40,20 @@ export function findCommandSuggestions(args, commands, limit = 3) {
         return [];
     const ranked = commands
         .map(command => {
-        const keys = [command.name, ...(command.aliases ?? [])].map(normalizeCommand);
-        const score = Math.max(...queries.flatMap(query => keys.map(key => similarity(query, key))));
-        return { command, score };
+        const keys = [command.name, ...(command.aliases ?? [])].map(name => ({ name }));
+        for (const [name, example] of Object.entries(command.aliasExamples ?? {})) {
+            keys.push({ name, example });
+        }
+        let score = -1;
+        let example;
+        for (const key of keys) {
+            const candidate = Math.max(...queries.map(query => similarity(query, normalizeCommand(key.name))));
+            if (candidate > score) {
+                score = candidate;
+                example = key.example;
+            }
+        }
+        return { command, score, ...(example ? { example } : {}) };
     })
         .filter(suggestion => suggestion.score >= MIN_SIMILARITY)
         .sort((left, right) => right.score - left.score || left.command.name.localeCompare(right.command.name));
@@ -52,8 +63,8 @@ export function findCommandSuggestions(args, commands, limit = 3) {
     return ranked.filter(suggestion => bestScore - suggestion.score <= MAX_SCORE_GAP).slice(0, limit);
 }
 export function formatCommandSuggestions(commandName, suggestions) {
-    return suggestions.map(({ command }) => {
-        const invocation = command.examples?.[0] ?? command.name;
+    return suggestions.map(({ command, example }) => {
+        const invocation = example ?? command.examples?.[0] ?? command.name;
         return `  ${commandName} ${invocation}\n    ${command.description}`;
     });
 }