@mearl/setup 2.22.4 → 2.23.0

package/README.md

@@ -2,21 +2,25 @@
 
 Mearl 环境的一次性安装、更新、卸载与配置工具。无需先全局安装 setup：
 
+要求 Node.js >= 20.18.0。首次安装可执行 `npx @mearl/setup@2` 选择最新稳定 2.x；
+若出现 `Unknown operation: plugin`，先检查 `node --version`，再用 `npx @mearl/setup@2 --version`
+确认安装器版本。未指定版本时，npm 可能优先选择兼容旧 Node 的历史版本。
+
 ```bash
-npx @mearl/setup [install] [--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 参数...>
-npx @mearl/setup plugin uninstall <name>
-npx @mearl/setup provider <install|update|uninstall> <package|id>
+npx @mearl/setup@2 [install] [--local] [--cloud|--qoder-cloud] [--mcp]
+npx @mearl/setup@2 update [--local] [--cloud|--qoder-cloud] [--mcp]
+npx @mearl/setup@2 uninstall [--local] [--cloud|--qoder-cloud] [--mcp] [--full]
+npx @mearl/setup@2 extension [--full] [--force]
+npx @mearl/setup@2 plugin [name] <path>
+npx @mearl/setup@2 plugin install <ali-skills add 参数...>
+npx @mearl/setup@2 plugin uninstall <name>
+npx @mearl/setup@2 provider <install|update|uninstall> <package|id>
 ```
 
 浏览器 Provider 独立安装和演进。安装后运行 `mearl <providerId>` 查看该版本声明的能力、
 配置和启动参数。
 
-在 Qoder Cloud Agent 环境中，使用 `npx @mearl/setup --qoder-cloud --yes` 选择 Qoder
+在 Qoder Cloud Agent 环境中，使用 `npx @mearl/setup@2 --qoder-cloud --yes` 选择 Qoder
 配对模式。它与 `--cloud` 安装同一套 cloud-server、client 和 Skill，只把 cloud-server
 模式记录为 Qoder；`mearl-cloud-server` 的命令交互保持不变，`start` 和 `restart` 输出新的
 配对指令后退出，不监听端口或保留守护进程。配对 URL 不包含 Qoder PAT。
@@ -26,7 +30,7 @@ npx @mearl/setup provider <install|update|uninstall> <package|id>
 一个命令安装 skill 并注册它的 CLI、SDK 和 MCP 能力：
 
 ```bash
-npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
+npx @mearl/setup@2 plugin install trip/mearl --branch 2.x --skill yuque-doc-fetch --yes
 mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
 ```
 
@@ -41,7 +45,7 @@ registry 可访问时通过 Ali Skills 批量处理 `mearl` 与 `tdbank-account`
 更新发现 TDBank 插件缺少注册时，会在批量更新已跟踪项后通过一次 `add` 补装并恢复注册。
 该 registry 不用于下载插件。
 探测不可用时按普通外网流程只处理 Mearl Skill；内网批量命令失败时 setup 失败，不再逐项重试。
-`--skip-skill` 和 `--target-line` 安装不执行自动插件步骤。
+安装和更新默认选择 2.x 的最新稳定运行包。`--target-line` 可指定次版本系列。`--skip-skill` 和 `--target-line` 安装不执行自动插件步骤。
 
 Mearl client 内置 `buc`、`authx` 与 `tdbank` 的安装来源。CLI、SDK、MCP 或另一个插件首次调用尚未注册的这些插件时，会通过内部幂等流程安装并重试一次；其他未注册名称不会触发安装。BUC 与 AuthX 不随 setup 预装。
 
@@ -52,8 +56,8 @@ Mearl client 内置 `buc`、`authx` 与 `tdbank` 的安装来源。CLI、SDK、M
 已通过其他渠道分发的 skill 或自定义入口，可以直接传入路径注册：
 
 ```bash
-npx @mearl/setup plugin /absolute/path/to/yuque-doc-fetch
-npx @mearl/setup plugin custom ./skills/custom/entry.mjs
+npx @mearl/setup@2 plugin /absolute/path/to/yuque-doc-fetch
+npx @mearl/setup@2 plugin custom ./skills/custom/entry.mjs
 ```
 
 path 接受目录或具体文件；目录默认读取 `scripts/main.mjs` 或 `scripts/main.py`，相对路径基于调用工作目录解析。插件名优先使用显式 name，其次读取入口的 `name` metadata，最后回退到 Skill 目录名；常规注册只传 path，显式 name 仅用于覆盖或兼容旧入口。Python 插件要求 `python3 >= 3.9`，可通过 `MEARL_PYTHON` 指定解释器路径；setup 只验证入口可加载，不安装 Python，也不执行 `pip install`。
@@ -66,7 +70,7 @@ native-host 会幂等初始化 Skills 模式。基础环境补齐或初始化失
 不再需要插件时执行：
 
 ```bash
-npx @mearl/setup plugin uninstall yuque
+npx @mearl/setup@2 plugin uninstall yuque
 ```
 
 若入口位于 `~/.agents/skills/<skill>/`，setup 会先执行
@@ -82,9 +86,9 @@ Provider 由 npm 包分发，但包本身无需暴露 CLI 或安装脚本。setu
 可创建的浏览器类型名称及其表单参数：
 
 ```bash
-npx @mearl/setup provider install @ali/mearl-provider-brow
-npx @mearl/setup provider update brow
-npx @mearl/setup provider uninstall brow
+npx @mearl/setup@2 provider install @ali/mearl-provider-brow
+npx @mearl/setup@2 provider update brow
+npx @mearl/setup@2 provider uninstall brow
 ```
 
 安装参数接受包名、版本或 dist-tag；更新和卸载可使用 `providerId` 或完整包名。`@ali/*` 包的
@@ -96,8 +100,8 @@ npx @mearl/setup provider uninstall brow
 ## 行为
 
 - Mearl 自有 npm 包的安装和更新固定使用 `https://registry.npmjs.org/`，与最新版本查询使用同一来源；第三方包沿用当前包管理器的源配置。
-- `install` 可以省略；直接执行 `npx @mearl/setup` 等同于 `npx @mearl/setup install`。
-  以选项开头时也默认安装，例如 `npx @mearl/setup --cloud --yes`。
+- `install` 可以省略；直接执行 `npx @mearl/setup@2` 等同于 `npx @mearl/setup@2 install`。
+  以选项开头时也默认安装，例如 `npx @mearl/setup@2 --cloud --yes`。
 - `install` 未指定环境时默认 `--local`。
 - `-h` / `--help` 显示帮助，`-v` / `--version` 显示 setup 版本。
 - `update` 和 `uninstall` 未指定环境时，从当前 `PATH` 中的
@@ -145,19 +149,19 @@ npx @mearl/setup provider uninstall brow
 ## 安装或更新浏览器扩展
 
 ```bash
-npx @mearl/setup extension
+npx @mearl/setup@2 extension
 ```
 
 首次使用时可一次安装完整的本地浏览器环境：
 
 ```bash
-npx @mearl/setup extension --full
+npx @mearl/setup@2 extension --full
 ```
 
 首次安装、旧版 setup 扩展首次迁移，或 Native Host reload 不可用时才需要 CDP。如果
 Chrome 尚未开放 CDP，交互命令会提示打开
 `chrome://inspect/#remote-debugging`、启用远程调试并允许连接，然后等待安装完成。面向人的
-安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup extension --yes`；它只尝试
+安装指引不要添加 `--yes`。无 TTY 环境使用 `npx @mearl/setup@2 extension --yes`；它只尝试
 一次，CDP 不可用时立即中断。无法确认 setup 管理来源且 CDP 不可用时不会下载或修改插件
 目录，打开 CDP 后重新执行同一命令即可。Chrome 版本过低、缺少扩展安装所需的 CDP 方法时，
 命令会中断并提示升级 Chrome。
@@ -187,7 +191,7 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
 
 自动更新不会降级较新的 Host，也不会改动 cloud、MCP 或独立安装的 Mearl Skill。
 目标 npm 版本尚未发布、网络不可用或更新失败时，旧 Host 会继续运行；下一次扩展后台
-生命周期可重新尝试，也可手动执行 `npx @mearl/setup update --local`。
+生命周期可重新尝试，也可手动执行 `npx @mearl/setup@2 update --local`。
 
 ## 人工与 Agent 使用
 
@@ -202,41 +206,41 @@ DevTools 面板的设置按钮会显示红点，快捷设置中提供“立即
 
 ```bash
 # 默认安装本地浏览器环境
-npx @mearl/setup
+npx @mearl/setup@2
 
 # 与上一条等价
-npx @mearl/setup install
+npx @mearl/setup@2 install
 
 # Agent / CI 无交互安装
-npx @mearl/setup --yes
+npx @mearl/setup@2 --yes
 
 # 安装云端 Agent 环境
-npx @mearl/setup --cloud
+npx @mearl/setup@2 --cloud
 
 # 同一台机器同时作为本地浏览器宿主和云端 Agent
-npx @mearl/setup --local --cloud
+npx @mearl/setup@2 --local --cloud
 
 # 自动更新当前 PATH 中检测到的全部 Mearl 环境
-npx @mearl/setup update
+npx @mearl/setup@2 update
 
 # 独立安装或更新到最新浏览器扩展
-npx @mearl/setup extension
+npx @mearl/setup@2 extension
 
 # 安装完整本地环境（client、Native Host、Skill 和扩展）
-npx @mearl/setup extension --full
+npx @mearl/setup@2 extension --full
 
 # 只卸载本地环境
-npx @mearl/setup uninstall --local
+npx @mearl/setup@2 uninstall --local
 
 # 自动检测并无交互卸载
-npx @mearl/setup uninstall --yes
+npx @mearl/setup@2 uninstall --yes
 
 # 卸载环境，并清理全部 CLI 插件与 Provider
-npx @mearl/setup uninstall --full
+npx @mearl/setup@2 uninstall --full
 
 # 安装可选浏览器 Provider
-npx @mearl/setup provider install @ali/mearl-provider-brow
-npx @mearl/setup provider install @ali/mearl-provider-agentbay
+npx @mearl/setup@2 provider install @ali/mearl-provider-brow
+npx @mearl/setup@2 provider install @ali/mearl-provider-agentbay
 ```
 
 原有 Mearl 环境包的 npm/npx 安装方式和 CLI 保持可用；setup 是统一的便利入口。

package/dist/aliSkills.js

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
-import { executableNames, findExecutable, isExecutable, prependCommandPath, prependNodePath, resolveSpawnCommand, runCommand, versionManagerExecutableCandidates, } from '@mearl/daemon-core';
+import { executableNames, findExecutable, isExecutable, npmExecEnvironment, prependCommandPath, prependNodePath, resolveSpawnCommand, runCommand, versionManagerExecutableCandidates, } from '@mearl/daemon-core';
 const COMMAND_TIMEOUT_MS = 120_000;
 const MAX_OUTPUT_LENGTH = 1_000_000;
 const ANSI_ESCAPE_PATTERN = new RegExp(String.raw `\u001B\[[0-?]*[ -/]*[@-~]`, 'g');
@@ -49,7 +49,7 @@ export const runAliSkillsCli = (executable, args, cwd) => new Promise((resolve,
     const launch = resolveSpawnCommand(executable, args);
     const child = spawn(launch.command, launch.args, {
         cwd,
-        env: prependNodePath(prependCommandPath(executable)),
+        env: npmExecEnvironment(prependNodePath(prependCommandPath(executable))),
         stdio: ['ignore', 'pipe', 'pipe'],
         windowsHide: true,
     });
@@ -107,7 +107,7 @@ export function resolveAliSkillsInvocation(options = {}) {
     return {
         command: npx,
         argsPrefix: ['-y', 'ali-skills'],
-        env: prependNodePath(prependCommandPath(npx, env), processExecPath),
+        env: npmExecEnvironment(prependNodePath(prependCommandPath(npx, env), processExecPath)),
     };
 }
 export function parseGlobalMearlSkillPaths(output) {

package/dist/browserExtension.js

@@ -6,7 +6,7 @@ import { runUnifiedCheck } from '@mearl/client/check';
 import { CLIENT_VERSION, invoke as invokeLocalMearl } from '@mearl/client/local';
 import extractZip from 'extract-zip';
 import WebSocket from 'ws';
-import { compareMearlReleaseVersions, isMearlReleaseVersion } from './version.js';
+import { compareMearlReleaseVersions, isMearlReleaseVersion, parseMearlReleaseVersion, } from './version.js';
 export const MEARL_EXTENSION_DOWNLOAD_PAGE = 'https://mearl.alibaba-inc.com/';
 export const MEARL_EXTENSION_REMOTE_CONFIG_URL = `${MEARL_EXTENSION_DOWNLOAD_PAGE}config.json`;
 export const MEARL_EXTENSION_DIRECTORY_NAME = 'chrome-extension';
@@ -78,22 +78,16 @@ export async function fetchBrowserExtensionRelease(fetchImpl = fetch) {
         throw new Error(`Extension config returned HTTP ${response.status}`);
     }
     const config = (await response.json());
+    const version = parseMearlReleaseVersion(config.latestVersion);
+    if (version?.major !== 2 || version.channel !== 'stable') {
+        throw new Error('Remote extension config must select a stable Mearl 2.x release');
+    }
     return validateExtensionRelease({
         archiveUrl: typeof config.downloadUrl === 'string' ? config.downloadUrl : '',
         ...(typeof config.downloadSha256 === 'string' ? { sha256: config.downloadSha256 } : {}),
-        version: typeof config.latestVersion === 'string' ? config.latestVersion : '',
+        version: version.raw,
     });
 }
-async function resolveExtensionArchive(fetchImpl) {
-    const response = await fetchImpl(MEARL_EXTENSION_DOWNLOAD_PAGE, { redirect: 'follow' });
-    if (!response.ok) {
-        throw new Error(`Extension release page returned HTTP ${response.status}`);
-    }
-    const version = findLatestExtensionVersion(await response.text());
-    if (!version)
-        throw new Error('No Mearl browser extension archive was found on the release page');
-    return { version, archiveUrl: extensionArchiveUrl(version) };
-}
 function readDevToolsActivePort(userDataDirectory) {
     try {
         const content = fs
@@ -475,7 +469,7 @@ export async function installMearlBrowserExtension(options = {}, dependencies =
     const targetDirectory = path.resolve(options.targetDirectory ?? resolveMearlExtensionDirectory());
     const release = options.release
         ? validateExtensionRelease(options.release)
-        : await resolveExtensionArchive(fetchImpl);
+        : await fetchBrowserExtensionRelease(fetchImpl);
     const chromeUserDataDirectory = options.chromeUserDataDirectory ?? resolveChromeUserDataDirectory();
     const waitForCdpMs = Math.max(0, options.waitForCdpMs ?? 0);
     const useSharedCdpSession = !dependencies.inspectInstallation && !dependencies.loadUnpacked;

package/dist/cli.js

@@ -163,7 +163,7 @@ function printHelp() {
     const output = `Mearl Setup v${SETUP_VERSION}
 
 Usage:
-  npx @mearl/setup [command] [options]
+  npx @mearl/setup@2 [command] [options]
 
 Environment commands:
   install [options]               Install an environment (default command; target: local)
@@ -186,7 +186,7 @@ Environment options:
   --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
+  --target-line <major.minor.x>   Override the default 2.x package range
   --skip-skill                    Keep the independently managed Mearl Skill unchanged
 
 Uninstall options:
@@ -203,14 +203,14 @@ General options:
   --help, -h                      Show this help
 
 Examples:
-  npx @mearl/setup
-  npx @mearl/setup --cloud
-  npx @mearl/setup --local --cloud
-  npx @mearl/setup update
-  npx @mearl/setup uninstall --full
-  npx @mearl/setup plugin uninstall yuque
-  npx @mearl/setup provider install @ali/mearl-provider-brow
-  npx @mearl/setup extension --full`;
+  npx @mearl/setup@2
+  npx @mearl/setup@2 --cloud
+  npx @mearl/setup@2 --local --cloud
+  npx @mearl/setup@2 update
+  npx @mearl/setup@2 uninstall --full
+  npx @mearl/setup@2 plugin uninstall yuque
+  npx @mearl/setup@2 provider install @ali/mearl-provider-brow
+  npx @mearl/setup@2 extension --full`;
     console.log(output);
 }
 export async function main(argv = process.argv.slice(2), interactiveTerminal = process.stdin.isTTY === true && process.stdout.isTTY === true, dependencies = {}) {
@@ -220,7 +220,7 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
-        console.error('Run "npx @mearl/setup --help" for usage.');
+        console.error('Run "npx @mearl/setup@2 --help" for usage.');
         return 2;
     }
     if (parsed.help) {
@@ -325,11 +325,11 @@ export async function main(argv = process.argv.slice(2), interactiveTerminal = p
                 if (result.cdpError) {
                     console.error(`CDP installation failed: ${result.cdpError}`);
                     if (isUnsupportedCdpMethodError(result.cdpError)) {
-                        console.error('This Chrome version does not support installing extensions through CDP. Update Chrome to version 145 or later, then rerun: npx @mearl/setup extension');
+                        console.error('This Chrome version does not support installing extensions through CDP. Update Chrome to version 145 or later, then rerun: npx @mearl/setup@2 extension');
                         extensionFailureIsTerminal = true;
                     }
                     else {
-                        console.error('Open chrome://inspect/#remote-debugging, enable remote debugging, approve the connection, then rerun: npx @mearl/setup extension');
+                        console.error('Open chrome://inspect/#remote-debugging, enable remote debugging, approve the connection, then rerun: npx @mearl/setup@2 extension');
                         extensionFailureIsTerminal = parsed.yes;
                     }
                 }

package/dist/lifecycle.js

@@ -79,7 +79,7 @@ async function runLifecycleCommand(runner, command, args, env, label, writeLine,
     }
 }
 async function runPackageOperation(installation, operation, packages, targetLine, runner, env, label, writeLine) {
-    const command = buildGlobalPackageCommand(installation, operation, packages, targetLine);
+    const command = buildGlobalPackageCommand(installation, operation, packages, targetLine ?? '2.x');
     writeLine(`${label}: ${command.manager}`);
     const result = await runLifecycleCommand(runner, command.command, command.args, operation === 'uninstall'
         ? env

package/dist/plugin.js

@@ -4,7 +4,7 @@ import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'nod
 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 '@mearl/daemon-core';
+import { findExecutable, npmExecEnvironment, prependNodePath, runCommand, } from '@mearl/daemon-core';
 const registrationContext = {
     options: {},
     invoke: async () => {
@@ -241,7 +241,7 @@ export async function installPlugins(args, runner = runCommand, options = {}) {
         throw new Error('未找到 npx，请检查 Node.js 安装。');
     // 固定共享安装模式，确保成功结果指向 ~/.agents/skills 中的入口。
     const installed = await runner(npx, ['-y', 'ali-skills', 'add', ...args, '--global', '--install-mode', 'symlink'], {
-        env: prependNodePath(),
+        env: npmExecEnvironment(prependNodePath()),
         tee: true,
     });
     if (installed.code !== 0)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/setup",
-  "version": "2.22.4",
+  "version": "2.23.0",
   "description": "One-shot environment setup and configuration for Mearl",
   "type": "module",
   "main": "dist/index.js",
@@ -56,18 +56,18 @@
   ],
   "license": "ISC",
   "engines": {
-    "node": ">=22.12.0"
+    "node": ">=20.18.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org"
   },
   "dependencies": {
-    "commander": "^15.0.0",
+    "commander": "^14.0.3",
     "extract-zip": "^2.0.1",
     "ws": "^8.18.3",
-    "@mearl/client": "2.22.4",
-    "@mearl/provider": "2.22.4",
-    "@mearl/daemon-core": "2.22.4"
+    "@mearl/client": "2.23.0",
+    "@mearl/provider": "2.23.0",
+    "@mearl/daemon-core": "2.23.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",