@mearl/setup 2.5.0 → 2.6.0

package/README.md

@@ -3,7 +3,8 @@
 Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
 ```bash
-npx @mearl/setup <install|update|uninstall> [--local|--cloud|--mcp] [--yes]
+npx @mearl/setup [install] [--local] [--cloud] [--mcp] [--yes]
+npx @mearl/setup <update|uninstall> [--local] [--cloud] [--mcp] [--yes]
 ```
 
 配置 AgentBay API Key 时只需执行一次下面的命令，然后在隐藏输入提示中粘贴 Key。
@@ -18,14 +19,19 @@ npx @mearl/setup agentbay
 
 ## 行为
 
+- `install` 可以省略；直接执行 `npx @mearl/setup` 等同于 `npx @mearl/setup install`。
+  以选项开头时也默认安装，例如 `npx @mearl/setup --cloud --yes`。
 - `install` 未指定环境时默认 `--local`。
+- `-h` / `--help` 显示帮助，`-v` / `--version` 显示 setup 版本。
 - `update` 和 `uninstall` 未指定环境时，从当前 `PATH` 中的
-  `mearl-native-host`、`mearl-cloud`、`mearl-mcp-server` 自动检测，可同时处理
+  `mearl-native-host`、`mearl-cloud-server`、`mearl-mcp-server` 自动检测，可同时处理
   多个已安装环境。
-- 显式传入 `--local`、`--cloud` 或 `--mcp` 时只处理指定环境。
+- `--local`、`--cloud` 与 `--mcp` 可以组合，显式传入时只处理选中的环境。
 - 已有环境沿用其原包管理器和全局安装前缀；首次安装沿用启动 setup 的包管理器。
-- cloud 环境统一管理 `@mearl/cloud-server` 与 `@mearl/cloud-client`：首次安装后启动
+- cloud 环境统一管理 `@mearl/cloud-server` 与 `@mearl/client`：首次安装后启动
   Server，更新后仅在 Server 原本运行时重启，卸载前停止。
+- local/cloud 共用一份 `@mearl/client`；组合安装只处理一次，卸载单个环境时若另一个环境仍在使用则保留。
+- 从 2.5.x 更新 cloud 环境时会先卸载旧 `@mearl/cloud-client`，避免它遗留的 `mearl` bin 与统一 client 冲突。
 - local/cloud 共用的全局 mearl skill 通过 `ali-skills` 的 JSON 清单定位，只处理一次。
 - 卸载一个环境但另一个仍依赖全局 mearl skill 时会保留 skill。
 - `--mcp` 的客户端配置和清理由 `@mearl/mcp-server` 自己的命令完成。
@@ -55,6 +61,9 @@ npx @mearl/setup agentbay
 
 ```bash
 # 默认安装本地浏览器环境
+npx @mearl/setup
+
+# 与上一条等价
 npx @mearl/setup install
 
 # Agent / CI 无交互安装
@@ -63,6 +72,9 @@ npx @mearl/setup install --yes
 # 安装云端 Agent 环境
 npx @mearl/setup install --cloud
 
+# 同一台机器同时作为本地浏览器宿主和云端 Agent
+npx @mearl/setup install --local --cloud
+
 # 自动更新当前 PATH 中检测到的全部 Mearl 环境
 npx @mearl/setup update
 

package/dist/cli.d.ts

@@ -2,14 +2,16 @@
 import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin } from './agentBay.js';
 import { type MearlLifecycleOperation } from './lifecycle.js';
 import type { MearlProfile } from './profiles.js';
+export declare const SETUP_VERSION: string;
 interface ParsedArgs {
     agentBayKeyFile?: string;
     agentBayReadStdin: boolean;
     help: boolean;
     operation?: MearlLifecycleOperation | 'agentbay';
-    profile?: MearlProfile;
+    profiles?: MearlProfile[];
     skipSkill: boolean;
     targetLine?: string;
+    version?: boolean;
     yes: boolean;
 }
 export interface SetupCliDependencies {

package/dist/cli.js

@@ -1,14 +1,28 @@
 #!/usr/bin/env node
 import path from 'node:path';
+import { createRequire } from 'node:module';
 import { fileURLToPath } from 'node:url';
 import { configureAgentBayApiKey, promptAgentBayApiKey, readAgentBayApiKeyFile, readAgentBayApiKeyStdin, } from './agentBay.js';
 import { runMearlLifecycle } from './lifecycle.js';
 import { isMearlReleaseLine } from './version.js';
+const require = createRequire(import.meta.url);
+export const SETUP_VERSION = require('../package.json').version;
 export function parseSetupArgs(argv) {
-    if (argv.length === 0 || argv.includes('--help') || argv.includes('-h')) {
+    if (argv.includes('--help') || argv.includes('-h')) {
         return { agentBayReadStdin: false, help: true, skipSkill: false, yes: false };
     }
-    const operation = argv[0];
+    if (argv.includes('--version') || argv.includes('-v')) {
+        return {
+            agentBayReadStdin: false,
+            help: false,
+            skipSkill: false,
+            version: true,
+            yes: false,
+        };
+    }
+    const firstArg = argv[0];
+    const operation = firstArg === undefined || firstArg.startsWith('-') ? 'install' : firstArg;
+    const optionStart = operation === firstArg ? 1 : 0;
     if (operation === 'agentbay') {
         if (argv.length === 1) {
             return {
@@ -43,11 +57,11 @@ export function parseSetupArgs(argv) {
     if (operation !== 'install' && operation !== 'update' && operation !== 'uninstall') {
         throw new Error(`Unknown operation: ${operation}`);
     }
-    let profile;
+    const profiles = [];
     let skipSkill = false;
     let targetLine;
     let yes = false;
-    for (let index = 1; index < argv.length; index += 1) {
+    for (let index = optionStart; index < argv.length; index += 1) {
         const arg = argv[index];
         if (arg === '--yes' || arg === '-y' || arg === '--non-interactive') {
             yes = true;
@@ -75,10 +89,8 @@ export function parseSetupArgs(argv) {
                     : undefined;
         if (!candidate)
             throw new Error(`Unknown option: ${arg}`);
-        if (profile && profile !== candidate) {
-            throw new Error('Choose only one of --local, --cloud, or --mcp');
-        }
-        profile = candidate;
+        if (!profiles.includes(candidate))
+            profiles.push(candidate);
     }
     if (operation === 'uninstall' && targetLine) {
         throw new Error('--target-line is not available for uninstall');
@@ -87,28 +99,29 @@ export function parseSetupArgs(argv) {
         agentBayReadStdin: false,
         help: false,
         operation,
-        profile,
+        ...(profiles.length > 0 ? { profiles } : {}),
         skipSkill,
         targetLine,
         yes,
     };
 }
-function printHelp() {
-    console.error(`Mearl Setup
+function printHelp(toError = false) {
+    const output = `Mearl Setup v${SETUP_VERSION}
 
 Usage:
-  npx @mearl/setup <install|update|uninstall> [--local|--cloud|--mcp] [--yes]
+  npx @mearl/setup [install] [--local] [--cloud] [--mcp] [--yes]
+  npx @mearl/setup <update|uninstall> [--local] [--cloud] [--mcp] [--yes]
   npx @mearl/setup agentbay [--stdin | --key-file <path>]
 
 Behavior:
-  install      Defaults to --local when no environment is specified
+  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
   agentbay     Save or update AGENTBAY_KEY without changing other Mearl settings
 
 Options:
   --local      Manage @mearl/native-host and @mearl/client
-  --cloud      Manage @mearl/cloud-server and @mearl/cloud-client
+  --cloud      Manage @mearl/cloud-server and the unified @mearl/client
   --mcp        Manage @mearl/mcp-server and its configuration
   --stdin      Read the AgentBay API key from standard input
   --key-file   Read the AgentBay API key from a local file
@@ -118,16 +131,25 @@ Options:
   --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
 
 Examples:
+  npx @mearl/setup
+  npx @mearl/setup --yes
   npx @mearl/setup install
   npx @mearl/setup install --yes
   npx @mearl/setup install --cloud
+  npx @mearl/setup install --local --cloud
   npx @mearl/setup update
   npx @mearl/setup agentbay
   npx @mearl/setup update --local --target-line 2.3.x --skip-skill
-  npx @mearl/setup uninstall --local`);
+  npx @mearl/setup uninstall --local`;
+    if (toError)
+        console.error(output);
+    else
+        console.log(output);
 }
 export async function main(argv = process.argv.slice(2), interactiveTerminal = process.stdin.isTTY === true && process.stdout.isTTY === true, dependencies = {}) {
     let parsed;
@@ -136,13 +158,17 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
-        printHelp();
+        printHelp(true);
         return 2;
     }
     if (parsed.help) {
         printHelp();
         return 0;
     }
+    if (parsed.version) {
+        console.log(SETUP_VERSION);
+        return 0;
+    }
     if (parsed.operation === 'agentbay') {
         try {
             const configureAgentBay = dependencies.configureAgentBay ?? configureAgentBayApiKey;
@@ -175,7 +201,7 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
     try {
         const ok = await runMearlLifecycle({
             operation: parsed.operation,
-            profile: parsed.profile,
+            profiles: parsed.profiles,
             skipSkill: parsed.skipSkill,
             targetLine: parsed.targetLine,
             yes: parsed.yes,

package/dist/lifecycle.d.ts

@@ -6,7 +6,9 @@ import { type CommandRunner } from './process.js';
 export type MearlLifecycleOperation = 'install' | 'update' | 'uninstall';
 export interface MearlLifecycleOptions {
     operation: MearlLifecycleOperation;
+    /** @deprecated Use profiles when selecting one or more composable environments. */
     profile?: MearlProfile;
+    profiles?: MearlProfile[];
     yes?: boolean;
     targetLine?: string;
     skipSkill?: boolean;

package/dist/lifecycle.js

@@ -8,6 +8,10 @@ import { MEARL_PROFILES, detectMearlProfiles, } from './profiles.js';
 import { uninstallNativeHostArtifacts } from './nativeHost.js';
 import { executableNames, prependCommandPath, runCommand, } from './process.js';
 import { isMearlReleaseLine } from './version.js';
+const LEGACY_CLOUD_CLIENT = '@mearl/cloud-client';
+const UNIFIED_CLIENT = '@mearl/client';
+const PROFILE_ORDER = ['local', 'cloud', 'mcp'];
+const CLIENT_PROFILES = ['local', 'cloud'];
 async function confirmInTerminal(message) {
     if (!input.isTTY || !output.isTTY)
         return false;
@@ -40,6 +44,18 @@ async function runLifecycleCommand(runner, command, args, env, label, writeLine,
         return null;
     }
 }
+async function runPackageOperation(installation, operation, packages, targetLine, runner, env, label, writeLine) {
+    const command = buildGlobalPackageCommand(installation, operation, packages, targetLine);
+    writeLine(`${label}: ${command.manager}`);
+    const result = await runLifecycleCommand(runner, command.command, command.args, env, label, writeLine);
+    if (!result)
+        return { command, ok: false };
+    if (result.code !== 0) {
+        writeLine(`${label}: failed (exit ${result.code}).`);
+        return { command, ok: false };
+    }
+    return { command, ok: true };
+}
 async function runHook(profile, operation, detected, runner, existsSync, env, writeLine, yes) {
     let executable;
     let args;
@@ -101,11 +117,13 @@ async function runHook(profile, operation, detected, runner, existsSync, env, wr
     return true;
 }
 function selectedProfiles(operation, requested, detected) {
-    if (requested)
-        return [requested];
+    if (requested?.length) {
+        const requestedSet = new Set(requested);
+        return PROFILE_ORDER.filter(profile => requestedSet.has(profile));
+    }
     if (operation === 'install')
         return ['local'];
-    return [...detected.keys()];
+    return PROFILE_ORDER.filter(profile => detected.has(profile));
 }
 function operationVerb(operation) {
     return operation === 'uninstall' ? 'uninstall' : operation === 'update' ? 'update' : 'install';
@@ -126,7 +144,8 @@ export async function runMearlLifecycle(options, dependencies = {}) {
     const runSkill = dependencies.runSkillOperation ?? runGlobalMearlSkillOperation;
     const confirm = dependencies.confirm ?? confirmInTerminal;
     const detected = detectProfiles(env);
-    const selected = selectedProfiles(options.operation, options.profile, detected);
+    const requestedProfiles = options.profiles ?? (options.profile ? [options.profile] : undefined);
+    const selected = selectedProfiles(options.operation, requestedProfiles, detected);
     if (selected.length === 0) {
         writeLine('No installed Mearl environment was detected on the current PATH.');
         if (options.operation === 'uninstall')
@@ -157,6 +176,38 @@ export async function runMearlLifecycle(options, dependencies = {}) {
         .map(profile => MEARL_PROFILES[profile].label)
         .join(', ')}`);
     let packagesOk = true;
+    if (selected.includes('cloud')) {
+        const legacyCloudClient = detectPackage(LEGACY_CLOUD_CLIENT, ['mearl-cloud'], { env });
+        if (legacyCloudClient?.packageName === LEGACY_CLOUD_CLIENT) {
+            const command = buildGlobalPackageCommand(legacyCloudClient, 'uninstall', [
+                LEGACY_CLOUD_CLIENT,
+            ]);
+            writeLine(`Migration (cloud): removing ${LEGACY_CLOUD_CLIENT}.`);
+            const result = await runLifecycleCommand(runner, command.command, command.args, env, 'Migration (cloud)', writeLine);
+            if (!result || result.code !== 0) {
+                if (result)
+                    writeLine(`Migration (cloud): failed (exit ${result.code}).`);
+                writeLine('Mearl setup incomplete. Review the messages above.');
+                return false;
+            }
+        }
+    }
+    const selectedUsesClient = selected.some(profile => CLIENT_PROFILES.includes(profile));
+    const detectedClientCandidate = selectedUsesClient
+        ? detectPackage(UNIFIED_CLIENT, ['mearl'], { env })
+        : null;
+    const detectedClient = detectedClientCandidate?.packageName === UNIFIED_CLIENT ? detectedClientCandidate : null;
+    if (selectedUsesClient && options.operation !== 'uninstall') {
+        const clientInstallation = detectedClient ??
+            detected.get('local') ??
+            detected.get('cloud') ??
+            resolveInvokingManager(env);
+        const sharedClient = await runPackageOperation(clientInstallation, options.operation, [UNIFIED_CLIENT], options.targetLine, runner, env, 'Packages (shared client)', writeLine);
+        if (!sharedClient.ok) {
+            writeLine('Mearl setup incomplete. Review the messages above.');
+            return false;
+        }
+    }
     for (const profile of selected) {
         const config = MEARL_PROFILES[profile];
         const current = detected.get(profile);
@@ -186,23 +237,20 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             packagesOk = false;
             continue;
         }
-        const packageOperation = options.operation === 'uninstall' ? 'uninstall' : options.operation;
-        const command = buildGlobalPackageCommand(installation, packageOperation, config.packages, options.targetLine);
-        writeLine(`Packages (${profile}): ${command.manager}`);
-        const result = await runLifecycleCommand(runner, command.command, command.args, env, `Packages (${profile})`, writeLine);
-        if (!result) {
-            packagesOk = false;
+        const packageOperation = options.operation;
+        const packages = config.packages.filter(packageName => packageName !== UNIFIED_CLIENT);
+        if (packages.length === 0) {
             continue;
         }
-        if (result.code !== 0) {
-            writeLine(`Packages (${profile}): failed (exit ${result.code}).`);
+        const packageResult = await runPackageOperation(installation, packageOperation, packages, options.targetLine, runner, env, `Packages (${profile})`, writeLine);
+        if (!packageResult.ok) {
             packagesOk = false;
             continue;
         }
         if (options.operation !== 'uninstall' &&
             (profile === 'local' || profile === 'cloud' || profile === 'mcp')) {
             const refreshed = detectPackage(config.anchorPackage, config.anchorBins, {
-                env: prependCommandPath(command.command, env),
+                env: prependCommandPath(packageResult.command.command, env),
             }) ?? current;
             if (!refreshed ||
                 !(await runHook(profile, options.operation, refreshed, runner, existsSync, env, writeLine, options.yes === true))) {
@@ -210,6 +258,17 @@ export async function runMearlLifecycle(options, dependencies = {}) {
             }
         }
     }
+    if (selectedUsesClient && options.operation === 'uninstall') {
+        const remainingClientProfiles = CLIENT_PROFILES.filter(profile => detected.has(profile) && !selected.includes(profile));
+        if (remainingClientProfiles.length > 0) {
+            writeLine(`Packages (shared client): kept for ${remainingClientProfiles.join(', ')}.`);
+        }
+        else if (packagesOk && detectedClient) {
+            const sharedClient = await runPackageOperation(detectedClient, 'uninstall', [UNIFIED_CLIENT], undefined, runner, env, 'Packages (shared client)', writeLine);
+            if (!sharedClient.ok)
+                packagesOk = false;
+        }
+    }
     let skillOk = true;
     const selectedUsesSkill = selected.some(profile => MEARL_PROFILES[profile].usesSkill);
     if (packagesOk && selectedUsesSkill && options.skipSkill !== true) {

package/dist/profiles.js

@@ -11,9 +11,9 @@ export const MEARL_PROFILES = {
     cloud: {
         id: 'cloud',
         label: 'cloud agent',
-        anchorPackage: '@mearl/cloud-client',
-        anchorBins: ['mearl-cloud'],
-        packages: ['@mearl/cloud-server', '@mearl/cloud-client'],
+        anchorPackage: '@mearl/cloud-server',
+        anchorBins: ['mearl-cloud-server'],
+        packages: ['@mearl/cloud-server', '@mearl/client'],
         usesSkill: true,
     },
     mcp: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",