@timmy_hu/plugin-middleware 1.0.1 → 1.0.3

package/index.js

@@ -15,8 +15,8 @@ class PluginMiddleware {
         zh_Hans: "插件中间件管理器"
       },
       description: {
-        en_US: "Discovers all middleware-type plugins and provides dynamic on-demand loading, unloading, and status query tools for agent orchestration. 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",
@@ -42,12 +42,6 @@ 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: "缓存有效期（秒）" },
@@ -61,158 +55,143 @@ class PluginMiddleware {
   }
 
   createMiddleware(options = {}, context = {}) {
-    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;
 
-    // In-memory registry
-    const registry = {
-      plugins: new Map(),
-      loadedPlugins: new Map(),
+    const state = {
+      allPlugins: [],
+      middlewarePlugins: [],
       lastRefresh: null,
       cacheTtl: cacheTtlSeconds * 1000,
       token: null,
       tokenExpiry: null
     };
 
-    // ---- Login: call /api/auth/login to get token ----
     async function loginAndGetToken() {
       const now = Date.now();
-      // Reuse token if still valid (within 50 minutes, assuming 1h expiry)
-      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");
       }
-
       const fetch = (await import("node-fetch")).default;
-      const loginUrl = `${platformUrl}/api/auth/login`;
-      const resp = await fetch(loginUrl, {
+      const resp = await fetch(`${platformUrl}/api/auth/login`, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ email, password }),
         timeout: 15000
       });
-
       if (!resp.ok) {
         const errText = await resp.text();
         throw new Error(`登录失败 (${resp.status}): ${errText}`);
       }
-
       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)}`);
+        throw new Error(`登录响应中未找到 token 字段`);
       }
-
-      registry.token = token;
-      // Assume token expires in 50 minutes (conservative)
-      registry.tokenExpiry = now + 50 * 60 * 1000;
+      state.token = token;
+      state.tokenExpiry = now + 50 * 60 * 1000;
       return token;
     }
 
-    // ---- Helper: build auth headers ----
     function authHeaders(token) {
-      const headers = {
-        "Content-Type": "application/json",
-        "Authorization": `Bearer ${token}`
-      };
-      if (organizationId) {
-        headers["organization-id"] = organizationId;
-      }
-      return headers;
+      const h = { "Content-Type": "application/json", "Authorization": `Bearer ${token}` };
+      if (organizationId) h["organization-id"] = organizationId;
+      return h;
     }
 
-    // ---- Fetch middleware plugins from platform ----
-    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, {
+      const resp = await fetch(`${platformUrl}/api/plugin`, {
         method: "GET",
         headers: authHeaders(token),
-        timeout: 10000
+        timeout: 15000
       });
-
       if (!resp.ok) {
-        // If 401, try re-login once
         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}: ${retryResp.statusText}`);
-          }
-          const retryData = await retryResp.json();
-          return parsePluginList(retryData);
+          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}`);
       }
-
       const data = await resp.json();
-      return parsePluginList(data);
+      return processPluginList(data);
     }
 
-    function parsePluginList(data) {
-      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) {
+      const list = Array.isArray(data) ? data : (data.data || data.items || data.plugins || []);
+      state.allPlugins = list;
+      state.middlewarePlugins = list.filter(p => {
+        const meta = p.meta || {};
+        return meta.category === "middleware";
+      });
+      state.lastRefresh = Date.now();
+      return state.allPlugins;
+    }
+
+    function formatMiddlewarePlugin(p) {
+      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 ========
+    // 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;
+          let filtered = state.middlewarePlugins;
+
           if (filter === "loaded") {
-            filtered = plugins.filter(p => p.loaded || registry.loadedPlugins.has(p.code));
-          } else if (filter === "available") {
-            filtered = plugins.filter(p => !p.loaded && !registry.loadedPlugins.has(p.code));
+            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 => ({
-              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
-            }))
+            totalAllPlugins: state.allPlugins.length,
+            totalMiddleware: state.middlewarePlugins.length,
+            filter,
+            plugins: filtered.map(formatMiddlewarePlugin),
+            note: "⚠️ 插件已安装并加载，但需要在 XpertAI 平台 UI 中手动绑定到智能体才能使用其工具。请使用 get_binding_guidance 工具获取绑定指导。"
           };
         } catch (err) {
           return { success: false, error: err.message, plugins: [] };
@@ -220,263 +199,517 @@ class PluginMiddleware {
       },
       {
         name: "list_middleware_plugins",
-        description: "列出所有已发现的中间件类型插件，可按加载状态过滤。返回插件编码、名称、版本、描述和当前状态。",
+        description: "列出平台上所有已安装的中间件类型插件。注意：插件需要在 XpertAI 平台 UI 中手动绑定到智能体。",
         schema: z.object({
-          filter: z.enum(["all", "loaded", "available"]).optional().default("all")
-            .describe("过滤条件：all=全部, loaded=已加载, available=可用未加载")
+          filter: z.enum(["all", "loaded", "error", "updatable"]).optional().default("all")
+            .describe("过滤条件：all=全部, loaded=已加载, error=加载出错, updatable=有可用更新")
         })
       }
     );
 
-    // ======== Tool 2: load_middleware_plugin ========
-    const loadMiddlewarePlugin = tool(
+    // Tool 2: get_middleware_plugin_detail
+    const getMiddlewarePluginDetail = 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" }
-          };
-        }
+        try {
+          await fetchAllPlugins();
+          const keyword = input.pluginNameOrPackage;
+          const found = state.middlewarePlugins.find(p => {
+            const meta = p.meta || {};
+            return p.name === keyword
+              || meta.name === keyword
+              || p.packageName === keyword
+              || meta.displayName === keyword;
+          });
 
-        const plugins = await fetchMiddlewarePlugins();
-        const target = plugins.find(p => p.code === pluginCode);
-        if (!target) {
-          return {
-            success: false,
-            error: `未找到编码为 ${pluginCode} 的中间件插件`,
-            availablePlugins: plugins.map(p => p.code)
-          };
+          if (!found) {
+            return {
+              success: false,
+              error: `未找到名为 "${keyword}" 的中间件插件`,
+              availableMiddleware: state.middlewarePlugins.map(p => ({
+                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) {
+          return { success: false, error: err.message };
         }
+      },
+      {
+        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 3: install_middleware_plugin
+    const installMiddlewarePlugin = tool(
+      async (input) => {
+        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`, {
+          const resp = await fetch(`${platformUrl}/api/plugin`, {
             method: "POST",
             headers: authHeaders(token),
-            body: JSON.stringify({ pluginName: target.name || pluginCode, version: target.version, source: "npm" }),
-            timeout: 30000
+            body: JSON.stringify({ pluginName: packageName, version, source: "npm" }),
+            timeout: 60000
           });
+
           if (!resp.ok) {
             const errText = await resp.text();
-            throw new Error(`Load API returned ${resp.status}: ${errText}`);
+            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
-          });
+          state.lastRefresh = null;
+
           return {
-            success: true, message: `插件 ${pluginCode} 加载成功`,
-            plugin: { code: pluginCode, name: target.name, version: target.version, loadedAt: registry.loadedPlugins.get(pluginCode).loadedAt, status: "loaded" }
+            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) {
-          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 }
+            success: false,
+            error: err.message,
+            packageName,
+            version
           };
         }
       },
       {
-        name: "load_middleware_plugin",
-        description: "按插件编码动态加载指定的中间件插件。加载后该插件的工具和能力将对智能体可用。",
+        name: "install_middleware_plugin",
+        description: "从 npm 安装一个新的中间件插件到 XpertAI 平台。安装后需要在平台 UI 中手动绑定到智能体。",
         schema: z.object({
-          pluginCode: z.string().min(1).describe("要加载的中间件插件编码，例如 'weather-query' 或 'pg-query-tool'")
+          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(
+    // Tool 4: refresh_plugin_list
+    const refreshPluginList = tool(
       async (input) => {
-        const pluginCode = input.pluginCode;
-        if (!registry.loadedPlugins.has(pluginCode)) {
+        state.lastRefresh = null;
+        state.token = null;
+        state.tokenExpiry = null;
+        try {
+          await fetchAllPlugins();
           return {
-            success: false,
-            error: `插件 ${pluginCode} 当前未加载，无需卸载`,
-            loadedPlugins: Array.from(registry.loadedPlugins.keys())
+            success: true,
+            message: `插件列表已刷新，共发现 ${state.allPlugins.length} 个插件，其中 ${state.middlewarePlugins.length} 个中间件类型`,
+            totalPlugins: state.allPlugins.length,
+            totalMiddleware: state.middlewarePlugins.length,
+            refreshedAt: new Date().toISOString()
           };
+        } catch (err) {
+          return { success: false, error: `刷新失败: ${err.message}` };
         }
+      },
+      {
+        name: "refresh_plugin_list",
+        description: "刷新插件列表缓存，强制重新登录并从平台获取所有已安装插件的最新状态。",
+        schema: z.object({})
+      }
+    );
+
+    // Tool 5: check_login_status
+    const checkLoginStatus = tool(
+      async (input) => {
         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) {
-            const errText = await resp.text();
-            throw new Error(`Unload API returned ${resp.status}: ${errText}`);
-          }
+          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) {
-          // Continue with local unload even if API fails
+          return {
+            success: false,
+            loggedIn: false,
+            email,
+            platformUrl,
+            error: err.message
+          };
         }
-        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" }
-        };
       },
       {
-        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(
+    // Tool 6: search_middleware_plugins
+    const searchMiddlewarePlugins = tool(
       async (input) => {
-        const pluginCode = input.pluginCode;
-        const plugins = await fetchMiddlewarePlugins();
-        const target = plugins.find(p => p.code === pluginCode);
-        if (!target) {
-          return { success: false, error: `未找到编码为 ${pluginCode} 的中间件插件` };
+        try {
+          await fetchAllPlugins();
+          const keyword = (input.keyword || "").toLowerCase();
+          const results = state.middlewarePlugins.filter(p => {
+            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) {
+          return { success: false, error: err.message, plugins: [] };
         }
-        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 || []
-          }
-        };
       },
       {
-        name: "get_middleware_plugin_status",
-        description: "查询指定中间件插件的详细状态信息，包括加载状态、版本、描述和可用工具列表。",
+        name: "search_middleware_plugins",
+        description: "按关键词搜索中间件类型插件。搜索范围包括插件名称、包名、描述和关键词。",
         schema: z.object({
-          pluginCode: z.string().min(1).describe("要查询的中间件插件编码")
+          keyword: z.string().min(1).describe("搜索关键词，例如 'echarts'、'email'、'retry'")
         })
       }
     );
 
-    // ======== Tool 5: refresh_plugin_cache ========
-    const refreshPluginCache = tool(
+    // Tool 7: get_plugin_statistics
+    const getPluginStatistics = tool(
       async (input) => {
-        registry.lastRefresh = null;
-        registry.token = null;
-        registry.tokenExpiry = null;
         try {
-          const plugins = await fetchMiddlewarePlugins();
+          await fetchAllPlugins();
+
+          const categoryStats = {};
+          for (const p of state.allPlugins) {
+            const cat = (p.meta || {}).category || "unknown";
+            categoryStats[cat] = (categoryStats[cat] || 0) + 1;
+          }
+
+          const loadStatusStats = {};
+          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,
-            message: `缓存已刷新，发现 ${plugins.length} 个中间件插件`,
-            total: plugins.length,
-            refreshedAt: new Date().toISOString()
+            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) {
-          return { success: false, error: `刷新缓存失败: ${err.message}` };
+          return { success: false, error: err.message };
         }
       },
       {
-        name: "refresh_plugin_cache",
-        description: "刷新中间件插件发现缓存，强制重新登录并获取所有中间件类型插件列表。",
+        name: "get_plugin_statistics",
+        description: "获取平台上所有插件的统计信息，包括按分类统计、按加载状态统计、有更新的插件、有错误的插件等。",
         schema: z.object({})
       }
     );
 
-    // ======== Tool 6: batch_load_middleware_plugins ========
-    const batchLoadMiddlewarePlugins = tool(
+    // Tool 8: get_binding_guidance (NEW)
+    const getBindingGuidance = tool(
       async (input) => {
-        const pluginCodes = input.pluginCodes;
-        const results = [];
-        const plugins = await fetchMiddlewarePlugins();
-        for (const code of pluginCodes) {
-          if (registry.loadedPlugins.has(code)) {
-            results.push({ code, status: "already_loaded", success: true });
-            continue;
+        const pluginName = input.pluginName;
+        
+        try {
+          await fetchAllPlugins();
+          
+          const plugin = state.middlewarePlugins.find(p => {
+            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 target = plugins.find(p => p.code === code);
-          if (!target) {
-            results.push({ code, status: "not_found", success: false, error: `未找到编码为 ${code} 的中间件插件` });
-            continue;
+
+          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: []
+          };
+
+          // 诊断问题
+          if (detail.loadStatus !== "loaded") {
+            guidance.troubleshooting.push({
+              issue: "插件未加载",
+              status: detail.loadStatus,
+              error: detail.loadError,
+              solution: "插件加载失败，请检查插件是否正确安装，或联系插件作者"
+            });
           }
-          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 (detail.componentSummary.total === 0) {
+            guidance.troubleshooting.push({
+              issue: "插件没有暴露任何组件",
+              componentSummary: detail.componentSummary,
+              solution: "插件实现可能有问题，没有正确注册中间件策略或工具。请联系插件作者检查插件代码。"
             });
-            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
+          }
+
+          if (!detail.effectiveInCurrentScope) {
+            guidance.troubleshooting.push({
+              issue: "插件在当前作用域未生效",
+              scopeRelation: detail.scopeRelation,
+              solution: "请在智能体编排页面中手动添加此中间件到智能体"
             });
-            results.push({ code, name: target.name, version: target.version, status: "loaded", success: true, loadedAt: registry.loadedPlugins.get(code).loadedAt });
-          } catch (err) {
-            registry.loadedPlugins.set(code, {
-              code, name: target.name, version: target.version,
-              loadedAt: new Date().toISOString(), loadResult: { offline: true, error: err.message }
+          }
+
+          if (detail.configurationError) {
+            guidance.troubleshooting.push({
+              issue: "插件配置错误",
+              error: detail.configurationError,
+              solution: "请检查并修正插件配置"
             });
-            results.push({ code, name: target.name, version: target.version, status: "loaded_offline", success: true, warning: err.message });
           }
+
+          return {
+            success: true,
+            guidance
+          };
+        } catch (err) {
+          return {
+            success: false,
+            error: err.message
+          };
         }
-        return {
-          success: true, total: pluginCodes.length,
-          loaded: results.filter(r => r.status === "loaded").length,
-          alreadyLoaded: results.filter(r => r.status === "already_loaded").length,
-          failed: results.filter(r => !r.success).length,
-          results
-        };
       },
       {
-        name: "batch_load_middleware_plugins",
-        description: "批量加载多个中间件插件。传入插件编码数组，一次性加载所有指定的中间件插件。",
+        name: "get_binding_guidance",
+        description: "获取将指定中间件插件绑定到智能体的详细步骤指导，包括诊断插件状态和提供故障排除建议。",
         schema: z.object({
-          pluginCodes: z.array(z.string().min(1)).min(1)
-            .describe("要批量加载的中间件插件编码数组，例如 ['weather-query', 'pg-query-tool']")
+          pluginName: z.string().min(1)
+            .describe("插件名称、packageName 或 displayName，例如 '@timmy_hu/bulk-email-sender'")
         })
       }
     );
 
-    // ======== Tool 7: login_status ========
-    const checkLoginStatus = tool(
+    // Tool 9: diagnose_plugin_availability (NEW)
+    const diagnosePluginAvailability = tool(
       async (input) => {
+        const pluginName = input.pluginName;
+        
         try {
-          const token = await loginAndGetToken();
+          await fetchAllPlugins();
+          
+          const plugin = state.middlewarePlugins.find(p => {
+            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;
+
+          // Check 1: 插件是否加载
+          const loadCheck = {
+            name: "插件加载状态",
+            passed: detail.loadStatus === "loaded",
+            status: detail.loadStatus,
+            error: detail.loadError
+          };
+          checks.push(loadCheck);
+          if (!loadCheck.passed) allPassed = false;
+
+          // Check 2: 是否有组件
+          const componentCheck = {
+            name: "组件暴露",
+            passed: detail.componentSummary.total > 0,
+            total: detail.componentSummary.total,
+            breakdown: detail.componentSummary
+          };
+          checks.push(componentCheck);
+          if (!componentCheck.passed) allPassed = false;
+
+          // Check 3: 配置状态
+          const configCheck = {
+            name: "配置状态",
+            passed: !detail.configurationError,
+            status: detail.configurationStatus,
+            error: detail.configurationError
+          };
+          checks.push(configCheck);
+          if (!configCheck.passed) allPassed = false;
+
+          // Check 4: 作用域生效
+          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: []
+          };
+
+          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,
-            loggedIn: true,
-            email: email,
-            platformUrl: platformUrl,
-            tokenExpiry: registry.tokenExpiry ? new Date(registry.tokenExpiry).toISOString() : null,
-            message: "登录状态正常，token 有效"
+            diagnosis
           };
         } catch (err) {
           return {
             success: false,
-            loggedIn: false,
-            email: email,
-            platformUrl: platformUrl,
             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'")
+        })
       }
     );
 
@@ -484,12 +717,14 @@ class PluginMiddleware {
       name: MIDDLEWARE_PROVIDER,
       tools: [
         listMiddlewarePlugins,
-        loadMiddlewarePlugin,
-        unloadMiddlewarePlugin,
-        getMiddlewarePluginStatus,
-        refreshPluginCache,
-        batchLoadMiddlewarePlugins,
-        checkLoginStatus
+        getMiddlewarePluginDetail,
+        installMiddlewarePlugin,
+        refreshPluginList,
+        checkLoginStatus,
+        searchMiddlewarePlugins,
+        getPluginStatistics,
+        getBindingGuidance,
+        diagnosePluginAvailability
       ]
     };
   }
@@ -503,12 +738,12 @@ class PluginModule {}
 const plugin = {
   meta: {
     name: "@timmy_hu/plugin-middleware",
-    version: "1.0.1",
+    version: "1.0.3",
     level: "organization",
     category: "middleware",
     displayName: "插件中间件",
-    description: "自动发现所有中间件类型插件，支持动态按需加载、卸载和状态查询。通过 /api/auth/login 登录获取 token 后调用平台 API。",
-    keywords: ["middleware", "plugin", "discovery", "dynamic-loading", "agent", "orchestration"],
+    description: "自动发现 XpertAI 平台上所有已安装的中间件类型插件，展示加载状态，提供插件绑定指导和诊断工具。注意：插件需要在 XpertAI 平台 UI 中手动绑定到智能体。",
+    keywords: ["middleware", "plugin", "discovery", "install", "binding", "diagnosis", "agent"],
     author: "fpi"
   },
   register(ctx) {