foliko 2.0.5 → 2.0.7

package/plugins/executors/extension/index.js

@@ -1,25 +1,34 @@
 /**
- * ExtensionExecutorPlugin 扩展插件执行器
+ * ExtensionExecutorPlugin - 扩展插件执行器
  * 统一管理扩展插件（如 gate-trading）的工具，通过 ext_call 调用
+ *
+ * 模块拆分：
+ * - extension-registry.js: 扩展注册表（数据管理）
+ * - prompt-builder.js:     Prompt 构建器（提示词生成）
+ * - skill-helper.js:       Skill 命令辅助
+ * - index.js (本文件):     主入口，组合各模块
  */
 
 const { Plugin } = require('../../../src/plugin/base');
 const { logger } = require('../../../src/common/logger');
 const { z } = require('zod');
-const { PROMPT_PRIORITY } = require('../../../src/common/constants');
-const { zodSchemaToMarkdown, zodSchemaToTable } = require('@chnak/zod-to-markdown');
+
+const { ExtensionRegistry } = require('./extension-registry');
+const { ExtensionPromptBuilder } = require('./prompt-builder');
+const { SkillHelper } = require('./skill-helper');
 
 const log = logger.child('ExtensionExecutor');
 
 class ExtensionExecutorPlugin extends Plugin {
-  // 声明式 prompt parts
+  // 声明式 prompt parts - 由基类自动注册和管理生命周期
   prompts = [
     {
       name: 'extension-tools',
-      slot: 'CAPABILITY',
+      scope: 'global',
+      priority: 60,
       description: '所有扩展工具的说明和使用方式',
       provider: function () {
-        return this._buildExtensionsDescription();
+        return this._promptBuilder.build();
       },
     },
   ];
@@ -33,47 +42,93 @@ class ExtensionExecutorPlugin extends Plugin {
     this.system = true;
 
     this._framework = null;
-    this._extensions = new Map();
+    this._registry = new ExtensionRegistry();
+    this._promptBuilder = new ExtensionPromptBuilder(this._registry, this._registry);
+    this._skillHelper = null; // 延迟到 start 时创建（需要 framework）
   }
 
+  // ============ 生命周期 ============
+
   install(framework) {
     this._framework = framework;
+    this._skillHelper = new SkillHelper(this._registry, framework);
 
-    framework.on('plugin:loaded', (plugin) => {
-      this._scanPluginTools(plugin);
-    });
+    framework.on('plugin:loaded', (plugin) => this._scanPlugin(plugin));
+    framework.on('plugin:reloaded', (plugin) => this._rescanPlugin(plugin));
 
-    framework.on('plugin:reloaded', (plugin) => {
-      this._rescanPluginTools(plugin);
+    // 监听 MCP 工具变化（MCP 工具是异步加载的）
+    // MCP 服务器现在直接注册为 mcp:<server> 扩展，
+    // mcp:tools-changed 事件触发时让 prompt 缓存失效，让 provider 重新渲染
+    framework.on('mcp:tools-changed', () => {
+      this._invalidatePromptCaches();
+    });
+    framework.on('mcp:reloaded', () => {
+      this._invalidatePromptCaches();
     });
-
-    // 不监听 tool:registered — 直接 registerTool 注册的工具通过 AI SDK 暴露给 LLM，无需出现在 Extensions 中
 
     framework.on('framework:ready', () => {
       log.debug('Framework ready, rescanning all plugin tools...');
-      const plugins = framework.pluginManager.getAll();
-      for (const { instance: plugin } of plugins) {
-        if (plugin.name === 'skill-manager') {
-          continue;
-        }
-        this._scanPluginTools(plugin);
-      }
-      this._invalidatePromptCaches(framework);
+      this._scanAllPlugins();
+      this._invalidatePromptCaches();
     });
 
     return this;
   }
 
-  _scanPluginTools(plugin, extName) {
-    if (!plugin || !plugin.tools || typeof plugin.tools !== 'object') {
-      return;
+  async start(framework) {
+    super.start(framework);
+    this._framework = framework;
+    this._registry._framework = framework;
+    this._promptBuilder = new ExtensionPromptBuilder(this._registry, framework);
+    this._skillHelper = new SkillHelper(this._registry, framework);
+
+    this._scanAllPlugins();
+    this._registerBuiltinTools(framework);
+
+    this._invalidatePromptCaches();
+    return this;
+  }
+
+  async reload(framework) {
+    this._framework = framework;
+    this._registry.clear();
+    this._scanAllPlugins();
+    this._invalidatePromptCaches();
+  }
+
+  uninstall(framework) {
+    this._registry.clear();
+    this._framework = null;
+  }
+
+  // ============ 扫描插件 ============
+
+  _scanAllPlugins() {
+    if (!this._framework) return;
+    const plugins = this._framework.pluginManager.getAll();
+    for (const { instance: plugin } of plugins) {
+      if (plugin.name === 'skill-manager') continue;
+      this._scanPlugin(plugin);
     }
+  }
 
-    const pluginName = plugin.name;
-    if (!pluginName) return;
+  /**
+   * 扫描单个插件的工具
+   * 兼容两种注册方式：
+   *   1. plugin.tools = { name: toolDef }     - 旧的静态方式
+   *   2. plugin._registeredExtensions = [...] - 新的 this.extension.register() 方式
+   */
+  _scanPlugin(plugin) {
+    if (!plugin || !plugin.name) return;
 
-    const useExtName = extName || pluginName;
+    this._scanPluginTools(plugin);
+    this._scanRegisteredExtensions(plugin);
+  }
 
+  _scanPluginTools(plugin) {
+    if (!plugin.tools || typeof plugin.tools !== 'object') return;
+
+    const useExtName = plugin.name;
     const pluginInfo = {
       name: useExtName,
       description: plugin.description || '',
@@ -82,7 +137,6 @@ class ExtensionExecutorPlugin extends Plugin {
 
     for (const [toolName, toolDef] of Object.entries(plugin.tools)) {
       if (!toolDef || typeof toolDef !== 'object') continue;
-
       this.registerTool(useExtName, pluginInfo, {
         name: toolName,
         description: toolDef.description || '',
@@ -91,504 +145,418 @@ class ExtensionExecutorPlugin extends Plugin {
       });
     }
 
-    log.debug(` Scanned ${Object.keys(plugin.tools).length} tools from plugin '${pluginName}' (as '${useExtName}')`);
+    log.debug(` Scanned ${Object.keys(plugin.tools).length} tools from plugin '${plugin.name}'`);
+  }
+
+  _scanRegisteredExtensions(plugin) {
+    if (!plugin._registeredExtensions || !Array.isArray(plugin._registeredExtensions)) return;
 
-    if (this._framework && this._framework._ready) {
-      this._invalidatePromptCaches(this._framework);
+    const pluginInfo = {
+      name: plugin.name,
+      description: plugin.description || '',
+      version: plugin.version || '1.0.0',
+    };
+
+    for (const { extName, toolDef } of plugin._registeredExtensions) {
+      this.registerTool(extName || plugin.name, pluginInfo, toolDef);
     }
+
+    log.debug(` Scanned ${plugin._registeredExtensions.length} extensions from plugin '${plugin.name}'`);
+  }
+
+  _rescanPlugin(plugin) {
+    if (!plugin || !plugin.name) return;
+    this._registry.clearPlugin(plugin.name);
+    this._scanPlugin(plugin);
   }
 
-  _rescanPluginTools(plugin) {
-    if (!plugin || !plugin.tools || typeof plugin.tools !== 'object') {
+  // ============ 注册/注销工具 ============
+
+  /**
+   * 注册扩展工具（供 Plugin 基类 extension.register 调用）
+   */
+  registerTool(pluginName, pluginInfo, toolDef) {
+    if (!toolDef || !toolDef.name) {
+      log.warn(`[ExtensionExecutor] Invalid tool definition for '${pluginName}'`);
       return;
     }
 
-    const pluginName = plugin.name;
-    if (!pluginName) return;
-
-    const extName = pluginName === 'skill-manager' ? 'skill' : pluginName;
-
-    const keysToRemove = [extName, pluginName];
-    for (const key of keysToRemove) {
-      if (this._extensions.has(key)) {
-        const ext = this._extensions.get(key);
-        for (const tool of ext.tools || []) {
-          if (this._framework?.toolRouter) {
-            this._framework.toolRouter.unregister(`ext_${tool.name}`);
-          }
-        }
-        this._extensions.delete(key);
-      }
-    }
+    this._registry.registerTool(pluginName, pluginInfo, toolDef);
+    this._invalidatePromptCaches();
+  }
 
-    this._scanPluginTools(plugin, extName);
+  /**
+   * 注销扩展工具（供 Plugin 基类 extension.remove 调用）
+   */
+  _unregisterTool(pluginName, toolName) {
+    this._registry.unregisterTool(pluginName, toolName);
+    if (this._framework?.toolRouter) {
+      this._framework.toolRouter.unregister(`ext_${toolName}`);
+    }
+    this._invalidatePromptCaches();
   }
 
-  async start(framework) {
-    super.start(framework);
-    const plugins = framework.pluginManager.getAll();
-    for (const { instance: plugin } of plugins) {
-      if (plugin.name === 'skill-manager') {
-        continue;
-      }
-      this._scanPluginTools(plugin);
+  // ============ 缓存管理 ============
+
+  _invalidatePromptCaches() {
+    this._framework?.prompts?.invalidate(this.name, 'extension-tools');
+    for (const agent of this._framework?._agents || []) {
+      agent._invalidateSystemPromptCache?.();
     }
+  }
+
+  // ============ 内置工具 ============
 
-    this._mcpExecutor = framework.pluginManager?.get('mcp') || null;
+  _registerBuiltinTools(framework) {
+    framework.registerTool(this._createExtCallTool());
+    framework.registerTool(this._createExtListTool());
+    framework.registerTool(this._createExtSkillTool());
+  }
 
-    framework.registerTool({
+  _createExtCallTool() {
+    return {
       name: 'ext_call',
-      description: '调用扩展插件的工具（包括 MCP 服务器工具）。注意：使用前必须先调用 ext_skill 获取详细参数和使用方法',
+      description:
+        '【⚡ 执行扩展工具】调用某个扩展插件的具体工具。\n' +
+        '\n' +
+        '**必传参数**：\n' +
+        '- `plugin`：插件名（命名空间支持 4 种：普通插件名 `email` / MCP 服务器 `mcp:<server>` / Skill `skill:<name>` / Python 插件 `python:<plugin>`）\n' +
+        '- `tool`：工具名（来自 ext_list 或 ext_skill 输出）\n' +
+        '- `args`：参数对象（每个工具的必填项见 ext_skill 输出）\n' +
+        '\n' +
+        '**推荐使用顺序**：`ext_list` 查看所有可用插件 → `ext_skill` 查看参数细节 → `ext_call` 执行\n' +
+        '\n' +
+        '**调用示例**：\n' +
+        '```js\n' +
+        'ext_call({\n' +
+        '  plugin: "mcp:designmd",\n' +
+        '  tool: "search_design_kits",\n' +
+        '  args: { query: "modern" }\n' +
+        '})\n' +
+        '```\n' +
+        '\n' +
+        '**返回值**：`{success: true, data: <工具返回的数据>}` 或 `{success: false, error: "<错误信息>"}`\n' +
+        '**注意**：调用前必须先调 ext_skill 确认参数格式和必填项，否则可能因参数缺失失败',
       inputSchema: z.object({
-        plugin: z.string().describe('插件名称（如 email, gate-trading, mcp）'),
-        tool: z.string().describe('工具名称'),
-        args: z.record(z.any()).optional().describe('工具参数'),
+        plugin: z.string().describe('插件名称（如 email, gate-trading, mcp:designmd, skill:my-skill, python:stock）'),
+        tool: z.string().describe('工具名称（来自 ext_list 输出）'),
+        args: z.record(z.any()).optional().describe('工具参数（对象格式，详见 ext_skill 输出）'),
       }),
       execute: async (args) => {
         const { plugin, tool, args: toolArgs = {} } = args;
-
-        if (plugin === 'mcp' && this._mcpExecutor) {
-          const mcpToolDef = this._mcpExecutor.tools?.[tool];
-          if (mcpToolDef && mcpToolDef.execute) {
-            return await mcpToolDef.execute(toolArgs || {});
-          }
-          return { success: false, error: `MCP tool '${tool}' not found` };
-        }
-
-        const ext = this._extensions.get(plugin);
-        if (!ext) {
-          framework.emit('tool:error', {
-            name: `${plugin}:${tool}`,
-            args: toolArgs,
-            error: `扩展插件 '${plugin}' 不存在`,
-            source: 'extension'
-          });
-          return { success: false, error: `扩展插件 '${plugin}' 不存在` };
-        }
-
-        const toolDef = ext.tools.find((t) => t.name === tool);
-        if (!toolDef) {
-          framework.emit('tool:error', {
-            name: `${plugin}:${tool}`,
-            args: toolArgs,
-            error: `扩展工具 '${tool}' 不存在`,
-            source: 'extension'
-          });
-          return { success: false, error: `扩展工具 '${tool}' 不存在` };
-        }
-
-        try {
-          framework.emit('tool:call', {
-            name: `${plugin}:${tool}`,
-            args: toolArgs,
-            source: 'extension'
-          });
-          framework.emit('tool-call', {
-            name: `${plugin}:${tool}`,
-            args: toolArgs,
-            source: 'extension'
-          });
-
-          const result = await toolDef.execute(toolArgs, framework);
-
-          if (result && result.success === false && result.error) {
-            framework.emit('tool:error', {
-              name: `${plugin}:${tool}`,
-              args: toolArgs,
-              error: result.error,
-              source: 'extension'
-            });
-            return result;
-          }
-
-          framework.emit('tool:result', {
-            name: `${plugin}:${tool}`,
-            args: toolArgs,
-            result,
-            source: 'extension'
-          });
-
-          return { success: true, data: result };
-        } catch (err) {
-          log.error(` Tool '${tool}' failed:`, err.message);
-
-          framework.emit('tool:error', {
-            name: `${plugin}:${tool}`,
-            args: toolArgs,
-            error: err.message,
-            source: 'extension'
-          });
-
-          return { success: false, error: err.message };
-        }
+        return this._executeExtensionTool(plugin, tool, toolArgs);
       },
-    });
+    };
+  }
 
-    framework.registerTool({
+  _createExtListTool() {
+    return {
       name: 'ext_list',
-      description: '列出所有可用的扩展插件及其工具',
+      description:
+        '【📋 扩展工具清单】列出所有可用的扩展插件及其工具。\n' +
+        '\n' +
+        '**用途**：作为使用扩展的第一步，先调用本工具了解可用能力。\n' +
+        '\n' +
+        '**返回格式**：\n' +
+        '```js\n' +
+        '{\n' +
+        '  success: true,\n' +
+        '  data: [\n' +
+        '    { name: "email", description: "...", tools: [{ name: "send_mail", description: "..." }] },\n' +
+        '    { name: "mcp:designmd", description: "...", tools: [...] }\n' +
+        '  ]\n' +
+        '}\n' +
+        '```\n' +
+        '\n' +
+        '**命名空间规则**：返回的 plugin 名支持 4 种命名空间：\n' +
+        '- 普通插件：`email`, `gate-trading`\n' +
+        '- MCP 服务器：`mcp:<servername>`（如 `mcp:designmd`）\n' +
+        '- Skill：`skill:<name>`（如 `skill:ambient-agent`）\n' +
+        '- Python 插件：`python:<plugin>`（如 `python:stock`）\n' +
+        '\n' +
+        '**推荐使用顺序**：`ext_list` → `ext_skill` → `ext_call`',
       inputSchema: z.object({}),
       execute: async () => {
-        const extensions = [];
-        for (const [name, ext] of this._extensions) {
-          extensions.push({
-            name,
-            description: ext.description,
-            version: ext.version,
-            tools: ext.tools.filter(t => t && t.name).map((t) => ({ name: t.name, description: t.description })),
-          });
-        }
+        const extensions = this._registry.getAll().map((ext) => ({
+          name: ext.name,
+          description: ext.description,
+          version: ext.version,
+          tools: ext.tools
+            .filter((t) => t && t.name)
+            .map((t) => ({ name: t.name, description: t.description })),
+        }));
         return { success: true, data: extensions };
       },
-    });
+    };
+  }
 
-    framework.registerTool({
+  _createExtSkillTool() {
+    return {
       name: 'ext_skill',
-      description: '查询扩展工具的调用参数结构',
+      description:
+        '【📖 扩展参数手册】查询某个扩展插件的详细参数结构。\n' +
+        '\n' +
+        '**必传参数**：`plugin`（支持 `mcp:<server>`, `skill:<name>`, `python:<plugin>`, 普通插件名）\n' +
+        '\n' +
+        '**返回内容**：Markdown 格式，包含：\n' +
+        '- 插件标题、描述、类型元数据\n' +
+        '- 快速调用示例（可直接复制）\n' +
+        '- 每个工具的参数表（含必填/可选、类型、描述）\n' +
+        '\n' +
+        '**典型使用**：找到陌生工具的必填参数 → 调用 ext_skill 看详情 → 再用 ext_call 执行\n' +
+        '\n' +
+        '**调用示例**：\n' +
+        '```js\n' +
+        'ext_skill({ plugin: "mcp:designmd" })\n' +
+        '```\n' +
+        '\n' +
+        '**插件不存在时**：返回友好的错误提示（包含可能原因和排查步骤）',
       inputSchema: z.object({
-        plugin: z.string().describe('扩展插件名称')
+        plugin: z.string().describe('扩展插件名称（如 mcp:designmd, skill:my-skill, python:stock, email）'),
       }),
       execute: async (args) => {
         const { plugin } = args;
-        if (plugin === 'skill') {
-          return "请使用 `skill_load` 获取skill的使用详情"
-        }
-        return this.bindAllToolSkill(plugin)
+        return this._promptBuilder.buildSkill(plugin);
       },
-    });
-
-    framework.on('agent:created', (agent) => {
-      // Extension tool 描述已通过 prompts 声明式注册到 framework.prompts，
-      // 并由 _syncPromptParts 同步到子 Agent，无需再注入 _originalPrompt
-    });
+    };
+  }
 
-    // Extension tool 描述已通过 prompts 声明式注册到 framework.prompts，
-    // 不再需要 _refreshAllAgentsExtPrompt 注入 _originalPrompt
+  // ============ 工具执行 ============
 
-    // prompt part 由基类 _autoRegisterPrompts 自动处理
+  /**
+   * 执行扩展工具（供 ext_call 工具调用）
+   */
+  async _executeExtensionTool(plugin, tool, toolArgs) {
+    return this._doExecute(plugin, tool, toolArgs, { source: 'ext_call', emitEvent: true });
+  }
 
-    return this;
+  /**
+   * 执行扩展工具（供 Plugin 基类 extension.execute 调用）
+   */
+  async _executeTool(pluginName, toolName, args) {
+    return this._doExecute(pluginName, toolName, args, { source: 'plugin_extension', emitEvent: false });
   }
 
-  registerTool(pluginName, pluginInfo, toolDef) {
-    if (!toolDef || !toolDef.name) {
-      log.warn(`[ExtensionExecutor] Invalid tool definition for '${pluginName}'`);
-      return;
+  /**
+   * 统一的工具执行内部实现
+   * @private
+   */
+  async _doExecute(plugin, tool, toolArgs, { source, emitEvent }) {
+    // 1) 插件存在性检查 + 友好错误
+    const ext = this._registry.getPlugin(plugin);
+    if (!ext) {
+      return this._pluginNotFoundError(plugin);
     }
 
-    if (!this._extensions.has(pluginName)) {
-      this._extensions.set(pluginName, {
-        name: pluginInfo.name || pluginName,
-        description: pluginInfo.description || '',
-        version: pluginInfo.version || '1.0.0',
-        tools: [],
-      });
+    // 2) 工具存在性检查 + 友好错误
+    const toolDef = ext.tools.find((t) => t.name === tool);
+    if (!toolDef) {
+      return this._toolNotFoundError(plugin, ext, tool);
     }
 
-    const ext = this._extensions.get(pluginName);
-    const existingIdx = ext.tools.findIndex((t) => t.name === toolDef.name);
-    const toolEntry = {
-      name: toolDef.name,
-      description: toolDef.description || '',
-      inputSchema: toolDef.inputSchema,
-      execute: toolDef.execute,
-    };
-    if (toolDef._options) {
-      toolEntry._options = toolDef._options;
-    }
-    if (existingIdx >= 0) {
-      ext.tools[existingIdx] = toolEntry;
-    } else {
-      ext.tools.push(toolEntry);
+    // 3) 参数预校验（Zod schema）
+    if (toolDef.inputSchema && typeof toolDef.inputSchema.safeParse === 'function') {
+      const parsed = toolDef.inputSchema.safeParse(toolArgs);
+      if (!parsed.success) {
+        return this._paramValidationError(plugin, tool, parsed.error);
+      }
     }
 
-    //log.debug(` Registered tool '${toolDef.name}' for extension '${pluginName}'`);
-
-    if (this._framework && this._framework._ready) {
-      this._invalidatePromptCaches(this._framework);
+    // 4) 触发事件（可选）
+    if (emitEvent) {
+      this._framework?.emit?.('tool-call', {
+        name: `${plugin}:${tool}`,
+        args: toolArgs,
+        source,
+      });
     }
-  }
 
-  bindAllToolSkill(pluginName) {
-    const mcp = this._framework.pluginManager.get('mcp');
-    const sections = [
-      '你可以通过 `ext_call` 工具调用以下扩展插件的功能。',
-      '',
-      '### 调用规则',
-      '',
-      '> **重要**：',
-      '> 1. 调用前必须指定 `plugin`（插件名）和 `tool`（工具名）',
-      '> 2. 参数通过 `args` 对象传入，参数名和类型见各工具说明，注意引号的问题，遵守JSON的格式',
-      '> 3. 必填参数（Required）必须提供，可选参数（Optional）可省略',
-      '',
-      '---',
-      '',
-    ];
-
-    const ext = this._extensions.get(pluginName);
-    if (!ext) return '找不到扩展！'
-    for (const tool of ext.tools) {
-      sections.push(`#### \`${tool.name}\``, '');
-      sections.push(tool.description || '无描述', '');
-      if (ext.name === 'mcp' && mcp) {
-        const mcp_desc = mcp._bindMcpParamsDesc(tool.inputSchema);
-        sections.push(mcp_desc, '');
-      } else if (tool.inputSchema) {
-        try {
-          const schemaMarkdown = zodSchemaToMarkdown(tool.inputSchema);
-          sections.push('**参数：**', ' ');
-          sections.push(schemaMarkdown || '无', ' ');
-        } catch (e) {
-          const schemaTable = zodSchemaToTable(tool.inputSchema);
-          sections.push('**参数：**', ' ');
-          sections.push(schemaTable || '无', ' ');
-        }
-      }
+    // 5) 执行
+    try {
+      const result = await toolDef.execute(toolArgs, this._framework);
+      return { success: true, data: result };
+    } catch (err) {
+      return this._executionError(plugin, tool, err);
     }
+  }
 
-    sections.push('');
-    return sections.join('\n')
+  // ============ 错误处理辅助方法 ============
+
+  /** 插件不存在错误 */
+  _pluginNotFoundError(plugin) {
+    const allPlugins = this._registry.listPlugins();
+    const namespaces = this._groupByNamespace(allPlugins);
+    const similar = this._findSimilar(plugin, allPlugins);
+
+    return {
+      success: false,
+      error: `扩展插件 '${plugin}' 不存在`,
+      hint: similar.length > 0
+        ? `你可能想用：${similar.slice(0, 3).join(', ')}`
+        : `可用插件：\n${this._formatNamespaceList(namespaces)}`,
+      availableNamespaces: namespaces,
+      similar: similar.slice(0, 3),
+    };
   }
 
-  /**
-   * 失效所有 Agent 的延展工具 prompt 缓存
-   * 不再注入 _originalPrompt，仅失效缓存让下次 build 时自动读取最新 _buildExtensionsDescription()
-   */
-  _invalidatePromptCaches(framework) {
-    framework?.prompts?.invalidate(this.name, 'extension-tools');
-    for (const agent of framework?._agents || []) {
-      agent._invalidateSystemPromptCache?.();
-    }
+  /** 工具不存在错误 */
+  _toolNotFoundError(plugin, ext, tool) {
+    const availableTools = ext.tools.map((t) => t.name);
+    const similar = this._findSimilar(tool, availableTools);
+
+    return {
+      success: false,
+      error: `扩展工具 '${tool}' 不存在（插件 '${plugin}'）`,
+      hint: similar.length > 0
+        ? `你可能想用：${similar.slice(0, 3).join(', ')}`
+        : `可用工具（${availableTools.length} 个）：${availableTools.slice(0, 10).join(', ')}${availableTools.length > 10 ? '...' : ''}`,
+      availableTools,
+      similar: similar.slice(0, 3),
+    };
   }
 
-  _buildExtensionsDescription() {
-    let desc = '';
+  /** 参数校验错误（Zod） */
+  _paramValidationError(plugin, tool, zodError) {
+    const issues = (zodError && zodError.issues) || [];
+    const formatted = issues.slice(0, 5).map((iss) => {
+      const path = (iss.path && iss.path.length > 0 ? iss.path.join('.') : '<root>');
+      return `  - ${path}: ${iss.message}`;
+    }).join('\n');
+
+    return {
+      success: false,
+      error: `参数校验失败：'${plugin}:${tool}'`,
+      details: formatted,
+      issuesCount: issues.length,
+      hint: '请使用 ext_skill({ plugin: "' + plugin + '" }) 查看完整参数说明',
+    };
+  }
 
-    if (this._extensions.size > 0 || (this._mcpExecutor && Object.keys(this._mcpExecutor.tools || {}).length > 0)) {
-      desc += '## 【Extensions】扩展插件\n\n';
-      desc += '**使用流程（必须按顺序执行）：**\n';
-      desc += '1. 调用 `ext_skill({ plugin: "<plugin_name>" })` 获取技能命令的详细参数\n';
-      desc += '2. 根据返回的参数定义，使用 `ext_call({ plugin: "<plugin_name>", tool: "<tool_name>", args: {...} })` 调用\n\n';
-      desc += '> **警告**：禁止在未执行第1步获取参数的情况下直接调用 `ext_call`！\n\n';
+  /** 执行时错误 */
+  _executionError(plugin, tool, err) {
+    const message = (err && err.message) || String(err);
+    const stack = (err && err.stack) ? err.stack.split('\n').slice(0, 5).join('\n') : '';
+    log.error(`Tool '${plugin}:${tool}' failed:`, message);
+    if (stack) log.debug(`  Stack: ${stack}`);
+
+    return {
+      success: false,
+      error: message,
+      errorType: (err && err.name) || 'Error',
+      stack,
+      timeout: message.includes('timeout'),
+    };
+  }
 
-      for (const [name, ext] of this._extensions) {
-          if (name === 'mcp' || name === 'skill') continue;
-          desc += `### ${ext.name || name}\n`;
-          desc += `${ext.description || '无描述'}\n`;
-          const validTools = ext.tools.filter(t => t && t.name);
-          desc += `**工具:** ${validTools.map(t => `\`${t.name}\``).join(', ')}\n\n`;
+  // ============ 匹配/格式化辅助方法 ============
+
+  /** 模糊匹配（包含 / 编辑距离），返回相似名称列表 */
+  _findSimilar(target, candidates, max = 5) {
+    if (!target || !Array.isArray(candidates) || candidates.length === 0) return [];
+    const lower = String(target).toLowerCase();
+    const threshold = Math.max(2, Math.floor(lower.length / 3));
+
+    const scored = [];
+    for (const c of candidates) {
+      if (typeof c !== 'string') continue;
+      const cl = c.toLowerCase();
+      // 1) 包含关系
+      if (cl.includes(lower) || lower.includes(cl)) {
+        scored.push({ name: c, score: 1 });
+        continue;
       }
-
-      if (this._mcpExecutor && Object.keys(this._mcpExecutor.tools || {}).length > 0) {
-        desc += '### mcp (MCP 服务器工具)\n';
-        desc += '已注册为 `服务器_工具名` 格式\n';
-        desc += `**工具:** ${Object.keys(this._mcpExecutor.tools).map(t => `\`${t}\``).join(', ')}\n`;
+      // 2) 编辑距离
+      const dist = this._levenshtein(lower, cl);
+      if (dist <= threshold) {
+        scored.push({ name: c, score: 1 - dist / Math.max(lower.length, cl.length) });
       }
-
-      desc += '\n## 禁止事项\n';
-      desc += '- 不先调用 `ext_skill` 获取参数就直接使用 `ext_call`\n';
     }
 
-    if (!desc) {
-      return '';
-    }
-
-    return desc.trim();
+    return scored
+      .sort((a, b) => b.score - a.score)
+      .slice(0, max)
+      .map((s) => s.name);
   }
 
-  _convertSchemaToMarkdown(inputSchema) {
-    if (!inputSchema) return null;
-
-    let schema = inputSchema;
-    if (inputSchema.jsonSchema) schema = inputSchema.jsonSchema;
-    if (inputSchema.inputSchema) schema = inputSchema.inputSchema;
-
-    const isZodSchema = typeof schema.shape === 'function' || (schema._def && schema._def.typeName);
-    if (isZodSchema) {
-      return zodSchemaToMarkdown(schema);
-    }
-
-    if (schema.properties) {
-      const zodSchema = this._jsonSchemaToZod(schema);
-      if (zodSchema) {
-        return zodSchemaToMarkdown(zodSchema);
+  /** Levenshtein 编辑距离（带长度预筛） */
+  _levenshtein(a, b) {
+    if (Math.abs(a.length - b.length) > 5) return 99;
+    const m = a.length, n = b.length;
+    if (m === 0) return n;
+    if (n === 0) return m;
+    const dp = Array.from({ length: m + 1 }, (_, i) => {
+      const row = new Array(n + 1);
+      row[0] = i;
+      return row;
+    });
+    for (let j = 0; j <= n; j++) dp[0][j] = j;
+    for (let i = 1; i <= m; i++) {
+      for (let j = 1; j <= n; j++) {
+        dp[i][j] = a[i - 1] === b[j - 1]
+          ? dp[i - 1][j - 1]
+          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
       }
     }
-
-    return this._schemaToMarkdown(schema);
+    return dp[m][n];
   }
 
-  _jsonSchemaToZod(jsonSchema) {
-    if (!jsonSchema || !jsonSchema.properties) return null;
-
-    try {
-      const shape = {};
-      const properties = jsonSchema.properties;
-      const required = jsonSchema.required || [];
-
-      for (const [key, prop] of Object.entries(properties)) {
-        shape[key] = this._jsonSchemaPropToZod(prop, required.includes(key));
+  /** 按命名空间分组插件名 */
+  _groupByNamespace(plugins) {
+    const groups = {};
+    for (const p of plugins) {
+      let ns = 'plugin';
+      if (typeof p === 'string') {
+        if (p.startsWith('mcp:')) ns = 'mcp';
+        else if (p.startsWith('skill:')) ns = 'skill';
+        else if (p.startsWith('python:')) ns = 'python';
       }
-
-      return z.object(shape);
-    } catch (e) {
-      return null;
+      if (!groups[ns]) groups[ns] = [];
+      groups[ns].push(p);
     }
+    return groups;
   }
 
-  _jsonSchemaPropToZod(prop, isRequired) {
-    if (prop.enum) {
-      let zodType = z.string().enum(prop.enum);
-      if (prop.nullable) zodType = zodType.nullable();
-      return isRequired ? zodType : zodType.optional();
-    }
-
-    const type = prop.type || 'string';
-    switch (type) {
-      case 'string':
-        return isRequired ? z.string() : z.string().optional();
-      case 'number':
-      case 'integer':
-        return isRequired ? z.number() : z.number().optional();
-      case 'boolean':
-        return isRequired ? z.boolean() : z.boolean().optional();
-      case 'array':
-        return isRequired ? z.array(z.any()) : z.array(z.any()).optional();
-      case 'object':
-        if (prop.properties) {
-          const nested = {};
-          for (const [k, v] of Object.entries(prop.properties)) {
-            nested[k] = this._jsonSchemaPropToZod(v, prop.required?.includes(k) || false);
-          }
-          return isRequired ? z.object(nested) : z.object(nested).optional();
-        }
-        return isRequired ? z.record(z.any()) : z.record(z.any()).optional();
-      default:
-        return isRequired ? z.any() : z.any().optional();
+  /** 格式化命名空间列表为多行文本 */
+  _formatNamespaceList(namespaces) {
+    const lines = [];
+    for (const [ns, items] of Object.entries(namespaces)) {
+      const head = items.slice(0, 5).join(', ');
+      const more = items.length > 5 ? ` (+${items.length - 5} more)` : '';
+      lines.push(`  [${ns}] ${head}${more}`);
     }
+    return lines.join('\n');
   }
 
-  _schemaToMarkdown(schema) {
-    if (!schema || !schema.properties) return null;
-
-    const props = schema.properties || {};
-    const required = schema.required || [];
-    let md = '';
-
-    for (const [key, prop] of Object.entries(props)) {
-      const isRequired = required.includes(key);
-      const type = prop.type || 'any';
-      const descText = prop.description || '';
-      md += `- \`${key}\`${isRequired ? ' (必填)' : ''}: ${type} ${descText}\n`;
-    }
-    return md || null;
-  }
+  // ============ 公开查询 API ============
 
   getExtensions() {
-    return Array.from(this._extensions.entries()).map(([name, ext]) => ({
-      name,
-      description: ext.description,
-      version: ext.version,
-      tools: ext.tools,
-    }));
+    return this._registry.getAll();
   }
 
-  // 获取指定插件的所有工具
   getExtensionTools(pluginName) {
-    const ext = this._extensions.get(pluginName);
-    return ext ? ext.tools : [];
+    return this._registry.listTools(pluginName);
   }
 
-  // 获取指定插件的指定工具
   getExtensionTool(pluginName, toolName) {
-    const ext = this._extensions.get(pluginName);
-    if (!ext) return null;
-    return ext.tools.find(t => t.name === toolName) || null;
+    return this._registry.getTool(pluginName, toolName);
   }
 
-  // 获取所有插件名称
   getExtensionNames() {
-    return Array.from(this._extensions.keys());
+    return this._registry.listPlugins();
   }
 
+  // Skill 命令相关
   getSkillCommands() {
-    const ext = this._extensions.get('skill');
-    if (!ext) return [];
-    return ext.tools
-      .filter(t => t && t.name)
-      .map(t => ({
-        name: t.name.replace(/^([^:]+):(.*)$/, '$1:$2'),
-        description: t.description || t.name,
-        options: t._options || null,
-      }));
+    return this._skillHelper?.getCommands() || [];
   }
 
   getSkillCommandsHelp() {
-    const ext = this._extensions.get('skill');
-    if (!ext || ext.tools.length === 0) return '';
-
-    const lines = [];
-    for (const tool of ext.tools) {
-      if (!tool || !tool.name) continue;
-      const parts = tool.name.split(':');
-      if (parts.length === 2) {
-        lines.push(`/${parts[0]}:${parts[1]} - ${tool.description || '无描述'}`);
-      }
-    }
-    return lines.join('\n');
+    return this._skillHelper?.getCommandsHelp() || '';
   }
 
   async executeSkillCommand(command, args) {
-    if (!command.includes(':')) return null;
-    try {
-      const result = await this._framework.executeTool('ext_call', {
-        plugin: 'skill',
-        tool: command,
-        args: { command: args }
-      });
-      return result.success !== false ? result : null;
-    } catch (err) {
-      log.warn('Skill command failed:', err.message);
-      return null;
-    }
-  }
-
-  async reload(framework) {
-    this._framework = framework;
-    this._extensions.clear();
-    const plugins = framework.pluginManager.getAll();
-    for (const { instance: plugin } of plugins) {
-      this._rescanPluginTools(plugin);
-    }
-    this._mcpExecutor = framework.pluginManager?.get('mcp') || null;
-    this._invalidatePromptCaches(framework);
-
-    await this._reloadMCPConfig(framework);
-  }
-
-  async _reloadMCPConfig(framework) {
-    const fs = require('fs');
-    const path = require('path');
-    const mcpExecutor = framework.pluginManager?.get('mcp');
-    if (!mcpExecutor) return;
-
-    try {
-      const configPath = path.resolve('.foliko/mcp_config.json');
-      if (fs.existsSync(configPath)) {
-        const configContent = fs.readFileSync(configPath, 'utf8');
-        const config = JSON.parse(configContent);
-        await mcpExecutor.reloadConfig(config);
-        logger.info(' MCP config reloaded via extension-executor');
-      }
-    } catch (err) {
-      logger.warn(' Failed to reload MCP config:', err.message);
-    }
-  }
-
-  async uninstall(framework) {
-    this._extensions.clear();
-    this._framework = null;
+    return this._skillHelper?.executeCommand(command, args) || null;
   }
 }
 
-module.exports = ExtensionExecutorPlugin
+module.exports = ExtensionExecutorPlugin;