@chatbi-v/vue 3.0.0 → 3.1.1

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

@@ -0,0 +1,345 @@
+import { PLUGIN_TYPES, type PluginManifest, type PluginType } from '../manifest/PluginManifest';
+import { isPluginId, type PluginId } from '../types/branded';
+export { isPluginId };
+export type { PluginId };
+import { ApiAdapter, ApiConfig } from './api-port';
+import { EventBusPort } from './event-bus-port';
+import { TypedStorage } from './storage-port';
+/**
+ * API 端口接口
+ * @description 插件使用 API 能力的入口，包含请求适配器和 API 配置注册功能
+ */
+export interface ApiPort extends ApiAdapter {
+    /**
+     * 注册 API 配置
+     * @param config - API 配置对象
+     */
+    register?: (config: ApiConfig) => void;
+}
+/**
+ * 插件类型定义
+ */
+export { PLUGIN_TYPES };
+export type { PluginType };
+/**
+ * 路由配置
+ */
+export interface RouteConfig {
+    path: string;
+    component: any;
+    meta?: Record<string, any>;
+}
+/**
+ * 插件插槽位置
+ * @description 定义插件可以注入 UI 的标准位置
+ */
+export 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";
+};
+export type SlotType = (typeof Slot)[keyof typeof Slot];
+export type SlotPosition = SlotType | string;
+/**
+ * 插件扩展 (插槽注入配置)
+ */
+export interface PluginExtension {
+    /** 插槽位置标识符 */
+    slot: SlotPosition;
+    /** 要注入的 React 等框架组件 */
+    component: any;
+    /** 排序权重，数值越小越靠前 */
+    order?: number;
+    /** @internal 插件 ID，由系统在加载时自动注入，用于溯源 */
+    _pluginId?: string;
+    /** 扩展的元数据信息 */
+    meta?: {
+        /** 显示图标 */
+        icon?: any;
+        /** 显示标签文本 */
+        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;
+    /**
+     * 是否为私有配置
+     * @description 如果为 true，则该配置不会通过自动配置服务暴露给其他插件
+     * @default false
+     */
+    private?: boolean;
+}
+/**
+ * 插件能力定义 (Behavioral Capabilities)
+ * @description 定义插件的行为特征。注意：路由(routes)和扩展(extensions)属于结构化能力，直接通过 metadata 字段声明，不在此列。
+ */
+export 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)
+ */
+export interface StorageItemSchema {
+    /** 存储键名 */
+    key: string;
+    /** 数据类型 */
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    /** 默认值 */
+    default?: any;
+    /** 描述信息 */
+    description?: string;
+    /**
+     * 作用域
+     * @description 'plugin' 表示仅当前插件可见（带插件 ID 前缀），'shared' 表示全局共享
+     */
+    scope?: 'plugin' | 'shared';
+}
+/**
+ * 插件存储接口
+ * @description 包含私有存储和共享存储访问能力
+ */
+export 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 插件可以在不同的生命周期阶段执行特定的逻辑
+ * @template T - 插件清单类型，默认为 PluginManifest
+ */
+export interface PluginLifecycle<T extends PluginManifest = PluginManifest> {
+    /**
+     * 插件加载时调用
+     * @description 在插件被扫描并注入内核时触发。用于初始化内部状态、注册服务、设置拦截器等。此时 UI 尚未挂载。
+     * @param context - 插件上下文对象，提供核心能力的访问
+     */
+    onLoad?: (context: PluginContext<T>) => void | Promise<void>;
+    /**
+     * 插件挂载到 UI 时调用
+     * @description 当插件的 UI 组件（如有）被 React 挂载到 DOM 时触发。
+     * @param context - 插件上下文对象
+     */
+    onMount?: (context: PluginContext<T>) => void;
+    /**
+     * 插件从 UI 卸载时调用
+     * @description 当插件的 UI 组件被销毁时触发。用于清理定时器、取消订阅等。
+     * @param context - 插件上下文对象
+     */
+    onUnmount?: (context: PluginContext<T>) => void;
+    /**
+     * 插件配置发生变化时调用
+     * @description 当用户通过配置中心修改插件设置时触发。
+     * @param newConfig - 变更后的新配置对象
+     * @param oldConfig - 变更前的旧配置对象
+     */
+    onConfigChange?: (newConfig: any, oldConfig: any) => void;
+    /**
+     * 插件错误处理
+     * @description 当插件发生错误时触发，用于统一错误处理和日志记录
+     * @param error - 错误对象
+     * @param context - 插件上下文对象
+     */
+    onError?: (error: Error, context: PluginContext<T>) => void;
+}
+/**
+ * 插件上下文
+ * @description 传递给插件生命周期钩子的核心对象，是插件访问宿主环境能力的唯一入口。
+ * @template T - 插件清单类型，默认为 PluginManifest
+ */
+export interface PluginContext<T extends PluginManifest = PluginManifest> {
+    /** 当前插件的唯一标识符 */
+    pluginId: PluginId;
+    /** 插件清单 */
+    manifest: T;
+    /** API 请求能力入口 */
+    api: ApiPort;
+    /** 事件总线能力入口 */
+    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 = unknown>(serviceName: string) => T | undefined;
+    /**
+     * 注册当前插件的服务供他人使用
+     * @param serviceName - 唯一服务名称
+     * @param service - 服务实现对象
+     */
+    registerService: <T = unknown>(serviceName: string, service: T) => void;
+    /** 宿主环境 Window 的代理对象 (用于沙箱隔离) */
+    window: WindowProxy;
+}
+/**
+ * 完整的插件对象定义
+ */
+export interface Plugin extends PluginLifecycle {
+    /**
+     * 插件唯一标识符
+     * @description 必须与 metadata.id 一致，通常为只读。
+     */
+    readonly id: string;
+    /** 插件元数据配置 */
+    metadata: PluginMetadata;
+    /** 插件提供的功能组件集合 (可选) */
+    components?: Record<string, any>;
+    /** 插件提供的工具函数集合 (可选) */
+    utils?: Record<string, any>;
+    /** 插件的初始默认配置 (可选) */
+    defaultConfig?: Record<string, any>;
+}
+/**
+ * 插件基础类
+ * @deprecated 建议统一使用工厂模式 definePlugin() 定义插件，以消除类与对象定义的歧义。
+ * @description 解决插件定义时 id 与 metadata.id 重复定义的问题，并提供基础生命周期管理
+ */
+export 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 完整的插件对象
+ */
+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;
+    /** 插件图标 */
+    icon?: any;
+    /** 插件依赖的其他插件 ID 列表 */
+    dependencies?: string[];
+    /** 路由配置集合，用于在主应用中注册页面 */
+    routes?: RouteConfig[];
+    /** 插槽扩展集合，用于在主应用 UI 预留位注入组件 */
+    extensions?: PluginExtension[];
+    /** 插件所需调用的 API 接口配置 */
+    api?: ApiConfig;
+    /** 插件行为能力声明 */
+    capabilities?: PluginCapabilities;
+    /** 插件的可配置项定义 */
+    configuration?: PluginConfigItem[];
+    /** 插件所需的存储结构定义 */
+    storage?: StorageItemSchema[];
+    /**
+     * 插件优先级
+     * @description 数值越小优先级越高，用于插件加载顺序和插槽渲染顺序
+     * @default 100
+     */
+    priority?: number;
+    /**
+     * 系统状态自动绑定
+     * @description 将插件的配置项自动同步到系统的全局状态中 (如主题色、身份认证等)
+     */
+    systemStateBindings?: {
+        /** 插件配置中的键名 */
+        configKey: string;
+        /** 系统全局状态中的键名 */
+        stateKey: string;
+        /** 预设的转换逻辑名称 */
+        transform?: 'theme-mode' | 'identity';
+    }[];
+}

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

@@ -0,0 +1,49 @@
+/**
+ * 存储端口接口
+ * @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;
+    /**
+     * 根据索引返回存储中对应键的名称
+     * @param index - 数值索引
+     * @returns 键名，如果索引超出范围则返回 null
+     */
+    key(index: number): string | null;
+}
+/**
+ * 类型化存储接口
+ * @description 提供泛型支持的存储访问能力，自动处理序列化
+ */
+export interface TypedStorage {
+    /** 获取存储数据 */
+    get: <T = any>(key: string) => T | null;
+    /** 设置存储数据 */
+    set: <T = any>(key: string, value: T) => void;
+    /** 移除存储数据 */
+    remove: (key: string) => void;
+}

package/dist/core/src/remote/RemoteCache.d.ts

@@ -0,0 +1,57 @@
+import type { CacheEntry, CacheOptions } from './RemotePluginSource.js';
+/**
+ * 远程缓存管理器
+ * @description 管理远程插件Manifest的缓存，支持TTL和大小限制
+ */
+export declare class RemoteCache<T = any> {
+    private cache;
+    private defaultTtl;
+    /**
+     * 创建远程缓存管理器
+     * @param options 缓存配置选项
+     */
+    constructor(options?: CacheOptions);
+    /**
+     * 获取缓存条目
+     * @param key 缓存键
+     * @returns 缓存条目，如果不存在或已过期返回 undefined
+     */
+    get(key: string): CacheEntry<T> | undefined;
+    /**
+     * 设置缓存条目
+     * @param key 缓存键
+     * @param data 要缓存的数据
+     * @param ttl 自定义 TTL (毫秒)，使用默认 TTL 如果未指定
+     */
+    set(key: string, data: T, ttl?: number): void;
+    /**
+     * 删除缓存条目
+     * @param key 缓存键
+     * @returns 是否成功删除
+     */
+    delete(key: string): boolean;
+    /**
+     * 清空所有缓存
+     */
+    clear(): void;
+    /**
+     * 检查缓存键是否存在
+     * @param key 缓存键
+     */
+    has(key: string): boolean;
+    /**
+     * 获取缓存条目数量
+     */
+    size(): number;
+    /**
+     * 获取缓存条目的元数据（不触发访问时间更新）
+     * @param key 缓存键
+     */
+    getMetadata(key: string): CacheEntry<T> | undefined;
+    /**
+     * 更新缓存 TTL
+     * @param key 缓存键
+     * @param ttl 新 TTL (毫秒)
+     */
+    updateTTL(key: string, ttl: number): boolean;
+}

package/dist/core/src/remote/RemoteLoader.d.ts

@@ -0,0 +1,85 @@
+import type { PluginManifest } from '../manifest/PluginManifest.js';
+import type { LoadResult, RemotePluginSource, RemoteSourceOptions } from './RemotePluginSource.js';
+/**
+ * 远程插件加载器
+ * @description 管理远程插件源的添加、移除和 Manifest 加载
+ */
+export declare class RemoteLoader {
+    private sources;
+    private cache;
+    private retryStrategy;
+    private options;
+    /**
+     * 创建远程加载器
+     * @param options 远程源配置选项
+     */
+    constructor(options?: RemoteSourceOptions);
+    /**
+     * 添加远程插件源
+     * @param source 远程插件源
+     */
+    addSource(source: RemotePluginSource): void;
+    /**
+     * 移除远程插件源
+     * @param sourceId 插件源 ID
+     * @returns 是否成功移除
+     */
+    removeSource(sourceId: string): boolean;
+    /**
+     * 获取所有远程插件源
+     * @returns 远程插件源列表
+     */
+    getSources(): RemotePluginSource[];
+    /**
+     * 获取指定远程插件源
+     * @param sourceId 插件源 ID
+     */
+    getSource(sourceId: string): RemotePluginSource | undefined;
+    /**
+     * 启用/禁用远程插件源
+     * @param sourceId 插件源 ID
+     * @param enabled 是否启用
+     */
+    setSourceEnabled(sourceId: string, enabled: boolean): boolean;
+    /**
+     * 从远程加载插件 Manifest
+     * @param sourceId 插件源 ID
+     * @returns 加载结果
+     */
+    loadManifest<T = PluginManifest>(sourceId: string): Promise<LoadResult<T>>;
+    /**
+     * 带重试的请求
+     * @param url 请求 URL
+     * @param attempt 当前尝试次数
+     * @returns 响应数据
+     */
+    private fetchWithRetry;
+    /**
+     * 处理加载错误
+     * @param error 错误对象
+     * @returns 错误结果
+     */
+    private handleLoadError;
+    /**
+     * 创建错误结果
+     * @param code 错误代码
+     * @param message 错误消息
+     * @param retryable 是否可重试
+     * @returns 错误结果
+     */
+    private createErrorResult;
+    /**
+     * 清除缓存
+     * @param sourceId 可选，指定源 ID（只清除该源的缓存）
+     */
+    clearCache(sourceId?: string): void;
+    /**
+     * 获取缓存大小
+     */
+    getCacheSize(): number;
+    /**
+     * 睡眠
+     * @param ms 毫秒数
+     */
+    private sleep;
+}

package/dist/core/src/remote/RemotePluginSource.d.ts

@@ -0,0 +1,88 @@
+/**
+ * Remote Plugin Source 类型定义
+ * @description 定义远程插件源接口和配置选项
+ */
+/**
+ * 远程插件源
+ * @description 表示一个远程插件仓库地址
+ */
+export interface RemotePluginSource {
+    /** 唯一标识符 */
+    id: string;
+    /** 显示名称 */
+    name: string;
+    /** plugin.json URL */
+    url: string;
+    /** 是否启用 */
+    enabled?: boolean;
+}
+/**
+ * 缓存配置选项
+ */
+export interface CacheOptions {
+    /** 缓存 TTL (毫秒)，默认 5 分钟 */
+    ttl: number;
+    /** 最大缓存条目数 */
+    maxSize?: number;
+}
+/**
+ * 重试配置选项
+ */
+export interface RetryOptions {
+    /** 最大重试次数 */
+    maxRetries: number;
+    /** 重试延迟 (毫秒) */
+    retryDelay: number;
+    /** 自定义重试条件 */
+    retryCondition?: (error: any) => boolean;
+}
+/**
+ * 远程源配置选项
+ */
+export interface RemoteSourceOptions {
+    /** 请求超时 (毫秒) */
+    timeout?: number;
+    /** 重试配置 */
+    retry?: RetryOptions;
+    /** 缓存配置 */
+    cache?: CacheOptions;
+}
+/**
+ * 缓存条目元数据
+ */
+export interface CacheEntry<T = any> {
+    /** 缓存数据 */
+    data: T;
+    /** 创建时间戳 */
+    createdAt: number;
+    /** 最后访问时间戳 */
+    lastAccessedAt: number;
+    /** 过期时间戳 */
+    expiresAt: number;
+}
+/**
+ * 加载结果
+ */
+export interface LoadResult<T = any> {
+    /** 是否成功 */
+    success: boolean;
+    /** 加载的数据 */
+    data?: T;
+    /** 加载错误 */
+    error?: LoadError;
+    /** 是否来自缓存 */
+    fromCache?: boolean;
+}
+/**
+ * 加载错误
+ */
+export interface LoadError {
+    /** 错误代码 */
+    code: 'NETWORK' | 'TIMEOUT' | 'PARSE' | 'NOT_FOUND' | 'CACHE_ERROR' | 'VALIDATION_ERROR';
+    /** 错误消息 */
+    message: string;
+    /** 是否可重试 */
+    retryable: boolean;
+    /** 原始错误 */
+    originalError?: any;
+}

package/dist/core/src/remote/RetryStrategy.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Retry Strategy 实现
+ * @description 提供重试延迟计算和错误判断逻辑
+ */
+import type { RetryOptions } from './RemotePluginSource.js';
+/**
+ * 重试策略类
+ * @description 计算重试延迟、判断错误是否可重试
+ */
+export declare class RetryStrategy {
+    private defaultOptions;
+    /**
+     * 创建重试策略
+     * @param options 重试配置选项
+     */
+    constructor(options?: RetryOptions);
+    /**
+     * 计算重试延迟（指数退避）
+     * @param attempt 当前尝试次数 (从 1 开始)
+     * @returns 延迟毫秒数
+     */
+    calculateDelay(attempt: number): number;
+    /**
+     * 判断错误是否可重试
+     * @param error 错误对象
+     * @returns 是否可重试
+     */
+    isRetryable(error: any): boolean;
+    /**
+     * 默认重试条件判断
+     * @param error 错误对象
+     * @returns 是否可重试
+     */
+    private defaultRetryCondition;
+    /**
+     * 获取最大重试次数
+     */
+    getMaxRetries(): number;
+    /**
+     * 获取基础重试延迟
+     */
+    getBaseDelay(): number;
+}

package/dist/core/src/remote/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Remote Module 入口
+ * @description 导出远程插件加载相关类型和类
+ */
+export * from './RemoteCache';
+export * from './RemoteLoader';
+export * from './RemotePluginSource';
+export * from './RetryStrategy';