@mearl/client 2.16.0 → 2.16.1

package/README.md

@@ -153,8 +153,11 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 退出码为 0 表示插件已注册且入口可加载，stdout 返回同目录 `SKILL.md` 的版本，缺少版本元数据时返回 `unknown`。
 未注册、入口丢失或加载失败会以退出码 2 和对应的 `PLUGIN_*` 错误结束。普通业务调用无需预先检查，直接处理同样的错误即可。
 
-插件接受位置参数或包含 command/input 的 `--payload`，两种形式不能混用。JSON 保留业务字段类型；正文等文件输入
-按具体 skill 的字段约定处理。插件不使用上表中内置 action 的 `--payload-file` 入口。
+插件接受位置参数、字符串业务选项或包含 command/input 的 `--payload`。业务选项推荐写成
+`--name=value`，也接受 `--name value`，字段名与 handler 的 input 一致且不依赖位置顺序；同一字段不能同时
+使用位置参数和业务选项，`--payload` 不能与前两种形式混用。JSON 保留业务字段类型；正文等文件输入按具体
+skill 的字段约定处理。`browser`、`timeout`、`output` 等宿主选项保留原有含义；同名业务字段以及数字、
+布尔值、对象和数组通过 `--payload` 传入。插件不使用上表中内置 action 的 `--payload-file` 入口。
 
 注册后的插件也可从 SDK 调用；实例方法 `client.invokePlugin` 复用既有连接和默认浏览器：
 
@@ -180,8 +183,9 @@ MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command
 
 需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request`，业务插件使用
 `app.invoke('buc', { command: 'request', input })`；当前身份和人员资料分别使用 `whoami` 与 `profile`
-子命令。BUC 插件按请求创建一次性凭据，只允许访问 HTTPS `alibaba-inc.com` 域名，过滤认证字段与
-Cookie，并始终在运行 CLI、SDK 或 MCP Server 的机器上执行，不随浏览器或 connector 转发。
+子命令。BUC 插件按请求创建一次性凭据，只接受无 URL 凭据的 HTTPS 地址，过滤认证字段与 Cookie；
+调用方须按已验证的业务契约确认目标服务可信。请求始终在运行 CLI、SDK 或 MCP Server 的机器上执行，
+不随浏览器或 connector 转发。
 `buc request` 支持与 `send_request` 同结构的 `formData` 和 `files`；`files[].filePath` 从该插件执行
 宿主读取，而不是浏览器 native-host，无法引用宿主路径时使用 Base64 内容与 `filename`。
 

package/dist/cli.d.ts

@@ -17,6 +17,7 @@ export interface ParsedArgs {
     timeoutSec: number;
     timeoutOption?: string;
     pluginArgs?: string[];
+    pluginInput?: Record<string, unknown>;
     help?: boolean;
     version?: boolean;
     verbose?: boolean;

package/dist/cli.js

@@ -70,6 +70,39 @@ const SUGGESTABLE_COMMANDS = [
     ...OFFICIAL_PLUGIN_COMMANDS,
 ];
 const ADVANCED_BUILTIN_COMMANDS = new Set(['connector_list']);
+const PLUGIN_HOST_OPTIONS = new Set([
+    '--browser',
+    '--cdp',
+    '--compact',
+    '--connector',
+    '--help',
+    '--json',
+    '--local',
+    '--output',
+    '--payload',
+    '--payload-file',
+    '--server',
+    '--timeout',
+    '--verbose',
+    '--version',
+]);
+function findPluginInputOptionNames(args) {
+    const names = new Set();
+    for (const argument of args) {
+        if (!argument.startsWith('--') || argument === '--')
+            continue;
+        const equals = argument.indexOf('=');
+        const option = equals === -1 ? argument : argument.slice(0, equals);
+        if (PLUGIN_HOST_OPTIONS.has(option))
+            continue;
+        const name = option.slice(2);
+        if (!/^[a-zA-Z][a-zA-Z0-9]*$/.test(name)) {
+            throw new Error(`无效的插件业务选项: ${option}`);
+        }
+        names.add(name);
+    }
+    return [...names];
+}
 function printUsage(commandName, version) {
     const lines = [
         `${commandName} v${version}`,
@@ -355,6 +388,7 @@ function actionInvocationFailed(action, result) {
         : false;
 }
 export function parseClientArgs(args, plugin = false) {
+    const pluginInputOptionNames = plugin ? findPluginInputOptionNames(args) : [];
     const program = new Command()
         .name('mearl')
         .helpOption(false)
@@ -379,6 +413,8 @@ export function parseClientArgs(args, plugin = false) {
             .option('-h, --help')
             .option('-v, --version')
             .option('--verbose');
+    for (const name of pluginInputOptionNames)
+        program.option(`--${name} <value>`);
     try {
         program.parse(['node', 'mearl', ...args]);
     }
@@ -393,6 +429,12 @@ export function parseClientArgs(args, plugin = false) {
     if (plugin && options.payloadFile !== undefined) {
         throw new Error('插件使用 --payload 传入 command 和 input；正文文件可由业务字段引用');
     }
+    const pluginInput = Object.fromEntries(pluginInputOptionNames
+        .filter(name => Object.hasOwn(options, name))
+        .map(name => [name, options[name]]));
+    if (plugin && options.payload !== undefined && Object.keys(pluginInput).length > 0) {
+        throw new Error('插件业务选项不能与 --payload 同时使用');
+    }
     const json = options.json === true;
     if (json && action !== 'check')
         throw new Error('--json 仅适用于 check');
@@ -420,6 +462,7 @@ export function parseClientArgs(args, plugin = false) {
         ...(plugin
             ? {
                 pluginArgs: program.processedArgs[1],
+                ...(Object.keys(pluginInput).length > 0 ? { pluginInput } : {}),
                 help: options.help === true,
                 version: options.version === true,
                 verbose: options.verbose === true,
@@ -471,7 +514,7 @@ async function runPluginCli(args, commandName) {
             console.error(plugin.help(`${commandName} ${parsed.action}`, parsed.pluginArgs?.[0]));
             return 0;
         }
-        const result = await plugin.run(parsed.pluginArgs ?? [], parsed.hasPayload ? parsed.payload : undefined);
+        const result = await plugin.run(parsed.pluginArgs ?? [], parsed.hasPayload ? parsed.payload : undefined, parsed.pluginInput);
         if (result !== undefined) {
             if (parsed.outputPath)
                 writeOutput('', result, parsed.outputPath);

package/dist/plugin.d.ts

@@ -27,13 +27,13 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invo
     description: string | undefined;
     version: string | undefined;
     help(namespace: string, name?: string): string;
-    run(positionals: string[], payload?: unknown): Promise<unknown>;
+    run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
 }>;
 export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
     name: string | undefined;
     description: string | undefined;
     version: string | undefined;
     help(namespace: string, name?: string): string;
-    run(positionals: string[], payload?: unknown): Promise<unknown>;
+    run(positionals: string[], payload?: unknown, namedInput?: Record<string, unknown>): Promise<unknown>;
 }>;
 export declare function invokeRegisteredPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;

package/dist/plugin.js

@@ -145,21 +145,24 @@ export async function loadPlugin(entry, context, pluginName) {
                 '',
                 '常用选项: --browser --timeout --compact --output',
                 '连接或传输排障运行 mearl check --help。',
-                '插件选项: --verbose; -h, --help; -v, --version',
-                'JSON input 直接传给 handler；业务字段与校验规则见对应 skill。',
+                '插件选项: --name=value 传入字符串业务字段；--verbose; -h, --help; -v, --version',
+                '同名宿主选项及非字符串字段使用 --payload；业务字段与校验规则见对应 skill。',
             ].join('\n');
         },
-        async run(positionals, payload) {
+        async run(positionals, payload, namedInput = {}) {
             if (payload !== undefined && positionals.length > 0) {
                 throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数调用与 --payload 调用不能混用');
             }
+            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))) {
                 throw new PluginError('PLUGIN_INVALID_INPUT', '--payload 必须为 {"command":"...","input":{...}}');
             }
             const envelope = payload;
             const { command, handler } = find(envelope?.command ?? positionals[0] ?? '');
-            const input = envelope
+            const positionalInput = envelope
                 ? { ...envelope.input }
                 : Object.fromEntries(command.registeredArguments
                     .map((argument, index) => [
@@ -167,6 +170,12 @@ export async function loadPlugin(entry, context, pluginName) {
                     argument.variadic ? positionals.slice(index + 1) : positionals[index + 1],
                 ])
                     .filter(([, value]) => value !== undefined));
+            for (const name of Object.keys(namedInput)) {
+                if (Object.hasOwn(positionalInput, name)) {
+                    throw new PluginError('PLUGIN_INVALID_INPUT', `参数不能重复传入: ${name}`);
+                }
+            }
+            const input = { ...positionalInput, ...namedInput };
             if (!envelope &&
                 !command.registeredArguments.some(argument => argument.variadic) &&
                 positionals.length - 1 > command.registeredArguments.length) {

package/package.json

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