@mearl/client 2.14.0 → 2.15.1

package/dist/officialPluginCatalog.d.ts

@@ -0,0 +1,79 @@
+export declare const OFFICIAL_PLUGIN_MANAGER = "@mearl/setup:official";
+export interface OfficialPluginDefinition {
+    description: string;
+    installArgs: readonly string[];
+    setup?: 'alibaba';
+    skill: string;
+}
+export declare const OFFICIAL_PLUGINS: {
+    readonly buc: {
+        readonly description: "使用 BUC 身份请求内部服务";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "buc-request", "--yes"];
+        readonly setup: "alibaba";
+        readonly skill: "buc-request";
+    };
+    readonly tdbank: {
+        readonly description: "查询、借用和切换 TDBank 测试账号";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "tdbank-account", "--yes"];
+        readonly setup: "alibaba";
+        readonly skill: "tdbank-account";
+    };
+    readonly agentforce: {
+        readonly description: "管理 AgentForce 数字员工";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "agentforce-manage", "--yes"];
+        readonly skill: "agentforce-manage";
+    };
+    readonly aliway: {
+        readonly description: "读取和管理 Aliway 内容";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "aliway-doc-fetch", "--yes"];
+        readonly skill: "aliway-doc-fetch";
+    };
+    readonly ata: {
+        readonly description: "读取和管理 ATA 内容";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "ata-doc-fetch", "--yes"];
+        readonly skill: "ata-doc-fetch";
+    };
+    readonly code: {
+        readonly description: "读取 code.alibaba-inc.com 代码";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "code-file-fetch", "--yes"];
+        readonly skill: "code-file-fetch";
+    };
+    readonly dingtalk: {
+        readonly description: "读取钉钉文档与表格";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "dingtalk-doc-fetch", "--yes"];
+        readonly skill: "dingtalk-doc-fetch";
+    };
+    readonly figma: {
+        readonly description: "提取 Figma 设计数据与素材";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "figma-design-fetch", "--yes"];
+        readonly skill: "figma-design-fetch";
+    };
+    readonly flyeye: {
+        readonly description: "查询 FlyEye 分布式链路日志";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "flyeye-trace-query", "--yes"];
+        readonly skill: "flyeye-trace-query";
+    };
+    readonly jarvis: {
+        readonly description: "查询和处理 Jarvis 机票退改";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "jarvis-order-operations", "--yes"];
+        readonly skill: "jarvis-order-operations";
+    };
+    readonly loginsight: {
+        readonly description: "分析 LogInsight 全链路日志";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "loginsight-analyze", "--yes"];
+        readonly skill: "loginsight-analyze";
+    };
+    readonly tps: {
+        readonly description: "上传 TPS 图片并获取 CDN 地址";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "tps-image-upload", "--yes"];
+        readonly skill: "tps-image-upload";
+    };
+    readonly yuque: {
+        readonly description: "读取和管理阿里语雀文档";
+        readonly installArgs: readonly ["trip/mearl", "--skill", "yuque-doc-fetch", "--yes"];
+        readonly skill: "yuque-doc-fetch";
+    };
+};
+export type OfficialPluginName = keyof typeof OFFICIAL_PLUGINS;
+export declare function findOfficialPlugin(name: string): OfficialPluginDefinition | undefined;
+export declare function listOfficialPluginNames(setup?: OfficialPluginDefinition['setup']): string[];

package/dist/officialPluginCatalog.js

@@ -0,0 +1,80 @@
+export const OFFICIAL_PLUGIN_MANAGER = '@mearl/setup:official';
+export const OFFICIAL_PLUGINS = {
+    buc: {
+        description: '使用 BUC 身份请求内部服务',
+        installArgs: ['trip/mearl', '--skill', 'buc-request', '--yes'],
+        setup: 'alibaba',
+        skill: 'buc-request',
+    },
+    tdbank: {
+        description: '查询、借用和切换 TDBank 测试账号',
+        installArgs: ['trip/mearl', '--skill', 'tdbank-account', '--yes'],
+        setup: 'alibaba',
+        skill: 'tdbank-account',
+    },
+    agentforce: {
+        description: '管理 AgentForce 数字员工',
+        installArgs: ['trip/mearl', '--skill', 'agentforce-manage', '--yes'],
+        skill: 'agentforce-manage',
+    },
+    aliway: {
+        description: '读取和管理 Aliway 内容',
+        installArgs: ['trip/mearl', '--skill', 'aliway-doc-fetch', '--yes'],
+        skill: 'aliway-doc-fetch',
+    },
+    ata: {
+        description: '读取和管理 ATA 内容',
+        installArgs: ['trip/mearl', '--skill', 'ata-doc-fetch', '--yes'],
+        skill: 'ata-doc-fetch',
+    },
+    code: {
+        description: '读取 code.alibaba-inc.com 代码',
+        installArgs: ['trip/mearl', '--skill', 'code-file-fetch', '--yes'],
+        skill: 'code-file-fetch',
+    },
+    dingtalk: {
+        description: '读取钉钉文档与表格',
+        installArgs: ['trip/mearl', '--skill', 'dingtalk-doc-fetch', '--yes'],
+        skill: 'dingtalk-doc-fetch',
+    },
+    figma: {
+        description: '提取 Figma 设计数据与素材',
+        installArgs: ['trip/mearl', '--skill', 'figma-design-fetch', '--yes'],
+        skill: 'figma-design-fetch',
+    },
+    flyeye: {
+        description: '查询 FlyEye 分布式链路日志',
+        installArgs: ['trip/mearl', '--skill', 'flyeye-trace-query', '--yes'],
+        skill: 'flyeye-trace-query',
+    },
+    jarvis: {
+        description: '查询和处理 Jarvis 机票退改',
+        installArgs: ['trip/mearl', '--skill', 'jarvis-order-operations', '--yes'],
+        skill: 'jarvis-order-operations',
+    },
+    loginsight: {
+        description: '分析 LogInsight 全链路日志',
+        installArgs: ['trip/mearl', '--skill', 'loginsight-analyze', '--yes'],
+        skill: 'loginsight-analyze',
+    },
+    tps: {
+        description: '上传 TPS 图片并获取 CDN 地址',
+        installArgs: ['trip/mearl', '--skill', 'tps-image-upload', '--yes'],
+        skill: 'tps-image-upload',
+    },
+    yuque: {
+        description: '读取和管理阿里语雀文档',
+        installArgs: ['trip/mearl', '--skill', 'yuque-doc-fetch', '--yes'],
+        skill: 'yuque-doc-fetch',
+    },
+};
+export function findOfficialPlugin(name) {
+    return Object.hasOwn(OFFICIAL_PLUGINS, name)
+        ? OFFICIAL_PLUGINS[name]
+        : undefined;
+}
+export function listOfficialPluginNames(setup) {
+    return Object.entries(OFFICIAL_PLUGINS)
+        .filter(([, definition]) => setup === undefined || ('setup' in definition && definition.setup === setup))
+        .map(([name]) => name);
+}

package/dist/officialPluginInstaller.d.ts

@@ -0,0 +1,3 @@
+export type OfficialPluginInstallProgress = (message: string) => void;
+export type OfficialPluginInstaller = (name: string, progress?: OfficialPluginInstallProgress) => Promise<void>;
+export declare const ensureOfficialPluginRegistered: OfficialPluginInstaller;

package/dist/officialPluginInstaller.js

@@ -0,0 +1,130 @@
+import { closeSync, mkdirSync, openSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { findOfficialPlugin } from './officialPluginCatalog.js';
+import { findPluginRegistration, pluginDirectory } from './pluginRegistry.js';
+const require = createRequire(import.meta.url);
+const CLIENT_VERSION = require('../package.json').version;
+const INSTALL_TIMEOUT_MS = 180_000;
+const INSTALL_LOCK_STALE_MS = 5 * 60_000;
+const MAX_INSTALL_OUTPUT = 1024 * 1024;
+const activeInstallations = new Map();
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}
+function installLockPath(name) {
+    return join(pluginDirectory(), `.official-${name}.install.lock`);
+}
+async function acquireInstallLock(name) {
+    const directory = pluginDirectory();
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const lockPath = installLockPath(name);
+    const deadline = Date.now() + INSTALL_TIMEOUT_MS;
+    while (true) {
+        let descriptor;
+        try {
+            descriptor = openSync(lockPath, 'wx', 0o600);
+            writeFileSync(descriptor, `${process.pid}\n`);
+            closeSync(descriptor);
+            return () => rmSync(lockPath, { force: true });
+        }
+        catch (error) {
+            if (descriptor !== undefined)
+                closeSync(descriptor);
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+        if (findPluginRegistration(name))
+            return () => undefined;
+        try {
+            if (Date.now() - statSync(lockPath).mtimeMs > INSTALL_LOCK_STALE_MS) {
+                rmSync(lockPath, { force: true });
+                continue;
+            }
+        }
+        catch (error) {
+            if (error.code === 'ENOENT')
+                continue;
+            throw error;
+        }
+        if (Date.now() >= deadline) {
+            throw new Error(`等待安装官方插件 ${name} 超时`);
+        }
+        await delay(250);
+    }
+}
+function appendOutput(current, chunk) {
+    if (current.length >= MAX_INSTALL_OUTPUT)
+        return current;
+    return (current + chunk.toString('utf8')).slice(0, MAX_INSTALL_OUTPUT);
+}
+function installWithSetup(name) {
+    return new Promise((resolve, reject) => {
+        const command = process.platform === 'win32' ? 'npx.cmd' : 'npx';
+        const child = spawn(command, ['-y', `@mearl/setup@${CLIENT_VERSION}`, 'plugin', 'ensure', name], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        let stdout = '';
+        let stderr = '';
+        let settled = false;
+        const finish = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error)
+                reject(error);
+            else
+                resolve();
+        };
+        const timer = setTimeout(() => {
+            child.kill('SIGTERM');
+            finish(new Error(`安装官方插件 ${name} 超时`));
+        }, INSTALL_TIMEOUT_MS);
+        child.stdout.on('data', chunk => (stdout = appendOutput(stdout, chunk)));
+        child.stderr.on('data', chunk => (stderr = appendOutput(stderr, chunk)));
+        child.once('error', error => finish(error));
+        child.once('exit', code => {
+            if (code === 0) {
+                finish();
+                return;
+            }
+            const detail = (stderr || stdout)
+                .replace(/[\r\n]+/g, ' ')
+                .trim()
+                .slice(-1000);
+            finish(new Error(detail
+                ? `安装官方插件 ${name} 失败 (exit ${code}): ${detail}`
+                : `安装官方插件 ${name} 失败 (exit ${code})`));
+        });
+    });
+}
+async function installOfficialPlugin(name, progress) {
+    if (findPluginRegistration(name))
+        return;
+    if (!findOfficialPlugin(name))
+        throw new Error(`未知官方插件: ${name}`);
+    const releaseLock = await acquireInstallLock(name);
+    try {
+        if (findPluginRegistration(name))
+            return;
+        progress?.(`正在安装官方插件 ${name}...`);
+        await installWithSetup(name);
+        if (!findPluginRegistration(name)) {
+            throw new Error(`官方插件 ${name} 安装完成后仍未注册`);
+        }
+        progress?.(`官方插件 ${name} 已安装。`);
+    }
+    finally {
+        releaseLock();
+    }
+}
+export const ensureOfficialPluginRegistered = (name, progress) => {
+    const active = activeInstallations.get(name);
+    if (active)
+        return active;
+    const installation = installOfficialPlugin(name, progress).finally(() => {
+        activeInstallations.delete(name);
+    });
+    activeInstallations.set(name, installation);
+    return installation;
+};

package/dist/plugin.d.ts

@@ -1,6 +1,19 @@
+import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
 import type { UnifiedInvokeOptions } from './unified.js';
-export { assertPluginName, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, } from './pluginRegistry.js';
+export { assertPluginName, 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 {
+    command: string;
+    input: Record<string, any>;
+}
+export interface PluginInvokeOptions extends UnifiedInvokeOptions {
+    onProgress?: (message: string) => void;
+}
+export interface PluginExecutionContext {
+    ensurePlugin?: OfficialPluginInstaller;
+    invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
+}
 export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
     command(signature: string, handler: PluginHandler, description?: string): void;
@@ -16,3 +29,11 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invo
     help(namespace: string, name?: string): string;
     run(positionals: string[], payload?: 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>;
+}>;
+export declare function invokeRegisteredPlugin(name: string, invocation: PluginInvocation, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<unknown>;

package/dist/plugin.js

@@ -2,8 +2,12 @@ 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';
+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';
+export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, } from './officialPluginCatalog.js';
 function readPluginVersion(entry) {
     try {
         const content = readFileSync(resolve(dirname(entry), '..', 'SKILL.md'), 'utf8');
@@ -18,6 +22,9 @@ function readPluginVersion(entry) {
 function isObject(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+function isPluginInvocation(value) {
+    return isObject(value) && typeof value.command === 'string' && isObject(value.input);
+}
 function missingPluginEntryMessage(entry, pluginName) {
     const name = pluginName ?? '<name>';
     return [
@@ -31,9 +38,12 @@ function missingPluginEntryMessage(entry, pluginName) {
 }
 /** 注册和执行共享一个 app；仅 handler 执行期间开放浏览器调用。 */
 export async function loadPlugin(entry, context, pluginName) {
+    let entryVersion;
     try {
-        if (!statSync(entry).isFile())
+        const stat = statSync(entry);
+        if (!stat.isFile())
             throw new Error('not a file');
+        entryVersion = `${stat.mtimeMs}-${stat.size}`;
     }
     catch {
         throw new PluginError('PLUGIN_ENTRY_MISSING', missingPluginEntryMessage(entry, pluginName));
@@ -78,7 +88,9 @@ export async function loadPlugin(entry, context, pluginName) {
         },
     });
     try {
-        const module = await import(pathToFileURL(entry).href);
+        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;
@@ -171,3 +183,60 @@ export async function loadPlugin(entry, context, pluginName) {
         },
     };
 }
+async function loadRegisteredPluginWithState(name, context, options = {}, state = { stack: [] }) {
+    if (state.stack.includes(name)) {
+        throw new PluginError('PLUGIN_INVOCATION_CYCLE', `插件调用形成循环: ${[...state.stack, name].join(' -> ')}`);
+    }
+    let registration = findPluginRegistration(name);
+    if (!registration && findOfficialPlugin(name)) {
+        await (context.ensurePlugin ?? ensureOfficialPluginRegistered)(name, options.onProgress);
+        registration = findPluginRegistration(name);
+    }
+    if (!registration) {
+        throw new PluginError('PLUGIN_NOT_REGISTERED', `插件未注册: ${name}`);
+    }
+    const { onProgress, ...invokeOptions } = options;
+    const childState = { stack: [...state.stack, name] };
+    return loadPlugin(registration.entry, {
+        options: invokeOptions,
+        progress: onProgress ?? (() => undefined),
+        async invoke(action, payload, overrides) {
+            const nestedOptions = {
+                ...invokeOptions,
+                ...overrides,
+            };
+            if (COMMAND_MAP.has(action) || action === 'connector_list') {
+                const result = await context.invoke(action, payload, nestedOptions);
+                if (result?.action?.success === false) {
+                    throw new Error(result.action.error || `${action} failed`);
+                }
+                return result;
+            }
+            const pluginInvocation = isPluginInvocation(payload);
+            if (findPluginRegistration(action) || findOfficialPlugin(action) || pluginInvocation) {
+                if (!pluginInvocation) {
+                    throw new PluginError('PLUGIN_INVALID_INPUT', `调用插件 ${action} 需要 {"command":"...","input":{...}}`);
+                }
+                return invokeRegisteredPluginWithState(action, payload, context, {
+                    ...nestedOptions,
+                    ...(onProgress ? { onProgress } : {}),
+                }, childState);
+            }
+            const result = await context.invoke(action, payload, nestedOptions);
+            if (result?.action?.success === false) {
+                throw new Error(result.action.error || `${action} failed`);
+            }
+            return result;
+        },
+    }, name);
+}
+export function loadRegisteredPlugin(name, context, options = {}) {
+    return loadRegisteredPluginWithState(name, context, options);
+}
+async function invokeRegisteredPluginWithState(name, invocation, context, options = {}, state = { stack: [] }) {
+    const plugin = await loadRegisteredPluginWithState(name, context, options, state);
+    return plugin.run([], invocation);
+}
+export function invokeRegisteredPlugin(name, invocation, context, options = {}) {
+    return invokeRegisteredPluginWithState(name, invocation, context, options);
+}

package/dist/pluginRegistry.d.ts

@@ -5,11 +5,15 @@ export declare class PluginError extends Error {
 export interface PluginRegistration {
     entry: string;
     description?: string;
+    managedBy?: string;
+}
+export interface PluginRegistrationOptions {
+    managedBy?: 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, description?: string): string;
+export declare function registerPlugin(name: string, target: string, description?: string, options?: PluginRegistrationOptions): string;
 export declare function unregisterPlugin(name: string): boolean;
 export declare function findPluginRegistration(name: string): PluginRegistration | undefined;
 export declare function findPluginEntry(name: string): string | undefined;

package/dist/pluginRegistry.js

@@ -40,7 +40,7 @@ export function resolvePluginEntry(target) {
         throw new PluginError('PLUGIN_ENTRY_MISSING', `入口不存在: ${absolute}（目录默认使用 scripts/main.mjs）`);
     }
 }
-export function registerPlugin(name, target, description) {
+export function registerPlugin(name, target, description, options = {}) {
     assertPluginName(name);
     const entry = resolvePluginEntry(target);
     const directory = pluginDirectory();
@@ -49,7 +49,12 @@ export function registerPlugin(name, target, description) {
     // 每个插件独立保存，多个名称并发注册不会覆盖彼此；同名注册原子替换绑定。
     const temporary = `${file}.${randomUUID()}.tmp`;
     const summary = description?.trim();
-    const record = { entry, ...(summary ? { description: summary } : {}) };
+    const managedBy = options.managedBy?.trim();
+    const record = {
+        entry,
+        ...(summary ? { description: summary } : {}),
+        ...(managedBy ? { managedBy } : {}),
+    };
     try {
         writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600, flag: 'wx' });
         renameSync(temporary, file);
@@ -92,7 +97,14 @@ export function findPluginRegistration(name) {
         const description = typeof record.description === 'string' && record.description.trim()
             ? record.description.trim()
             : undefined;
-        return { entry: record.entry, ...(description ? { description } : {}) };
+        const managedBy = typeof record.managedBy === 'string' && record.managedBy.trim()
+            ? record.managedBy.trim()
+            : undefined;
+        return {
+            entry: record.entry,
+            ...(description ? { description } : {}),
+            ...(managedBy ? { managedBy } : {}),
+        };
     }
     catch {
         throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);

package/dist/socket.d.ts

@@ -4,7 +4,8 @@
  * 通过 Unix Domain Socket (macOS/Linux) 或 Named Pipe (Windows) 与 native host 进程通信。
  * 每次调用新建连接，收到响应后关闭，简单可靠。
  *
- * 当 Socket 文件不存在（ENOENT）时，自动尝试拉起 native host，稍后重试连接。
+ * 当 Socket 不存在，或 legacy Socket 是无人监听的残留文件时，
+ * 自动尝试拉起 native host，稍后重试连接。
  */
 export declare const CLIENT_VERSION: string;
 /**
@@ -34,7 +35,7 @@ export declare function decorateBrowserListResult(result: Record<string, any>):
  *
  * 目标解析优先级：显式 options.browser → setDefaultBrowser → 环境变量
  * MEARL_BROWSER → 自动（注册表中最近聚焦的浏览器）。注册表为空时回退到
- * legacy well-known socket，并在 socket 不存在（ENOENT）时自动拉起 native host。
+ * legacy well-known socket，并在 socket 不存在或已残留时自动拉起 native host。
  */
 export declare function invoke(action: string, data?: Record<string, any>, options?: InvokeOptions): Promise<any>;
 export {};