@mearl/setup 2.15.0 → 2.15.1

package/README.md

@@ -35,10 +35,12 @@ setup 从 `Installed … skill(s)` 成功区块提取路径，仅注册本次安
 普通 skill 正常安装。输出格式无法识别时提示手动注册，不扫描其他 skill 或猜测安装结果。
 
 默认 `install` 和 `update` 完成后，setup 会用最多 5 秒的 `npm ping` 检查阿里内网 registry。
-可访问时通过上述 Ali Skills 链路自动安装并注册 `tdbank-account`；该 registry 不用于下载插件。
+可访问时通过上述 Ali Skills 链路依次自动安装并注册 `buc-request` 与 `tdbank-account`；该 registry 不用于下载插件。
 探测不可用或插件安装失败不会破坏 Mearl 主环境的安装；`--skip-skill` 和
 `--target-line` 安装不执行自动插件步骤。
 
+Mearl client 内置官方插件名称与安装来源目录。CLI、SDK、MCP 或另一个插件首次调用尚未注册的官方插件时，会通过内部幂等流程安装并重试一次；未知名称不会触发安装。
+
 自动注册默认使用安装目录名；入口可用 `export const name = 'yuque'` 指定简短命令名。
 重装会刷新同名绑定。每个入口必须默认导出 `register(app)`；完整协议见
 [Skill 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
@@ -55,7 +57,7 @@ path 接受目录或具体文件；目录默认读取 `scripts/main.mjs`，相
 两种注册流程都会检查本机 `@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` 调用。已注册插件的日常调用不执行安装或版本检查；只有缺失的官方插件会触发一次按需安装。
 
 不再需要插件时执行：
 

package/dist/cli.d.ts

@@ -2,7 +2,7 @@
 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 { ensureOfficialPlugin, installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
 import { installProviderPackage, uninstallProviderPackage, updateProviderPackage } from './provider.js';
 export declare const SETUP_VERSION: string;
 interface ParsedArgs {
@@ -14,6 +14,7 @@ interface ParsedArgs {
     pluginName?: string;
     pluginPath?: string;
     pluginInstallArgs?: string[];
+    pluginEnsureName?: string;
     pluginUninstallName?: string;
     providerCommand?: 'install' | 'uninstall' | 'update';
     providerTarget?: string;
@@ -25,6 +26,7 @@ interface ParsedArgs {
 }
 export interface SetupCliDependencies {
     registerPlugin?: typeof setupPlugin;
+    ensureOfficialPlugin?: typeof ensureOfficialPlugin;
     installPlugins?: typeof installPlugins;
     uninstallPlugin?: typeof uninstallPlugin;
     installBrowserExtension?: typeof installMearlBrowserExtension;

package/dist/cli.js

@@ -4,7 +4,7 @@ import { Command, CommanderError } from 'commander';
 import { installMearlBrowserExtension } from './browserExtension.js';
 import { runMearlLifecycle } from './lifecycle.js';
 import { isMearlReleaseLine } from './version.js';
-import { installPlugins, setupPlugin, uninstallPlugin } from './plugin.js';
+import { ensureOfficialPlugin, 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;
@@ -41,6 +41,12 @@ export function parseSetupArgs(argv) {
     if (argv[0] === 'plugin' && argv[1] === 'install') {
         return { ...baseParsedArgs(), operation: 'plugin', pluginInstallArgs: argv.slice(2) };
     }
+    if (argv[0] === 'plugin' && argv[1] === 'ensure') {
+        if (argv.length !== 3 || !argv[2]) {
+            throw new Error('plugin ensure requires exactly one official plugin name');
+        }
+        return { ...baseParsedArgs(), operation: 'plugin', pluginEnsureName: argv[2] };
+    }
     if (argv[0] === 'plugin' && argv[1] === 'uninstall') {
         if (argv.length !== 3 || !argv[2]) {
             throw new Error('plugin uninstall requires exactly one plugin name');
@@ -225,6 +231,13 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
             if (parsed.pluginInstallArgs) {
                 return await (dependencies.installPlugins ?? installPlugins)(parsed.pluginInstallArgs);
             }
+            if (parsed.pluginEnsureName) {
+                const result = await (dependencies.ensureOfficialPlugin ?? ensureOfficialPlugin)(parsed.pluginEnsureName);
+                console.error(result === 'installed'
+                    ? `Official plugin ${parsed.pluginEnsureName} installed.`
+                    : `Official plugin ${parsed.pluginEnsureName} is already registered.`);
+                return 0;
+            }
             if (parsed.pluginUninstallName) {
                 const result = await (dependencies.uninstallPlugin ?? uninstallPlugin)(parsed.pluginUninstallName);
                 if (!result.removed) {

package/dist/internalPlugins.d.ts

@@ -2,8 +2,7 @@ import { findPluginRegistration } from '@mearl/client/plugin';
 import { installPlugins, uninstallPlugin } from './plugin.js';
 import { findExecutable, type CommandRunner } from './process.js';
 export declare const ALIBABA_NPM_REGISTRY = "https://registry.anpm.alibaba-inc.com/";
-export declare const TDBANK_PLUGIN_INSTALL_ARGS: readonly ["trip/mearl", "--skill", "tdbank-account", "--yes"];
-export declare const INTERNAL_PLUGIN_MANAGER = "@mearl/setup";
+export declare const ALIBABA_INTERNAL_PLUGIN_NAMES: string[];
 export interface InternalPluginOptions {
     env?: NodeJS.ProcessEnv;
     runCommand?: CommandRunner;
@@ -17,6 +16,6 @@ export interface InternalPluginDependencies {
     uninstallPlugin?: typeof uninstallPlugin;
 }
 export declare function canAccessAlibabaNpmRegistry(options?: InternalPluginOptions, dependencies?: Pick<InternalPluginDependencies, 'findExecutable'>): Promise<boolean>;
-/** Uses the internal registry only as an intranet probe; the plugin is installed by Ali Skills. */
+/** Uses the internal registry only as an intranet probe; Ali Skills installs the plugins. */
 export declare function installAlibabaInternalPlugins(options?: InternalPluginOptions, dependencies?: InternalPluginDependencies): Promise<'installed' | 'skipped' | 'failed'>;
 export declare function uninstallAlibabaInternalPlugins(options?: InternalPluginOptions, dependencies?: InternalPluginDependencies): Promise<'uninstalled' | 'skipped' | 'failed'>;

package/dist/internalPlugins.js

@@ -1,16 +1,9 @@
 import { dirname } from 'node:path';
-import { findPluginRegistration } from '@mearl/client/plugin';
+import { findOfficialPlugin, findPluginRegistration, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, } from '@mearl/client/plugin';
 import { installPlugins, uninstallPlugin } from './plugin.js';
 import { findExecutable, prependCommandPath, runCommand } from './process.js';
 export const ALIBABA_NPM_REGISTRY = 'https://registry.anpm.alibaba-inc.com/';
-export const TDBANK_PLUGIN_INSTALL_ARGS = [
-    'trip/mearl',
-    '--skill',
-    'tdbank-account',
-    '--yes',
-];
-export const INTERNAL_PLUGIN_MANAGER = '@mearl/setup';
-const TDBANK_PLUGIN_NAME = 'tdbank';
+export const ALIBABA_INTERNAL_PLUGIN_NAMES = listOfficialPluginNames('alibaba');
 export async function canAccessAlibabaNpmRegistry(options = {}, dependencies = {}) {
     const env = options.env ?? process.env;
     const runner = options.runCommand ?? runCommand;
@@ -38,48 +31,67 @@ export async function canAccessAlibabaNpmRegistry(options = {}, dependencies = {
         return false;
     }
 }
-/** Uses the internal registry only as an intranet probe; the plugin is installed by Ali Skills. */
+/** Uses the internal registry only as an intranet probe; Ali Skills installs the plugins. */
 export async function installAlibabaInternalPlugins(options = {}, dependencies = {}) {
     const writeLine = options.writeLine ?? (line => console.error(line));
-    try {
-        const registration = (dependencies.findPluginRegistration ?? findPluginRegistration)(TDBANK_PLUGIN_NAME);
-        if (registration && registration.managedBy !== INTERNAL_PLUGIN_MANAGER) {
-            writeLine('TDBank plugin: existing user registration kept.');
-            return 'skipped';
+    const registrationFor = dependencies.findPluginRegistration ?? findPluginRegistration;
+    const candidates = ALIBABA_INTERNAL_PLUGIN_NAMES.filter(name => {
+        const registration = registrationFor(name);
+        if (registration && registration.managedBy !== OFFICIAL_PLUGIN_MANAGER) {
+            writeLine(`${name} plugin: existing user registration kept.`);
+            return false;
+        }
+        return true;
+    });
+    if (candidates.length === 0)
+        return 'skipped';
+    const probe = dependencies.probeAlibabaRegistry ?? (input => canAccessAlibabaNpmRegistry(input));
+    if (!(await probe(options)))
+        return 'skipped';
+    let installed = false;
+    let failed = false;
+    for (const name of candidates) {
+        const definition = findOfficialPlugin(name);
+        try {
+            const code = await (dependencies.installPlugins ?? installPlugins)([...definition.installArgs], options.runCommand, { registrationManagedBy: OFFICIAL_PLUGIN_MANAGER });
+            if (code !== 0) {
+                failed = true;
+                writeLine(`${name} plugin: install failed (exit ${code}).`);
+                continue;
+            }
+            installed = true;
+            writeLine(`${name} plugin: installed and registered.`);
         }
-        const probe = dependencies.probeAlibabaRegistry ?? (input => canAccessAlibabaNpmRegistry(input));
-        if (!(await probe(options)))
-            return 'skipped';
-        const code = await (dependencies.installPlugins ?? installPlugins)([...TDBANK_PLUGIN_INSTALL_ARGS], options.runCommand, { registrationManagedBy: INTERNAL_PLUGIN_MANAGER });
-        if (code !== 0) {
-            writeLine(`TDBank plugin: install failed (exit ${code}).`);
-            return 'failed';
+        catch (error) {
+            failed = true;
+            writeLine(`${name} plugin: ${error instanceof Error ? error.message : String(error)}; skipped.`);
         }
-        writeLine('TDBank plugin: installed and registered.');
-        return 'installed';
-    }
-    catch (error) {
-        writeLine(`TDBank plugin: ${error instanceof Error ? error.message : String(error)}; skipped.`);
-        return 'failed';
     }
+    return failed ? 'failed' : installed ? 'installed' : 'skipped';
 }
 export async function uninstallAlibabaInternalPlugins(options = {}, dependencies = {}) {
     const writeLine = options.writeLine ?? (line => console.error(line));
-    try {
-        const registration = (dependencies.findPluginRegistration ?? findPluginRegistration)(TDBANK_PLUGIN_NAME);
-        if (registration?.managedBy !== INTERNAL_PLUGIN_MANAGER) {
-            if (registration)
-                writeLine('TDBank plugin: existing user registration kept.');
-            return 'skipped';
+    const registrationFor = dependencies.findPluginRegistration ?? findPluginRegistration;
+    let uninstalled = false;
+    let failed = false;
+    for (const name of [...ALIBABA_INTERNAL_PLUGIN_NAMES].reverse()) {
+        try {
+            const registration = registrationFor(name);
+            if (registration?.managedBy !== OFFICIAL_PLUGIN_MANAGER) {
+                if (registration)
+                    writeLine(`${name} plugin: existing user registration kept.`);
+                continue;
+            }
+            const result = await (dependencies.uninstallPlugin ?? uninstallPlugin)(name, options.runCommand);
+            if (!result.removed)
+                continue;
+            uninstalled = true;
+            writeLine(`${name} plugin: uninstalled.`);
+        }
+        catch (error) {
+            failed = true;
+            writeLine(`${name} plugin: ${error instanceof Error ? error.message : String(error)}; uninstall failed.`);
         }
-        const result = await (dependencies.uninstallPlugin ?? uninstallPlugin)(TDBANK_PLUGIN_NAME, options.runCommand);
-        if (!result.removed)
-            return 'skipped';
-        writeLine('TDBank plugin: uninstalled.');
-        return 'uninstalled';
-    }
-    catch (error) {
-        writeLine(`TDBank plugin: ${error instanceof Error ? error.message : String(error)}; uninstall failed.`);
-        return 'failed';
     }
+    return failed ? 'failed' : uninstalled ? 'uninstalled' : 'skipped';
 }

package/dist/lifecycle.js

@@ -313,7 +313,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
     if (packagesOk && skillOk && selectedUsesClient && options.skipSkill !== true) {
         if (options.operation === 'uninstall') {
             if (remainingClientProfiles.length > 0) {
-                writeLine(`TDBank plugin: kept for ${remainingClientProfiles.join(', ')}.`);
+                writeLine(`Internal plugins: kept for ${remainingClientProfiles.join(', ')}.`);
             }
             else {
                 try {
@@ -325,7 +325,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
                         })) !== 'failed';
                 }
                 catch (error) {
-                    writeLine(`TDBank plugin: ${error instanceof Error ? error.message : String(error)}; uninstall failed.`);
+                    writeLine(`Internal plugins: ${error instanceof Error ? error.message : String(error)}; uninstall failed.`);
                     internalPluginsOk = false;
                 }
             }
@@ -339,7 +339,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
                 });
             }
             catch (error) {
-                writeLine(`TDBank plugin: ${error instanceof Error ? error.message : String(error)}; skipped.`);
+                writeLine(`Internal plugins: ${error instanceof Error ? error.message : String(error)}; skipped.`);
             }
         }
     }

package/dist/plugin.d.ts

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

package/dist/plugin.js

@@ -1,7 +1,7 @@
 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 { assertPluginName, findOfficialPlugin, findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, OFFICIAL_PLUGIN_MANAGER, 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';
@@ -21,6 +21,22 @@ export async function setupPlugin(name, target) {
     await ensurePluginRuntime();
     return registerPlugin(name, entry, plugin.description);
 }
+export async function ensureOfficialPlugin(name, runner = runCommand) {
+    const definition = findOfficialPlugin(name);
+    if (!definition)
+        throw new Error(`未知官方插件: ${name}`);
+    if (findPluginRegistration(name))
+        return 'existing';
+    const code = await installPlugins([...definition.installArgs], runner, {
+        registrationManagedBy: OFFICIAL_PLUGIN_MANAGER,
+    });
+    if (code !== 0)
+        throw new Error(`官方插件 ${name} 安装失败 (exit ${code})`);
+    const registration = findPluginRegistration(name);
+    if (!registration)
+        throw new Error(`官方插件 ${name} 安装完成后仍未注册`);
+    return 'installed';
+}
 function globalAliSkill(entry) {
     const globalSkillsDirectory = join(homedir(), '.agents', 'skills');
     const relativeEntry = relative(globalSkillsDirectory, resolve(entry));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.15.0",
+  "version": "2.15.1",
   "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.15.0",
-    "@mearl/provider": "2.15.0"
+    "@mearl/client": "2.15.1",
+    "@mearl/provider": "2.15.1"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",