@mearl/setup 2.15.3 → 2.16.1

package/README.md

@@ -31,18 +31,22 @@ 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。
+setup 从 `Installed … skill(s)` 成功区块提取路径，仅注册本次安装且包含 `scripts/main.mjs` 或 `scripts/main.py` 的 skill；两者同时存在时使用 JavaScript 入口。
 普通 skill 正常安装。输出格式无法识别时提示手动注册，不扫描其他 skill 或猜测安装结果。
 
-默认 `install` 和 `update` 完成后，setup 会用最多 5 秒的 `npm ping` 检查阿里内网 registry。
-可访问时通过上述 Ali Skills 链路依次自动安装并注册 `buc-request` 与 `tdbank-account`；该 registry 不用于下载插件。
-探测不可用或插件安装失败不会破坏 Mearl 主环境的安装；`--skip-skill` 和
-`--target-line` 安装不执行自动插件步骤。
+默认 `install` 和 `update` 会用最多 5 秒的 `npm ping` 检查阿里内网 registry。
+registry 可访问时通过 Ali Skills 批量处理 `mearl`、`buc-request` 与 `tdbank-account`：安装使用一次
+`add` 并注册两个插件，更新已跟踪项使用一次 `update`；卸载时使用一次 `remove` 批量移除 setup 管理的
+三项 Skill。
+更新发现某个官方插件缺少注册时，会在批量更新已跟踪项后通过一次 `add` 补装并恢复注册。
+该 registry 不用于下载插件。
+探测不可用时按普通外网流程只处理 Mearl Skill；内网批量命令失败时 setup 失败，不再逐项重试。
+`--skip-skill` 和 `--target-line` 安装不执行自动插件步骤。
 
 Mearl client 内置官方插件名称与安装来源目录。CLI、SDK、MCP 或另一个插件首次调用尚未注册的官方插件时，会通过内部幂等流程安装并重试一次；未知名称不会触发安装。
 
-自动注册默认使用安装目录名；入口可用 `export const name = 'yuque'` 指定简短命令名。
-重装会刷新同名绑定。每个入口必须默认导出 `register(app)`；完整协议见
+自动注册默认使用安装目录名；入口可声明 `name` 指定简短命令名。
+重装会刷新同名绑定。JavaScript 入口必须默认导出 `register(app)`，Python 入口必须导出 `register(app)` 函数；完整协议见
 [Skill 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
 
 已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
@@ -52,7 +56,7 @@ npx @mearl/setup plugin yuque /absolute/path/to/yuque-doc-fetch
 npx @mearl/setup plugin custom ./skills/custom/entry.mjs
 ```
 
-path 接受目录或具体文件；目录默认读取 `scripts/main.mjs`，相对路径基于调用工作目录解析。
+path 接受目录或具体文件；目录默认读取 `scripts/main.mjs` 或 `scripts/main.py`，相对路径基于调用工作目录解析。Python 插件要求 `python3 >= 3.9`，可通过 `MEARL_PYTHON` 指定解释器路径；setup 只验证入口可加载，不安装 Python，也不执行 `pip install`。
 命令检查入口注册函数，然后保存绝对入口路径，同名注册更新绑定。
 两种注册流程都会检查本机 `@mearl/client` 和 `@mearl/native-host`：缺失或低于当前 setup 版本时，
 复用已有包管理器安装 setup 的对应版本，更新后再次验证；更高版本保持不动。

package/dist/internalPlugins.d.ts

@@ -1,10 +1,13 @@
-import { findPluginRegistration } from '@mearl/client/plugin';
-import { installPlugins, uninstallPlugin } from './plugin.js';
+import { findPluginRegistration, listPluginNames, unregisterPlugin } from '@mearl/client/plugin';
+import { resolveAliSkillsInvocation } from './aliSkills.js';
+import { installPlugins } 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 ALIBABA_INTERNAL_PLUGIN_NAMES: string[];
 export interface InternalPluginOptions {
     env?: NodeJS.ProcessEnv;
+    includeMearlSkill?: boolean;
+    mearlSkillOperation?: 'install' | 'update';
     runCommand?: CommandRunner;
     writeLine?: (line: string) => void;
 }
@@ -12,8 +15,10 @@ export interface InternalPluginDependencies {
     findExecutable?: typeof findExecutable;
     findPluginRegistration?: typeof findPluginRegistration;
     installPlugins?: typeof installPlugins;
+    listPluginNames?: typeof listPluginNames;
     probeAlibabaRegistry?: (options: InternalPluginOptions) => Promise<boolean>;
-    uninstallPlugin?: typeof uninstallPlugin;
+    resolveAliSkillsInvocation?: typeof resolveAliSkillsInvocation;
+    unregisterPlugin?: typeof unregisterPlugin;
 }
 export declare function canAccessAlibabaNpmRegistry(options?: InternalPluginOptions, dependencies?: Pick<InternalPluginDependencies, 'findExecutable'>): Promise<boolean>;
 /** Uses the internal registry only as an intranet probe; Ali Skills installs the plugins. */

package/dist/internalPlugins.js

@@ -1,6 +1,7 @@
 import { dirname } from 'node:path';
-import { findOfficialPlugin, findPluginRegistration, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, } from '@mearl/client/plugin';
-import { installPlugins, uninstallPlugin } from './plugin.js';
+import { findOfficialPlugin, findPluginRegistration, listPluginNames, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, unregisterPlugin, } from '@mearl/client/plugin';
+import { resolveAliSkillsInvocation } from './aliSkills.js';
+import { installPlugins } from './plugin.js';
 import { findExecutable, prependCommandPath, runCommand } from './process.js';
 export const ALIBABA_NPM_REGISTRY = 'https://registry.anpm.alibaba-inc.com/';
 export const ALIBABA_INTERNAL_PLUGIN_NAMES = listOfficialPluginNames('alibaba');
@@ -35,12 +36,15 @@ export async function canAccessAlibabaNpmRegistry(options = {}, dependencies = {
 export async function installAlibabaInternalPlugins(options = {}, dependencies = {}) {
     const writeLine = options.writeLine ?? (line => console.error(line));
     const registrationFor = dependencies.findPluginRegistration ?? findPluginRegistration;
+    const missingRegistrations = new Set();
     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;
         }
+        if (!registration)
+            missingRegistrations.add(name);
         return true;
     });
     if (candidates.length === 0)
@@ -48,50 +52,145 @@ export async function installAlibabaInternalPlugins(options = {}, dependencies =
     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;
+    if (options.mearlSkillOperation === 'update') {
+        const registeredCandidates = candidates.filter(name => !missingRegistrations.has(name));
+        const missingCandidates = candidates.filter(name => missingRegistrations.has(name));
+        const updateSkillNames = [
+            ...(options.includeMearlSkill ? ['mearl'] : []),
+            ...registeredCandidates.map(name => findOfficialPlugin(name).skill),
+        ];
+        if (updateSkillNames.length > 0) {
+            const invocation = (dependencies.resolveAliSkillsInvocation ?? resolveAliSkillsInvocation)({
+                env: options.env,
+            });
+            if (!invocation) {
+                writeLine('Internal skill batch: ali-skills and npx are both unavailable; update failed.');
+                return 'failed';
+            }
+            try {
+                const updated = await (options.runCommand ?? runCommand)(invocation.command, [...invocation.argsPrefix, 'update', ...updateSkillNames, '--global', '--yes'], { env: invocation.env, tee: true });
+                if (updated.code !== 0) {
+                    writeLine(`Internal skill batch: update failed (exit ${updated.code}).`);
+                    return 'failed';
+                }
+                if (options.includeMearlSkill)
+                    writeLine('Skill: updated.');
+                for (const name of registeredCandidates)
+                    writeLine(`${name} plugin: updated.`);
+            }
+            catch (error) {
+                writeLine(`Internal skill batch: ${error instanceof Error ? error.message : String(error)}; update failed.`);
+                return 'failed';
+            }
+        }
+        if (missingCandidates.length > 0) {
+            const repairArgs = [
+                'trip/mearl',
+                '--skill',
+                ...missingCandidates.map(name => findOfficialPlugin(name).skill),
+                '--yes',
+            ];
+            try {
+                const code = await (dependencies.installPlugins ?? installPlugins)(repairArgs, options.runCommand, { registrationManagedBy: OFFICIAL_PLUGIN_MANAGER });
+                if (code !== 0) {
+                    writeLine(`Internal skill batch: registration repair failed (exit ${code}).`);
+                    return 'failed';
+                }
+                for (const name of missingCandidates) {
+                    writeLine(`${name} plugin: installed and registered.`);
+                }
+            }
+            catch (error) {
+                writeLine(`Internal skill batch: ${error instanceof Error ? error.message : String(error)}; registration repair failed.`);
+                return 'failed';
             }
-            installed = true;
-            writeLine(`${name} plugin: installed and registered.`);
         }
-        catch (error) {
-            failed = true;
-            writeLine(`${name} plugin: ${error instanceof Error ? error.message : String(error)}; skipped.`);
+        return 'installed';
+    }
+    const skillNames = [
+        ...(options.includeMearlSkill ? ['mearl'] : []),
+        ...candidates.map(name => findOfficialPlugin(name).skill),
+    ];
+    const args = ['trip/mearl', '--skill', ...skillNames, '--yes'];
+    try {
+        const code = await (dependencies.installPlugins ?? installPlugins)(args, options.runCommand, {
+            registrationManagedBy: OFFICIAL_PLUGIN_MANAGER,
+        });
+        if (code !== 0) {
+            writeLine(`Internal skill batch: install failed (exit ${code}).`);
+            return 'failed';
         }
+        if (options.includeMearlSkill)
+            writeLine('Skill: installed.');
+        for (const name of candidates)
+            writeLine(`${name} plugin: installed and registered.`);
+        return 'installed';
+    }
+    catch (error) {
+        writeLine(`Internal skill batch: ${error instanceof Error ? error.message : String(error)}; install failed.`);
+        return 'failed';
     }
-    return failed ? 'failed' : installed ? 'installed' : 'skipped';
 }
 export async function uninstallAlibabaInternalPlugins(options = {}, dependencies = {}) {
     const writeLine = options.writeLine ?? (line => console.error(line));
     const registrationFor = dependencies.findPluginRegistration ?? findPluginRegistration;
-    let uninstalled = false;
-    let failed = false;
-    for (const name of [...ALIBABA_INTERNAL_PLUGIN_NAMES].reverse()) {
+    const removedSkillDirectories = new Set();
+    const candidates = ALIBABA_INTERNAL_PLUGIN_NAMES.filter(name => {
+        const registration = registrationFor(name);
+        if (!registration)
+            return false;
+        if (registration.managedBy !== OFFICIAL_PLUGIN_MANAGER) {
+            writeLine(`${name} plugin: existing user registration kept.`);
+            return false;
+        }
+        removedSkillDirectories.add(dirname(dirname(registration.entry)));
+        return true;
+    });
+    const skillNames = [
+        ...(options.includeMearlSkill ? ['mearl'] : []),
+        ...candidates.map(name => findOfficialPlugin(name).skill),
+    ];
+    if (skillNames.length === 0)
+        return 'skipped';
+    const invocation = (dependencies.resolveAliSkillsInvocation ?? resolveAliSkillsInvocation)({
+        env: options.env,
+    });
+    if (!invocation) {
+        writeLine('Internal skill batch: ali-skills and npx are both unavailable; uninstall failed.');
+        return 'failed';
+    }
+    const runner = options.runCommand ?? runCommand;
+    let removed;
+    try {
+        removed = await runner(invocation.command, [...invocation.argsPrefix, 'remove', ...skillNames, '--global', '--yes'], { env: invocation.env, tee: true });
+    }
+    catch (error) {
+        writeLine(`Internal skill batch: ${error instanceof Error ? error.message : String(error)}; uninstall failed.`);
+        return 'failed';
+    }
+    if (removed.code !== 0) {
+        writeLine(`Internal skill batch: uninstall failed (exit ${removed.code}).`);
+        return 'failed';
+    }
+    const unregister = dependencies.unregisterPlugin ?? unregisterPlugin;
+    const registrationsToRemove = new Set(candidates);
+    for (const name of (dependencies.listPluginNames ?? listPluginNames)()) {
         try {
             const registration = registrationFor(name);
-            if (registration?.managedBy !== OFFICIAL_PLUGIN_MANAGER) {
-                if (registration)
-                    writeLine(`${name} plugin: existing user registration kept.`);
-                continue;
+            if (registration && removedSkillDirectories.has(dirname(dirname(registration.entry)))) {
+                registrationsToRemove.add(name);
             }
-            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.`);
+        catch {
+            // 无法读取的注册不影响已确认 Skill 的卸载和其他有效注册清理。
         }
     }
-    return failed ? 'failed' : uninstalled ? 'uninstalled' : 'skipped';
+    for (const name of [...registrationsToRemove].sort())
+        unregister(name);
+    for (const name of candidates) {
+        writeLine(`${name} plugin: uninstalled.`);
+    }
+    if (options.includeMearlSkill)
+        writeLine('Skill: uninstalled.');
+    return 'uninstalled';
 }

package/dist/lifecycle.js

@@ -277,16 +277,61 @@ export async function runMearlLifecycle(options, dependencies = {}) {
                 packagesOk = false;
         }
     }
-    let skillOk = true;
     const selectedUsesSkill = selected.some(profile => MEARL_PROFILES[profile].usesSkill);
-    if (packagesOk && selectedUsesSkill && options.skipSkill !== true) {
+    const remainingSkillProfiles = ['local', 'cloud'].filter(profile => detected.has(profile) && !selected.includes(profile));
+    let runStandaloneSkill = true;
+    let skillOk = true;
+    if (packagesOk &&
+        selectedUsesSkill &&
+        selectedUsesClient &&
+        options.skipSkill !== true &&
+        ((options.operation === 'uninstall' && remainingSkillProfiles.length === 0) ||
+            (options.operation !== 'uninstall' && options.targetLine === undefined))) {
+        try {
+            if (options.operation === 'uninstall') {
+                const result = await (dependencies.uninstallInternalPlugins ?? uninstallAlibabaInternalPlugins)({
+                    env,
+                    includeMearlSkill: true,
+                    runCommand: runner,
+                    writeLine,
+                });
+                if (result === 'uninstalled')
+                    runStandaloneSkill = false;
+                else if (result === 'failed') {
+                    runStandaloneSkill = false;
+                    skillOk = false;
+                }
+            }
+            else {
+                const result = await (dependencies.installInternalPlugins ?? installAlibabaInternalPlugins)({
+                    env,
+                    includeMearlSkill: true,
+                    mearlSkillOperation: options.operation,
+                    runCommand: runner,
+                    writeLine,
+                });
+                if (result === 'installed')
+                    runStandaloneSkill = false;
+                else if (result === 'failed') {
+                    runStandaloneSkill = false;
+                    skillOk = false;
+                }
+            }
+        }
+        catch (error) {
+            writeLine(`Internal skill batch: ${error instanceof Error ? error.message : String(error)}; failed.`);
+            runStandaloneSkill = false;
+            skillOk = false;
+        }
+    }
+    if (packagesOk && skillOk && selectedUsesSkill && options.skipSkill !== true) {
         try {
             if (options.operation === 'uninstall') {
-                const remainingSkillProfiles = ['local', 'cloud'].filter(profile => detected.has(profile) && !selected.includes(profile));
                 if (remainingSkillProfiles.length > 0) {
                     writeLine(`Skill: kept for ${remainingSkillProfiles.join(', ')}.`);
+                    writeLine(`Internal plugins: kept for ${remainingSkillProfiles.join(', ')}.`);
                 }
-                else {
+                else if (runStandaloneSkill) {
                     skillOk = await runSkill('uninstall', {
                         env,
                         yes: options.yes,
@@ -295,7 +340,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
                     });
                 }
             }
-            else {
+            else if (runStandaloneSkill) {
                 skillOk = await runSkill(options.operation, {
                     env,
                     yes: options.yes,
@@ -309,41 +354,7 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             skillOk = false;
         }
     }
-    let internalPluginsOk = true;
-    if (packagesOk && skillOk && selectedUsesClient && options.skipSkill !== true) {
-        if (options.operation === 'uninstall') {
-            if (remainingClientProfiles.length > 0) {
-                writeLine(`Internal plugins: kept for ${remainingClientProfiles.join(', ')}.`);
-            }
-            else {
-                try {
-                    internalPluginsOk =
-                        (await (dependencies.uninstallInternalPlugins ?? uninstallAlibabaInternalPlugins)({
-                            env,
-                            runCommand: runner,
-                            writeLine,
-                        })) !== 'failed';
-                }
-                catch (error) {
-                    writeLine(`Internal plugins: ${error instanceof Error ? error.message : String(error)}; uninstall failed.`);
-                    internalPluginsOk = false;
-                }
-            }
-        }
-        else if (options.targetLine === undefined) {
-            try {
-                await (dependencies.installInternalPlugins ?? installAlibabaInternalPlugins)({
-                    env,
-                    runCommand: runner,
-                    writeLine,
-                });
-            }
-            catch (error) {
-                writeLine(`Internal plugins: ${error instanceof Error ? error.message : String(error)}; skipped.`);
-            }
-        }
-    }
-    if (packagesOk && skillOk && internalPluginsOk) {
+    if (packagesOk && skillOk) {
         writeLine('Mearl setup complete.');
         return true;
     }

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, findOfficialPlugin, findPluginEntry, findPluginRegistration, listPluginNames, loadPlugin, OFFICIAL_PLUGIN_MANAGER, registerPlugin, resolvePluginEntry, unregisterPlugin, } from '@mearl/client/plugin';
+import { assertPluginName, findPluginDirectoryEntry, 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';
@@ -178,8 +178,8 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
     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))
+        const entry = findPluginDirectoryEntry(skillPath);
+        if (!entry)
             continue;
         const plugin = await loadPlugin(entry, registrationContext);
         const name = plugin.name ?? basename(skillPath);
@@ -189,7 +189,7 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
         plugins.set(name, { entry, description: plugin.description });
     }
     if (plugins.size === 0) {
-        console.error('未找到 scripts/main.mjs 插件入口；自定义入口可用 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.15.3",
+  "version": "2.16.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.3",
-    "@mearl/provider": "2.15.3"
+    "@mearl/client": "2.16.1",
+    "@mearl/provider": "2.16.1"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",