@mearl/client 2.17.1 → 2.18.0

package/README.md

@@ -149,7 +149,7 @@ mearl yuque --version
 Provider 与插件仍可独立安装、更新和卸载，帮助聚合不会启动 Provider 或执行业务命令。
 
 目录默认使用 `scripts/main.mjs` 或 `scripts/main.py`；两者同时存在时使用 JavaScript 入口。JavaScript 入口默认导出 `register(app)`，Python 入口导出 `register(app)` 函数；两种入口都可声明简短的 `name` 和 `description`，并通过 `app.command(signature, handler, description?)`
-注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。Python 的 `app.invoke` 是同步调用，handler 可以是普通函数或 `async def`。Python 插件要求 `python3 >= 3.9`，可用 `MEARL_PYTHON` 指定解释器路径；Mearl 不安装 Python 或执行 `pip install`。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
+注册动作、`app.invoke(action, payload, options?)` 复用当前浏览器上下文，并用 `app.progress(message)` 报告可选进度。JavaScript 插件还可传入 `{ message, data }`，让工具页通过可 JSON 序列化的 `data` 获取稳定的阶段、对象 ID 等机器信息；CLI 仍只显示 `message`。Python 的 `app.invoke` 是同步调用，handler 可以是普通函数或 `async def`。Python 插件要求 `python3 >= 3.9`，可用 `MEARL_PYTHON` 指定解释器路径；Mearl 不安装 Python 或执行 `pip install`。调用另一个插件时，payload 使用 `{ command, input }` envelope；嵌套调用继承宿主选项并拒绝循环依赖。CLI 默认只输出最终结果，传入
 `--verbose` 时才把进度写入 stderr。handler 返回文本或 JSON，宿主统一处理 `--output`、连接和错误。写命令在用户调用后直接执行，业务模块负责目标、状态、幂等和结果校验。
 自动注册默认以 skill 安装目录名作为命令名，也可在入口声明 `name` 指定短名称。
 setup 会补齐缺失或低于自身版本的 client、native-host；安装参数透传给 Ali Skills，并固定全局共享安装。
@@ -186,6 +186,59 @@ MCP Server 通过固定工具 `mearl_plugin` 接受同样的 `plugin`、`command
 卸载清理命令。其他错误按实际原因处理。
 编写规范见 [Mearl Skill Creator 的 Skill 插件规范](../skills/mearl-skill-creator/references/cli-plugin.md)。
 
+插件可选导出 `toolbox`，注册后会出现在扩展 Popup 的工具箱中。页面资源放在 Skill 目录内，注册时由
+Mearl 将入口 HTML 引用的本地 CSS、JavaScript 和图片内联为不可变页面包，不需要启动 HTTP 服务，
+也不要求普通 HTML/CSS/JS 页面自行构建：
+
+```javascript
+export const toolbox = {
+  version: 1,
+  title: '迭代管理',
+  description: '查看多个仓库的改动与发布状态',
+  icon: 'git-branch',
+  locales: {
+    en: {
+      title: 'Iteration Management',
+      description: 'Track changes and release status across repositories',
+    },
+  },
+  agent: {
+    skill: 'iteration-manager',
+    layout: 'workspace',
+  },
+  page: {
+    type: 'sandbox',
+    runtime: 'preact',
+    entry: 'assets/toolbox/index.html',
+    commands: ['list', 'create', 'delete'],
+  },
+  order: 100,
+};
+
+export default function register(app) {
+  app.command('list', async () => ({ items: await listItems() }));
+  app.command('create <name>', async input => ({ item: await createItem(input.name) }));
+  app.command('delete <id>', async input => ({ item: await deleteItem(input.id) }));
+}
+```
+
+声明 `agent` 后工具页可以把任务交给对话 Agent；`layout` 默认为 `drawer`，宿主会提供顶部入口。
+页面也可在 `setAgentPanelVisible` 或 `runAgentTask` 中为单次交互指定 `drawer` / `workspace`。带固定
+18rem 左侧导航的工作台可默认使用 `workspace`，由导航项切换 Agent，并占满导航栏以外的主内容区；详情页仍可按需唤起右侧抽屉。
+
+页面通过 `await window.mearl.ready()` 取得 `{ locale, theme, title, fontSize }`，通过
+`window.mearl.invoke(command, input?)` 调用 `commands` 白名单中的同一插件命令。页面运行在无扩展
+API、默认不可联网的 sandbox iframe 中；Native Host 校验插件身份、命令白名单和消息大小。页面包按
+内容哈希缓存并分块传输，因此不会增加 Popup 的启动开销。使用模块脚本时需先打包为不再包含 `import`
+的单文件；React、Vue 等工程可以把构建后的 `index.html` 作为 `entry`，注册流程仍负责最终资源封装。
+需要无构建的组件与状态管理时可声明 `page.runtime: 'preact'`，扩展会在页面完整性校验后注入固定的
+Preact、Hooks 和 HTM 运行时。页面从 `window.mearl.ui` 读取 `html`、`render`、`useState` 等 API；
+`window.mearl.ui.version` 仅用于诊断，插件不能选择运行时版本。
+宿主会同步扩展主题、字号，并注入 `--mearl-bg-primary`、`--mearl-bg-secondary`、
+`--mearl-text-primary`、`--mearl-text-secondary`、`--mearl-border`、`--mearl-bg-hover` 和
+`--mearl-accent` 等语义变量；主操作按钮使用 `--mearl-action-primary`、
+`--mearl-action-primary-hover` 和 `--mearl-action-primary-text`，以保持与扩展按钮一致。
+
 需要 BUC 身份的内部 HTTP 接口通过官方 `buc` 插件调用。CLI 使用 `mearl buc request`，业务插件使用
 `app.invoke('buc', { command: 'request', input })`；当前身份和人员资料分别使用 `whoami` 与 `profile`
 子命令。BUC 插件按请求创建一次性凭据，只接受无 URL 凭据的 HTTPS 地址，过滤认证字段与 Cookie；

package/dist/cli.js

@@ -504,7 +504,8 @@ async function runPluginCli(args, commandName) {
             ...invokeOptions,
             ...(parsed.verbose
                 ? {
-                    onProgress(message) {
+                    onProgress(progress) {
+                        const message = typeof progress === 'string' ? progress : progress.message;
                         process.stderr.write(message.endsWith('\n') ? message : `${message}\n`);
                     },
                 }

package/dist/generated-browser-action-protocol.d.ts

@@ -365,7 +365,7 @@ export interface BrowserEmulationOptions {
     /** App 容器横屏时将根页面与业务页面分置左右 WebView；仅与 deviceShell、App 档案同时生效。 */
     splitScreen?: boolean;
 }
-export type AppBridgeConfigBehavior = 'navigate' | 'closeAll' | 'closeBackData' | 'postMessage' | 'notifySubscribe' | 'notifyUnsubscribe' | 'notifyPost' | 'sharedFileRead' | 'sharedFileWrite' | 'sharedDataGet' | 'sharedDataSet' | 'legacyBroadcastCreate' | 'legacyBroadcastPost' | 'legacyBroadcastClose' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'networkInfo' | 'geolocation' | 'permission' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest' | 'voiceRecognition';
+export type AppBridgeConfigBehavior = 'navigate' | 'closeAll' | 'closeBackData' | 'postMessage' | 'notifySubscribe' | 'notifyUnsubscribe' | 'notifyPost' | 'sharedFileRead' | 'sharedFileWrite' | 'sharedDataGet' | 'sharedDataSet' | 'legacyBroadcastCreate' | 'legacyBroadcastPost' | 'legacyBroadcastClose' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'networkInfo' | 'geolocation' | 'permission' | 'imagePicker' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest' | 'voiceRecognition';
 /** 单个桥方法的声明式覆盖；行为、固定回包、成功空实现三选一。 */
 export interface AppBridgeMethodConfig {
     behavior?: AppBridgeConfigBehavior;

package/dist/index.d.ts

@@ -6,7 +6,7 @@
  */
 export { UnifiedClient, UnifiedClient as MearlClient, decodeBrowserTarget, invoke, invokePlugin, listCloudConnectors, } from './unified.js';
 export type { UnifiedClientOptions, UnifiedInvokeOptions, UnifiedInvokeOptions as InvokeOptions, } from './unified.js';
-export type { PluginInvocation, PluginInvokeOptions } from './plugin.js';
+export type { PluginInvocation, PluginInvokeOptions, PluginProgress, StructuredPluginProgress, } from './plugin.js';
 export { APP_PROFILE_NAMES, BROWSER_DEVICE_PRESET_NAMES, BROWSER_ACTIONS, BROWSER_COMMAND_ACTIONS, EXTENSION_BROWSER_ACTIONS, PAGE_ACT_ACTIONS, SEND_REQUEST_MAX_FILES, SEND_REQUEST_MAX_TOTAL_BASE64_FILE_BYTES, SEND_REQUEST_MAX_TOTAL_FILE_BYTES, isBrowserAction, isBrowserCapabilityAction, isBrowserCommandAction, isExtensionBrowserAction, } from './generated-browser-action-protocol.js';
 export type { ActionStep, AppProfileName, BrowserAction, BrowserActionMap, BrowserActionRequest, BrowserActionResponse, BrowserCapabilities, BrowserCapabilityAction, BrowserCloseParams, BrowserCommandAction, BrowserInfo, BrowserInfoBase, BrowserJsonValue, BrowserLaunchParams, BrowserProviderOperation, BrowserListResult, BrowserPairingInfo, BrowserReleaseFailure, BrowserReleaseResult, BrowserProviderDefinition, BrowserProviderIdentity, BrowserProviderInputSchema, BrowserProviderListResult, BrowserReference, BrowserDetails, BrowserSource, BrowserStatus, BrowserScreenshotKind, BrowserTransport, CaptureCheckpointParams, CaptureCheckpointResult, BrowserDevicePresetName, BrowserEmulationOptions, ExtensionBrowserAction, GetCookieParams, GetCookieResult, GetEventsParams, GetLogsParams, GetMocksParams, GetRequestsParams, ManagedBrowserInfo, PageClickParams, PageDragEndpoint, PageDragParams, PageDragPoint, PageActAction, PageDiagnosticsOptions, PageDiagnosticsSetting, PageEvalParams, PageFramesParams, PageHoverParams, PageInspectFilter, PageInspectParams, PageNavigateParams, PageObservationWaitOptions, PagePressParams, PageScreenshotParams, PageScrollParams, PageSnapshotParams, PageSnapshotQuery, PageTypeParams, PageUploadParams, PageWaitParams, RegularBrowserInfo, RequestDomainPermissionParams, RulesResult, RunActionName, RunActionsParams, SelectBrowserParams, SelectBrowserResult, SendRequestFile, SendRequestFormValue, SendMtopRequestParams, SendRequestParams, SetAppProfileParams, SetCookieParams, SetCookieResult, SetDeviceEmulationParams, SetMockParams, SetRuleParams, SetTimezoneParams, SetTimezoneResult, TabCloseParams, TabOpenParams, } from './generated-browser-action-protocol.js';
 import { type UnifiedInvokeOptions } from './unified.js';

package/dist/plugin.d.ts

@@ -1,14 +1,20 @@
 import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
+import { type PluginToolboxContribution } from './pluginRegistry.js';
 import type { UnifiedInvokeOptions } from './unified.js';
-export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, type PluginRegistration, type PluginRegistrationOptions, } from './pluginRegistry.js';
+export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, type PluginRegistration, type PluginRegistrationOptions, type PluginToolboxAgentConfig, type PluginPageBundleRegistration, type PluginToolboxContribution, type PluginToolboxLocale, type PluginToolboxSandboxPage, } from './pluginRegistry.js';
 export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, type OfficialPluginDefinition, type OfficialPluginName, } from './officialPluginCatalog.js';
 export type PluginOptions = UnifiedInvokeOptions;
+export interface StructuredPluginProgress {
+    message: string;
+    data?: Record<string, unknown>;
+}
+export type PluginProgress = string | StructuredPluginProgress;
 export interface PluginInvocation {
     command: string;
     input: Record<string, any>;
 }
 export interface PluginInvokeOptions extends UnifiedInvokeOptions {
-    onProgress?: (message: string) => void;
+    onProgress?: (progress: PluginProgress) => void;
 }
 export interface PluginExecutionContext {
     ensurePlugin?: OfficialPluginInstaller;
@@ -18,13 +24,14 @@ export interface PluginApp {
     readonly options: Readonly<PluginOptions>;
     command(signature: string, handler: PluginHandler, description?: string): void;
     invoke(action: string, payload?: Record<string, any>, options?: UnifiedInvokeOptions): Promise<any>;
-    progress(message: string): void;
+    progress(progress: PluginProgress): void;
 }
 export type PluginHandler = (input: Record<string, any>) => unknown | Promise<unknown>;
 /** 注册和执行复用同一宿主能力边界；仅 handler 执行期间开放浏览器调用。 */
 export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invoke' | 'options' | 'progress'>, pluginName?: string): Promise<{
     name: string | undefined;
     description: string | undefined;
+    toolbox: PluginToolboxContribution | undefined;
     version: string | undefined;
     commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;
@@ -33,6 +40,7 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invo
 export declare function loadRegisteredPlugin(name: string, context: PluginExecutionContext, options?: PluginInvokeOptions): Promise<{
     name: string | undefined;
     description: string | undefined;
+    toolbox: PluginToolboxContribution | undefined;
     version: string | undefined;
     commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;

package/dist/plugin.js

@@ -5,9 +5,9 @@ import { Command } from 'commander';
 import { COMMAND_MAP } from './commands.js';
 import { findOfficialPlugin } from './officialPluginCatalog.js';
 import { ensureOfficialPluginRegistered, } from './officialPluginInstaller.js';
-import { findPluginRegistration, PluginError } from './pluginRegistry.js';
+import { findPluginRegistration, normalizePluginToolboxContribution, PluginError, } from './pluginRegistry.js';
 import { describePythonPlugin, runPythonPluginCommand } from './pythonPlugin.js';
-export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, } from './pluginRegistry.js';
+export { assertPluginName, findPluginDirectoryEntry, findPluginEntry, findPluginRegistration, listPluginNames, registerPlugin, resolvePluginEntry, unregisterPlugin, PluginError, readPluginPageBundleChunk, } from './pluginRegistry.js';
 export { findOfficialPlugin, listOfficialPluginNames, OFFICIAL_PLUGIN_MANAGER, OFFICIAL_PLUGINS, } from './officialPluginCatalog.js';
 function readPluginVersion(entry) {
     try {
@@ -26,6 +26,36 @@ function isObject(value) {
 function isPluginInvocation(value) {
     return isObject(value) && typeof value.command === 'string' && isObject(value.input);
 }
+function normalizePluginProgress(progress) {
+    if (typeof progress === 'string') {
+        if (!progress)
+            throw new Error('app.progress 需要非空消息');
+        return progress;
+    }
+    if (!isObject(progress) || typeof progress.message !== 'string' || !progress.message) {
+        throw new Error('app.progress 需要非空消息');
+    }
+    if (progress.data !== undefined && !isObject(progress.data)) {
+        throw new Error('app.progress data 必须是对象');
+    }
+    let data;
+    if (progress.data) {
+        try {
+            const serialized = JSON.stringify(progress.data);
+            const parsed = serialized === undefined ? undefined : JSON.parse(serialized);
+            if (!isObject(parsed))
+                throw new Error('invalid object');
+            data = Object.freeze(parsed);
+        }
+        catch {
+            throw new Error('app.progress data 必须是可 JSON 序列化的对象');
+        }
+    }
+    return Object.freeze({
+        message: progress.message,
+        ...(data ? { data } : {}),
+    });
+}
 function missingPluginEntryMessage(entry, pluginName) {
     const name = pluginName ?? '<name>';
     return [
@@ -54,6 +84,7 @@ export async function loadPlugin(entry, context, pluginName) {
     let registering = true;
     let name;
     let description;
+    let toolbox;
     const app = Object.freeze({
         options: Object.freeze({ ...context.options }),
         command(signature, handler, description = '') {
@@ -80,12 +111,10 @@ export async function loadPlugin(entry, context, pluginName) {
                 throw new Error('app.invoke 只能在命令执行期间调用');
             return context.invoke(action, payload, options);
         },
-        progress(message) {
+        progress(progress) {
             if (!executing)
                 throw new Error('app.progress 只能在命令执行期间调用');
-            if (typeof message !== 'string' || !message)
-                throw new Error('app.progress 需要非空字符串');
-            context.progress(message);
+            context.progress(normalizePluginProgress(progress));
         },
     });
     try {
@@ -93,6 +122,7 @@ export async function loadPlugin(entry, context, pluginName) {
             const descriptor = await describePythonPlugin(entry, app.options);
             name = descriptor.name;
             description = descriptor.description;
+            toolbox = normalizePluginToolboxContribution(descriptor.toolbox);
             for (const command of descriptor.commands) {
                 const commandName = command.signature.trim().split(/\s+/)[0];
                 app.command(command.signature, input => runPythonPluginCommand(entry, commandName, input, app), command.description);
@@ -108,12 +138,18 @@ export async function loadPlugin(entry, context, pluginName) {
             if (module.description !== undefined && typeof module.description !== 'string')
                 throw new Error('入口的 description 导出必须为字符串');
             description = module.description;
+            toolbox = normalizePluginToolboxContribution(module.toolbox);
             if (typeof module.default !== 'function')
                 throw new Error('入口必须默认导出 register(app) 函数');
             await module.default(app);
         }
         if (commands.size === 0)
             throw new Error('入口未注册任何命令');
+        const toolboxCommands = toolbox?.page.commands ?? [];
+        for (const command of toolboxCommands) {
+            if (!commands.has(command))
+                throw new Error(`toolbox 命令未注册: ${command}`);
+        }
     }
     catch (error) {
         throw new PluginError('PLUGIN_LOAD_FAILED', `${entry}: ${error instanceof Error ? error.message : String(error)}`);
@@ -130,6 +166,7 @@ export async function loadPlugin(entry, context, pluginName) {
     return {
         name,
         description,
+        toolbox,
         version: readPluginVersion(entry),
         commandHelp(namespace) {
             return [...commands.values()]
@@ -215,7 +252,7 @@ async function loadRegisteredPluginWithState(name, context, options = {}, state
     }
     let registration = findPluginRegistration(name);
     if (!registration && findOfficialPlugin(name)) {
-        await (context.ensurePlugin ?? ensureOfficialPluginRegistered)(name, options.onProgress);
+        await (context.ensurePlugin ?? ensureOfficialPluginRegistered)(name, options.onProgress ? message => options.onProgress?.(message) : undefined);
         registration = findPluginRegistration(name);
     }
     if (!registration) {

package/dist/pluginPageBundle.d.ts

@@ -0,0 +1,8 @@
+export declare const PLUGIN_PAGE_CHUNK_BYTES: number;
+export interface BuiltPluginPageBundle {
+    content: string;
+    hash: string;
+    size: number;
+    chunks: number;
+}
+export declare function buildPluginPageBundle(entry: string, pageEntry: string): BuiltPluginPageBundle;

package/dist/pluginPageBundle.js

@@ -0,0 +1,420 @@
+import { createHash } from 'node:crypto';
+import { readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+export const PLUGIN_PAGE_CHUNK_BYTES = 384 * 1024;
+const MAX_PAGE_SOURCE_BYTES = 16 * 1024 * 1024;
+const MAX_PAGE_BUNDLE_BYTES = 24 * 1024 * 1024;
+const MIME_TYPES = {
+    '.avif': 'image/avif',
+    '.gif': 'image/gif',
+    '.ico': 'image/x-icon',
+    '.jpeg': 'image/jpeg',
+    '.jpg': 'image/jpeg',
+    '.mp3': 'audio/mpeg',
+    '.mp4': 'video/mp4',
+    '.ogg': 'audio/ogg',
+    '.otf': 'font/otf',
+    '.png': 'image/png',
+    '.svg': 'image/svg+xml',
+    '.ttf': 'font/ttf',
+    '.wav': 'audio/wav',
+    '.webm': 'video/webm',
+    '.webp': 'image/webp',
+    '.woff': 'font/woff',
+    '.woff2': 'font/woff2',
+};
+const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
+  let context = null;
+  let port = null;
+  let requestSequence = 0;
+  const pending = new Map();
+  let resolveReady;
+  const ready = new Promise(resolve => { resolveReady = resolve; });
+
+  const requestHost = async (type, payload = {}) => {
+    await ready;
+    const requestId = String(++requestSequence);
+    return new Promise((resolve, reject) => {
+      pending.set(requestId, { resolve, reject });
+      port.postMessage({ type, requestId, ...payload });
+    });
+  };
+
+  const invoke = async (command, input = {}) => {
+    if (typeof command !== 'string' || !/^[a-z][a-z0-9-]*$/.test(command)) {
+      throw new Error('Invalid plugin command');
+    }
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+      throw new Error('Plugin command input must be an object');
+    }
+    return requestHost('invoke', { command, input });
+  };
+
+  const start = async (command, input = {}) => {
+    if (typeof command !== 'string' || !/^[a-z][a-z0-9-]*$/.test(command)) {
+      throw new Error('Invalid plugin command');
+    }
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+      throw new Error('Plugin command input must be an object');
+    }
+    return requestHost('invoke-start', { command, input });
+  };
+
+  const operation = async operationId => {
+    if (typeof operationId !== 'string' || !/^[0-9a-f-]{36}$/i.test(operationId)) {
+      throw new Error('Invalid plugin operation id');
+    }
+    return requestHost('invoke-operation', { operationId });
+  };
+
+  const runningOperations = async () => requestHost('invoke-operations');
+
+  const selectDirectory = async () => {
+    const path = await requestHost('select-directory');
+    if (path !== null && typeof path !== 'string') {
+      throw new Error('Directory selection returned an invalid path');
+    }
+    return path;
+  };
+
+  const copyText = async text => {
+    if (typeof text !== 'string' || text.length > 1000000) {
+      throw new Error('Clipboard text must be a string no longer than 1000000 characters');
+    }
+    await requestHost('clipboard-write', { text });
+  };
+
+  const toast = async (message, options = {}) => {
+    if (typeof message !== 'string' || !message.trim() || message.length > 4000) {
+      throw new Error('Toast message must be a non-empty string no longer than 4000 characters');
+    }
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new Error('Toast options must be an object');
+    }
+    const type = options.type ?? 'info';
+    const duration = options.duration ?? 3000;
+    if (!['success', 'error', 'info'].includes(type)) throw new Error('Invalid toast type');
+    if (!Number.isInteger(duration) || duration < 1000 || duration > 30000) {
+      throw new Error('Toast duration must be between 1000 and 30000 milliseconds');
+    }
+    await ready;
+    port.postMessage({ type: 'toast', message: message.trim(), toastType: type, duration });
+  };
+
+  const agentPanelLayout = options => {
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new Error('Agent panel options must be an object');
+    }
+    const layout = options.layout;
+    if (layout !== undefined && layout !== 'drawer' && layout !== 'workspace') {
+      throw new Error('Agent panel layout must be drawer or workspace');
+    }
+    return layout;
+  };
+
+  const setAgentPanelVisible = async (visible, options = {}) => {
+    if (typeof visible !== 'boolean') throw new Error('Agent panel visibility must be a boolean');
+    const layout = agentPanelLayout(options);
+    await requestHost('agent-panel', { visible, ...(layout ? { layout } : {}) });
+  };
+
+  const runAgentTask = async (prompt, options = {}) => {
+    if (typeof prompt !== 'string' || !prompt.trim() || prompt.length > 16000) {
+      throw new Error('Agent task prompt must be a non-empty string no longer than 16000 characters');
+    }
+    if (!options || typeof options !== 'object' || Array.isArray(options)) {
+      throw new Error('Agent task options must be an object');
+    }
+    const cwd = options.cwd;
+    const layout = agentPanelLayout(options);
+    if (
+      cwd !== undefined &&
+      (typeof cwd !== 'string' ||
+        !cwd.trim() ||
+        cwd.length > 4096 ||
+        !/^(?:\/|[a-zA-Z]:[\\/])/.test(cwd.trim()))
+    ) {
+      throw new Error('Agent task cwd must be an absolute path no longer than 4096 characters');
+    }
+    await requestHost('agent-task', {
+      prompt: prompt.trim(),
+      ...(cwd !== undefined ? { cwd: cwd.trim() } : {}),
+      ...(layout ? { layout } : {}),
+    });
+  };
+
+  const setQueryParam = async (name, value) => {
+    if (typeof name !== 'string' || !/^[a-z][a-z0-9-]{0,63}$/.test(name)) {
+      throw new Error('Query parameter name is invalid');
+    }
+    if (value !== null && (typeof value !== 'string' || value.length > 512)) {
+      throw new Error('Query parameter value must be null or a string no longer than 512 characters');
+    }
+    const query = await requestHost('query-param', { name, value });
+    applyContext({ query });
+    return query;
+  };
+
+  const api = { copyText, invoke, operation, ready: () => ready, runAgentTask, runningOperations, selectDirectory, setAgentPanelVisible, setQueryParam, start, toast };
+  const ui = globalThis.__mearlToolboxUi;
+  if (ui !== undefined) {
+    if (!ui || typeof ui !== 'object' || ui.runtime !== 'preact') {
+      throw new Error('Invalid Mearl toolbox UI runtime');
+    }
+    Object.defineProperty(api, 'ui', { enumerable: true, value: ui });
+    delete globalThis.__mearlToolboxUi;
+  }
+  Object.defineProperty(api, 'context', { enumerable: true, get: () => context });
+  Object.defineProperty(window, 'mearl', { configurable: false, value: Object.freeze(api) });
+
+  const applyContext = nextContext => {
+    const theme =
+      nextContext?.theme === 'dark' ||
+      (nextContext?.theme !== 'light' && context?.theme === 'dark')
+        ? 'dark'
+        : 'light';
+    const fontSize = String(nextContext?.fontSize || context?.fontSize || '');
+    document.documentElement.dataset.mearlTheme = theme;
+    document.documentElement.style.colorScheme = theme;
+    if (/^\d+(?:\.\d+)?px$/.test(fontSize)) document.documentElement.style.fontSize = fontSize;
+    context = Object.freeze({ ...(context || {}), ...(nextContext || {}), theme });
+    return context;
+  };
+
+  const connect = event => {
+    const message = event.data;
+    const nextPort = event.ports && event.ports[0];
+    if (
+      (event.source && event.source !== window.parent) ||
+      message?.type !== 'mearl-plugin-connect' ||
+      !nextPort
+    ) return;
+    window.removeEventListener('message', connect);
+    applyContext(message.context);
+    port = nextPort;
+    port.onmessage = responseEvent => {
+      const response = responseEvent.data;
+      if (response?.type === 'context') {
+        applyContext(response.context);
+        return;
+      }
+      if (response?.type !== 'result' || typeof response.requestId !== 'string') return;
+      const request = pending.get(response.requestId);
+      if (!request) return;
+      pending.delete(response.requestId);
+      if (response.ok) request.resolve(response.result);
+      else request.reject(new Error(response.error || 'Plugin command failed'));
+    };
+    port.start();
+    resolveReady(context);
+    port.postMessage({ type: 'ready' });
+  };
+  window.addEventListener('message', connect);
+  window.parent.postMessage({ type: 'mearl-plugin-ready' }, '*');
+})();`;
+const PAGE_SECURITY_META = "<meta http-equiv=\"Content-Security-Policy\" content=\"default-src 'none'; script-src 'unsafe-inline'; style-src 'unsafe-inline'; img-src data: blob:; font-src data:; media-src data: blob:; connect-src 'none'; frame-src 'none'; object-src 'none'; base-uri 'none'; form-action 'none'\">";
+const PAGE_THEME_STYLE = `<style data-mearl-theme>
+:root {
+  color-scheme: light dark;
+  --mearl-toolbar: #f3f3f3;
+  --mearl-toolbar-border: #d0d0d0;
+  --mearl-text-primary: #2c2c2c;
+  --mearl-text-secondary: #6e6e6e;
+  --mearl-bg-primary: #ffffff;
+  --mearl-bg-secondary: #f8f9fa;
+  --mearl-bg-list: #fafbfc;
+  --mearl-bg-hover: #f0f1f3;
+  --mearl-bg-selected: #f5f5f5;
+  --mearl-border: #e1e4e8;
+  --mearl-accent: #2a57c9;
+  --mearl-accent-hover: #1d4ed8;
+  --mearl-action-primary: oklch(54.6% 0.245 262.881);
+  --mearl-action-primary-hover: oklch(48.8% 0.243 264.376);
+  --mearl-action-primary-text: #ffffff;
+  --mearl-danger: #dc2626;
+  --mearl-danger-bg: rgb(220 38 38 / 8%);
+  --mearl-success: #16a34a;
+  --mearl-scrollbar-track: #f6f8fa;
+  --mearl-scrollbar-thumb: #d1d5db;
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+  background: var(--mearl-bg-primary);
+}
+:root[data-mearl-theme="dark"] {
+  color-scheme: dark;
+  --mearl-toolbar: #1f1f1f;
+  --mearl-toolbar-border: #343434;
+  --mearl-text-primary: #e4e4e7;
+  --mearl-text-secondary: #a1a1aa;
+  --mearl-bg-primary: #0f0f0f;
+  --mearl-bg-secondary: #1a1a1a;
+  --mearl-bg-list: #0f0f0f;
+  --mearl-bg-hover: #262626;
+  --mearl-bg-selected: #1f1f1f;
+  --mearl-border: #30363d;
+  --mearl-accent: #58a6ff;
+  --mearl-accent-hover: #79b8ff;
+  --mearl-danger: #f87171;
+  --mearl-danger-bg: rgb(248 113 113 / 10%);
+  --mearl-success: #4ade80;
+  --mearl-scrollbar-track: #1a1a1a;
+  --mearl-scrollbar-thumb: #3b3b3b;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-mearl-theme="light"]) {
+    color-scheme: dark;
+    --mearl-toolbar: #1f1f1f;
+    --mearl-toolbar-border: #343434;
+    --mearl-text-primary: #e4e4e7;
+    --mearl-text-secondary: #a1a1aa;
+    --mearl-bg-primary: #0f0f0f;
+    --mearl-bg-secondary: #1a1a1a;
+    --mearl-bg-list: #0f0f0f;
+    --mearl-bg-hover: #262626;
+    --mearl-bg-selected: #1f1f1f;
+    --mearl-border: #30363d;
+    --mearl-accent: #58a6ff;
+    --mearl-accent-hover: #79b8ff;
+    --mearl-danger: #f87171;
+    --mearl-danger-bg: rgb(248 113 113 / 10%);
+    --mearl-success: #4ade80;
+    --mearl-scrollbar-track: #1a1a1a;
+    --mearl-scrollbar-thumb: #3b3b3b;
+  }
+}
+body {
+  margin: 0;
+  background: var(--mearl-bg-primary);
+  color: var(--mearl-text-primary);
+}
+button, input, select, textarea { font: inherit; }
+</style>`;
+function pluginRoot(entry) {
+    const entryDirectory = dirname(entry);
+    return basename(entryDirectory) === 'scripts' ? dirname(entryDirectory) : entryDirectory;
+}
+function attributeValue(tag, name) {
+    const match = tag.match(new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i'));
+    return match?.[1] ?? match?.[2] ?? match?.[3];
+}
+function removeAttribute(tag, name) {
+    return tag.replace(new RegExp(`\\s+${name}\\s*=\\s*(?:"[^"]*"|'[^']*'|[^\\s>]+)`, 'i'), '');
+}
+function isEmbeddedReference(reference) {
+    return /^(?:data:|blob:|#)/i.test(reference.trim());
+}
+function isRemoteReference(reference) {
+    return /^(?:[a-z][a-z0-9+.-]*:|\/\/)/i.test(reference.trim());
+}
+function contentType(path) {
+    return MIME_TYPES[extname(path).toLowerCase()] ?? 'application/octet-stream';
+}
+function escapeStyleText(value) {
+    return value.replace(/<\/style/gi, '\\3C /style');
+}
+function escapeScriptText(value) {
+    return value.replace(/<\/script/gi, '<\\/script');
+}
+export function buildPluginPageBundle(entry, pageEntry) {
+    const root = realpathSync(pluginRoot(entry));
+    let sourceBytes = 0;
+    const countedFiles = new Set();
+    const resolveLocalFile = (reference, fromFile) => {
+        const cleanReference = reference.trim().split(/[?#]/, 1)[0];
+        if (!cleanReference || isEmbeddedReference(cleanReference))
+            return '';
+        if (isRemoteReference(cleanReference) || isAbsolute(cleanReference)) {
+            throw new Error(`toolbox.page 不允许远程或绝对资源: ${reference}`);
+        }
+        const resolved = realpathSync(resolve(dirname(fromFile), cleanReference));
+        const relativePath = relative(root, resolved);
+        if (relativePath === '..' || relativePath.startsWith(`..${sep}`) || isAbsolute(relativePath)) {
+            throw new Error(`toolbox.page 资源超出插件目录: ${reference}`);
+        }
+        return resolved;
+    };
+    const readAsset = (path) => {
+        const content = readFileSync(path);
+        if (!countedFiles.has(path)) {
+            countedFiles.add(path);
+            sourceBytes += content.byteLength;
+            if (sourceBytes > MAX_PAGE_SOURCE_BYTES) {
+                throw new Error('toolbox.page 源文件总大小不能超过 16 MiB');
+            }
+        }
+        return content;
+    };
+    const dataUrl = (reference, fromFile) => {
+        if (isEmbeddedReference(reference))
+            return reference;
+        const path = resolveLocalFile(reference, fromFile);
+        return `data:${contentType(path)};base64,${readAsset(path).toString('base64')}`;
+    };
+    const inlineCss = (css, cssPath) => css.replace(/url\(\s*(['"]?)([^'"()]+)\1\s*\)/gi, (_match, _quote, reference) => {
+        const value = reference.trim();
+        if (isEmbeddedReference(value))
+            return `url("${value}")`;
+        return `url("${dataUrl(value, cssPath)}")`;
+    });
+    const absoluteEntry = resolveLocalFile(pageEntry, join(root, '__toolbox_entry__'));
+    if (extname(absoluteEntry).toLowerCase() !== '.html') {
+        throw new Error('toolbox.page.entry 必须指向 HTML 文件');
+    }
+    let html = readAsset(absoluteEntry)
+        .toString('utf8')
+        .replace(/^\uFEFF/, '');
+    if (!/<html\b|<!doctype\b/i.test(html)) {
+        throw new Error('toolbox.page.entry 必须是完整 HTML 文档');
+    }
+    if (/<base\b/i.test(html))
+        throw new Error('toolbox.page 不允许声明 base 标签');
+    if (/<meta\b[^>]*http-equiv\s*=\s*["']?content-security-policy/i.test(html)) {
+        throw new Error('toolbox.page 的安全策略由 Mearl 管理，请移除 CSP meta 标签');
+    }
+    html = html.replace(/<link\b[^>]*>/gi, tag => {
+        const rel = attributeValue(tag, 'rel')?.toLowerCase().split(/\s+/) ?? [];
+        const href = attributeValue(tag, 'href');
+        if (rel.includes('stylesheet')) {
+            if (!href)
+                throw new Error('toolbox.page stylesheet 缺少 href');
+            const cssPath = resolveLocalFile(href, absoluteEntry);
+            const css = inlineCss(readAsset(cssPath).toString('utf8'), cssPath);
+            return `<style data-mearl-source="${href.replaceAll('"', '&quot;')}">${escapeStyleText(css)}</style>`;
+        }
+        if (href && rel.some(value => ['icon', 'apple-touch-icon'].includes(value))) {
+            return tag.replace(href, dataUrl(href, absoluteEntry));
+        }
+        if (href && isRemoteReference(href)) {
+            throw new Error(`toolbox.page 不允许远程 link 资源: ${href}`);
+        }
+        return tag;
+    });
+    html = html.replace(/<script\b[^>]*>[\s\S]*?<\/script\s*>/gi, tag => {
+        const src = attributeValue(tag, 'src');
+        if (!src)
+            return tag;
+        const scriptPath = resolveLocalFile(src, absoluteEntry);
+        const script = readAsset(scriptPath).toString('utf8');
+        if (attributeValue(tag, 'type')?.toLowerCase() === 'module' &&
+            /(?:^|[;\n]\s*)(?:import\s|export\s)|\bimport\s*\(/m.test(script)) {
+            throw new Error('toolbox.page 的模块脚本必须先打包为无 import 的单文件');
+        }
+        const openingTag = removeAttribute(tag.slice(0, tag.indexOf('>') + 1), 'src');
+        return `${openingTag}${escapeScriptText(script)}</script>`;
+    });
+    html = html.replace(/(<(?:img|source|video|audio|track|input)\b[^>]*?\s(?:src|poster)\s*=\s*)(["'])([^"']+)\2/gi, (_match, prefix, quote, reference) => `${prefix}${quote}${dataUrl(reference, absoluteEntry)}${quote}`);
+    const injection = `<meta name="color-scheme" content="light dark">${PAGE_SECURITY_META}${PAGE_THEME_STYLE}<script data-mearl-bridge>${escapeScriptText(PAGE_BRIDGE_SCRIPT)}</script>`;
+    html = /<head\b[^>]*>/i.test(html)
+        ? html.replace(/<head\b[^>]*>/i, tag => `${tag}${injection}`)
+        : html.replace(/<html\b[^>]*>/i, tag => `${tag}<head>${injection}</head>`);
+    const content = html;
+    const buffer = Buffer.from(content, 'utf8');
+    if (buffer.byteLength > MAX_PAGE_BUNDLE_BYTES) {
+        throw new Error('toolbox.page 打包后不能超过 24 MiB');
+    }
+    return {
+        content,
+        hash: createHash('sha256').update(buffer).digest('hex'),
+        size: buffer.byteLength,
+        chunks: Math.ceil(buffer.byteLength / PLUGIN_PAGE_CHUNK_BYTES),
+    };
+}

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/package.json

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