@mearl/client 2.15.3 → 2.16.1

package/README.md

@@ -143,19 +143,21 @@ mearl yuque --help
 mearl yuque --version
 ```
 
-目录默认使用 `scripts/main.mjs`。入口默认导出 `register(app)`，可导出简短的 `description`
-显示在 `mearl` 插件列表中，并通过 `app.command(signature, handler, description?)`
-注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
+目录默认使用 `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`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
-自动注册默认以 skill 安装目录名作为命令名，也可在入口导出 `name` 指定短名称。
+自动注册默认以 skill 安装目录名作为命令名，也可在入口声明 `name` 指定短名称。
 setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。
 
 需要单独检查插件时运行 `mearl <name> --version`。命令会解析注册记录并加载入口，但不连接浏览器；
 退出码为 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` 复用既有连接和默认浏览器：
 
@@ -181,8 +183,11 @@ 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

@@ -1,6 +1,6 @@
 import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
 import type { UnifiedInvokeOptions } from './unified.js';
-export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, type PluginRegistrationOptions, } from './pluginRegistry.js';
+export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, type PluginRegistrationOptions, } from './pluginRegistry.js';
 export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, type OfficialPluginDefinition, type OfficialPluginName, } from './officialPluginCatalog.js';
 export type PluginOptions = UnifiedInvokeOptions;
 export interface PluginInvocation {
@@ -21,19 +21,19 @@ export interface PluginApp {
     progress(message: string): void;
 }
 export type PluginHandler = (input: Record<string, any>) => unknown | Promise<unknown>;
-/** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
+/** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
 export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): 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 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

@@ -1,12 +1,13 @@
 import { readFileSync, statSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
+import { dirname, extname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command } from 'commander';
 import { COMMAND_MAP } from './commands.js';
 import { findOfficialPlugin } from './officialPluginCatalog.js';
 import { ensureOfficialPluginRegistered, } from './officialPluginInstaller.js';
 import { findPluginRegistration, PluginError } from './pluginRegistry.js';
-export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
+import { describePythonPlugin, runPythonPluginCommand } from './pythonPlugin.js';
+export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
 export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, } from './officialPluginCatalog.js';
 function readPluginVersion(entry) {
     try {
@@ -36,7 +37,7 @@ function missingPluginEntryMessage(entry, pluginName) {
         `卸载命令：npx @mearl/setup plugin uninstall ${name}`,
     ].join('\n');
 }
-/** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
+/** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
 export async function loadPlugin(entry, context, pluginName) {
     let entryVersion;
     try {
@@ -88,18 +89,29 @@ export async function loadPlugin(entry, context, pluginName) {
         },
     });
     try {
-        const moduleUrl = pathToFileURL(entry);
-        moduleUrl.searchParams.set('mearl-version', entryVersion);
-        const module = await import(moduleUrl.href);
-        if (module.name !== undefined && typeof module.name !== 'string')
-            throw new Error('入口的 name 导出必须为字符串');
-        name = module.name;
-        if (module.description !== undefined && typeof module.description !== 'string')
-            throw new Error('入口的 description 导出必须为字符串');
-        description = module.description;
-        if (typeof module.default !== 'function')
-            throw new Error('入口必须默认导出 register(app) 函数');
-        await module.default(app);
+        if (extname(entry).toLowerCase() === '.py') {
+            const descriptor = await describePythonPlugin(entry, app.options);
+            name = descriptor.name;
+            description = descriptor.description;
+            for (const command of descriptor.commands) {
+                const commandName = command.signature.trim().split(/\s+/)[0];
+                app.command(command.signature, input => runPythonPluginCommand(entry, commandName, input, app), command.description);
+            }
+        }
+        else {
+            const moduleUrl = pathToFileURL(entry);
+            moduleUrl.searchParams.set('mearl-version', entryVersion);
+            const module = await import(moduleUrl.href);
+            if (module.name !== undefined && typeof module.name !== 'string')
+                throw new Error('入口的 name 导出必须为字符串');
+            name = module.name;
+            if (module.description !== undefined && typeof module.description !== 'string')
+                throw new Error('入口的 description 导出必须为字符串');
+            description = module.description;
+            if (typeof module.default !== 'function')
+                throw new Error('入口必须默认导出 register(app) 函数');
+            await module.default(app);
+        }
         if (commands.size === 0)
             throw new Error('入口未注册任何命令');
     }
@@ -133,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) => [
@@ -155,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/dist/pluginRegistry.d.ts

@@ -12,6 +12,7 @@ export interface PluginRegistrationOptions {
 }
 export declare function pluginDirectory(): string;
 export declare function assertPluginName(name: string): void;
+export declare function findPluginDirectoryEntry(directory: string): string | undefined;
 export declare function resolvePluginEntry(target: string): string;
 export declare function registerPlugin(name: string, target: string, description?: string, options?: PluginRegistrationOptions): string;
 export declare function unregisterPlugin(name: string): boolean;

package/dist/pluginRegistry.js

@@ -26,18 +26,31 @@ export function assertPluginName(name) {
         throw new PluginError('PLUGIN_INVALID_NAME', `不可用的插件名称: ${name}`);
     }
 }
+export function findPluginDirectoryEntry(directory) {
+    for (const filename of ['main.mjs', 'main.py']) {
+        const entry = join(directory, 'scripts', filename);
+        try {
+            if (statSync(entry).isFile())
+                return entry;
+        }
+        catch {
+            // 没有约定入口的目录是普通 skill，调用方据此跳过自动注册。
+        }
+    }
+    return undefined;
+}
 export function resolvePluginEntry(target) {
     const absolute = resolve(target);
     try {
-        const entry = statSync(absolute).isDirectory()
-            ? join(absolute, 'scripts', 'main.mjs')
-            : absolute;
+        const entry = statSync(absolute).isDirectory() ? findPluginDirectoryEntry(absolute) : absolute;
+        if (!entry)
+            throw new Error('not a file');
         if (!statSync(entry).isFile())
             throw new Error('not a file');
         return entry;
     }
     catch {
-        throw new PluginError('PLUGIN_ENTRY_MISSING', `入口不存在: ${absolute}（目录默认使用 scripts/main.mjs）`);
+        throw new PluginError('PLUGIN_ENTRY_MISSING', `入口不存在: ${absolute}（目录默认使用 scripts/main.mjs 或 scripts/main.py）`);
     }
 }
 export function registerPlugin(name, target, description, options = {}) {

package/dist/pythonPlugin.d.ts

@@ -0,0 +1,17 @@
+import type { PluginOptions } from './plugin.js';
+export interface PythonPluginCommand {
+    description: string;
+    signature: string;
+}
+export interface PythonPluginDescriptor {
+    commands: PythonPluginCommand[];
+    description?: string;
+    name?: string;
+}
+export interface PythonPluginApp {
+    readonly options: Readonly<PluginOptions>;
+    invoke(action: string, payload?: Record<string, any>, options?: PluginOptions): Promise<any>;
+    progress(message: string): void;
+}
+export declare function describePythonPlugin(entry: string, options: Readonly<PluginOptions>): Promise<PythonPluginDescriptor>;
+export declare function runPythonPluginCommand(entry: string, command: string, input: Record<string, any>, app: PythonPluginApp): Promise<unknown>;

package/dist/pythonPlugin.js

@@ -0,0 +1,403 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { PluginError } from './pluginRegistry.js';
+const STDERR_LIMIT = 64 * 1024;
+// Bootstrap 随 Node client 分发，Python 插件无需额外安装宿主 SDK。
+const PYTHON_BOOTSTRAP = String.raw `
+import asyncio
+import importlib.util
+import inspect
+import json
+import os
+import sys
+from types import MappingProxyType
+
+_protocol_output = sys.stdout
+sys.stdout = sys.stderr
+
+
+def _send(message):
+    encoded = json.dumps(message, ensure_ascii=False, allow_nan=False, separators=(",", ":"))
+    _protocol_output.write(encoded + "\n")
+    _protocol_output.flush()
+
+
+def _receive():
+    line = sys.stdin.readline()
+    if not line:
+        raise RuntimeError("Mearl 宿主已断开")
+    message = json.loads(line)
+    if not isinstance(message, dict):
+        raise RuntimeError("Mearl 宿主发送了无效消息")
+    return message
+
+
+def _resolve(value):
+    if inspect.isawaitable(value):
+        return asyncio.run(value)
+    return value
+
+
+class _InvocationError(RuntimeError):
+    def __init__(self, message, code=None):
+        super().__init__(message)
+        self.code = code
+
+
+class _App:
+    def __init__(self, options):
+        self.options = MappingProxyType(options)
+        self.commands = []
+        self.registering = True
+        self.executing = False
+        self.request_id = 0
+
+    def command(self, signature, handler=None, description=""):
+        if not self.registering:
+            raise RuntimeError("命令只能在入口注册阶段声明")
+        if not isinstance(signature, str):
+            raise TypeError("命令签名必须为字符串")
+        if not isinstance(description, str):
+            raise TypeError("命令 description 必须为字符串")
+
+        def add(candidate):
+            if not callable(candidate):
+                raise TypeError("命令 handler 必须可调用")
+            self.commands.append({
+                "signature": signature,
+                "description": description,
+                "handler": candidate,
+            })
+            return candidate
+
+        if handler is None:
+            return add
+        add(handler)
+        return None
+
+    def invoke(self, action, payload=None, options=None):
+        if not self.executing:
+            raise RuntimeError("app.invoke 只能在命令执行期间调用")
+        if not isinstance(action, str) or not action:
+            raise TypeError("app.invoke action 必须为非空字符串")
+        if payload is None:
+            payload = {}
+        if options is None:
+            options = {}
+        if not isinstance(payload, dict) or not isinstance(options, dict):
+            raise TypeError("app.invoke payload 和 options 必须为字典")
+        self.request_id += 1
+        request_id = self.request_id
+        _send({
+            "type": "invoke",
+            "id": request_id,
+            "action": action,
+            "payload": payload,
+            "options": options,
+        })
+        response = _receive()
+        if response.get("type") != "response" or response.get("id") != request_id:
+            raise RuntimeError("Mearl 宿主返回了无效的 invoke 响应")
+        error = response.get("error")
+        if isinstance(error, dict):
+            raise _InvocationError(str(error.get("message", "调用失败")), error.get("code"))
+        return response.get("result")
+
+    def progress(self, message):
+        if not self.executing:
+            raise RuntimeError("app.progress 只能在命令执行期间调用")
+        if not isinstance(message, str) or not message:
+            raise TypeError("app.progress 需要非空字符串")
+        _send({"type": "progress", "message": message})
+
+
+def _error_message(error):
+    if isinstance(error, _InvocationError):
+        return str(error)
+    detail = str(error)
+    return type(error).__name__ + (": " + detail if detail else "")
+
+
+phase = "load"
+try:
+    if sys.version_info < (3, 9):
+        current = ".".join(str(part) for part in sys.version_info[:3])
+        raise RuntimeError("需要 Python 3.9 或更高版本，当前为 " + current)
+
+    initial = _receive()
+    mode = initial.get("mode")
+    options = initial.get("options", {})
+    if mode not in ("describe", "run") or not isinstance(options, dict):
+        raise RuntimeError("Mearl 宿主发送了无效的初始化消息")
+
+    entry = os.path.abspath(sys.argv[1])
+    entry_directory = os.path.dirname(entry)
+    if entry_directory not in sys.path:
+        sys.path.insert(0, entry_directory)
+    spec = importlib.util.spec_from_file_location("mearl_skill_plugin", entry)
+    if spec is None or spec.loader is None:
+        raise RuntimeError("无法加载 Python 插件入口")
+    module = importlib.util.module_from_spec(spec)
+    sys.modules[spec.name] = module
+    spec.loader.exec_module(module)
+
+    plugin_name = getattr(module, "name", None)
+    plugin_description = getattr(module, "description", None)
+    if plugin_name is not None and not isinstance(plugin_name, str):
+        raise TypeError("入口的 name 必须为字符串")
+    if plugin_description is not None and not isinstance(plugin_description, str):
+        raise TypeError("入口的 description 必须为字符串")
+    register = getattr(module, "register", None)
+    if not callable(register):
+        raise TypeError("入口必须导出 register(app) 函数")
+
+    app = _App(options)
+    _resolve(register(app))
+    app.registering = False
+    if not app.commands:
+        raise RuntimeError("入口未注册任何命令")
+
+    descriptor = {
+        "type": "ready",
+        "commands": [
+            {"signature": item["signature"], "description": item["description"]}
+            for item in app.commands
+        ],
+    }
+    if plugin_name is not None:
+        descriptor["name"] = plugin_name
+    if plugin_description is not None:
+        descriptor["description"] = plugin_description
+    _send(descriptor)
+
+    if mode == "run":
+        acknowledgement = _receive()
+        if acknowledgement.get("type") != "ready_ack":
+            raise RuntimeError("Mearl 宿主未确认插件注册信息")
+        command_name = initial.get("command")
+        command_input = initial.get("input")
+        if not isinstance(command_name, str) or not isinstance(command_input, dict):
+            raise RuntimeError("Mearl 宿主发送了无效的命令")
+        selected = next(
+            (item for item in app.commands if item["signature"].strip().split()[0] == command_name),
+            None,
+        )
+        if selected is None:
+            raise RuntimeError("未知子命令: " + command_name)
+        phase = "run"
+        app.executing = True
+        try:
+            result = _resolve(selected["handler"](command_input))
+        finally:
+            app.executing = False
+        _send({"type": "result", "result": result})
+except BaseException as error:
+    response = {"type": "error", "phase": phase, "message": _error_message(error)}
+    code = getattr(error, "code", None)
+    if isinstance(code, str):
+        response["code"] = code
+    try:
+        _send(response)
+    except BaseException as serialization_error:
+        _send({
+            "type": "error",
+            "phase": phase,
+            "message": "返回值无法 JSON 序列化: " + _error_message(serialization_error),
+        })
+    sys.exit(1)
+`;
+function pythonExecutable() {
+    return process.env.MEARL_PYTHON?.trim() || 'python3';
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function parseDescriptor(message) {
+    if (!Array.isArray(message.commands))
+        throw new Error('Python 插件未返回命令列表');
+    const commands = message.commands.map(value => {
+        if (!isObject(value) ||
+            typeof value.signature !== 'string' ||
+            typeof value.description !== 'string') {
+            throw new Error('Python 插件返回了无效的命令描述');
+        }
+        return { signature: value.signature, description: value.description };
+    });
+    if (message.name !== undefined && typeof message.name !== 'string') {
+        throw new Error('Python 插件返回了无效的 name');
+    }
+    if (message.description !== undefined && typeof message.description !== 'string') {
+        throw new Error('Python 插件返回了无效的 description');
+    }
+    return {
+        commands,
+        ...(typeof message.name === 'string' ? { name: message.name } : {}),
+        ...(typeof message.description === 'string' ? { description: message.description } : {}),
+    };
+}
+function bridgedError(message) {
+    const detail = typeof message.message === 'string' ? message.message : 'Python 插件执行失败';
+    if (typeof message.code === 'string' && /^PLUGIN_[A-Z0-9_]+$/.test(message.code)) {
+        return new PluginError(message.code, detail);
+    }
+    return new Error(detail);
+}
+function errorResponse(error) {
+    if (error instanceof PluginError) {
+        const prefix = `${error.code}: `;
+        return {
+            code: error.code,
+            message: error.message.startsWith(prefix)
+                ? error.message.slice(prefix.length)
+                : error.message,
+        };
+    }
+    return { message: error instanceof Error ? error.message : String(error) };
+}
+async function runPythonWorker(entry, initial, app) {
+    return new Promise((resolve, reject) => {
+        const executable = pythonExecutable();
+        const child = spawn(executable, ['-u', '-c', PYTHON_BOOTSTRAP, entry], {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        const lines = createInterface({ input: child.stdout });
+        let descriptor;
+        let outcome;
+        let protocolError;
+        let stderr = '';
+        const failProtocol = (error) => {
+            if (protocolError)
+                return;
+            protocolError = error instanceof Error ? error : new Error(String(error));
+            child.kill();
+        };
+        const write = (message) => {
+            try {
+                child.stdin.write(`${JSON.stringify(message)}\n`);
+            }
+            catch (error) {
+                failProtocol(error);
+            }
+        };
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', chunk => {
+            stderr = `${stderr}${chunk}`.slice(-STDERR_LIMIT);
+        });
+        child.stdin.on('error', () => undefined);
+        child.once('error', error => {
+            if (error.code === 'ENOENT') {
+                reject(new Error(`未找到 ${executable}，Python 插件需要 Python 3.9 或更高版本` +
+                    '（可通过 MEARL_PYTHON 指定解释器）'));
+            }
+            else {
+                reject(error);
+            }
+        });
+        lines.on('line', line => {
+            let message;
+            try {
+                const value = JSON.parse(line);
+                if (!isObject(value) || typeof value.type !== 'string') {
+                    throw new Error('消息不是对象');
+                }
+                message = value;
+            }
+            catch (error) {
+                failProtocol(new Error(`Python 插件输出了无效协议消息: ${line.slice(0, 200)}`, error instanceof Error ? { cause: error } : undefined));
+                return;
+            }
+            if (message.type === 'ready') {
+                try {
+                    if (descriptor)
+                        throw new Error('Python 插件重复发送 ready');
+                    descriptor = parseDescriptor(message);
+                    if (initial.mode === 'run')
+                        write({ type: 'ready_ack' });
+                }
+                catch (error) {
+                    failProtocol(error);
+                }
+                return;
+            }
+            if (message.type === 'progress') {
+                if (!app || typeof message.message !== 'string') {
+                    failProtocol(new Error('Python 插件发送了无效的 progress 消息'));
+                    return;
+                }
+                try {
+                    app.progress(message.message);
+                }
+                catch (error) {
+                    failProtocol(error);
+                }
+                return;
+            }
+            if (message.type === 'invoke') {
+                if (!app ||
+                    typeof message.id !== 'number' ||
+                    typeof message.action !== 'string' ||
+                    !isObject(message.payload) ||
+                    !isObject(message.options)) {
+                    failProtocol(new Error('Python 插件发送了无效的 invoke 消息'));
+                    return;
+                }
+                void app
+                    .invoke(message.action, message.payload, message.options)
+                    .then(result => {
+                    write({
+                        type: 'response',
+                        id: message.id,
+                        result: result === undefined ? null : result,
+                    });
+                })
+                    .catch(error => {
+                    write({ type: 'response', id: message.id, error: errorResponse(error) });
+                });
+                return;
+            }
+            if (message.type === 'result') {
+                outcome = { hasResult: true, result: message.result };
+                return;
+            }
+            if (message.type === 'error') {
+                outcome = { error: bridgedError(message) };
+                return;
+            }
+            failProtocol(new Error(`Python 插件发送了未知消息类型: ${message.type}`));
+        });
+        child.once('close', code => {
+            lines.close();
+            if (protocolError) {
+                reject(protocolError);
+                return;
+            }
+            if (outcome?.error) {
+                reject(outcome.error);
+                return;
+            }
+            if (code !== 0) {
+                reject(new Error(stderr.trim() || `Python 插件进程异常退出${code === null ? '' : ` (exit ${code})`}`));
+                return;
+            }
+            if (!descriptor) {
+                reject(new Error('Python 插件未返回注册信息'));
+                return;
+            }
+            if (initial.mode === 'run' && !outcome?.hasResult) {
+                reject(new Error('Python 插件未返回执行结果'));
+                return;
+            }
+            resolve({ descriptor, ...(outcome?.hasResult ? { result: outcome.result } : {}) });
+        });
+        write(initial);
+    });
+}
+export async function describePythonPlugin(entry, options) {
+    const { descriptor } = await runPythonWorker(entry, { mode: 'describe', options });
+    return descriptor;
+}
+export async function runPythonPluginCommand(entry, command, input, app) {
+    const { result } = await runPythonWorker(entry, { mode: 'run', command, input, options: app.options }, app);
+    return result;
+}

package/package.json

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