@chatbi-v/core 2.0.4 → 2.0.5

package/dist/ports/event-bus-port.d.ts

@@ -1,30 +1,32 @@
 /**
  * 事件总线端口接口
+ * @description 定义应用内部事件通信的标准契约，支持发布订阅模式。
  */
 export interface EventBusPort {
     /**
      * 订阅事件
-     * @param event 事件名称
-     * @param callback 回调函数
-     * @returns 取消订阅函数
+     * @param event - 事件名称
+     * @param callback - 事件触发时的回调函数
+     * @returns 取消订阅的函数
      */
     on(event: string, callback: (...args: any[]) => any): () => void;
     /**
-     * 取消订阅
-     * @param event 事件名称
-     * @param callback 回调函数
+     * 取消订阅事件
+     * @param event - 事件名称
+     * @param callback - 之前注册的回调函数
      */
     off(event: string, callback: (...args: any[]) => any): void;
     /**
-     * 触发事件
-     * @param event 事件名称
-     * @param args 事件参数
+     * 触发事件 (发布)
+     * @param event - 事件名称
+     * @param args - 传递给回调函数的参数列表
      */
     emit(event: string, ...args: any[]): void;
     /**
      * 订阅一次性事件
-     * @param event 事件名称
-     * @param callback 回调函数
+     * @description 事件触发一次后会自动取消订阅
+     * @param event - 事件名称
+     * @param callback - 事件触发时的回调函数
      */
     once(event: string, callback: (...args: any[]) => any): void;
 }

package/dist/ports/plugin-port.d.ts

@@ -34,34 +34,55 @@ export declare const Slot: {
 export type SlotType = typeof Slot[keyof typeof Slot];
 export type SlotPosition = SlotType | string;
 /**
- * 插件扩展 (插槽)
+ * 插件扩展 (插槽注入配置)
  */
 export interface PluginExtension {
+    /** 插槽位置标识符 */
     slot: SlotPosition;
+    /** 要注入的 React 组件 */
     component: React.ComponentType<any>;
+    /** 排序权重，数值越小越靠前 */
     order?: number;
-    /** @internal 插件 ID，由系统自动注入 */
+    /** @internal 插件 ID，由系统在加载时自动注入，用于溯源 */
     _pluginId?: string;
+    /** 扩展的元数据信息 */
     meta?: {
+        /** 显示图标 */
         icon?: React.ReactNode;
+        /** 显示标签文本 */
         label?: string;
+        /** 详细描述 */
         description?: string;
+        /** 唯一标识符，用于某些特定插槽的索引 */
         key?: string;
+        /** 允许其他自定义属性 */
         [key: string]: any;
     };
 }
+/**
+ * 插件配置项定义
+ */
 export 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;
 }
 /**
@@ -91,81 +112,122 @@ export interface PluginCapabilities {
     background?: boolean;
     [key: string]: boolean | undefined;
 }
+/**
+ * 存储项数据结构定义 (Schema)
+ */
 export interface StorageItemSchema {
+    /** 存储键名 */
     key: string;
+    /** 数据类型 */
     type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** 默认值 */
     default?: any;
+    /** 描述信息 */
     description?: string;
+    /**
+     * 作用域
+     * @description 'plugin' 表示仅当前插件可见（带插件 ID 前缀），'shared' 表示全局共享
+     */
     scope?: 'plugin' | 'shared';
 }
 /**
  * 插件生命周期 Hooks
+ * @description 插件可以在不同的生命周期阶段执行特定的逻辑
  */
 export interface PluginLifecycle {
     /**
      * 插件加载时调用
-     * @description 用于初始化内部状态、注册服务等。此时 UI 尚未挂载。
+     * @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 传递给插件生命周期钩子的对象，提供核心能力的访问
+ * @description 传递给插件生命周期钩子的核心对象，是插件访问宿主环境能力的唯一入口。
  */
 export interface PluginContext {
+    /** 当前插件的唯一标识符 */
     pluginId: string;
+    /** API 请求能力入口 */
     api: any;
+    /** 事件总线能力入口 */
     events: EventBusPort;
+    /** 存储管理能力入口 */
     storage: {
+        /** 获取插件私有存储数据 */
         get: <T = any>(key: string) => T | null;
+        /** 设置插件私有存储数据 */
         set: <T = any>(key: string, value: T) => void;
+        /** 移除插件私有存储数据 */
         remove: (key: string) => void;
+        /** 全局共享存储访问 */
         shared: {
+            /** 获取全局共享存储数据 */
             get: <T = any>(key: string) => T | null;
+            /** 设置全局共享存储数据 */
             set: <T = any>(key: string, value: T) => void;
+            /** 移除全局共享存储数据 */
             remove: (key: string) => void;
         };
     };
+    /** 日志输出工具，自动携带插件 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 的代理对象 (用于沙箱隔离) */
     window: WindowProxy;
 }
 /**
- * 完整的插件接口定义
+ * 完整的插件对象定义
  */
 export interface Plugin extends PluginLifecycle {
     /**
-     * 插件 ID
-     * @description 必须与 metadata.id 一致，且定义为只读（通常通过 getter 实现）
+     * 插件唯一标识符
+     * @description 必须与 metadata.id 一致，通常为只读。
      */
     readonly id: string;
+    /** 插件元数据配置 */
     metadata: PluginMetadata;
-    /** 插件提供的组件（可选） */
+    /** 插件提供的功能组件集合 (可选) */
     components?: Record<string, React.ComponentType<any>>;
-    /** 插件提供的工具函数（可选） */
+    /** 插件提供的工具函数集合 (可选) */
     utils?: Record<string, any>;
-    /** 默认配置（可选） */
+    /** 插件的初始默认配置 (可选) */
     defaultConfig?: Record<string, any>;
 }
 /**
@@ -192,36 +254,49 @@ export declare abstract class BasePlugin implements Plugin {
  * @returns 完整的插件对象
  */
 export declare function definePlugin(plugin: Omit<Plugin, 'id'>): Plugin;
+/**
+ * 插件元数据定义
+ * @description 描述插件的静态属性，用于插件市场展示、权限校验和内核加载参考。
+ */
 export 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 接口配置 */
     api?: ApiConfig;
-    /** 插件能力声明 */
+    /** 插件行为能力声明 */
     capabilities?: PluginCapabilities;
-    /** 插件配置定义 */
+    /** 插件的可配置项定义 */
     configuration?: PluginConfigItem[];
-    /** 存储定义（Schema） */
+    /** 插件所需的存储结构定义 */
     storage?: StorageItemSchema[];
     /**
-     * 系统状态绑定
-     * @description 将插件配置自动同步到系统 UI 状态
+     * 系统状态自动绑定
+     * @description 将插件的配置项自动同步到系统的全局状态中 (如主题色、身份认证等)
      */
     systemStateBindings?: {
+        /** 插件配置中的键名 */
         configKey: string;
+        /** 系统全局状态中的键名 */
         stateKey: string;
-        /** 预设转换逻辑: 'theme-mode' | 'identity' 等 */
+        /** 预设的转换逻辑名称 */
         transform?: 'theme-mode' | 'identity';
     }[];
 }

package/dist/ports/storage-port.d.ts

@@ -1,19 +1,37 @@
 /**
  * 存储端口接口
- * @description 定义数据持久化的契约
+ * @description 定义数据持久化的标准契约，兼容 Web Storage API。
  */
 export 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;
     /**
-     * 返回存储中第 n 个键的名称。
-     * @param index 一个整数，表示要获取名称的键的编号。
+     * 根据索引返回存储中对应键的名称
+     * @param index - 数值索引
+     * @returns 键名，如果索引超出范围则返回 null
      */
     key(index: number): string | null;
 }

package/dist/utils/logger.d.ts

@@ -2,60 +2,70 @@
  * 日志等级枚举
  */
 export declare enum LogLevel {
+    /** 调试级别：输出最详尽的信息 */
     DEBUG = 0,
+    /** 信息级别：输出重要的运行状态 */
     INFO = 1,
+    /** 警告级别：输出潜在的问题，但不影响运行 */
     WARN = 2,
+    /** 错误级别：输出严重的运行异常 */
     ERROR = 3,
+    /** 禁用日志：不输出任何信息 */
     NONE = 4
 }
 /**
  * 日志工具类
- * @description 支持日志等级控制和统一前缀格式，方便治理和排查问题
+ * @description 核心工具类，提供统一的日志输出格式 `[Prefix] Message`。
+ * 支持通过 `LogLevel` 进行全局过滤，在生产环境下建议设置为 WARN 或以上。
  */
 export declare class Logger {
-    /** 全局默认日志等级 */
+    /** 全局静态日志等级，所有实例共享 */
     private static level;
-    /** 当前实例的前缀 */
+    /** 当前实例的业务模块前缀 */
     private prefix;
     /**
      * 构造函数
-     * @param prefix 日志前缀，默认为 'App'
+     * @param prefix - 业务模块前缀，默认为 'App'
      */
     constructor(prefix?: string);
     /**
-     * 设置全局日志等级
-     * @param level 日志等级
+     * 静态方法：设置全局日志输出等级
+     * @param level - 目标日志等级
      */
     static setLevel(level: LogLevel): void;
     /**
-     * 获取当前日志等级
-     * @returns 当前全局日志等级
+     * 静态方法：获取当前全局日志等级
+     * @returns 当前生效的全局日志等级
      */
     static getLevel(): LogLevel;
     /**
      * 打印 DEBUG 级别日志
+     * @description 仅在 LogLevel <= DEBUG 时输出
      */
     get debug(): (...args: any[]) => void;
     /**
      * 打印 INFO 级别日志
+     * @description 仅在 LogLevel <= INFO 时输出
      */
     get info(): (...args: any[]) => void;
     /**
      * 打印 WARN 级别日志
+     * @description 仅在 LogLevel <= WARN 时输出
      */
     get warn(): (...args: any[]) => void;
     /**
      * 打印 ERROR 级别日志
+     * @description 仅在 LogLevel <= ERROR 时输出
      */
     get error(): (...args: any[]) => void;
     /**
-     * 开始一个日志分组
-     * @param label 分组标签
-     * @param collapsed 是否默认折叠，默认为 false
+     * 开始一个日志控制台分组
+     * @param label - 分组显示的标签名
+     * @param collapsed - 是否默认折叠显示，默认为 false
      */
     group(label: string, collapsed?: boolean): void;
     /**
-     * 结束当前日志分组
+     * 结束当前日志控制台分组
      */
     get groupEnd(): () => void;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chatbi-v/core",
-  "version": "2.0.4",
+  "version": "2.0.5",
   "main": "dist/index.cjs",
   "files": [
     "dist"
@@ -26,10 +26,12 @@
   },
   "peerDependencies": {},
   "devDependencies": {
+    "@types/react": "^18.3.1",
+    "@types/react-dom": "^18.3.0",
     "tsup": "^8.5.1",
     "vite": "^5.4.21",
-    "@chatbi-v/tsconfig": "2.0.4",
-    "@chatbi-v/cli": "2.0.4"
+    "@chatbi-v/cli": "2.0.5",
+    "@chatbi-v/tsconfig": "2.0.5"
   },
   "scripts": {
     "build": "chatbi-cli build",