@chatbi-v/core 2.0.4 → 2.0.5

package/dist/adapters/local-storage-adapter.d.ts

@@ -1,13 +1,61 @@
 import { StoragePort } from '../ports/storage-port';
+/**
+ * 浏览器本地存储 (LocalStorage) 适配器
+ * @description 实现 `StoragePort` 接口，封装了对原生 `localStorage` 的访问。
+ * 支持可选的命名空间前缀隔离，确保在同一个域下不同模块的数据互不干扰。
+ */
 export 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;
 }

package/dist/adapters/scoped-storage-adapter.d.ts

@@ -1,18 +1,61 @@
 import { StoragePort } from '../ports/storage-port';
 /**
- * 作用域存储适配器
- * 包装现有的 StoragePort 并为所有键应用命名空间前缀。
+ * 作用域存储适配器 (ScopedStorageAdapter)
+ * @description 采用装饰器模式实现。它包装一个现有的 `StoragePort` 实例，
+ * 并为所有存储操作透明地注入一个前缀（命名空间），从而实现逻辑上的存储隔离。
+ * 常用于为插件分配独立的存储空间，而无需修改插件代码。
  */
 export 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;
 }

package/dist/api/adapters/axios-adapter.d.ts

@@ -6,5 +6,5 @@ export 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>;
+    stream(config: ApiRequestConfig, callbacks: StreamCallbacks, _endpointConfig?: ApiEndpointConfig): Promise<void>;
 }

package/dist/api/engine.d.ts

@@ -47,9 +47,30 @@ export declare class ApiEngine {
      */
     stream(module: string, action: string, data?: any, options?: RequestOptions): Promise<void>;
     /**
-     * 准备请求配置，应用 URL 参数替换和拦截器
+     * 准备请求配置，应用 URL 参数替换和请求拦截器
      */
     private prepareRequestConfig;
+    /**
+     * 应用所有请求拦截器
+     */
+    private applyRequestInterceptors;
+    /**
+     * 应用所有响应拦截器
+     * @returns 是否被劫持
+     */
+    private applyResponseInterceptors;
+    /**
+     * 检查 HTTP 状态码
+     */
+    private checkHttpStatus;
+    /**
+     * 提取响应数据
+     */
+    private extractResponseData;
+    /**
+     * 处理业务错误
+     */
+    private handleBusinessError;
     /**
      * 判断是否为 BaseResponse
      */

package/dist/application/service-registry.d.ts

@@ -1,33 +1,56 @@
 /**
- * 服务注册中心
- * @description 实现插件间的解耦通信。插件可以注册服务，其他插件可以通过名称获取服务。
+ * 服务注册中心 (Service Registry)
+ * @description 核心应用层服务，作为微内核架构中的“中枢调度员”。
+ * 主要职责：
+ * 1. 服务解耦：允许插件将其内部功能暴露为“服务”，而无需与其他插件产生物理依赖。
+ * 2. 动态发现：提供按名称查找服务的能力，支持服务热插拔。
+ * 3. 依赖协调：通过 `waitFor` 机制解决插件间由于加载顺序导致的初始化依赖问题。
+ *
+ * 建议的服务命名规范: `pluginId.serviceName` (例如: `auth.sessionService`)
  */
 export declare class ServiceRegistry {
+    /** 存储已注册服务的 Map 对象 */
     private services;
+    /** 存储正在等待特定服务的监听器集合 */
     private listeners;
     /**
-     * 注册服务
-     * @param name 服务名称 (建议格式: pluginId.serviceName)
-     * @param service 服务实现
+     * 注册一个服务实现
+     * @param name - 唯一的服务名称
+     * @param service - 服务实例或对象
      */
     register(name: string, service: any): void;
     /**
-     * 获取服务
-     * @param name 服务名称
+     * 同步获取服务实例
+     * @template T - 服务类型的泛型
+     * @param name - 服务名称
+     * @returns 服务实例，若不存在则返回 undefined
      */
     get<T = any>(name: string): T | undefined;
     /**
-     * 异步获取服务 (如果尚未注册则等待)
-     * @param name 服务名称
+     * 异步等待并获取服务
+     * @description 如果服务尚未注册，将返回一个 Promise，直到该服务被注册时 resolve。
+     * 支持设置超时时间，防止因插件加载失败导致的永久挂起。
+     *
+     * @template T - 服务类型的泛型
+     * @param name - 待等待的服务名称
+     * @param timeout - 超时时间 (毫秒)，默认 10000ms (10秒)。若为 0 则永不超时。
+     * @returns 包含服务实例的 Promise
+     * @throws {Error} 若在规定时间内服务未注册，则抛出超时异常。
      */
-    waitFor<T = any>(name: string): Promise<T>;
+    waitFor<T = any>(name: string, timeout?: number): Promise<T>;
     /**
-     * 注销服务
-     * @param name 服务名称
+     * 检查服务是否已注册
+     * @param name - 服务名称
+     */
+    has(name: string): boolean;
+    /**
+     * 注销特定的服务
+     * @param name - 服务名称
      */
     unregister(name: string): void;
     /**
-     * 清除所有服务 (通常在系统重置时使用)
+     * 清除所有已注册的服务和监听器
+     * @description 通常仅在系统重置或大型热更新时使用。
      */
     clear(): void;
 }

package/dist/components/PluginErrorBoundary.d.ts

@@ -1,21 +1,43 @@
 import React, { Component, ErrorInfo, ReactNode } from 'react';
+/** 插件错误边界组件属性 */
 interface Props {
+    /** 发生错误的插件 ID */
     pluginId?: string;
+    /** 错误发生时的降级 UI */
     fallback?: ReactNode;
+    /** 子组件内容 */
     children: ReactNode;
+    /** 是否静默模式，开启后不显示任何错误 UI，仅记录日志 */
+    silent?: boolean;
 }
+/** 插件错误边界组件状态 */
 interface State {
+    /** 是否捕获到错误 */
     hasError: boolean;
+    /** 捕获到的错误对象 */
     error: Error | null;
 }
 /**
  * 插件错误边界组件
- * @description 捕获子组件错误，防止单个插件崩溃导致整个应用崩溃
+ * @description 核心组件，用于捕获子组件渲染过程中的 JavaScript 错误，记录日志并显示降级 UI。
+ * 确保单个插件的运行异常不会导致整个主应用或其他插件崩溃。
  */
 export declare class PluginErrorBoundary extends Component<Props, State> {
     constructor(props: Props);
+    /**
+     * 从错误中派生状态
+     * @param error - 捕获到的错误
+     */
     static getDerivedStateFromError(error: Error): State;
+    /**
+     * 捕获到错误后的回调
+     * @param error - 错误对象
+     * @param errorInfo - 错误堆栈信息
+     */
     componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    /**
+     * 重置错误状态，尝试重新渲染
+     */
     handleRetry: () => void;
     render(): string | number | boolean | Iterable<React.ReactNode> | import("react/jsx-runtime").JSX.Element | null | undefined;
 }

package/dist/components/PluginSlot.d.ts

@@ -1,24 +1,35 @@
 import React from 'react';
 import type { PluginExtension, SlotPosition } from '../api';
+/** 插件插槽组件属性 */
 interface PluginSlotProps {
-    /** 插槽位置标识 */
+    /** 插槽位置标识，决定渲染哪些插件扩展 */
     slot: SlotPosition;
-    /** 传递给扩展组件的 Props */
+    /** 传递给扩展组件的 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;
-    /** 回退组件 (当没有插件扩展时显示，优先于 skeleton) */
+    /** 回退组件，当插槽内无插件扩展时显示的 UI，优先级高于 skeleton */
     fallback?: React.ReactNode;
 }
+/**
+ * 插件插槽组件
+ * @description UI 层的核心组件，用于在应用中声明一个“插槽”。
+ * 它会自动根据 slot 标识从 PluginManager 中获取所有注册的插件扩展组件并按顺序渲染。
+ * 支持订阅插件变更，实现动态热插拔。
+ */
 export declare const PluginSlot: React.FC<PluginSlotProps>;
 export {};

package/dist/components/SlotSkeletons.d.ts

@@ -1,12 +1,27 @@
 import React from 'react';
 /**
  * 通用插槽骨架屏组件集合
+ * @description 提供一组预定义的骨架屏 UI，用于在插件加载或插槽内容未准备好时提供更好的用户体验。
+ */
+/**
+ * 侧边栏图标骨架屏
+ * @param expanded - 是否处于展开状态
  */
 export declare const SidebarIconSkeleton: React.FC<{
     expanded?: boolean;
 }>;
+/**
+ * 状态栏项骨架屏
+ */
 export declare const StatusBarItemSkeleton: React.FC;
+/**
+ * 头像骨架屏
+ */
 export declare const AvatarSkeleton: React.FC;
+/**
+ * 通用块级骨架屏
+ * @param className - 自定义类名
+ */
 export declare const BlockSkeleton: React.FC<{
     className?: string;
 }>;

package/dist/config-manager.d.ts

@@ -1,28 +1,32 @@
 /**
  * 配置管理器
- * @description 负责管理应用的全局配置和插件配置
+ * @description 核心工具类，负责管理应用的全局系统配置以及各插件的初始化业务配置。
+ * 配置数据通常在应用启动时通过 `usePluginLoader` 注入，并作为插件运行时的取值回退来源。
  */
 export declare class ConfigManager {
-    /** 存储配置的 Map */
+    /** 内部存储配置的 Map 对象 */
     private config;
     /**
-     * 设置配置项
-     * @param key 配置键
-     * @param value 配置值
+     * 设置特定的配置项
+     * @param key - 配置键名（如 'system' 或插件 ID）
+     * @param value - 配置内容对象
      */
     set(key: string, value: any): void;
     /**
-     * 获取配置项
-     * @param key 配置键
+     * 获取指定的配置项
+     * @param key - 配置键名
+     * @returns 配置内容，若不存在则返回 undefined
      */
     get(key: string): any;
     /**
-     * 合并配置
-     * @param config 配置对象
+     * 批量合并配置对象
+     * @description 对顶层属性进行浅合并，若属性值为对象则进行一层深度的合并。
+     * @param config - 待合并的配置对象映射
      */
     merge(config: Record<string, any>): void;
     /**
-     * 获取所有配置
+     * 获取当前存储的所有配置快照
+     * @returns 包含所有配置的普通对象
      */
     getAll(): Record<string, any>;
 }

package/dist/domain/auto-loader.d.ts

@@ -1,21 +1,36 @@
+/**
+ * 插件注册表接口
+ * @description 键为插件 ID，值为一个返回插件定义的异步加载函数。
+ */
 export interface PluginRegistry {
     [pluginId: string]: () => Promise<any>;
 }
+/**
+ * 插件自动发现规则
+ */
 export interface DiscoveryRule {
     /**
-     * 路径匹配标识（如 'plugins' 或 '@chatbi-plugins'）
+     * 路径匹配标识。
+     * @example 'plugins' 或 '@chatbi-plugins'
      */
     pathSegment: string;
     /**
-     * 生成插件 ID 时的前缀（如 '@chatbi-v/plugin'）
+     * 生成插件 ID 时的前缀。
+     * @example '@chatbi-v/plugin'，最终生成如 '@chatbi-v/plugin-demo'
      */
     idPrefix: string;
 }
 /**
- * 自动发现并解析插件
- * @description 将 Vite 的 glob 导入结果解析为符合 PluginManager 要求的注册表
+ * 解析插件注册表
+ * @description 核心逻辑：将 Vite 的 `import.meta.glob` 结果映射为标准的插件注册表。
+ * 它会根据预定义的路径匹配规则，从文件路径中提取插件目录名，并拼接前缀生成唯一的插件 ID。
+ *
+ * @param options - 包含待处理模块和匹配规则的选项对象
+ * @returns 解析后的 PluginRegistry 对象
  */
 export declare const resolvePluginRegistry: (options: {
+    /** 原始模块映射 (来自 Vite glob) */
     modules: Record<string, () => Promise<any>>;
+    /** 自定义发现规则 (可选) */
     rules?: DiscoveryRule[];
 }) => PluginRegistry;

package/dist/domain/models.d.ts

@@ -1,34 +1,42 @@
+/**
+ * 成功状态码
+ */
 export declare const SUCCESS_CODE = "000000";
 /**
- * 基础响应接口
+ * 基础 API 响应接口
+ * @template T 响应数据的类型
  */
 export interface BaseResponse<T = any> {
+    /** 业务状态码 */
     code: string | number;
+    /** 响应消息提示 */
     message: string;
+    /** 业务响应数据主体 */
     data: T;
 }
 /**
- * 场景接口
+ * 业务场景实体接口
+ * @description 描述系统中的业务分析场景
  */
 export 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;
 }