@mearl/client 2.17.1 → 2.19.0

package/dist/pluginRegistry.d.ts

@@ -2,20 +2,59 @@ export declare class PluginError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
 }
+export interface PluginToolboxSandboxPage {
+    type: 'sandbox';
+    runtime?: 'preact';
+    entry: string;
+    commands: string[];
+}
+export interface PluginToolboxLocale {
+    title?: string;
+    description?: string;
+}
+export interface PluginToolboxAgentConfig {
+    skill: string;
+    layout?: 'drawer' | 'workspace';
+}
+export interface PluginToolboxContribution {
+    version: 1;
+    title: string;
+    description?: string;
+    icon?: string;
+    locales?: Record<string, PluginToolboxLocale>;
+    agent?: PluginToolboxAgentConfig;
+    page: PluginToolboxSandboxPage;
+    order?: number;
+}
+export interface PluginPageBundleRegistration {
+    hash: string;
+    size: number;
+    chunks: number;
+}
 export interface PluginRegistration {
     entry: string;
     description?: string;
     managedBy?: string;
+    toolbox?: PluginToolboxContribution;
+    pageBundle?: PluginPageBundleRegistration;
 }
 export interface PluginRegistrationOptions {
     managedBy?: string;
+    toolbox?: PluginToolboxContribution;
 }
 export declare function pluginDirectory(): string;
 export declare function assertPluginName(name: string): void;
+export declare function normalizePluginToolboxContribution(value: unknown): PluginToolboxContribution | undefined;
 export declare function findPluginDirectoryEntry(directory: string): string | undefined;
 export declare function resolvePluginEntry(target: string): string;
 export declare function registerPlugin(name: string, target: string, description?: string, options?: PluginRegistrationOptions): string;
 export declare function unregisterPlugin(name: string): boolean;
 export declare function findPluginRegistration(name: string): PluginRegistration | undefined;
+export declare function readPluginPageBundleChunk(name: string, hash: string, index: number): {
+    data: string;
+    hash: string;
+    index: number;
+    total: number;
+};
 export declare function findPluginEntry(name: string): string | undefined;
 export declare function listPluginNames(): string[];

package/dist/pluginRegistry.js

@@ -1,8 +1,9 @@
 import { randomUUID } from 'node:crypto';
-import { mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { closeSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
 import { isAbsolute, join, resolve } from 'node:path';
 import { COMMAND_MAP } from './commands.js';
+import { buildPluginPageBundle, PLUGIN_PAGE_CHUNK_BYTES, } from './pluginPageBundle.js';
 const RESERVED_NAMES = new Set([
     'check',
     'help',
@@ -21,11 +22,196 @@ export class PluginError extends Error {
 export function pluginDirectory() {
     return resolve(process.env.MEARL_PLUGIN_DIR || join(homedir(), '.mearl', 'plugins'));
 }
+function pluginPageDirectory() {
+    return join(pluginDirectory(), '.pages');
+}
+function pluginPageBundlePath(name, hash) {
+    return join(pluginPageDirectory(), `${name}-${hash}.html`);
+}
+function removePluginPageBundles(name, exceptHash) {
+    let files;
+    try {
+        files = readdirSync(pluginPageDirectory());
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    const keep = exceptHash ? `${name}-${exceptHash}.html` : undefined;
+    for (const file of files) {
+        if (file === keep || !file.startsWith(`${name}-`) || !file.endsWith('.html'))
+            continue;
+        rmSync(join(pluginPageDirectory(), file), { force: true });
+    }
+}
+function normalizePageBundle(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('invalid page bundle');
+    }
+    const candidate = value;
+    if (typeof candidate.hash !== 'string' ||
+        !/^[a-f0-9]{64}$/.test(candidate.hash) ||
+        !Number.isInteger(candidate.size) ||
+        (candidate.size ?? 0) <= 0 ||
+        !Number.isInteger(candidate.chunks) ||
+        candidate.chunks !== Math.ceil((candidate.size ?? 0) / PLUGIN_PAGE_CHUNK_BYTES)) {
+        throw new Error('invalid page bundle');
+    }
+    return {
+        hash: candidate.hash,
+        size: candidate.size,
+        chunks: candidate.chunks,
+    };
+}
+function persistPluginPageBundle(name, bundle) {
+    const directory = pluginPageDirectory();
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const target = pluginPageBundlePath(name, bundle.hash);
+    try {
+        if (statSync(target).isFile())
+            return;
+    }
+    catch {
+        // 页面内容哈希变化时创建新的不可变产物。
+    }
+    const temporary = `${target}.${randomUUID()}.tmp`;
+    try {
+        writeFileSync(temporary, bundle.content, { mode: 0o600, flag: 'wx' });
+        renameSync(temporary, target);
+    }
+    finally {
+        rmSync(temporary, { force: true });
+    }
+}
 export function assertPluginName(name) {
     if (!/^[a-z][a-z0-9-]*$/.test(name) || RESERVED_NAMES.has(name) || COMMAND_MAP.has(name)) {
         throw new PluginError('PLUGIN_INVALID_NAME', `不可用的插件名称: ${name}`);
     }
 }
+export function normalizePluginToolboxContribution(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        throw new Error('toolbox 必须是对象');
+    }
+    const candidate = value;
+    const title = typeof candidate.title === 'string' ? candidate.title.trim() : '';
+    const description = typeof candidate.description === 'string' ? candidate.description.trim() : undefined;
+    const icon = typeof candidate.icon === 'string' ? candidate.icon.trim() : undefined;
+    if (candidate.version !== 1)
+        throw new Error('toolbox.version 必须为 1');
+    if (!title || title.length > 80)
+        throw new Error('toolbox.title 必须是 1-80 个字符');
+    if (description && description.length > 240) {
+        throw new Error('toolbox.description 不能超过 240 个字符');
+    }
+    if (icon && (!/^[a-z][a-z0-9-]*$/.test(icon) || icon.length > 40)) {
+        throw new Error('toolbox.icon 必须是短横线命名的图标名称');
+    }
+    let locales;
+    if (candidate.locales !== undefined) {
+        if (!candidate.locales ||
+            typeof candidate.locales !== 'object' ||
+            Array.isArray(candidate.locales)) {
+            throw new Error('toolbox.locales 必须是对象');
+        }
+        const entries = Object.entries(candidate.locales);
+        if (entries.length === 0 || entries.length > 20) {
+            throw new Error('toolbox.locales 必须包含 1-20 个语言');
+        }
+        locales = Object.fromEntries(entries.map(([locale, localized]) => {
+            if (!/^[a-z]{2,3}(?:[_-][A-Za-z0-9]{2,8})*$/.test(locale)) {
+                throw new Error(`toolbox.locales 包含无效语言: ${locale}`);
+            }
+            if (!localized || typeof localized !== 'object' || Array.isArray(localized)) {
+                throw new Error(`toolbox.locales.${locale} 必须是对象`);
+            }
+            const localizedTitle = typeof localized.title === 'string' ? localized.title.trim() : undefined;
+            const localizedDescription = typeof localized.description === 'string' ? localized.description.trim() : undefined;
+            if (localizedTitle !== undefined && (!localizedTitle || localizedTitle.length > 80)) {
+                throw new Error(`toolbox.locales.${locale}.title 必须是 1-80 个字符`);
+            }
+            if (localizedDescription !== undefined && localizedDescription.length > 240) {
+                throw new Error(`toolbox.locales.${locale}.description 不能超过 240 个字符`);
+            }
+            if (!localizedTitle && !localizedDescription) {
+                throw new Error(`toolbox.locales.${locale} 至少声明 title 或 description`);
+            }
+            return [
+                locale,
+                {
+                    ...(localizedTitle ? { title: localizedTitle } : {}),
+                    ...(localizedDescription ? { description: localizedDescription } : {}),
+                },
+            ];
+        }));
+    }
+    if (!candidate.page || typeof candidate.page !== 'object' || Array.isArray(candidate.page)) {
+        throw new Error('toolbox.page 必须是对象');
+    }
+    const pageCandidate = candidate.page;
+    if (pageCandidate.type !== 'sandbox') {
+        throw new Error('toolbox.page.type 必须为 sandbox');
+    }
+    if (pageCandidate.runtime !== undefined && pageCandidate.runtime !== 'preact') {
+        throw new Error('toolbox.page.runtime 仅支持 preact');
+    }
+    const pageEntry = typeof pageCandidate.entry === 'string' ? pageCandidate.entry.trim() : '';
+    if (!pageEntry ||
+        pageEntry.length > 240 ||
+        isAbsolute(pageEntry) ||
+        pageEntry.includes('\\') ||
+        pageEntry.split('/').some(segment => !segment || segment === '.' || segment === '..')) {
+        throw new Error('toolbox.page.entry 必须是插件目录内的相对 HTML 路径');
+    }
+    if (!Array.isArray(pageCandidate.commands)) {
+        throw new Error('toolbox.page.commands 必须是命令名称数组');
+    }
+    const commands = pageCandidate.commands.map(command => typeof command === 'string' ? command.trim() : '');
+    if (commands.length === 0 ||
+        commands.length > 64 ||
+        new Set(commands).size !== commands.length ||
+        commands.some(command => !/^[a-z][a-z0-9-]*$/.test(command))) {
+        throw new Error('toolbox.page.commands 必须包含 1-64 个不重复的插件命令名称');
+    }
+    const page = {
+        type: 'sandbox',
+        ...(pageCandidate.runtime ? { runtime: pageCandidate.runtime } : {}),
+        entry: pageEntry,
+        commands,
+    };
+    let agent;
+    if (candidate.agent !== undefined) {
+        if (!candidate.agent || typeof candidate.agent !== 'object' || Array.isArray(candidate.agent)) {
+            throw new Error('toolbox.agent 必须是对象');
+        }
+        const agentCandidate = candidate.agent;
+        const skill = typeof agentCandidate.skill === 'string' ? agentCandidate.skill.trim() : '';
+        if (!skill || skill.length > 128 || !/^[A-Za-z0-9][A-Za-z0-9._:@/-]*$/.test(skill)) {
+            throw new Error('toolbox.agent.skill 必须是有效的 Skill 名称');
+        }
+        const layout = agentCandidate.layout;
+        if (layout !== undefined && layout !== 'drawer' && layout !== 'workspace') {
+            throw new Error('toolbox.agent.layout 必须是 drawer 或 workspace');
+        }
+        agent = { skill, ...(layout ? { layout } : {}) };
+    }
+    if (candidate.order !== undefined &&
+        (!Number.isInteger(candidate.order) || candidate.order < 0 || candidate.order > 10_000)) {
+        throw new Error('toolbox.order 必须是 0-10000 的整数');
+    }
+    return {
+        version: 1,
+        title,
+        ...(description ? { description } : {}),
+        ...(icon ? { icon } : {}),
+        ...(locales ? { locales } : {}),
+        ...(agent ? { agent } : {}),
+        page,
+        ...(candidate.order !== undefined ? { order: candidate.order } : {}),
+    };
+}
 export function findPluginDirectoryEntry(directory) {
     for (const filename of ['main.mjs', 'main.py']) {
         const entry = join(directory, 'scripts', filename);
@@ -63,10 +249,31 @@ export function registerPlugin(name, target, description, options = {}) {
     const temporary = `${file}.${randomUUID()}.tmp`;
     const summary = description?.trim();
     const managedBy = options.managedBy?.trim();
+    let toolbox;
+    try {
+        toolbox = normalizePluginToolboxContribution(options.toolbox);
+    }
+    catch (error) {
+        throw new PluginError('PLUGIN_INVALID_TOOLBOX', error instanceof Error ? error.message : String(error));
+    }
+    let builtPage;
+    if (toolbox) {
+        try {
+            builtPage = buildPluginPageBundle(entry, toolbox.page.entry);
+        }
+        catch (error) {
+            throw new PluginError('PLUGIN_INVALID_TOOLBOX_PAGE', error instanceof Error ? error.message : String(error));
+        }
+        persistPluginPageBundle(name, builtPage);
+    }
     const record = {
         entry,
         ...(summary ? { description: summary } : {}),
         ...(managedBy ? { managedBy } : {}),
+        ...(toolbox ? { toolbox } : {}),
+        ...(builtPage
+            ? { pageBundle: { hash: builtPage.hash, size: builtPage.size, chunks: builtPage.chunks } }
+            : {}),
     };
     try {
         writeFileSync(temporary, `${JSON.stringify(record)}\n`, { mode: 0o600, flag: 'wx' });
@@ -75,6 +282,7 @@ export function registerPlugin(name, target, description, options = {}) {
     finally {
         rmSync(temporary, { force: true });
     }
+    removePluginPageBundles(name, builtPage?.hash);
     return entry;
 }
 export function unregisterPlugin(name) {
@@ -82,6 +290,7 @@ export function unregisterPlugin(name) {
     const file = join(pluginDirectory(), `${name}.json`);
     try {
         rmSync(file);
+        removePluginPageBundles(name);
         return true;
     }
     catch (error) {
@@ -113,16 +322,67 @@ export function findPluginRegistration(name) {
         const managedBy = typeof record.managedBy === 'string' && record.managedBy.trim()
             ? record.managedBy.trim()
             : undefined;
+        const toolbox = normalizePluginToolboxContribution(record.toolbox);
+        const pageBundle = toolbox ? normalizePageBundle(record.pageBundle) : undefined;
         return {
             entry: record.entry,
             ...(description ? { description } : {}),
             ...(managedBy ? { managedBy } : {}),
+            ...(toolbox ? { toolbox } : {}),
+            ...(pageBundle ? { pageBundle } : {}),
         };
     }
     catch {
         throw new PluginError('PLUGIN_REGISTRY_INVALID', `无效的插件记录: ${file}`);
     }
 }
+export function readPluginPageBundleChunk(name, hash, index) {
+    assertPluginName(name);
+    const registration = findPluginRegistration(name);
+    const bundle = registration?.pageBundle;
+    if (!bundle || bundle.hash !== hash) {
+        throw new PluginError('PLUGIN_PAGE_CHANGED', `插件页面已更新: ${name}`);
+    }
+    if (!Number.isInteger(index) || index < 0 || index >= bundle.chunks) {
+        throw new PluginError('PLUGIN_PAGE_CHUNK_INVALID', `插件页面分块无效: ${index}`);
+    }
+    const path = pluginPageBundlePath(name, hash);
+    let size;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        throw new PluginError('PLUGIN_PAGE_INVALID', `插件页面产物不存在: ${name}`);
+    }
+    if (size !== bundle.size) {
+        throw new PluginError('PLUGIN_PAGE_INVALID', `插件页面产物损坏: ${name}`);
+    }
+    const start = index * PLUGIN_PAGE_CHUNK_BYTES;
+    const content = Buffer.allocUnsafe(Math.min(PLUGIN_PAGE_CHUNK_BYTES, bundle.size - start));
+    let descriptor;
+    try {
+        descriptor = openSync(path, 'r');
+    }
+    catch {
+        throw new PluginError('PLUGIN_PAGE_INVALID', `插件页面产物无法读取: ${name}`);
+    }
+    let bytesRead;
+    try {
+        bytesRead = readSync(descriptor, content, 0, content.byteLength, start);
+    }
+    finally {
+        closeSync(descriptor);
+    }
+    if (bytesRead !== content.byteLength) {
+        throw new PluginError('PLUGIN_PAGE_INVALID', `插件页面产物损坏: ${name}`);
+    }
+    return {
+        data: content.toString('base64'),
+        hash,
+        index,
+        total: bundle.chunks,
+    };
+}
 export function findPluginEntry(name) {
     return findPluginRegistration(name)?.entry;
 }

package/dist/pythonPlugin.d.ts

@@ -7,6 +7,7 @@ export interface PythonPluginDescriptor {
     commands: PythonPluginCommand[];
     description?: string;
     name?: string;
+    toolbox?: unknown;
 }
 export interface PythonPluginApp {
     readonly options: Readonly<PluginOptions>;

package/dist/pythonPlugin.js

@@ -143,10 +143,13 @@ try:
 
     plugin_name = getattr(module, "name", None)
     plugin_description = getattr(module, "description", None)
+    plugin_toolbox = getattr(module, "toolbox", None)
     if plugin_name is not None and not isinstance(plugin_name, str):
         raise TypeError("入口的 name 必须为字符串")
     if plugin_description is not None and not isinstance(plugin_description, str):
         raise TypeError("入口的 description 必须为字符串")
+    if plugin_toolbox is not None and not isinstance(plugin_toolbox, dict):
+        raise TypeError("入口的 toolbox 必须为对象")
     register = getattr(module, "register", None)
     if not callable(register):
         raise TypeError("入口必须导出 register(app) 函数")
@@ -168,6 +171,8 @@ try:
         descriptor["name"] = plugin_name
     if plugin_description is not None:
         descriptor["description"] = plugin_description
+    if plugin_toolbox is not None:
+        descriptor["toolbox"] = plugin_toolbox
     _send(descriptor)
 
     if mode == "run":
@@ -233,6 +238,7 @@ function parseDescriptor(message) {
         commands,
         ...(typeof message.name === 'string' ? { name: message.name } : {}),
         ...(typeof message.description === 'string' ? { description: message.description } : {}),
+        ...(message.toolbox !== undefined ? { toolbox: message.toolbox } : {}),
     };
 }
 function bridgedError(message) {

package/dist/socket.js

@@ -13,7 +13,8 @@ import os from 'node:os';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { StringDecoder } from 'node:string_decoder';
-import { ensureInstalledProvidersRunning } from '@mearl/provider/runtime';
+import { listInstalledProviders } from '@mearl/provider/host';
+import { readLiveProvider } from '@mearl/provider/runtime';
 import { resolveFileRefs } from './fileRefs.js';
 import { listLiveBrowsers, findBrowser, describeBrowser, } from './browserRegistry.js';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
@@ -95,12 +96,8 @@ function browserListFromProviderRecords(browsers) {
         browsers: providerBrowsers,
     };
 }
-function mergeWarnings(result, warnings) {
-    const resultWarnings = Array.isArray(result?.warnings)
-        ? result.warnings.filter((warning) => typeof warning === 'string')
-        : [];
-    const merged = [...new Set([...resultWarnings, ...warnings])];
-    return { ...result, ...(merged.length > 0 ? { warnings: merged } : {}) };
+function areInstalledProvidersRunning() {
+    return listInstalledProviders().every(provider => readLiveProvider(provider.providerId));
 }
 function isConnectedBrowser(browser) {
     return browser.status === undefined || browser.status === 'connected';
@@ -243,11 +240,7 @@ export function invoke(action, data = {}, options = {}) {
     // 统一解析 payload 顶层字段中的 `@<path>` 文件引用（所有 action 通用）
     const resolvedData = resolveFileRefs(data);
     if (action === 'browser_list') {
-        const hasNativeAggregator = listLiveBrowsers().some(liveBrowser => liveBrowser.transport !== 'provider');
-        const providerStartup = hasNativeAggregator
-            ? Promise.resolve([])
-            : ensureInstalledProvidersRunning();
-        return providerStartup.then(providerWarnings => dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined, controlSource).then(result => decorateBrowserListResult(mergeWarnings(result, providerWarnings))));
+        return dispatchInvoke(action, resolvedData, timeoutSec, undefined, undefined, controlSource).then(result => decorateBrowserListResult(result));
     }
     const selector = browser ?? defaultBrowser ?? process.env.MEARL_BROWSER ?? undefined;
     return dispatchInvoke(action, resolvedData, timeoutSec, transport, selector, controlSource);
@@ -325,7 +318,9 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
                 throw error;
         }
     }
-    if (action === 'browser_list' && browsers.some(browser => browser.transport === 'provider')) {
+    if (action === 'browser_list' &&
+        browsers.some(browser => browser.transport === 'provider') &&
+        areInstalledProvidersRunning()) {
         return browserListFromProviderRecords(browsers);
     }
     return invokeViaLegacy(action, data, timeoutSec, transport, controlSource, /* isRetry */ false);

package/dist/unifiedConfig.d.ts

@@ -1,6 +1,8 @@
 export interface CloudServerConfig {
     server: string;
 }
+/** Number of local calendar days between CLI update checks; null disables them. */
+export declare function loadCliAutoUpdateIntervalDays(configPath?: string): number | null;
 export declare function getCloudServerConfigPath(): string;
 export declare function loadCloudServerConfig(): CloudServerConfig | null;
 export declare function loadLocalConnectorId(): string | null;

package/dist/unifiedConfig.js

@@ -2,6 +2,29 @@ import { existsSync, readFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 const MEARL_CONFIG_DIR = join(homedir(), '.mearl');
+/** Number of local calendar days between CLI update checks; null disables them. */
+export function loadCliAutoUpdateIntervalDays(configPath = join(MEARL_CONFIG_DIR, 'config.json')) {
+    try {
+        const config = JSON.parse(readFileSync(configPath, 'utf8'));
+        if (config.cliAutoUpdate === false)
+            return null;
+        if (config.cliAutoUpdate === undefined)
+            return 1;
+        if (typeof config.cliAutoUpdate === 'object' &&
+            config.cliAutoUpdate !== null &&
+            !Array.isArray(config.cliAutoUpdate)) {
+            const { intervalDays } = config.cliAutoUpdate;
+            if (typeof intervalDays === 'number' &&
+                Number.isSafeInteger(intervalDays) &&
+                intervalDays > 0)
+                return intervalDays;
+        }
+    }
+    catch {
+        // A missing or invalid config uses the daily default.
+    }
+    return 1;
+}
 export function getCloudServerConfigPath() {
     return join(MEARL_CONFIG_DIR, 'cloud-server.json');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.17.1",
+  "version": "2.19.0",
   "description": "Unified Mearl SDK & CLI for local and remote browsers",
   "type": "module",
   "main": "dist/index.js",
@@ -59,8 +59,8 @@
     "commander": "^15.0.0",
     "fastest-levenshtein": "^1.0.16",
     "ws": "^8.18.0",
-    "@mearl/cloud-types": "2.17.1",
-    "@mearl/provider": "2.17.1"
+    "@mearl/provider": "2.19.0",
+    "@mearl/cloud-types": "2.19.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",