@timmy_hu/plugin-middleware 1.0.1 → 1.0.3

package/src/middlewares/plugin-middleware.middleware.ts

@@ -5,12 +5,6 @@ import { z } from "zod";
 
 const MIDDLEWARE_PROVIDER = "PluginMiddleware";
 
-/**
- * PluginMiddleware - 插件中间件管理器
- *
- * 自动发现所有中间件类型插件，支持动态按需加载、卸载和状态查询。
- * 通过 /api/auth/login 登录获取 token 后调用平台 API。
- */
 @Injectable()
 @AgentMiddlewareStrategy(MIDDLEWARE_PROVIDER)
 export class PluginMiddleware {
@@ -21,8 +15,8 @@ export class PluginMiddleware {
       zh_Hans: "插件中间件管理器"
     },
     description: {
-      en_US: "Discovers all middleware-type plugins and provides dynamic on-demand loading, unloading, and status query tools. Authenticates via /api/auth/login.",
-      zh_Hans: "自动发现所有中间件类型插件，支持动态按需加载、卸载和状态查询。通过 /api/auth/login 登录获取 token 后调用平台 API。"
+      en_US: "Discovers all middleware-type plugins installed on the XpertAI platform, shows their load status, and provides guidance on binding plugins to agents. Note: Plugins must be manually bound to agents in the XpertAI platform UI.",
+      zh_Hans: "自动发现 XpertAI 平台上所有已安装的中间件类型插件，展示加载状态，并提供插件绑定指导。注意：插件需要在 XpertAI 平台 UI 中手动绑定到智能体。"
     },
     configSchema: {
       type: "object",
@@ -48,12 +42,6 @@ export class PluginMiddleware {
           title: { en_US: "Organization ID", zh_Hans: "组织 ID" },
           description: "Organization ID for scoped plugin queries"
         },
-        autoDiscover: {
-          type: "boolean",
-          title: { en_US: "Auto Discover", zh_Hans: "自动发现" },
-          description: "Whether to automatically discover available middleware plugins on startup",
-          default: true
-        },
         cacheTtlSeconds: {
           type: "number",
           title: { en_US: "Cache TTL (seconds)", zh_Hans: "缓存有效期（秒）" },
@@ -66,26 +54,25 @@ export class PluginMiddleware {
   };
 
   createMiddleware(options: any = {}, context: any = {}) {
-    const platformUrl = options.platformUrl || "http://10.161.48.53:3300";
+    const platformUrl = (options.platformUrl || "http://10.161.48.53:3300").replace(/\/+$/, "");
     const email = options.email || "";
     const password = options.password || "";
     const organizationId = options.organizationId || "";
     const cacheTtlSeconds = options.cacheTtlSeconds || 300;
 
-    const registry = {
-      plugins: new Map(),
-      loadedPlugins: new Map(),
+    const state = {
+      allPlugins: [] as any[],
+      middlewarePlugins: [] as any[],
       lastRefresh: null as number | null,
       cacheTtl: cacheTtlSeconds * 1000,
       token: null as string | null,
       tokenExpiry: null as number | null
     };
 
-    // ---- Login: call /api/auth/login to get token ----
     async function loginAndGetToken(): Promise<string> {
       const now = Date.now();
-      if (registry.token && registry.tokenExpiry && now < registry.tokenExpiry) {
-        return registry.token;
+      if (state.token && state.tokenExpiry && now < state.tokenExpiry) {
+        return state.token;
       }
       if (!email || !password) {
         throw new Error("缺少登录凭据：请在插件配置中填写 email 和 password");
@@ -103,197 +90,521 @@ export class PluginMiddleware {
       }
       const data = await resp.json();
       const token = data.access_token || data.token || (data.data && data.data.access_token);
-      if (!token) {
-        throw new Error(`登录响应中未找到 token 字段，响应: ${JSON.stringify(data)}`);
-      }
-      registry.token = token;
-      registry.tokenExpiry = now + 50 * 60 * 1000; // 50 min
+      if (!token) throw new Error("登录响应中未找到 token 字段");
+      state.token = token;
+      state.tokenExpiry = now + 50 * 60 * 1000;
       return token;
     }
 
     function authHeaders(token: string): Record<string, string> {
-      const headers: Record<string, string> = {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${token}`
-      };
-      if (organizationId) headers["organization-id"] = organizationId;
-      return headers;
+      const h: Record<string, string> = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` };
+      if (organizationId) h["organization-id"] = organizationId;
+      return h;
     }
 
-    async function fetchMiddlewarePlugins() {
+    async function fetchAllPlugins() {
       const now = Date.now();
-      if (registry.lastRefresh && (now - registry.lastRefresh) < registry.cacheTtl) {
-        return Array.from(registry.plugins.values());
+      if (state.lastRefresh && (now - state.lastRefresh) < state.cacheTtl && state.allPlugins.length > 0) {
+        return state.allPlugins;
       }
       const token = await loginAndGetToken();
       const fetch = (await import("node-fetch")).default;
-      const url = `${platformUrl}/api/plugin?category=middleware`;
-      const resp = await fetch(url, { method: "GET", headers: authHeaders(token), timeout: 10000 });
+      const resp = await fetch(`${platformUrl}/api/plugin`, {
+        method: "GET",
+        headers: authHeaders(token),
+        timeout: 15000
+      });
       if (!resp.ok) {
         if (resp.status === 401) {
-          registry.token = null; registry.tokenExpiry = null;
+          state.token = null; state.tokenExpiry = null;
           const newToken = await loginAndGetToken();
-          const retryResp = await fetch(url, { method: "GET", headers: authHeaders(newToken), timeout: 10000 });
-          if (!retryResp.ok) throw new Error(`Platform API returned ${retryResp.status}`);
-          return parsePluginList(await retryResp.json());
+          const retry = await fetch(`${platformUrl}/api/plugin`, { method: "GET", headers: authHeaders(newToken), timeout: 15000 });
+          if (!retry.ok) throw new Error(`Platform API returned ${retry.status}`);
+          return processPluginList(await retry.json());
         }
         throw new Error(`Platform API returned ${resp.status}: ${resp.statusText}`);
       }
-      return parsePluginList(await resp.json());
+      return processPluginList(await resp.json());
     }
 
-    function parsePluginList(data: any) {
-      const pluginList = Array.isArray(data) ? data : (data.data || data.items || data.plugins || []);
-      registry.plugins.clear();
-      for (const p of pluginList) {
-        const code = p.code || p.name || p.pluginName;
-        if (code) {
-          registry.plugins.set(code, {
-            code, name: p.name || p.displayName || code,
-            version: p.version || "unknown", description: p.description || "",
-            status: p.status || "available", category: p.category || "middleware",
-            loaded: registry.loadedPlugins.has(code)
-          });
-        }
-      }
-      registry.lastRefresh = Date.now();
-      return Array.from(registry.plugins.values());
+    function processPluginList(data: any) {
+      const list = Array.isArray(data) ? data : (data.data || data.items || data.plugins || []);
+      state.allPlugins = list;
+      state.middlewarePlugins = list.filter((p: any) => (p.meta || {}).category === "middleware");
+      state.lastRefresh = Date.now();
+      return state.allPlugins;
+    }
+
+    function formatMiddlewarePlugin(p: any) {
+      const meta = p.meta || {};
+      return {
+        name: p.name || meta.name,
+        packageName: p.packageName || "",
+        displayName: meta.displayName || p.name || meta.name,
+        version: meta.version || p.currentVersion || "unknown",
+        description: meta.description || "",
+        category: meta.category || "unknown",
+        author: meta.author || "",
+        keywords: meta.keywords || [],
+        source: p.source || "",
+        loadStatus: p.loadStatus || "unknown",
+        loadError: p.loadError || null,
+        configurationStatus: p.configurationStatus || null,
+        configurationError: p.configurationError || null,
+        canConfigure: p.canConfigure || false,
+        canUninstall: p.canUninstall || false,
+        canUpdate: p.canUpdate || false,
+        hasUpdate: p.hasUpdate || false,
+        effectiveInCurrentScope: p.effectiveInCurrentScope !== false,
+        scopeRelation: p.scopeRelation || "unknown",
+        componentSummary: p.componentSummary || { total: 0, skills: 0, mcpServers: 0, apps: 0, hooks: 0 }
+      };
     }
 
-    // Tool 1: list_middleware_plugins
     const listMiddlewarePlugins = tool(
       async (input) => {
         try {
-          const plugins = await fetchMiddlewarePlugins();
+          await fetchAllPlugins();
           const filter = input.filter || "all";
-          let filtered = plugins;
-          if (filter === "loaded") filtered = plugins.filter((p: any) => p.loaded || registry.loadedPlugins.has(p.code));
-          else if (filter === "available") filtered = plugins.filter((p: any) => !p.loaded && !registry.loadedPlugins.has(p.code));
+          let filtered = state.middlewarePlugins;
+          if (filter === "loaded") filtered = filtered.filter(p => p.loadStatus === "loaded");
+          else if (filter === "error") filtered = filtered.filter(p => p.loadStatus === "error" || p.loadError);
+          else if (filter === "updatable") filtered = filtered.filter(p => p.hasUpdate === true);
           return {
-            success: true, total: filtered.length,
-            plugins: filtered.map((p: any) => ({
-              code: p.code, name: p.name, version: p.version, description: p.description,
-              status: registry.loadedPlugins.has(p.code) ? "loaded" : "available",
-              loadedAt: registry.loadedPlugins.has(p.code) ? registry.loadedPlugins.get(p.code).loadedAt : null
-            }))
+            success: true,
+            total: filtered.length,
+            totalAllPlugins: state.allPlugins.length,
+            totalMiddleware: state.middlewarePlugins.length,
+            filter,
+            plugins: filtered.map(formatMiddlewarePlugin),
+            note: "⚠️ 插件已安装并加载，但需要在 XpertAI 平台 UI 中手动绑定到智能体才能使用其工具。请使用 get_binding_guidance 工具获取绑定指导。"
           };
-        } catch (err: any) { return { success: false, error: err.message, plugins: [] }; }
+        } catch (err: any) {
+          return { success: false, error: err.message, plugins: [] };
+        }
+      },
+      {
+        name: "list_middleware_plugins",
+        description: "列出平台上所有已安装的中间件类型插件。注意：插件需要在 XpertAI 平台 UI 中手动绑定到智能体。",
+        schema: z.object({
+          filter: z.enum(["all", "loaded", "error", "updatable"]).optional().default("all")
+            .describe("过滤条件：all=全部, loaded=已加载, error=加载出错, updatable=有可用更新")
+        })
+      }
+    );
+
+    const getMiddlewarePluginDetail = tool(
+      async (input) => {
+        try {
+          await fetchAllPlugins();
+          const keyword = input.pluginNameOrPackage;
+          const found = state.middlewarePlugins.find((p: any) => {
+            const meta = p.meta || {};
+            return p.name === keyword || meta.name === keyword || p.packageName === keyword || meta.displayName === keyword;
+          });
+          if (!found) {
+            return {
+              success: false,
+              error: `未找到名为 "${keyword}" 的中间件插件`,
+              availableMiddleware: state.middlewarePlugins.map((p: any) => ({
+                name: p.name, packageName: p.packageName, displayName: (p.meta || {}).displayName
+              }))
+            };
+          }
+          const detail = formatMiddlewarePlugin(found);
+          try {
+            const token = await loginAndGetToken();
+            const fetch = (await import("node-fetch")).default;
+            const compResp = await fetch(`${platformUrl}/api/plugin/${encodeURIComponent(found.name)}/components`, {
+              method: "GET", headers: authHeaders(token), timeout: 10000
+            });
+            if (compResp.ok) {
+              const compData = await compResp.json();
+              detail.components = compData.items || compData;
+            }
+          } catch (e) {
+            detail.components = [];
+          }
+          if (detail.componentSummary.total === 0) {
+            detail.bindingWarning = "⚠️ 该插件没有暴露任何组件（工具/技能/MCP服务器）。请检查插件实现是否正确注册了中间件策略。";
+          } else if (!detail.effectiveInCurrentScope) {
+            detail.bindingWarning = "⚠️ 该插件在当前作用域中未生效。请在 XpertAI 平台 UI 中将此插件绑定到当前智能体。";
+          }
+          return { success: true, plugin: detail };
+        } catch (err: any) {
+          return { success: false, error: err.message };
+        }
       },
-      { name: "list_middleware_plugins", description: "列出所有已发现的中间件类型插件，可按加载状态过滤。", schema: z.object({ filter: z.enum(["all", "loaded", "available"]).optional().default("all").describe("过滤条件") }) }
+      {
+        name: "get_middleware_plugin_detail",
+        description: "查询指定中间件插件的详细信息，包括加载状态、配置状态、组件列表、版本信息和绑定状态。",
+        schema: z.object({
+          pluginNameOrPackage: z.string().min(1)
+            .describe("插件名称、packageName 或 displayName，例如 'echarts-generator' 或 '@timmy_hu/bulk-email-sender'")
+        })
+      }
     );
 
-    // Tool 2: load_middleware_plugin
-    const loadMiddlewarePlugin = tool(
+    const installMiddlewarePlugin = tool(
       async (input) => {
-        const pluginCode = input.pluginCode;
-        if (registry.loadedPlugins.has(pluginCode)) return { success: true, message: `插件 ${pluginCode} 已经处于加载状态`, plugin: { code: pluginCode, loadedAt: registry.loadedPlugins.get(pluginCode).loadedAt, status: "already_loaded" } };
-        const plugins = await fetchMiddlewarePlugins();
-        const target = plugins.find((p: any) => p.code === pluginCode);
-        if (!target) return { success: false, error: `未找到编码为 ${pluginCode} 的中间件插件`, availablePlugins: plugins.map((p: any) => p.code) };
+        const packageName = input.packageName;
+        const version = input.version || "latest";
         try {
           const token = await loginAndGetToken();
           const fetch = (await import("node-fetch")).default;
-          const resp = await fetch(`${platformUrl}/api/plugin/load`, { method: "POST", headers: authHeaders(token), body: JSON.stringify({ pluginName: target.name || pluginCode, version: target.version, source: "npm" }), timeout: 30000 });
-          if (!resp.ok) throw new Error(`Load API returned ${resp.status}: ${await resp.text()}`);
+          const resp = await fetch(`${platformUrl}/api/plugin`, {
+            method: "POST",
+            headers: authHeaders(token),
+            body: JSON.stringify({ pluginName: packageName, version, source: "npm" }),
+            timeout: 60000
+          });
+          if (!resp.ok) {
+            const errText = await resp.text();
+            throw new Error(`安装失败 (${resp.status}): ${errText}`);
+          }
           const result = await resp.json();
-          registry.loadedPlugins.set(pluginCode, { code: pluginCode, name: target.name, version: target.version, loadedAt: new Date().toISOString(), loadResult: result });
-          return { success: true, message: `插件 ${pluginCode} 加载成功`, plugin: { code: pluginCode, name: target.name, version: target.version, loadedAt: registry.loadedPlugins.get(pluginCode).loadedAt, status: "loaded" } };
+          state.lastRefresh = null;
+          return {
+            success: true,
+            message: `插件 ${packageName} 安装成功`,
+            installed: {
+              name: result.name || packageName,
+              packageName: result.packageName || packageName,
+              version: result.currentVersion || version,
+              organizationId: result.organizationId || organizationId
+            },
+            nextSteps: [
+              "1. 插件已安装并加载到平台",
+              "2. 请在 XpertAI 平台 UI 中进入智能体编排页面",
+              "3. 点击"添加中间件"按钮",
+              "4. 在列表中找到刚安装的插件并添加",
+              "5. 保存智能体配置后，插件的工具即可使用"
+            ]
+          };
         } catch (err: any) {
-          registry.loadedPlugins.set(pluginCode, { code: pluginCode, name: target.name, version: target.version, loadedAt: new Date().toISOString(), loadResult: { offline: true, error: err.message } });
-          return { success: true, message: `插件 ${pluginCode} 已标记为加载（离线模式）`, plugin: { code: pluginCode, name: target.name, version: target.version, loadedAt: registry.loadedPlugins.get(pluginCode).loadedAt, status: "loaded_offline", warning: err.message } };
+          return { success: false, error: err.message, packageName, version };
         }
       },
-      { name: "load_middleware_plugin", description: "按插件编码动态加载指定的中间件插件。", schema: z.object({ pluginCode: z.string().min(1).describe("要加载的中间件插件编码") }) }
+      {
+        name: "install_middleware_plugin",
+        description: "从 npm 安装一个新的中间件插件到 XpertAI 平台。安装后需要在平台 UI 中手动绑定到智能体。",
+        schema: z.object({
+          packageName: z.string().min(1).describe("npm 包名，例如 '@timmy_hu/bulk-email-sender'"),
+          version: z.string().optional().default("latest").describe("版本号，默认为 latest")
+        })
+      }
     );
 
-    // Tool 3: unload_middleware_plugin
-    const unloadMiddlewarePlugin = tool(
+    const refreshPluginList = tool(
       async (input) => {
-        const pluginCode = input.pluginCode;
-        if (!registry.loadedPlugins.has(pluginCode)) return { success: false, error: `插件 ${pluginCode} 当前未加载，无需卸载`, loadedPlugins: Array.from(registry.loadedPlugins.keys()) };
+        state.lastRefresh = null;
+        state.token = null;
+        state.tokenExpiry = null;
         try {
-          const token = await loginAndGetToken();
-          const fetch = (await import("node-fetch")).default;
-          const resp = await fetch(`${platformUrl}/api/plugin/unload`, { method: "POST", headers: authHeaders(token), body: JSON.stringify({ pluginCode }), timeout: 15000 });
-          if (!resp.ok) throw new Error(`Unload API returned ${resp.status}: ${await resp.text()}`);
-        } catch (err: any) { /* continue */ }
-        const removed = registry.loadedPlugins.get(pluginCode);
-        registry.loadedPlugins.delete(pluginCode);
-        return { success: true, message: `插件 ${pluginCode} 已卸载`, plugin: { code: pluginCode, name: removed.name, unloadedAt: new Date().toISOString(), status: "unloaded" } };
+          await fetchAllPlugins();
+          return {
+            success: true,
+            message: `插件列表已刷新，共发现 ${state.allPlugins.length} 个插件，其中 ${state.middlewarePlugins.length} 个中间件类型`,
+            totalPlugins: state.allPlugins.length,
+            totalMiddleware: state.middlewarePlugins.length,
+            refreshedAt: new Date().toISOString()
+          };
+        } catch (err: any) {
+          return { success: false, error: `刷新失败: ${err.message}` };
+        }
+      },
+      {
+        name: "refresh_plugin_list",
+        description: "刷新插件列表缓存，强制重新登录并从平台获取所有已安装插件的最新状态。",
+        schema: z.object({})
+      }
+    );
+
+    const checkLoginStatus = tool(
+      async (input) => {
+        try {
+          await loginAndGetToken();
+          return {
+            success: true,
+            loggedIn: true,
+            email,
+            platformUrl,
+            organizationId: organizationId || "(未设置)",
+            tokenExpiry: state.tokenExpiry ? new Date(state.tokenExpiry).toISOString() : null,
+            cachedPlugins: state.allPlugins.length,
+            cachedMiddleware: state.middlewarePlugins.length,
+            message: "登录状态正常，token 有效"
+          };
+        } catch (err: any) {
+          return { success: false, loggedIn: false, email, platformUrl, error: err.message };
+        }
       },
-      { name: "unload_middleware_plugin", description: "按插件编码卸载已加载的中间件插件。", schema: z.object({ pluginCode: z.string().min(1).describe("要卸载的中间件插件编码") }) }
+      {
+        name: "check_login_status",
+        description: "检查当前平台登录状态，验证 email/password 是否有效、token 是否过期，以及缓存中有多少插件。",
+        schema: z.object({})
+      }
     );
 
-    // Tool 4: get_middleware_plugin_status
-    const getMiddlewarePluginStatus = tool(
+    const searchMiddlewarePlugins = tool(
       async (input) => {
-        const pluginCode = input.pluginCode;
-        const plugins = await fetchMiddlewarePlugins();
-        const target = plugins.find((p: any) => p.code === pluginCode);
-        if (!target) return { success: false, error: `未找到编码为 ${pluginCode} 的中间件插件` };
-        const loaded = registry.loadedPlugins.has(pluginCode);
-        const loadInfo = loaded ? registry.loadedPlugins.get(pluginCode) : null;
-        return { success: true, plugin: { code: target.code, name: target.name, version: target.version, description: target.description, category: target.category, status: loaded ? "loaded" : "available", loadedAt: loadInfo ? loadInfo.loadedAt : null, tools: loaded ? (loadInfo.tools || []) : [], configRequired: target.configRequired || [] } };
+        try {
+          await fetchAllPlugins();
+          const keyword = (input.keyword || "").toLowerCase();
+          const results = state.middlewarePlugins.filter((p: any) => {
+            const meta = p.meta || {};
+            const searchFields = [
+              p.name, p.packageName, meta.name, meta.displayName,
+              meta.description, (meta.keywords || []).join(" ")
+            ].map(s => (s || "").toLowerCase());
+            return searchFields.some(f => f.includes(keyword));
+          });
+          return {
+            success: true,
+            keyword: input.keyword,
+            total: results.length,
+            plugins: results.map(formatMiddlewarePlugin)
+          };
+        } catch (err: any) {
+          return { success: false, error: err.message, plugins: [] };
+        }
       },
-      { name: "get_middleware_plugin_status", description: "查询指定中间件插件的详细状态信息。", schema: z.object({ pluginCode: z.string().min(1).describe("要查询的中间件插件编码") }) }
+      {
+        name: "search_middleware_plugins",
+        description: "按关键词搜索中间件类型插件。搜索范围包括插件名称、包名、描述和关键词。",
+        schema: z.object({
+          keyword: z.string().min(1).describe("搜索关键词，例如 'echarts'、'email'、'retry'")
+        })
+      }
     );
 
-    // Tool 5: refresh_plugin_cache
-    const refreshPluginCache = tool(
+    const getPluginStatistics = tool(
       async (input) => {
-        registry.lastRefresh = null; registry.token = null; registry.tokenExpiry = null;
         try {
-          const plugins = await fetchMiddlewarePlugins();
-          return { success: true, message: `缓存已刷新，发现 ${plugins.length} 个中间件插件`, total: plugins.length, refreshedAt: new Date().toISOString() };
-        } catch (err: any) { return { success: false, error: `刷新缓存失败: ${err.message}` }; }
+          await fetchAllPlugins();
+          const categoryStats: Record<string, number> = {};
+          for (const p of state.allPlugins) {
+            const cat = (p.meta || {}).category || "unknown";
+            categoryStats[cat] = (categoryStats[cat] || 0) + 1;
+          }
+          const loadStatusStats: Record<string, number> = {};
+          for (const p of state.middlewarePlugins) {
+            const ls = p.loadStatus || "unknown";
+            loadStatusStats[ls] = (loadStatusStats[ls] || 0) + 1;
+          }
+          const updatable = state.middlewarePlugins.filter(p => p.hasUpdate === true);
+          const configErrors = state.middlewarePlugins.filter(p => p.configurationError);
+          const loadErrors = state.middlewarePlugins.filter(p => p.loadError);
+          return {
+            success: true,
+            statistics: {
+              totalPlugins: state.allPlugins.length,
+              totalMiddleware: state.middlewarePlugins.length,
+              byCategory: categoryStats,
+              middlewareByLoadStatus: loadStatusStats,
+              updatableCount: updatable.length,
+              updatablePlugins: updatable.map(p => ({ name: p.name, packageName: p.packageName, version: (p.meta || {}).version })),
+              configErrorCount: configErrors.length,
+              configErrorPlugins: configErrors.map(p => ({ name: p.name, error: p.configurationError })),
+              loadErrorCount: loadErrors.length,
+              loadErrorPlugins: loadErrors.map(p => ({ name: p.name, error: p.loadError }))
+            },
+            generatedAt: new Date().toISOString()
+          };
+        } catch (err: any) {
+          return { success: false, error: err.message };
+        }
       },
-      { name: "refresh_plugin_cache", description: "刷新中间件插件发现缓存，强制重新登录并获取插件列表。", schema: z.object({}) }
+      {
+        name: "get_plugin_statistics",
+        description: "获取平台上所有插件的统计信息，包括按分类统计、按加载状态统计、有更新的插件、有错误的插件等。",
+        schema: z.object({})
+      }
     );
 
-    // Tool 6: batch_load_middleware_plugins
-    const batchLoadMiddlewarePlugins = tool(
+    const getBindingGuidance = tool(
       async (input) => {
-        const pluginCodes = input.pluginCodes;
-        const results: any[] = [];
-        const plugins = await fetchMiddlewarePlugins();
-        for (const code of pluginCodes) {
-          if (registry.loadedPlugins.has(code)) { results.push({ code, status: "already_loaded", success: true }); continue; }
-          const target = plugins.find((p: any) => p.code === code);
-          if (!target) { results.push({ code, status: "not_found", success: false, error: `未找到编码为 ${code} 的中间件插件` }); continue; }
-          try {
-            const token = await loginAndGetToken();
-            const fetch = (await import("node-fetch")).default;
-            const resp = await fetch(`${platformUrl}/api/plugin/load`, { method: "POST", headers: authHeaders(token), body: JSON.stringify({ pluginName: target.name || code, version: target.version, source: "npm" }), timeout: 30000 });
-            if (!resp.ok) throw new Error(`Load API returned ${resp.status}`);
-            const result = await resp.json();
-            registry.loadedPlugins.set(code, { code, name: target.name, version: target.version, loadedAt: new Date().toISOString(), loadResult: result });
-            results.push({ code, name: target.name, version: target.version, status: "loaded", success: true, loadedAt: registry.loadedPlugins.get(code).loadedAt });
-          } catch (err: any) {
-            registry.loadedPlugins.set(code, { code, name: target.name, version: target.version, loadedAt: new Date().toISOString(), loadResult: { offline: true, error: err.message } });
-            results.push({ code, name: target.name, version: target.version, status: "loaded_offline", success: true, warning: err.message });
+        const pluginName = input.pluginName;
+        try {
+          await fetchAllPlugins();
+          const plugin = state.middlewarePlugins.find((p: any) => {
+            const meta = p.meta || {};
+            return p.name === pluginName || meta.name === pluginName || p.packageName === pluginName || meta.displayName === pluginName;
+          });
+          if (!plugin) {
+            return {
+              success: false,
+              error: `未找到名为 "${pluginName}" 的中间件插件`,
+              guidance: "请先使用 list_middleware_plugins 查看所有可用的中间件插件"
+            };
+          }
+          const meta = plugin.meta || {};
+          const detail = formatMiddlewarePlugin(plugin);
+          const guidance = {
+            pluginName: detail.displayName,
+            packageName: detail.packageName,
+            version: detail.version,
+            loadStatus: detail.loadStatus,
+            componentSummary: detail.componentSummary,
+            steps: [
+              { step: 1, action: "打开 XpertAI 平台", url: platformUrl, description: "登录到 XpertAI 平台" },
+              { step: 2, action: "进入智能体编排页面", description: "找到并编辑需要使用该插件的智能体" },
+              { step: 3, action: "添加中间件", description: `点击"添加中间件"按钮，在列表中找到 "${detail.displayName}" (${detail.packageName})` },
+              { step: 4, action: "配置插件（如需要）", description: detail.canConfigure ? "根据插件要求填写配置参数" : "该插件无需额外配置" },
+              { step: 5, action: "保存智能体", description: "保存智能体配置，插件的工具将立即可用" }
+            ],
+            troubleshooting: [] as any[]
+          };
+          if (detail.loadStatus !== "loaded") {
+            guidance.troubleshooting.push({
+              issue: "插件未加载",
+              status: detail.loadStatus,
+              error: detail.loadError,
+              solution: "插件加载失败，请检查插件是否正确安装，或联系插件作者"
+            });
+          }
+          if (detail.componentSummary.total === 0) {
+            guidance.troubleshooting.push({
+              issue: "插件没有暴露任何组件",
+              componentSummary: detail.componentSummary,
+              solution: "插件实现可能有问题，没有正确注册中间件策略或工具。请联系插件作者检查插件代码。"
+            });
+          }
+          if (!detail.effectiveInCurrentScope) {
+            guidance.troubleshooting.push({
+              issue: "插件在当前作用域未生效",
+              scopeRelation: detail.scopeRelation,
+              solution: "请在智能体编排页面中手动添加此中间件到智能体"
+            });
+          }
+          if (detail.configurationError) {
+            guidance.troubleshooting.push({
+              issue: "插件配置错误",
+              error: detail.configurationError,
+              solution: "请检查并修正插件配置"
+            });
           }
+          return { success: true, guidance };
+        } catch (err: any) {
+          return { success: false, error: err.message };
         }
-        return { success: true, total: pluginCodes.length, loaded: results.filter((r: any) => r.status === "loaded").length, alreadyLoaded: results.filter((r: any) => r.status === "already_loaded").length, failed: results.filter((r: any) => !r.success).length, results };
       },
-      { name: "batch_load_middleware_plugins", description: "批量加载多个中间件插件。", schema: z.object({ pluginCodes: z.array(z.string().min(1)).min(1).describe("要批量加载的中间件插件编码数组") }) }
+      {
+        name: "get_binding_guidance",
+        description: "获取将指定中间件插件绑定到智能体的详细步骤指导，包括诊断插件状态和提供故障排除建议。",
+        schema: z.object({
+          pluginName: z.string().min(1)
+            .describe("插件名称、packageName 或 displayName，例如 '@timmy_hu/bulk-email-sender'")
+        })
+      }
     );
 
-    // Tool 7: check_login_status
-    const checkLoginStatus = tool(
+    const diagnosePluginAvailability = tool(
       async (input) => {
+        const pluginName = input.pluginName;
         try {
-          await loginAndGetToken();
-          return { success: true, loggedIn: true, email, platformUrl, tokenExpiry: registry.tokenExpiry ? new Date(registry.tokenExpiry).toISOString() : null, message: "登录状态正常，token 有效" };
+          await fetchAllPlugins();
+          const plugin = state.middlewarePlugins.find((p: any) => {
+            const meta = p.meta || {};
+            return p.name === pluginName || meta.name === pluginName || p.packageName === pluginName || meta.displayName === pluginName;
+          });
+          if (!plugin) {
+            return {
+              success: false,
+              error: `未找到名为 "${pluginName}" 的中间件插件`,
+              diagnosis: "插件未安装",
+              solution: "使用 install_middleware_plugin 工具安装该插件"
+            };
+          }
+          const meta = plugin.meta || {};
+          const detail = formatMiddlewarePlugin(plugin);
+          const checks = [];
+          let allPassed = true;
+          const loadCheck = {
+            name: "插件加载状态",
+            passed: detail.loadStatus === "loaded",
+            status: detail.loadStatus,
+            error: detail.loadError
+          };
+          checks.push(loadCheck);
+          if (!loadCheck.passed) allPassed = false;
+          const componentCheck = {
+            name: "组件暴露",
+            passed: detail.componentSummary.total > 0,
+            total: detail.componentSummary.total,
+            breakdown: detail.componentSummary
+          };
+          checks.push(componentCheck);
+          if (!componentCheck.passed) allPassed = false;
+          const configCheck = {
+            name: "配置状态",
+            passed: !detail.configurationError,
+            status: detail.configurationStatus,
+            error: detail.configurationError
+          };
+          checks.push(configCheck);
+          if (!configCheck.passed) allPassed = false;
+          const scopeCheck = {
+            name: "作用域生效",
+            passed: detail.effectiveInCurrentScope,
+            scopeRelation: detail.scopeRelation
+          };
+          checks.push(scopeCheck);
+          if (!scopeCheck.passed) allPassed = false;
+          const diagnosis = {
+            pluginName: detail.displayName,
+            packageName: detail.packageName,
+            version: detail.version,
+            allChecksPassed: allPassed,
+            checks,
+            summary: allPassed 
+              ? "✅ 插件状态正常，应该可以在智能体中使用。如果仍无法使用，请确保已在智能体编排页面中添加了该中间件。"
+              : "❌ 插件存在问题，需要修复后才能使用",
+            recommendations: [] as string[]
+          };
+          if (!loadCheck.passed) {
+            diagnosis.recommendations.push("插件加载失败，请检查插件代码或联系插件作者");
+          }
+          if (!componentCheck.passed) {
+            diagnosis.recommendations.push("插件没有暴露任何工具或组件。这通常意味着插件代码没有正确实现中间件策略。请联系插件作者检查代码。");
+          }
+          if (!configCheck.passed) {
+            diagnosis.recommendations.push(`插件配置错误: ${detail.configurationError}`);
+          }
+          if (!scopeCheck.passed) {
+            diagnosis.recommendations.push("插件在当前作用域未生效。请在 XpertAI 平台 UI 的智能体编排页面中手动添加此中间件。");
+          }
+          if (allPassed) {
+            diagnosis.recommendations.push("插件状态正常。如果工具仍不可用，请确保：1) 已在智能体编排页面添加了该中间件；2) 已保存智能体配置；3) 刷新了智能体页面。");
+          }
+          return { success: true, diagnosis };
         } catch (err: any) {
-          return { success: false, loggedIn: false, email, platformUrl, error: err.message };
+          return { success: false, error: err.message };
         }
       },
-      { name: "check_login_status", description: "检查当前平台登录状态，验证 email/password 是否有效、token 是否过期。", schema: z.object({}) }
+      {
+        name: "diagnose_plugin_availability",
+        description: "诊断指定中间件插件为什么其工具不可用。检查加载状态、组件暴露、配置状态和作用域生效情况，并提供修复建议。",
+        schema: z.object({
+          pluginName: z.string().min(1)
+            .describe("插件名称、packageName 或 displayName，例如 '@timmy_hu/bulk-email-sender'")
+        })
+      }
     );
 
     return {
       name: MIDDLEWARE_PROVIDER,
-      tools: [listMiddlewarePlugins, loadMiddlewarePlugin, unloadMiddlewarePlugin, getMiddlewarePluginStatus, refreshPluginCache, batchLoadMiddlewarePlugins, checkLoginStatus]
+      tools: [
+        listMiddlewarePlugins,
+        getMiddlewarePluginDetail,
+        installMiddlewarePlugin,
+        refreshPluginList,
+        checkLoginStatus,
+        searchMiddlewarePlugins,
+        getPluginStatistics,
+        getBindingGuidance,
+        diagnosePluginAvailability
+      ]
     };
   }
 }