@mearl/client 2.16.3 → 2.16.4

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/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.16.4",
   "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/cloud-types": "2.16.4",
+    "@mearl/provider": "2.16.4"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",