@mearl/client 2.15.3 → 2.16.0

package/README.md

@@ -143,11 +143,10 @@ 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`。命令会解析注册记录并加载入口，但不连接浏览器；
@@ -183,6 +182,8 @@ MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command
 `app.invoke('buc', { command: 'request', input })`；当前身份和人员资料分别使用 `whoami` 与 `profile`
 子命令。BUC 插件按请求创建一次性凭据，只允许访问 HTTPS `alibaba-inc.com` 域名，过滤认证字段与
 Cookie，并始终在运行 CLI、SDK 或 MCP Server 的机器上执行，不随浏览器或 connector 转发。
+`buc request` 支持与 `send_request` 同结构的 `formData` 和 `files`；`files[].filePath` 从该插件执行
+宿主读取，而不是浏览器 native-host，无法引用宿主路径时使用 Base64 内容与 `filename`。
 
 ## 支持的操作
 

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,7 +21,7 @@ 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;

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('入口未注册任何命令');
     }

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