@xpert-ai/plugin-sdk 0.0.1 → 0.0.2

package/SCHEMA_SPECIFICATION.md

@@ -1,332 +0,0 @@
-# 🔧 Schema UI 扩展规范
-
-:::tip
-设计一套 通用的 schema UI 扩展规范
-:::
-
-👌好的，我来帮你设计一套 **通用的 Schema UI 扩展规范**，可以应用在你的插件系统所有配置 schema 中，让前端渲染时有统一的规则。
-
----
-
-在 JSON Schema 基础上扩展一个保留字段：
-
-```json
-"x-ui": { ... }
-```
-
-前端 UI 渲染器根据 `x-ui` 的内容决定用什么组件、怎么展示、怎么动态联动。
-
----
-
-## 1. 基础字段
-
-| 字段名            | 类型     | 说明                                                                                                                       |
-| -------------- | ------ | ------------------------------------------------------------------------------------------------------------------------ |
-| `component`    | string | 指定 UI 组件类型，如 `textInput`, `textarea`, `select`, `switch`, `slider`, `promptEditor`, `modelProviderSelect`, `modelSelect` |
-| `label`        | string | UI 展示的标签                                                                                                                 |
-| `description`  | string | UI 展示的帮助文本，优先覆盖 schema.description                                                                                       |
-| `placeholder`  | string | 输入占位符                                                                                                                    |
-| `defaultValue` | any    | 默认值，优先覆盖 schema.default                                                                                                  |
-| `order`        | number | 字段在 UI 中的展示顺序                                                                                                            |
-
----
-
-## 2. 数据源相关
-
-| 字段名          | 类型     | 说明                                                         |
-| ------------ | ------ | ---------------------------------------------------------- |
-| `options`    | array  | 静态选项（下拉框、多选框等），形如 `[{ label: 'OpenAI', value: 'openai' }]` |
-| `dataSource` | string | 动态选项来源标识，如 `"system.providers"`, `"system.models"`         |
-| `dependency` | string | 依赖其他字段的值来过滤选项，如 `"provider"`                               |
-| `mapping`    | object | 映射关系，例如 `{ label: 'name', value: 'id' }`                   |
-
----
-
-## 3. 验证与交互
-
-| 字段名           | 类型      | 说明                                           |
-| ------------- | ------- | -------------------------------------------- |
-| `required`    | boolean | 是否必填（优先覆盖 schema.required）                   |
-| `visibleWhen` | object  | 条件渲染，只有满足条件才显示字段，例如 `{ provider: 'openai' }` |
-| `enabledWhen` | object  | 条件启用，例如 `{ useCustomPrompt: true }`          |
-| `maxLength`   | number  | 输入最大长度                                       |
-| `minLength`   | number  | 输入最小长度                                       |
-| `regex`       | string  | 自定义正则校验规则                                    |
-
----
-
-## 4. 特殊组件约定
-
-### `modelProviderSelect`
-
-* 用于选择模型提供商（OpenAI、Anthropic、Azure、Ollama 等）
-* `dataSource = "system.providers"`
-
-### `modelSelect`
-
-* 用于选择具体模型
-* 需要依赖 `provider`
-* `dataSource = "system.models"`
-* `dependency = "provider"`
-
-### `promptEditor`
-
-* 用于编辑 Prompt，支持多行、语法高亮、变量插值
-
-### `jsonEditor`
-
-* 用于编辑 JSON 对象，带格式校验
-
-### `codeEditor`
-
-* 用于编辑代码（支持语言高亮，如 js, ts, python）
-
----
-
-## 5. 示例 Schema
-
-```ts
-configSchema: {
-  type: 'object',
-  properties: {
-    provider: {
-      type: 'string',
-      description: '模型提供商',
-      enum: ['openai', 'anthropic', 'azure', 'ollama'],
-      'x-ui': {
-        component: 'modelProviderSelect',
-        label: 'Provider',
-        order: 1,
-        dataSource: 'system.providers'
-      }
-    },
-    model: {
-      type: 'string',
-      description: '大模型名称',
-      default: 'gpt-4-vision-preview',
-      'x-ui': {
-        component: 'modelSelect',
-        label: 'Model',
-        order: 2,
-        dependency: 'provider',
-        dataSource: 'system.models'
-      }
-    },
-    prompt: {
-      type: 'string',
-      default: 'Describe this image in detail.',
-      description: '提示词',
-      'x-ui': {
-        component: 'promptEditor',
-        label: 'Prompt',
-        order: 3,
-        placeholder: '请输入提示词，可使用 {{variables}} 占位符'
-      }
-    },
-    temperature: {
-      type: 'number',
-      default: 0.7,
-      'x-ui': {
-        component: 'slider',
-        label: 'Temperature',
-        order: 4,
-        min: 0,
-        max: 1,
-        step: 0.1
-      }
-    },
-    advanced: {
-      type: 'object',
-      'x-ui': {
-        component: 'jsonEditor',
-        label: 'Advanced Config',
-        order: 5,
-        visibleWhen: { provider: 'openai' }
-      }
-    }
-  },
-  required: ['provider', 'model']
-}
-```
-
----
-
-这样一来：
-
-* 前端 UI 渲染器只需要识别 `x-ui.component`，其余逻辑由 `x-ui` 字段驱动。
-* 插件开发者只需写 schema，就能自动获得智能化配置体验。
-* 扩展性强，可以统一适配未来的 Embedding、OCR、VLM、VectorStore 插件。
-
-## 如何表示 SECRET 的input 字段
-
-好问题 👍，**SECRET 类型的字段**（比如 API Key、Token、密码）在 schema UI 里需要特殊处理：
-
-1. **前端渲染时要显示为密码输入框**（`type="password"` 或遮罩）。
-2. **存储时需要区分**：不回显原始值，而是用 `"******"` 或空值占位。
-3. **Schema 中可以显式标记**，让前端 UI 渲染器知道这是一个密钥字段。
-
----
-
-## 扩展规范方案
-
-在 `x-ui` 里增加 `component: "secretInput"`，并支持以下属性：
-
-| 字段名           | 类型      | 说明                          |
-| ------------- | ------- | --------------------------- |
-| `component`   | string  | 固定为 `"secretInput"`，渲染密码输入框 |
-| `label`       | string  | 字段标签                        |
-| `description` | string  | 字段说明                        |
-| `placeholder` | string  | 占位符（如 `请输入 API Key`）        |
-| `revealable`  | boolean | 是否允许用户点按钮临时查看明文             |
-| `maskSymbol`  | string  | 遮罩符号（默认 `*`）                |
-| `persist`     | boolean | 是否持久保存，false 时表示仅运行时使用，不落盘  |
-
----
-
-## 示例 Schema
-
-```ts
-configSchema: {
-  type: 'object',
-  properties: {
-    apiKey: {
-      type: 'string',
-      description: 'OpenAI API Key',
-      'x-ui': {
-        component: 'secretInput',
-        label: 'API Key',
-        placeholder: '请输入您的 OpenAI API Key',
-        revealable: true,
-        maskSymbol: '*',
-        persist: true
-      }
-    },
-    provider: {
-      type: 'string',
-      enum: ['openai', 'anthropic', 'azure'],
-      'x-ui': {
-        component: 'modelProviderSelect',
-        label: 'Provider'
-      }
-    }
-  },
-  required: ['apiKey', 'provider']
-}
-```
-
----
-
-## 前端渲染效果
-
-* `apiKey` 显示为 **密码输入框**，默认遮罩显示。
-* 如果 `revealable: true`，UI 上有 👁 按钮，用户可切换显示/隐藏。
-* 编辑配置时，如果后端返回 `"******"` 代表已有值，用户不改就继续使用原值。
-
----
-
-## 额外安全考虑
-
-* 前端表单提交时，如果 `apiKey === "******"`，表示不修改，后端应保留旧值。
-* 如果提交了新值，则后端替换旧值。
-* 日志、导出配置时跳过 SECRET 字段。
-
----
-
-要不要我帮你把 **SECRET 字段** 再抽象成一个通用接口（比如 `ISchemaSecretField`），这样和普通字段区分得更清晰？
-
-## 抽象成一个通用接口
-
-👌好的，我们把 **SECRET 字段**抽象成一个通用接口，既能和普通字段保持一致，又能明确标识“这是一个需要特殊处理的敏感字段”。
-
----
-
-# 🔐 通用接口设计
-
-```ts
-/**
- * 通用 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 表示仅运行时使用
-}
-```
-
-这样 SECRET 字段就和普通 UI 字段继承同一套规范，只是 **多了一些敏感信息处理的扩展属性**。
-
----
-
-# 🔧 使用示例
-
-```ts
-configSchema: {
-  type: 'object',
-  properties: {
-    apiKey: {
-      type: 'string',
-      description: 'OpenAI API Key',
-      'x-ui': <ISchemaSecretField>{
-        component: 'secretInput',
-        label: 'API Key',
-        placeholder: '请输入您的 OpenAI API Key',
-        revealable: true,
-        maskSymbol: '*',
-        persist: true
-      }
-    },
-    provider: {
-      type: 'string',
-      enum: ['openai', 'anthropic', 'azure'],
-      'x-ui': {
-        component: 'modelProviderSelect',
-        label: 'Provider'
-      }
-    }
-  },
-  required: ['apiKey', 'provider']
-}
-```
-
----
-
-# 🔒 前端处理规范
-
-1. **渲染时**：
-
-   * `secretInput` 渲染为密码框（`type=password`）。
-   * 如果 `revealable: true`，增加 👁 切换按钮。
-
-2. **加载配置时**：
-
-   * 后端返回 `******` 代表已有值，前端不展示真实内容。
-
-3. **保存配置时**：
-
-   * 如果提交的值仍为 `******` → 保持旧值不变。
-   * 如果提交了新值 → 更新存储并覆盖旧值。
-
-4. **导出配置/日志**：
-
-   * 忽略 SECRET 字段或输出 `******`，避免泄露。
-
----
-
-这样以后 `secretInput` 就是一个 **一级公民 UI 组件**，和 `textInput`、`select` 一样可以被 schema 统一驱动。
-
-要不要我再帮你定义一个 **完整的 ISchemaUIComponent 联合类型**，把所有 `x-ui` 组件（select、slider、secretInput、promptEditor 等）都规范起来？

package/jest.config.ts

@@ -1,28 +0,0 @@
-/* eslint-disable */
-import { readFileSync } from 'fs'
-
-// Reading the SWC compilation config and remove the "exclude"
-// for the test files to be compiled by SWC
-const { exclude: _, ...swcJestConfig } = JSON.parse(readFileSync(`${__dirname}/.swcrc`, 'utf-8'))
-
-// disable .swcrc look-up by SWC core because we're passing in swcJestConfig ourselves.
-// If we do not disable this, SWC Core will read .swcrc and won't transform our test files due to "exclude"
-if (swcJestConfig.swcrc === undefined) {
-  swcJestConfig.swcrc = false
-}
-
-// Uncomment if using global setup/teardown files being transformed via swc
-// https://nx.dev/packages/jest/documents/overview#global-setup/teardown-with-nx-libraries
-// jest needs EsModule Interop to find the default exported setup/teardown functions
-// swcJestConfig.module.noInterop = false;
-
-export default {
-  displayName: 'plugin-sdk',
-  preset: '../../jest.preset.js',
-  transform: {
-    '^.+\\.[tj]s$': ['@swc/jest', swcJestConfig]
-  },
-  moduleFileExtensions: ['ts', 'js', 'html'],
-  testEnvironment: 'node',
-  coverageDirectory: '../../coverage/packages/plugin-sdk'
-}

package/project.json

@@ -1,29 +0,0 @@
-{
-  "name": "plugin-sdk",
-  "$schema": "../../node_modules/nx/schemas/project-schema.json",
-  "sourceRoot": "packages/plugin-sdk/src",
-  "projectType": "library",
-  "tags": [],
-  "targets": {
-    "build": {
-      "executor": "@nx/rollup:rollup",
-      "outputs": ["{options.outputPath}"],
-      "options": {
-        "outputPath": "dist/packages/plugin-sdk",
-        "main": "packages/plugin-sdk/src/index.ts",
-        "tsConfig": "packages/plugin-sdk/tsconfig.lib.json",
-        "assets": [],
-        "project": "packages/plugin-sdk/package.json",
-        "compiler": "swc",
-        "format": ["cjs", "esm"]
-      }
-    },
-    "test": {
-      "executor": "@nx/jest:jest",
-      "outputs": ["{workspaceRoot}/coverage/{projectRoot}"],
-      "options": {
-        "jestConfig": "packages/plugin-sdk/jest.config.ts"
-      }
-    }
-  }
-}

package/src/index.ts

@@ -1,12 +0,0 @@
-export * from './lib/plugin'
-export * from './lib/plugin.interface'
-export * from './lib/plugin-metadata'
-export * from './lib/types'
-export * from './lib/logger'
-export * from './lib/knowledge'
-export * from './lib/integration/index'
-export * from './lib/workflow/index'
-export * from './lib/vectorstore/index'
-export * from './lib/rag/index'
-export * from './lib/toolset/index'
-export * from './lib/core/index'

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

@@ -1,96 +0,0 @@
-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

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

package/src/lib/core/permissions.ts

@@ -1,97 +0,0 @@
-/**
- * ===============================
- * 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

@@ -1,23 +0,0 @@
-/**
- * 通用 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

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

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

@@ -1,6 +0,0 @@
-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.registry.ts

@@ -1,12 +0,0 @@
-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

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

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

@@ -1,6 +0,0 @@
-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

@@ -1,15 +0,0 @@
-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][] }>
-}