foliko 1.0.76 → 1.0.78

package/src/core/agent.js

@@ -3,9 +3,11 @@
  * 负责对话和推理
  */
 
+const { pl } = require('zod/v4/locales');
 const { EventEmitter } = require('../utils/event-emitter');
 const { AgentChatHandler } = require('./agent-chat');
 const { SystemPromptBuilder } = require('./system-prompt-builder');
+const { zodSchemaToMarkdown } = require('@chnak/zod-to-markdown');
 const os = require('os');
 
 class Agent extends EventEmitter {
@@ -108,9 +110,16 @@ class Agent extends EventEmitter {
     this._systemPromptBuilder.register('subagents', 600, () => this._buildSubAgentsDescription());
 
     // 7. 系统能力 (优先级 700)
-    this._systemPromptBuilder.register('capabilities', 700, () => this._buildCapabilitiesDescription());
-
-    // 8. 工具调用核心规则 (优先级 1000)
+    this._systemPromptBuilder.register('capabilities', 700, () =>
+      this._buildCapabilitiesDescription()
+    );
+    // 8. MCP 工具列表 (优先级 750)
+    this._systemPromptBuilder.register('mcp-tools', 750, () => this._buildMcpToolsDescription());
+    // 9. 扩展工具列表 (优先级 800)
+    this._systemPromptBuilder.register('extension-tools', 800, () =>
+      this._buildExtensionToolsDescription()
+    );
+    // 10. 工具调用核心规则 (优先级 1000)
     this._systemPromptBuilder.register('tool-core-rules', 1000, () => this._getToolCoreRules());
   }
 
@@ -153,26 +162,35 @@ class Agent extends EventEmitter {
   }
 
   /**
-   * 构建工具描述
+   * 构建工具描述（直接调用的工具）
    */
   _buildToolsDescription() {
     if (this._tools.size === 0) {
       return '';
     }
 
-    // 需要排除的子Agent相关工具（它们通过专门的子Agent部分提供）
-    // const excludedTools = new Set(['subagent_call', 'subagent_list', 'subagent_reload']);
+    const directTools = [];
 
-    let desc = '【可用工具】\n';
     for (const [name, tool] of this._tools) {
-      // 跳过没有描述的工具（对LLM无帮助）
       if (!tool.description) continue;
-      // // 跳过子Agent相关工具（通过专门的子Agent部分提供）
-      // if (excludedTools.has(name)) continue;
-      // // 跳过子Agent委托工具（通过专门的子Agent部分提供）
-      // if (this._subAgents.has(name)) continue;
-      desc += `- ${name}: ${tool.description}\n`;
+
+      // MCP 和 ext 工具不在这里显示，它们通过专门的描述部分提供
+      if (name.startsWith('mcp_') || name.startsWith('ext_') || name.startsWith('workflow_')) {
+        continue;
+      }
+
+      directTools.push({ name, tool });
+    }
+
+    if (directTools.length === 0) {
+      return '';
     }
+
+    let desc = '## 可用工具\n\n';
+    for (const { name, tool } of directTools) {
+      desc += `- **${name}**: ${tool.description || '无描述'}\n`;
+    }
+
     return desc.trim();
   }
 
@@ -222,15 +240,61 @@ class Agent extends EventEmitter {
     }
 
     let desc = '【系统能力】\n';
-    for (const plugin of keyPlugins) {
+    keyPlugins.map((plugin, index) => {
       const name = plugin.instance?.name || plugin.name || 'unknown';
       const description = plugin.instance?.description || '无描述';
-      desc += `- ${name}: ${description}\n`;
+      desc += `${index + 1}. ${name}: ${description}\n`;
+    });
+
+    return desc.trim();
+  }
+
+  _buildExtensionToolsDescription() {
+    const extensionExecutor = this.framework.pluginManager.get('extension-executor');
+    if (!extensionExecutor) {
+      return '';
+    }
+
+    const extensions = extensionExecutor.getExtensions();
+    if (!extensions || extensions.length === 0) {
+      return '';
+    }
+
+    let desc = '【Extensions 扩展工具】\n\n';
+    desc += '你可以通过 `ext_call` 工具调用以下扩展插件的功能。\n\n';
+
+    for (const ext of extensions) {
+      desc += `### ${ext.name}\n\n`;
+      desc += `${ext.description || ''}\n\n`;
+      for (const tool of ext.tools) {
+        desc += `- **${tool.name}**: ${tool.description || '无描述'}\n`;
+        // 添加参数描述
+        if (tool.inputSchema) {
+          try {
+            desc += `**参数:**\n\n`;
+            desc += zodSchemaToMarkdown(tool.inputSchema) + '\n\n';
+          } catch (e) {
+            // 忽略转换错误
+          }
+        }
+      }
+      desc += '\n';
     }
 
+    desc += '**调用格式:**\n';
+    desc += '```\next_call({ plugin: "插件名", tool: "工具名", args: {参数} })\n';
+    desc += '```\n';
     return desc.trim();
   }
 
+  _buildMcpToolsDescription() {
+    const mcpExecutor = this.framework.pluginManager.get('mcp-executor');
+    if (!mcpExecutor) {
+      return '';
+    }
+    return mcpExecutor._buildMCPServersDescription();
+  }
+
   /**
    * 构建子Agent描述
    * 动态从配置文件读取每个子Agent的专业领域
@@ -366,8 +430,10 @@ class Agent extends EventEmitter {
         const key = line.substring(0, colonIndex).trim();
         let value = line.substring(colonIndex + 1).trim();
         // 移除可能的引号
-        if ((value.startsWith('"') && value.endsWith('"')) ||
-            (value.startsWith("'") && value.endsWith("'"))) {
+        if (
+          (value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))
+        ) {
           value = value.slice(1, -1);
         }
         config[key] = value;
@@ -377,7 +443,7 @@ class Agent extends EventEmitter {
     if (config.description) {
       const desc = config.description;
       // 按逗号/顿号分隔
-      const parts = desc.split(/[,，、]/).map(s => s.trim());
+      const parts = desc.split(/[,，、]/).map((s) => s.trim());
       // 取第一部分（通常是最核心的能力描述）
       const firstPart = parts[0];
       // 如果第一部分太长（说明是句子），取前50个字符

package/src/core/plugin-base.js

@@ -52,6 +52,13 @@ class Plugin {
   _framework = null;
   _subAgents = [];
 
+  /**
+   * 插件注册的工具集（供 ExtensionExecutor 自动加载）
+   * 格式: { toolName: { name, description, inputSchema, execute } }
+   * @type {Object}
+   */
+  tools = {};
+
   /**
    * 安装插件 - 注册工具/事件等
    * @param {Framework} framework - 框架实例
@@ -61,6 +68,42 @@ class Plugin {
     return this;
   }
 
+  /**
+   * 注册工具到扩展执行器（供 ExtensionExecutor 统一管理）
+   * 支持三种调用方式：
+   *   this.registerTool('name', { description, inputSchema, execute })
+   *   this.registerTool({ name, description, inputSchema, execute })
+   *   this.registerTool({ name, description, inputSchema, execute, pluginName: 'xxx' })
+   * @param {string|Object} name - 工具名称或工具定义对象
+   * @param {Object} [def] - 工具定义 { description, inputSchema, execute }
+   */
+  registerTool(name, def) {
+    if (!this._framework) return;
+    // 支持 this.registerTool({ name, description, ... }) 形式
+    if (typeof name === 'object' && name !== null) {
+      def = name;
+      name = def.name;
+    }
+    if (!name || !def) return;
+
+    // 支持自定义插件名
+    const pluginName = def.pluginName || this.name;
+    delete def.pluginName;
+
+    const extExec = this._framework.pluginManager.get('extension-executor');
+    if (extExec) {
+      extExec.registerTool(
+        pluginName,
+        {
+          name: pluginName,
+          description: def.description || this.description,
+          version: this.version,
+        },
+        { name, ...def }
+      );
+    }
+  }
+
   /**
    * 启动插件 - 初始化完成后的启动
    * @param {Framework} framework - 框架实例

package/src/executors/mcp-executor.js

@@ -10,6 +10,10 @@ const path = require('path');
 const { z } = require('zod');
 const { createMCPClient } = require('@ai-sdk/mcp');
 const { StdioClientTransport } = require('@modelcontextprotocol/sdk/client/stdio.js');
+const { zodSchemaToMarkdown } = require('@chnak/zod-to-markdown');
+const { logger } = require('../utils/logger');
+
+const log = logger.child('MCPExecutor');
 
 /**
  * MCP 客户端包装器
@@ -495,39 +499,139 @@ class MCPExecutorPlugin extends Plugin {
       return '';
     }
 
-    let desc = '【MCP Servers - 可用工具服务】\n';
-    desc += '你可以通过 mcp_call 工具调用以下 MCP 服务器的工具。\n\n';
+    let desc = '[MCP Servers]\n\n';
+    desc += '你可以通过 `mcp_call` 工具调用以下 MCP 服务器的工具。\n\n';
 
     for (const [serverName, info] of this._clients) {
-      desc += `【${serverName}】\n`;
+      desc += `### ${serverName}\n\n`;
       for (const tool of info.tools) {
-        const schema = this._extractSchema(tool.inputSchema);
-        const props = schema.properties || {};
-        const required = schema.required || [];
+        desc += `#### ${tool.name}\n`;
+        desc += `${tool.description || '无描述'}\n\n`;
 
-        // 简化参数列表
-        let paramStr = '';
-        if (Object.keys(props).length > 0) {
-          const params = Object.entries(props).map(([key, prop]) => {
-            const isRequired = required.includes(key);
-            return `${key}${isRequired ? '(必填)' : ''}`;
-          });
-          paramStr = ` 参数: ${params.join(', ')}`;
+        // 使用 zodSchemaToMarkdown 生成参数文档
+        const schema = tool.inputSchema;
+        if (schema) {
+          try {
+            if (typeof schema.toJSON === 'function') {
+              // Zod schema 直接转换
+              desc += `**参数:**\n\n`;
+              desc += zodSchemaToMarkdown(schema) + '\n\n';
+            } else if (schema.jsonSchema) {
+              // JSON Schema 格式，尝试转换为 Zod schema
+              const zodSchema = this._jsonSchemaToZod(schema.jsonSchema || schema);
+              if (zodSchema) {
+                desc += `**参数:**\n\n`;
+                desc += zodSchemaToMarkdown(zodSchema) + '\n\n';
+              }
+            } else if (schema.properties) {
+              // 已经是对象格式
+              const zodSchema = this._jsonSchemaToZod(schema);
+              if (zodSchema) {
+                desc += `**参数:**\n\n`;
+                desc += zodSchemaToMarkdown(zodSchema) + '\n\n';
+              }
+            }
+          } catch (e) {
+            // 如果转换失败，使用简化格式
+            desc += this._fallbackParamsDesc(schema);
+          }
         }
-
-        // 截取描述的第一句
-        const shortDesc = tool.description?.split('.')[0] || '无描述';
-        desc += `- ${tool.name}: ${shortDesc}${paramStr}\n`;
       }
-      desc += '\n';
+      desc += '---\n\n';
     }
 
-    desc +=
-      '调用格式：mcp_call({ server: "服务器", tool: "工具", args_json: \'{"参数": "值"}\' })\n';
-    desc += '复杂参数时先用 mcp_tool_schema 查询完整参数结构\n';
+    desc += '**调用格式:**\n';
+    desc += '```\nmcp_call({ server: "服务器", tool: "工具", args_json: \'{"参数": "值"}\' })\n';
+    desc += '```\n';
     return desc.trim();
   }
 
+  /**
+   * 将 JSON Schema 转换为 Zod schema
+   */
+  _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));
+      }
+
+      return z.object(shape);
+    } catch (e) {
+      return null;
+    }
+  }
+
+  /**
+   * 将 JSON Schema 属性转换为 Zod 类型
+   */
+  _jsonSchemaPropToZod(prop, isRequired) {
+    if (prop.$ref) {
+      return isRequired ? z.any() : z.any().optional();
+    }
+
+    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();
+    }
+  }
+
+  /**
+   * 回退的参数描述（当 zodSchemaToMarkdown 失败时）
+   */
+  _fallbackParamsDesc(schema) {
+    const props = schema.properties || {};
+    const required = schema.required || [];
+
+    if (Object.keys(props).length === 0) {
+      return '';
+    }
+
+    let desc = '**参数:**\n\n';
+    for (const [key, prop] of Object.entries(props)) {
+      const isRequired = required.includes(key);
+      const type = prop.type || 'any';
+      const desc_text = prop.description || '';
+      desc += `- \`${key}\`${isRequired ? ' (必填)' : ''}: ${type} ${desc_text}\n`;
+    }
+    return desc + '\n';
+  }
+
   _getParentAgent() {
     // 优先返回已缓存的主 agent
     if (this._mainAgent) {