@timmy_hu/plugin-middleware 1.0.2 → 1.0.3

package/.xpertai-plugin/plugin.json

@@ -1,8 +1,8 @@
 {
   "name": "插件中间件",
   "code": "plugin-middleware",
-  "version": "1.0.2",
-  "description": "自动发现 XpertAI 平台上所有已安装的中间件类型插件，展示加载状态，支持从 npm 安装新插件、搜索、统计。通过 /api/auth/login 登录获取 token。",
+  "version": "1.0.3",
+  "description": "自动发现 XpertAI 平台上所有已安装的中间件类型插件，展示加载状态，提供插件绑定指导和诊断工具。注意：插件需要在 XpertAI 平台 UI 中手动绑定到智能体。",
   "createdBy": "fpi",
   "platform": "http://10.161.48.53:3300",
   "category": "middleware",

package/index.js

@@ -15,8 +15,8 @@ class PluginMiddleware {
         zh_Hans: "插件中间件管理器"
       },
       description: {
-        en_US: "Discovers all middleware-type plugins installed on the XpertAI platform, shows their load status, and can install new middleware plugins from npm. Authenticates via /api/auth/login.",
-        zh_Hans: "自动发现 XpertAI 平台上所有已安装的中间件类型插件，展示加载状态，并支持从 npm 安装新的中间件插件。通过 /api/auth/login 登录获取 token。"
+        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",
@@ -61,17 +61,15 @@ class PluginMiddleware {
     const organizationId = options.organizationId || "";
     const cacheTtlSeconds = options.cacheTtlSeconds || 300;
 
-    // In-memory state
     const state = {
-      allPlugins: [],          // 所有插件列表
-      middlewarePlugins: [],   // 中间件类型插件列表
+      allPlugins: [],
+      middlewarePlugins: [],
       lastRefresh: null,
       cacheTtl: cacheTtlSeconds * 1000,
       token: null,
       tokenExpiry: null
     };
 
-    // ======== 登录：调用 /api/auth/login 获取 token ========
     async function loginAndGetToken() {
       const now = Date.now();
       if (state.token && state.tokenExpiry && now < state.tokenExpiry) {
@@ -107,7 +105,6 @@ class PluginMiddleware {
       return h;
     }
 
-    // ======== 获取所有已安装插件（GET /api/plugin） ========
     async function fetchAllPlugins() {
       const now = Date.now();
       if (state.lastRefresh && (now - state.lastRefresh) < state.cacheTtl && state.allPlugins.length > 0) {
@@ -126,8 +123,7 @@ class PluginMiddleware {
           const newToken = await loginAndGetToken();
           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}`);
-          const retryData = await retry.json();
-          return processPluginList(retryData);
+          return processPluginList(await retry.json());
         }
         throw new Error(`Platform API returned ${resp.status}: ${resp.statusText}`);
       }
@@ -146,7 +142,6 @@ class PluginMiddleware {
       return state.allPlugins;
     }
 
-    // ======== 格式化中间件插件信息 ========
     function formatMiddlewarePlugin(p) {
       const meta = p.meta || {};
       return {
@@ -168,11 +163,12 @@ class PluginMiddleware {
         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 {
@@ -194,7 +190,8 @@ class PluginMiddleware {
             totalAllPlugins: state.allPlugins.length,
             totalMiddleware: state.middlewarePlugins.length,
             filter,
-            plugins: filtered.map(formatMiddlewarePlugin)
+            plugins: filtered.map(formatMiddlewarePlugin),
+            note: "⚠️ 插件已安装并加载，但需要在 XpertAI 平台 UI 中手动绑定到智能体才能使用其工具。请使用 get_binding_guidance 工具获取绑定指导。"
           };
         } catch (err) {
           return { success: false, error: err.message, plugins: [] };
@@ -202,7 +199,7 @@ class PluginMiddleware {
       },
       {
         name: "list_middleware_plugins",
-        description: "列出平台上所有已安装的中间件类型插件，可按状态过滤。返回插件名称、版本、描述、加载状态等详细信息。",
+        description: "列出平台上所有已安装的中间件类型插件。注意：插件需要在 XpertAI 平台 UI 中手动绑定到智能体。",
         schema: z.object({
           filter: z.enum(["all", "loaded", "error", "updatable"]).optional().default("all")
             .describe("过滤条件：all=全部, loaded=已加载, error=加载出错, updatable=有可用更新")
@@ -210,7 +207,7 @@ class PluginMiddleware {
       }
     );
 
-    // ======== Tool 2: get_middleware_plugin_detail ========
+    // Tool 2: get_middleware_plugin_detail
     const getMiddlewarePluginDetail = tool(
       async (input) => {
         try {
@@ -236,7 +233,6 @@ class PluginMiddleware {
 
           const detail = formatMiddlewarePlugin(found);
 
-          // 尝试获取组件信息
           try {
             const token = await loginAndGetToken();
             const fetch = (await import("node-fetch")).default;
@@ -251,6 +247,13 @@ class PluginMiddleware {
             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 };
@@ -258,7 +261,7 @@ class PluginMiddleware {
       },
       {
         name: "get_middleware_plugin_detail",
-        description: "查询指定中间件插件的详细信息，包括加载状态、配置状态、组件列表、版本信息等。",
+        description: "查询指定中间件插件的详细信息，包括加载状态、配置状态、组件列表、版本信息和绑定状态。",
         schema: z.object({
           pluginNameOrPackage: z.string().min(1)
             .describe("插件名称、packageName 或 displayName，例如 'echarts-generator' 或 '@timmy_hu/bulk-email-sender'")
@@ -266,7 +269,7 @@ class PluginMiddleware {
       }
     );
 
-    // ======== Tool 3: install_middleware_plugin ========
+    // Tool 3: install_middleware_plugin
     const installMiddlewarePlugin = tool(
       async (input) => {
         const packageName = input.packageName;
@@ -288,8 +291,6 @@ class PluginMiddleware {
           }
 
           const result = await resp.json();
-
-          // 刷新缓存
           state.lastRefresh = null;
 
           return {
@@ -300,7 +301,14 @@ class PluginMiddleware {
               packageName: result.packageName || packageName,
               version: result.currentVersion || version,
               organizationId: result.organizationId || organizationId
-            }
+            },
+            nextSteps: [
+              "1. 插件已安装并加载到平台",
+              "2. 请在 XpertAI 平台 UI 中进入智能体编排页面",
+              "3. 点击\"添加中间件\"按钮",
+              "4. 在列表中找到刚安装的插件并添加",
+              "5. 保存智能体配置后，插件的工具即可使用"
+            ]
           };
         } catch (err) {
           return {
@@ -313,7 +321,7 @@ class PluginMiddleware {
       },
       {
         name: "install_middleware_plugin",
-        description: "从 npm 安装一个新的中间件插件到 XpertAI 平台。安装后插件将自动加载并可供智能体使用。",
+        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")
@@ -321,7 +329,7 @@ class PluginMiddleware {
       }
     );
 
-    // ======== Tool 4: refresh_plugin_list ========
+    // Tool 4: refresh_plugin_list
     const refreshPluginList = tool(
       async (input) => {
         state.lastRefresh = null;
@@ -347,7 +355,7 @@ class PluginMiddleware {
       }
     );
 
-    // ======== Tool 5: check_login_status ========
+    // Tool 5: check_login_status
     const checkLoginStatus = tool(
       async (input) => {
         try {
@@ -380,7 +388,7 @@ class PluginMiddleware {
       }
     );
 
-    // ======== Tool 6: search_middleware_plugins ========
+    // Tool 6: search_middleware_plugins
     const searchMiddlewarePlugins = tool(
       async (input) => {
         try {
@@ -414,33 +422,26 @@ class PluginMiddleware {
       }
     );
 
-    // ======== Tool 7: get_plugin_statistics ========
+    // Tool 7: get_plugin_statistics
     const getPluginStatistics = tool(
       async (input) => {
         try {
           await fetchAllPlugins();
 
-          // 按 category 统计
           const categoryStats = {};
           for (const p of state.allPlugins) {
             const cat = (p.meta || {}).category || "unknown";
             categoryStats[cat] = (categoryStats[cat] || 0) + 1;
           }
 
-          // 按 loadStatus 统计中间件
           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 {
@@ -470,6 +471,248 @@ class PluginMiddleware {
       }
     );
 
+    // Tool 8: get_binding_guidance (NEW)
+    const getBindingGuidance = tool(
+      async (input) => {
+        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 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: "插件加载失败，请检查插件是否正确安装，或联系插件作者"
+            });
+          }
+
+          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) {
+          return {
+            success: false,
+            error: err.message
+          };
+        }
+      },
+      {
+        name: "get_binding_guidance",
+        description: "获取将指定中间件插件绑定到智能体的详细步骤指导，包括诊断插件状态和提供故障排除建议。",
+        schema: z.object({
+          pluginName: z.string().min(1)
+            .describe("插件名称、packageName 或 displayName，例如 '@timmy_hu/bulk-email-sender'")
+        })
+      }
+    );
+
+    // Tool 9: diagnose_plugin_availability (NEW)
+    const diagnosePluginAvailability = tool(
+      async (input) => {
+        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}" 的中间件插件`,
+              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,
+            diagnosis
+          };
+        } catch (err) {
+          return {
+            success: false,
+            error: err.message
+          };
+        }
+      },
+      {
+        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: [
@@ -479,7 +722,9 @@ class PluginMiddleware {
         refreshPluginList,
         checkLoginStatus,
         searchMiddlewarePlugins,
-        getPluginStatistics
+        getPluginStatistics,
+        getBindingGuidance,
+        diagnosePluginAvailability
       ]
     };
   }
@@ -493,12 +738,12 @@ class PluginModule {}
 const plugin = {
   meta: {
     name: "@timmy_hu/plugin-middleware",
-    version: "1.0.2",
+    version: "1.0.3",
     level: "organization",
     category: "middleware",
     displayName: "插件中间件",
-    description: "自动发现 XpertAI 平台上所有已安装的中间件类型插件，展示加载状态，支持从 npm 安装新插件、搜索、统计。通过 /api/auth/login 登录获取 token。",
-    keywords: ["middleware", "plugin", "discovery", "install", "agent", "orchestration"],
+    description: "自动发现 XpertAI 平台上所有已安装的中间件类型插件，展示加载状态，提供插件绑定指导和诊断工具。注意：插件需要在 XpertAI 平台 UI 中手动绑定到智能体。",
+    keywords: ["middleware", "plugin", "discovery", "install", "binding", "diagnosis", "agent"],
     author: "fpi"
   },
   register(ctx) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@timmy_hu/plugin-middleware",
-  "version": "1.0.2",
-  "description": "自动发现所有中间件类型插件，支持动态按需加载、卸载和状态查询",
+  "version": "1.0.3",
+  "description": "自动发现 XpertAI 平台上所有已安装的中间件类型插件，展示加载状态，提供插件绑定指导和诊断工具。注意：插件需要在 XpertAI 平台 UI 中手动绑定到智能体。",
   "main": "index.js",
   "scripts": {
     "build": "echo 'No build step required for CJS plugin'",

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

@@ -15,8 +15,8 @@ export class PluginMiddleware {
       zh_Hans: "插件中间件管理器"
     },
     description: {
-      en_US: "Discovers all middleware-type plugins installed on the XpertAI platform, shows their load status, and can install new middleware plugins from npm. Authenticates via /api/auth/login.",
-      zh_Hans: "自动发现 XpertAI 平台上所有已安装的中间件类型插件，展示加载状态，并支持从 npm 安装新的中间件插件。通过 /api/auth/login 登录获取 token。"
+      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",
@@ -156,6 +156,7 @@ export class PluginMiddleware {
         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 }
       };
     }
@@ -175,7 +176,8 @@ export class PluginMiddleware {
             totalAllPlugins: state.allPlugins.length,
             totalMiddleware: state.middlewarePlugins.length,
             filter,
-            plugins: filtered.map(formatMiddlewarePlugin)
+            plugins: filtered.map(formatMiddlewarePlugin),
+            note: "⚠️ 插件已安装并加载，但需要在 XpertAI 平台 UI 中手动绑定到智能体才能使用其工具。请使用 get_binding_guidance 工具获取绑定指导。"
           };
         } catch (err: any) {
           return { success: false, error: err.message, plugins: [] };
@@ -183,7 +185,7 @@ export class PluginMiddleware {
       },
       {
         name: "list_middleware_plugins",
-        description: "列出平台上所有已安装的中间件类型插件，可按状态过滤。返回插件名称、版本、描述、加载状态等详细信息。",
+        description: "列出平台上所有已安装的中间件类型插件。注意：插件需要在 XpertAI 平台 UI 中手动绑定到智能体。",
         schema: z.object({
           filter: z.enum(["all", "loaded", "error", "updatable"]).optional().default("all")
             .describe("过滤条件：all=全部, loaded=已加载, error=加载出错, updatable=有可用更新")
@@ -223,6 +225,11 @@ export class PluginMiddleware {
           } 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 };
@@ -230,7 +237,7 @@ export class PluginMiddleware {
       },
       {
         name: "get_middleware_plugin_detail",
-        description: "查询指定中间件插件的详细信息，包括加载状态、配置状态、组件列表、版本信息等。",
+        description: "查询指定中间件插件的详细信息，包括加载状态、配置状态、组件列表、版本信息和绑定状态。",
         schema: z.object({
           pluginNameOrPackage: z.string().min(1)
             .describe("插件名称、packageName 或 displayName，例如 'echarts-generator' 或 '@timmy_hu/bulk-email-sender'")
@@ -265,7 +272,14 @@ export class PluginMiddleware {
               packageName: result.packageName || packageName,
               version: result.currentVersion || version,
               organizationId: result.organizationId || organizationId
-            }
+            },
+            nextSteps: [
+              "1. 插件已安装并加载到平台",
+              "2. 请在 XpertAI 平台 UI 中进入智能体编排页面",
+              "3. 点击"添加中间件"按钮",
+              "4. 在列表中找到刚安装的插件并添加",
+              "5. 保存智能体配置后，插件的工具即可使用"
+            ]
           };
         } catch (err: any) {
           return { success: false, error: err.message, packageName, version };
@@ -273,7 +287,7 @@ export class PluginMiddleware {
       },
       {
         name: "install_middleware_plugin",
-        description: "从 npm 安装一个新的中间件插件到 XpertAI 平台。安装后插件将自动加载并可供智能体使用。",
+        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")
@@ -408,6 +422,176 @@ export class PluginMiddleware {
       }
     );
 
+    const getBindingGuidance = tool(
+      async (input) => {
+        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 };
+        }
+      },
+      {
+        name: "get_binding_guidance",
+        description: "获取将指定中间件插件绑定到智能体的详细步骤指导，包括诊断插件状态和提供故障排除建议。",
+        schema: z.object({
+          pluginName: z.string().min(1)
+            .describe("插件名称、packageName 或 displayName，例如 '@timmy_hu/bulk-email-sender'")
+        })
+      }
+    );
+
+    const diagnosePluginAvailability = tool(
+      async (input) => {
+        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}" 的中间件插件`,
+              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, error: err.message };
+        }
+      },
+      {
+        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: [
@@ -417,7 +601,9 @@ export class PluginMiddleware {
         refreshPluginList,
         checkLoginStatus,
         searchMiddlewarePlugins,
-        getPluginStatistics
+        getPluginStatistics,
+        getBindingGuidance,
+        diagnosePluginAvailability
       ]
     };
   }