@mearl/client 2.17.0 → 2.18.0

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';
@@ -117,6 +114,9 @@ function supportsAction(browser, action, data) {
         const required = data.deleteProfile === true ? 'deleteData' : 'close';
         return browser.operations?.includes(required) === true;
     }
+    if (action === 'browser_release') {
+        return browser.transport !== 'provider' || browser.operations?.includes('detach') === true;
+    }
     if (!isConnectedBrowser(browser))
         return false;
     return (browser.transport !== 'provider' ||
@@ -240,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);
@@ -282,7 +278,10 @@ async function dispatchInvoke(action, data, timeoutSec, transport, selector, con
         if (transport === 'cdp' && match.transport === 'provider') {
             throw new Error(`Browser ${describeBrowser(match)} does not support the CDP transport`);
         }
-        if (match.status === 'pairing' && action !== 'get_versions' && action !== 'browser_close') {
+        if (match.status === 'pairing' &&
+            action !== 'get_versions' &&
+            action !== 'browser_close' &&
+            action !== 'browser_release') {
             throw new Error(`Browser ${describeBrowser(match)} is waiting for device pairing`);
         }
         if (!supportsAction(match, action, data)) {
@@ -319,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/unified.js

@@ -1,6 +1,7 @@
 import WebSocket from 'ws';
 import { DEFAULT_CONNECT_TIMEOUT, DEFAULT_HEARTBEAT_INTERVAL, DEFAULT_REQUEST_TIMEOUT, MAX_BUFFER_SIZE, isHeartbeatMessage, resolveCloudConnectorSelector, } from '@mearl/cloud-types';
 import { resolveActionTimeoutSec } from './actionTimeouts.js';
+import { validateRequiredActionTabId, } from './generated-browser-action-protocol.js';
 import { invoke as invokeLocalBrowser } from './socket.js';
 import { loadCloudServerConfig, loadLocalConnectorId } from './unifiedConfig.js';
 const RESPONSE_GRACE_MS = 1_000;
@@ -126,6 +127,7 @@ export class UnifiedClient {
         }, options);
     }
     async invoke(action, data = {}, options = {}) {
+        validateRequiredActionTabId(action, data);
         const timeoutSec = options.timeoutSec ?? resolveActionTimeoutSec(action, data, this.options.requestTimeoutSec);
         if (action === 'connector_list')
             return this.listConnectors(timeoutSec);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mearl/client",
-  "version": "2.17.0",
+  "version": "2.18.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/provider": "2.17.0",
-    "@mearl/cloud-types": "2.17.0"
+    "@mearl/cloud-types": "2.18.0",
+    "@mearl/provider": "2.18.0"
   },
   "devDependencies": {
     "@types/node": "^24.9.1",