@mearl/client 2.11.0 → 2.12.0

package/README.md

@@ -97,6 +97,41 @@ mearl browser_release
 
 `check` 有独立的选项说明，运行 `mearl check --help` 查看。其中 `--json` 仅用于输出机器可读的检查结果。
 
+## Skill CLI 插件
+
+安装 skill 并自动注册命令，或直接注册已有入口：
+
+```bash
+npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
+npx @mearl/setup plugin yuque /absolute/path/to/yuque-doc-fetch
+npx @mearl/setup plugin uninstall yuque
+mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
+mearl yuque --payload '{"command":"read","input":{"url":"https://aliyuque.antfin.com/group/book/doc"}}'
+mearl yuque --help
+mearl yuque --version
+```
+
+目录默认使用 `scripts/main.mjs`。入口默认导出 `register(app)`，通过 `app.command(signature, handler, description?)`
+注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。CLI 默认只输出最终结果，传入
+`--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
+自动注册默认以 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` 入口。
+
+注册记录在 `~/.mearl/plugins/<name>.json`，只引用入口路径；skill 原地更新直接生效，换路径后重新注册。
+`plugin uninstall <name>` 会对 `~/.agents/skills` 中的全局 Skill 调用 `ali-skills remove --global --yes`，
+成功后清除相关注册；即使入口目录已被手动删除，也会完成 Ali Skills 跟踪记录的清理。
+手工路径只解除注册并保留源码。
+`PLUGIN_NOT_REGISTERED` 表示插件尚未注册。`PLUGIN_ENTRY_MISSING` 会显示失效入口，并给出带有实际插件名的
+卸载清理命令。其他错误按实际原因处理。
+编写规范见 [Mearl Skill Creator 的 CLI 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
+
 ## 支持的操作
 
 | 分类          | Actions                                                                                                                              |

package/dist/cli.d.ts

@@ -16,6 +16,11 @@ export interface ParsedArgs {
     serverUrlSource?: string;
     timeoutSec: number;
     timeoutOption?: string;
+    pluginArgs?: string[];
+    help?: boolean;
+    version?: boolean;
+    verbose?: boolean;
+    hasPayload?: boolean;
 }
-export declare function parseClientArgs(args: string[]): ParsedArgs;
+export declare function parseClientArgs(args: string[], plugin?: boolean): ParsedArgs;
 export declare function runMearlCli(args: string[], options?: MearlCliOptions): Promise<number>;

package/dist/cli.js

@@ -7,6 +7,7 @@ import { commandInput, findCommandSuggestions, formatCommandSuggestions, } from
 import { COMMANDS, COMMAND_MAP } from './commands.js';
 import { CLIENT_VERSION } from './socket.js';
 import { UnifiedClient } from './unified.js';
+import { findPluginEntry, listPluginNames, loadPlugin, PluginError } from './plugin.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
 const CATEGORIES = [
     {
@@ -100,6 +101,14 @@ function printUsage(commandName, version) {
                 lines.push(`    ${name.padEnd(26)}${command.summary ?? command.description}`);
         }
     }
+    try {
+        const plugins = listPluginNames();
+        if (plugins.length)
+            lines.push('', '已注册插件：', ...plugins.map(name => `  ${name}`));
+    }
+    catch (error) {
+        lines.push('', error instanceof Error ? error.message : String(error));
+    }
     lines.push('', `运行 ${commandName} <action> --help 查看 action 参数。`);
     console.error(lines.join('\n'));
 }
@@ -162,7 +171,7 @@ function printCommandHelp(commandName, command) {
 function printUnknownCommand(commandName, args) {
     const input = commandInput(args) || args[0] || '';
     const suggestions = findCommandSuggestions(args, SUGGESTABLE_COMMANDS);
-    const lines = [`不支持的命令: ${input}`];
+    const lines = [`PLUGIN_NOT_REGISTERED: 不支持的命令: ${input}`];
     if (suggestions.length > 0) {
         lines.push('', '你可能想用：', ...formatCommandSuggestions(commandName, suggestions));
     }
@@ -213,7 +222,7 @@ function resolveServer(explicit) {
         ? { serverUrl: config.server, serverUrlSource: getCloudServerConfigPath() }
         : {};
 }
-export function parseClientArgs(args) {
+export function parseClientArgs(args, plugin = false) {
     const program = new Command()
         .name('mearl')
         .helpOption(false)
@@ -232,6 +241,12 @@ export function parseClientArgs(args) {
         .option('--local')
         .option('--cdp')
         .option('--server <url>');
+    if (plugin)
+        program
+            .argument('[pluginArgs...]')
+            .option('-h, --help')
+            .option('-v, --version')
+            .option('--verbose');
     try {
         program.parse(['node', 'mearl', ...args]);
     }
@@ -243,6 +258,9 @@ export function parseClientArgs(args) {
     }
     const action = program.processedArgs[0];
     const options = program.opts();
+    if (plugin && options.payloadFile !== undefined) {
+        throw new Error('插件使用 --payload 传入 command 和 input；正文文件可由业务字段引用');
+    }
     const json = options.json === true;
     if (json && action !== 'check')
         throw new Error('--json 仅适用于 check');
@@ -266,8 +284,85 @@ export function parseClientArgs(args) {
         ...(options.browser ? { browser: options.browser } : {}),
         ...(connector ? { connector } : {}),
         ...resolveServer(options.server),
+        ...(plugin
+            ? {
+                pluginArgs: program.processedArgs[1],
+                help: options.help === true,
+                version: options.version === true,
+                verbose: options.verbose === true,
+                hasPayload: options.payload !== undefined,
+            }
+            : {}),
     };
 }
+async function runPluginCli(args, entry, commandName) {
+    let parsed;
+    try {
+        parsed = parseClientArgs(args, true);
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return 2;
+    }
+    let client;
+    try {
+        const invokeOptions = {
+            ...(parsed.timeoutOption ? { timeoutSec: parsed.timeoutSec } : {}),
+            ...(parsed.browser ? { browser: parsed.browser } : {}),
+            ...(parsed.connector ? { connector: parsed.connector } : {}),
+            ...(parsed.local ? { local: true } : {}),
+            ...(parsed.forceCdp ? { transport: 'cdp' } : {}),
+        };
+        const plugin = await loadPlugin(entry, {
+            options: invokeOptions,
+            progress(message) {
+                if (parsed.verbose) {
+                    process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
+                }
+            },
+            async invoke(action, payload, options) {
+                client ??= new UnifiedClient({
+                    ...(parsed.serverUrl ? { serverUrl: parsed.serverUrl } : {}),
+                });
+                const result = await client.invoke(action, payload, { ...invokeOptions, ...options });
+                if (result?.action?.success === false)
+                    throw new Error(result.action.error || `${action} failed`);
+                return result;
+            },
+        }, parsed.action);
+        if (parsed.version) {
+            console.log(plugin.version ?? 'unknown');
+            return 0;
+        }
+        if (parsed.help || (!parsed.pluginArgs?.length && !parsed.hasPayload)) {
+            console.error(plugin.help(`${commandName} ${parsed.action}`, parsed.pluginArgs?.[0]));
+            return 0;
+        }
+        const result = await plugin.run(parsed.pluginArgs ?? [], parsed.hasPayload ? parsed.payload : undefined);
+        if (result !== undefined) {
+            if (parsed.outputPath)
+                writeOutput('', result, parsed.outputPath);
+            else if (typeof result === 'string')
+                process.stdout.write(result.endsWith('\n') ? result : `${result}\n`);
+            else
+                process.stdout.write(`${JSON.stringify(result, null, parsed.compact ? undefined : 2)}\n`);
+        }
+        return result &&
+            typeof result === 'object' &&
+            !Array.isArray(result) &&
+            'success' in result &&
+            result.success === false
+            ? 1
+            : 0;
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        return error instanceof PluginError ? 2 : 1;
+    }
+    finally {
+        client?.disconnect();
+    }
+}
 function screenshotData(action, result) {
     if (typeof result === 'string' && result.startsWith('data:image')) {
         return result.split(',')[1] ?? null;
@@ -294,7 +389,23 @@ export async function runMearlCli(args, options = {}) {
     const clientVersion = options.clientVersion ?? CLIENT_VERSION;
     if (args[0] === 'capture_checkpoint')
         args = ['tab_checkpoint', ...args.slice(1)];
-    if (args.includes('--version') || args.includes('-v')) {
+    if (args[0] &&
+        !args[0].startsWith('-') &&
+        !args[0].startsWith('__') &&
+        args[0] !== 'check' &&
+        !ADVANCED_BUILTIN_COMMANDS.has(args[0]) &&
+        !COMMAND_MAP.has(args[0])) {
+        try {
+            const entry = findPluginEntry(args[0]);
+            if (entry)
+                return await runPluginCli(args, entry, commandName);
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 2;
+        }
+    }
+    if (args[0] === '--version' || args[0] === '-v') {
         console.log(clientVersion);
         return 0;
     }

package/dist/plugin.d.ts

@@ -0,0 +1,17 @@
+import type { UnifiedInvokeOptions } from './unified.js';
+export { assertPluginName, findPluginEntry, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
+export type PluginOptions = UnifiedInvokeOptions;
+export interface PluginApp {
+    readonly options: Readonly<PluginOptions>;
+    command(signature: string, handler: PluginHandler, description?: string): void;
+    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+    progress(message: string): void;
+}
+export type PluginHandler = (input: Record<string, any>) => unknown | Promise<unknown>;
+/** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
+export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
+    name: string | undefined;
+    version: string | undefined;
+    help(namespace: string, name?: string): string;
+    run(positionals: string[], payload?: unknown): Promise<unknown>;
+}>;

package/dist/plugin.js

@@ -0,0 +1,167 @@
+import { readFileSync, statSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { Command } from 'commander';
+import { PluginError } from './pluginRegistry.js';
+export { assertPluginName, findPluginEntry, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
+function readPluginVersion(entry) {
+    try {
+        const content = readFileSync(resolve(dirname(entry), '..', 'SKILL.md'), 'utf8');
+        const frontmatter = content.match(/^---\r?\n([\s\S]*?)\r?\n---/)?.[1];
+        const versionLine = frontmatter?.split(/\r?\n/).find(line => /^version:\s*/.test(line));
+        return versionLine?.match(/^version:\s*["']?([^"'#\s]+)["']?\s*$/)?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function missingPluginEntryMessage(entry, pluginName) {
+    const name = pluginName ?? '<name>';
+    return [
+        '插件入口已失效',
+        '',
+        `插件：${name}`,
+        `入口：${entry}`,
+        '',
+        `卸载命令：npx @mearl/setup plugin uninstall ${name}`,
+    ].join('\n');
+}
+/** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
+export async function loadPlugin(entry, context, pluginName) {
+    try {
+        if (!statSync(entry).isFile())
+            throw new Error('not a file');
+    }
+    catch {
+        throw new PluginError('PLUGIN_ENTRY_MISSING', missingPluginEntryMessage(entry, pluginName));
+    }
+    const commands = new Map();
+    let executing = false;
+    let registering = true;
+    let name;
+    const app = Object.freeze({
+        options: Object.freeze({ ...context.options }),
+        command(signature, handler, description = '') {
+            if (!registering)
+                throw new Error('命令只能在入口注册阶段声明');
+            const [name, ...args] = signature.trim().split(/\s+/);
+            if (!/^[a-z][a-z0-9-]*$/.test(name) || commands.has(name) || typeof handler !== 'function') {
+                throw new Error(`无效或重复的命令: ${signature}`);
+            }
+            const command = new Command(name).description(description);
+            for (const argument of args) {
+                if (!/^(?:<[a-zA-Z][\w-]*(?:\.\.\.)?>|\[[a-zA-Z][\w-]*(?:\.\.\.)?\])$/.test(argument)) {
+                    throw new Error(`无效的位置参数: ${argument}`);
+                }
+                command.argument(argument);
+            }
+            const names = command.registeredArguments.map(argument => argument.name());
+            if (new Set(names).size !== names.length)
+                throw new Error(`参数名称重复: ${signature}`);
+            commands.set(name, { command, signature, handler });
+        },
+        invoke(action, payload = {}, options = {}) {
+            if (!executing)
+                throw new Error('app.invoke 只能在命令执行期间调用');
+            return context.invoke(action, payload, options);
+        },
+        progress(message) {
+            if (!executing)
+                throw new Error('app.progress 只能在命令执行期间调用');
+            if (typeof message !== 'string' || !message)
+                throw new Error('app.progress 需要非空字符串');
+            context.progress(message);
+        },
+    });
+    try {
+        const module = await import(pathToFileURL(entry).href);
+        if (module.name !== undefined && typeof module.name !== 'string')
+            throw new Error('入口的 name 导出必须为字符串');
+        name = module.name;
+        if (typeof module.default !== 'function')
+            throw new Error('入口必须默认导出 register(app) 函数');
+        await module.default(app);
+        if (commands.size === 0)
+            throw new Error('入口未注册任何命令');
+    }
+    catch (error) {
+        throw new PluginError('PLUGIN_LOAD_FAILED', `${entry}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    finally {
+        registering = false;
+    }
+    const find = (name) => {
+        const command = commands.get(name);
+        if (!command)
+            throw new PluginError('PLUGIN_COMMAND_NOT_FOUND', `未知子命令: ${name}`);
+        return command;
+    };
+    return {
+        name,
+        version: readPluginVersion(entry),
+        help(namespace, name) {
+            const selected = name ? [find(name)] : [...commands.values()];
+            const example = selected[0].command;
+            const input = Object.fromEntries(example.registeredArguments.map(argument => [
+                argument.name(),
+                argument.variadic ? [`<${argument.name()}>`] : `<${argument.name()}>`,
+            ]));
+            return [
+                ...selected.map(({ command, signature }) => `  ${namespace} ${signature}  ${command.description()}`),
+                '',
+                `  ${namespace} --payload '${JSON.stringify({ command: example.name(), input })}'`,
+                '',
+                '通用选项: --browser --connector --local --cdp --server --timeout --compact --output',
+                '插件选项: --verbose; -h, --help; -v, --version',
+                'JSON input 直接传给 handler；业务字段与校验规则见对应 skill。',
+            ].join('\n');
+        },
+        async run(positionals, payload) {
+            if (payload !== undefined && positionals.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
+                ? { ...envelope.input }
+                : Object.fromEntries(command.registeredArguments
+                    .map((argument, index) => [
+                    argument.name(),
+                    argument.variadic ? positionals.slice(index + 1) : positionals[index + 1],
+                ])
+                    .filter(([, value]) => value !== undefined));
+            if (!envelope &&
+                !command.registeredArguments.some(argument => argument.variadic) &&
+                positionals.length - 1 > command.registeredArguments.length) {
+                throw new PluginError('PLUGIN_INVALID_INPUT', '位置参数过多');
+            }
+            for (const argument of command.registeredArguments) {
+                const value = Object.hasOwn(input, argument.name()) ? input[argument.name()] : undefined;
+                if (argument.required &&
+                    (value === undefined ||
+                        value === null ||
+                        value === '' ||
+                        (Array.isArray(value) && value.length === 0))) {
+                    throw new PluginError('PLUGIN_INVALID_INPUT', `缺少必填参数: ${argument.name()}`);
+                }
+                if (argument.variadic && value !== undefined && !Array.isArray(value)) {
+                    throw new PluginError('PLUGIN_INVALID_INPUT', `${argument.name()} 必须为数组`);
+                }
+            }
+            executing = true;
+            try {
+                return await handler(input);
+            }
+            finally {
+                executing = false;
+            }
+        },
+    };
+}

package/dist/pluginRegistry.d.ts

@@ -0,0 +1,11 @@
+export declare class PluginError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function pluginDirectory(): string;
+export declare function assertPluginName(name: string): void;
+export declare function resolvePluginEntry(target: string): string;
+export declare function registerPlugin(name: string, target: string): string;
+export declare function unregisterPlugin(name: string): boolean;
+export declare function findPluginEntry(name: string): string | undefined;
+export declare function listPluginNames(): string[];

package/dist/pluginRegistry.js

@@ -0,0 +1,108 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { homedir } from 'node:os';
+import { isAbsolute, join, resolve } from 'node:path';
+import { COMMAND_MAP } from './commands.js';
+const RESERVED_NAMES = new Set([
+    'check',
+    'help',
+    'connector_list',
+    'capture_checkpoint',
+    'plugin',
+    'plugins',
+]);
+export class PluginError extends Error {
+    code;
+    constructor(code, message) {
+        super(`${code}: ${message}`);
+        this.code = code;
+    }
+}
+export function pluginDirectory() {
+    return resolve(process.env.MEARL_PLUGIN_DIR || join(homedir(), '.mearl', 'plugins'));
+}
+export function assertPluginName(name) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name) || RESERVED_NAMES.has(name) || COMMAND_MAP.has(name)) {
+        throw new PluginError('PLUGIN_INVALID_NAME', `不可用的插件名称: ${name}`);
+    }
+}
+export function resolvePluginEntry(target) {
+    const absolute = resolve(target);
+    try {
+        const entry = statSync(absolute).isDirectory()
+            ? join(absolute, 'scripts', 'main.mjs')
+            : absolute;
+        if (!statSync(entry).isFile())
+            throw new Error('not a file');
+        return entry;
+    }
+    catch {
+        throw new PluginError('PLUGIN_ENTRY_MISSING', `入口不存在: ${absolute}（目录默认使用 scripts/main.mjs）`);
+    }
+}
+export function registerPlugin(name, target) {
+    assertPluginName(name);
+    const entry = resolvePluginEntry(target);
+    const directory = pluginDirectory();
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const file = join(directory, `${name}.json`);
+    // 每个插件独立保存，多个名称并发注册不会覆盖彼此；同名注册原子替换绑定。
+    const temporary = `${file}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, `${JSON.stringify({ entry })}\n`, { mode: 0o600, flag: 'wx' });
+        renameSync(temporary, file);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+    return entry;
+}
+export function unregisterPlugin(name) {
+    assertPluginName(name);
+    const file = join(pluginDirectory(), `${name}.json`);
+    try {
+        rmSync(file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw new PluginError('PLUGIN_UNINSTALL_FAILED', `无法移除插件注册: ${file}`);
+    }
+}
+export function findPluginEntry(name) {
+    if (!/^[a-z][a-z0-9-]*$/.test(name))
+        return undefined;
+    const file = join(pluginDirectory(), `${name}.json`);
+    let content;
+    try {
+        content = readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return undefined;
+        throw new PluginError('PLUGIN_REGISTRY_INVALID', `无法读取插件记录: ${file}`);
+    }
+    try {
+        const record = JSON.parse(content);
+        if (typeof record?.entry !== 'string' || !isAbsolute(record.entry))
+            throw new Error('invalid entry');
+        return record.entry;
+    }
+    catch {
+        throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);
+    }
+}
+export function listPluginNames() {
+    try {
+        return readdirSync(pluginDirectory())
+            .filter(file => /^[a-z][a-z0-9-]*\.json$/.test(file))
+            .map(file => file.slice(0, -5))
+            .sort();
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return [];
+        throw new PluginError('PLUGIN_REGISTRY_INVALID', '无法读取插件目录');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.11.0",
+  "version": "2.12.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -29,6 +29,10 @@
     "./cli": {
       "types": "./dist/cli.d.ts",
       "import": "./dist/cli.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
     }
   },
   "bin": {
@@ -55,7 +59,7 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.11.0"
+    "@mearl/cloud-types": "2.12.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",