@mearl/setup 2.11.0 → 2.13.0

package/README.md

@@ -6,6 +6,10 @@ Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全
 npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp]
 npx @mearl/setup <update|uninstall> [--local] [--cloud|--qoder-cloud] [--mcp]
 npx @mearl/setup extension [--full] [--force]
+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>
 ```
 
 配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。
@@ -23,6 +27,67 @@ npx @mearl/setup agentbay
 模式记录为 Qoder；`mearl-cloud-server` 的命令交互保持不变，`start` 和 `restart` 输出新的
 配对指令后退出，不监听端口或保留守护进程。配对 URL 不包含 Qoder PAT。
 
+## 安装与注册 Skill CLI 插件
+
+一个命令安装 skill 并注册它的 CLI 能力：
+
+```bash
+npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
+mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
+```
+
+安装参数透传给 `npx -y ali-skills add`，末尾统一追加 `--global --install-mode symlink`；不接受会截断后置选项的 `--` 参数分隔符，
+确保 skill 存放在 `~/.agents/skills` 并共享给所选 agent。安装日志实时显示，保留交互；
+setup 从 `Installed … skill(s)` 成功区块提取路径，仅注册本次安装且包含 `scripts/main.mjs` 的 skill。
+普通 skill 正常安装。输出格式无法识别时提示手动注册，不扫描其他 skill 或猜测安装结果。
+
+自动注册默认使用安装目录名；入口可用 `export const name = 'yuque'` 指定简短命令名。
+重装会刷新同名绑定。每个入口必须默认导出 `register(app)`；完整协议见
+[CLI 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
+
+已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
+
+```bash
+npx @mearl/setup plugin yuque /absolute/path/to/yuque-doc-fetch
+npx @mearl/setup plugin custom ./skills/custom/entry.mjs
+```
+
+path 接受目录或具体文件；目录默认读取 `scripts/main.mjs`，相对路径基于调用工作目录解析。
+命令检查入口注册函数，然后保存绝对入口路径，同名注册更新绑定。
+两种注册流程都会检查本机 `@mearl/client` 和 `@mearl/native-host`：缺失或低于当前 setup 版本时，
+复用已有包管理器安装 setup 的对应版本，更新后再次验证；更高版本保持不动。
+native-host 会幂等初始化 Skills 模式。基础环境补齐或初始化失败时保留已安装的 skill，并停止注册。
+注册后可在任意目录运行 `mearl <name> --help`，日常业务调用不执行安装或版本检查。
+
+不再需要插件时执行：
+
+```bash
+npx @mearl/setup plugin uninstall yuque
+```
+
+若入口位于 `~/.agents/skills/<skill>/`，setup 会先执行
+`ali-skills remove <skill> --global --yes`，成功后清除该 Skill 对应的全部插件注册；
+入口目录已被手动删除时会让 Ali Skills 仍能识别本次移除，从而一并清理其跟踪记录。
+移除失败时保留注册以便重试。手工注册的其他路径只解除 Mearl 注册，不删除源码。
+重复卸载未注册名称会成功返回，不产生改动。
+
+## 管理浏览器 Provider
+
+Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setup 使用当前 npm 包管理器
+完成全局包生命周期，再读取包内的 `package.json#mearl.provider` 元数据登记协议入口、
+可创建的浏览器类型名称及其表单参数：
+
+```bash
+npx @mearl/setup provider install @ali/mearl-provider-brow
+npx @mearl/setup provider update brow
+npx @mearl/setup provider uninstall brow
+```
+
+安装参数接受包名、版本或 dist-tag；更新和卸载可使用 `providerId` 或完整包名。阿里包在
+本机存在 `tnpm` 时优先使用 `tnpm`，其他情况沿用启动 setup 的包管理器。Provider 登记只保存
+经过校验的包名、安装目录和包内入口；不接受包自行注入启动命令、参数、工作目录或环境变量。
+卸载仅在包管理器成功移除包后清除登记，以便失败时可以重试。
+
 ## 行为
 
 - `install` 可以省略；直接执行 `npx @mearl/setup` 等同于 `npx @mearl/setup install`。
@@ -153,4 +218,4 @@ npx @mearl/setup agentbay
 npx @mearl/setup agentbay --key-file ./agentbay.key
 ```
 
-原有的 npm/npx 安装方式和各包 CLI 保持可用；setup 只是统一的便利入口。
+原有 Mearl 环境包的 npm/npx 安装方式和 CLI 保持可用；setup 是统一的便利入口。

package/dist/cli.d.ts

@@ -3,6 +3,8 @@ import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile,
 import { installMearlBrowserExtension } from './browserExtension.js';
 import { runMearlLifecycle, type MearlLifecycleOperation } from './lifecycle.js';
 import type { MearlProfile } from './profiles.js';
+import { installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
+import { installProviderPackage, uninstallProviderPackage, updateProviderPackage } from './provider.js';
 export declare const SETUP_VERSION: string;
 interface ParsedArgs {
     agentBayKeyFile?: string;
@@ -11,7 +13,13 @@ interface ParsedArgs {
     force?: boolean;
     full?: boolean;
     help: boolean;
-    operation?: MearlLifecycleOperation | 'agentbay' | 'extension';
+    operation?: MearlLifecycleOperation | 'agentbay' | 'extension' | 'plugin' | 'provider';
+    pluginName?: string;
+    pluginPath?: string;
+    pluginInstallArgs?: string[];
+    pluginUninstallName?: string;
+    providerCommand?: 'install' | 'uninstall' | 'update';
+    providerTarget?: string;
     profiles?: MearlProfile[];
     skipSkill: boolean;
     targetLine?: string;
@@ -19,12 +27,18 @@ interface ParsedArgs {
     yes: boolean;
 }
 export interface SetupCliDependencies {
+    registerPlugin?: typeof setupPlugin;
+    installPlugins?: typeof installPlugins;
+    uninstallPlugin?: typeof uninstallPlugin;
     configureAgentBay?: typeof configureAgentBayApiKey;
     promptAgentBayKey?: typeof promptAgentBayApiKey;
     readAgentBayKeyFile?: typeof readAgentBayApiKeyFile;
     readAgentBayKeyStdin?: typeof readAgentBayApiKeyStdin;
     installBrowserExtension?: typeof installMearlBrowserExtension;
+    installProvider?: typeof installProviderPackage;
     runLifecycle?: typeof runMearlLifecycle;
+    uninstallProvider?: typeof uninstallProviderPackage;
+    updateProvider?: typeof updateProviderPackage;
 }
 export declare function parseSetupArgs(argv: string[]): ParsedArgs;
 export declare function main(argv?: string[], interactiveTerminal?: boolean, dependencies?: SetupCliDependencies): Promise<number>;

package/dist/cli.js

@@ -5,6 +5,8 @@ import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile,
 import { installMearlBrowserExtension } from './browserExtension.js';
 import { runMearlLifecycle } from './lifecycle.js';
 import { isMearlReleaseLine } from './version.js';
+import { installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
+import { installProviderPackage, uninstallProviderPackage, updateProviderPackage, } from './provider.js';
 const require = createRequire(import.meta.url);
 export const SETUP_VERSION = require('../package.json').version;
 const baseParsedArgs = () => ({
@@ -24,6 +26,29 @@ function commanderError(error) {
     return new Error(message);
 }
 export function parseSetupArgs(argv) {
+    if (argv[0] === 'provider') {
+        const command = argv[1];
+        if ((command === 'install' || command === 'update' || command === 'uninstall') &&
+            argv.length === 3 &&
+            argv[2]) {
+            return {
+                ...baseParsedArgs(),
+                operation: 'provider',
+                providerCommand: command,
+                providerTarget: argv[2],
+            };
+        }
+        throw new Error('provider requires install <package>, update <id>, or uninstall <id>');
+    }
+    if (argv[0] === 'plugin' && argv[1] === 'install') {
+        return { ...baseParsedArgs(), operation: 'plugin', pluginInstallArgs: argv.slice(2) };
+    }
+    if (argv[0] === 'plugin' && argv[1] === 'uninstall') {
+        if (argv.length !== 3 || !argv[2]) {
+            throw new Error('plugin uninstall requires exactly one plugin name');
+        }
+        return { ...baseParsedArgs(), operation: 'plugin', pluginUninstallName: argv[2] };
+    }
     let parsed;
     const program = new Command()
         .name('mearl-setup')
@@ -77,6 +102,14 @@ 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: () => { } })
@@ -145,6 +178,10 @@ Usage:
   npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
   npx @mearl/setup <update|uninstall> [--local] [--cloud|--qoder-cloud] [--mcp] [--yes]
   npx @mearl/setup extension [--full] [--force] [--yes]
+  npx @mearl/setup plugin <name> <path>
+  npx @mearl/setup plugin install <ali-skills add arguments...>
+  npx @mearl/setup plugin uninstall <name>
+  npx @mearl/setup provider <install|update|uninstall> <package|id>
   npx @mearl/setup agentbay [--stdin | --key-file <path>]
 
 Behavior:
@@ -153,6 +190,8 @@ Behavior:
   uninstall    Auto-detects installed environments and asks for confirmation
   extension    Install or update the browser extension; --full also installs the local environment
   agentbay     Save or update AGENTBAY_KEY without changing other Mearl settings
+  plugin       Register, install, or uninstall a CLI plugin
+  provider     Install npm Provider packages and manage their Mearl registration
 
 Options:
   --local      Manage @mearl/native-host and @mearl/client
@@ -183,6 +222,8 @@ Examples:
   npx @mearl/setup update
   npx @mearl/setup extension
   npx @mearl/setup extension --full
+  npx @mearl/setup plugin uninstall yuque
+  npx @mearl/setup provider install @ali/mearl-provider-brow
   npx @mearl/setup agentbay
   npx @mearl/setup --qoder-cloud --yes
   npx @mearl/setup update --local --target-line 2.3.x --skip-skill
@@ -210,6 +251,62 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
         console.log(SETUP_VERSION);
         return 0;
     }
+    if (parsed.operation === 'plugin') {
+        try {
+            if (parsed.pluginInstallArgs) {
+                return await (dependencies.installPlugins ?? installPlugins)(parsed.pluginInstallArgs);
+            }
+            if (parsed.pluginUninstallName) {
+                const result = await (dependencies.uninstallPlugin ?? uninstallPlugin)(parsed.pluginUninstallName);
+                if (!result.removed) {
+                    console.error(`Plugin ${parsed.pluginUninstallName} is not registered.`);
+                }
+                else if (result.skillName) {
+                    console.error(result.entryMissing
+                        ? `Plugin ${parsed.pluginUninstallName} had a missing entry; ali-skills cleanup completed for ${result.skillName}.`
+                        : `Plugin ${parsed.pluginUninstallName} uninstalled with ali-skills skill ${result.skillName}.`);
+                    if (result.unregisteredNames.length > 1) {
+                        console.error(`Removed registrations: ${result.unregisteredNames.join(', ')}`);
+                    }
+                }
+                else {
+                    console.error(result.entryMissing
+                        ? `Plugin ${parsed.pluginUninstallName} stale registration removed; the external entry was already missing.`
+                        : `Plugin ${parsed.pluginUninstallName} unregistered; external skill files were kept.`);
+                }
+                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`);
+            return 0;
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    }
+    if (parsed.operation === 'provider') {
+        try {
+            const target = parsed.providerTarget;
+            const result = parsed.providerCommand === 'install'
+                ? await (dependencies.installProvider ?? installProviderPackage)(target)
+                : parsed.providerCommand === 'update'
+                    ? await (dependencies.updateProvider ?? updateProviderPackage)(target)
+                    : await (dependencies.uninstallProvider ?? uninstallProviderPackage)(target);
+            const verb = parsed.providerCommand === 'uninstall'
+                ? 'uninstalled'
+                : parsed.providerCommand === 'update'
+                    ? 'updated'
+                    : 'installed';
+            console.error(`Provider ${result.manifest.providerId} ${verb}: ${result.manifest.packageName}@${result.manifest.version} (${result.manager})`);
+            return 0;
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    }
     if (parsed.operation === 'agentbay') {
         try {
             const configureAgentBay = dependencies.configureAgentBay ?? configureAgentBayApiKey;

package/dist/index.d.ts

@@ -11,4 +11,6 @@ export type { DetectedMearlProfiles, MearlProfile, MearlProfileConfig } from './
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
 export { compareMearlReleaseLines, compareMearlReleaseVersions, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';
 export type { MearlReleaseLine, MearlReleaseVersion } from './version.js';
+export { installProviderPackage, parseProviderPackageSpec, uninstallProviderPackage, updateProviderPackage, } from './provider.js';
+export type { ProviderSetupDependencies, ProviderSetupResult } from './provider.js';
 export type { NativeHostCleanupDependencies, NativeHostCleanupOptions, NativeHostIntegrationMode, } from './nativeHost.js';

package/dist/index.js

@@ -5,3 +5,4 @@ export { runMearlLifecycle } from './lifecycle.js';
 export { MEARL_PROFILES, detectMearlProfiles } from './profiles.js';
 export { MEARL_NATIVE_HOST_NAMES, resolveNativeHostDirectory, uninstallNativeHostArtifacts, } from './nativeHost.js';
 export { compareMearlReleaseLines, compareMearlReleaseVersions, isMearlReleaseLine, isMearlReleaseVersion, isMearlReleaseVersionInLine, mearlReleaseLineForVersion, parseMearlReleaseLine, parseMearlReleaseVersion, } from './version.js';
+export { installProviderPackage, parseProviderPackageSpec, uninstallProviderPackage, updateProviderPackage, } from './provider.js';

package/dist/packageManager.d.ts

@@ -32,4 +32,5 @@ export declare function resolveInvokingPackageManager(options?: {
     platform?: NodeJS.Platform;
     processExecPath?: string;
 }): PackageManagerInstallation;
+export declare function detectCliPackage(packageName: string, binNames: string[], options?: PackageDetectionOptions): Pick<DetectedGlobalPackage, 'packageName' | 'packageRoot' | 'executable'> | null;
 export declare function detectGlobalPackage(packageName: string, binNames: string[], options?: PackageDetectionOptions): DetectedGlobalPackage | null;

package/dist/packageManager.js

@@ -188,7 +188,7 @@ function packageRootFromWrapper(executable, packageName, readFileSync) {
         return null;
     }
 }
-export function detectGlobalPackage(packageName, binNames, options = {}) {
+export function detectCliPackage(packageName, binNames, options = {}) {
     const env = options.env ?? process.env;
     const platform = options.platform ?? process.platform;
     const existsSync = options.existsSync ?? (candidate => isExecutable(candidate, platform));
@@ -215,20 +215,22 @@ export function detectGlobalPackage(packageName, binNames, options = {}) {
         packageRoot ??= packageRootFromWrapper(executable, packageName, readFileSync);
         if (!packageRoot)
             continue;
-        const installation = resolvePackageManagerInstallation(packageRoot, packageName, {
-            env,
-            existsSync,
-            platform,
-            processExecPath,
-        });
+        return { packageName, packageRoot, executable };
+    }
+    return null;
+}
+export function detectGlobalPackage(packageName, binNames, options = {}) {
+    for (const binName of binNames) {
+        const cli = detectCliPackage(packageName, [binName], options);
+        if (!cli)
+            continue;
+        const installation = resolvePackageManagerInstallation(cli.packageRoot, packageName, options);
         if (!installation)
             continue;
         return {
-            packageName,
-            packageRoot,
-            executable,
+            ...cli,
             ...installation,
-            binDirectory: path.dirname(executable),
+            binDirectory: path.dirname(cli.executable),
         };
     }
     return null;

package/dist/plugin.d.ts

@@ -0,0 +1,12 @@
+import { type CommandRunner } from './process.js';
+export declare function setupPlugin(name: string, target: string): Promise<string>;
+export interface PluginUninstallResult {
+    entryMissing?: boolean;
+    removed: boolean;
+    skillName?: string;
+    unregisteredNames: string[];
+}
+export declare function uninstallPlugin(name: string, runner?: CommandRunner): Promise<PluginUninstallResult>;
+/** Ali Skills 的 Installed 区块列出成功路径；计数校验避免输出变化导致漏注册。 */
+export declare function parseInstalledPluginPaths(output: string): string[];
+export declare function installPlugins(args: string[], runner?: CommandRunner): Promise<number>;

package/dist/plugin.js

@@ -0,0 +1,185 @@
+import { existsSync, mkdirSync, rmdirSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { assertPluginName, findPluginEntry, listPluginNames, loadPlugin, registerPlugin, resolvePluginEntry, unregisterPlugin, } from '@mearl/client/plugin';
+import { ensurePluginRuntime } from './pluginRuntime.js';
+import { resolveAliSkillsInvocation, stripAnsi } from './aliSkills.js';
+import { findExecutable, prependNodePath, runCommand } from './process.js';
+const registrationContext = {
+    options: {},
+    invoke: async () => {
+        throw new Error('注册时不能执行浏览器操作');
+    },
+    progress: () => {
+        throw new Error('注册时不能报告执行进度');
+    },
+};
+export async function setupPlugin(name, target) {
+    assertPluginName(name);
+    const entry = resolvePluginEntry(target);
+    const plugin = await loadPlugin(entry, registrationContext);
+    await ensurePluginRuntime();
+    return registerPlugin(name, entry, plugin.description);
+}
+function globalAliSkill(entry) {
+    const globalSkillsDirectory = join(homedir(), '.agents', 'skills');
+    const relativeEntry = relative(globalSkillsDirectory, resolve(entry));
+    if (isAbsolute(relativeEntry) || relativeEntry === '..' || relativeEntry.startsWith(`..${sep}`))
+        return undefined;
+    const [name, ...entrySegments] = relativeEntry.split(sep);
+    if (!name || entrySegments.length === 0)
+        return undefined;
+    return { directory: join(globalSkillsDirectory, name), name };
+}
+export async function uninstallPlugin(name, runner = runCommand) {
+    assertPluginName(name);
+    const entry = findPluginEntry(name);
+    if (!entry)
+        return { removed: false, unregisteredNames: [] };
+    const entryMissing = !existsSync(entry);
+    const managedSkill = globalAliSkill(entry);
+    if (!managedSkill) {
+        unregisterPlugin(name);
+        return {
+            ...(entryMissing ? { entryMissing: true } : {}),
+            removed: true,
+            unregisteredNames: [name],
+        };
+    }
+    const invocation = resolveAliSkillsInvocation();
+    if (!invocation)
+        throw new Error('未找到 ali-skills 或 npx，插件注册已保留。');
+    const { directory: skillDirectory, name: skillName } = managedSkill;
+    let placeholderCreated = false;
+    if (!existsSync(skillDirectory)) {
+        mkdirSync(dirname(skillDirectory), { recursive: true, mode: 0o700 });
+        try {
+            mkdirSync(skillDirectory, { mode: 0o700 });
+            placeholderCreated = true;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+        }
+    }
+    let removed;
+    try {
+        removed = await runner(invocation.command, [...invocation.argsPrefix, 'remove', skillName, '--global', '--yes'], { env: invocation.env, tee: true });
+    }
+    catch (error) {
+        throw new Error(`ali-skills remove ${skillName} 执行失败：${error instanceof Error ? error.message : String(error)}；插件注册已保留。`, { cause: error });
+    }
+    finally {
+        if (placeholderCreated) {
+            try {
+                rmdirSync(skillDirectory);
+            }
+            catch {
+                /* ali-skills 已移除，或目录中出现了新内容。 */
+            }
+        }
+    }
+    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 {
+        ...(entryMissing ? { entryMissing: true } : {}),
+        removed: true,
+        skillName,
+        unregisteredNames,
+    };
+}
+/** Ali Skills 的 Installed 区块列出成功路径；计数校验避免输出变化导致漏注册。 */
+export function parseInstalledPluginPaths(output) {
+    const paths = [];
+    let expected = 0;
+    let inResult = false;
+    for (const line of stripAnsi(output).split(/\r?\n/)) {
+        const heading = line.match(/\bInstalled (\d+) skills?\b/);
+        if (heading) {
+            expected += Number(heading[1]);
+            inResult = true;
+            continue;
+        }
+        if (!inResult)
+            continue;
+        if (/[╰└├]/.test(line)) {
+            inResult = false;
+            continue;
+        }
+        const item = line.trim().match(/^[│|]?\s*✓\s+(.+?)\s*[│|]?$/);
+        if (!item)
+            continue;
+        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> 注册。`);
+        }
+        paths.push(skillPath);
+    }
+    if (paths.length !== expected)
+        throw new Error('Ali Skills 安装结果格式无法识别，请使用 setup plugin <name> <path> 注册。');
+    return [...new Set(paths)];
+}
+function permitsEmptyInstallResult(args, output) {
+    return (args.length === 0 ||
+        args.some(argument => ['--help', '-h', '--list'].includes(argument)) ||
+        /\b(?:installation\s+)?cancel(?:led|ed)\b/i.test(output));
+}
+export async function installPlugins(args, runner = runCommand) {
+    if (args.includes('--')) {
+        throw new Error('plugin install 不支持 -- 参数分隔符，以确保全局 symlink 安装选项生效。');
+    }
+    const npx = findExecutable('npx', { extraDirectories: [dirname(process.execPath)] });
+    if (!npx)
+        throw new Error('未找到 npx，请检查 Node.js 安装。');
+    // 固定共享安装模式，确保成功结果指向 ~/.agents/skills 中的入口。
+    const installed = await runner(npx, ['-y', 'ali-skills', 'add', ...args, '--global', '--install-mode', 'symlink'], {
+        env: prependNodePath(),
+        tee: true,
+    });
+    if (installed.code !== 0)
+        return installed.code;
+    const output = `${installed.stdout ?? ''}\n${installed.stderr ?? ''}`;
+    const paths = parseInstalledPluginPaths(output);
+    if (paths.length === 0) {
+        if (permitsEmptyInstallResult(args, output))
+            return 0;
+        throw new Error('Ali Skills 安装成功但无法识别安装结果，请使用 setup plugin <name> <path> 注册。');
+    }
+    const plugins = new Map();
+    for (const skillPath of paths) {
+        if (!statSync(join(skillPath, 'SKILL.md')).isFile())
+            throw new Error(`安装结果缺少 SKILL.md: ${skillPath}`);
+        const entry = join(skillPath, 'scripts', 'main.mjs');
+        if (!existsSync(entry))
+            continue;
+        const plugin = await loadPlugin(entry, registrationContext);
+        const name = plugin.name ?? basename(skillPath);
+        assertPluginName(name);
+        if (plugins.has(name))
+            throw new Error(`多个 skill 使用插件名称 ${name}，请通过 setup plugin <name> <path> 分别注册。`);
+        plugins.set(name, { entry, description: plugin.description });
+    }
+    if (plugins.size === 0) {
+        console.error('未找到 scripts/main.mjs 插件入口；自定义入口可用 setup plugin <name> <path> 注册。');
+        return 0;
+    }
+    await ensurePluginRuntime(runner);
+    for (const [name, { entry, description }] of plugins) {
+        registerPlugin(name, entry, description);
+        console.error(`Plugin ${name} registered: ${entry}\nRun: mearl ${name} --help`);
+    }
+    return 0;
+}

package/dist/pluginRuntime.d.ts

@@ -0,0 +1,4 @@
+import { type CommandRunner } from './process.js';
+export declare const PLUGIN_RUNTIME_VERSION: string;
+/** 插件使用当前 setup 同版本的运行时；已安装的更高版本保持不动。 */
+export declare function ensurePluginRuntime(runner?: CommandRunner): Promise<void>;

package/dist/pluginRuntime.js

@@ -0,0 +1,57 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { join } from 'node:path';
+import { buildGlobalPackageCommand, detectCliPackage, detectGlobalPackage, resolveInvokingPackageManager, } from './packageManager.js';
+import { prependCommandPath, runCommand } from './process.js';
+import { compareMearlReleaseVersions, isMearlReleaseVersion } from './version.js';
+const require = createRequire(import.meta.url);
+export const PLUGIN_RUNTIME_VERSION = require('../package.json').version;
+/** 插件使用当前 setup 同版本的运行时；已安装的更高版本保持不动。 */
+export async function ensurePluginRuntime(runner = runCommand) {
+    for (const [packageName, bin] of [
+        ['@mearl/client', 'mearl'],
+        ['@mearl/native-host', 'mearl-native-host'],
+    ]) {
+        const inspect = () => {
+            const installed = detectCliPackage(packageName, [bin]);
+            const manifest = installed && JSON.parse(readFileSync(join(installed.packageRoot, 'package.json'), 'utf8'));
+            const version = manifest?.version;
+            const pluginExport = manifest?.exports?.['./plugin']?.import;
+            const supported = packageName !== '@mearl/client' ||
+                (installed &&
+                    typeof pluginExport === 'string' &&
+                    existsSync(join(installed.packageRoot, pluginExport)));
+            const current = isMearlReleaseVersion(version) &&
+                compareMearlReleaseVersions(version, PLUGIN_RUNTIME_VERSION) >= 0;
+            return { installed, version, current, ready: current && supported };
+        };
+        const before = inspect();
+        let ready = before;
+        if (!before.ready) {
+            if (before.current &&
+                compareMearlReleaseVersions(before.version, PLUGIN_RUNTIME_VERSION) > 0) {
+                throw new Error(`${packageName}@${before.version} 缺少插件入口，请修复该版本的安装后重试。`);
+            }
+            const manager = detectGlobalPackage(packageName, [bin]) ?? resolveInvokingPackageManager();
+            const command = buildGlobalPackageCommand(manager, 'install', [packageName], PLUGIN_RUNTIME_VERSION);
+            console.error(`${packageName}: ${before.version ?? '未安装'} → ${PLUGIN_RUNTIME_VERSION}`);
+            const result = await runner(command.command, command.args, {
+                env: prependCommandPath(command.command),
+            });
+            if (result.code !== 0)
+                throw new Error(`${packageName} 安装失败 (exit ${result.code})，插件尚未注册。`);
+            ready = inspect();
+            if (!ready.ready || !ready.installed) {
+                throw new Error(`${packageName} 更新后仍不可用，请检查 PATH 中的 ${bin} 是否指向 >= ${PLUGIN_RUNTIME_VERSION} 的有效安装。`);
+            }
+        }
+        if (packageName === '@mearl/native-host') {
+            const executable = ready.installed.executable;
+            const initialized = await runner(executable, ['--init', '--mode', 'skills'], {
+                env: prependCommandPath(executable),
+            });
+            if (initialized.code !== 0)
+                throw new Error(`native-host 初始化失败 (exit ${initialized.code})，插件尚未注册。`);
+        }
+    }
+}

package/dist/process.d.ts

@@ -10,6 +10,8 @@ export interface CommandResult {
 }
 export interface RunCommandOptions {
     capture?: boolean;
+    /** 显示并捕获输出，同时继承 stdin 以保留安装器交互。 */
+    tee?: boolean;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
     timeoutMs?: number;

package/dist/process.js

@@ -89,20 +89,22 @@ export function findExecutable(name, options = {}) {
     return null;
 }
 export const runCommand = (command, args, options = {}) => new Promise((resolve, reject) => {
-    const capture = options.capture === true;
+    const capture = options.capture === true || options.tee === true;
     const launch = resolveSpawnCommand(command, args);
     const child = spawn(launch.command, launch.args, {
         cwd: options.cwd,
         env: options.env,
-        stdio: capture ? ['ignore', 'pipe', 'pipe'] : 'inherit',
+        stdio: capture ? [options.tee ? 'inherit' : 'ignore', 'pipe', 'pipe'] : 'inherit',
         windowsHide: true,
     });
     let stdout = '';
     let stderr = '';
     let settled = false;
-    const append = (current, chunk) => current.length >= MAX_CAPTURE_LENGTH
-        ? current
-        : (current + chunk.toString('utf8')).slice(0, MAX_CAPTURE_LENGTH);
+    const append = (current, chunk) => options.tee
+        ? (current + chunk).slice(-MAX_CAPTURE_LENGTH)
+        : current.length >= MAX_CAPTURE_LENGTH
+            ? current
+            : (current + chunk).slice(0, MAX_CAPTURE_LENGTH);
     const finish = (error, code = 1) => {
         if (settled)
             return;
@@ -121,8 +123,16 @@ export const runCommand = (command, args, options = {}) => new Promise((resolve,
             finish(new Error(`Command timed out after ${options.timeoutMs}ms`));
         }, options.timeoutMs);
     if (capture) {
-        child.stdout?.on('data', chunk => (stdout = append(stdout, chunk)));
-        child.stderr?.on('data', chunk => (stderr = append(stderr, chunk)));
+        child.stdout?.setEncoding('utf8').on('data', (chunk) => {
+            stdout = append(stdout, chunk);
+            if (options.tee)
+                process.stdout.write(chunk);
+        });
+        child.stderr?.setEncoding('utf8').on('data', (chunk) => {
+            stderr = append(stderr, chunk);
+            if (options.tee)
+                process.stderr.write(chunk);
+        });
     }
     child.once('error', error => finish(error));
     child.once('close', code => finish(undefined, code ?? 1));

package/dist/provider.d.ts

@@ -0,0 +1,28 @@
+import { listInstalledProviders, registerProviderPackage, stopProvider, uninstallProvider, type InstalledProviderManifest } from '@mearl/provider/host';
+import { resolvePackageManagerInstallation, type PackageManagerInstallation } from './packageManager.js';
+import { findExecutable, type CommandRunner } from './process.js';
+interface ProviderPackageSpec {
+    packageName: string;
+    target: string;
+}
+export interface ProviderSetupDependencies {
+    existsSync?: (filePath: string) => boolean;
+    findExecutable?: typeof findExecutable;
+    listProviders?: typeof listInstalledProviders;
+    registerPackage?: typeof registerProviderPackage;
+    resolveInvokingManager?: (env: NodeJS.ProcessEnv) => PackageManagerInstallation;
+    resolvePackageManager?: typeof resolvePackageManagerInstallation;
+    resolvePackageRoot?: (installation: PackageManagerInstallation, packageName: string, runner: CommandRunner, env: NodeJS.ProcessEnv) => Promise<string>;
+    runCommand?: CommandRunner;
+    stopProvider?: typeof stopProvider;
+    unregisterProvider?: typeof uninstallProvider;
+}
+export interface ProviderSetupResult {
+    manifest: InstalledProviderManifest;
+    manager: PackageManagerInstallation['manager'];
+}
+export declare function parseProviderPackageSpec(value: string): ProviderPackageSpec;
+export declare function installProviderPackage(packageSpec: string, dependencies?: ProviderSetupDependencies): Promise<ProviderSetupResult>;
+export declare function updateProviderPackage(selector: string, dependencies?: ProviderSetupDependencies): Promise<ProviderSetupResult>;
+export declare function uninstallProviderPackage(selector: string, dependencies?: ProviderSetupDependencies): Promise<ProviderSetupResult>;
+export {};

package/dist/provider.js

@@ -0,0 +1,114 @@
+import { existsSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { listInstalledProviders, registerProviderPackage, stopProvider, uninstallProvider, } from '@mearl/provider/host';
+import { buildGlobalPackageCommand, resolveInvokingPackageManager, resolvePackageManagerInstallation, } from './packageManager.js';
+import { findExecutable, prependCommandPath, runCommand } from './process.js';
+export function parseProviderPackageSpec(value) {
+    const input = value.trim();
+    const nameMatch = input.match(/^(@[a-z0-9][a-z0-9._-]*\/[a-z0-9][a-z0-9._-]*|[a-z0-9][a-z0-9._-]*)(?:@(.+))?$/i);
+    if (!nameMatch || !nameMatch[1] || /\s/.test(nameMatch[2] ?? '')) {
+        throw new Error(`Provider install requires an npm package name, received: ${value}`);
+    }
+    return { packageName: nameMatch[1], target: nameMatch[2] || 'latest' };
+}
+function providerManager(packageName, env, dependencies) {
+    const resolved = (dependencies.resolveInvokingManager ??
+        (childEnv => resolveInvokingPackageManager({ env: childEnv })))(env);
+    if (!packageName.startsWith('@ali/') || resolved.command.includes('tnpm'))
+        return resolved;
+    const tnpm = (dependencies.findExecutable ?? findExecutable)('tnpm', {
+        env,
+        extraDirectories: [dirname(process.execPath)],
+    });
+    return tnpm ? { manager: 'npm', command: tnpm } : resolved;
+}
+function outputPath(output) {
+    const lines = output
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(Boolean);
+    return lines.at(-1) ?? null;
+}
+async function resolveGlobalProviderPackageRoot(installation, packageName, runner, env) {
+    let args;
+    let toNodeModules;
+    switch (installation.manager) {
+        case 'npm':
+        case 'pnpm':
+            args = ['root', '-g'];
+            toNodeModules = value => value;
+            break;
+        case 'yarn':
+            args = ['global', 'dir'];
+            toNodeModules = value => join(value, 'node_modules');
+            break;
+        case 'bun':
+            args = ['pm', 'bin', '-g'];
+            toNodeModules = value => resolve(value, '..', 'install', 'global', 'node_modules');
+            break;
+        case 'volta':
+            throw new Error('Volta cannot manage a Provider package without a binary; use npm or pnpm');
+    }
+    const result = await runner(installation.command, args, {
+        capture: true,
+        env: prependCommandPath(installation.command, env),
+    });
+    const root = outputPath(result.stdout);
+    if (result.code !== 0 || !root) {
+        throw new Error(`${installation.manager} global package root lookup failed`);
+    }
+    return join(toNodeModules(root), ...packageName.split('/'));
+}
+function findRegisteredProvider(selector, listProviders) {
+    const providers = listProviders();
+    const matches = providers.filter(provider => provider.providerId === selector || provider.packageName === selector);
+    if (matches.length === 0)
+        throw new Error(`Provider is not registered: ${selector}`);
+    if (matches.length > 1)
+        throw new Error(`Provider selector is ambiguous: ${selector}`);
+    return matches[0];
+}
+async function runPackageCommand(installation, operation, packageName, target, runner, env) {
+    const command = buildGlobalPackageCommand(installation, operation, [packageName], target);
+    const result = await runner(command.command, command.args, {
+        env: prependCommandPath(command.command, env),
+        tee: true,
+    });
+    if (result.code !== 0) {
+        throw new Error(`${packageName} ${operation} failed (exit ${result.code})`);
+    }
+}
+export async function installProviderPackage(packageSpec, dependencies = {}) {
+    const { packageName, target } = parseProviderPackageSpec(packageSpec);
+    const env = process.env;
+    const runner = dependencies.runCommand ?? runCommand;
+    const installation = providerManager(packageName, env, dependencies);
+    await runPackageCommand(installation, 'install', packageName, target, runner, env);
+    const packageRoot = await (dependencies.resolvePackageRoot ?? resolveGlobalProviderPackageRoot)(installation, packageName, runner, env);
+    if (!(dependencies.existsSync ?? existsSync)(join(packageRoot, 'package.json'))) {
+        throw new Error(`${packageName} was installed but its package root was not found: ${packageRoot}`);
+    }
+    const manifest = (dependencies.registerPackage ?? registerProviderPackage)(packageRoot);
+    return { manifest, manager: installation.manager };
+}
+export async function updateProviderPackage(selector, dependencies = {}) {
+    const listProviders = dependencies.listProviders ?? listInstalledProviders;
+    const current = findRegisteredProvider(selector, listProviders);
+    const env = process.env;
+    const runner = dependencies.runCommand ?? runCommand;
+    const installation = (dependencies.resolvePackageManager ?? resolvePackageManagerInstallation)(current.packageRoot, current.packageName) ?? providerManager(current.packageName, env, dependencies);
+    (dependencies.stopProvider ?? stopProvider)(current.providerId);
+    await runPackageCommand(installation, 'update', current.packageName, 'latest', runner, env);
+    const manifest = (dependencies.registerPackage ?? registerProviderPackage)(current.packageRoot);
+    return { manifest, manager: installation.manager };
+}
+export async function uninstallProviderPackage(selector, dependencies = {}) {
+    const listProviders = dependencies.listProviders ?? listInstalledProviders;
+    const manifest = findRegisteredProvider(selector, listProviders);
+    const env = process.env;
+    const installation = (dependencies.resolvePackageManager ?? resolvePackageManagerInstallation)(manifest.packageRoot, manifest.packageName) ?? providerManager(manifest.packageName, env, dependencies);
+    (dependencies.stopProvider ?? stopProvider)(manifest.providerId);
+    await runPackageCommand(installation, 'uninstall', manifest.packageName, 'latest', dependencies.runCommand ?? runCommand, env);
+    (dependencies.unregisterProvider ?? uninstallProvider)(manifest.providerId);
+    return { manifest, manager: installation.manager };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.11.0",
+  "version": "2.13.0",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -65,7 +65,8 @@
     "commander": "^15.0.0",
     "extract-zip": "^2.0.1",
     "ws": "^8.18.3",
-    "@mearl/client": "2.11.0"
+    "@mearl/client": "2.13.0",
+    "@mearl/provider": "2.13.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",