@chatbi-v/core 1.0.2

package/README.md

@@ -0,0 +1,36 @@
+# @chatbi-v/core
+
+ChatBI 核心模块，提供插件管理、基础设施接口及通用 API 引擎。
+
+## 架构原则 (Architecture Principles)
+
+- **业务无关性 (Business Agnostic)**: `core` 包禁止包含任何具体的业务模型、业务逻辑或业务常量。
+- **共享契约 (Shared Contract)**: `core` 只定义通用的技术契约（如 `Plugin`, `StoragePort`, `ApiAdapter`）。
+- **插件驱动 (Plugin Driven)**: 所有的业务逻辑应由插件实现。
+
+## 目录结构
+
+- `adapters/`: 基础设施的具体实现（如 LocalStorage, Axios）。
+- `api/`: 通用 API 请求引擎。
+- `domain/`: 核心领域逻辑（插件管理器、运行时、沙箱）。
+- `ports/`: 核心接口定义（端口）。
+
+## 功能
+
+- **PluginManager**: 管理插件的注册和生命周期。
+- **ApiEngine**: 统一的 API 请求管理。
+- **Sandbox**: 提供插件运行时的样式和全局变量隔离。
+
+## 使用方法
+
+```typescript
+import { pluginManager } from '@chatbi/core';
+
+// 注册插件
+pluginManager.register({
+  id: 'my-plugin',
+  init: (context) => {
+    console.log('Plugin initialized');
+  },
+});
+```

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

@@ -0,0 +1,13 @@
+import { StoragePort } from '../ports/storage-port';
+export declare class LocalStorageAdapter implements StoragePort {
+    private prefix;
+    constructor(prefix?: string);
+    private getKey;
+    private getOriginalKey;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    get length(): number;
+    key(index: number): string | null;
+}

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

@@ -0,0 +1,18 @@
+import { StoragePort } from '../ports/storage-port';
+/**
+ * 作用域存储适配器
+ * 包装现有的 StoragePort 并为所有键应用命名空间前缀。
+ */
+export declare class ScopedStorageAdapter implements StoragePort {
+    private underlyingStorage;
+    private prefix;
+    constructor(underlyingStorage: StoragePort, prefix: string);
+    private getKey;
+    private getOriginalKey;
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    clear(): void;
+    get length(): number;
+    key(index: number): string | null;
+}

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

@@ -0,0 +1,10 @@
+import { ApiAdapter, ApiEndpointConfig, ApiRequestConfig, StreamCallbacks } from '../../ports/api-port';
+/**
+ * 基于 Axios 的默认请求适配器
+ */
+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>;
+}

package/dist/api/engine.d.ts

@@ -0,0 +1,41 @@
+import { ApiAdapter, ApiConfig, ApiEndpointConfig, RequestOptions } from '../ports/api-port';
+/**
+ * API 引擎核心类
+ * @description 负责加载配置并执行请求，支持策略模式切换底层请求实现
+ */
+export declare class ApiEngine {
+    private adapter;
+    private config;
+    constructor(adapter?: ApiAdapter);
+    /**
+     * 切换请求适配器
+     * @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>;
+}
+export declare const apiEngine: ApiEngine;

package/dist/api/index.d.ts

@@ -0,0 +1,6 @@
+export * from './adapters/axios-adapter';
+export * from './engine';
+export * from './utils';
+export * from '../domain/models';
+export * from '../ports/api-port';
+export * from '../ports/plugin-port';

package/dist/api/utils.d.ts

@@ -0,0 +1,14 @@
+import { ApiConfig } from '../ports/api-port';
+/**
+ * 自动检测是否处于 Mock 模式
+ */
+export 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
+ */
+export declare function resolveApiModules(definitionsMap: Record<string, any>, mocksMap?: Record<string, any>): ApiConfig;

package/dist/api-context.d.ts

@@ -0,0 +1,8 @@
+import React from 'react';
+import type { ApiEngine } from './api';
+export interface ApiProviderProps {
+    api: ApiEngine;
+    children: React.ReactNode;
+}
+export declare const ApiProvider: React.FC<ApiProviderProps>;
+export declare const useApi: () => ApiEngine;

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

@@ -0,0 +1,34 @@
+/**
+ * 服务注册中心
+ * @description 实现插件间的解耦通信。插件可以注册服务，其他插件可以通过名称获取服务。
+ */
+export declare class ServiceRegistry {
+    private services;
+    private listeners;
+    /**
+     * 注册服务
+     * @param name 服务名称 (建议格式: pluginId.serviceName)
+     * @param service 服务实现
+     */
+    register(name: string, service: any): void;
+    /**
+     * 获取服务
+     * @param name 服务名称
+     */
+    get<T = any>(name: string): T | undefined;
+    /**
+     * 异步获取服务 (如果尚未注册则等待)
+     * @param name 服务名称
+     */
+    waitFor<T = any>(name: string): Promise<T>;
+    /**
+     * 注销服务
+     * @param name 服务名称
+     */
+    unregister(name: string): void;
+    /**
+     * 清除所有服务 (通常在系统重置时使用)
+     */
+    clear(): void;
+}
+export declare const serviceRegistry: ServiceRegistry;

package/dist/components/PluginErrorBoundary.d.ts

@@ -0,0 +1,22 @@
+import React, { Component, ErrorInfo, ReactNode } from 'react';
+interface Props {
+    pluginId?: string;
+    fallback?: ReactNode;
+    children: ReactNode;
+}
+interface State {
+    hasError: boolean;
+    error: Error | null;
+}
+/**
+ * 插件错误边界组件
+ * @description 捕获子组件错误，防止单个插件崩溃导致整个应用崩溃
+ */
+export declare class PluginErrorBoundary extends Component<Props, State> {
+    constructor(props: Props);
+    static getDerivedStateFromError(error: Error): State;
+    componentDidCatch(error: Error, errorInfo: ErrorInfo): void;
+    handleRetry: () => void;
+    render(): string | number | boolean | Iterable<React.ReactNode> | import("react/jsx-runtime").JSX.Element | null | undefined;
+}
+export {};

package/dist/components/PluginSlot.d.ts

@@ -0,0 +1,22 @@
+import React from 'react';
+import type { PluginExtension, SlotPosition } from '../api';
+interface PluginSlotProps {
+    /** 插槽位置标识 */
+    slot: SlotPosition;
+    /** 传递给扩展组件的 Props */
+    props?: Record<string, any>;
+    /** 自定义容器类名 */
+    className?: string;
+    /** 自定义容器样式 */
+    style?: React.CSSProperties;
+    /** 渲染器自定义 (可选) */
+    renderItem?: (item: {
+        key: string;
+        component: React.ReactNode;
+        extension: PluginExtension;
+    }, index: number) => React.ReactNode;
+    /** 骨架屏组件 (当没有插件扩展时显示) */
+    skeleton?: React.ReactNode;
+}
+export declare const PluginSlot: React.FC<PluginSlotProps>;
+export {};

package/dist/components/SlotSkeletons.d.ts

@@ -0,0 +1,10 @@
+import React from 'react';
+/**
+ * 通用插槽骨架屏组件集合
+ */
+export declare const SidebarIconSkeleton: React.FC;
+export declare const StatusBarItemSkeleton: React.FC;
+export declare const AvatarSkeleton: React.FC;
+export declare const BlockSkeleton: React.FC<{
+    className?: string;
+}>;

package/dist/config-manager.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 配置管理器
+ * @description 负责管理应用的全局配置和插件配置
+ */
+export declare class ConfigManager {
+    /** 存储配置的 Map */
+    private config;
+    /**
+     * 设置配置项
+     * @param key 配置键
+     * @param value 配置值
+     */
+    set(key: string, value: any): void;
+    /**
+     * 获取配置项
+     * @param key 配置键
+     */
+    get(key: string): any;
+    /**
+     * 合并配置
+     * @param config 配置对象
+     */
+    merge(config: Record<string, any>): void;
+    /**
+     * 获取所有配置
+     */
+    getAll(): Record<string, any>;
+}
+/** 全局配置管理器单例 */
+export declare const configManager: ConfigManager;

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

@@ -0,0 +1,37 @@
+export interface PluginRegistry {
+    [pluginId: string]: () => Promise<any>;
+}
+export interface DiscoveryRule {
+    /**
+     * 插件发现的 Glob 模式 (例如: '@chatbi-plugins/*\/src/index.{ts,tsx}')
+     */
+    pattern: string;
+    /**
+     * 路径标识部分（用于从绝对路径中提取 ID，例如 'packages/plugins'）
+     */
+    pathSegment: string;
+    /**
+     * 生成插件 ID 时的前缀
+     */
+    idPrefix: string;
+    /**
+     * 可选的别名映射
+     */
+    alias?: string;
+}
+/**
+ * 自动发现并解析插件
+ * @description 将 Vite 的 glob 导入结果解析为符合 PluginManager 要求的注册表
+ */
+export declare const resolvePluginRegistry: (options: {
+    modules: Record<string, () => Promise<any>>;
+    baseUrl: string;
+    rules: DiscoveryRule[];
+}) => PluginRegistry;
+/**
+ * 核心插件发现方法
+ * @description 该方法应在应用层被调用，但逻辑集成在 core 中。
+ * 注意：由于 Vite import.meta.glob 必须使用字面量的限制，
+ * 这里使用一个覆盖范围合理的模式，并通过 rules 进行精确匹配。
+ */
+export declare const discoverPlugins: (rules: DiscoveryRule[], baseUrl: string) => PluginRegistry;

package/dist/domain/models.d.ts

@@ -0,0 +1,9 @@
+export declare const SUCCESS_CODE = "000000";
+/**
+ * 基础响应接口
+ */
+export interface BaseResponse<T = any> {
+    code: string | number;
+    message: string;
+    data: T;
+}

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

@@ -0,0 +1,143 @@
+import { DefaultEventBus } from '../event-bus';
+import { Plugin, PluginExtension, RouteConfig, SlotPosition } from '../ports/plugin-port';
+import { StoragePort } from '../ports/storage-port';
+import { StorageManager } from './storage-manager';
+/**
+ * 插件管理器
+ * @description 负责插件的加载、注册和生命周期管理
+ */
+export declare class PluginManager {
+    /** 全局事件总线 */
+    readonly eventBus: DefaultEventBus;
+    /** 存储接口 */
+    private storageManager;
+    /** 所有插件运行时实例 */
+    private runtimes;
+    /** 所有注册的插件（原始数据） */
+    private plugins;
+    /** 收集的路由 */
+    private routes;
+    /** 收集的扩展点 */
+    private extensions;
+    /** 插件状态管理（启用/禁用、排序） */
+    private pluginStates;
+    /** 状态变更监听器 */
+    private listeners;
+    /** 共享上下文缓存 */
+    private sharedContext;
+    /** 收集的工具函数 */
+    private utils;
+    constructor(storage: StoragePort);
+    private loadStates;
+    private saveStates;
+    /**
+     * 订阅插件状态变更
+     * @param listener 监听函数
+     * @returns 取消订阅函数
+     */
+    subscribe(listener: () => void): () => void;
+    getStorageManager(): StorageManager;
+    /**
+     * 触发状态变更通知
+     */
+    private notify;
+    /**
+     * 获取所有已注册的插件
+     */
+    getPlugins(): Plugin[];
+    /**
+     * 获取插件状态
+     * @param pluginId 插件 ID
+     */
+    getPluginState(pluginId: string): {
+        enabled: boolean;
+        order: number;
+    };
+    /**
+     * 检查插件是否启用
+     * @param pluginId 插件 ID
+     */
+    isPluginEnabled(pluginId: string): boolean;
+    /**
+     * 切换插件启用状态
+     * @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
+     */
+    getUnifiedCapabilities(pluginId: string): import("..").PluginCapabilities;
+    /**
+     * 更新插件配置
+     * @param pluginId 插件 ID
+     * @param key 配置项 Key
+     * @param value 配置值
+     */
+    updatePluginConfig(pluginId: string, key: string, value: any): void;
+    /**
+     * 获取插件配置
+     * @param pluginId 插件 ID
+     * @param key 配置键
+     * @returns 配置值
+     */
+    getPluginConfig(pluginId: string, key: string): any;
+    /**
+     * 获取指定插槽的扩展
+     * @param slot 插槽位置
+     */
+    getExtensions(slot: SlotPosition | string): PluginExtension[];
+    /**
+     * 获取所有收集到的路由
+     */
+    getRoutes(): RouteConfig[];
+    /**
+     * 注册插件
+     * @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>;
+    /**
+     * 实例化插件
+     */
+    private instantiatePlugin;
+    private validatePlugin;
+    private handleBusinessPlugin;
+    private handleFunctionalPlugin;
+    private handleViewPlugin;
+    private handleThemePlugin;
+    private handleSystemPlugin;
+}
+/**
+ * 全局插件管理器实例
+ */
+export declare const pluginManager: PluginManager;

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

@@ -0,0 +1,34 @@
+import { Plugin, PluginContext } from '../ports/plugin-port';
+import { StorageManager } from './storage-manager';
+/**
+ * 插件运行时
+ * @description 封装单个插件的生命周期、沙箱和状态
+ */
+export declare class PluginRuntime {
+    plugin: Plugin;
+    context: PluginContext;
+    private storageSandbox;
+    private windowSandbox;
+    private isLoaded;
+    private isMounted;
+    constructor(plugin: Plugin, sharedContext: Record<string, any>, storageManager: StorageManager);
+    /**
+     * 加载插件 (onLoad)
+     * @description 注册服务、初始化非 UI 逻辑
+     */
+    load(): Promise<void>;
+    /**
+     * 挂载插件 (onMount)
+     * @description 激活沙箱、处理 UI 相关的副作用
+     */
+    mount(): Promise<void>;
+    /**
+     * 卸载插件 (onUnmount)
+     */
+    unmount(): Promise<void>;
+    /**
+     * 销毁插件 (完全移除)
+     */
+    destroy(): Promise<void>;
+    get status(): "mounted" | "loaded" | "initial";
+}

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

@@ -0,0 +1,27 @@
+import { StorageManager } from './storage-manager';
+/**
+ * 插件沙箱
+ * @description 为插件提供隔离的运行时环境
+ */
+export declare class PluginSandbox {
+    private pluginId;
+    private storageManager;
+    constructor(pluginId: string, storageManager: StorageManager);
+    /**
+     * 获取隔离的存储接口
+     */
+    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;
+    };
+    /**
+     * 获取隔离的日志接口
+     */
+    get logger(): import("..").Logger;
+}

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

@@ -0,0 +1,46 @@
+import { StorageItemSchema } from '../ports/plugin-port';
+import { StoragePort } from '../ports/storage-port';
+/**
+ * 存储管理器
+ * @description 统一管理系统、插件和共享存储
+ */
+export declare class StorageManager {
+    private baseStorage;
+    private schemas;
+    constructor(baseStorage: StoragePort);
+    /**
+     * 注册插件存储 Schema
+     */
+    registerSchema(pluginId: string, schema: StorageItemSchema[]): void;
+    /**
+     * 验证 Key 是否符合 Schema 定义 (仅在开发环境或严格模式下警告)
+     */
+    private validateKey;
+    /**
+     * 获取插件专用存储适配器
+     * @param pluginId 插件 ID
+     */
+    getPluginStorage(pluginId: string): StoragePort;
+    /**
+     * 获取共享存储适配器
+     */
+    getSharedStorage(): StoragePort;
+    /**
+     * 获取系统存储适配器
+     */
+    getSystemStorage(): StoragePort;
+    /**
+     * 获取插件上下文中的 storage 对象 (包含类型转换辅助方法)
+     * @param pluginId 插件 ID
+     */
+    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;
+    };
+}

package/dist/event-bus.d.ts

@@ -0,0 +1,38 @@
+export type EventCallback = (...args: any[]) => any;
+/**
+ * 事件总线接口
+ */
+export 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;
+}
+export 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;
+}

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

@@ -0,0 +1,20 @@
+export interface PluginLoaderOptions {
+    /** 插件发现规则 */
+    discoveryRules?: any[];
+    /** 预注册的插件注册表 (可选，用于离线或手动加载) */
+    registry?: Record<string, () => Promise<any>>;
+    /** 插件配置映射 */
+    pluginConfigs: Record<string, any>;
+    /** 初始化的上下文服务 (如 api, events 等) */
+    sharedContext?: Record<string, any>;
+    /** 发现的基础 URL */
+    baseUrl?: string;
+}
+/**
+ * 通用插件加载 Hook
+ * @description 负责插件的自动发现、加载、初始化和状态订阅
+ */
+export declare const usePluginLoader: (options: PluginLoaderOptions) => {
+    pluginsLoaded: boolean;
+    pluginVersion: number;
+};

package/dist/hooks/use-storage-state.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Hook options
+ */
+export interface UseStorageStateOptions<T> {
+    defaultValue?: T;
+    scope?: 'plugin' | 'shared';
+}
+/**
+ * Unified Storage State Hook
+ * @description Provides a persistent state hook that integrates with the StorageManager and Schema Registry.
+ * @param pluginId The plugin ID defining the key
+ * @param key The storage key (must be registered in schema)
+ * @param options Options including default value and scope
+ */
+export declare function useStorageState<T>(pluginId: string, key: string, options?: UseStorageStateOptions<T>): [T, (value: T | ((val: T) => T)) => void];