@mearl/client 3.0.0-beta.7 → 3.0.0-beta.8

package/dist/plugins/sdk/plugin.js

@@ -146,6 +146,7 @@ export async function loadPlugin(entry, context, pluginName) {
     let registering = true;
     let name;
     let description;
+    let defaultCommand;
     let toolbox;
     let pageRuntime;
     let stateStorage;
@@ -312,6 +313,9 @@ export async function loadPlugin(entry, context, pluginName) {
             if (module.description !== undefined && typeof module.description !== 'string')
                 throw new Error('入口的 description 导出必须为字符串');
             description = module.description;
+            if (module.defaultCommand !== undefined && typeof module.defaultCommand !== 'string')
+                throw new Error('入口的 defaultCommand 导出必须为字符串');
+            defaultCommand = module.defaultCommand;
             toolbox = normalizePluginToolboxContribution(module.toolbox);
             pageRuntime = normalizePluginPageRuntime(module.pageRuntime);
             stateStorage = normalizePluginState(module.stateStorage);
@@ -326,6 +330,8 @@ export async function loadPlugin(entry, context, pluginName) {
         }
         if (commands.size === 0 && !appProfiles)
             throw new Error('入口未注册任何命令');
+        if (defaultCommand !== undefined && (!commands.has(defaultCommand) || commands.get(defaultCommand)?.toolboxOnly || commands.get(defaultCommand)?.runtimeOnly))
+            throw new Error('defaultCommand 必须指向公开命令');
         for (const command of Object.keys(taskRecovery?.commands ?? {})) {
             if (!commands.has(command) ||
                 commands.get(command)?.runtimeOnly ||
@@ -401,12 +407,13 @@ export async function loadPlugin(entry, context, pluginName) {
         if (payload !== undefined && Object.keys(namedInput).length > 0) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '插件业务选项与 --payload 调用不能混用');
         }
-        if (payload !== undefined &&
-            (!isObject(payload) || typeof payload.command !== 'string' || !isObject(payload.input))) {
+        const defaultPayload = defaultCommand && toolboxPage === false && isObject(payload) && !Object.hasOwn(payload, 'command');
+        if (payload !== undefined && !defaultPayload && !isPluginInvocation(payload)) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '--payload 必须为 {"command":"...","input":{...}}');
         }
-        const envelope = payload;
-        const commandName = envelope?.command ?? positionals[0] ?? '';
+        const envelope = (defaultPayload ? { command: defaultCommand, input: payload } : payload);
+        const positionalOffset = defaultCommand && !commands.has(positionals[0]) && toolboxPage === false ? 0 : 1;
+        const commandName = envelope?.command ?? (positionalOffset === 0 ? defaultCommand : positionals[0] ?? '');
         const hidden = toolboxPage === 'recovery' || toolboxPage === 'migration';
         const selected = find(commandName, hidden ? false : toolboxPage);
         const command = selected.command;
@@ -426,7 +433,7 @@ export async function loadPlugin(entry, context, pluginName) {
             : Object.fromEntries(command.registeredArguments
                 .map((argument, index) => [
                 argument.name(),
-                argument.variadic ? positionals.slice(index + 1) : positionals[index + 1],
+                argument.variadic ? positionals.slice(index + positionalOffset) : positionals[index + positionalOffset],
             ])
                 .filter(([, value]) => value !== undefined));
         for (const name of Object.keys(namedInput)) {
@@ -437,7 +444,7 @@ export async function loadPlugin(entry, context, pluginName) {
         const input = { ...positionalInput, ...namedInput };
         if (!envelope &&
             !command.registeredArguments.some(argument => argument.variadic) &&
-            positionals.length - 1 > command.registeredArguments.length) {
+            positionals.length - positionalOffset > command.registeredArguments.length) {
             throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数过多');
         }
         for (const argument of hidden ? [] : command.registeredArguments) {
@@ -529,6 +536,7 @@ export async function loadPlugin(entry, context, pluginName) {
     return {
         name,
         description,
+        defaultCommand,
         toolbox,
         pageRuntime,
         stateStorage,
@@ -538,11 +546,11 @@ export async function loadPlugin(entry, context, pluginName) {
         version: readPluginVersion(entry),
         commandHelp(namespace) {
             return publicCommands()
-                .map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`)
+                .map(({ command, signature }) => `  ${namespace} ${command.name() === defaultCommand ? signature.slice(defaultCommand.length).trim() : signature}  ${command.description()}`)
                 .join('\n');
         },
         help(namespace, name) {
-            const selected = name ? [find(name)] : publicCommands();
+            const selected = name ? [find(defaultCommand && !commands.has(name) ? defaultCommand : name)] : publicCommands();
             if (!selected.length) {
                 const location = toolbox
                     ? `请在 Mearl ${toolbox.displayMode === 'popup' ? 'Popup' : '工具箱'} 中打开「${toolbox.title}」使用。`
@@ -552,7 +560,7 @@ export async function loadPlugin(entry, context, pluginName) {
             const examples = selected.flatMap(({ examples }) => examples);
             return [
                 '用法：',
-                ...selected.map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`),
+                ...selected.map(({ command, signature }) => `  ${namespace} ${command.name() === defaultCommand ? signature.slice(defaultCommand.length).trim() : signature}  ${command.description()}`),
                 ...(examples.length
                     ? ['', '示例：', ...examples.map(example => `  ${namespace} ${example}`)]
                     : []),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "3.0.0-beta.7",
+  "version": "3.0.0-beta.8",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -67,11 +67,11 @@
     "commander": "^14.0.3",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/daemon-core": "3.0.0-beta.7",
-    "@mearl/cloud-types": "3.0.0-beta.7",
-    "@mearl/provider": "3.0.0-beta.7",
-    "@mearl/agent-runtime": "3.0.0-beta.7",
-    "@mearl/browser-core": "3.0.0-beta.7"
+    "@mearl/daemon-core": "3.0.0-beta.8",
+    "@mearl/cloud-types": "3.0.0-beta.8",
+    "@mearl/provider": "3.0.0-beta.8",
+    "@mearl/agent-runtime": "3.0.0-beta.8",
+    "@mearl/browser-core": "3.0.0-beta.8"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",
@@ -84,7 +84,7 @@
     "directory": "packages/client"
   },
   "scripts": {
-    "build": "rm -rf dist/ && tsc && chmod +x dist/bin.js",
+    "build": "rm -rf dist/ && tsc && node build-guides.mjs && chmod +x dist/bin.js",
     "dev": "tsc --watch",
     "typecheck": "tsc --noEmit",
     "test": "vitest run"