@mearl/setup 2.16.1 → 2.16.3

package/README.md

@@ -4,7 +4,8 @@ Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全
 
 ```bash
 npx @mearl/setup [install] [--local] [--cloud|--qoder-cloud] [--mcp]
-npx @mearl/setup <update|uninstall> [--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 install <ali-skills add 参数...>
@@ -38,12 +39,12 @@ setup 从 `Installed … skill(s)` 成功区块提取路径，仅注册本次安
 registry 可访问时通过 Ali Skills 批量处理 `mearl`、`buc-request` 与 `tdbank-account`：安装使用一次
 `add` 并注册两个插件，更新已跟踪项使用一次 `update`；卸载时使用一次 `remove` 批量移除 setup 管理的
 三项 Skill。
-更新发现某个官方插件缺少注册时，会在批量更新已跟踪项后通过一次 `add` 补装并恢复注册。
+更新发现 BUC 或 TDBank 插件缺少注册时，会在批量更新已跟踪项后通过一次 `add` 补装并恢复注册。
 该 registry 不用于下载插件。
 探测不可用时按普通外网流程只处理 Mearl Skill；内网批量命令失败时 setup 失败，不再逐项重试。
 `--skip-skill` 和 `--target-line` 安装不执行自动插件步骤。
 
-Mearl client 内置官方插件名称与安装来源目录。CLI、SDK、MCP 或另一个插件首次调用尚未注册的官方插件时，会通过内部幂等流程安装并重试一次；未知名称不会触发安装。
+Mearl client 内置 `buc` 与 `tdbank` 的安装来源。CLI、SDK、MCP 或另一个插件首次调用尚未注册的这两个插件时，会通过内部幂等流程安装并重试一次；其他未注册名称不会触发安装。
 
 自动注册默认使用安装目录名；入口可声明 `name` 指定简短命令名。
 重装会刷新同名绑定。JavaScript 入口必须默认导出 `register(app)`，Python 入口必须导出 `register(app)` 函数；完整协议见
@@ -61,7 +62,7 @@ path 接受目录或具体文件；目录默认读取 `scripts/main.mjs` 或 `sc
 两种注册流程都会检查本机 `@mearl/client` 和 `@mearl/native-host`：缺失或低于当前 setup 版本时，
 复用已有包管理器安装 setup 的对应版本，更新后再次验证；更高版本保持不动。
 native-host 会幂等初始化 Skills 模式。基础环境补齐或初始化失败时保留已安装的 skill，并停止注册。
-注册后可在任意目录运行 `mearl <name> --help`，也可通过 `@mearl/client` 的 `invokePlugin` 或 MCP 的 `mearl_plugin` 调用。已注册插件的日常调用不执行安装或版本检查；只有缺失的官方插件会触发一次按需安装。
+注册后可在任意目录运行 `mearl <name> --help`，也可通过 `@mearl/client` 的 `invokePlugin` 或 MCP 的 `mearl_plugin` 调用。已注册插件的日常调用不执行安装或版本检查；只有缺失的 `buc` 或 `tdbank` 会触发一次按需安装。
 
 不再需要插件时执行：
 
@@ -110,9 +111,13 @@ npx @mearl/setup provider uninstall brow
 - local/cloud 共用一份 `@mearl/client`；组合安装只处理一次，卸载单个环境时若另一个环境仍在使用则保留。
 - 从 2.5.x 更新 cloud 环境时会先卸载旧 `@mearl/cloud-client`，避免它遗留的 `mearl` bin 与统一 client 冲突。
 - local/cloud 共用的全局 mearl skill 通过 `ali-skills` 的 JSON 清单定位，只处理一次。
-- 安装始终通过 `ali-skills add` 写入最新的全局 mearl skill，并关联当前检测到的 Agent；
+- 安装始终通过 `ali-skills add --install-mode symlink` 写入最新的全局 mearl skill，并关联当前检测到的 Agent；
   可用 `--skip-skill` 跳过。
 - 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
+- `uninstall --full` 在环境卸载之外，还会逐项卸载所有已注册 CLI 插件与浏览器 Provider。
+  Ali Skills 安装的插件会同时移除 Skill；手工注册的外部插件只清除注册、保留源码；Provider
+  只有在包管理器成功卸载 npm 包后才清除注册。单项失败不阻止其他项继续清理，命令最终返回非零。
+  该选项不删除 Chrome 扩展；`extension --full` 仍表示安装扩展及完整本地环境。
 - `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
 - 默认的 `install` / `update` 不处理浏览器扩展。`extension` 是独立命令：从
   `https://mearl.alibaba-inc.com/` 识别并下载最新的 `mearl-chrome-v*.zip`，原子解压到
@@ -215,6 +220,9 @@ npx @mearl/setup uninstall --local
 # 自动检测并无交互卸载
 npx @mearl/setup uninstall --yes
 
+# 卸载环境，并清理全部 CLI 插件与 Provider
+npx @mearl/setup uninstall --full
+
 # 安装可选浏览器 Provider
 npx @mearl/setup provider install @ali/mearl-provider-brow
 npx @mearl/setup provider install @ali/mearl-provider-agentbay

package/dist/aliSkills.js

@@ -164,7 +164,16 @@ export async function runGlobalMearlSkillOperation(operation, options = {}) {
         }
     };
     if (operation === 'install') {
-        const installed = await run(['add', 'trip/mearl', '--skill', 'mearl', '--global', ...(options.yes ? ['--yes'] : [])], false);
+        const installed = await run([
+            'add',
+            'trip/mearl',
+            '--skill',
+            'mearl',
+            '--global',
+            '--install-mode',
+            'symlink',
+            ...(options.yes ? ['--yes'] : []),
+        ], false);
         if (!installed)
             return false;
         if (installed.code !== 0) {

package/dist/cli.js

@@ -70,8 +70,10 @@ export function parseSetupArgs(argv) {
             .option('--target-line <major.minor.x>')
             .option('--skip-skill')
             .option('-y, --yes')
-            .option('--non-interactive')
-            .action(() => {
+            .option('--non-interactive');
+        if (operation === 'uninstall')
+            command.option('--full');
+        command.action(() => {
             const options = command.opts();
             if (options.cloud && options.qoderCloud) {
                 throw new Error('--cloud and --qoder-cloud cannot be used together');
@@ -96,6 +98,7 @@ export function parseSetupArgs(argv) {
                     ? { cloudMode: options.qoderCloud ? 'qoder' : 'websocket' }
                     : {}),
                 ...(profiles.length > 0 ? { profiles } : {}),
+                ...(options.full ? { full: true } : {}),
                 skipSkill: options.skipSkill === true,
                 targetLine: options.targetLine,
                 yes: options.yes === true || options.nonInteractive === true,
@@ -150,63 +153,59 @@ export function parseSetupArgs(argv) {
         throw new Error('No setup operation was selected');
     return parsed;
 }
-function printHelp(toError = false) {
+function printHelp() {
     const output = `Mearl Setup v${SETUP_VERSION}
 
 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 [command] [options]
 
-Behavior:
-  install      Default command; defaults to --local when no environment is specified
-  update       Auto-detects installed environments from the current PATH
-  uninstall    Auto-detects installed environments and asks for confirmation
-  extension    Install or update the browser extension; --full also installs the local environment
-  plugin       Register, install, or uninstall a CLI plugin
-  provider     Install npm Provider packages and manage their Mearl registration
+Environment commands:
+  install [options]               Install an environment (default command; target: local)
+  update [options]                Update detected or selected environments
+  uninstall [options]             Uninstall detected or selected environments
 
-Options:
-  --local      Manage @mearl/native-host and @mearl/client
-  --cloud      Manage cloud packages in WebSocket server mode
-  --qoder-cloud
-               Manage the same cloud packages in Qoder pairing mode
-  --mcp        Manage @mearl/mcp-server and its configuration
-  --target-line <major.minor.x>
-               Install the latest packages from one release line, such as 2.3.x
-  --skip-skill Keep the independently managed Mearl Skill unchanged
-  --full       Also install @mearl/client, @mearl/native-host, and the Mearl Skill
-  --force      Replace an existing store, managed, or other local Mearl extension
-  --yes, -y    Run without prompts and accept detected defaults
-  --non-interactive
-               Alias for --yes, intended for Agents and CI
-  --version, -v
-               Show version
-  --help, -h   Show this help
+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
+  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
+
+Browser extension:
+  extension [--full] [--force]    Install or update the browser extension
+
+Environment options:
+  --local                         Manage @mearl/native-host and @mearl/client
+  --cloud                         Manage cloud packages in WebSocket server mode
+  --qoder-cloud                   Manage cloud packages in Qoder pairing mode
+  --mcp                           Manage @mearl/mcp-server and its configuration
+  --target-line <major.minor.x>   Use the latest packages in one release line
+  --skip-skill                    Keep the independently managed Mearl Skill unchanged
+
+Uninstall options:
+  --full                          Remove all CLI plugins and Provider packages/registrations
+
+Extension options:
+  --full                          Install the extension and complete local environment
+  --force                         Replace an extension managed by another source
+
+General options:
+  --yes, -y                       Accept prompts and detected defaults
+  --non-interactive               Alias for --yes, intended for Agents and CI
+  --version, -v                   Show version
+  --help, -h                      Show this help
 
 Examples:
   npx @mearl/setup
-  npx @mearl/setup --yes
-  npx @mearl/setup install
   npx @mearl/setup --cloud
   npx @mearl/setup --local --cloud
   npx @mearl/setup update
-  npx @mearl/setup extension
-  npx @mearl/setup extension --full
+  npx @mearl/setup uninstall --full
   npx @mearl/setup plugin uninstall yuque
   npx @mearl/setup provider install @ali/mearl-provider-brow
-  npx @mearl/setup provider install @ali/mearl-provider-agentbay
-  npx @mearl/setup --qoder-cloud --yes
-  npx @mearl/setup update --local --target-line 2.3.x --skip-skill
-  npx @mearl/setup uninstall --local`;
-    if (toError)
-        console.error(output);
-    else
-        console.log(output);
+  npx @mearl/setup extension --full`;
+    console.log(output);
 }
 export async function main(argv = process.argv.slice(2), interactiveTerminal = process.stdin.isTTY === true && process.stdout.isTTY === true, dependencies = {}) {
     let parsed;
@@ -215,7 +214,7 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
-        printHelp(true);
+        console.error('Run "npx @mearl/setup --help" for usage.');
         return 2;
     }
     if (parsed.help) {
@@ -346,6 +345,7 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
             operation: parsed.operation,
             profiles: parsed.profiles,
             cloudMode: parsed.cloudMode,
+            full: parsed.full,
             skipSkill: parsed.skipSkill,
             targetLine: parsed.targetLine,
             yes: parsed.yes,

package/dist/lifecycle.d.ts

@@ -1,13 +1,19 @@
+import { listPluginNames } from '@mearl/client/plugin';
+import { listInstalledProviders } from '@mearl/provider/host';
 import { runGlobalMearlSkillOperation } from './aliSkills.js';
 import { detectGlobalPackage, type PackageManagerInstallation } from './packageManager.js';
 import { type DetectedMearlProfiles, type MearlProfile } from './profiles.js';
 import { uninstallNativeHostArtifacts } from './nativeHost.js';
 import { type CommandRunner } from './process.js';
 import { installAlibabaInternalPlugins, uninstallAlibabaInternalPlugins } from './internalPlugins.js';
+import { uninstallPlugin } from './plugin.js';
+import { uninstallProviderPackage } from './provider.js';
 export type MearlLifecycleOperation = 'install' | 'update' | 'uninstall';
 export interface MearlLifecycleOptions {
     operation: MearlLifecycleOperation;
     cloudMode?: 'websocket' | 'qoder';
+    /** Uninstall every registered CLI plugin and Provider in addition to selected environments. */
+    full?: boolean;
     /** @deprecated Use profiles when selecting one or more composable environments. */
     profile?: MearlProfile;
     profiles?: MearlProfile[];
@@ -23,10 +29,14 @@ export interface MearlLifecycleDependencies {
     detectProfiles?: (env: NodeJS.ProcessEnv) => DetectedMearlProfiles;
     existsSync?: (filePath: string) => boolean;
     installInternalPlugins?: typeof installAlibabaInternalPlugins;
+    listPlugins?: typeof listPluginNames;
+    listProviders?: typeof listInstalledProviders;
     resolveInvokingManager?: (env: NodeJS.ProcessEnv) => PackageManagerInstallation;
     runCommand?: CommandRunner;
     runSkillOperation?: typeof runGlobalMearlSkillOperation;
     uninstallInternalPlugins?: typeof uninstallAlibabaInternalPlugins;
+    uninstallPlugin?: typeof uninstallPlugin;
+    uninstallProvider?: typeof uninstallProviderPackage;
     writeLine?: (line: string) => void;
 }
 export declare function runMearlLifecycle(options: MearlLifecycleOptions, dependencies?: MearlLifecycleDependencies): Promise<boolean>;

package/dist/lifecycle.js

@@ -2,6 +2,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createInterface } from 'node:readline/promises';
 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 { MEARL_PROFILES, detectMearlProfiles, } from './profiles.js';
@@ -9,6 +11,8 @@ import { uninstallNativeHostArtifacts } from './nativeHost.js';
 import { executableNames, prependCommandPath, runCommand, } from './process.js';
 import { isMearlReleaseLine } from './version.js';
 import { installAlibabaInternalPlugins, uninstallAlibabaInternalPlugins, } from './internalPlugins.js';
+import { uninstallPlugin } from './plugin.js';
+import { uninstallProviderPackage } from './provider.js';
 const LEGACY_CLOUD_CLIENT = '@mearl/cloud-client';
 const UNIFIED_CLIENT = '@mearl/client';
 const PROFILE_ORDER = ['local', 'cloud', 'mcp'];
@@ -152,7 +156,37 @@ export async function runMearlLifecycle(options, dependencies = {}) {
     const detected = detectProfiles(env);
     const requestedProfiles = options.profiles ?? (options.profile ? [options.profile] : undefined);
     const selected = selectedProfiles(options.operation, requestedProfiles, detected);
-    if (selected.length === 0) {
+    const lifecycleSelected = options.operation === 'uninstall'
+        ? selected.filter(profile => detected.has(profile))
+        : selected;
+    let fullPluginNames = [];
+    let fullProviders = [];
+    if (options.operation === 'uninstall' && options.full) {
+        try {
+            fullPluginNames = (dependencies.listPlugins ?? listPluginNames)();
+        }
+        catch (error) {
+            writeLine(`CLI plugins: unable to list registrations: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+        try {
+            fullProviders = (dependencies.listProviders ?? listInstalledProviders)();
+        }
+        catch (error) {
+            writeLine(`Providers: unable to list registrations: ${error instanceof Error ? error.message : String(error)}`);
+            return false;
+        }
+    }
+    const hasFullIntegrationTargets = fullPluginNames.length > 0 || fullProviders.length > 0;
+    if (options.operation === 'uninstall' &&
+        options.full &&
+        lifecycleSelected.length === 0 &&
+        !hasFullIntegrationTargets) {
+        writeLine('No installed Mearl environments, CLI plugins, or Providers were detected.');
+        return true;
+    }
+    if (selected.length === 0 &&
+        !(options.operation === 'uninstall' && options.full && hasFullIntegrationTargets)) {
         writeLine('No installed Mearl environment was detected on the current PATH.');
         if (options.operation === 'uninstall')
             return true;
@@ -167,22 +201,33 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         }
     }
     if (options.operation === 'uninstall') {
-        const installedSelected = selected.filter(profile => detected.has(profile));
-        if (installedSelected.length === 0) {
+        if (lifecycleSelected.length === 0 && !options.full) {
             writeLine(`Nothing to uninstall for ${selected.join(', ')}.`);
             return true;
         }
+        if (options.full) {
+            writeLine(`CLI plugins: ${fullPluginNames.length > 0 ? fullPluginNames.join(', ') : 'none detected'}.`);
+            writeLine(`Providers: ${fullProviders.length > 0
+                ? fullProviders.map(provider => provider.providerId).join(', ')
+                : 'none detected'}.`);
+        }
         if (!options.yes &&
-            !(await confirm(`Uninstall Mearl environments: ${installedSelected.join(', ')}?`))) {
+            !(await confirm(options.full
+                ? `Uninstall ${lifecycleSelected.length > 0
+                    ? `Mearl environments (${lifecycleSelected.join(', ')}) and `
+                    : ''}all CLI plugins and Providers?`
+                : `Uninstall Mearl environments: ${lifecycleSelected.join(', ')}?`))) {
             writeLine('Uninstall cancelled.');
             return false;
         }
     }
-    writeLine(`${operationVerb(options.operation)} targets: ${selected
-        .map(profile => MEARL_PROFILES[profile].label)
-        .join(', ')}`);
+    if (lifecycleSelected.length > 0) {
+        writeLine(`${operationVerb(options.operation)} targets: ${lifecycleSelected
+            .map(profile => MEARL_PROFILES[profile].label)
+            .join(', ')}`);
+    }
     let packagesOk = true;
-    if (selected.includes('cloud')) {
+    if (lifecycleSelected.includes('cloud')) {
         const legacyCloudClient = detectPackage(LEGACY_CLOUD_CLIENT, ['mearl-cloud'], { env });
         if (legacyCloudClient?.packageName === LEGACY_CLOUD_CLIENT) {
             const command = buildGlobalPackageCommand(legacyCloudClient, 'uninstall', [
@@ -198,13 +243,13 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             }
         }
     }
-    const selectedUsesClient = selected.some(profile => CLIENT_PROFILES.includes(profile));
+    const selectedUsesClient = lifecycleSelected.some(profile => CLIENT_PROFILES.includes(profile));
     const detectedClientCandidate = selectedUsesClient
         ? detectPackage(UNIFIED_CLIENT, ['mearl'], { env })
         : null;
     const detectedClient = detectedClientCandidate?.packageName === UNIFIED_CLIENT ? detectedClientCandidate : null;
     const remainingClientProfiles = selectedUsesClient && options.operation === 'uninstall'
-        ? CLIENT_PROFILES.filter(profile => detected.has(profile) && !selected.includes(profile))
+        ? CLIENT_PROFILES.filter(profile => detected.has(profile) && !lifecycleSelected.includes(profile))
         : [];
     if (selectedUsesClient && options.operation !== 'uninstall') {
         const clientInstallation = detectedClient ??
@@ -217,7 +262,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             return false;
         }
     }
-    for (const profile of selected) {
+    for (const profile of lifecycleSelected) {
         const config = MEARL_PROFILES[profile];
         const current = detected.get(profile);
         if (options.operation === 'uninstall' && !current)
@@ -277,8 +322,40 @@ export async function runMearlLifecycle(options, dependencies = {}) {
                 packagesOk = false;
         }
     }
-    const selectedUsesSkill = selected.some(profile => MEARL_PROFILES[profile].usesSkill);
-    const remainingSkillProfiles = ['local', 'cloud'].filter(profile => detected.has(profile) && !selected.includes(profile));
+    let fullOk = true;
+    if (options.operation === 'uninstall' && options.full) {
+        const pendingPlugins = new Set(fullPluginNames);
+        const removePlugin = dependencies.uninstallPlugin ?? uninstallPlugin;
+        while (pendingPlugins.size > 0) {
+            const name = pendingPlugins.values().next().value;
+            pendingPlugins.delete(name);
+            try {
+                const result = await removePlugin(name, runner);
+                for (const removedName of result.unregisteredNames)
+                    pendingPlugins.delete(removedName);
+                if (result.removed) {
+                    writeLine(`CLI plugin ${name}: uninstalled.`);
+                }
+            }
+            catch (error) {
+                fullOk = false;
+                writeLine(`CLI plugin ${name}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        const removeProvider = dependencies.uninstallProvider ?? uninstallProviderPackage;
+        for (const provider of fullProviders) {
+            try {
+                await removeProvider(provider.providerId);
+                writeLine(`Provider ${provider.providerId}: uninstalled.`);
+            }
+            catch (error) {
+                fullOk = false;
+                writeLine(`Provider ${provider.providerId}: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+    }
+    const selectedUsesSkill = lifecycleSelected.some(profile => MEARL_PROFILES[profile].usesSkill);
+    const remainingSkillProfiles = ['local', 'cloud'].filter(profile => detected.has(profile) && !lifecycleSelected.includes(profile));
     let runStandaloneSkill = true;
     let skillOk = true;
     if (packagesOk &&
@@ -354,7 +431,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             skillOk = false;
         }
     }
-    if (packagesOk && skillOk) {
+    if (packagesOk && skillOk && fullOk) {
         writeLine('Mearl setup complete.');
         return true;
     }

package/package.json

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