@mearl/client 2.15.0 → 2.15.2

package/README.md

@@ -134,6 +134,7 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 
 ```bash
 npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
+npx @mearl/setup plugin install trip/mearl --skill buc-request --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"
@@ -144,7 +145,7 @@ mearl yuque --version
 
 目录默认使用 `scripts/main.mjs`。入口默认导出 `register(app)`，可导出简短的 `description`
 显示在 `mearl` 插件列表中，并通过 `app.command(signature, handler, description?)`
-注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。CLI 默认只输出最终结果，传入
+注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
 `--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
 自动注册默认以 skill 安装目录名作为命令名，也可在入口导出 `name` 指定短名称。
 setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。
@@ -168,7 +169,7 @@ const result = await invokePlugin(
 );
 ```
 
-MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 都只解析本机 registry 中已注册的名称，不接受任意入口路径。
+MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command` 和 `input`，不会把插件子命令动态扩展成 MCP 工具。SDK 与 MCP 不接受任意入口路径；调用官方目录中尚未注册的插件时，会通过匹配当前 client 版本的 setup 自动安装并重试一次。未知名称仍返回 `PLUGIN_NOT_REGISTERED`。
 
 注册记录在 `~/.mearl/plugins/<name>.json`，保存入口路径和可选的简短描述；skill 业务代码原地更新直接生效，换路径或更新描述后重新注册。
 `plugin uninstall <name>` 会对 `~/.agents/skills` 中的全局 Skill 调用 `ali-skills remove --global --yes`，
@@ -178,16 +179,10 @@ MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command
 卸载清理命令。其他错误按实际原因处理。
 编写规范见 [Mearl Skill Creator 的 Skill 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
 
-插件通过 `app.buc.request({ app, auth, url, ... })` 调用需要 BUC 身份的内部 HTTP 接口。`auth` 支持
-`id-token`（默认）、`ticket-header` 和兼容旧服务的 `ticket-query`。Mearl 按请求创建一次性凭据并注入
-`Authorization` + `DPoP`、`SSO-TICKET` Header 或 `SSO_TICKET` Query，只允许访问 HTTPS
-`alibaba-inc.com` 域名；凭据不会返回给插件，也不会复用到下一次请求，调用方也不能自行传入这些认证字段。
-`app.buc.whoami()` 返回当前身份的
-`empId` 和姓名，并在 Agent 身份场景返回 `agentId`；仅在确实需要部门等详细字段时使用
-`app.buc.profile()`，它通过一次性 `alineiwai` Ticket
-建立内存会话、校验资料属于当前员工，并只返回白名单字段，Ticket 与 Cookie 均不暴露给插件。
-缺少 BUC CLI 时 Mearl 会从官方 CLI Hub 安装后重试。这些方法与 `app.invoke` 一样，只能在插件 handler
-执行期间调用。BUC 请求始终在运行 CLI、SDK 或 MCP Server 的机器上执行，不会随浏览器或 connector 转发到远端浏览器宿主。
+需要 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 转发。
 
 ## 支持的操作
 

package/dist/cli.js

@@ -8,7 +8,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, findPluginRegistration, listPluginNames, loadRegisteredPlugin, PluginError, } from './plugin.js';
+import { findPluginEntry, findPluginRegistration, findOfficialPlugin, listPluginNames, listOfficialPluginNames, loadRegisteredPlugin, PluginError, } from './plugin.js';
 import { getCloudServerConfigPath, loadCloudServerConfig } from './unifiedConfig.js';
 const TOP_LEVEL_COMMAND_NAME_WIDTH = 22;
 const CATEGORIES = [
@@ -59,7 +59,16 @@ const BUILTIN_COMMANDS = [
         examples: ['check'],
     },
 ];
-const SUGGESTABLE_COMMANDS = [...COMMANDS, ...BUILTIN_COMMANDS];
+const OFFICIAL_PLUGIN_COMMANDS = listOfficialPluginNames().map(name => ({
+    name,
+    description: findOfficialPlugin(name).description,
+    examples: [name],
+}));
+const SUGGESTABLE_COMMANDS = [
+    ...COMMANDS,
+    ...BUILTIN_COMMANDS,
+    ...OFFICIAL_PLUGIN_COMMANDS,
+];
 const ADVANCED_BUILTIN_COMMANDS = new Set(['connector_list']);
 function printUsage(commandName, version) {
     const lines = [
@@ -113,6 +122,14 @@ function printUsage(commandName, version) {
             });
             lines.push('', '已注册插件：', ...entries);
         }
+        const installed = new Set(plugins);
+        const available = listOfficialPluginNames().filter(name => !installed.has(name));
+        if (available.length) {
+            lines.push('', '官方插件（首次调用自动安装）：', ...available.map(name => {
+                const description = findOfficialPlugin(name).description;
+                return `  ${name.padEnd(TOP_LEVEL_COMMAND_NAME_WIDTH)}${description}`;
+            }));
+        }
     }
     catch (error) {
         lines.push('', error instanceof Error ? error.message : String(error));
@@ -519,7 +536,7 @@ export async function runMearlCli(args, options = {}) {
         !COMMAND_MAP.has(args[0])) {
         try {
             const entry = findPluginEntry(args[0]);
-            if (entry)
+            if (entry || findOfficialPlugin(args[0]))
                 return await runPluginCli(args, commandName);
         }
         catch (error) {

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,7 +1,7 @@
-import { type BucApi } from './buc.js';
+import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
 import type { UnifiedInvokeOptions } from './unified.js';
-export { type BucApi, type BucIdentity, type BucProfile, type BucRequestAuth, type BucRequestFormValue, type BucRequestParams, type BucRequestResult, } from './buc.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;
@@ -11,21 +11,18 @@ export interface PluginInvokeOptions extends UnifiedInvokeOptions {
     onProgress?: (message: string) => void;
 }
 export interface PluginExecutionContext {
-    buc?: BucApi;
+    ensurePlugin?: OfficialPluginInstaller;
     invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
 }
 export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
-    readonly buc: BucApi;
     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'> & {
-    buc?: BucApi;
-}, pluginName?: string): Promise<{
+export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
     name: string | undefined;
     description: string | undefined;
     version: string | undefined;

package/dist/plugin.js

@@ -2,9 +2,12 @@ import { readFileSync, statSync } from 'node:fs';
 import { dirname, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { Command } from 'commander';
-import { buc } from './buc.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');
@@ -19,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 [
@@ -49,23 +55,6 @@ export async function loadPlugin(entry, context, pluginName) {
     let description;
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
-        buc: Object.freeze({
-            request(params) {
-                if (!executing)
-                    throw new Error('app.buc.request 只能在命令执行期间调用');
-                return (context.buc ?? buc).request(params);
-            },
-            whoami() {
-                if (!executing)
-                    throw new Error('app.buc.whoami 只能在命令执行期间调用');
-                return (context.buc ?? buc).whoami();
-            },
-            profile() {
-                if (!executing)
-                    throw new Error('app.buc.profile 只能在命令执行期间调用');
-                return (context.buc ?? buc).profile();
-            },
-        }),
         command(signature, handler, description = '') {
             if (!registering)
                 throw new Error('命令只能在入口注册阶段声明');
@@ -194,21 +183,46 @@ export async function loadPlugin(entry, context, pluginName) {
         },
     };
 }
-export async function loadRegisteredPlugin(name, context, options = {}) {
-    const registration = findPluginRegistration(name);
+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,
-        ...(context.buc ? { buc: context.buc } : {}),
         progress: onProgress ?? (() => undefined),
         async invoke(action, payload, overrides) {
-            const result = await context.invoke(action, payload, {
+            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`);
             }
@@ -216,7 +230,13 @@ export async function loadRegisteredPlugin(name, context, options = {}) {
         },
     }, name);
 }
-export async function invokeRegisteredPlugin(name, invocation, context, options = {}) {
-    const plugin = await loadRegisteredPlugin(name, context, options);
+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/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 {};