@xpert-ai/plugin-sdk 0.0.1

package/.eslintrc.json

@@ -0,0 +1,30 @@
+{
+  "extends": ["../../.eslintrc.json"],
+  "ignorePatterns": ["!**/*"],
+  "overrides": [
+    {
+      "files": ["*.ts", "*.tsx", "*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.ts", "*.tsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.js", "*.jsx"],
+      "rules": {}
+    },
+    {
+      "files": ["*.json"],
+      "parser": "jsonc-eslint-parser",
+      "rules": {
+        "@nx/dependency-checks": [
+          "error",
+          {
+            "ignoredFiles": ["{projectRoot}/rollup.config.{js,ts,mjs,mts}"]
+          }
+        ]
+      }
+    }
+  ]
+}

package/.swcrc

@@ -0,0 +1,29 @@
+{
+  "jsc": {
+    "target": "es2017",
+    "parser": {
+      "syntax": "typescript",
+      "decorators": true,
+      "dynamicImport": true
+    },
+    "transform": {
+      "decoratorMetadata": true,
+      "legacyDecorator": true
+    },
+    "keepClassNames": true,
+    "externalHelpers": true,
+    "loose": true
+  },
+  "module": {
+    "type": "es6"
+  },
+  "sourceMaps": true,
+  "exclude": [
+    "jest.config.ts",
+    ".*\\.spec.tsx?$",
+    ".*\\.test.tsx?$",
+    "./src/jest-setup.ts$",
+    "./**/jest-setup.ts$",
+    ".*.js$"
+  ]
+}

package/PERMISSIONS.md

@@ -0,0 +1,181 @@
+# 插件权限设计指南
+
+:::tip
+在 meta 中设计一套可以向核心系统反向请求 大模型 调用权限的（如请求一个 OpenAI Client实例）的配置，例如在 meta中声明大模型的权限请求，在 configSchema 中设计属性让用户配置具体的模型提供商和模型名称，核心系统在识别到权限请求时会根据 config 中用户配置的具体参数实例化大模型 Client 通过 config 传入到 understandImages 这个方法：
+:::
+
+👌明白了，你希望 **在插件 Strategy 的 meta 中声明依赖的大模型权限请求**，核心系统解析后根据用户配置（模型提供商 + 模型名称 + 其他参数）自动注入一个 `client` 到 `config`，这样插件不用自己创建 OpenAI / Anthropic / 其他 VLM 客户端。
+
+我帮你重新设计 `OpenAIGPT4VStrategy` 的 meta 和 configSchema，使它能 **反向请求核心系统提供的 Client**。
+
+---
+
+## 新版 Strategy
+
+```ts
+import { Injectable } from '@nestjs/common';
+import { Document } from 'langchain/document';
+import {
+  ImageUnderstandingStrategy,
+  IImageUnderstandingStrategy,
+  TImageUnderstandingFile,
+  TImageUnderstandingResult
+} from './strategy.interface';
+
+@Injectable()
+@ImageUnderstandingStrategy('openai-gpt4v')
+export class OpenAIGPT4VStrategy implements IImageUnderstandingStrategy<any> {
+  readonly meta = {
+    name: 'openai-gpt4v',
+    label: { en: 'OpenAI GPT-4 Vision', zh: 'OpenAI GPT-4 图像理解' },
+
+    /**
+     * 权限声明：告诉核心系统，这个插件需要一个 "llm" 权限，
+     * 提供方是 openai，能力是 vision。
+     * 核心系统识别后会根据 config.provider + config.model 实例化对应的 Client，
+     * 并注入到 config.client
+     */
+    permissions: [
+      {
+        type: 'llm',
+        provider: 'openai',
+        capability: 'vision',
+      },
+    ],
+
+    /**
+     * 配置 schema，用户需要填写 provider 和 model，
+     * 核心系统会根据 provider + model + 用户账号 API Key，
+     * 实例化好 Client 注入。
+     */
+    configSchema: {
+      type: 'object',
+      properties: {
+        provider: { 
+          type: 'string', 
+          enum: ['openai'], 
+          description: '模型提供商' 
+        },
+        model: { 
+          type: 'string', 
+          default: 'gpt-4-vision-preview', 
+          description: '大模型名称' 
+        },
+        prompt: { 
+          type: 'string', 
+          default: 'Describe this image in detail.', 
+          description: '提示词（可以自定义理解任务）' 
+        }
+      },
+      required: ['provider', 'model']
+    },
+
+    icon: {
+      svg: '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20"><circle cx="10" cy="10" r="8" stroke="black" fill="none"/><text x="6" y="14">VLM</text></svg>',
+      color: '#10a37f'
+    }
+  };
+
+  async validateConfig(config: any): Promise<void> {
+    if (!config.client) {
+      throw new Error('Missing injected LLM client in config. Core system must inject client.');
+    }
+  }
+
+  async understandImages(
+    files: TImageUnderstandingFile[],
+    config: any
+  ): Promise<TImageUnderstandingResult[]> {
+    const client = config.client; // ✅ 已由核心系统注入
+    const results: TImageUnderstandingResult[] = [];
+
+    for (const file of files) {
+      const description = await this.runGPT4V(client, file.path, config);
+
+      const doc = new Document({
+        pageContent: description,
+        metadata: {
+          chunkId: `img-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`,
+          parentChunkId: file.parentChunkId,
+          imagePath: file.path,
+          source: file.filename,
+          type: 'vlm',
+          engine: config.model
+        }
+      });
+
+      results.push({
+        docs: [doc],
+        metadata: { engine: config.model, file: file.filename }
+      });
+    }
+
+    return results;
+  }
+
+  private async runGPT4V(client: any, imagePath: string, config: any): Promise<string> {
+    // client 已经是 openai client，由核心系统实例化
+    const response = await client.chat.completions.create({
+      model: config.model,
+      messages: [
+        {
+          role: 'user',
+          content: [
+            { type: 'text', text: config.prompt || 'Describe this image in detail.' },
+            { type: 'image_url', image_url: { url: imagePath } }
+          ]
+        }
+      ],
+      max_tokens: 500
+    });
+
+    return response.choices[0]?.message?.content || '';
+  }
+}
+```
+
+---
+
+## 🔑 核心系统如何处理
+
+* 解析插件的 `meta.permissions`，发现需要：
+
+  ```json
+  { "type": "llm", "provider": "openai", "capability": "vision" }
+  ```
+* 根据用户 `config.provider = "openai"`, `config.model = "gpt-4-vision-preview"`
+  实例化 `OpenAI({ apiKey: userApiKey })`
+* 将 client 注入到 `config.client`
+* 调用 `strategy.understandImages(files, config)`
+
+---
+
+## 📌 使用示例
+
+```ts
+const strategy = this.imageUnderstandingRegistry.get('openai-gpt4v');
+const result = await strategy.understandImages(
+  [
+    { 
+      path: 'https://example.com/chart.png', 
+      filename: 'chart.png', 
+      extname: 'png', 
+      parentChunkId: 'uuid-123' 
+    }
+  ],
+  { 
+    provider: 'openai',
+    model: 'gpt-4-vision-preview',
+    prompt: '请用中文详细描述这张图片。',
+    client: openaiClient // ✅ 核心系统注入
+  }
+);
+
+console.log(result[0].docs[0].pageContent);
+```
+
+---
+
+这样插件本身不依赖任何 `openai` 包装逻辑，**只声明权限 + 要求 provider/model**，核心系统就能注入合适的 client。
+
+要不要我帮你写一个 **抽象的权限声明接口 (例如 ILLMPermissionRequest)**，这样 OCR/VLM/Embedding 插件都可以统一声明依赖？

package/README.md

@@ -0,0 +1,19 @@
+# plugin-sdk
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build plugin-sdk` to build the library.
+
+## Running unit tests
+
+Run `nx test plugin-sdk` to execute the unit tests via [Jest](https://jestjs.io).
+
+## Schema config
+
+[Schema UI 扩展规范](./SCHEMA_SPECIFICATION.md)
+
+## Permissions
+
+[插件权限设计指南](./PERMISSIONS.md)

package/SCHEMA_SPECIFICATION.md

@@ -0,0 +1,332 @@
+# 🔧 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

@@ -0,0 +1,28 @@
+/* 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/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@xpert-ai/plugin-sdk",
+  "version": "0.0.1",
+  "license": "AGPL-3.0",
+  "dependencies": {},
+  "main": "./index.cjs",
+  "module": "./index.js",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/project.json

@@ -0,0 +1,29 @@
+{
+  "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

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