@xpert-ai/plugin-sdk 0.0.1

package/src/lib/core/file-system.ts

@@ -0,0 +1,96 @@
+import fsPromises from 'fs/promises'
+import path from 'path'
+import { FileSystemPermission } from './permissions'
+
+
+/**
+ * Restricted FileSystem based on granted permissions
+ */
+export class XpFileSystem {
+  private allowedOps: Set<'read' | 'write' | 'delete' | 'list'>
+  private scope: string[] | undefined
+
+  constructor(permission: FileSystemPermission, private basePath: string, private baseUrl: string) {
+    this.allowedOps = new Set(permission.operations)
+    this.scope = permission.scope
+  }
+
+  /**
+   * Check if operation is allowed
+   */
+  private ensureAllowed(op: 'read' | 'write' | 'delete' | 'list') {
+    if (!this.allowedOps.has(op)) {
+      throw new Error(`Permission denied: ${op} operation not allowed`)
+    }
+  }
+
+  /**
+   * Check if path is within scope
+   */
+  private ensureInScope(targetPath: string) {
+    if (!this.scope || this.scope.length === 0) return
+    const resolved = path.resolve(targetPath)
+    for (const s of this.scope) {
+      const absScope = path.resolve(s)
+      if (resolved.startsWith(absScope)) return
+    }
+    throw new Error(`Permission denied: path "${targetPath}" is out of scope`)
+  }
+
+  fullPath(filePath: string): string {
+    return path.join(this.basePath, filePath)
+  }
+
+  /**
+   * Read file contents
+   */
+  async readFile(filePath: string, encoding: BufferEncoding = 'utf-8') {
+    this.ensureAllowed('read')
+    const fullPath = this.fullPath(filePath)
+    this.ensureInScope(fullPath)
+    return await fsPromises.readFile(fullPath)
+  }
+
+  /**
+   * Write file contents
+   */
+  async writeFile(filePath: string, content: string | Buffer): Promise<string> {
+    this.ensureAllowed('write')
+    const fullPath = this.fullPath(filePath)
+    this.ensureInScope(fullPath)
+    await fsPromises.mkdir(path.dirname(fullPath), { recursive: true })
+    await fsPromises.writeFile(fullPath, content)
+    const url = new URL(filePath, this.baseUrl)
+    return url.href
+  }
+
+  /**
+   * Delete a file
+   */
+  async deleteFile(filePath: string): Promise<void> {
+    this.ensureAllowed('delete')
+    this.ensureInScope(filePath)
+    await fsPromises.unlink(filePath)
+  }
+
+  /**
+   * List directory contents
+   */
+  async listDir(dirPath: string): Promise<string[]> {
+    this.ensureAllowed('list')
+    this.ensureInScope(dirPath)
+    return fsPromises.readdir(dirPath)
+  }
+
+  /**
+   * Utility: check if a file or directory exists
+   */
+  async exists(targetPath: string): Promise<boolean> {
+    try {
+      await fsPromises.access(targetPath)
+      return true
+    } catch {
+      return false
+    }
+  }
+}

package/src/lib/core/index.ts

@@ -0,0 +1,3 @@
+export * from './file-system'
+export * from './permissions'
+export * from './schema'

package/src/lib/core/permissions.ts

@@ -0,0 +1,97 @@
+/**
+ * ===============================
+ * Unified Permissions Definition
+ * ===============================
+ * Used by Agent / Plugin developers to declare required capabilities.
+ * Core system will check and inject allowed resources accordingly.
+ */
+
+/**
+ * Base Permission type
+ */
+export interface BasePermission {
+  type: string; // Discriminator
+  description?: string; // Optional description for UI
+}
+
+/**
+ * 1. LLM Permission
+ * Example: { type: 'llm', provider: 'openai', capability: 'vision' }
+ */
+export interface LLMPermission extends BasePermission {
+  type: 'llm';
+  provider?: string; // e.g. "openai", "anthropic", "azure", "ollama"
+  capability: 'text' | 'chat' | 'vision' | 'embedding';
+  scope?: string[]; // Allowed model names, e.g. ["gpt-4", "gpt-4-vision-preview"]
+  maxTokens?: number; // Maximum output tokens allowed
+  rateLimit?: { rps: number }; // Rate limit per second
+}
+
+/**
+ * 2. Vector Store Permission
+ * Example: { type: 'vectorstore', provider: 'pinecone', operations: ['insert', 'query'] }
+ */
+export interface VectorStorePermission extends BasePermission {
+  type: 'vectorstore';
+  provider: string; // "pinecone" | "milvus" | "chromadb" | ...
+  operations: Array<'insert' | 'query' | 'delete'>;
+  scope?: string[]; // Restrict to index / collection
+}
+
+/**
+ * 3. Knowledge Base Permission
+ * Example: { type: 'knowledge', operations: ['read', 'write'], scope: ['kb_123'] }
+ */
+export interface KnowledgePermission extends BasePermission {
+  type: 'knowledge';
+  operations: Array<'read' | 'write' | 'update' | 'delete'>;
+  scope?: string[]; // Restrict to certain KB IDs
+}
+
+/**
+ * 4. File System Permission
+ * Example: { type: 'filesystem', operations: ['read', 'write'], scope: ['/documents', '/images'] }
+ */
+export interface FileSystemPermission extends BasePermission {
+  type: 'filesystem';
+  operations: Array<'read' | 'write' | 'delete' | 'list'>;
+  scope?: string[]; // Restrict to certain directories or file types
+}
+
+/**
+ * 5. Integration Permission
+ * Example: { type: 'integration', service: 'feishu', operations: ['read', 'write'] }
+ */
+export interface IntegrationPermission extends BasePermission {
+  type: 'integration';
+  service: string; // e.g. 'slack', 'feishu', 'jira', 'sap', etc.
+  operations?: Array<'read' | 'write' | 'update' | 'delete'>;
+  scope?: string[];
+}
+
+// /**
+//  * 4. Document Permission
+//  * Example: { type: 'document', formats: ['pdf'], operations: ['load', 'transform'] }
+//  */
+// export interface DocumentPermission extends BasePermission {
+//   type: 'document';
+//   formats: string[]; // ['pdf', 'pptx', 'docx', 'image', 'html', 'md']
+//   operations: Array<'load' | 'transform' | 'ocr' | 'imageUnderstanding'>;
+// }
+
+/**
+ * Union type for all permissions
+ */
+export type Permission =
+  | LLMPermission
+  | VectorStorePermission
+  | KnowledgePermission
+  | FileSystemPermission
+  | IntegrationPermission
+//   | DocumentPermission
+//   | ExternalPermission;
+
+/**
+ * Permissions array type
+ */
+export type Permissions = Permission[];

package/src/lib/core/schema.ts

@@ -0,0 +1,23 @@
+/**
+ * 通用 UI Schema 字段定义
+ */
+export interface ISchemaUIBase {
+  component: string;       // UI 组件类型
+  label?: string;          // 字段标签
+  description?: string;    // 字段说明
+  placeholder?: string;    // 输入占位符
+  order?: number;          // UI 显示顺序
+  required?: boolean;      // 是否必填
+  visibleWhen?: Record<string, any>; // 条件渲染
+  enabledWhen?: Record<string, any>; // 条件启用
+}
+
+/**
+ * Secret 字段扩展
+ */
+export interface ISchemaSecretField extends ISchemaUIBase {
+  component: 'secretInput';   // 固定组件类型
+  revealable?: boolean;       // 是否允许明文显示（👁 按钮）
+  maskSymbol?: string;        // 遮罩符号（默认 *）
+  persist?: boolean;          // 是否持久保存，false 表示仅运行时使用
+}

package/src/lib/integration/index.ts

@@ -0,0 +1,3 @@
+export * from './strategy.decorator'
+export * from './strategy.interface'
+export * from './strategy.registry'

package/src/lib/integration/strategy.decorator.ts

@@ -0,0 +1,6 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const INTEGRATION_STRATEGY = 'INTEGRATION_STRATEGY';
+
+export const IntegrationStrategyKey = (provider: string) =>
+  SetMetadata(INTEGRATION_STRATEGY, provider);

package/src/lib/integration/strategy.interface.ts

@@ -0,0 +1,10 @@
+import { IIntegration, TIntegrationProvider } from '@metad/contracts'
+
+export type TIntegrationStrategyParams = {
+  query: string
+}
+
+export interface IntegrationStrategy<T = unknown> {
+  meta: TIntegrationProvider
+  execute(integration: IIntegration<T>, payload: TIntegrationStrategyParams): Promise<any>
+}

package/src/lib/integration/strategy.registry.ts

@@ -0,0 +1,12 @@
+import { Injectable } from '@nestjs/common'
+import { DiscoveryService, Reflector } from '@nestjs/core'
+import { BaseStrategyRegistry } from '../strategy'
+import { INTEGRATION_STRATEGY } from './strategy.decorator'
+import { IntegrationStrategy } from './strategy.interface'
+
+@Injectable()
+export class IntegrationStrategyRegistry extends BaseStrategyRegistry<IntegrationStrategy> {
+  constructor(discoveryService: DiscoveryService, reflector: Reflector) {
+    super(INTEGRATION_STRATEGY, discoveryService, reflector)
+  }
+}

package/src/lib/knowledge/index.ts

@@ -0,0 +1,3 @@
+export * from './knowledge-strategy.decorator'
+export * from './knowledge-strategy.interface'
+export * from './knowledge-strategy.registry'

package/src/lib/knowledge/knowledge-strategy.decorator.ts

@@ -0,0 +1,6 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const KNOWLEDGE_STRATEGY = 'KNOWLEDGE_STRATEGY';
+
+export const KnowledgeStrategyKey = (provider: string) =>
+  SetMetadata(KNOWLEDGE_STRATEGY, provider);

package/src/lib/knowledge/knowledge-strategy.interface.ts

@@ -0,0 +1,15 @@
+import { IIntegration } from '@metad/contracts'
+import { Document } from 'langchain/document'
+
+export type TKnowledgeStrategyParams = {
+	query: string;
+	k: number;
+	filter: Record<string, any>
+	options: {
+		knowledgebaseId: string
+	}
+}
+
+export interface KnowledgeStrategy {
+	execute(integration: IIntegration, payload: TKnowledgeStrategyParams): Promise<{ chunks: [Document, number][] }>
+}

package/src/lib/knowledge/knowledge-strategy.registry.ts

@@ -0,0 +1,36 @@
+import { KnowledgeProviderEnum } from '@metad/contracts'
+import { Injectable, OnModuleInit } from '@nestjs/common'
+import { DiscoveryService, Reflector } from '@nestjs/core'
+import { KNOWLEDGE_STRATEGY } from './knowledge-strategy.decorator'
+import { KnowledgeStrategy } from './knowledge-strategy.interface'
+
+@Injectable()
+export class KnowledgeStrategyRegistry implements OnModuleInit {
+	private strategies = new Map<KnowledgeProviderEnum, KnowledgeStrategy>()
+
+	constructor(
+		private discoveryService: DiscoveryService,
+		private reflector: Reflector
+	) {}
+
+	onModuleInit() {
+		const providers = this.discoveryService.getProviders()
+		for (const wrapper of providers) {
+			const { instance } = wrapper
+			if (!instance) continue
+
+			const type = this.reflector.get<KnowledgeProviderEnum>(KNOWLEDGE_STRATEGY, instance.constructor)
+			if (type) {
+				this.strategies.set(type, instance as KnowledgeStrategy)
+			}
+		}
+	}
+
+	get(type: KnowledgeProviderEnum): KnowledgeStrategy {
+		const strategy = this.strategies.get(type)
+		if (!strategy) {
+			throw new Error(`No strategy found for type ${type}`)
+		}
+		return strategy
+	}
+}

package/src/lib/logger.ts

@@ -0,0 +1,18 @@
+import { Logger } from '@nestjs/common';
+import type { PluginLogger } from './types';
+
+export function createPluginLogger(scope: string, baseMeta: Record<string, any> = {}): PluginLogger {
+  const nestLogger = new Logger(scope);
+  const wrap = (level: keyof Logger, msg: string, meta?: any) => {
+    const payload = meta ? { ...baseMeta, ...meta } : baseMeta;
+    // 保持与 Nest Logger 接口对齐
+    (nestLogger as any)[level]?.(msg + (Object.keys(payload).length ? ` ${JSON.stringify(payload)}` : ''));
+  };
+  return {
+    child(meta) { return createPluginLogger(scope, { ...baseMeta, ...meta }); },
+    debug: (msg, meta) => wrap('debug' as any, msg, meta),
+    log:   (msg, meta) => wrap('log', msg, meta),
+    warn:  (msg, meta) => wrap('warn', msg, meta),
+    error: (msg, meta) => wrap('error', msg, meta),
+  };
+}

package/src/lib/plugin-metadata.ts

@@ -0,0 +1,20 @@
+/**
+ * Metadata keys used in plugins for defining various aspects like entities, subscribers, and configurations.
+ */
+export const PLUGIN_METADATA = {
+	/**
+	 * Key representing the entities registered within the plugin.
+	 */
+	ENTITIES: 'entities',
+
+	/**
+	 * Key representing event subscribers within the plugin.
+	 */
+	SUBSCRIBERS: 'subscribers',
+
+} as const;
+
+/**
+ * Type definition for valid plugin metadata keys.
+ */
+export type PluginMetadataKey = (typeof PLUGIN_METADATA)[keyof typeof PLUGIN_METADATA];

package/src/lib/plugin.hook.ts

@@ -0,0 +1,54 @@
+/**
+ * Interface for plugins with a bootstrap lifecycle method.
+ */
+export interface IOnPluginBootstrap {
+    /**
+     * Called when the plugin is being initialized.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginBootstrap(): void | Promise<void>;
+}
+
+/**
+ * Interface for plugins with a destroy lifecycle method.
+ */
+export interface IOnPluginDestroy {
+    /**
+     * Called when the plugin is being destroyed.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginDestroy(): void | Promise<void>;
+}
+
+/**
+ * Interface for plugins supporting basic seed operations.
+ */
+export interface IOnPluginWithBasicSeed {
+    /**
+     * Invoked when seeding basic plugin data.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginBasicSeed(): void | Promise<void>;
+}
+
+/**
+ * Interface for plugins supporting default seed operations.
+ */
+export interface IOnPluginWithDefaultSeed {
+    /**
+     * Invoked when seeding default plugin data.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginDefaultSeed(): void | Promise<void>;
+}
+
+/**
+ * Interface for plugins supporting random seed operations.
+ */
+export interface IOnPluginWithRandomSeed {
+    /**
+     * Invoked when seeding random plugin data.
+     * @returns A void or a Promise representing the completion of the operation.
+     */
+    onPluginRandomSeed(): void | Promise<void>;
+}

package/src/lib/plugin.interface.ts

@@ -0,0 +1,67 @@
+import { ModuleMetadata, Type } from '@nestjs/common';
+
+/**
+ * Metadata definition for a plugin in NestJS.
+ */
+export interface PluginMetadata extends ModuleMetadata {
+	/**
+	 * List of entities injected by the plugin.
+	 */
+	entities?: Array<Type<any>> | (() => Array<Type<any>>);
+
+	/**
+	 * List of subscribers injected by the plugin.
+	 */
+	subscribers?: Array<Type<any>> | (() => Array<Type<any>>);
+}
+
+/**
+ * Interface for plugins with a bootstrap lifecycle method.
+ */
+export interface IOnPluginBootstrap {
+	/**
+	 * Called when the plugin is being initialized.
+	 * @returns A void or a Promise representing the completion of the operation.
+	 */
+	onPluginBootstrap(): void | Promise<void>;
+}
+
+/**
+ * Interface for plugins with a destroy lifecycle method.
+ */
+export interface IOnPluginDestroy {
+	/**
+	 * Called when the plugin is being destroyed.
+	 * @returns A void or a Promise representing the completion of the operation.
+	 */
+	onPluginDestroy(): void | Promise<void>;
+}
+
+/**
+ * Interface for plugins supporting various seed operations.
+ */
+export interface IOnPluginSeedable {
+	/**
+	 * Invoked when seeding basic plugin data.
+	 * @returns A void or a Promise representing the completion of the operation.
+	 */
+	onPluginBasicSeed?(): void | Promise<void>;
+
+	/**
+	 * Invoked when seeding default plugin data.
+	 * @returns A void or a Promise representing the completion of the operation.
+	 */
+	onPluginDefaultSeed?(): void | Promise<void>;
+
+	/**
+	 * Invoked when seeding random plugin data.
+	 * @returns A void or a Promise representing the completion of the operation.
+	 */
+	onPluginRandomSeed?(): void | Promise<void>;
+}
+
+/**
+ * Represents the combined lifecycle methods for a plugin.
+ * This type combines interfaces for initializing and destroying a plugin.
+ */
+export type PluginLifecycleMethods = IOnPluginBootstrap & IOnPluginDestroy & IOnPluginSeedable;

package/src/lib/plugin.ts

@@ -0,0 +1,32 @@
+import { Module } from '@nestjs/common';
+import { MODULE_METADATA } from '@nestjs/common/constants';
+import { pick } from 'underscore';
+import { PluginMetadata } from './plugin.interface';
+import { PLUGIN_METADATA } from './plugin-metadata';
+
+/**
+ * Decorator function for extending NestJS features with additional metadata.
+ *
+ * @param pluginMetadata Metadata to be applied to the target class.
+ * @returns Class decorator function.
+ */
+export function XpertServerPlugin(pluginMetadata: PluginMetadata): ClassDecorator {
+	return (targetClass) => {
+		// Iterate over properties in PLUGIN_METADATA
+		for (const metadataProperty of Object.values(PLUGIN_METADATA)) {
+			const property = metadataProperty as keyof PluginMetadata;
+
+			// Check if the property exists in pluginMetadata and is not undefined
+			if (property in pluginMetadata && pluginMetadata[property] !== undefined) {
+				// Set metadata on the target class using Reflect
+				Reflect.defineMetadata(property, pluginMetadata[property] || [], targetClass);
+			}
+		}
+
+		// Pick relevant metadata from pluginMetadata based on MODULE_METADATA values
+		const metadata = pick(pluginMetadata, Object.values(MODULE_METADATA) as string[]);
+
+		// Apply the Module decorator with the picked metadata
+		Module(metadata)(targetClass);
+	};
+}

package/src/lib/rag/image/index.ts

@@ -0,0 +1,3 @@
+export * from './strategy.decorator'
+export * from './strategy.interface'
+export * from './strategy.registry'

package/src/lib/rag/image/strategy.decorator.ts

@@ -0,0 +1,9 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const IMAGE_UNDERSTANDING_STRATEGY = 'IMAGE_UNDERSTANDING_STRATEGY';
+
+/**
+ * Decorator to mark a provider as an Image Understanding Strategy
+ */
+export const ImageUnderstandingStrategy = (provider: string) =>
+  SetMetadata(IMAGE_UNDERSTANDING_STRATEGY, provider);

package/src/lib/rag/image/strategy.interface.ts

@@ -0,0 +1,42 @@
+import { BaseChatModel } from '@langchain/core/language_models/chat_models'
+import { IDocumentUnderstandingProvider } from '@metad/contracts'
+import { Document } from 'langchain/document'
+import { Permissions, XpFileSystem } from '../../core/index'
+import { ChunkMetadata, TDocumentAsset } from '../types'
+
+export type TImageUnderstandingConfig = {
+  stage: 'test' | 'prod'
+  visionModel: BaseChatModel
+  permissions?: {
+    fileSystem?: XpFileSystem
+  }
+}
+
+export type TImageUnderstandingInput = {
+  chunks: Document<ChunkMetadata>[] // 来自 Loader 的初始文档块
+  files: TDocumentAsset[] // 需要处理的图像文件
+}
+
+export type TImageUnderstandingResult = {
+  chunks: Document<Partial<ChunkMetadata>>[]
+  pages?: Document<Partial<ChunkMetadata>>[]
+  metadata: any // 额外的元数据（例如模型名称、处理耗时）
+}
+
+export interface IImageUnderstandingStrategy<TConfig extends TImageUnderstandingConfig = TImageUnderstandingConfig> {
+  readonly permissions: Permissions
+  /**
+   * Metadata about this strategy
+   */
+  readonly meta: IDocumentUnderstandingProvider
+
+  /**
+   * Validate the configuration
+   */
+  validateConfig(config: TConfig): Promise<void>
+
+  /**
+   * Understand image files (e.g., OCR, VLM, Chart Parsing)
+   */
+  understandImages(params: TImageUnderstandingInput, config: TConfig): Promise<TImageUnderstandingResult>
+}

package/src/lib/rag/image/strategy.registry.ts

@@ -0,0 +1,17 @@
+import { Injectable } from '@nestjs/common';
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../../strategy';
+import { IMAGE_UNDERSTANDING_STRATEGY } from './strategy.decorator';
+import { IImageUnderstandingStrategy, TImageUnderstandingConfig } from './strategy.interface';
+
+@Injectable()
+export class ImageUnderstandingRegistry<TConfig extends TImageUnderstandingConfig = TImageUnderstandingConfig>
+  extends BaseStrategyRegistry<IImageUnderstandingStrategy<TConfig>> 
+{
+  constructor(
+    discoveryService: DiscoveryService,
+    reflector: Reflector
+  ) {
+    super(IMAGE_UNDERSTANDING_STRATEGY, discoveryService, reflector);
+  }
+}

package/src/lib/rag/index.ts

@@ -0,0 +1,6 @@
+export * from './textsplitter/index'
+export * from './source/index'
+export * from './transformer/index'
+export * from './retriever/index'
+export * from './types'
+export * from './image/index'

package/src/lib/rag/retriever/index.ts

@@ -0,0 +1,3 @@
+export * from './strategy.decorator'
+export * from './strategy.interface'
+export * from './strategy.registry'

package/src/lib/rag/retriever/strategy.decorator.ts

@@ -0,0 +1,9 @@
+import { SetMetadata } from '@nestjs/common';
+
+export const RETRIEVER_STRATEGY = 'RETRIEVER_STRATEGY';
+
+/**
+ * Decorator to mark a provider as a Retriever Strategy
+ */
+export const RetrieverStrategy = (provider: string) =>
+  SetMetadata(RETRIEVER_STRATEGY, provider);

package/src/lib/rag/retriever/strategy.interface.ts

@@ -0,0 +1,32 @@
+import { VectorStore } from '@langchain/core/vectorstores'
+import { I18nObject } from '@metad/contracts'
+import { Document } from 'langchain/document'
+
+export type TRetrieverConfig = {
+  vectorStore: VectorStore
+}
+
+export interface IRetrieverStrategy<TConfig extends TRetrieverConfig = TRetrieverConfig> {
+  /**
+   * Metadata about this retriever
+   */
+  readonly meta: {
+    name: string
+    label: I18nObject
+    configSchema: any
+    icon: {
+      svg?: string
+      color?: string
+    }
+  }
+
+  /**
+   * Validate the configuration
+   */
+  validateConfig(config: TConfig): Promise<void>;
+
+  /**
+   * Retrieve relevant documents for a given query
+   */
+  retrieve(query: string, options?: TConfig): Promise<{ documents: Document[] }>;
+}

package/src/lib/rag/retriever/strategy.registry.ts

@@ -0,0 +1,12 @@
+import { Injectable } from '@nestjs/common'
+import { DiscoveryService, Reflector } from '@nestjs/core'
+import { BaseStrategyRegistry } from '../../strategy'
+import { RETRIEVER_STRATEGY } from './strategy.decorator'
+import { IRetrieverStrategy } from './strategy.interface'
+
+@Injectable()
+export class RetrieverRegistry extends BaseStrategyRegistry<IRetrieverStrategy> {
+  constructor(discoveryService: DiscoveryService, reflector: Reflector) {
+    super(RETRIEVER_STRATEGY, discoveryService, reflector)
+  }
+}