@mearl/client 2.22.4 → 2.23.0

package/README.md

@@ -58,7 +58,7 @@ mearl check
 mearl check --local --json
 
 # 更新本地环境
-npx @mearl/setup update --local
+npx @mearl/setup@2 update --local --skip-skill
 
 # 查看某个 action 的帮助
 mearl <action> --help
@@ -176,8 +176,8 @@ Provider 浏览器与扩展、CDP 浏览器一起出现在 `browser_list` 中，
 全局 `browserId` 参与路由。Provider 的安装、更新和卸载由 `@mearl/setup` 管理：
 
 ```bash
-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
 
 # 查看 Provider 当前版本的能力、参数与使用流程
 mearl brow
@@ -191,8 +191,8 @@ mearl browser_list
 mearl tab_list --browser '<browserId>'
 mearl page_snapshot --payload '{"tabId":12345}' --browser '<browserId>'
 
-npx @mearl/setup provider update brow
-npx @mearl/setup provider uninstall brow
+npx @mearl/setup@2 provider update brow
+npx @mearl/setup@2 provider uninstall brow
 ```
 
 `browser_launch` 创建 `pairing` 实例时会直接返回 `pairing.url` 和可选的配对码；Agent 应把 URL 直接渲染为
@@ -241,8 +241,7 @@ Mearl 默认聚合当前机器和已配置 cloud-server 下的浏览器，并通
 `mearl check --help`。`mearl check` 检查连接与浏览器状态；`mearl check --updates` 还会并发查询
 client、native-host、cloud-connector 和扩展的最新发布版本。发布版本查询最长等待约 1.5 秒，
 无法访问发布源时会提示无法确认更新，不影响浏览器可用性检查。`--json` 输出机器可读的检查结果，
-与 `--updates` 同用时包含更新状态。发现更新时会提示适用的命令：client/native-host 使用
-`npx @mearl/setup update`，setup 管理的扩展使用 `npx @mearl/setup extension`。
+与 `--updates` 同用时包含更新状态。发现更新时，client/native-host 会显示 `npx @mearl/setup@2 update --skip-skill`，扩展会显示对应版本的 ZIP 下载链接。
 
 全局安装的 `mearl` CLI 默认在每天首次使用后启动独立后台进程，查询最新发布版本，并比较
 client、native-host、cloud-server 和 MCP server 的已安装版本。发现更新时调用
@@ -267,11 +266,11 @@ client、native-host、cloud-server 和 MCP server 的已安装版本。发现
 安装 skill 并自动注册命令，或直接注册已有入口：
 
 ```bash
-npx @mearl/setup plugin install trip/mearl --skill yuque-doc-fetch --yes
-npx @mearl/setup plugin install trip/mearl --skill buc-request --yes
-npx @mearl/setup plugin install trip/mearl --skill authx-request --yes
-npx @mearl/setup plugin /absolute/path/to/yuque-doc-fetch
-npx @mearl/setup plugin uninstall yuque
+npx @mearl/setup@2 plugin install trip/mearl --branch 2.x --skill yuque-doc-fetch --yes
+npx @mearl/setup@2 plugin install trip/mearl --branch 2.x --skill buc-request --yes
+npx @mearl/setup@2 plugin install trip/mearl --branch 2.x --skill authx-request --yes
+npx @mearl/setup@2 plugin /absolute/path/to/yuque-doc-fetch
+npx @mearl/setup@2 plugin uninstall yuque
 mearl yuque read "https://aliyuque.antfin.com/group/book/doc"
 mearl yuque --payload '{"command":"read","input":{"url":"https://aliyuque.antfin.com/group/book/doc"}}'
 mearl yuque --help
@@ -291,7 +290,7 @@ setup 会补齐缺失或低于自身版本的 client、native-host；安装参
 `mearl-bbrowser` Skill 提供 `bbrowser` 插件，可直接加载 bb-browser 格式的社区及私有站点适配器，无需安装 bb-browser：
 
 ```bash
-npx @mearl/setup plugin install trip/mearl --skill mearl-bbrowser --yes
+npx @mearl/setup@2 plugin install trip/mearl --branch 2.x --skill mearl-bbrowser --yes
 mearl bbrowser site list
 mearl bbrowser site fliggy-ebooking/whoami
 mearl bbrowser site ./fliggy-ebooking/ai-agent.js

package/dist/autoUpdate.js

@@ -4,14 +4,14 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, realpathSync,
 import { homedir } from 'node:os';
 import { delimiter, dirname, join, resolve, win32 } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { isNewerRelease, parseReleaseVersion } from './check.js';
+import { npmExecEnvironment } from '@mearl/daemon-core';
+import { fetchLatestStablePackageVersion, isNewerRelease, parseReleaseVersion } from './check.js';
 import { loadCliAutoUpdateIntervalDays } from './unifiedConfig.js';
 const CONFIG_DIR = join(homedir(), '.mearl');
 const STATE_PATH = join(CONFIG_DIR, 'cli-auto-update-state.json');
 const LOCK_PATH = join(CONFIG_DIR, 'cli-auto-update.lock');
 const LOCK_STALE_MS = 10 * 60_000;
 const UPDATE_TIMEOUT_MS = 5 * 60_000;
-const VERSION_URL = 'https://registry.npmjs.org/@mearl%2Fclient/latest';
 function localDate(date) {
     return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
 }
@@ -207,7 +207,7 @@ export function setupUpdateCommand(version, packageRoot, profiles, updateClient)
     if (!parseReleaseVersion(version))
         throw new Error('A valid Mearl release is required');
     const [major, minor] = version.split('.');
-    const env = { ...process.env };
+    const env = npmExecEnvironment();
     delete env.MEARL_AUTO_UPDATE_CLIENT_ROOT;
     delete env.MEARL_AUTO_UPDATE_CLIENT_ONLY;
     delete env.MEARL_AUTO_UPDATE_PROFILES;
@@ -285,17 +285,6 @@ function installedEnvironments() {
     }
     return versions;
 }
-async function fetchLatestClientVersion() {
-    const response = await fetch(VERSION_URL, { signal: AbortSignal.timeout(2_000) });
-    if (!response.ok)
-        throw new Error(`Registry returned HTTP ${response.status}`);
-    const payload = (await response.json());
-    const version = payload.version;
-    if (typeof version !== 'string') {
-        throw new Error('Registry returned an invalid release version');
-    }
-    return version;
-}
 /** Runs only in the detached worker process. */
 export async function runCliAutoUpdate(installedVersion, packageRoot, token, options = {}) {
     const statePath = options.statePath ?? STATE_PATH;
@@ -312,7 +301,8 @@ export async function runCliAutoUpdate(installedVersion, packageRoot, token, opt
     }
     let result;
     try {
-        const version = await (options.fetchLatestVersion ?? fetchLatestClientVersion)();
+        const version = await (options.fetchLatestVersion?.() ??
+            fetchLatestStablePackageVersion('client', installedVersion));
         if (!parseReleaseVersion(version))
             throw new Error('Registry returned an invalid release version');
         const environments = (options.getInstalledEnvironments ?? installedEnvironments)();

package/dist/check.d.ts

@@ -99,8 +99,16 @@ export interface UnifiedCheckDependencies {
     fetchLatestVersion?: (component: string) => Promise<string>;
     inspectNativeHostInstallation?: () => NativeHostDiagnostic[];
 }
+declare const UPDATE_SOURCES: {
+    readonly client: "https://registry.npmjs.org/@mearl%2Fclient";
+    readonly 'native-host': "https://registry.npmjs.org/@mearl%2Fnative-host";
+    readonly 'cloud-connector': "https://registry.npmjs.org/@mearl%2Fcloud-connector";
+    readonly extension: "https://mearl.alibaba-inc.com/config.json";
+};
+type UpdateComponent = keyof typeof UPDATE_SOURCES;
 export declare function parseReleaseVersion(value: unknown): number[] | null;
 export declare function isNewerRelease(latest: string, installed: string): boolean;
+export declare function fetchLatestStablePackageVersion(component: Exclude<UpdateComponent, 'extension'>, installedVersion: string): Promise<string>;
 export declare function parseCheckTimeout(value: string | undefined): number | null;
 export declare function runUnifiedCheck(options: UnifiedCheckOptions & {
     json: true;

package/dist/check.js

@@ -1,9 +1,9 @@
 import { inspectNativeHostInstallation } from './nativeHost.js';
 import { UnifiedClient, normalizeBrowserSelector, } from './unified.js';
 const UPDATE_SOURCES = {
-    client: 'https://registry.npmjs.org/@mearl%2Fclient/latest',
-    'native-host': 'https://registry.npmjs.org/@mearl%2Fnative-host/latest',
-    'cloud-connector': 'https://registry.npmjs.org/@mearl%2Fcloud-connector/latest',
+    client: 'https://registry.npmjs.org/@mearl%2Fclient',
+    'native-host': 'https://registry.npmjs.org/@mearl%2Fnative-host',
+    'cloud-connector': 'https://registry.npmjs.org/@mearl%2Fcloud-connector',
     extension: 'https://mearl.alibaba-inc.com/config.json',
 };
 export function parseReleaseVersion(value) {
@@ -29,14 +29,42 @@ export function isNewerRelease(latest, installed) {
     }
     return false;
 }
-async function fetchLatestVersion(component) {
+export async function fetchLatestStablePackageVersion(component, installedVersion) {
+    const major = parseReleaseVersion(installedVersion)?.[0];
     const response = await fetch(UPDATE_SOURCES[component], {
+        headers: { Accept: 'application/vnd.npm.install-v1+json' },
+        signal: AbortSignal.timeout(2_000),
+    });
+    if (!response.ok)
+        throw new Error(`Registry returned HTTP ${response.status}`);
+    const payload = (await response.json());
+    const tagged = payload['dist-tags']?.latest;
+    const taggedParts = parseReleaseVersion(tagged);
+    if (tagged && taggedParts && taggedParts[0] === major && taggedParts[3] === 1)
+        return tagged;
+    let latest;
+    for (const version of Object.keys(payload.versions ?? {})) {
+        const parts = parseReleaseVersion(version);
+        if (parts &&
+            parts[0] === major &&
+            parts[3] === 1 &&
+            (!latest || isNewerRelease(version, latest))) {
+            latest = version;
+        }
+    }
+    if (!latest)
+        throw new Error('Registry returned no stable release for the installed major version');
+    return latest;
+}
+async function fetchLatestVersion(component, clientVersion) {
+    if (component !== 'extension')
+        return fetchLatestStablePackageVersion(component, clientVersion);
+    const response = await fetch(UPDATE_SOURCES.extension, {
         signal: AbortSignal.timeout(1500),
     });
     if (!response.ok)
         throw new Error(`HTTP ${response.status}`);
-    const payload = (await response.json());
-    const version = component === 'extension' ? payload.latestVersion : payload.version;
+    const { latestVersion: version } = (await response.json());
     if (!parseReleaseVersion(version))
         throw new Error('Invalid release version');
     return version;
@@ -141,7 +169,8 @@ export async function runUnifiedCheck(options, dependencies = {}) {
         requestTimeoutSec: timeoutSec,
     });
     const latestVersions = options.checkUpdates
-        ? Promise.allSettled(Object.keys(UPDATE_SOURCES).map(component => (dependencies.fetchLatestVersion ?? fetchLatestVersion)(component)))
+        ? Promise.allSettled(Object.keys(UPDATE_SOURCES).map(component => dependencies.fetchLatestVersion?.(component) ??
+            fetchLatestVersion(component, options.clientVersion)))
         : null;
     const environment = [
         { status: 'ok', label: `Unified client v${options.clientVersion}` },
@@ -401,7 +430,7 @@ export async function runUnifiedCheck(options, dependencies = {}) {
             const available = updates.filter(update => update.status === 'available');
             const unavailable = updates.filter(update => update.status === 'unavailable');
             const packageUpdateAvailable = available.some(update => update.component === 'client' || update.component === 'native-host');
-            const extensionUpdateAvailable = available.some(update => update.component === 'extension');
+            const extensionUpdate = available.find(update => update.component === 'extension');
             const connectorUpdateAvailable = available.some(update => update.component === 'cloud-connector');
             environment.push({
                 status: available.length || unavailable.length ? 'warning' : 'ok',
@@ -413,10 +442,12 @@ export async function runUnifiedCheck(options, dependencies = {}) {
                 details: [
                     ...available.map(update => `${update.component}: ${update.installed} → ${update.latest}`),
                     ...(packageUpdateAvailable
-                        ? ['Update on the affected machine: npx @mearl/setup update']
+                        ? ['Update Mearl 2.x on the affected machine: npx @mearl/setup@2 update --skip-skill']
                         : []),
-                    ...(extensionUpdateAvailable
-                        ? ['Update a setup-managed extension: npx @mearl/setup extension']
+                    ...(extensionUpdate
+                        ? [
+                            `Update the Chrome extension from its release ZIP: ${new URL(`mearl-chrome-v${extensionUpdate.latest}.zip`, UPDATE_SOURCES.extension).href}`,
+                        ]
                         : []),
                     ...(connectorUpdateAvailable
                         ? ['Update cloud-connector with its package manager on the connector machine.']

package/dist/cli.js

@@ -237,7 +237,7 @@ function printProviderHelp(commandName, provider, extensionHelp) {
             lines.push(`  ${mode}（必填：${requiredFields}）`);
         });
     }
-    lines.push('', '发现与检查：', `  ${commandName} browser_list`, `  ${commandName} check --browser <browserId>`, '', '管理：', `  npx @mearl/setup provider update ${provider.providerId}`, `  npx @mearl/setup provider uninstall ${provider.providerId}`);
+    lines.push('', '发现与检查：', `  ${commandName} browser_list`, `  ${commandName} check --browser <browserId>`, '', '管理：', `  npx @mearl/setup@2 provider update ${provider.providerId}`, `  npx @mearl/setup@2 provider uninstall ${provider.providerId}`);
     if (browserType.configuration) {
         lines.push('', 'Provider 配置（在 Mearl 浏览器管理器中填写）：');
         const configurationRequired = new Set(browserType.configuration.inputSchema.required ?? []);

package/dist/generated/plugin-host-build.d.ts

@@ -1 +1 @@
-export declare const PLUGIN_HOST_BUILD_ID = "83323695c8ac2e39755494d27cb70be47d162c502111d32a1fc6d6be71981f18";
+export declare const PLUGIN_HOST_BUILD_ID = "83b778ad78c82ef3cd6d48e2a23b118d36e60b9adceda991f943f9c346dd10fe";

package/dist/generated/plugin-host-build.js

@@ -1,2 +1,2 @@
 // Generated by scripts/generate-plugin-host-build.mjs.
-export const PLUGIN_HOST_BUILD_ID = '83323695c8ac2e39755494d27cb70be47d162c502111d32a1fc6d6be71981f18';
+export const PLUGIN_HOST_BUILD_ID = '83b778ad78c82ef3cd6d48e2a23b118d36e60b9adceda991f943f9c346dd10fe';

package/dist/nativeHost.js

@@ -98,7 +98,7 @@ export function inspectNativeHostInstallation(options = {}) {
                 details: [
                     ...details,
                     `Registration: ${manifestPath}`,
-                    'Run `mearl-native-host init` with a working Node.js, then reopen the extension. If the runtime package is missing, run `npx @mearl/setup update --local`.',
+                    'Run `mearl-native-host init` with a working Node.js, then reopen the extension. If the runtime package is missing, run `npx @mearl/setup@2 update --local`.',
                 ],
             });
         }

package/dist/plugins/officialPluginInstaller.js

@@ -2,6 +2,7 @@ import { closeSync, mkdirSync, openSync, rmSync, statSync, writeFileSync } from
 import { CLIENT_VERSION } from '../runtimePaths.js';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
+import { npmExecEnvironment } from '@mearl/daemon-core';
 import { findOfficialPlugin } from './officialPluginCatalog.js';
 import { findPluginRegistration, pluginDirectory } from './pluginRegistry.js';
 const INSTALL_TIMEOUT_MS = 180_000;
@@ -60,7 +61,7 @@ function appendOutput(current, chunk) {
 function installWithSetup(name) {
     return new Promise((resolve, reject) => {
         const command = process.platform === 'win32' ? 'npx.cmd' : 'npx';
-        const child = spawn(command, ['-y', `@mearl/setup@${CLIENT_VERSION}`, 'plugin', 'ensure', name], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        const child = spawn(command, ['-y', `@mearl/setup@${CLIENT_VERSION}`, 'plugin', 'ensure', name], { env: npmExecEnvironment(), stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
         let stdout = '';
         let stderr = '';
         let settled = false;

package/dist/plugins/sdk/plugin.js

@@ -79,7 +79,7 @@ function missingPluginEntryMessage(entry, pluginName) {
         `插件：${name}`,
         `入口：${entry}`,
         '',
-        `卸载命令：npx @mearl/setup plugin uninstall ${name}`,
+        `卸载命令：npx @mearl/setup@2 plugin uninstall ${name}`,
     ].join('\n');
 }
 const registrationRefreshes = new Map();

package/dist/socket.js

@@ -676,7 +676,7 @@ function formatConnectError(error, socketPath) {
     if (error.code === 'ENOENT') {
         return [
             `未找到 Socket: ${socketPath}`,
-            'native host 自动拉起失败。先运行 mearl check --local；缺少命令时运行 npx @mearl/setup --local --yes。',
+            'native host 自动拉起失败。先运行 mearl check --local；缺少命令时运行 npx @mearl/setup@2 --local --yes。',
             '自动拉起只使用默认 daemon 参数；自定义 CDP/Profile/浏览器参数需手工启动，参见 mearl-native-host --help。',
             '',
             '【方式一：浏览器插件模式】',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.22.4",
+  "version": "2.23.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -58,19 +58,19 @@
   ],
   "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",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/daemon-core": "2.22.4",
-    "@mearl/agent-runtime": "2.22.4",
-    "@mearl/cloud-types": "2.22.4",
-    "@mearl/provider": "2.22.4"
+    "@mearl/daemon-core": "2.23.0",
+    "@mearl/cloud-types": "2.23.0",
+    "@mearl/agent-runtime": "2.23.0",
+    "@mearl/provider": "2.23.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",