插件中间件 (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 平台

# 在 XpertAI 平台通过 API 安装
POST http://10.161.48.53:3300/api/plugin
{
  "pluginName": "@timmy_hu/plugin-middleware",
  "version": "1.0.0",
  "source": "npm"
}

本地开发

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=可用未加载 |

返回值：

{
  "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 | 是 | 要加载的中间件插件编码 |

返回值：

{
  "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[] | 是 | 要批量加载的中间件插件编码数组 |

调用示例

// 列出所有中间件插件
{
  "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 的智能体编排页面，添加"插件中间件管理器"中间件，即可在对话中使用插件发现和动态加载能力。