@mearl/client 2.16.3 → 2.17.0

package/README.md

@@ -143,6 +143,10 @@ mearl yuque --help
 mearl yuque --version
 ```
 
+当已注册插件与 Provider 使用同一名称时，`mearl <name> --help` 会先显示 Provider 的启动和生命周期说明，
+再自动追加插件注册的扩展命令；`mearl <name> <command> --help` 继续显示单个插件命令的详细帮助。
+Provider 与插件仍可独立安装、更新和卸载，帮助聚合不会启动 Provider 或执行业务命令。
+
 目录默认使用 `scripts/main.mjs` 或 `scripts/main.py`；两者同时存在时使用 JavaScript 入口。JavaScript 入口默认导出 `register(app)`，Python 入口导出 `register(app)` 函数；两种入口都可声明简短的 `name` 和 `description`，并通过 `app.command(signature, handler, description?)`
 注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。Python 的 `app.invoke` 是同步调用，handler 可以是普通函数或 `async def`。Python 插件要求 `python3 >= 3.9`，可用 `MEARL_PYTHON` 指定解释器路径；Mearl 不安装 Python 或执行 `pip install`。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
 `--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。

package/dist/cli.js

@@ -192,7 +192,7 @@ function providerSchemaLines(name, schema, required, indent = 2) {
     }
     return lines;
 }
-function printProviderHelp(commandName, provider) {
+function printProviderHelp(commandName, provider, extensionHelp) {
     const browserType = provider.browserType;
     const lines = [
         `${provider.providerId} — ${provider.name} v${provider.version}`,
@@ -230,8 +230,26 @@ function printProviderHelp(commandName, provider) {
     if (browserType.documentationUrl) {
         lines.push('', `文档：${browserType.documentationUrl}`);
     }
+    if (extensionHelp) {
+        lines.push('', '扩展命令：', extensionHelp, '', `运行 ${commandName} ${provider.providerId} <command> --help 查看命令参数。`);
+    }
     console.error(lines.join('\n'));
 }
+async function sameNamePluginHelp(commandName, name) {
+    try {
+        if (!findPluginEntry(name))
+            return undefined;
+        const plugin = await loadRegisteredPlugin(name, {
+            async invoke() {
+                throw new Error('生成插件帮助时不能调用宿主能力');
+            },
+        });
+        return plugin.commandHelp(`${commandName} ${name}`);
+    }
+    catch (error) {
+        return `  （扩展命令帮助不可用：${error instanceof Error ? error.message : String(error)}）`;
+    }
+}
 function installedProvider(name) {
     if (!name)
         return undefined;
@@ -559,7 +577,8 @@ export async function runMearlCli(args, options = {}) {
     const provider = installedProvider(args[0]);
     if (provider &&
         (args.length === 1 || args.slice(1).every(arg => arg === '--help' || arg === '-h'))) {
-        printProviderHelp(commandName, provider);
+        const extensionHelp = await sameNamePluginHelp(commandName, provider.providerId);
+        printProviderHelp(commandName, provider, extensionHelp);
         return 0;
     }
     if (args[0] &&

package/dist/commands.d.ts

@@ -308,8 +308,8 @@ export declare const COMMANDS: readonly [{
         readonly description: "签名使用的 appKey，默认 12574478";
     }, {
         readonly name: "env";
-        readonly type: "\"online\" | \"pre\"";
-        readonly description: "请求环境，默认 online";
+        readonly type: "\"prod\" | \"pre\"";
+        readonly description: "请求环境，默认 prod";
     }, {
         readonly name: "timeout";
         readonly type: "number";
@@ -856,7 +856,7 @@ export declare const COMMANDS: readonly [{
     readonly examples: ["set_device_emulation --payload '{\"enabled\":true,\"preset\":\"iphone-17-pro\"}'", "set_device_emulation --payload '{\"enabled\":true,\"preset\":\"pixel-11\",\"orientation\":\"landscape\"}'", "set_device_emulation --payload '{\"enabled\":true,\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}'", "set_device_emulation --payload '{\"enabled\":false}'"];
 }, {
     readonly name: "set_app_profile";
-    readonly description: "设置 App 客户端环境与 JSBridge；传 emulation 时由同一个命令联动设备模拟，省略时不改变设备状态";
+    readonly description: "设置 App 客户端环境与 JSBridge；可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟";
     readonly summary: "设置或清除目标标签页的 App 容器模拟";
     readonly params: [{
         readonly name: "enabled";
@@ -883,6 +883,10 @@ export declare const COMMANDS: readonly [{
         readonly name: "bridgeConfig";
         readonly type: "object";
         readonly description: "声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本";
+    }, {
+        readonly name: "mtopEnv";
+        readonly type: "\"default\" | \"prod\" | \"pre\"";
+        readonly description: "可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab";
     }, {
         readonly name: "emulation";
         readonly type: "object";
@@ -897,7 +901,7 @@ export declare const COMMANDS: readonly [{
         readonly required: true;
         readonly description: "目标标签页 ID";
     }];
-    readonly examples: ["set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\"}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\",\"emulation\":{}}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"alipay\",\"emulation\":{\"preset\":\"pixel-11\",\"deviceShell\":true}}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "set_app_profile --payload '{\"enabled\":false}'", "set_app_profile --payload '{\"enabled\":false,\"emulation\":{}}'"];
+    readonly examples: ["set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\"}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\",\"mtopEnv\":\"pre\"}'", "set_app_profile --payload '{\"enabled\":false,\"mtopEnv\":\"prod\"}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\",\"emulation\":{}}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"alipay\",\"emulation\":{\"preset\":\"pixel-11\",\"deviceShell\":true}}'", "set_app_profile --payload '{\"enabled\":true,\"profile\":\"fliggy\",\"emulation\":{\"preset\":\"ipad-mini-a17-pro\",\"orientation\":\"landscape\",\"deviceShell\":true,\"splitScreen\":true}}'", "set_app_profile --payload '{\"enabled\":false}'", "set_app_profile --payload '{\"enabled\":false,\"emulation\":{}}'"];
 }, {
     readonly name: "set_timezone";
     readonly description: "覆盖目标 tab 的时区，传空字符串恢复浏览器默认时区";

package/dist/commands.js

@@ -214,7 +214,7 @@ export const COMMANDS = [
             { name: 'version', type: 'string', description: 'API 版本，默认 1.0' },
             { name: 'method', type: 'string', description: 'HTTP 方法，默认 GET' },
             { name: 'appKey', type: 'string', description: '签名使用的 appKey，默认 12574478' },
-            { name: 'env', type: '"online" | "pre"', description: '请求环境，默认 online' },
+            { name: 'env', type: '"prod" | "pre"', description: '请求环境，默认 prod' },
             { name: 'timeout', type: 'number', description: '超时毫秒数，默认 10000' },
         ],
         examples: [
@@ -794,7 +794,7 @@ export const COMMANDS = [
     },
     {
         name: 'set_app_profile',
-        description: '设置 App 客户端环境与 JSBridge；传 emulation 时由同一个命令联动设备模拟，省略时不改变设备状态',
+        description: '设置 App 客户端环境与 JSBridge；可同时设置 MTop 页面接口环境，传 emulation 时联动设备模拟',
         summary: '设置或清除目标标签页的 App 容器模拟',
         params: [
             { name: 'enabled', type: 'boolean', required: true, description: 'true=启用，false=清除' },
@@ -815,6 +815,11 @@ export const COMMANDS = [
                 type: 'object',
                 description: '声明式覆盖桥方法，形如 {methods:{api:{behavior|response|noop,silent?}}}；不执行配置脚本',
             },
+            {
+                name: 'mtopEnv',
+                type: '"default" | "prod" | "pre"',
+                description: '可选 MTop 页面接口环境；default 关闭环境改写，省略时保持当前设置。扩展模式全局生效，CDP 模式仅作用于目标 tab',
+            },
             {
                 name: 'emulation',
                 type: 'object',
@@ -825,6 +830,8 @@ export const COMMANDS = [
         ],
         examples: [
             `set_app_profile --payload '{"enabled":true,"profile":"fliggy"}'`,
+            `set_app_profile --payload '{"enabled":true,"profile":"fliggy","mtopEnv":"pre"}'`,
+            `set_app_profile --payload '{"enabled":false,"mtopEnv":"prod"}'`,
             `set_app_profile --payload '{"enabled":true,"profile":"fliggy","emulation":{}}'`,
             `set_app_profile --payload '{"enabled":true,"profile":"alipay","emulation":{"preset":"pixel-11","deviceShell":true}}'`,
             `set_app_profile --payload '{"enabled":true,"profile":"fliggy","emulation":{"preset":"ipad-mini-a17-pro","orientation":"landscape","deviceShell":true,"splitScreen":true}}'`,

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

@@ -95,13 +95,15 @@ export interface SendRequestParams {
     responseType?: 'json' | 'text' | 'auto';
     timeout?: number;
 }
+export type MtopEnvironmentTarget = 'prod' | 'pre';
+export type MtopEnvironment = 'default' | MtopEnvironmentTarget;
 export interface SendMtopRequestParams {
     api: string;
     data?: unknown;
     version?: string;
     method?: string;
     appKey?: string;
-    env?: string;
+    env?: MtopEnvironmentTarget;
     timeout?: number;
     headers?: Record<string, string>;
     ttid?: string;
@@ -427,6 +429,11 @@ export interface SetAppProfileParams {
     deviceModel?: string;
     /** 按方法覆盖档案内置桥配置，仅支持受控行为、固定 JSON 回包和成功空实现 */
     bridgeConfig?: AppBridgeConfig;
+    /**
+     * 可选 MTop 接口环境。default 关闭环境改写；省略时保持当前设置。
+     * 扩展模式与插件设置页共享并全局生效；CDP 模式仅作用于目标 tab。
+     */
+    mtopEnv?: MtopEnvironment;
     /**
      * 可选设备联动参数。传入时显式字段覆盖档案推荐设备，空对象使用推荐设备且默认开启
      * deviceShell；省略时不设置或清除该 tab 的设备状态。

package/dist/plugin.d.ts

@@ -26,6 +26,7 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invo
     name: string | undefined;
     description: string | undefined;
     version: string | undefined;
+    commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;
     run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
 }>;
@@ -33,6 +34,7 @@ export declare function loadRegisteredPlugin(name: string, context: PluginExecut
     name: string | undefined;
     description: string | undefined;
     version: string | undefined;
+    commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;
     run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
 }>;

package/dist/plugin.js

@@ -131,6 +131,11 @@ export async function loadPlugin(entry, context, pluginName) {
         name,
         description,
         version: readPluginVersion(entry),
+        commandHelp(namespace) {
+            return [...commands.values()]
+                .map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`)
+                .join('\n');
+        },
         help(namespace, name) {
             const selected = name ? [find(name)] : [...commands.values()];
             const example = selected[0].command;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.16.3",
+  "version": "2.17.0",
   "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.16.3",
-    "@mearl/provider": "2.16.3"
+    "@mearl/provider": "2.17.0",
+    "@mearl/cloud-types": "2.17.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",