@mearl/client 2.20.3 → 2.20.5

package/dist/generated-app-profile-runtime-types.d.ts

@@ -0,0 +1,209 @@
+import type { AppProfileBinding, AppProfilePolicies, AppProfileSetting } from './generated-app-profile-definition.js';
+import type { BrowserDevicePresetName } from './generated-browser-action-protocol.js';
+type DeviceCutout = 'none' | 'dynamic-island' | 'notch' | 'side-camera';
+/** 桥调用风格，与页面适配器使用的端内调用约定一一对应。 */
+export type AppBridgeStyle = 'windvane' | 'fliggy' | 'alipay' | 'callback' | 'btrip' | 'invoke' | 'callHandler' | 'amap' | 'didi' | 'easybikeNative' | 'mega' | 'wechat' | 'wechatMiniProgram';
+export interface AppBridgeSpec {
+    global: string;
+    style: AppBridgeStyle;
+    /** 页面脚本重设全局对象时仍保留桥叶子，同时接纳页面对象上的其他 API。 */
+    persistent?: boolean;
+}
+export type AppBridgeBehavior = 'navigate' | 'closeAll' | 'closeBackData' | 'postMessage' | 'notifySubscribe' | 'notifyUnsubscribe' | 'notifyPost' | 'sharedFileRead' | 'sharedFileWrite' | 'sharedDataGet' | 'sharedDataSet' | 'legacyBroadcastCreate' | 'legacyBroadcastPost' | 'legacyBroadcastClose' | 'memoryGet' | 'memorySet' | 'memoryDelete' | 'availabilityMap' | 'userInfo' | 'authCode' | 'networkInfo' | 'geolocation' | 'permission' | 'imagePicker' | 'prefetch' | 'fptTrack' | 'mtopStream' | 'previewFile' | 'toast' | 'unsupportedNativeInput' | 'payment' | 'userTrack' | 'calendar' | 'networkQualityMonitor' | 'beaconRequest' | 'voiceRecognition';
+/** 桥方法名到标准化动作的映射。WindVane 风格使用 `Class.method`，其余使用 api 名。 */
+export interface BridgeActionMap {
+    open: string[];
+    close: string[];
+    title: string[];
+    navigationBar?: string[];
+    statusBar?: string[];
+    systemInfo: string[];
+    mtop: string[];
+    kvGet?: string[];
+    kvSet?: string[];
+    kvDelete?: string[];
+    pageContext?: string[];
+    responses?: Record<string, unknown>;
+    behaviors?: Record<string, AppBridgeBehavior>;
+    noop: string[];
+    silent?: string[];
+}
+export interface AppSchemeRule {
+    match: string;
+    /** 规则仅在目标或当前页面 host 命中这些根域时生效。 */
+    hostSuffixes?: string[];
+    param?: string;
+    /** 将参数解出的 H5 地址保留 path/query/hash，并投影到当前页面 origin。 */
+    useCurrentOrigin?: boolean;
+    targetPath?: string;
+    targetHostPrefix?: string;
+    targetParams?: Record<string, string>;
+}
+export interface AppMiniProgramPaymentRoute {
+    /** 小程序支付中转页 pathname。 */
+    pathname: string;
+    /** 限制业务根域，避免同名小程序路由被其他项目接管。 */
+    hostSuffixes?: string[];
+    /** JSON 字符串形式的支付桥入参。 */
+    paymentParamsParam: string;
+    /** 按顺序读取的支付成功回跳参数，前者为空时使用后者。 */
+    successUrlParams: string[];
+    /** 按顺序读取的支付失败或取消回跳参数。 */
+    failureUrlParams: string[];
+    /** 支付成功结果写入回跳 URL 的参数名。 */
+    successResultParam?: string;
+    /** 从支付页路由透传到回跳 URL 的默认参数。 */
+    forwardParams?: string[];
+    /** 将回跳 H5 的 path/query/hash 投影到当前页面 origin。 */
+    useCurrentOrigin?: boolean;
+}
+export type AppMiniProgramMessageAction = 'stageBackData' | 'closeAll';
+export interface AppMiniProgramMessageRule {
+    /** H5 通过 wx.miniProgram.postMessage 发送的 type。 */
+    type: string;
+    /** 容器只提供有限的页面栈动作，业务消息名由档案映射。 */
+    action: AppMiniProgramMessageAction;
+    /** 限制发送消息的 H5 根域。 */
+    hostSuffixes?: string[];
+}
+export type AppMiniProgramNativeAction = 'navigateMiniProgram' | 'subscribeMessage';
+export interface AppMiniProgramNativeRoute {
+    /** 承接微信原生能力的小程序页面 pathname。 */
+    pathname: string;
+    /** 该页面允许模拟的固定原生动作，动作名读取 URL 的 action 参数。 */
+    actions: AppMiniProgramNativeAction[];
+    /** 限制业务根域，避免其他小程序的同名页面被接管。 */
+    hostSuffixes?: string[];
+}
+/** 微信小程序容器相关规则统一收口，避免为每种业务页增加顶层配置。 */
+export interface AppMiniProgramConfig {
+    paymentRoutes?: AppMiniProgramPaymentRoute[];
+    nativeRoutes?: AppMiniProgramNativeRoute[];
+    messageRules?: AppMiniProgramMessageRule[];
+}
+export interface AppImagePickerConfig {
+    schemes: string[];
+    api: string;
+    version: string;
+    fcId: string;
+    fcGroup: string;
+    uploadUrlFunction: string;
+    prefix: string;
+    region: string;
+}
+export interface AppOverlayConfig {
+    enabledParam: string;
+    topRatioParam: string;
+    /** 弹层高度占屏比例参数，与 topRatioParam 二选一即可。 */
+    heightRatioParam?: string;
+    radiusParam: string;
+    maskAlphaParam: string;
+    tapCloseParam: string;
+    /** 蒙层关闭时优先触发当前 WebView 内的关闭控件，以复用页面定义的回传逻辑。 */
+    tapCloseSelectors?: string[];
+    /** 蒙层点击只退出当前 WebView，不调用页面关闭控件或打开回调。 */
+    silentTapClose?: boolean;
+    defaultTopRatio: number;
+    defaultRadius: number;
+    defaultMaskAlpha: number;
+    defaultTapClose: boolean;
+}
+export interface AppNativeBackConfig {
+    /** 原生返回键触发的 document 事件。 */
+    event?: string;
+    /** 返回 true 时由页面接管返回，再分发 event。 */
+    controlFunction?: string;
+    /** 原生返回键直接调用的 window 函数。 */
+    handler?: string;
+}
+export interface AppLayerUrlProxyConfig {
+    sourceHostPrefix: string;
+    pathPrefix: string;
+    targetHostSuffixes: string[];
+    defaultTargetHost?: string;
+}
+export interface AppTitleBarConfig {
+    navigationBarHeight: number;
+    backgroundColor: string;
+    textColor: string;
+    hiddenPathnames?: string[];
+    statusBarBackgroundColors?: Record<string, string>;
+    hostStyles?: AppTitleBarHostStyle[];
+}
+export interface AppTitleBarHostStyle {
+    /** 同时匹配该 host 与其全部子域，配置值不含前导点。 */
+    hostSuffix: string;
+    titleBarBackgroundColor?: string;
+    statusBarBackgroundColor?: string;
+}
+export interface AppSafeAreaInsets {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/** App 运行时使用的设备外观快照，避免通过机型字符串反推物理特征。 */
+export interface AppDeviceAppearance {
+    preset: BrowserDevicePresetName;
+    orientation: 'portrait' | 'landscape';
+    cutout: DeviceCutout;
+}
+export interface AppRootContainerCookie {
+    name: string;
+    value: string;
+    domain?: string;
+    path?: string;
+}
+export interface AppRootContainerConfig {
+    enabled: boolean;
+    initialCookies?: AppRootContainerCookie[];
+    /** 横屏设备外壳中保留根页面，并将后续业务 WebView 呈现在右半屏。 */
+    splitScreen?: boolean;
+}
+/** 注入页内的运行时配置，可经 Server-Timing 或 CDP new-document 脚本传输。 */
+export interface InjectedAppProfileConfig {
+    binding?: AppProfileBinding;
+    policies?: AppProfilePolicies;
+    settings?: AppProfileSetting[];
+    profile: string;
+    label: string;
+    globals: Record<string, string>;
+    bridges: AppBridgeSpec[];
+    activeEvents: string[];
+    maxTouchPoints: number;
+    statusBarHeight: number;
+    safeAreaInsets?: AppSafeAreaInsets;
+    /** 可选，以兼容未携带设备外观快照的持久化配置。 */
+    deviceAppearance?: AppDeviceAppearance;
+    userAgent: string;
+    navigatorPlatform: string;
+    platform: string;
+    systemVersion: string;
+    clientType: string;
+    language: string;
+    actions: BridgeActionMap;
+    schemes: AppSchemeRule[];
+    miniProgram?: AppMiniProgramConfig;
+    imagePicker?: AppImagePickerConfig;
+    /** 原生定位返回地址时使用的逆地理编码服务，复用容器的 MTop 传输。 */
+    geolocation?: {
+        reverseGeocodeApi: string;
+        version: string;
+    };
+    overlay?: AppOverlayConfig;
+    /** URL 参数为真时以新 WebView 替换当前业务层。 */
+    popBeforeOpenParam?: string;
+    /** 跨 WebView 消息抵达 opener 时分发的 document 事件。 */
+    messageEvent?: string;
+    nativeBack?: AppNativeBackConfig;
+    layerUrlProxy?: AppLayerUrlProxyConfig;
+    urlSyncHostSuffixes?: string[];
+    animationMs?: number;
+    forceH5Mtop?: boolean;
+    titleBar?: AppTitleBarConfig;
+    rootContainer?: AppRootContainerConfig;
+    simulateSystemBars?: boolean;
+    /** 物理状态栏与底部操作区由独立设备运行时渲染；本运行时只保留客户端导航栏。 */
+    externalDeviceChrome?: boolean;
+}
+export {};

package/dist/generated-app-profile-runtime-types.js

@@ -0,0 +1 @@
+export {};

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

@@ -512,17 +512,22 @@ export type TabGroupParams = {
  * 因此新增档案时只需改两处（名单 + 档案数据），且漏改会在类型检查时暴露。
  */
 export declare const APP_PROFILE_NAMES: readonly ["fliggy", "taobao", "wechat", "tmall", "alipay", "koubei", "taobao-tj", "taobao-live", "xianyu", "etao", "eleme", "damai", "btrip", "amap", "qianwen", "lingyou", "didi", "easybike"];
-export type AppProfileName = (typeof APP_PROFILE_NAMES)[number];
+export type BuiltinAppProfileName = (typeof APP_PROFILE_NAMES)[number];
+export type AppProfileName = BuiltinAppProfileName | `${string}/${string}`;
 export interface SetAppProfileParams {
     tabId: number;
     /** false 时清除该 tab 的容器模拟并刷新 */
     enabled: boolean;
     /** 容器档案名（enabled=true 时必填） */
     profile?: AppProfileName;
+    /** Immediately use the latest installed definition while preserving explicit options. */
+    refreshDefinition?: boolean;
+    /** 固定当前档案定义；默认在下次文档导航时自动采用可用更新。 */
+    lockDefinition?: boolean;
     os?: 'ios' | 'android';
     appVersion?: string;
-    /** 支付宝容器语言；其他容器忽略。 */
-    language?: 'zh-CN' | 'zh-TW' | 'zh-HK' | 'en-US';
+    /** 端定义支持的语言选项。 */
+    language?: string;
     deviceModel?: string;
     /** 按方法覆盖档案内置桥配置，仅支持受控行为、固定 JSON 回包和成功空实现 */
     bridgeConfig?: AppBridgeConfig;

package/dist/nativeHost.d.ts

@@ -0,0 +1,21 @@
+export type NativeHostIntegrationMode = 'skills' | 'mcp';
+export declare const MEARL_NATIVE_HOST_NAMES: Record<NativeHostIntegrationMode, string>;
+export interface NativeHostDirectoryOptions {
+    env?: NodeJS.ProcessEnv;
+    homedir?: () => string;
+    platform?: NodeJS.Platform;
+}
+export declare function resolveNativeHostDirectory(options?: NativeHostDirectoryOptions): string;
+export interface NativeHostDiagnostic {
+    label: string;
+    details: string[];
+}
+export interface NativeHostLauncherMetadata {
+    version: 1;
+    nodePaths: string[];
+    hostPath: string;
+}
+/** Inspect registrations even when Chrome cannot start the native host. Never execute launchers. */
+export declare function inspectNativeHostInstallation(options?: NativeHostDirectoryOptions & {
+    hostDir?: string;
+}): NativeHostDiagnostic[];

package/dist/nativeHost.js

@@ -0,0 +1,107 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+export const MEARL_NATIVE_HOST_NAMES = {
+    skills: 'com.alibaba.mearl.skills',
+    mcp: 'com.alibaba.mearl.mcp',
+};
+export function resolveNativeHostDirectory(options = {}) {
+    const env = options.env ?? process.env;
+    const home = (options.homedir ?? os.homedir)();
+    switch (options.platform ?? process.platform) {
+        case 'darwin':
+            return path.join(home, 'Library/Application Support/Google/Chrome/NativeMessagingHosts');
+        case 'linux':
+            return path.join(home, '.config/google-chrome/NativeMessagingHosts');
+        case 'win32':
+            return path.join(env.PROGRAMDATA || 'C:\\ProgramData', 'Google\\Chrome\\NativeMessagingHosts');
+        default:
+            throw new Error(`Unsupported platform: ${String(options.platform ?? process.platform)}`);
+    }
+}
+function readLauncherMetadata(content) {
+    const metadata = content.match(/^(?:#|rem) mearl-native-host-launcher: (.+)\r?$/m);
+    if (metadata) {
+        const parsed = JSON.parse(metadata[1]);
+        if (parsed.version === 1 &&
+            Array.isArray(parsed.nodePaths) &&
+            parsed.nodePaths.length > 0 &&
+            parsed.nodePaths.every(value => typeof value === 'string' && path.isAbsolute(value)) &&
+            typeof parsed.hostPath === 'string' &&
+            path.isAbsolute(parsed.hostPath)) {
+            return { version: 1, nodePaths: parsed.nodePaths, hostPath: parsed.hostPath };
+        }
+        throw new Error('Invalid native host launcher metadata');
+    }
+    // Legacy launchers stored these assignments as JSON strings.
+    const node = content.match(/^NODE_BIN=(".*")\r?$/m);
+    const host = content.match(/^HOST_SCRIPT=(".*")\r?$/m);
+    if (!node || !host)
+        return null;
+    const nodePath = JSON.parse(node[1]);
+    const hostPath = JSON.parse(host[1]);
+    if (typeof nodePath !== 'string' ||
+        !path.isAbsolute(nodePath) ||
+        typeof hostPath !== 'string' ||
+        !path.isAbsolute(hostPath)) {
+        throw new Error('Invalid native host launcher paths');
+    }
+    return { version: 1, nodePaths: [nodePath], hostPath };
+}
+/** Inspect registrations even when Chrome cannot start the native host. Never execute launchers. */
+export function inspectNativeHostInstallation(options = {}) {
+    const platform = options.platform ?? process.platform;
+    if (!['darwin', 'linux', 'win32'].includes(platform))
+        return [];
+    const hostDir = options.hostDir ?? resolveNativeHostDirectory(options);
+    const diagnostics = [];
+    const isUsable = (filePath, executable) => {
+        try {
+            fs.accessSync(filePath, executable && platform !== 'win32' ? fs.constants.X_OK : fs.constants.R_OK);
+            return fs.statSync(filePath).isFile();
+        }
+        catch {
+            return false;
+        }
+    };
+    for (const hostName of Object.values(MEARL_NATIVE_HOST_NAMES)) {
+        const manifestPath = path.join(hostDir, `${hostName}.json`);
+        const details = [];
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+            if (typeof manifest?.path !== 'string' || !path.isAbsolute(manifest.path)) {
+                details.push(`Invalid launcher path in ${manifestPath}`);
+            }
+            else if (!isUsable(manifest.path, true)) {
+                details.push(`Launcher is missing or not executable: ${manifest.path}`);
+            }
+            else {
+                const metadata = readLauncherMetadata(fs.readFileSync(manifest.path, 'utf-8'));
+                if (metadata) {
+                    if (!metadata.nodePaths.some(candidate => isUsable(candidate, true))) {
+                        details.push(`No executable Node.js found. Launcher candidates: ${metadata.nodePaths.join(', ')}`);
+                    }
+                    if (!isUsable(metadata.hostPath, false)) {
+                        details.push(`Native host runtime script is missing or unreadable: ${metadata.hostPath}`);
+                    }
+                }
+            }
+        }
+        catch (error) {
+            if (error.code === 'ENOENT' && !fs.existsSync(manifestPath))
+                continue;
+            details.push(`Cannot inspect ${manifestPath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        if (details.length) {
+            diagnostics.push({
+                label: `Native Messaging registration needs repair: ${hostName}`,
+                details: [
+                    ...details,
+                    `Registration: ${manifestPath}`,
+                    'Run `mearl-native-host init` with a working Node.js, then reopen the extension. If the runtime package is missing, run `npx @mearl/setup update --local`.',
+                ],
+            });
+        }
+    }
+    return diagnostics;
+}

package/dist/plugin.d.ts

@@ -1,3 +1,5 @@
+import type { AppProfileContribution } from './generated-app-profile-definition.js';
+export type { AppProfileContribution, AppProfileDefinition, } from './generated-app-profile-definition.js';
 export { invokePageEvalWithArgs } from './pageEvalArguments.js';
 import { type OfficialPluginInstaller } from './officialPluginInstaller.js';
 import { type PluginToolboxContribution, type PluginRegistration } from './pluginRegistry.js';
@@ -38,6 +40,8 @@ export declare function loadPlugin(entry: string, context: Pick<PluginApp, 'invo
     name: string | undefined;
     description: string | undefined;
     toolbox: PluginToolboxContribution | undefined;
+    appProfiles: AppProfileContribution | undefined;
+    profileSources: Record<string, string> | undefined;
     version: string | undefined;
     commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;
@@ -48,6 +52,8 @@ export declare function loadRegisteredPlugin(name: string, context: PluginExecut
     name: string | undefined;
     description: string | undefined;
     toolbox: PluginToolboxContribution | undefined;
+    appProfiles: AppProfileContribution | undefined;
+    profileSources: Record<string, string> | undefined;
     version: string | undefined;
     commandHelp(namespace: string): string;
     help(namespace: string, name?: string): string;

package/dist/plugin.js

@@ -1,3 +1,4 @@
+import { loadPluginAppProfiles } from './pluginAppProfiles.js';
 export { invokePageEvalWithArgs } from './pageEvalArguments.js';
 import { readFileSync } from 'node:fs';
 import { dirname, extname, resolve } from 'node:path';
@@ -107,6 +108,8 @@ export async function refreshRegisteredPlugin(name, includePage = false) {
         }
         registerPlugin(name, registration.entry, loaded.description, {
             toolbox: loaded.toolbox,
+            appProfiles: loaded.appProfiles,
+            profileSources: 'profileSources' in loaded ? loaded.profileSources : loaded.source?.profiles,
             ...(registration.managedBy ? { managedBy: registration.managedBy } : {}),
         });
         return findPluginRegistration(name);
@@ -134,6 +137,8 @@ export async function loadPlugin(entry, context, pluginName) {
     let name;
     let description;
     let toolbox;
+    let appProfiles;
+    let profileSources;
     const registerCommand = (signature, handler, description = '', examples = [], toolboxOnly = false) => {
         if (!registering)
             throw new Error('命令只能在入口注册阶段声明');
@@ -178,6 +183,7 @@ export async function loadPlugin(entry, context, pluginName) {
             name = descriptor.name;
             description = descriptor.description;
             toolbox = normalizePluginToolboxContribution(descriptor.toolbox);
+            ({ appProfiles, profileSources } = loadPluginAppProfiles(entry, descriptor.appProfiles));
             for (const command of descriptor.commands) {
                 const commandName = command.signature.trim().split(/\s+/)[0];
                 const register = command.toolboxOnly ? app.toolboxCommand : app.command;
@@ -195,11 +201,15 @@ export async function loadPlugin(entry, context, pluginName) {
                 throw new Error('入口的 description 导出必须为字符串');
             description = module.description;
             toolbox = normalizePluginToolboxContribution(module.toolbox);
-            if (typeof module.default !== 'function')
+            ({ appProfiles, profileSources } = loadPluginAppProfiles(entry, module.appProfiles));
+            if (module.default !== undefined && typeof module.default !== 'function')
+                throw new Error('入口必须默认导出 register(app) 函数');
+            if (typeof module.default === 'function')
+                await module.default(app);
+            else if (!appProfiles)
                 throw new Error('入口必须默认导出 register(app) 函数');
-            await module.default(app);
         }
-        if (commands.size === 0)
+        if (commands.size === 0 && !appProfiles)
             throw new Error('入口未注册任何命令');
         const toolboxCommands = toolbox?.page.commands ?? [];
         for (const [name, command] of commands) {
@@ -290,6 +300,8 @@ export async function loadPlugin(entry, context, pluginName) {
         name,
         description,
         toolbox,
+        appProfiles,
+        profileSources,
         version: readPluginVersion(entry),
         commandHelp(namespace) {
             return publicCommands()

package/dist/pluginAppProfiles.d.ts

@@ -0,0 +1,6 @@
+import { type AppProfileContribution } from './generated-app-profile-definition.js';
+/** Profile resources share the Skill root and metadata refresh rules of toolbox resources. */
+export declare function loadPluginAppProfiles(entry: string, value: unknown): {
+    appProfiles?: AppProfileContribution;
+    profileSources?: Record<string, string>;
+};

package/dist/pluginAppProfiles.js

@@ -0,0 +1,40 @@
+import { readFileSync, realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve } from 'node:path';
+import { validateAppProfileContribution, } from './generated-app-profile-definition.js';
+import { pluginFileVersion } from './pluginSource.js';
+/** Profile resources share the Skill root and metadata refresh rules of toolbox resources. */
+export function loadPluginAppProfiles(entry, value) {
+    if (value === undefined)
+        return {};
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('appProfiles must be an object');
+    const declaration = value;
+    if (!Array.isArray(declaration.profiles))
+        throw new Error('appProfiles.profiles must be an array');
+    const root = realpathSync(basename(dirname(entry)) === 'scripts' ? dirname(dirname(entry)) : dirname(entry));
+    const sources = {};
+    const profiles = declaration.profiles.map(profile => {
+        if (typeof profile !== 'string')
+            return profile;
+        if (isAbsolute(profile) || !profile.endsWith('.json'))
+            throw new Error('Profile resource must be a relative JSON path');
+        const reference = resolve(root, profile);
+        const file = realpathSync(reference);
+        const inside = relative(root, file);
+        if (inside.startsWith('..') || isAbsolute(inside))
+            throw new Error('Profile resource must stay inside the Skill directory');
+        const version = pluginFileVersion(file);
+        const content = readFileSync(file, 'utf8');
+        if (content.length > 65_536)
+            throw new Error('Profile resource exceeds 64 KiB');
+        const parsed = JSON.parse(content);
+        if (pluginFileVersion(reference) !== version)
+            throw new Error('Profile resource changed during registration');
+        sources[reference] = version;
+        return parsed;
+    });
+    return {
+        appProfiles: validateAppProfileContribution({ ...declaration, profiles }),
+        profileSources: sources,
+    };
+}

package/dist/pluginPageBundle.js

@@ -30,6 +30,7 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
   let requestSequence = 0;
   const pending = new Map();
   const pageEventListeners = new Map();
+  const contextListeners = new Set();
   let subscriptionSequence = 0;
   let resolveReady;
   const ready = new Promise(resolve => { resolveReady = resolve; });
@@ -397,7 +398,13 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     return query;
   };
 
-  const api = { invoke, subscribe, ready: () => ready, runAgentTask, setAgentGuides, setAgentPanelVisible, setQueryParam };
+  const onContextChange = listener => {
+    if (typeof listener !== 'function') throw new Error('Invalid context listener');
+    contextListeners.add(listener);
+    if (context) listener(context);
+    return () => contextListeners.delete(listener);
+  };
+  const api = { invoke, subscribe, onContextChange, ready: async () => { await ready; return context; }, runAgentTask, setAgentGuides, setAgentPanelVisible, setQueryParam };
   const ui = globalThis.__mearlToolboxUi;
   if (ui !== undefined) {
     if (!ui || typeof ui !== 'object' || ui.runtime !== 'preact') {
@@ -421,6 +428,10 @@ const PAGE_BRIDGE_SCRIPT = String.raw `(() => {
     document.documentElement.style.colorScheme = theme;
     if (/^\d+(?:\.\d+)?px$/.test(fontSize)) document.documentElement.style.fontSize = fontSize;
     context = Object.freeze({ ...(context || {}), ...(nextContext || {}), theme });
+    for (const listener of contextListeners) {
+      try { listener(context); }
+      catch (error) { console.error('Toolbox context listener failed', error); }
+    }
     return context;
   };
 

package/dist/pluginRegistry.d.ts

@@ -1,3 +1,4 @@
+import { type AppProfileContribution } from './generated-app-profile-definition.js';
 export declare class PluginError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
@@ -7,6 +8,9 @@ export interface PluginToolboxSandboxPage {
     runtime?: 'preact';
     entry: string;
     commands: string[];
+    lifecycle?: {
+        onNavigation: string;
+    };
 }
 export interface PluginToolboxLocale {
     title?: string;
@@ -37,9 +41,11 @@ export interface PluginRegistration {
     description?: string;
     managedBy?: string;
     toolbox?: PluginToolboxContribution;
+    appProfiles?: AppProfileContribution;
     pageBundle?: PluginPageBundleRegistration;
     source?: {
         entry: string;
+        profiles?: Record<string, string>;
         page?: Record<string, string>;
         pageRuntime?: string;
     };
@@ -48,6 +54,8 @@ export declare function pluginRegistrationNeedsRefresh(registration: PluginRegis
 export interface PluginRegistrationOptions {
     managedBy?: string;
     toolbox?: PluginToolboxContribution;
+    appProfiles?: AppProfileContribution;
+    profileSources?: Record<string, string>;
 }
 export declare function pluginDirectory(): string;
 export declare function assertPluginName(name: string): void;

package/dist/pluginRegistry.js

@@ -1,3 +1,4 @@
+import { validateAppProfileContribution, } from './generated-app-profile-definition.js';
 import { randomUUID } from 'node:crypto';
 import { closeSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, rmSync, statSync, writeFileSync, } from 'node:fs';
 import { homedir } from 'node:os';
@@ -25,6 +26,15 @@ export function pluginRegistrationNeedsRefresh(registration, includePage = false
         return true;
     if (pluginFileVersion(registration.entry) !== registration.source.entry)
         return true;
+    if (Object.entries(registration.source.profiles ?? {}).some(([path, version]) => {
+        try {
+            return pluginFileVersion(path) !== version;
+        }
+        catch {
+            return true;
+        }
+    }))
+        return true;
     if (!includePage || !registration.toolbox)
         return false;
     if (registration.source.pageRuntime !== PLUGIN_PAGE_RUNTIME_HASH)
@@ -199,6 +209,17 @@ export function normalizePluginToolboxContribution(value) {
         entry: pageEntry,
         commands,
     };
+    if (pageCandidate.lifecycle !== undefined) {
+        const lifecycle = pageCandidate.lifecycle;
+        if (!lifecycle ||
+            typeof lifecycle !== 'object' ||
+            Array.isArray(lifecycle) ||
+            typeof lifecycle.onNavigation !== 'string' ||
+            !commands.includes(lifecycle.onNavigation)) {
+            throw new Error('toolbox.page.lifecycle.onNavigation 必须是 page.commands 中的命令名称');
+        }
+        page.lifecycle = { onNavigation: lifecycle.onNavigation };
+    }
     let agent;
     if (candidate.agent !== undefined) {
         if (!candidate.agent || typeof candidate.agent !== 'object' || Array.isArray(candidate.agent)) {
@@ -290,11 +311,15 @@ export function registerPlugin(name, target, description, options = {}) {
         entry,
         source: {
             entry: entryVersion,
+            ...(options.profileSources ? { profiles: options.profileSources } : {}),
             ...(builtPage ? { page: builtPage.sources, pageRuntime: PLUGIN_PAGE_RUNTIME_HASH } : {}),
         },
         ...(summary ? { description: summary } : {}),
         ...(managedBy ? { managedBy } : {}),
         ...(toolbox ? { toolbox } : {}),
+        ...(options.appProfiles
+            ? { appProfiles: validateAppProfileContribution(options.appProfiles) }
+            : {}),
         ...(builtPage
             ? { pageBundle: { hash: builtPage.hash, size: builtPage.size, chunks: builtPage.chunks } }
             : {}),
@@ -348,12 +373,18 @@ export function findPluginRegistration(name) {
             : undefined;
         const toolbox = normalizePluginToolboxContribution(record.toolbox);
         const pageBundle = toolbox ? normalizePageBundle(record.pageBundle) : undefined;
+        const appProfiles = validateAppProfileContribution(record.appProfiles);
         const source = record.source;
         if (source !== undefined &&
             (!source ||
                 typeof source !== 'object' ||
                 Array.isArray(source) ||
                 typeof source.entry !== 'string' ||
+                (source.profiles !== undefined &&
+                    (!source.profiles ||
+                        typeof source.profiles !== 'object' ||
+                        Array.isArray(source.profiles) ||
+                        Object.entries(source.profiles).some(([path, version]) => !isAbsolute(path) || typeof version !== 'string'))) ||
                 (source.pageRuntime !== undefined &&
                     (typeof source.pageRuntime !== 'string' || !/^[a-f0-9]{64}$/.test(source.pageRuntime))) ||
                 (source.page !== undefined &&
@@ -369,6 +400,7 @@ export function findPluginRegistration(name) {
             ...(managedBy ? { managedBy } : {}),
             ...(toolbox ? { toolbox } : {}),
             ...(pageBundle ? { pageBundle } : {}),
+            ...(appProfiles ? { appProfiles } : {}),
             ...(source ? { source } : {}),
         };
     }

package/dist/pythonPlugin.d.ts

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