@mearl/setup 2.18.0 → 2.19.0

package/README.md

@@ -7,7 +7,7 @@ npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp]
 npx @mearl/setup update [--local] [--cloud|--qoder-cloud] [--mcp]
 npx @mearl/setup uninstall [--local] [--cloud|--qoder-cloud] [--mcp] [--full]
 npx @mearl/setup extension [--full] [--force]
-npx @mearl/setup plugin <name> <path>
+npx @mearl/setup plugin [name] <path>
 npx @mearl/setup plugin install <ali-skills add 参数...>
 npx @mearl/setup plugin uninstall <name>
 npx @mearl/setup provider <install|update|uninstall> <package|id>
@@ -53,16 +53,16 @@ Mearl client 内置 `buc` 与 `tdbank` 的安装来源。CLI、SDK、MCP 或另
 已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
 
 ```bash
-npx @mearl/setup plugin yuque /absolute/path/to/yuque-doc-fetch
+npx @mearl/setup plugin /absolute/path/to/yuque-doc-fetch
 npx @mearl/setup plugin custom ./skills/custom/entry.mjs
 ```
 
-path 接受目录或具体文件；目录默认读取 `scripts/main.mjs` 或 `scripts/main.py`，相对路径基于调用工作目录解析。Python 插件要求 `python3 >= 3.9`，可通过 `MEARL_PYTHON` 指定解释器路径；setup 只验证入口可加载，不安装 Python，也不执行 `pip install`。
+path 接受目录或具体文件；目录默认读取 `scripts/main.mjs` 或 `scripts/main.py`，相对路径基于调用工作目录解析。插件名优先使用显式 name，其次读取入口的 `name` metadata，最后回退到 Skill 目录名；常规注册只传 path，显式 name 仅用于覆盖或兼容旧入口。Python 插件要求 `python3 >= 3.9`，可通过 `MEARL_PYTHON` 指定解释器路径；setup 只验证入口可加载，不安装 Python，也不执行 `pip install`。
 命令检查入口注册函数，然后保存绝对入口路径，同名注册更新绑定。
 两种注册流程都会检查本机 `@mearl/client` 和 `@mearl/native-host`：缺失或低于当前 setup 版本时，
 复用已有包管理器安装 setup 的对应版本，更新后再次验证；更高版本保持不动。
 native-host 会幂等初始化 Skills 模式。基础环境补齐或初始化失败时保留已安装的 skill，并停止注册。
-注册后可在任意目录运行 `mearl <name> --help`，也可通过 `@mearl/client` 的 `invokePlugin` 或 MCP 的 `mearl_plugin` 调用。已注册插件的日常调用不执行安装或版本检查；只有缺失的 `buc` 或 `tdbank` 会触发一次按需安装。
+注册后可在任意目录运行 `mearl <name> --help`，也可通过 `@mearl/client` 的 `invokePlugin` 或 MCP 的 `plugin_invoke` 工具调用。已注册插件的日常调用不执行安装或版本检查；只有缺失的 `buc` 或 `tdbank` 会触发一次按需安装。
 
 不再需要插件时执行：
 
@@ -148,9 +148,11 @@ npx @mearl/setup extension --full
 
 首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
 Chrome 尚未开放 CDP，交互命令会提示打开
-`chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。无 TTY
-环境使用 `npx @mearl/setup extension --yes`；它只尝试一次。无法确认 setup 管理来源且
-CDP 不可用时不会下载或修改插件目录，打开 CDP 后重新执行同一命令即可。
+`chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。面向人的
+安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup extension --yes`；它只尝试
+一次，CDP 不可用时立即中断。无法确认 setup 管理来源且 CDP 不可用时不会下载或修改插件
+目录，打开 CDP 后重新执行同一命令即可。Chrome 版本过低、缺少扩展安装所需的 CDP 方法时，
+命令会中断并提示升级 Chrome。
 
 该命令每次都读取下载页上的最新插件版本，不要求与 setup、CLI 或 Native Host 同版本。
 CDP 来源检查和 `Extensions.loadUnpacked` 复用同一条连接，避免一次安装重复请求授权。

package/dist/browserExtension.d.ts

@@ -54,6 +54,7 @@ export declare class BrowserExtensionConflictError extends Error {
     readonly installed: InstalledBrowserExtension;
     constructor(installed: InstalledBrowserExtension);
 }
+export declare function isUnsupportedCdpMethodError(message: string): boolean;
 export declare function resolveChromeUserDataDirectory(platform?: NodeJS.Platform, home?: string, env?: NodeJS.ProcessEnv): string;
 export declare function resolveMearlExtensionDirectory(home?: string): string;
 export declare function findLatestExtensionVersion(html: string): string | null;

package/dist/browserExtension.js

@@ -23,6 +23,9 @@ export class BrowserExtensionConflictError extends Error {
         this.name = 'BrowserExtensionConflictError';
     }
 }
+export function isUnsupportedCdpMethodError(message) {
+    return /Method not (?:available|found)|wasn't found|unknown method/i.test(message);
+}
 export function resolveChromeUserDataDirectory(platform = process.platform, home = os.homedir(), env = process.env) {
     if (platform === 'darwin') {
         return path.join(home, 'Library', 'Application Support', 'Google', 'Chrome');
@@ -522,7 +525,7 @@ export async function installMearlBrowserExtension(options = {}, dependencies =
                     throw error;
                 const message = error instanceof Error ? error.message : String(error);
                 lastFailure = message;
-                if (waitForCdpMs === 0 || /Method not (?:available|found)|wasn't found/i.test(message)) {
+                if (waitForCdpMs === 0 || isUnsupportedCdpMethodError(message)) {
                     break;
                 }
                 if (lastNoticeAt === 0) {

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from 'node:module';
 import { Command, CommanderError } from 'commander';
-import { installMearlBrowserExtension } from './browserExtension.js';
+import { installMearlBrowserExtension, isUnsupportedCdpMethodError } from './browserExtension.js';
 import { runMearlLifecycle } from './lifecycle.js';
 import { isMearlReleaseLine } from './version.js';
 import { ensureOfficialPlugin, installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
@@ -53,6 +53,20 @@ export function parseSetupArgs(argv) {
         }
         return { ...baseParsedArgs(), operation: 'plugin', pluginUninstallName: argv[2] };
     }
+    if (argv[0] === 'plugin') {
+        if (argv.length === 2 && argv[1]) {
+            return { ...baseParsedArgs(), operation: 'plugin', pluginPath: argv[1] };
+        }
+        if (argv.length === 3 && argv[1] && argv[2]) {
+            return {
+                ...baseParsedArgs(),
+                operation: 'plugin',
+                pluginName: argv[1],
+                pluginPath: argv[2],
+            };
+        }
+        throw new Error('plugin requires <path> or <name> <path>');
+    }
     let parsed;
     const program = new Command()
         .name('mearl-setup')
@@ -109,14 +123,6 @@ export function parseSetupArgs(argv) {
     addLifecycleCommand('install');
     addLifecycleCommand('update');
     addLifecycleCommand('uninstall');
-    program
-        .command('plugin')
-        .argument('<name>')
-        .argument('<path>')
-        .allowExcessArguments(false)
-        .action((pluginName, pluginPath) => {
-        parsed = { ...baseParsedArgs(), operation: 'plugin', pluginName, pluginPath };
-    });
     const extension = new Command('extension')
         .exitOverride()
         .configureOutput({ writeErr: () => { }, writeOut: () => { } })
@@ -167,7 +173,7 @@ Environment commands:
 Integration commands:
   plugin install <arguments...>   Install Skills and register their CLI plugins
   plugin uninstall <name>        Uninstall one CLI plugin
-  plugin <name> <path>            Register an existing plugin entry
+  plugin [name] <path>            Register an existing plugin; name overrides metadata
   provider install <package>      Install and register a Provider package
   provider update <id|package>    Update a registered Provider package
   provider uninstall <id|package> Uninstall a Provider package and registration
@@ -257,9 +263,12 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
                 }
                 return 0;
             }
-            const entry = await (dependencies.registerPlugin ?? setupPlugin)(parsed.pluginName, parsed.pluginPath);
-            console.error(`Plugin ${parsed.pluginName} registered: ${entry}`);
-            console.error(`Run: mearl ${parsed.pluginName} --help`);
+            const register = dependencies.registerPlugin ?? setupPlugin;
+            const registration = parsed.pluginName
+                ? await register(parsed.pluginPath, parsed.pluginName)
+                : await register(parsed.pluginPath);
+            console.error(`Plugin ${registration.name} registered: ${registration.entry}`);
+            console.error(`Run: mearl ${registration.name} --help`);
             return 0;
         }
         catch (error) {
@@ -294,6 +303,7 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
             return 2;
         }
         let extensionInstalled = false;
+        let extensionFailureIsTerminal = false;
         try {
             const result = await (dependencies.installBrowserExtension ?? installMearlBrowserExtension)({
                 force: parsed.force,
@@ -312,15 +322,23 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
                 console.error(result.filesUpdated
                     ? `Browser extension v${result.version} files were updated, but the extension was not reloaded.`
                     : `Browser extension v${result.version} was not installed.`);
-                if (result.cdpError)
-                    console.error(`CDP installation pending: ${result.cdpError}`);
-                console.error('Open chrome://inspect/#remote-debugging, enable remote debugging, approve the connection, then rerun: npx @mearl/setup extension');
+                if (result.cdpError) {
+                    console.error(`CDP installation failed: ${result.cdpError}`);
+                    if (isUnsupportedCdpMethodError(result.cdpError)) {
+                        console.error('This Chrome version does not support installing extensions through CDP. Update Chrome to version 145 or later, then rerun: npx @mearl/setup extension');
+                        extensionFailureIsTerminal = true;
+                    }
+                    else {
+                        console.error('Open chrome://inspect/#remote-debugging, enable remote debugging, approve the connection, then rerun: npx @mearl/setup extension');
+                        extensionFailureIsTerminal = parsed.yes;
+                    }
+                }
             }
         }
         catch (error) {
             console.error(error instanceof Error ? error.message : String(error));
         }
-        if (!parsed.full)
+        if (!parsed.full || extensionFailureIsTerminal)
             return extensionInstalled ? 0 : 1;
         let localInstalled = false;
         try {

package/dist/lifecycle.js

@@ -5,7 +5,7 @@ import { stdin as input, stdout as output } from 'node:process';
 import { listPluginNames } from '@mearl/client/plugin';
 import { listInstalledProviders } from '@mearl/provider/host';
 import { runGlobalMearlSkillOperation } from './aliSkills.js';
-import { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, } from './packageManager.js';
+import { buildGlobalPackageCommand, detectGlobalPackage, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
 import { MEARL_PROFILES, detectMearlProfiles, } from './profiles.js';
 import { uninstallNativeHostArtifacts } from './nativeHost.js';
 import { executableNames, prependCommandPath, runCommand, } from './process.js';
@@ -17,6 +17,33 @@ const LEGACY_CLOUD_CLIENT = '@mearl/cloud-client';
 const UNIFIED_CLIENT = '@mearl/client';
 const PROFILE_ORDER = ['local', 'cloud', 'mcp'];
 const CLIENT_PROFILES = ['local', 'cloud'];
+function autoUpdateClientInstallation(env) {
+    const root = env.MEARL_AUTO_UPDATE_CLIENT_ROOT;
+    if (!root)
+        return null;
+    try {
+        const packageRoot = fs.realpathSync(root);
+        const manifest = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8'));
+        if (manifest.name !== UNIFIED_CLIENT)
+            return null;
+        return resolvePackageManagerInstallation(packageRoot, UNIFIED_CLIENT, { env });
+    }
+    catch {
+        return null;
+    }
+}
+function autoUpdateProfiles(env) {
+    const value = env.MEARL_AUTO_UPDATE_PROFILES;
+    if (value === undefined)
+        return undefined;
+    const requested = value.split(',');
+    if (requested.length === 0 ||
+        new Set(requested).size !== requested.length ||
+        requested.some(profile => !PROFILE_ORDER.includes(profile))) {
+        throw new Error('Invalid automatic update profiles');
+    }
+    return PROFILE_ORDER.filter(profile => requested.includes(profile));
+}
 async function confirmInTerminal(message) {
     if (!input.isTTY || !output.isTTY)
         return false;
@@ -153,9 +180,22 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         (childEnv => resolveInvokingPackageManager({ env: childEnv }));
     const runSkill = dependencies.runSkillOperation ?? runGlobalMearlSkillOperation;
     const confirm = dependencies.confirm ?? confirmInTerminal;
-    const detected = detectProfiles(env);
-    const requestedProfiles = options.profiles ?? (options.profile ? [options.profile] : undefined);
-    const selected = selectedProfiles(options.operation, requestedProfiles, detected);
+    const detectionEnv = options.operation === 'update' && env.MEARL_AUTO_UPDATE_SEARCH_PATH !== undefined
+        ? { ...env, PATH: env.MEARL_AUTO_UPDATE_SEARCH_PATH }
+        : env;
+    const detected = detectProfiles(detectionEnv);
+    const requestedProfiles = options.profiles ??
+        (options.profile ? [options.profile] : undefined) ??
+        (options.operation === 'update' ? autoUpdateProfiles(env) : undefined);
+    const autoUpdateClient = options.operation === 'update' ? autoUpdateClientInstallation(env) : null;
+    const clientOnly = options.operation === 'update' && env.MEARL_AUTO_UPDATE_CLIENT_ONLY === '1';
+    if (clientOnly && !autoUpdateClient) {
+        writeLine('A valid global client installation is required for a client-only update.');
+        return false;
+    }
+    const selected = clientOnly
+        ? []
+        : selectedProfiles(options.operation, requestedProfiles, detected);
     const lifecycleSelected = options.operation === 'uninstall'
         ? selected.filter(profile => detected.has(profile))
         : selected;
@@ -186,6 +226,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         return true;
     }
     if (selected.length === 0 &&
+        !autoUpdateClient &&
         !(options.operation === 'uninstall' && options.full && hasFullIntegrationTargets)) {
         writeLine('No installed Mearl environment was detected on the current PATH.');
         if (options.operation === 'uninstall')
@@ -226,6 +267,9 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             .map(profile => MEARL_PROFILES[profile].label)
             .join(', ')}`);
     }
+    if (autoUpdateClient && lifecycleSelected.length === 0) {
+        writeLine('update targets: client CLI');
+    }
     let packagesOk = true;
     if (lifecycleSelected.includes('cloud')) {
         const legacyCloudClient = detectPackage(LEGACY_CLOUD_CLIENT, ['mearl-cloud'], { env });
@@ -243,8 +287,9 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             }
         }
     }
-    const selectedUsesClient = lifecycleSelected.some(profile => CLIENT_PROFILES.includes(profile));
-    const detectedClientCandidate = selectedUsesClient
+    const selectedUsesClient = autoUpdateClient !== null ||
+        lifecycleSelected.some(profile => CLIENT_PROFILES.includes(profile));
+    const detectedClientCandidate = selectedUsesClient && !autoUpdateClient
         ? detectPackage(UNIFIED_CLIENT, ['mearl'], { env })
         : null;
     const detectedClient = detectedClientCandidate?.packageName === UNIFIED_CLIENT ? detectedClientCandidate : null;
@@ -252,7 +297,8 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         ? CLIENT_PROFILES.filter(profile => detected.has(profile) && !lifecycleSelected.includes(profile))
         : [];
     if (selectedUsesClient && options.operation !== 'uninstall') {
-        const clientInstallation = detectedClient ??
+        const clientInstallation = autoUpdateClient ??
+            detectedClient ??
             detected.get('local') ??
             detected.get('cloud') ??
             resolveInvokingManager(env);

package/dist/plugin.d.ts

@@ -1,5 +1,9 @@
 import { type CommandRunner } from './process.js';
-export declare function setupPlugin(name: string, target: string): Promise<string>;
+export interface PluginSetupResult {
+    entry: string;
+    name: string;
+}
+export declare function setupPlugin(target: string, requestedName?: string): Promise<PluginSetupResult>;
 export declare function ensureOfficialPlugin(name: string, runner?: CommandRunner): Promise<'existing' | 'installed'>;
 export interface PluginUninstallResult {
     entryMissing?: boolean;

package/dist/plugin.js

@@ -1,4 +1,4 @@
-import { existsSync, mkdirSync, rmdirSync, statSync } from 'node:fs';
+import { existsSync, mkdirSync, readdirSync, readlinkSync, realpathSync, rmdirSync, statSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
 import { assertPluginName, findPluginDirectoryEntry, findOfficialPlugin, findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, OFFICIAL_PLUGIN_MANAGER, registerPlugin, resolvePluginEntry, unregisterPlugin, } from '@mearl/client/plugin';
@@ -14,12 +14,32 @@ const registrationContext = {
         throw new Error('注册时不能报告执行进度');
     },
 };
-export async function setupPlugin(name, target) {
-    assertPluginName(name);
+function defaultPluginName(target, entry) {
+    const resolvedTarget = resolve(target);
+    try {
+        if (statSync(resolvedTarget).isDirectory())
+            return basename(resolvedTarget);
+    }
+    catch {
+        // resolvePluginEntry 会提供具体的路径错误。
+    }
+    const entryDirectory = dirname(entry);
+    return basename(entryDirectory) === 'scripts'
+        ? basename(dirname(entryDirectory))
+        : basename(entryDirectory);
+}
+export async function setupPlugin(target, requestedName) {
+    if (requestedName)
+        assertPluginName(requestedName);
     const entry = resolvePluginEntry(target);
     const plugin = await loadPlugin(entry, registrationContext);
+    const name = requestedName || plugin.name || defaultPluginName(target, entry);
+    assertPluginName(name);
     await ensurePluginRuntime();
-    return registerPlugin(name, entry, plugin.description, { toolbox: plugin.toolbox });
+    return {
+        entry: registerPlugin(name, entry, plugin.description, { toolbox: plugin.toolbox }),
+        name,
+    };
 }
 export async function ensureOfficialPlugin(name, runner = runCommand) {
     const definition = findOfficialPlugin(name);
@@ -40,12 +60,57 @@ export async function ensureOfficialPlugin(name, runner = runCommand) {
 function globalAliSkill(entry) {
     const globalSkillsDirectory = join(homedir(), '.agents', 'skills');
     const relativeEntry = relative(globalSkillsDirectory, resolve(entry));
-    if (isAbsolute(relativeEntry) || relativeEntry === '..' || relativeEntry.startsWith(`..${sep}`))
+    if (!isAbsolute(relativeEntry) &&
+        relativeEntry !== '..' &&
+        !relativeEntry.startsWith(`..${sep}`)) {
+        const [name, ...entrySegments] = relativeEntry.split(sep);
+        if (name && entrySegments.length > 0)
+            return { directory: join(globalSkillsDirectory, name), name };
+    }
+    const sourceDirectory = dirname(dirname(resolve(entry)));
+    if (basename(dirname(entry)) !== 'scripts')
+        return undefined;
+    try {
+        const source = existsSync(sourceDirectory) ? realpathSync(sourceDirectory) : sourceDirectory;
+        for (const name of readdirSync(globalSkillsDirectory)) {
+            const directory = join(globalSkillsDirectory, name);
+            let target;
+            try {
+                target = resolve(globalSkillsDirectory, readlinkSync(directory));
+            }
+            catch {
+                continue;
+            }
+            if (target === sourceDirectory || (existsSync(target) && realpathSync(target) === source)) {
+                return { directory, name };
+            }
+        }
+    }
+    catch {
+        // 全局 Skill 目录不可读时保留本地插件的普通卸载路径。
+    }
+    return undefined;
+}
+function projectAliSkill(entry, managedBy) {
+    if (managedBy !== 'ali-skills')
+        return undefined;
+    const absolute = resolve(entry);
+    const marker = `${sep}.agents${sep}skills${sep}`;
+    const markerIndex = absolute.lastIndexOf(marker);
+    if (markerIndex <= 0)
+        return undefined;
+    const cwd = absolute.slice(0, markerIndex);
+    if (resolve(cwd) === resolve(homedir()))
         return undefined;
-    const [name, ...entrySegments] = relativeEntry.split(sep);
-    if (!name || entrySegments.length === 0)
+    const [name, scripts, filename, ...remaining] = absolute
+        .slice(markerIndex + marker.length)
+        .split(sep);
+    if (!name ||
+        scripts !== 'scripts' ||
+        !['main.mjs', 'main.py'].includes(filename) ||
+        remaining.length > 0)
         return undefined;
-    return { directory: join(globalSkillsDirectory, name), name };
+    return { directory: join(cwd, '.agents', 'skills', name), name, cwd };
 }
 export async function uninstallPlugin(name, runner = runCommand) {
     assertPluginName(name);
@@ -53,7 +118,7 @@ export async function uninstallPlugin(name, runner = runCommand) {
     if (!entry)
         return { removed: false, unregisteredNames: [] };
     const entryMissing = !existsSync(entry);
-    const managedSkill = globalAliSkill(entry);
+    const managedSkill = projectAliSkill(entry, findPluginRegistration(name)?.managedBy) ?? globalAliSkill(entry);
     if (!managedSkill) {
         unregisterPlugin(name);
         return {
@@ -66,6 +131,18 @@ export async function uninstallPlugin(name, runner = runCommand) {
     if (!invocation)
         throw new Error('未找到 ali-skills 或 npx，插件注册已保留。');
     const { directory: skillDirectory, name: skillName } = managedSkill;
+    const unregisteredNames = listPluginNames().filter(pluginName => {
+        try {
+            const candidate = findPluginEntry(pluginName);
+            if (!candidate)
+                return false;
+            const candidateSkill = projectAliSkill(candidate, 'ali-skills') ?? globalAliSkill(candidate);
+            return candidateSkill?.directory === skillDirectory;
+        }
+        catch {
+            return false;
+        }
+    });
     let placeholderCreated = false;
     if (!existsSync(skillDirectory)) {
         mkdirSync(dirname(skillDirectory), { recursive: true, mode: 0o700 });
@@ -80,7 +157,13 @@ export async function uninstallPlugin(name, runner = runCommand) {
     }
     let removed;
     try {
-        removed = await runner(invocation.command, [...invocation.argsPrefix, 'remove', skillName, '--global', '--yes'], { env: invocation.env, tee: true });
+        removed = await runner(invocation.command, [
+            ...invocation.argsPrefix,
+            'remove',
+            skillName,
+            ...(managedSkill.cwd ? [] : ['--global']),
+            '--yes',
+        ], { env: invocation.env, tee: true, ...(managedSkill.cwd ? { cwd: managedSkill.cwd } : {}) });
     }
     catch (error) {
         throw new Error(`ali-skills remove ${skillName} 执行失败：${error instanceof Error ? error.message : String(error)}；插件注册已保留。`, { cause: error });
@@ -98,15 +181,6 @@ export async function uninstallPlugin(name, runner = runCommand) {
     if (removed.code !== 0) {
         throw new Error(`ali-skills remove ${skillName} 失败（exit ${removed.code}）；插件注册已保留。`);
     }
-    const unregisteredNames = listPluginNames().filter(pluginName => {
-        try {
-            const candidate = findPluginEntry(pluginName);
-            return candidate !== undefined && globalAliSkill(candidate)?.directory === skillDirectory;
-        }
-        catch {
-            return false;
-        }
-    });
     for (const pluginName of unregisteredNames)
         unregisterPlugin(pluginName);
     return {
@@ -140,12 +214,12 @@ export function parseInstalledPluginPaths(output) {
         const value = item[1].trim().replaceAll('\\', '/');
         const skillPath = resolve(value.startsWith('~/') ? join(homedir(), value.slice(2)) : value);
         if (dirname(skillPath) !== join(homedir(), '.agents', 'skills')) {
-            throw new Error(`无法识别全局 skill 安装路径: ${item[1]}。请使用 setup plugin <name> <path> 注册。`);
+            throw new Error(`无法识别全局 skill 安装路径: ${item[1]}。请使用 setup plugin [name] <path> 注册。`);
         }
         paths.push(skillPath);
     }
     if (paths.length !== expected)
-        throw new Error('Ali Skills 安装结果格式无法识别，请使用 setup plugin <name> <path> 注册。');
+        throw new Error('Ali Skills 安装结果格式无法识别，请使用 setup plugin [name] <path> 注册。');
     return [...new Set(paths)];
 }
 function permitsEmptyInstallResult(args, output) {
@@ -172,7 +246,7 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
     if (paths.length === 0) {
         if (permitsEmptyInstallResult(args, output))
             return 0;
-        throw new Error('Ali Skills 安装成功但无法识别安装结果，请使用 setup plugin <name> <path> 注册。');
+        throw new Error('Ali Skills 安装成功但无法识别安装结果，请使用 setup plugin [name] <path> 注册。');
     }
     const plugins = new Map();
     for (const skillPath of paths) {
@@ -182,10 +256,10 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
         if (!entry)
             continue;
         const plugin = await loadPlugin(entry, registrationContext);
-        const name = plugin.name ?? basename(skillPath);
+        const name = plugin.name || basename(skillPath);
         assertPluginName(name);
         if (plugins.has(name))
-            throw new Error(`多个 skill 使用插件名称 ${name}，请通过 setup plugin <name> <path> 分别注册。`);
+            throw new Error(`多个 skill 使用插件名称 ${name}，请调整入口的 name metadata。`);
         plugins.set(name, {
             entry,
             description: plugin.description,
@@ -193,7 +267,7 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
         });
     }
     if (plugins.size === 0) {
-        console.error('未找到 scripts/main.mjs 或 scripts/main.py 插件入口；自定义入口可用 setup plugin <name> <path> 注册。');
+        console.error('未找到 scripts/main.mjs 或 scripts/main.py 插件入口；自定义入口可用 setup plugin [name] <path> 注册。');
         return 0;
     }
     await ensurePluginRuntime(runner);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.18.0",
+  "version": "2.19.0",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -22,6 +22,10 @@
       "types": "./dist/packageManager.d.ts",
       "import": "./dist/packageManager.js"
     },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "import": "./dist/plugin.js"
+    },
     "./native-host": {
       "types": "./dist/nativeHost.d.ts",
       "import": "./dist/nativeHost.js"
@@ -61,8 +65,8 @@
     "commander": "^15.0.0",
     "extract-zip": "^2.0.1",
     "ws": "^8.18.3",
-    "@mearl/client": "2.18.0",
-    "@mearl/provider": "2.18.0"
+    "@mearl/client": "2.19.0",
+    "@mearl/provider": "2.19.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",