@chatbi-v/core 2.0.0 → 2.0.2

package/README.md

@@ -2,35 +2,60 @@
 
 ChatBI 核心模块，提供插件管理、基础设施接口及通用 API 引擎。
 
-## 架构原则 (Architecture Principles)
+## 模块功能说明
 
-- **业务无关性 (Business Agnostic)**: `core` 包禁止包含任何具体的业务模型、业务逻辑或业务常量。
-- **共享契约 (Shared Contract)**: `core` 只定义通用的技术契约（如 `Plugin`, `StoragePort`, `ApiAdapter`）。
-- **插件驱动 (Plugin Driven)**: 所有的业务逻辑应由插件实现。
+- **微内核架构**: 实现插件的注册、生命周期管理与隔离。
+- **领域驱动设计**: 严格区分领域逻辑 (`domain`)、外部接口 (`ports`) 和具体实现 (`adapters`)。
+- **API 引擎**: 统一的 API 请求管理，支持同步、流式请求及拦截器。
+- **存储管理**: 提供隔离的存储适配器，确保插件数据互不干扰。
 
-## 目录结构
+## 安装和使用方法
 
-- `adapters/`: 基础设施的具体实现（如 LocalStorage, Axios）。
-- `api/`: 通用 API 请求引擎。
-- `domain/`: 核心领域逻辑（插件管理器、运行时、沙箱）。
-- `ports/`: 核心接口定义（端口）。
-
-## 功能
+### 安装
 
-- **PluginManager**: 管理插件的注册和生命周期。
-- **ApiEngine**: 统一的 API 请求管理。支持请求拦截器 (`ApiInterceptor`)，且拦截器能力已覆盖普通请求 (`call`) 和流式请求 (`stream`)。
-- **Sandbox**: 提供插件运行时的样式和全局变量隔离。
+```bash
+pnpm add @chatbi-v/core
+```
 
-## 使用方法
+### 使用示例
 
 ```typescript
-import { pluginManager } from '@chatbi/core';
+import { PluginManager, LocalStorageAdapter } from '@chatbi-v/core';
+
+// 初始化插件管理器
+const storage = new LocalStorageAdapter();
+const pluginManager = new PluginManager(storage);
 
-// 注册插件
+// 注册并初始化插件
 pluginManager.register({
   id: 'my-plugin',
-  init: (context) => {
-    console.log('Plugin initialized');
-  },
+  metadata: { name: 'My Plugin', type: 'business' },
+  onLoad: async (context) => {
+    console.log('Plugin loaded', context.pluginId);
+  }
 });
 ```
+
+## API 文档链接
+
+详细 API 文档请参考 [docs/index.html](https://github.com/your-repo/docs/index.html) 或运行 `npm run docs:dev` 本地查看。
+
+## 开发注意事项
+
+- **禁止引入 UI 框架**: 本模块为纯逻辑层，不得包含 React/AntD 等 UI 依赖。
+- **禁止反向依赖**: `core` 不得依赖 `plugins` 或 `apps` 中的任何代码。
+- **类型安全**: 优先使用 `ports` 中定义的接口。
+
+## 架构原则 (Architecture Principles)
+
+- **业务无关性 (Business Agnostic)**: `core` 包禁止包含任何具体的业务模型、业务逻辑或业务常量。
+- **共享契约 (Shared Contract)**: `core` 只定义通用的技术契约（如 `Plugin`, `StoragePort`, `ApiAdapter`）。
+- **插件驱动 (Plugin Driven)**: 所有的业务逻辑应由插件实现。
+
+## 目录结构
+
+- `adapters/`: 基础设施的具体实现（如 LocalStorage, Axios）。
+- `api/`: 通用 API 请求引擎。
+- `domain/`: 核心领域逻辑（插件管理器、运行时、沙箱）。
+- `ports/`: 核心接口定义（端口）。
+- `utils/`: 通用工具函数。

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

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

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

@@ -1,3 +1,8 @@
+/**
+ * @file plugin-manager.ts
+ * @description 插件管理器，负责插件的注册、生命周期管理、状态持久化及扩展点收集
+ * @author ChatBI Team
+ */
 import { DefaultEventBus } from '../event-bus';
 import { Plugin, PluginExtension, RouteConfig, SlotPosition } from '../ports/plugin-port';
 import { StoragePort } from '../ports/storage-port';
@@ -104,9 +109,6 @@ export declare class PluginManager {
      * @param slot 插槽位置
      */
     getExtensions(slot: SlotPosition | string): PluginExtension[];
-    /**
-     * 获取所有收集到的路由
-     */
     getRoutes(): RouteConfig[];
     /**
      * 注册插件
@@ -136,6 +138,10 @@ export declare class PluginManager {
      * @param config 插件配置
      */
     loadRemotePlugin(pluginId: string, url: string, config: any): Promise<Plugin | null>;
+    /**
+     * IIFE 模式加载插件
+     */
+    private loadIIFEPlugin;
     /**
      * 实例化插件
      */

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

@@ -1,3 +1,8 @@
+/**
+ * @file plugin-runtime.ts
+ * @description 插件运行时，封装单个插件的生命周期（load/mount/unmount）、沙箱环境和隔离上下文
+ * @author ChatBI Team
+ */
 import { Plugin, PluginContext } from '../ports/plugin-port';
 import { StorageManager } from './storage-manager';
 /**

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

@@ -1,6 +1,8 @@
 export interface PluginLoaderOptions {
     /** 插件发现规则 */
     discoveryRules?: any[];
+    /** 插件模块映射 (由 Vite import.meta.glob 生成) */
+    modules?: Record<string, () => Promise<any>>;
     /** 预注册的插件注册表 (可选，用于离线或手动加载) */
     registry?: Record<string, () => Promise<any>>;
     /** 插件配置映射 */

package/dist/index.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @file index.ts
+ * @description Core 模块入口文件，导出所有公共 API、领域逻辑、组件和 Hooks
+ * @author ChatBI Team
+ */
 export * from './ports/api-port';
 export * from './ports/event-bus-port';
 export * from './ports/plugin-port';
@@ -19,6 +24,7 @@ export * from './adapters/scoped-storage-adapter';
 export * from './event-bus';
 export * from './plugin-context';
 export * from './api';
+export * from './sandbox/proxy-sandbox';
 export * from './utils';
 export * from './hooks/use-storage-state';
 export * from './hooks/use-plugin-loader';

package/dist/index.mjs

@@ -18,6 +18,23 @@ var Slot = {
   RootLayout: "root-layout",
   Custom: "custom"
 };
+var BasePlugin = class {
+  /** 
+   * 插件 ID
+   * @description 自动从 metadata.id 获取
+   */
+  get id() {
+    return this.metadata.id;
+  }
+};
+function definePlugin(plugin) {
+  return {
+    ...plugin,
+    get id() {
+      return this.metadata.id;
+    }
+  };
+}
 
 // src/utils/logger.ts
 var LogLevel = /* @__PURE__ */ ((LogLevel2) => {
@@ -227,7 +244,7 @@ var PluginErrorBoundary = class extends Component {
 };
 
 // src/components/PluginSlot.tsx
-import { useMemo } from "react";
+import { useMemo, useState, useEffect } from "react";
 
 // src/adapters/local-storage-adapter.ts
 var LocalStorageAdapter = class {
@@ -764,18 +781,24 @@ var StorageManager = class {
         this.validateKey(pluginId, key, scope);
         try {
           const val = adapter.getItem(key);
-          if (val === null) {
-            const schema = this.schemas.get(pluginId)?.find((s) => s.key === key);
-            if (schema && schema.default !== void 0) {
-              return schema.default;
+          if (val !== null) {
+            try {
+              return JSON.parse(val);
+            } catch {
+              return val;
             }
-            return null;
           }
-          try {
-            return JSON.parse(val);
-          } catch {
-            return val;
+          if (scope === "plugin") {
+            const externalConfig = configManager.get(pluginId);
+            if (externalConfig && externalConfig[key] !== void 0) {
+              return externalConfig[key];
+            }
           }
+          const schema = this.schemas.get(pluginId)?.find((s) => s.key === key);
+          if (schema && schema.default !== void 0) {
+            return schema.default;
+          }
+          return null;
         } catch (e) {
           console.warn(`[Storage] Failed to read key "${key}"`, e);
           return null;
@@ -1012,14 +1035,21 @@ var PluginManager = class {
     });
     return extensions.sort((a, b) => (a.order || 0) - (b.order || 0));
   }
-  /**
-   * 获取所有收集到的路由
-   */
   getRoutes() {
     const activeRoutes = [];
     this.getPlugins().forEach((plugin) => {
       if (this.isPluginEnabled(plugin.id) && plugin.metadata.routes) {
-        activeRoutes.push(...plugin.metadata.routes);
+        const config = configManager.get(plugin.id) || {};
+        plugin.metadata.routes.forEach((route) => {
+          activeRoutes.push({
+            ...route,
+            meta: {
+              ...route.meta,
+              pluginId: plugin.id,
+              config
+            }
+          });
+        });
       }
     });
     return activeRoutes;
@@ -1037,42 +1067,48 @@ var PluginManager = class {
     if (this.plugins.has(plugin.id)) {
       return;
     }
-    if (plugin.metadata.storage) {
-      this.storageManager.registerSchema(plugin.id, plugin.metadata.storage);
+    const storageSchema = [
+      ...plugin.metadata.storage || [],
+      ...plugin.metadata.configuration?.map((c) => ({
+        key: c.key,
+        // 将 configuration 的 type 映射为 storage 支持的类型
+        type: c.type === "select" ? "string" : c.type,
+        label: c.label,
+        description: c.description,
+        default: c.default,
+        scope: "plugin"
+      })) || []
+    ];
+    if (storageSchema.length > 0) {
+      this.storageManager.registerSchema(plugin.id, storageSchema);
     }
     if (!this.pluginStates[plugin.id]) {
       this.pluginStates[plugin.id] = { enabled: true, order: 0 };
     }
-    const configFromStorage = {};
+    const metadataDefaults = {};
+    const userOverrides = {};
     const pluginStorage = this.storageManager.getPluginStorage(plugin.id);
     if (plugin.metadata.configuration) {
       plugin.metadata.configuration.forEach((item) => {
         if (item.default !== void 0) {
-          configFromStorage[item.key] = item.default;
+          metadataDefaults[item.key] = item.default;
         }
         try {
           const saved = pluginStorage.getItem(item.key);
           if (saved !== null) {
-            configFromStorage[item.key] = JSON.parse(saved);
+            userOverrides[item.key] = JSON.parse(saved);
           }
         } catch (e) {
         }
       });
     }
     const mergedConfig = {
+      ...metadataDefaults,
       ...plugin.defaultConfig,
-      ...configFromStorage,
-      ...configManager.get(plugin.id) || {}
+      ...configManager.get(plugin.id) || {},
+      ...userOverrides
     };
     configManager.set(plugin.id, mergedConfig);
-    if (mergedConfig) {
-      Object.entries(mergedConfig).forEach(([key, value]) => {
-        try {
-          pluginStorage.setItem(key, JSON.stringify(value));
-        } catch (e) {
-        }
-      });
-    }
     switch (plugin.metadata.type) {
       case "business":
         this.handleBusinessPlugin(plugin);
@@ -1133,7 +1169,9 @@ var PluginManager = class {
       const runtime = this.runtimes.get(id);
       if (runtime) {
         try {
+          console.log(`[PluginManager] invoking onLoad for ${id}`);
           await runtime.load();
+          console.log(`[PluginManager] onLoad completed for ${id}`);
         } catch (e) {
           logger7.error(`\u63D2\u4EF6 ${id} \u52A0\u8F7D\u5931\u8D25:`, e);
         }
@@ -1240,31 +1278,38 @@ var PluginManager = class {
    */
   async loadRemotePlugin(pluginId, url, config) {
     logger7.info(`\u6B63\u5728\u4ECE ${url} \u52A0\u8F7D\u8FDC\u7A0B\u63D2\u4EF6 ${pluginId}...`);
+    if (config?.format === "iife") {
+      return this.loadIIFEPlugin(pluginId, url, config);
+    }
     try {
-      const module = await import(
-        /* @vite-ignore */
-        url
-      );
+      const dynamicImport = new Function("specifier", "return import(specifier)");
+      const module = await dynamicImport(url);
       return this.instantiatePlugin(pluginId, module, config);
     } catch (e) {
       logger7.warn(`ESM \u52A0\u8F7D\u5931\u8D25\uFF0C\u5C1D\u8BD5 IIFE \u52A0\u8F7D: ${pluginId}`);
-      return new Promise((resolve, reject) => {
-        const script = document.createElement("script");
-        script.src = url;
-        script.onload = () => {
-          const globalName = pluginId.replace(/[^a-zA-Z0-9]/g, "_");
-          const pluginModule = window[globalName];
-          if (pluginModule) {
-            resolve(this.instantiatePlugin(pluginId, pluginModule, config));
-          } else {
-            reject(new Error(`\u8FDC\u7A0B\u63D2\u4EF6 ${pluginId} \u52A0\u8F7D\u540E\u672A\u627E\u5230\u5168\u5C40\u53D8\u91CF ${globalName}`));
-          }
-        };
-        script.onerror = () => reject(new Error(`\u8FDC\u7A0B\u63D2\u4EF6 ${pluginId} \u52A0\u8F7D\u5931\u8D25: ${url}`));
-        document.head.appendChild(script);
-      });
+      return this.loadIIFEPlugin(pluginId, url, config);
     }
   }
+  /**
+   * IIFE 模式加载插件
+   */
+  loadIIFEPlugin(pluginId, url, config) {
+    return new Promise((resolve, reject) => {
+      const script = document.createElement("script");
+      script.src = url;
+      script.onload = () => {
+        const globalName = pluginId.replace(/[^a-zA-Z0-9]/g, "_");
+        const pluginModule = window[globalName];
+        if (pluginModule) {
+          resolve(this.instantiatePlugin(pluginId, pluginModule, config));
+        } else {
+          reject(new Error(`\u8FDC\u7A0B\u63D2\u4EF6 ${pluginId} \u52A0\u8F7D\u540E\u672A\u627E\u5230\u5168\u5C40\u53D8\u91CF ${globalName}`));
+        }
+      };
+      script.onerror = () => reject(new Error(`\u8FDC\u7A0B\u63D2\u4EF6 ${pluginId} \u52A0\u8F7D\u5931\u8D25: ${url}`));
+      document.head.appendChild(script);
+    });
+  }
   /**
    * 实例化插件
    */
@@ -1280,11 +1325,22 @@ var PluginManager = class {
       }
     }
     if (PluginClass) {
+      const isClass = typeof PluginClass === "function" && PluginClass.prototype;
+      if (isClass) {
+        logger7.warn(`\u63D2\u4EF6 ${pluginId} \u4F7F\u7528\u4E86\u7C7B\u5B9A\u4E49\u6A21\u5F0F\u3002\u5EFA\u8BAE\u7EDF\u4E00\u4F7F\u7528 definePlugin() \u5DE5\u5382\u6A21\u5F0F\u4EE5\u6D88\u9664\u6B67\u4E49\u5E76\u7B80\u5316\u4EE3\u7801\u3002`);
+      }
       const pluginInstance = typeof PluginClass === "function" ? new PluginClass() : PluginClass;
+      const isFilePath = pluginId.includes("/") && (pluginId.includes(".ts") || pluginId.includes(".tsx"));
+      if (!isFilePath && pluginId && pluginInstance.metadata) {
+        if (pluginInstance.metadata.id !== pluginId) {
+          pluginInstance.metadata.id = pluginId;
+        }
+      }
       if (!pluginInstance.id && pluginInstance.metadata?.id) {
-        pluginInstance.id = pluginInstance.metadata.id;
-      } else if (!pluginInstance.id) {
-        pluginInstance.id = pluginId;
+        try {
+          pluginInstance.id = pluginInstance.metadata.id;
+        } catch (e) {
+        }
       }
       if (config) {
         pluginInstance.defaultConfig = { ...pluginInstance.defaultConfig, ...config };
@@ -1324,6 +1380,13 @@ var PluginSlot = ({
   skeleton,
   fallback
 }) => {
+  const [, forceUpdate] = useState({});
+  useEffect(() => {
+    const unsubscribe = pluginManager.subscribe(() => {
+      forceUpdate({});
+    });
+    return unsubscribe;
+  }, []);
   const extensions = pluginManager.getExtensions(slot);
   const systemConfig = pluginManager.getSystemConfig("title") ? {
     title: pluginManager.getSystemConfig("title"),
@@ -1373,8 +1436,14 @@ var BlockSkeleton = ({ className }) => /* @__PURE__ */ jsx4("div", { className:
 
 // src/domain/auto-loader.ts
 var logger8 = createLogger("AutoLoader");
+var DEFAULT_RULES = [
+  { pathSegment: "@chatbi-plugins", idPrefix: "@chatbi-v/plugin" },
+  { pathSegment: "@chatbi-apps", idPrefix: "@chatbi-v/app" },
+  { pathSegment: "packages/plugins", idPrefix: "@chatbi-v/plugin" },
+  { pathSegment: "packages/apps", idPrefix: "@chatbi-v/app" }
+];
 var resolvePluginRegistry = (options) => {
-  const { modules, baseUrl, rules } = options;
+  const { modules, rules = DEFAULT_RULES } = options;
   const registry = {};
   const compiledRules = rules.map((rule) => {
     const escapedSegment = rule.pathSegment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
@@ -1383,36 +1452,28 @@ var resolvePluginRegistry = (options) => {
       regex: new RegExp(`${escapedSegment}/([^/]+)/src/index`)
     };
   });
-  for (const relativePath in modules) {
+  for (const path in modules) {
     try {
-      const path = new URL(relativePath, baseUrl).pathname;
+      let pluginId = null;
       for (const rule of compiledRules) {
         const match = path.match(rule.regex);
         if (match && match[1]) {
-          const dirName = match[1];
-          const pluginId = `${rule.idPrefix}-${dirName}`;
-          registry[pluginId] = modules[relativePath];
-          logger8.info(`Found plugin: ${pluginId} at ${path}`);
+          pluginId = `${rule.idPrefix}-${match[1]}`;
+          logger8.info(`\u89E3\u6790\u8DEF\u5F84\u6210\u529F: ${path} -> ${pluginId}`);
           break;
         }
       }
+      if (pluginId) {
+        registry[pluginId] = modules[path];
+      } else {
+        logger8.warn(`\u65E0\u6CD5\u4ECE\u8DEF\u5F84\u89E3\u6790\u63D2\u4EF6 ID: ${path}\uFF0C\u8BF7\u68C0\u67E5\u662F\u5426\u7B26\u5408\u547D\u540D\u7EA6\u5B9A\u3002`);
+      }
     } catch (e) {
-      logger8.error(`Failed to resolve plugin at ${relativePath}:`, e);
+      logger8.error(`\u89E3\u6790\u63D2\u4EF6\u8DEF\u5F84\u5931\u8D25: ${path}`, e);
     }
   }
   return registry;
 };
-var discoverPlugins = (rules, baseUrl) => {
-  const modules = import.meta.glob([
-    "../../../../packages/plugins/*/src/index.{ts,tsx}",
-    "../../../../apps/*/src/index.{ts,tsx}"
-  ]);
-  return resolvePluginRegistry({
-    modules,
-    baseUrl,
-    rules
-  });
-};
 
 // src/domain/models.ts
 var SUCCESS_CODE = "000000";
@@ -1853,7 +1914,7 @@ var dateUtils = {
 var version = "1.0.0";
 
 // src/hooks/use-storage-state.ts
-import { useCallback, useState } from "react";
+import { useCallback, useState as useState2 } from "react";
 function useStorageState(pluginId, key, options = {}) {
   const { defaultValue, scope = "plugin" } = options;
   const storageManager = pluginManager.getStorageManager();
@@ -1861,7 +1922,7 @@ function useStorageState(pluginId, key, options = {}) {
     const contextStorage = storageManager.getContextStorage(pluginId);
     return scope === "shared" ? contextStorage.shared : contextStorage;
   }, [pluginId, scope, storageManager]);
-  const [state, setState] = useState(() => {
+  const [state, setState] = useState2(() => {
     try {
       if (typeof window === "undefined") return defaultValue;
       const storage = getStorage();
@@ -1886,13 +1947,13 @@ function useStorageState(pluginId, key, options = {}) {
 }
 
 // src/hooks/use-plugin-loader.ts
-import { useEffect, useRef, useState as useState2 } from "react";
+import { useEffect as useEffect2, useRef, useState as useState3 } from "react";
 var logger10 = createLogger("PluginLoader");
 var usePluginLoader = (options) => {
-  const [pluginsLoaded, setPluginsLoaded] = useState2(false);
-  const [pluginVersion, setPluginVersion] = useState2(0);
+  const [pluginsLoaded, setPluginsLoaded] = useState3(false);
+  const [pluginVersion, setPluginVersion] = useState3(0);
   const loadingRef = useRef(false);
-  useEffect(() => {
+  useEffect2(() => {
     const unsubscribe = pluginManager.subscribe(() => {
       logger10.debug("Plugin state changed, refreshing UI...");
       setPluginVersion((v) => v + 1);
@@ -1903,13 +1964,17 @@ var usePluginLoader = (options) => {
       try {
         const {
           discoveryRules = [],
+          modules = {},
           registry: manualRegistry = {},
           pluginConfigs,
           sharedContext = {},
           baseUrl = window.location.origin
         } = options;
         logger10.info("Starting to load plugins...");
-        const discoveredRegistry = discoveryRules.length > 0 ? discoverPlugins(discoveryRules, baseUrl) : {};
+        const discoveredRegistry = Object.keys(modules).length > 0 ? resolvePluginRegistry({
+          modules,
+          rules: discoveryRules.length > 0 ? discoveryRules : void 0
+        }) : {};
         const finalRegistry = { ...discoveredRegistry, ...manualRegistry };
         if (options.systemConfig) {
           const { configManager: configManager2 } = await import("./config-manager-ZARQENTB.mjs");
@@ -1940,6 +2005,7 @@ export {
   ApiProvider,
   AvatarSkeleton,
   AxiosAdapter,
+  BasePlugin,
   BlockSkeleton,
   ConfigManager,
   DefaultEventBus,
@@ -1953,6 +2019,7 @@ export {
   PluginRuntime,
   PluginSandbox,
   PluginSlot,
+  ProxySandbox,
   SUCCESS_CODE,
   ScopedStorageAdapter,
   ServiceRegistry,
@@ -1965,7 +2032,7 @@ export {
   configManager,
   createLogger,
   dateUtils,
-  discoverPlugins,
+  definePlugin,
   isMockMode,
   logger,
   normalizeParams,