@chatbi-v/core 2.0.4 → 2.1.0

package/dist/domain/plugin-manager.d.ts

@@ -9,111 +9,167 @@ import { StoragePort } from '../ports/storage-port';
 import { StorageManager } from './storage-manager';
 /**
  * 插件管理器
- * @description 负责插件的加载、注册和生命周期管理
+ * @description 核心领域服务，负责插件的完整生命周期管理，包括扫描、注册、配置合并、状态切换及依赖解析。
  */
 export 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 监听函数
-     * @returns 取消订阅函数
+     * 订阅插件状态的变更通知
+     * @param listener - 变更时的回调函数
+     * @param slot - (可选) 指定监听的插槽位置，若提供则仅在该插槽受影响时通知
+     * @returns 取消订阅的函数
+     */
+    subscribe(listener: () => void, slot?: SlotPosition | string): () => void;
+    /**
+     * 获取存储管理器实例
+     * @returns StorageManager 实例
      */
-    subscribe(listener: () => void): () => void;
     getStorageManager(): StorageManager;
     /**
      * 触发状态变更通知
+     * @param affectedSlot - (可选) 受影响的插槽位置
      */
     private notify;
     /**
-     * 获取所有已注册的插件
+     * 获取所有已注册的插件列表
+     * @description 结果会根据插件类型优先级和用户自定义排序进行排序
+     * @returns 排序后的插件数组
      */
     getPlugins(): Plugin[];
     /**
-     * 获取插件状态
-     * @param pluginId 插件 ID
+     * 获取指定插件的状态信息
+     * @param pluginId - 插件 ID
+     * @returns 包含启用状态和排序值的对象
      */
     getPluginState(pluginId: string): {
         enabled: boolean;
         order: number;
     };
     /**
-     * 检查插件是否启用
-     * @param pluginId 插件 ID
+     * 检查指定插件是否处于启用状态
+     * @param pluginId - 插件 ID
+     * @returns 是否启用
      */
     isPluginEnabled(pluginId: string): boolean;
     /**
-     * 切换插件启用状态
-     * @param pluginId 插件 ID
-     * @param enabled 是否启用
+     * 切换插件的启用/禁用状态
+     * @description 禁用插件会立即触发其卸载生命周期并销毁运行时。
+     * @param pluginId - 插件 ID
+     * @param enabled - 目标状态
      */
     togglePlugin(pluginId: string, enabled: boolean): void;
     /**
-     * 设置插件排序
-     * @param pluginId 插件 ID
-     * @param order 排序值
+     * 设置插件的显示排序权重
+     * @param pluginId - 插件 ID
+     * @param order - 排序权重值
      */
     setPluginOrder(pluginId: string, order: number): void;
     /**
-     * 获取插件的统一能力描述
-     * @param pluginId 插件 ID
+     * 获取指定插件的运行时状态
+     * @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): import("..").PluginCapabilities;
     /**
-     * 更新插件配置
-     * @param pluginId 插件 ID
-     * @param key 配置项 Key
-     * @param value 配置值
+     * 更新指定插件的某项配置
+     * @description 该操作会同步更新内存中的配置、持久化到存储并触发全局事件通知。
+     * @param pluginId - 插件 ID
+     * @param key - 配置键名
+     * @param value - 新的配置值
      */
     updatePluginConfig(pluginId: string, key: string, value: any): void;
     /**
-     * 获取插件配置
-     * @param pluginId 插件 ID
-     * @param key 配置键
+     * 获取指定插件的某项配置值
+     * @param pluginId - 插件 ID
+     * @param key - 配置键名
      * @returns 配置值
      */
     getPluginConfig(pluginId: string, key: string): any;
     /**
-     * 获取系统全局配置 (非插件特定配置)
-     * @param key 配置键 (如 title, version)
+     * 获取系统全局配置 (非插件特定)
+     * @param key - 系统配置键名
+     * @returns 配置值
      */
     getSystemConfig(key: string): any;
     /**
-     * 获取注册的服务
-     * @param name 服务名称
+     * 获取由插件注册的服务实例
+     * @template T 服务接口类型
+     * @param name - 服务注册名称
+     * @returns 服务实例或 undefined
      */
     getService<T = any>(name: string): T | undefined;
     /**
-     * 获取指定插槽的扩展
-     * @param slot 插槽位置
+     * 获取指定插槽位置的所有已启用插件的扩展
+     * @param slot - 插槽位置标识
+     * @returns 排序后的扩展配置数组
      */
     getExtensions(slot: SlotPosition | string): PluginExtension[];
+    /**
+     * 获取所有已启用插件注册的路由配置
+     * @returns 增强后的路由配置数组
+     */
     getRoutes(): RouteConfig[];
     /**
-     * 注册插件
-     * @param plugin 插件实例
-     * @param notify 是否触发状态变更通知
+     * 注册一个新插件到管理器中
+     * @description 此阶段会执行元数据校验、存储 Schema 注册、配置合并及扩展点收集。
+     * @param plugin - 插件对象
+     * @param notify - 是否在注册完成后触发状态变更通知
      */
     register(plugin: Plugin, notify?: boolean): void;
     /**

package/dist/domain/plugin-runtime.d.ts

@@ -6,34 +6,65 @@
 import { Plugin, PluginContext } from '../ports/plugin-port';
 import { StorageManager } from './storage-manager';
 /**
- * 插件运行时
- * @description 封装单个插件的生命周期、沙箱和状态
+ * 插件运行时类
+ * @description 为单个插件提供独立的运行环境，负责管理其生命周期、初始化沙箱环境并组装上下文对象。
  */
 export 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 注册服务、初始化非 UI 逻辑
+     * 执行插件的加载逻辑 (onLoad)
+     * @description 此阶段会自动注册插件声明的 API 配置，并调用插件的 onLoad 钩子。
+     * 用于执行非 UI 的初始化逻辑，如注册服务、拦截器等。
      */
     load(): Promise<void>;
     /**
-     * 挂载插件 (onMount)
-     * @description 激活沙箱、处理 UI 相关的副作用
+     * 执行插件的挂载逻辑 (onMount)
+     * @description 此阶段会激活 Window 沙箱并调用插件的 onMount 钩子。
+     * 此时插件的 UI 组件（如有）即将或已经进入 DOM。
      */
     mount(): Promise<void>;
     /**
-     * 卸载插件 (onUnmount)
+     * 执行插件的卸载逻辑 (onUnmount)
+     * @description 调用插件的 onUnmount 钩子并停用沙箱。
      */
     unmount(): Promise<void>;
     /**
-     * 销毁插件 (完全移除)
+     * 彻底销毁插件实例
+     * @description 卸载插件并重置加载状态。
      */
     destroy(): Promise<void>;
-    get status(): "mounted" | "loaded" | "initial";
+    /**
+     * 设置运行时错误 (内部使用)
+     * @internal
+     */
+    _setError(error: Error | null): void;
+    /**
+     * 获取插件运行时错误
+     */
+    getError(): Error | null;
+    /**
+     * 获取插件当前运行状态
+     * @returns 'error' | 'mounted' | 'loaded' | 'initial'
+     */
+    get status(): "error" | "mounted" | "loaded" | "initial";
 }

package/dist/domain/plugin-sandbox.d.ts

@@ -1,14 +1,26 @@
 import { StorageManager } from './storage-manager';
 /**
- * 插件沙箱
- * @description 为插件提供隔离的运行时环境
+ * 插件隔离沙箱
+ * @description 核心领域服务，为每个插件实例创建独立的运行上下文。
+ * 它是插件与系统核心之间的“中间层”，确保插件只能访问其权限范围内的资源。
+ * 主要职责：
+ * 1. 存储隔离：确保插件只能读写属于自己的 LocalStorage 命名空间。
+ * 2. 日志隔离：为插件提供带有自身 ID 前缀的日志输出，方便调试。
  */
 export declare class PluginSandbox {
+    /** 关联的插件唯一标识 */
     private pluginId;
+    /** 系统全局存储管理器 */
     private storageManager;
+    /**
+     * 构造插件沙箱
+     * @param pluginId - 插件 ID
+     * @param storageManager - 系统存储管理器实例
+     */
     constructor(pluginId: string, storageManager: StorageManager);
     /**
      * 获取隔离的存储接口
+     * @description 返回一个受限的 StoragePort，所有操作都会自动带上插件 ID 前缀。
      */
     get storage(): {
         shared: {
@@ -22,6 +34,7 @@ export declare class PluginSandbox {
     };
     /**
      * 获取隔离的日志接口
+     * @description 返回一个带插件 ID 前缀的 Logger 实例。
      */
     get logger(): import("..").Logger;
 }

package/dist/domain/storage-manager.d.ts

@@ -1,37 +1,65 @@
 import { StorageItemSchema } from '../ports/plugin-port';
 import { StoragePort } from '../ports/storage-port';
 /**
- * 存储管理器
- * @description 统一管理系统、插件和共享存储
+ * 核心领域服务：存储管理器
+ * @description 统一管理应用内所有的持久化存储资源。
+ * 核心功能：
+ * 1. 作用域隔离：通过前缀划分 `plugin`、`shared` 和 `system` 三个层级的存储空间。
+ * 2. Schema 校验：支持注册存储描述，规范数据存取，避免键名冲突。
+ * 3. 默认值与配置回退：支持从 Schema 默认值或 ConfigManager 中回退取值。
  */
 export declare class StorageManager {
+    /** 底层物理存储驱动 */
     private baseStorage;
+    /** 插件 ID 与存储描述定义的映射关系 */
     private schemas;
+    /** 内存缓存，减少 JSON 序列化和物理 IO 开销 */
+    private memoryCache;
+    /**
+     * 初始化存储管理器
+     * @param baseStorage - 符合 StoragePort 接口的物理存储驱动（如 LocalStorageAdapter）
+     */
     constructor(baseStorage: StoragePort);
     /**
-     * 注册插件存储 Schema
+     * 注册插件的存储 Schema
+     * @param pluginId - 插件 ID
+     * @param schema - 存储项定义列表
      */
     registerSchema(pluginId: string, schema: StorageItemSchema[]): void;
     /**
-     * 验证 Key 是否符合 Schema 定义 (仅在开发环境或严格模式下警告)
+     * 内部校验方法：检查键名是否在 Schema 中声明
+     * @param pluginId - 插件 ID
+     * @param key - 待校验的键名
+     * @param scope - 目标作用域
      */
     private validateKey;
     /**
-     * 获取插件专用存储适配器
-     * @param pluginId 插件 ID
+     * 获取插件私有存储适配器
+     * @param pluginId - 插件 ID
+     * @returns 自动添加 `plugin:{id}:` 前缀的存储接口
      */
     getPluginStorage(pluginId: string): StoragePort;
     /**
-     * 获取共享存储适配器
+     * 获取全局共享存储适配器
+     * @returns 自动添加 `shared:` 前缀的存储接口
      */
     getSharedStorage(): StoragePort;
     /**
-     * 获取系统存储适配器
+     * 获取系统内部存储适配器
+     * @returns 自动添加 `system:` 前缀的存储接口
      */
     getSystemStorage(): StoragePort;
     /**
-     * 获取插件上下文中的 storage 对象 (包含类型转换辅助方法)
-     * @param pluginId 插件 ID
+     * 创建插件沙箱使用的复合存储对象
+     * @description 返回的对象封装了对私有存储和共享存储的操作。
+     * 特性：
+     * - 内存级 LRU 缓存：极大提升高频读写性能。
+     * - 自动序列化/反序列化 JSON。
+     * - 自动校验 Schema。
+     * - 取值回退逻辑：持久化存储 -> ConfigManager -> Schema 默认值。
+     *
+     * @param pluginId - 插件 ID
+     * @returns 包含 get/set/remove 及 shared 子对象的复合接口
      */
     getContextStorage(pluginId: string): {
         shared: {

package/dist/hooks/use-plugin-loader.d.ts

@@ -1,22 +1,33 @@
+/** 插件加载 Hook 的配置选项 */
 export interface PluginLoaderOptions {
-    /** 插件发现规则 */
+    /** 插件发现规则，定义如何从模块列表中识别插件 */
     discoveryRules?: any[];
-    /** 插件模块映射 (由 Vite import.meta.glob 生成) */
+    /** 插件模块映射，通常由 Vite 的 `import.meta.glob` 生成，键为路径，值为加载函数 */
     modules?: Record<string, () => Promise<any>>;
-    /** 预注册的插件注册表 (可选，用于离线或手动加载) */
+    /** 预注册的插件注册表，用于手动指定插件加载逻辑，优先级高于自动发现 */
     registry?: Record<string, () => Promise<any>>;
-    /** 插件配置映射 */
+    /** 插件的业务配置映射，键为插件 ID */
     pluginConfigs: Record<string, any>;
-    /** 初始化的上下文服务 (如 api, events 等) */
+    /** 初始化的共享上下文服务，将注入到每个插件的 onLoad 中 */
     sharedContext?: Record<string, any>;
-    /** 系统级配置 (title, version 等) */
+    /** 系统级全局配置，如标题、版本号、Logo 等 */
     systemConfig?: Record<string, any>;
-    /** 发现的基础 URL */
+    /** 资源发现的基础 URL，默认为当前 window.location.origin */
     baseUrl?: string;
 }
 /**
- * 通用插件加载 Hook
- * @description 负责插件的自动发现、加载、初始化和状态订阅
+ * 核心 Hook：通用插件加载器
+ * @description 负责应用启动时的插件全生命周期管理：
+ * 1. 自动发现：解析 modules 并根据规则识别插件。
+ * 2. 注册：将插件信息录入 PluginManager。
+ * 3. 加载：调用插件的加载逻辑 (onLoad)。
+ * 4. 初始化：调用插件的挂载逻辑 (onMount)。
+ * 5. 响应式更新：订阅插件状态变更并触发 UI 刷新。
+ *
+ * @param options - 加载配置项
+ * @returns { pluginsLoaded: boolean, pluginVersion: number }
+ * - pluginsLoaded: 插件是否已全部完成初始化
+ * - pluginVersion: 插件状态版本号，用于强制触发依赖插件状态的组件重渲染
  */
 export declare const usePluginLoader: (options: PluginLoaderOptions) => {
     pluginsLoaded: boolean;