@chatbi-v/core 2.1.0 → 2.1.2

package/dist/index.d.ts

@@ -1,30 +1,1748 @@
+import React, { Component, ReactNode, ErrorInfo } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import dayjs from 'dayjs';
+
 /**
- * @file index.ts
- * @description Core 模块入口文件，导出所有公共 API、领域逻辑、组件和 Hooks
+ * HTTP 请求方法
+ */
+type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
+/**
+ * 错误处理策略
+ */
+type ErrorStrategy = 'reject' | 'resolve' | 'silent';
+/**
+ * API 接口端点配置
+ */
+interface ApiEndpointConfig {
+    /** 接口路径 (支持 :param 语法) */
+    url: string;
+    /** 请求方法 */
+    method: HttpMethod;
+    /** 接口描述 */
+    desc?: string;
+    /** Mock 响应数据结构定义 */
+    responseSchema?: any;
+    /** 错误处理策略 */
+    errorStrategy?: ErrorStrategy;
+}
+/**
+ * API 请求配置
+ */
+interface ApiRequestConfig {
+    /** 请求 URL */
+    url: string;
+    /** 请求方法 */
+    method: HttpMethod;
+    /** 请求体数据 (POST/PUT 等) */
+    data?: any;
+    /** 查询参数 (GET 等) */
+    params?: any;
+    /** 请求头 */
+    headers?: any;
+    /** 用于取消请求的信号对象 */
+    signal?: AbortSignal;
+}
+/**
+ * 流式响应回调函数接口
+ */
+interface StreamCallbacks {
+    /** 收到消息片段时的回调 */
+    onMessage?: (data: any) => void;
+    /** 发生错误时的回调 */
+    onError?: (error: any) => void;
+    /** 请求完成时的回调 */
+    onFinish?: () => void;
+    /** 收到 HTTP 响应头部信息的回调，返回 true 表示劫持并中止流 */
+    onResponse?: (response: any) => Promise<boolean> | boolean;
+}
+/**
+ * API 适配器端口接口
+ * @description 所有底层请求引擎（如 Fetch, Axios, Mock）都必须实现此接口，以确保内核对具体通信库的解耦。
+ */
+interface ApiAdapter {
+    /**
+     * 发起普通 HTTP 请求
+     * @param config - 请求配置
+     * @param endpointConfig - 接口端点定义的元数据配置
+     * @returns 响应数据的 Promise
+     */
+    request<T = any>(config: ApiRequestConfig, endpointConfig?: ApiEndpointConfig): Promise<T>;
+    /**
+     * 发起流式请求 (SSE 或 Chunked Transfer)
+     * @param config - 请求配置
+     * @param callbacks - 流式处理的回调函数集合
+     * @param endpointConfig - 接口端点定义的元数据配置
+     */
+    stream?(config: ApiRequestConfig, callbacks: StreamCallbacks, endpointConfig?: ApiEndpointConfig): Promise<void>;
+}
+/**
+ * API 配置集合 (按模块和动作分组)
+ */
+interface ApiConfig {
+    /** 模块名称 */
+    [module: string]: {
+        /** 动作/接口名称 */
+        [action: string]: ApiEndpointConfig;
+    };
+}
+/**
+ * 业务侧发起请求时的选项
+ */
+interface RequestOptions extends Partial<ApiRequestConfig> {
+    /** 是否跳过全局错误处理逻辑 */
+    skipErrorHandler?: boolean;
+    /** 路径参数集合 (将替换 url 中的 :param 占位符) */
+    params?: any;
+    /** 流式响应：收到数据片段的回调 */
+    onMessage?: (data: any) => void;
+    /** 流式响应：发生错误的回调 */
+    onError?: (error: any) => void;
+    /** 流式响应：正常结束的回调 */
+    onFinish?: () => void;
+    /** 允许透传其他底层适配器所需的属性 (例如 axios 的特定配置) */
+    [key: string]: any;
+}
+/**
+ * API 响应拦截上下文对象
+ */
+interface ApiResponseContext {
+    /** 原始响应对象 (例如 AxiosResponse 或 Fetch Response) */
+    response: any;
+    /** HTTP 响应状态码 */
+    status: number;
+    /** 响应头集合 */
+    headers: Record<string, string>;
+    /** 解析后的业务数据体 */
+    data: any;
+    /** 对应的原始请求配置 */
+    config: ApiRequestConfig;
+}
+/**
+ * API 拦截器定义
+ */
+interface ApiInterceptor {
+    /**
+     * 请求发送前的拦截逻辑
+     * @param config - 原始请求配置
+     * @returns 修改后的请求配置，或其 Promise
+     */
+    interceptRequest?: (config: ApiRequestConfig) => ApiRequestConfig | Promise<ApiRequestConfig>;
+    /**
+     * 响应接收后的拦截逻辑
+     * @param context - 响应上下文信息
+     * @returns 如果返回 true，表示该拦截器已接管并处理了响应，后续拦截器及业务回调将不再触发
+     */
+    interceptResponse?: (context: ApiResponseContext) => boolean | Promise<boolean>;
+}
+
+/**
+ * 事件总线端口接口
+ * @description 定义应用内部事件通信的标准契约，支持发布订阅模式。
+ */
+interface EventBusPort {
+    /**
+     * 订阅事件
+     * @param event - 事件名称
+     * @param callback - 事件触发时的回调函数
+     * @returns 取消订阅的函数
+     */
+    on(event: string, callback: (...args: any[]) => any): () => void;
+    /**
+     * 取消订阅事件
+     * @param event - 事件名称
+     * @param callback - 之前注册的回调函数
+     */
+    off(event: string, callback: (...args: any[]) => any): void;
+    /**
+     * 触发事件 (发布)
+     * @param event - 事件名称
+     * @param args - 传递给回调函数的参数列表
+     */
+    emit(event: string, ...args: any[]): void;
+    /**
+     * 订阅一次性事件
+     * @description 事件触发一次后会自动取消订阅
+     * @param event - 事件名称
+     * @param callback - 事件触发时的回调函数
+     */
+    once(event: string, callback: (...args: any[]) => any): void;
+}
+
+/**
+ * 存储端口接口
+ * @description 定义数据持久化的标准契约，兼容 Web Storage API。
+ */
+interface StoragePort {
+    /**
+     * 获取存储项
+     * @param key - 键名
+     * @returns 对应的值，如果不存在则返回 null
+     */
+    getItem(key: string): string | null;
+    /**
+     * 设置存储项
+     * @param key - 键名
+     * @param value - 键值 (字符串)
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * 移除指定的存储项
+     * @param key - 键名
+     */
+    removeItem(key: string): void;
+    /**
+     * 清空所有存储项
+     */
+    clear(): void;
+    /**
+     * 返回存储对象中当前存储的数据项总数
+     */
+    readonly length: number;
+    /**
+     * 根据索引返回存储中对应键的名称
+     * @param index - 数值索引
+     * @returns 键名，如果索引超出范围则返回 null
+     */
+    key(index: number): string | null;
+}
+/**
+ * 类型化存储接口
+ * @description 提供泛型支持的存储访问能力，自动处理序列化
+ */
+interface TypedStorage {
+    /** 获取存储数据 */
+    get: <T = any>(key: string) => T | null;
+    /** 设置存储数据 */
+    set: <T = any>(key: string, value: T) => void;
+    /** 移除存储数据 */
+    remove: (key: string) => void;
+}
+
+/**
+ * 插件类型定义
+ */
+declare const PLUGIN_TYPES: readonly ["business", "functional", "view", "theme", "renderer", "system"];
+type PluginType = typeof PLUGIN_TYPES[number];
+/**
+ * 路由配置
+ */
+interface RouteConfig {
+    path: string;
+    component: React.ComponentType<any>;
+    meta?: Record<string, any>;
+}
+/**
+ * 插件插槽位置
+ * @description 定义插件可以注入 UI 的标准位置
+ */
+declare const Slot: {
+    readonly Sidebar: "sidebar";
+    readonly SidebarPanel: "sidebar-panel";
+    readonly Header: "header";
+    readonly StatusBar: "status-bar";
+    readonly Settings: "settings";
+    readonly MessageRenderer: "message-renderer";
+    readonly MessageContentRenderer: "message-content-renderer";
+    readonly SidebarSystem: "sidebar-system";
+    readonly SidebarBottom: "sidebar-bottom";
+    readonly RootLayout: "root-layout";
+    readonly Custom: "custom";
+};
+type SlotType = typeof Slot[keyof typeof Slot];
+type SlotPosition = SlotType | string;
+/**
+ * 插件扩展 (插槽注入配置)
+ */
+interface PluginExtension {
+    /** 插槽位置标识符 */
+    slot: SlotPosition;
+    /** 要注入的 React 组件 */
+    component: React.ComponentType<any>;
+    /** 排序权重，数值越小越靠前 */
+    order?: number;
+    /** @internal 插件 ID，由系统在加载时自动注入，用于溯源 */
+    _pluginId?: string;
+    /** 扩展的元数据信息 */
+    meta?: {
+        /** 显示图标 */
+        icon?: React.ReactNode;
+        /** 显示标签文本 */
+        label?: string;
+        /** 详细描述 */
+        description?: string;
+        /** 唯一标识符，用于某些特定插槽的索引 */
+        key?: string;
+        /** 允许其他自定义属性 */
+        [key: string]: any;
+    };
+}
+/**
+ * 插件配置项定义
+ */
+interface PluginConfigItem {
+    /** 配置键名 */
+    key: string;
+    /** 配置类型 */
+    type: 'string' | 'number' | 'boolean' | 'select';
+    /** 配置显示的标签 */
+    label: string;
+    /** 配置描述信息 */
+    description?: string;
+    /** 默认值 */
+    default?: any;
+    /** 当类型为 select 时的选项列表 */
+    options?: {
+        label: string;
+        value: any;
+    }[];
+    /** 选择模式：支持多选或标签模式 (AntD 风格) */
+    mode?: 'multiple' | 'tags';
+    /** 最小值 (针对 number 类型) */
+    min?: number;
+    /** 最大值 (针对 number 类型) */
+    max?: number;
+    /**
+     * 是否为私有配置
+     * @description 如果为 true，则该配置不会通过自动配置服务暴露给其他插件
+     * @default false
+     */
+    private?: boolean;
+}
+/**
+ * 插件能力定义 (Behavioral Capabilities)
+ * @description 定义插件的行为特征。注意：路由(routes)和扩展(extensions)属于结构化能力，直接通过 metadata 字段声明，不在此列。
+ */
+interface PluginCapabilities {
+    /**
+     * 是否支持配置设置
+     * @default false (如果 metadata.configuration 存在，则可能被隐式视为 true，建议显式声明)
+     */
+    configurable?: boolean;
+    /**
+     * 是否可嵌入其他页面
+     * @description 声明该插件是否可以作为 Widget 被其他插件引用
+     */
+    embeddable?: boolean;
+    /**
+     * 是否支持多实例
+     * @description 默认为 false (单例)。如果在聊天窗口中每个会话都需要独立状态，则设为 true
+     */
+    multiInstance?: boolean;
+    /**
+     * 是否需要后台运行
+     * @description 如果为 true，即使 UI 不可见，插件也不会被卸载
+     */
+    background?: boolean;
+    [key: string]: boolean | undefined;
+}
+/**
+ * 存储项数据结构定义 (Schema)
+ */
+interface StorageItemSchema {
+    /** 存储键名 */
+    key: string;
+    /** 数据类型 */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** 默认值 */
+    default?: any;
+    /** 描述信息 */
+    description?: string;
+    /**
+     * 作用域
+     * @description 'plugin' 表示仅当前插件可见（带插件 ID 前缀），'shared' 表示全局共享
+     */
+    scope?: 'plugin' | 'shared';
+}
+/**
+ * 插件存储接口
+ * @description 包含私有存储和共享存储访问能力
+ */
+interface PluginStorage extends TypedStorage {
+    /** 获取插件私有存储数据 */
+    get: TypedStorage['get'];
+    /** 设置插件私有存储数据 */
+    set: TypedStorage['set'];
+    /** 移除插件私有存储数据 */
+    remove: TypedStorage['remove'];
+    /** 全局共享存储访问 */
+    shared: TypedStorage & {
+        /** 获取全局共享存储数据 */
+        get: TypedStorage['get'];
+        /** 设置全局共享存储数据 */
+        set: TypedStorage['set'];
+        /** 移除全局共享存储数据 */
+        remove: TypedStorage['remove'];
+    };
+}
+/**
+ * 插件生命周期 Hooks
+ * @description 插件可以在不同的生命周期阶段执行特定的逻辑
+ */
+interface PluginLifecycle {
+    /**
+     * 插件加载时调用
+     * @description 在插件被扫描并注入内核时触发。用于初始化内部状态、注册服务、设置拦截器等。此时 UI 尚未挂载。
+     * @param context - 插件上下文对象，提供核心能力的访问
+     */
+    onLoad?: (context: PluginContext) => void | Promise<void>;
+    /**
+     * 插件挂载到 UI 时调用
+     * @description 当插件的 UI 组件（如有）被 React 挂载到 DOM 时触发。
+     * @param context - 插件上下文对象
+     */
+    onMount?: (context: PluginContext) => void;
+    /**
+     * 插件从 UI 卸载时调用
+     * @description 当插件的 UI 组件被销毁时触发。用于清理定时器、取消订阅等。
+     * @param context - 插件上下文对象
+     */
+    onUnmount?: (context: PluginContext) => void;
+    /**
+     * 插件配置发生变化时调用
+     * @description 当用户通过配置中心修改插件设置时触发。
+     * @param newConfig - 变更后的新配置对象
+     * @param oldConfig - 变更前的旧配置对象
+     */
+    onConfigChange?: (newConfig: any, oldConfig: any) => void;
+}
+/**
+ * 插件上下文
+ * @description 传递给插件生命周期钩子的核心对象，是插件访问宿主环境能力的唯一入口。
+ */
+interface PluginContext {
+    /** 当前插件的唯一标识符 */
+    pluginId: string;
+    /** API 请求能力入口 */
+    api: any;
+    /** 事件总线能力入口 */
+    events: EventBusPort;
+    /** 存储管理能力入口 */
+    storage: PluginStorage;
+    /** 日志输出工具，自动携带插件 ID 前缀 */
+    logger: {
+        debug: (...args: any[]) => void;
+        info: (...args: any[]) => void;
+        warn: (...args: any[]) => void;
+        error: (...args: any[]) => void;
+    };
+    /**
+     * 访问其他插件提供的服务
+     * @param serviceName - 服务注册名称
+     * @returns 服务实例，如果不存在则返回 undefined
+     */
+    getService: <T = any>(serviceName: string) => T | undefined;
+    /**
+     * 注册当前插件的服务供他人使用
+     * @param serviceName - 唯一服务名称
+     * @param service - 服务实现对象
+     */
+    registerService: (serviceName: string, service: any) => void;
+    /** 宿主环境 Window 的代理对象 (用于沙箱隔离) */
+    window: WindowProxy;
+}
+/**
+ * 完整的插件对象定义
+ */
+interface Plugin extends PluginLifecycle {
+    /**
+     * 插件唯一标识符
+     * @description 必须与 metadata.id 一致，通常为只读。
+     */
+    readonly id: string;
+    /** 插件元数据配置 */
+    metadata: PluginMetadata;
+    /** 插件提供的功能组件集合 (可选) */
+    components?: Record<string, React.ComponentType<any>>;
+    /** 插件提供的工具函数集合 (可选) */
+    utils?: Record<string, any>;
+    /** 插件的初始默认配置 (可选) */
+    defaultConfig?: Record<string, any>;
+}
+/**
+ * 插件基础类
+ * @deprecated 建议统一使用工厂模式 definePlugin() 定义插件，以消除类与对象定义的歧义。
+ * @description 解决插件定义时 id 与 metadata.id 重复定义的问题，并提供基础生命周期管理
+ */
+declare abstract class BasePlugin implements Plugin {
+    abstract metadata: PluginMetadata;
+    /**
+     * 插件 ID
+     * @description 自动从 metadata.id 获取
+     */
+    get id(): string;
+    onLoad?(context: PluginContext): void | Promise<void>;
+    onMount?(context: PluginContext): void;
+    onUnmount?(context: PluginContext): void;
+    onConfigChange?(newConfig: any, oldConfig: any): void;
+}
+/**
+ * 辅助函数：定义插件并自动从 metadata.id 注入顶级 id
+ * @description 解决插件定义时 id 与 metadata.id 重复定义的问题，提高代码优雅度
+ * @param plugin 插件定义（不包含顶级 id）
+ * @returns 完整的插件对象
+ */
+declare function definePlugin(plugin: Omit<Plugin, 'id'>): Plugin;
+/**
+ * 插件元数据定义
+ * @description 描述插件的静态属性，用于插件市场展示、权限校验和内核加载参考。
+ */
+interface PluginMetadata {
+    /** 插件唯一 ID (推荐反向域名格式，如 com.company.plugin) */
+    id: string;
+    /** 插件显示名称 */
+    name: string;
+    /** 插件版本号 (符合 SemVer 规范) */
+    version: string;
+    /** 插件类型 */
+    type: PluginType;
+    /** 插件功能描述 */
+    description?: string;
+    /** 插件作者信息 */
+    author?: string;
+    /** 插件图标 (React 组件或图标名称) */
+    icon?: React.ReactNode;
+    /** 插件依赖的其他插件 ID 列表 */
+    dependencies?: string[];
+    /** 路由配置集合，用于在主应用中注册页面 */
+    routes?: RouteConfig[];
+    /** 插槽扩展集合，用于在主应用 UI 预留位注入组件 */
+    extensions?: PluginExtension[];
+    /** 插件所需调用的 API 接口配置 */
+    api?: ApiConfig;
+    /** 插件行为能力声明 */
+    capabilities?: PluginCapabilities;
+    /** 插件的可配置项定义 */
+    configuration?: PluginConfigItem[];
+    /** 插件所需的存储结构定义 */
+    storage?: StorageItemSchema[];
+    /**
+     * 系统状态自动绑定
+     * @description 将插件的配置项自动同步到系统的全局状态中 (如主题色、身份认证等)
+     */
+    systemStateBindings?: {
+        /** 插件配置中的键名 */
+        configKey: string;
+        /** 系统全局状态中的键名 */
+        stateKey: string;
+        /** 预设的转换逻辑名称 */
+        transform?: 'theme-mode' | 'identity';
+    }[];
+}
+
+/**
+ * 服务注册中心 (Service Registry)
+ * @description 核心应用层服务，作为微内核架构中的“中枢调度员”。
+ * 主要职责：
+ * 1. 服务解耦：允许插件将其内部功能暴露为“服务”，而无需与其他插件产生物理依赖。
+ * 2. 动态发现：提供按名称查找服务的能力，支持服务热插拔。
+ * 3. 依赖协调：通过 `waitFor` 机制解决插件间由于加载顺序导致的初始化依赖问题。
+ *
+ * 建议的服务命名规范: `pluginId.serviceName` (例如: `auth.sessionService`)
+ */
+declare class ServiceRegistry {
+    /** 存储已注册服务的 Map 对象 */
+    private services;
+    /** 存储正在等待特定服务的监听器集合 */
+    private listeners;
+    /**
+     * 注册一个服务实现
+     * @param name - 唯一的服务名称
+     * @param service - 服务实例或对象
+     */
+    register(name: string, service: any): void;
+    /**
+     * 同步获取服务实例
+     * @template T - 服务类型的泛型
+     * @param name - 服务名称
+     * @returns 服务实例，若不存在则返回 undefined
+     */
+    get<T = any>(name: string): T | undefined;
+    /**
+     * 异步等待并获取服务
+     * @description 如果服务尚未注册，将返回一个 Promise，直到该服务被注册时 resolve。
+     * 支持设置超时时间，防止因插件加载失败导致的永久挂起。
+     *
+     * @template T - 服务类型的泛型
+     * @param name - 待等待的服务名称
+     * @param timeout - 超时时间 (毫秒)，默认 10000ms (10秒)。若为 0 则永不超时。
+     * @returns 包含服务实例的 Promise
+     * @throws {Error} 若在规定时间内服务未注册，则抛出超时异常。
+     */
+    waitFor<T = any>(name: string, timeout?: number): Promise<T>;
+    /**
+     * 检查服务是否已注册
+     * @param name - 服务名称
+     */
+    has(name: string): boolean;
+    /**
+     * 注销特定的服务
+     * @param name - 服务名称
+     */
+    unregister(name: string): void;
+    /**
+     * 清除所有已注册的服务和监听器
+     * @description 通常仅在系统重置或大型热更新时使用。
+     */
+    clear(): void;
+}
+declare const serviceRegistry: ServiceRegistry;
+
+/**
+ * 基于 Axios 的默认请求适配器
+ */
+declare class AxiosAdapter implements ApiAdapter {
+    private client;
+    constructor(baseURL?: string, timeout?: number);
+    request<T = any>(config: ApiRequestConfig): Promise<T>;
+    stream(config: ApiRequestConfig, callbacks: StreamCallbacks, _endpointConfig?: ApiEndpointConfig): Promise<void>;
+}
+
+/**
+ * API 引擎核心类
+ * @description 负责加载配置并执行请求，支持策略模式切换底层请求实现
+ */
+declare class ApiEngine {
+    private adapter;
+    private config;
+    private interceptors;
+    constructor(adapter?: ApiAdapter);
+    /**
+     * 注册拦截器
+     */
+    registerInterceptor(interceptor: ApiInterceptor): void;
+    /**
+     * 移除拦截器
+     */
+    unregisterInterceptor(interceptor: ApiInterceptor): void;
+    /**
+     * 切换请求适配器
+     * @param adapter 新的适配器实例
+     */
+    useAdapter(adapter: ApiAdapter): void;
+    /**
+     * 注册 API 配置
+     * @param config 配置对象
+     */
+    register(config: ApiConfig): void;
+    /**
+     * 获取接口配置
+     */
+    getEndpoint(module: string, action: string): ApiEndpointConfig | undefined;
+    /**
+     * 发起 API 请求
+     * @param module 模块名
+     * @param action 动作名
+     * @param data 请求数据 (Body 或 Query)
+     * @param options 请求选项
+     */
+    call<T = any>(module: string, action: string, data?: any, options?: RequestOptions): Promise<T>;
+    /**
+     * 发起流式请求
+     * @param module 模块名
+     * @param action 动作名
+     * @param data 请求数据
+     * @param options 请求选项
+     */
+    stream(module: string, action: string, data?: any, options?: RequestOptions): Promise<void>;
+    /**
+     * 准备请求配置，应用 URL 参数替换和请求拦截器
+     */
+    private prepareRequestConfig;
+    /**
+     * 应用所有请求拦截器
+     */
+    private applyRequestInterceptors;
+    /**
+     * 应用所有响应拦截器
+     * @returns 是否被劫持
+     */
+    private applyResponseInterceptors;
+    /**
+     * 检查 HTTP 状态码
+     */
+    private checkHttpStatus;
+    /**
+     * 提取响应数据
+     */
+    private extractResponseData;
+    /**
+     * 处理业务错误
+     */
+    private handleBusinessError;
+    /**
+     * 判断是否为 BaseResponse
+     */
+    private isBaseResponse;
+    /**
+     * 严格判断是否为 AxiosResponse
+     */
+    private isAxiosResponse;
+    /**
+     * 创建拦截上下文
+     */
+    private createInterceptorContext;
+}
+declare const apiEngine: ApiEngine;
+
+/**
+ * 自动检测是否处于 Mock 模式
+ */
+declare function isMockMode(): boolean;
+/**
+ * 从文件模块映射中解析 API 配置
+ * @description 配合 Vite 的 import.meta.glob 使用，自动匹配定义文件和 Mock 文件
+ * @param definitionsMap API 定义文件映射 (import.meta.glob('./modules/*.ts', { eager: true }))
+ * @param mocksMap Mock 文件映射 (import.meta.glob('./modules/*.mock.ts', { eager: true }))
+ * @param useMock 是否启用 Mock (如果不传，将自动调用 isMockMode())
+ * @returns 合并后的 ApiConfig
+ */
+declare function resolveApiModules(definitionsMap: Record<string, any>, mocksMap?: Record<string, any>): ApiConfig;
+
+/**
+ * 成功状态码
+ */
+declare const SUCCESS_CODE = "000000";
+/**
+ * 基础 API 响应接口
+ * @template T 响应数据的类型
+ */
+interface BaseResponse<T = any> {
+    /** 业务状态码 */
+    code: string | number;
+    /** 响应消息提示 */
+    message: string;
+    /** 业务响应数据主体 */
+    data: T;
+}
+/**
+ * 业务场景实体接口
+ * @description 描述系统中的业务分析场景
+ */
+interface Scene {
+    /** 场景唯一标识符 */
+    id: string;
+    /** 场景名称 */
+    name: string;
+    /** 场景详细描述 */
+    description: string;
+    /** 场景内部代码/标识 */
+    code: string;
+    /** 场景创建者 ID 或名称 */
+    creator: string;
+    /** 创建时间字符串 (ISO 格式) */
+    createTime: string;
+    /** 该场景关联的物理数据表数量 */
+    tableCount: number;
+    /** 该场景关联的知识库数量 */
+    kbCount: number;
+    /** 该场景关联的预设问答对数量 */
+    qaCount: number;
+    /** 场景封面图 URL (可选) */
+    cover?: string;
+}
+
+interface ApiProviderProps {
+    api: ApiEngine;
+    children: React.ReactNode;
+}
+declare const ApiProvider: React.FC<ApiProviderProps>;
+declare const useApi: () => ApiEngine;
+
+/**
+ * 配置管理器
+ * @description 核心工具类，负责管理应用的全局系统配置以及各插件的初始化业务配置。
+ * 配置数据通常在应用启动时通过 `usePluginLoader` 注入，并作为插件运行时的取值回退来源。
+ */
+declare class ConfigManager {
+    /** 内部存储配置的 Map 对象 */
+    private config;
+    /**
+     * 设置特定的配置项
+     * @param key - 配置键名（如 'system' 或插件 ID）
+     * @param value - 配置内容对象
+     */
+    set(key: string, value: any): void;
+    /**
+     * 获取指定的配置项
+     * @param key - 配置键名
+     * @returns 配置内容，若不存在则返回 undefined
+     */
+    get(key: string): any;
+    /**
+     * 批量合并配置对象
+     * @description 对顶层属性进行浅合并，若属性值为对象则进行一层深度的合并。
+     * @param config - 待合并的配置对象映射
+     */
+    merge(config: Record<string, any>): void;
+    /**
+     * 获取当前存储的所有配置快照
+     * @returns 包含所有配置的普通对象
+     */
+    getAll(): Record<string, any>;
+}
+/** 全局配置管理器单例 */
+declare const configManager: ConfigManager;
+
+/** 插件错误边界组件属性 */
+interface Props {
+    /** 发生错误的插件 ID */
+    pluginId?: string;
+    /** 错误发生时的降级 UI */
+    fallback?: ReactNode;
+    /** 子组件内容 */
+    children: ReactNode;
+    /** 是否静默模式，开启后不显示任何错误 UI，仅记录日志 */
+    silent?: boolean;
+}
+/** 插件错误边界组件状态 */
+interface State {
+    /** 是否捕获到错误 */
+    hasError: boolean;
+    /** 捕获到的错误对象 */
+    error: Error | null;
+}
+/**
+ * 插件错误边界组件
+ * @description 核心组件，用于捕获子组件渲染过程中的 JavaScript 错误，记录日志并显示降级 UI。
+ * 确保单个插件的运行异常不会导致整个主应用或其他插件崩溃。
+ */
+declare class PluginErrorBoundary extends Component<Props, State> {
+    constructor(props: Props);
+    /**
+     * 从错误中派生状态
+     * @param error - 捕获到的错误
+     */
+    static getDerivedStateFromError(error: any): State;
+    /**
+     * 捕获到错误后的回调
+     * @param error - 错误对象
+     * @param errorInfo - 错误堆栈信息
+     */
+    componentDidCatch(error: any, errorInfo: ErrorInfo): void;
+    /**
+     * 重置错误状态，尝试重新渲染
+     */
+    handleRetry: () => void;
+    render(): string | number | boolean | Iterable<React.ReactNode> | react_jsx_runtime.JSX.Element | null | undefined;
+}
+
+/** 插件插槽组件属性 */
+interface PluginSlotProps {
+    /** 插槽位置标识，决定渲染哪些插件扩展 */
+    slot: SlotPosition;
+    /** 传递给扩展组件的 Props 对象 */
+    props?: Record<string, any>;
+    /** 自定义容器类名 (Tailwind CSS) */
+    className?: string;
+    /** 自定义容器内联样式 */
+    style?: React.CSSProperties;
+    /**
+     * 自定义渲染函数
+     * @param item - 包含 key、组件和扩展元信息的对象
+     * @param index - 索引位置
+     */
+    renderItem?: (item: {
+        key: string;
+        component: React.ReactNode;
+        extension: PluginExtension;
+    }, index: number) => React.ReactNode;
+    /** 骨架屏组件，当插槽内无插件扩展时显示的占位 UI */
+    skeleton?: React.ReactNode;
+    /** 回退组件，当插槽内无插件扩展时显示的 UI，优先级高于 skeleton */
+    fallback?: React.ReactNode;
+}
+/**
+ * 插件插槽组件
+ * @description UI 层的核心组件，用于在应用中声明一个“插槽”。
+ * 它会自动根据 slot 标识从 PluginManager 中获取所有注册的插件扩展组件并按顺序渲染。
+ * 支持订阅插件变更，实现动态热插拔。
+ */
+declare const PluginSlot: React.FC<PluginSlotProps>;
+
+/**
+ * 通用插槽骨架屏组件集合
+ * @description 提供一组预定义的骨架屏 UI，用于在插件加载或插槽内容未准备好时提供更好的用户体验。
+ */
+/**
+ * 侧边栏图标骨架屏
+ * @param expanded - 是否处于展开状态
+ */
+declare const SidebarIconSkeleton: React.FC<{
+    expanded?: boolean;
+}>;
+/**
+ * 状态栏项骨架屏
+ */
+declare const StatusBarItemSkeleton: React.FC;
+/**
+ * 头像骨架屏
+ */
+declare const AvatarSkeleton: React.FC;
+/**
+ * 通用块级骨架屏
+ * @param className - 自定义类名
+ */
+declare const BlockSkeleton: React.FC<{
+    className?: string;
+}>;
+/**
+ * 自动根据插槽位置匹配骨架屏
+ */
+declare const SlotSkeletons: React.FC<{
+    slot: string;
+    expanded?: boolean;
+}>;
+
+/**
+ * 插件注册表接口
+ * @description 键为插件 ID，值为一个返回插件定义的异步加载函数。
+ */
+interface PluginRegistry {
+    [pluginId: string]: () => Promise<any>;
+}
+/**
+ * 插件自动发现规则
+ */
+interface DiscoveryRule {
+    /**
+     * 路径匹配标识。
+     * @example 'plugins' 或 '@chatbi-plugins'
+     */
+    pathSegment: string;
+    /**
+     * 生成插件 ID 时的前缀。
+     * @example '@chatbi-v/plugin'，最终生成如 '@chatbi-v/plugin-demo'
+     */
+    idPrefix: string;
+}
+/**
+ * 解析插件注册表
+ * @description 核心逻辑：将 Vite 的 `import.meta.glob` 结果映射为标准的插件注册表。
+ * 它会根据预定义的路径匹配规则，从文件路径中提取插件目录名，并拼接前缀生成唯一的插件 ID。
+ *
+ * @param options - 包含待处理模块和匹配规则的选项对象
+ * @returns 解析后的 PluginRegistry 对象
+ */
+declare const resolvePluginRegistry: (options: {
+    /** 原始模块映射 (来自 Vite glob) */
+    modules: Record<string, () => Promise<any>>;
+    /** 自定义发现规则 (可选) */
+    rules?: DiscoveryRule[];
+}) => PluginRegistry;
+
+type EventCallback = (...args: any[]) => any;
+/**
+ * 事件总线接口
+ */
+interface EventBus {
+    /**
+     * 订阅事件
+     * @param event 事件名称
+     * @param callback 回调函数
+     * @returns 取消订阅函数
+     */
+    on(event: string, callback: EventCallback): () => void;
+    /**
+     * 取消订阅
+     * @param event 事件名称
+     * @param callback 回调函数
+     */
+    off(event: string, callback: EventCallback): void;
+    /**
+     * 触发事件
+     * @param event 事件名称
+     * @param args 事件参数
+     */
+    emit(event: string, ...args: any[]): void;
+    /**
+     * 订阅一次性事件
+     * @param event 事件名称
+     * @param callback 回调函数
+     */
+    once(event: string, callback: EventCallback): void;
+}
+declare class DefaultEventBus implements EventBus {
+    private listeners;
+    on(event: string, callback: EventCallback): () => void;
+    off(event: string, callback: EventCallback): void;
+    emit(event: string, ...args: any[]): void;
+    once(event: string, callback: EventCallback): void;
+}
+
+/**
+ * 核心领域服务：存储管理器
+ * @description 统一管理应用内所有的持久化存储资源。
+ * 核心功能：
+ * 1. 作用域隔离：通过前缀划分 `plugin`、`shared` 和 `system` 三个层级的存储空间。
+ * 2. Schema 校验：支持注册存储描述，规范数据存取，避免键名冲突。
+ * 3. 默认值与配置回退：支持从 Schema 默认值或 ConfigManager 中回退取值。
+ */
+declare class StorageManager {
+    /** 底层物理存储驱动 */
+    private baseStorage;
+    /** 插件 ID 与存储描述定义的映射关系 */
+    private schemas;
+    /** 内存缓存，减少 JSON 序列化和物理 IO 开销 */
+    private memoryCache;
+    /**
+     * 初始化存储管理器
+     * @param baseStorage - 符合 StoragePort 接口的物理存储驱动（如 LocalStorageAdapter）
+     */
+    constructor(baseStorage: StoragePort);
+    /**
+     * 注册插件的存储 Schema
+     * @param pluginId - 插件 ID
+     * @param schema - 存储项定义列表
+     */
+    registerSchema(pluginId: string, schema: StorageItemSchema[]): void;
+    /**
+     * 内部校验方法：检查键名是否在 Schema 中声明
+     * @param pluginId - 插件 ID
+     * @param key - 待校验的键名
+     * @param scope - 目标作用域
+     */
+    private validateKey;
+    /**
+     * 获取插件私有存储适配器
+     * @param pluginId - 插件 ID
+     * @returns 自动添加 `plugin:{id}:` 前缀的存储接口
+     */
+    getPluginStorage(pluginId: string): StoragePort;
+    /**
+     * 获取全局共享存储适配器
+     * @returns 自动添加 `shared:` 前缀的存储接口
+     */
+    getSharedStorage(): StoragePort;
+    /**
+     * 获取系统内部存储适配器
+     * @returns 自动添加 `system:` 前缀的存储接口
+     */
+    getSystemStorage(): StoragePort;
+    /**
+     * 创建插件沙箱使用的复合存储对象
+     * @description 返回的对象封装了对私有存储和共享存储的操作。
+     * 特性：
+     * - 内存级 LRU 缓存：极大提升高频读写性能。
+     * - 自动序列化/反序列化 JSON。
+     * - 自动校验 Schema。
+     * - 取值回退逻辑：持久化存储 -> ConfigManager -> Schema 默认值。
+     *
+     * @param pluginId - 插件 ID
+     * @returns 包含 get/set/remove 及 shared 子对象的复合接口
+     */
+    getContextStorage(pluginId: string): {
+        shared: {
+            get: <T = any>(key: string) => T | null;
+            set: <T = any>(key: string, value: T) => void;
+            remove: (key: string) => void;
+        };
+        get: <T = any>(key: string) => T | null;
+        set: <T = any>(key: string, value: T) => void;
+        remove: (key: string) => void;
+    };
+}
+
+/**
+ * 插件管理器
+ * @description 核心领域服务，负责插件的完整生命周期管理，包括扫描、注册、配置合并、状态切换及依赖解析。
+ */
+declare class PluginManager {
+    /** 全局事件总线，用于插件间及插件与内核间的异步通信 */
+    readonly eventBus: DefaultEventBus;
+    /** 存储管理服务，负责插件私有存储和系统级状态的持久化 */
+    private storageManager;
+    /** 插件 ID 到运行时实例的映射表 */
+    private runtimes;
+    /** 插件 ID 到原始插件定义对象的映射表 */
+    private plugins;
+    /** 收集到的所有插件路由配置 */
+    private routes;
+    /** 收集到的所有插件扩展点配置，按插槽位置分组 */
+    private extensions;
+    /** 插件的启用状态和排序信息的内存缓存 */
+    private pluginStates;
+    /** 状态变更监听器集合，支持按插槽过滤 */
+    private listeners;
+    /** 按插槽位置存储的监听器，用于精确通知 */
+    private slotListeners;
+    /** 扩展点缓存，避免重复计算 */
+    private memoizedExtensions;
+    /** 路由缓存 */
+    private memoizedRoutes;
+    /** 传递给插件的共享上下文缓存 */
+    private sharedContext;
+    /** 收集到的插件工具函数集合 */
+    private utils;
+    /**
+     * 构造函数
+     * @param storage - 底层存储适配器
+     */
+    constructor(storage: StoragePort);
+    /**
+     * 从持久化存储中恢复插件状态 (启用/禁用、排序等)
+     */
+    private loadStates;
+    /**
+     * 将当前的插件状态持久化到存储中
+     */
+    private saveStates;
+    /**
+     * 订阅插件状态的变更通知
+     * @param listener - 变更时的回调函数
+     * @param slot - (可选) 指定监听的插槽位置，若提供则仅在该插槽受影响时通知
+     * @returns 取消订阅的函数
+     */
+    subscribe(listener: () => void, slot?: SlotPosition | string): () => void;
+    /**
+     * 获取存储管理器实例
+     * @returns StorageManager 实例
+     */
+    getStorageManager(): StorageManager;
+    /**
+     * 触发状态变更通知
+     * @param affectedSlot - (可选) 受影响的插槽位置
+     */
+    private notify;
+    /**
+     * 获取所有已注册的插件列表
+     * @description 结果会根据插件类型优先级和用户自定义排序进行排序
+     * @returns 排序后的插件数组
+     */
+    getPlugins(): Plugin[];
+    /**
+     * 获取指定插件的状态信息
+     * @param pluginId - 插件 ID
+     * @returns 包含启用状态和排序值的对象
+     */
+    getPluginState(pluginId: string): {
+        enabled: boolean;
+        order: number;
+    };
+    /**
+     * 检查指定插件是否处于启用状态
+     * @param pluginId - 插件 ID
+     * @returns 是否启用
+     */
+    isPluginEnabled(pluginId: string): boolean;
+    /**
+     * 切换插件的启用/禁用状态
+     * @description 禁用插件会立即触发其卸载生命周期并销毁运行时。
+     * @param pluginId - 插件 ID
+     * @param enabled - 目标状态
+     */
+    togglePlugin(pluginId: string, enabled: boolean): void;
+    /**
+     * 设置插件的显示排序权重
+     * @param pluginId - 插件 ID
+     * @param order - 排序权重值
+     */
+    setPluginOrder(pluginId: string, order: number): void;
+    /**
+     * 获取指定插件的运行时状态
+     * @param pluginId - 插件 ID
+     * @returns 'error' | 'mounted' | 'loaded' | 'initial'
+     */
+    getPluginRuntimeStatus(pluginId: string): "error" | "mounted" | "loaded" | "initial";
+    /**
+     * 获取指定插件的运行时错误
+     * @param pluginId - 插件 ID
+     * @returns Error 对象或 null
+     */
+    getPluginError(pluginId: string): Error | null;
+    /**
+     * 报告插件运行时错误 (通常由 ErrorBoundary 调用)
+     * @param pluginId - 插件 ID
+     * @param error - 错误对象
+     */
+    reportPluginError(pluginId: string, error: Error): void;
+    /**
+     * 获取插件的完整能力声明
+     * @param pluginId - 插件 ID
+     * @returns 能力对象
+     */
+    getUnifiedCapabilities(pluginId: string): PluginCapabilities;
+    /**
+     * 更新指定插件的某项配置
+     * @description 该操作会同步更新内存中的配置、持久化到存储并触发全局事件通知。
+     * @param pluginId - 插件 ID
+     * @param key - 配置键名
+     * @param value - 新的配置值
+     */
+    updatePluginConfig(pluginId: string, key: string, value: any): void;
+    /**
+     * 获取指定插件的某项配置值
+     * @param pluginId - 插件 ID
+     * @param key - 配置键名
+     * @returns 配置值
+     */
+    getPluginConfig(pluginId: string, key: string): any;
+    /**
+     * 获取系统全局配置 (非插件特定)
+     * @param key - 系统配置键名
+     * @returns 配置值
+     */
+    getSystemConfig(key: string): any;
+    /**
+     * 获取由插件注册的服务实例
+     * @template T 服务接口类型
+     * @param name - 服务注册名称
+     * @returns 服务实例或 undefined
+     */
+    getService<T = any>(name: string): T | undefined;
+    /**
+     * 获取指定插槽位置的所有已启用插件的扩展
+     * @param slot - 插槽位置标识
+     * @returns 排序后的扩展配置数组
+     */
+    getExtensions(slot: SlotPosition | string): PluginExtension[];
+    /**
+     * 获取所有已启用插件注册的路由配置
+     * @returns 增强后的路由配置数组
+     */
+    getRoutes(): RouteConfig[];
+    /**
+     * 注册一个新插件到管理器中
+     * @description 此阶段会执行元数据校验、存储 Schema 注册、配置合并及扩展点收集。
+     * @param plugin - 插件对象
+     * @param notify - 是否在注册完成后触发状态变更通知
+     */
+    register(plugin: Plugin, notify?: boolean): void;
+    /**
+     * 初始化所有插件
+     * @param sharedContext 共享上下文
+     */
+    initPlugins(sharedContext?: Record<string, any>): Promise<void>;
+    /**
+     * 获取排序后的插件 ID 列表 (处理依赖)
+     */
+    private getSortedPluginIds;
+    /**
+     * 加载插件列表
+     * @param configs 插件配置
+     * @param registry 插件注册表 (动态导入函数)
+     */
+    loadPlugins(configs: Record<string, any>, registry: Record<string, () => Promise<any>>): Promise<void>;
+    /**
+     * 加载远程插件
+     * @param pluginId 插件 ID
+     * @param url 远程 URL
+     * @param config 插件配置
+     */
+    loadRemotePlugin(pluginId: string, url: string, config: any): Promise<Plugin | null>;
+    /**
+     * IIFE 模式加载插件
+     */
+    private loadIIFEPlugin;
+    /**
+     * 实例化插件
+     */
+    private instantiatePlugin;
+    private validatePlugin;
+    private handleBusinessPlugin;
+    private handleFunctionalPlugin;
+    private handleViewPlugin;
+    private handleThemePlugin;
+    private handleSystemPlugin;
+}
+/**
+ * 全局插件管理器实例
+ */
+declare const pluginManager: PluginManager;
+
+/**
+ * @file plugin-runtime.ts
+ * @description 插件运行时，封装单个插件的生命周期（load/mount/unmount）、沙箱环境和隔离上下文
  * @author ChatBI Team
  */
-export * from './ports/api-port';
-export * from './ports/event-bus-port';
-export * from './ports/plugin-port';
-export * from './ports/storage-port';
-export * from './application/service-registry';
-export * from './api-context';
-export * from './config-manager';
-export * from './components/PluginErrorBoundary';
-export * from './components/PluginSlot';
-export * from './components/SlotSkeletons';
-export * from './domain/auto-loader';
-export * from './domain/plugin-manager';
-export * from './domain/plugin-runtime';
-export * from './domain/plugin-sandbox';
-export * from './domain/storage-manager';
-export * from './domain/models';
-export * from './adapters/local-storage-adapter';
-export * from './adapters/scoped-storage-adapter';
-export * from './event-bus';
-export * from './plugin-context';
-export * from './api';
-export * from './sandbox/proxy-sandbox';
-export * from './utils';
-export * from './hooks/use-storage-state';
-export * from './hooks/use-plugin-loader';
+
+/**
+ * 插件运行时类
+ * @description 为单个插件提供独立的运行环境，负责管理其生命周期、初始化沙箱环境并组装上下文对象。
+ */
+declare class PluginRuntime {
+    /** 插件定义对象 */
+    plugin: Plugin;
+    /** 传递给插件的上下文对象 */
+    context: PluginContext;
+    /** 存储沙箱隔离设施 */
+    private storageSandbox;
+    /** Window/全局对象沙箱隔离设施 */
+    private windowSandbox;
+    /** 是否已完成加载阶段 */
+    private isLoaded;
+    /** 是否已完成挂载阶段 */
+    private isMounted;
+    /** 运行时捕获的错误信息 */
+    private error;
+    /**
+     * 构造函数
+     * @param plugin - 插件定义对象
+     * @param sharedContext - 来自内核的共享上下文资源 (如 API 引擎、事件总线)
+     * @param storageManager - 全局存储管理器
+     */
+    constructor(plugin: Plugin, sharedContext: Record<string, any>, storageManager: StorageManager);
+    /**
+     * 执行插件的加载逻辑 (onLoad)
+     * @description 此阶段会自动注册插件声明的 API 配置，并调用插件的 onLoad 钩子。
+     * 用于执行非 UI 的初始化逻辑，如注册服务、拦截器等。
+     */
+    load(): Promise<void>;
+    /**
+     * 执行插件的挂载逻辑 (onMount)
+     * @description 此阶段会激活 Window 沙箱并调用插件的 onMount 钩子。
+     * 此时插件的 UI 组件（如有）即将或已经进入 DOM。
+     */
+    mount(): Promise<void>;
+    /**
+     * 执行插件的卸载逻辑 (onUnmount)
+     * @description 调用插件的 onUnmount 钩子并停用沙箱。
+     */
+    unmount(): Promise<void>;
+    /**
+     * 彻底销毁插件实例
+     * @description 卸载插件并重置加载状态。
+     */
+    destroy(): Promise<void>;
+    /**
+     * 设置运行时错误 (内部使用)
+     * @internal
+     */
+    _setError(error: Error | null): void;
+    /**
+     * 获取插件运行时错误
+     */
+    getError(): Error | null;
+    /**
+     * 获取插件当前运行状态
+     * @returns 'error' | 'mounted' | 'loaded' | 'initial'
+     */
+    get status(): "error" | "mounted" | "loaded" | "initial";
+}
+
+/**
+ * 插件隔离沙箱
+ * @description 核心领域服务，为每个插件实例创建独立的运行上下文。
+ * 它是插件与系统核心之间的“中间层”，确保插件只能访问其权限范围内的资源。
+ * 主要职责：
+ * 1. 存储隔离：确保插件只能读写属于自己的 LocalStorage 命名空间。
+ * 2. 日志隔离：为插件提供带有自身 ID 前缀的日志输出，方便调试。
+ */
+declare class PluginSandbox {
+    /** 关联的插件唯一标识 */
+    private pluginId;
+    /** 系统全局存储管理器 */
+    private storageManager;
+    /**
+     * 构造插件沙箱
+     * @param pluginId - 插件 ID
+     * @param storageManager - 系统存储管理器实例
+     */
+    constructor(pluginId: string, storageManager: StorageManager);
+    /**
+     * 获取隔离的存储接口
+     * @description 返回一个受限的 StoragePort，所有操作都会自动带上插件 ID 前缀。
+     */
+    get storage(): {
+        shared: {
+            get: <T = any>(key: string) => T | null;
+            set: <T = any>(key: string, value: T) => void;
+            remove: (key: string) => void;
+        };
+        get: <T = any>(key: string) => T | null;
+        set: <T = any>(key: string, value: T) => void;
+        remove: (key: string) => void;
+    };
+    /**
+     * 获取隔离的日志接口
+     * @description 返回一个带插件 ID 前缀的 Logger 实例。
+     */
+    get logger(): Logger;
+}
+
+/**
+ * 浏览器本地存储 (LocalStorage) 适配器
+ * @description 实现 `StoragePort` 接口，封装了对原生 `localStorage` 的访问。
+ * 支持可选的命名空间前缀隔离，确保在同一个域下不同模块的数据互不干扰。
+ */
+declare class LocalStorageAdapter implements StoragePort {
+    /** 命名空间前缀，所有存入的键名都会自动添加此前缀 */
+    private prefix;
+    /**
+     * 初始化适配器
+     * @param prefix - 可选的命名空间前缀（如 'chatbi'），默认为空字符串
+     */
+    constructor(prefix?: string);
+    /**
+     * 内部方法：计算实际存储的键名
+     * @param key - 业务层传入的原始键名
+     * @returns 拼接前缀后的物理键名
+     */
+    private getKey;
+    /**
+     * 内部方法：从物理键名还原业务键名
+     * @param namespacedKey - 物理存储中的完整键名
+     * @returns 还原后的原始键名，若前缀不匹配则返回 null
+     */
+    private getOriginalKey;
+    /**
+     * 读取存储项
+     * @param key - 原始键名
+     * @returns 存储的字符串内容，不存在则返回 null
+     */
+    getItem(key: string): string | null;
+    /**
+     * 写入存储项
+     * @param key - 原始键名
+     * @param value - 待存储的字符串值
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * 移除特定的存储项
+     * @param key - 原始键名
+     */
+    removeItem(key: string): void;
+    /**
+     * 清空存储空间
+     * @description
+     * - 若定义了前缀：仅删除以该前缀开头的键名，不影响其他数据。
+     * - 若未定义前缀：调用原生 `localStorage.clear()` 清空所有数据。
+     */
+    clear(): void;
+    /**
+     * 返回当前命名空间下的存储项总数
+     */
+    get length(): number;
+    /**
+     * 根据索引获取对应的原始键名
+     * @param index - 索引位置
+     * @returns 对应的业务键名，不存在则返回 null
+     */
+    key(index: number): string | null;
+}
+
+/**
+ * 作用域存储适配器 (ScopedStorageAdapter)
+ * @description 采用装饰器模式实现。它包装一个现有的 `StoragePort` 实例，
+ * 并为所有存储操作透明地注入一个前缀（命名空间），从而实现逻辑上的存储隔离。
+ * 常用于为插件分配独立的存储空间，而无需修改插件代码。
+ */
+declare class ScopedStorageAdapter implements StoragePort {
+    private underlyingStorage;
+    private prefix;
+    /**
+     * 初始化作用域适配器
+     * @param underlyingStorage - 被装饰的底层存储适配器实例
+     * @param prefix - 用于隔离的作用域前缀字符串
+     */
+    constructor(underlyingStorage: StoragePort, prefix: string);
+    /**
+     * 内部方法：计算实际存储的键名
+     * @param key - 业务层传入的原始键名
+     * @returns 拼接前缀后的物理键名
+     */
+    private getKey;
+    /**
+     * 内部方法：从物理键名还原业务键名
+     * @param namespacedKey - 物理存储中的完整键名
+     * @returns 还原后的原始键名，若前缀不匹配则返回 null
+     */
+    private getOriginalKey;
+    /**
+     * 读取当前作用域下的存储项
+     * @param key - 原始键名
+     * @returns 字符串内容，不存在则返回 null
+     */
+    getItem(key: string): string | null;
+    /**
+     * 写入当前作用域下的存储项
+     * @param key - 原始键名
+     * @param value - 字符串内容
+     */
+    setItem(key: string, value: string): void;
+    /**
+     * 移除当前作用域下的特定存储项
+     * @param key - 原始键名
+     */
+    removeItem(key: string): void;
+    /**
+     * 清空当前作用域下的所有存储项
+     * @description 仅删除匹配当前前缀的键值对，不会影响底层存储中的其他数据。
+     */
+    clear(): void;
+    /**
+     * 返回当前作用域下的存储项总数
+     */
+    get length(): number;
+    /**
+     * 根据索引获取当前作用域下的原始键名
+     * @param index - 索引位置
+     * @returns 对应的业务键名，不存在则返回 null
+     */
+    key(index: number): string | null;
+}
+
+interface PluginProviderProps {
+    manager: PluginManager;
+    children: React.ReactNode;
+}
+declare const PluginProvider: React.FC<PluginProviderProps>;
+declare const usePluginManager: () => PluginManager;
+
+/**
+ * ProxySandbox 类
+ * @description 基于 Proxy 的 JS 沙箱实现，模拟独立的 Window 环境
+ */
+declare class ProxySandbox {
+    /** 沙箱名称 */
+    name: string;
+    /** 代理后的 Window 对象 */
+    proxy: WindowProxy;
+    /** 沙箱是否激活 */
+    running: boolean;
+    /** 记录新增/修改的全局变量 */
+    private updatedValueSet;
+    /** 绑定函数的缓存池，避免重复 bind 带来的性能开销 */
+    private boundFunctionCache;
+    /** 副作用记录池 */
+    private effectPool;
+    /** 真实的 Window 对象 */
+    private globalContext;
+    /** 白名单全局变量（允许透传访问真实 Window） */
+    private static globalWhitelist;
+    constructor(name: string, globalContext?: Window & typeof globalThis);
+    /**
+     * 激活沙箱
+     */
+    active(): void;
+    /**
+     * 销毁沙箱
+     */
+    inactive(): void;
+    /**
+     * 在沙箱中执行代码
+     * @param code JS 代码字符串
+     * @returns 执行结果
+     */
+    eval(code: string): any;
+    /**
+     * 创建伪造的 Window 对象
+     */
+    private createFakeWindow;
+    private isConstructor;
+    private isNativeFunction;
+    /**
+     * 劫持全局副作用 API
+     */
+    private patchGlobalEffects;
+}
+
+/**
+ * 日志等级枚举
+ */
+declare enum LogLevel {
+    /** 调试级别：输出最详尽的信息 */
+    DEBUG = 0,
+    /** 信息级别：输出重要的运行状态 */
+    INFO = 1,
+    /** 警告级别：输出潜在的问题，但不影响运行 */
+    WARN = 2,
+    /** 错误级别：输出严重的运行异常 */
+    ERROR = 3,
+    /** 禁用日志：不输出任何信息 */
+    NONE = 4
+}
+/**
+ * 日志工具类
+ * @description 核心工具类，提供统一的日志输出格式 `[Prefix] Message`。
+ * 支持通过 `LogLevel` 进行全局过滤。
+ * 支持日志缓冲和自动分组，以减少控制台噪音。
+ * 支持浏览器端 CSS 样式和 Node.js 端 ANSI 颜色。
+ */
+declare class Logger {
+    /** 全局静态日志等级，所有实例共享 */
+    private static level;
+    /** 日志缓冲区 */
+    private static buffer;
+    /** 缓冲输出防抖定时器 */
+    private static flushTimer;
+    /** 缓冲时间窗口 (ms) */
+    private static FLUSH_INTERVAL;
+    /** 是否启用缓冲模式 */
+    private static bufferEnabled;
+    /** 是否为浏览器环境 */
+    private static isBrowser;
+    /** 当前实例的业务模块前缀 */
+    private prefix;
+    /** 实例特定的颜色 */
+    private color;
+    /**
+     * 构造函数
+     * @param prefix - 业务模块前缀，默认为 'App'
+     */
+    constructor(prefix?: string);
+    /**
+     * 静态方法：设置全局日志输出等级
+     * @param level - 目标日志等级
+     */
+    static setLevel(level: LogLevel): void;
+    /**
+     * 静态方法：启用或禁用日志缓冲
+     * @param enabled - 是否启用
+     */
+    static setBufferEnabled(enabled: boolean): void;
+    /**
+     * 静态方法：获取当前全局日志等级
+     * @returns 当前生效的全局日志等级
+     */
+    static getLevel(): LogLevel;
+    /**
+     * 格式化输出前缀
+     */
+    private getFormattedPrefix;
+    /**
+     * 生成分组标题参数
+     */
+    private static getGroupTitleArgs;
+    /**
+     * 内部方法：将日志推入缓冲区或直接输出
+     */
+    private log;
+    /**
+     * 静态方法：刷新缓冲区，分组输出日志
+     */
+    static flush(): void;
+    /**
+     * 打印 DEBUG 级别日志
+     */
+    debug(...args: any[]): void;
+    /**
+     * 打印 INFO 级别日志
+     */
+    info(...args: any[]): void;
+    /**
+     * 打印 WARN 级别日志
+     */
+    warn(...args: any[]): void;
+    /**
+     * 打印 ERROR 级别日志
+     */
+    error(...args: any[]): void;
+    /**
+     * 开始一个日志控制台分组
+     */
+    group(label: string, collapsed?: boolean): void;
+    /**
+     * 结束当前日志控制台分组
+     */
+    groupEnd(): void;
+}
+/** 默认 Logger 实例 */
+declare const logger: Logger;
+/**
+ * 创建带特定前缀的 Logger 实例
+ * @param prefix 日志前缀
+ * @returns Logger 实例
+ */
+declare const createLogger: (prefix: string) => Logger;
+
+/**
+ * 日期时间格式化工具类
+ */
+declare const dateUtils: {
+    /**
+     * 格式化日期为 YYYY-MM-DD
+     */
+    formatDate(date?: dayjs.ConfigType): string;
+    /**
+     * 格式化时间为 HH:mm:ss
+     */
+    formatTime(date?: dayjs.ConfigType): string;
+    /**
+     * 格式化日期时间为 YYYY-MM-DD HH:mm:ss
+     */
+    formatDateTime(date?: dayjs.ConfigType): string;
+    /**
+     * 获取当前时间戳（毫秒）
+     */
+    now(): number;
+    /**
+     * 获取相对时间（例如：几分钟前）
+     */
+    fromNow(date: dayjs.ConfigType): string;
+    /**
+     * 原始 dayjs 对象，用于更复杂的场景
+     */
+    dayjs: typeof dayjs;
+};
+
+type KeepStrategy = 'first' | 'last' | 'search' | 'hash';
+/**
+ * 把当前地址中所有出现的参数合并成一份。
+ * 重复 key 的处理策略：
+ *  - 'first'  : 按出现顺序，第一次的值生效
+ *  - 'last'   : 按出现顺序，最后一次的值生效（默认，最直观）
+ *  - 'search' : 只要 search 里出现过，就用 search 的
+ *  - 'hash'   : 只要 hash 里出现过，就用 hash 的
+ */
+declare function normalizeParams(strategy?: KeepStrategy): URLSearchParams;
+/**
+ * 清除 URL 中的特定参数并返回新的 URL
+ * @description 同时处理 search 和 hash 中的参数
+ */
+declare function cleanUrlParams(keysToRemove: string[]): string;
+
+declare const version = "1.0.0";
+
+/**
+ * Hook 配置选项
+ */
+interface UseStorageStateOptions<T> {
+    defaultValue?: T;
+    scope?: 'plugin' | 'shared';
+}
+/**
+ * 统一存储状态 Hook
+ * @description 提供与 StorageManager 和 Schema Registry 集成的持久化状态 Hook。
+ * @param pluginId 定义该 Key 的插件 ID
+ * @param key 存储键名 (必须在 Schema 中注册)
+ * @param options 配置项，包含默认值和作用域
+ */
+declare function useStorageState<T>(pluginId: string, key: string, options?: UseStorageStateOptions<T>): [T, (value: T | ((val: T) => T)) => void];
+
+/** 插件加载 Hook 的配置选项 */
+interface PluginLoaderOptions {
+    /** 插件发现规则，定义如何从模块列表中识别插件 */
+    discoveryRules?: any[];
+    /** 插件模块映射，通常由 Vite 的 `import.meta.glob` 生成，键为路径，值为加载函数 */
+    modules?: Record<string, () => Promise<any>>;
+    /** 预注册的插件注册表，用于手动指定插件加载逻辑，优先级高于自动发现 */
+    registry?: Record<string, () => Promise<any>>;
+    /** 插件的业务配置映射，键为插件 ID */
+    pluginConfigs: Record<string, any>;
+    /** 初始化的共享上下文服务，将注入到每个插件的 onLoad 中 */
+    sharedContext?: Record<string, any>;
+    /** 系统级全局配置，如标题、版本号、Logo 等 */
+    systemConfig?: Record<string, any>;
+    /** 资源发现的基础 URL，默认为当前 window.location.origin */
+    baseUrl?: string;
+}
+/**
+ * 核心 Hook：通用插件加载器
+ * @description 负责应用启动时的插件全生命周期管理：
+ * 1. 自动发现：解析 modules 并根据规则识别插件。
+ * 2. 注册：将插件信息录入 PluginManager。
+ * 3. 加载：调用插件的加载逻辑 (onLoad)。
+ * 4. 初始化：调用插件的挂载逻辑 (onMount)。
+ * 5. 响应式更新：订阅插件状态变更并触发 UI 刷新。
+ *
+ * @param options - 加载配置项
+ * @returns { pluginsLoaded: boolean, pluginVersion: number }
+ * - pluginsLoaded: 插件是否已全部完成初始化
+ * - pluginVersion: 插件状态版本号，用于强制触发依赖插件状态的组件重渲染
+ */
+declare const usePluginLoader: (options: PluginLoaderOptions) => {
+    pluginsLoaded: boolean;
+    pluginVersion: number;
+};
+
+export { type ApiAdapter, type ApiConfig, type ApiEndpointConfig, ApiEngine, type ApiInterceptor, ApiProvider, type ApiProviderProps, type ApiRequestConfig, type ApiResponseContext, AvatarSkeleton, AxiosAdapter, BasePlugin, type BaseResponse, BlockSkeleton, ConfigManager, DefaultEventBus, type DiscoveryRule, type ErrorStrategy, type EventBus, type EventBusPort, type EventCallback, type HttpMethod, LocalStorageAdapter, LogLevel, Logger, PLUGIN_TYPES, type Plugin, type PluginCapabilities, type PluginConfigItem, type PluginContext, PluginErrorBoundary, type PluginExtension, type PluginLifecycle, type PluginLoaderOptions, PluginManager, type PluginMetadata, PluginProvider, type PluginProviderProps, type PluginRegistry, PluginRuntime, PluginSandbox, PluginSlot, type PluginStorage, type PluginType, ProxySandbox, type RequestOptions, type RouteConfig, SUCCESS_CODE, type Scene, ScopedStorageAdapter, ServiceRegistry, SidebarIconSkeleton, Slot, type SlotPosition, SlotSkeletons, type SlotType, StatusBarItemSkeleton, type StorageItemSchema, StorageManager, type StoragePort, type StreamCallbacks, type TypedStorage, type UseStorageStateOptions, apiEngine, cleanUrlParams, configManager, createLogger, dateUtils, definePlugin, isMockMode, logger, normalizeParams, pluginManager, resolveApiModules, resolvePluginRegistry, serviceRegistry, useApi, usePluginLoader, usePluginManager, useStorageState, version };