@mearl/setup 2.10.0 → 2.12.0

package/README.md

@@ -6,6 +6,9 @@ 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>
 ```
 
 配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。
@@ -23,6 +26,50 @@ 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 注册，不删除源码。
+重复卸载未注册名称会成功返回，不产生改动。
+
 ## 行为
 
 - `install` 可以省略；直接执行 `npx @mearl/setup` 等同于 `npx @mearl/setup install`。

package/dist/cli.d.ts

@@ -3,6 +3,7 @@ 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';
 export declare const SETUP_VERSION: string;
 interface ParsedArgs {
     agentBayKeyFile?: string;
@@ -11,7 +12,11 @@ interface ParsedArgs {
     force?: boolean;
     full?: boolean;
     help: boolean;
-    operation?: MearlLifecycleOperation | 'agentbay' | 'extension';
+    operation?: MearlLifecycleOperation | 'agentbay' | 'extension' | 'plugin';
+    pluginName?: string;
+    pluginPath?: string;
+    pluginInstallArgs?: string[];
+    pluginUninstallName?: string;
     profiles?: MearlProfile[];
     skipSkill: boolean;
     targetLine?: string;
@@ -19,6 +24,9 @@ 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;

package/dist/cli.js

@@ -5,6 +5,7 @@ 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';
 const require = createRequire(import.meta.url);
 export const SETUP_VERSION = require('../package.json').version;
 const baseParsedArgs = () => ({
@@ -24,6 +25,15 @@ function commanderError(error) {
     return new Error(message);
 }
 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] === '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 +87,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 +163,9 @@ 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 agentbay [--stdin | --key-file <path>]
 
 Behavior:
@@ -153,6 +174,7 @@ 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
 
 Options:
   --local      Manage @mearl/native-host and @mearl/client
@@ -183,6 +205,7 @@ Examples:
   npx @mearl/setup update
   npx @mearl/setup extension
   npx @mearl/setup extension --full
+  npx @mearl/setup plugin uninstall yuque
   npx @mearl/setup agentbay
   npx @mearl/setup --qoder-cloud --yes
   npx @mearl/setup update --local --target-line 2.3.x --skip-skill
@@ -210,6 +233,41 @@ 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 === 'agentbay') {
         try {
             const configureAgentBay = dependencies.configureAgentBay ?? configureAgentBayApiKey;

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);
+    await loadPlugin(entry, registrationContext);
+    await ensurePluginRuntime();
+    return registerPlugin(name, entry);
+}
+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);
+    }
+    if (plugins.size === 0) {
+        console.error('未找到 scripts/main.mjs 插件入口；自定义入口可用 setup plugin <name> <path> 注册。');
+        return 0;
+    }
+    await ensurePluginRuntime(runner);
+    for (const [name, entry] of plugins) {
+        registerPlugin(name, entry);
+        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/package.json

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