@timmy_hu/plugin-middleware 1.0.0

package/.xpertai-plugin/plugin.json

@@ -0,0 +1,10 @@
+{
+  "name": "插件中间件",
+  "code": "plugin-middleware",
+  "version": "1.0.0",
+  "description": "自动发现所有中间件类型插件，支持动态按需加载、卸载和状态查询，为智能体编排提供灵活的中间件管理能力。",
+  "createdBy": "fpi",
+  "platform": "http://10.161.48.53:3300",
+  "category": "middleware",
+  "main": "index.js"
+}

package/README.md

@@ -0,0 +1,201 @@
+# 插件中间件 (Plugin Middleware)
+
+## 插件简介
+
+**插件中间件** 是一个 XpertAI 平台的中间件类型插件，功能类似"技能中间件"。它能够自动发现平台上所有类型为"中间件"的插件，并提供动态按需加载、卸载、状态查询和批量管理能力，为智能体编排提供灵活的中间件管理基础设施。
+
+## 适用场景
+
+- **智能体编排**：在智能体运行时动态发现和加载所需的中间件插件，无需预先配置所有中间件。
+- **插件管理**：统一管理平台上所有中间件插件的生命周期，包括加载、卸载和状态监控。
+- **按需加载**：根据智能体任务需求，动态加载特定中间件插件，减少资源占用。
+- **批量操作**：一次性加载或管理多个中间件插件，提高运维效率。
+- **缓存优化**：内置缓存机制，避免频繁调用平台 API，提升响应速度。
+
+## 目录结构
+
+```
+plugin-middleware/
+├── .xpertai-plugin/
+│   └── plugin.json              # 插件清单
+├── index.js                     # 插件入口（CommonJS）
+├── package.json                 # 项目依赖与元信息
+├── README.md                    # 本文件
+├── src/
+│   ├── plugin-middleware.module.ts          # NestJS 模块定义
+│   ├── middlewares/
+│   │   └── plugin-middleware.middleware.ts  # 中间件策略实现
+│   └── schemas/
+│       └── config.schema.ts                 # Zod 配置 Schema
+└── examples/
+    └── request.example.json     # 工具调用示例
+```
+
+## 安装与导入
+
+### 通过 npm 安装到 XpertAI 平台
+
+```bash
+# 在 XpertAI 平台通过 API 安装
+POST http://10.161.48.53:3300/api/plugin
+{
+  "pluginName": "@timmy_hu/plugin-middleware",
+  "version": "1.0.0",
+  "source": "npm"
+}
+```
+
+### 本地开发
+
+```bash
+npm install
+node -e "require('./index.js')"  # 验证入口
+```
+
+## 配置项说明
+
+| 配置项 | 类型 | 必填 | 默认值 | 说明 |
+|--------|------|------|--------|------|
+| `platformUrl` | string | 是 | `http://10.161.48.53:3300` | XpertAI 平台基础地址 |
+| `organizationId` | string | 否 | - | 组织 ID，用于限定插件查询范围 |
+| `autoDiscover` | boolean | 否 | `true` | 是否在启动时自动发现可用中间件插件 |
+| `cacheTtlSeconds` | number | 否 | `300` | 插件发现缓存有效期（秒） |
+| `loadTimeoutMs` | number | 否 | `30000` | 插件加载超时时间（毫秒） |
+| `offlineMode` | boolean | 否 | `true` | 是否启用离线模式 |
+
+## Agent Middleware 工具列表
+
+本插件通过 `PluginMiddleware` provider 的 `createMiddleware()` 方法暴露以下 6 个工具：
+
+### 1. `list_middleware_plugins` - 列出中间件插件
+
+列出所有已发现的中间件类型插件，可按加载状态过滤。
+
+**入参：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `filter` | enum | 否 | 过滤条件：`all`=全部, `loaded`=已加载, `available`=可用未加载 |
+
+**返回值：**
+```json
+{
+  "success": true,
+  "total": 3,
+  "plugins": [
+    {
+      "code": "weather-query",
+      "name": "天气查询",
+      "version": "1.0.0",
+      "description": "查询城市天气信息",
+      "status": "loaded",
+      "loadedAt": "2026-07-07T10:00:00.000Z"
+    }
+  ]
+}
+```
+
+### 2. `load_middleware_plugin` - 加载中间件插件
+
+按插件编码动态加载指定的中间件插件。
+
+**入参：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `pluginCode` | string | 是 | 要加载的中间件插件编码 |
+
+**返回值：**
+```json
+{
+  "success": true,
+  "message": "插件 pg-query-tool 加载成功",
+  "plugin": {
+    "code": "pg-query-tool",
+    "name": "PostgreSQL 查询工具",
+    "version": "1.0.0",
+    "loadedAt": "2026-07-07T10:05:00.000Z",
+    "status": "loaded"
+  }
+}
+```
+
+### 3. `unload_middleware_plugin` - 卸载中间件插件
+
+按插件编码卸载已加载的中间件插件。
+
+**入参：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `pluginCode` | string | 是 | 要卸载的中间件插件编码 |
+
+### 4. `get_middleware_plugin_status` - 查询插件状态
+
+查询指定中间件插件的详细状态信息。
+
+**入参：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `pluginCode` | string | 是 | 要查询的中间件插件编码 |
+
+### 5. `refresh_plugin_cache` - 刷新缓存
+
+刷新中间件插件发现缓存，强制从平台重新获取插件列表。
+
+**入参：** 无
+
+### 6. `batch_load_middleware_plugins` - 批量加载
+
+批量加载多个中间件插件。
+
+**入参：**
+| 参数 | 类型 | 必填 | 说明 |
+|------|------|------|------|
+| `pluginCodes` | string[] | 是 | 要批量加载的中间件插件编码数组 |
+
+## 调用示例
+
+```json
+// 列出所有中间件插件
+{
+  "tool": "list_middleware_plugins",
+  "input": { "filter": "all" }
+}
+
+// 加载指定插件
+{
+  "tool": "load_middleware_plugin",
+  "input": { "pluginCode": "pg-query-tool" }
+}
+
+// 批量加载
+{
+  "tool": "batch_load_middleware_plugins",
+  "input": { "pluginCodes": ["weather-query", "pg-query-tool"] }
+}
+```
+
+## 常见错误和处理方式
+
+| 错误 | 原因 | 处理方式 |
+|------|------|----------|
+| `未找到编码为 xxx 的中间件插件` | 插件编码不存在或未被发现 | 先调用 `list_middleware_plugins` 确认可用插件列表 |
+| `插件 xxx 已经处于加载状态` | 重复加载 | 无需处理，插件已可用 |
+| `插件 xxx 当前未加载，无需卸载` | 重复卸载 | 无需处理 |
+| `Platform API returned 401` | 鉴权失败 | 检查组织 ID 和平台访问权限 |
+| `Failed to discover middleware plugins` | 平台 API 不可达 | 检查 `platformUrl` 配置和网络连接 |
+
+## 安全注意事项
+
+- 本插件通过平台 API 发现和加载中间件插件，需要确保平台 API 的访问权限已正确配置。
+- 加载的中间件插件将继承当前智能体的权限范围，请确保只加载受信任的中间件插件。
+- 缓存机制可防止频繁调用平台 API，但在插件列表变更时需要手动刷新缓存。
+- 离线模式下，插件状态仅在本地维护，重启后会丢失。
+
+## 使用方式
+
+1. 在 XpertAI 平台安装本插件后，在智能体编排中添加"插件中间件管理器"中间件。
+2. 配置 `platformUrl` 和 `organizationId`（可选）。
+3. 智能体即可通过对话调用 `list_middleware_plugins`、`load_middleware_plugin` 等工具，动态管理中间件插件。
+
+## 下一步
+
+安装成功后，前往 http://10.161.48.53:3300 的智能体编排页面，添加"插件中间件管理器"中间件，即可在对话中使用插件发现和动态加载能力。

package/examples/request.example.json

@@ -0,0 +1,119 @@
+{
+  "tools": [
+    {
+      "name": "list_middleware_plugins",
+      "description": "列出所有已发现的中间件类型插件",
+      "input": {
+        "filter": "all"
+      },
+      "expectedOutput": {
+        "success": true,
+        "total": 3,
+        "plugins": [
+          {
+            "code": "weather-query",
+            "name": "天气查询",
+            "version": "1.0.0",
+            "description": "查询城市天气信息",
+            "status": "loaded",
+            "loadedAt": "2026-07-07T10:00:00.000Z"
+          },
+          {
+            "code": "pg-query-tool",
+            "name": "PostgreSQL 查询工具",
+            "version": "1.0.0",
+            "description": "执行 PostgreSQL 数据库查询",
+            "status": "available",
+            "loadedAt": null
+          }
+        ]
+      }
+    },
+    {
+      "name": "load_middleware_plugin",
+      "description": "动态加载指定的中间件插件",
+      "input": {
+        "pluginCode": "pg-query-tool"
+      },
+      "expectedOutput": {
+        "success": true,
+        "message": "插件 pg-query-tool 加载成功",
+        "plugin": {
+          "code": "pg-query-tool",
+          "name": "PostgreSQL 查询工具",
+          "version": "1.0.0",
+          "loadedAt": "2026-07-07T10:05:00.000Z",
+          "status": "loaded"
+        }
+      }
+    },
+    {
+      "name": "unload_middleware_plugin",
+      "description": "卸载已加载的中间件插件",
+      "input": {
+        "pluginCode": "pg-query-tool"
+      },
+      "expectedOutput": {
+        "success": true,
+        "message": "插件 pg-query-tool 已卸载",
+        "plugin": {
+          "code": "pg-query-tool",
+          "name": "PostgreSQL 查询工具",
+          "unloadedAt": "2026-07-07T10:10:00.000Z",
+          "status": "unloaded"
+        }
+      }
+    },
+    {
+      "name": "get_middleware_plugin_status",
+      "description": "查询指定中间件插件的详细状态",
+      "input": {
+        "pluginCode": "weather-query"
+      },
+      "expectedOutput": {
+        "success": true,
+        "plugin": {
+          "code": "weather-query",
+          "name": "天气查询",
+          "version": "1.0.0",
+          "description": "查询城市天气信息",
+          "category": "middleware",
+          "status": "loaded",
+          "loadedAt": "2026-07-07T10:00:00.000Z",
+          "tools": [],
+          "configRequired": []
+        }
+      }
+    },
+    {
+      "name": "refresh_plugin_cache",
+      "description": "刷新插件发现缓存",
+      "input": {},
+      "expectedOutput": {
+        "success": true,
+        "message": "缓存已刷新，发现 5 个中间件插件",
+        "total": 5,
+        "refreshedAt": "2026-07-07T10:15:00.000Z"
+      }
+    },
+    {
+      "name": "batch_load_middleware_plugins",
+      "description": "批量加载多个中间件插件",
+      "input": {
+        "pluginCodes": ["weather-query", "pg-query-tool", "email-sender"]
+      },
+      "expectedOutput": {
+        "success": true,
+        "total": 3,
+        "loaded": 2,
+        "alreadyLoaded": 1,
+        "failed": 0,
+        "results": [
+          { "code": "weather-query", "status": "already_loaded", "success": true },
+          { "code": "pg-query-tool", "name": "PostgreSQL 查询工具", "version": "1.0.0", "status": "loaded", "success": true },
+          { "code": "email-sender", "name": "邮件发送", "version": "1.0.0", "status": "loaded", "success": true }
+        ]
+      }
+    }
+  ]
+}