foliko 1.1.4 → 1.1.6

package/src/core/agent.js

@@ -3,13 +3,70 @@
  * 负责对话和推理
  */
 
-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 { zodSchemaToTable } = require('@chnak/zod-to-markdown');
 const os = require('os');
 
+/**
+ * System Prompt 优先级常量
+ * 统一管理所有 prompt 部分的优先级，避免魔法数字
+ */
+const PROMPT_PRIORITY = {
+  ORIGINAL_PROMPT: 100,
+  SHARED_PROMPT: 200,
+  METADATA: 300,
+  TOOLS: 400,
+  SKILLS: 500,
+  SUB_AGENTS: 600,
+  CAPABILITIES: 700,
+  MCP_TOOLS: 750,
+  EXTENSION_TOOLS: 800,
+  TOOL_CORE_RULES: 1000,
+};
+
+/**
+ * Agent 配置常量
+ * 统一管理配置参数，避免魔法数字
+ */
+const AGENT_CONFIG = {
+  // AI 模型配置
+  MAX_OUTPUT_TOKENS: 8192,
+  TEMPERATURE: 0.3,
+  // 通知数量限制
+  MAX_NOTIFICATIONS: 5,
+  // 元数据提取配置
+  CAPABILITY_MAX_LENGTH: 50,
+  CAPABILITY_MAX_PARTS: 3,
+  // 错误重试配置
+  MAX_RETRIES: 3,
+};
+
+/**
+ * 日志工具函数
+ * @param {string} level - 日志级别
+ * @param {string} context - 上下文信息
+ * @param {string} message - 日志消息
+ * @param {any} data - 附加数据
+ */
+function log(level, context, message, data = null) {
+  const timestamp = new Date().toISOString();
+  const prefix = `[${timestamp}] [${level}] [${context}]`;
+  if (data !== null) {
+    console.log(`${prefix} ${message}`, data);
+  } else {
+    console.log(`${prefix} ${message}`);
+  }
+}
+
+const logger = {
+  info: (context, message, data) => log('INFO', context, message, data),
+  warn: (context, message, data) => log('WARN', context, message, data),
+  error: (context, message, data) => log('ERROR', context, message, data),
+  debug: (context, message, data) => log('DEBUG', context, message, data),
+};
+
 class Agent extends EventEmitter {
   /**
    * @param {Framework} framework - 框架实例
@@ -32,8 +89,9 @@ class Agent extends EventEmitter {
     this.baseURL = config.baseURL;
     this.provider = config.provider || 'deepseek';
     this.providerOptions = config.providerOptions || {};
-    this.providerOptions.maxOutputTokens = 8192;
-    this.providerOptions.temperature = 0.3; // 降低 temperature 减少生成错误 JSON 的概率
+    // 使用常量替代硬编码数字
+    this.providerOptions.maxOutputTokens = AGENT_CONFIG.MAX_OUTPUT_TOKENS;
+    this.providerOptions.temperature = AGENT_CONFIG.TEMPERATURE;
     // 原始 system prompt
     this._originalPrompt =
       config.systemPrompt ||
@@ -62,6 +120,8 @@ class Agent extends EventEmitter {
 
     // 初始化聊天处理器
     this._initChatHandler();
+
+    // logger.info('Agent', `Agent "${this.name}" 初始化完成`);
   }
 
   /**
@@ -69,19 +129,23 @@ class Agent extends EventEmitter {
    * @private
    */
   _registerDefaultPromptParts() {
-    // 1. 原始 system prompt (优先级 100)
-    this._systemPromptBuilder.register('original-prompt', 100, () => this._originalPrompt);
+    // 1. 原始 system prompt
+    this._systemPromptBuilder.register(
+      'original-prompt',
+      PROMPT_PRIORITY.ORIGINAL_PROMPT,
+      () => this._originalPrompt
+    );
 
-    // 2. 共享提示模板 (优先级 200)
-    this._systemPromptBuilder.register('shared-prompt', 200, () => {
+    // 2. 共享提示模板
+    this._systemPromptBuilder.register('shared-prompt', PROMPT_PRIORITY.SHARED_PROMPT, () => {
       if (this._sharedPrompt) {
         return this._replacePlaceholders(this._sharedPrompt);
       }
       return null;
     });
 
-    // 3. 元数据 (优先级 300)
-    this._systemPromptBuilder.register('metadata', 300, () => {
+    // 3. 元数据
+    this._systemPromptBuilder.register('metadata', PROMPT_PRIORITY.METADATA, () => {
       if (this._metadata.size === 0) {
         return null;
       }
@@ -97,26 +161,34 @@ class Agent extends EventEmitter {
     });
 
     // 4. 工具列表 (优先级 400)
-    //this._systemPromptBuilder.register('tools', 400, () => this._buildToolsDescription());
+    //this._systemPromptBuilder.register('tools', PROMPT_PRIORITY.TOOLS, () => this._buildToolsDescription());
 
-    // 5. 技能列表 (优先级 500)
-    this._systemPromptBuilder.register('skills', 500, () => this._buildSkillsDescription());
+    // 5. 技能列表
+    this._systemPromptBuilder.register('skills', PROMPT_PRIORITY.SKILLS, () =>
+      this._buildSkillsDescription()
+    );
 
-    // 6. 子Agent列表 (优先级 600)
-    this._systemPromptBuilder.register('subagents', 600, () => this._buildSubAgentsDescription());
+    // 6. 子Agent列表
+    this._systemPromptBuilder.register('subagents', PROMPT_PRIORITY.SUB_AGENTS, () =>
+      this._buildSubAgentsDescription()
+    );
 
-    // 7. 系统能力 (优先级 700)
-    this._systemPromptBuilder.register('capabilities', 700, () =>
+    // 7. 系统能力
+    this._systemPromptBuilder.register('capabilities', PROMPT_PRIORITY.CAPABILITIES, () =>
       this._buildCapabilitiesDescription()
     );
-    // 8. MCP 工具列表 (优先级 750)
-    this._systemPromptBuilder.register('mcp-tools', 750, () => this._buildMcpToolsDescription());
-    // 9. 扩展工具列表 (优先级 800)
-    this._systemPromptBuilder.register('extension-tools', 800, () =>
+    // 8. MCP 工具列表
+    this._systemPromptBuilder.register('mcp-tools', PROMPT_PRIORITY.MCP_TOOLS, () =>
+      this._buildMcpToolsDescription()
+    );
+    // 9. 扩展工具列表
+    this._systemPromptBuilder.register('extension-tools', PROMPT_PRIORITY.EXTENSION_TOOLS, () =>
       this._buildExtensionToolsDescription()
     );
-    // 10. 工具调用核心规则 (优先级 1000)
-    this._systemPromptBuilder.register('tool-core-rules', 1000, () => this._getToolCoreRules());
+    // 10. 工具调用核心规则
+    this._systemPromptBuilder.register('tool-core-rules', PROMPT_PRIORITY.TOOL_CORE_RULES, () =>
+      this._getToolCoreRules()
+    );
   }
 
   /**
@@ -182,12 +254,13 @@ class Agent extends EventEmitter {
       return '';
     }
 
-    let desc = '## 可用工具\n\n';
+    // 使用数组收集 + join 优化字符串拼接
+    const lines = ['## 可用工具', ''];
     for (const { name, tool } of directTools) {
-      desc += `- **${name}**: ${tool.description || '无描述'}\n`;
+      lines.push(`- **${name}**: ${tool.description || '无描述'}`);
     }
 
-    return desc.trim();
+    return lines.join('\n');
   }
 
   /**
@@ -204,15 +277,19 @@ class Agent extends EventEmitter {
       return '';
     }
 
-    let desc = '【可用技能】\n';
+    // 使用数组收集 + join 优化字符串拼接
+    const lines = ['【可用技能】'];
     for (const skill of skills) {
       const name = skill.metadata?.name || skill.name || 'unknown';
       const descText = skill.metadata?.description || '';
-      desc += `- ${name}: ${descText}\n`;
+      lines.push(`- ${name}: ${descText}`);
     }
-    desc +=
-      '\n重要：当需要开发插件、执行专业任务时，必须先使用 loadSkill 工具加载对应技能，获取专业指导。';
-    return desc.trim();
+    lines.push(
+      '',
+      '重要：当需要开发插件、执行专业任务时，必须先使用 loadSkill 工具加载对应技能，获取专业指导。'
+    );
+
+    return lines.join('\n');
   }
 
   /**
@@ -235,16 +312,21 @@ class Agent extends EventEmitter {
       return '';
     }
 
-    let desc = '【系统能力】\n';
-    keyPlugins.map((plugin, index) => {
+    // 使用数组收集 + join 优化字符串拼接
+    const lines = ['【系统能力】'];
+    keyPlugins.forEach((plugin, index) => {
       const name = plugin.instance?.name || plugin.name || 'unknown';
       const description = plugin.instance?.description || '无描述';
-      desc += `${index + 1}. ${name}: ${description}\n`;
+      lines.push(`${index + 1}. ${name}: ${description}`);
     });
 
-    return desc.trim();
+    return lines.join('\n');
   }
 
+  /**
+   * 构建扩展工具描述
+   * 使用 zodSchemaToMarkdown 解析参数，让 LLM 更易理解工具用法
+   */
   _buildExtensionToolsDescription() {
     const extensionExecutor = this.framework.pluginManager.get('extension-executor');
     if (!extensionExecutor) {
@@ -256,31 +338,113 @@ class Agent extends EventEmitter {
       return '';
     }
 
-    let desc = '【Extensions 扩展工具】\n\n';
-    desc += '你可以通过 `ext_call` 工具调用以下扩展插件的功能。\n\n';
+    const sections = [
+      '## 【Extensions 扩展工具】',
+      '',
+      '你可以通过 `ext_call` 工具调用以下扩展插件的功能。',
+      '',
+      '**重要调用规则：**',
+      '1. 调用前必须指定 `plugin`（插件名）和 `tool`（工具名）',
+      '2. 参数通过 `args` 对象传入，参数名和类型见各工具说明',
+      '3. 必填参数（Required）必须提供，可选参数（Optional）可省略',
+      '',
+      '---',
+      '',
+    ];
 
     for (const ext of extensions) {
-      desc += `### ${ext.name}\n\n`;
-      desc += `${ext.description || ''}\n\n`;
+      sections.push(`### ${ext.name}`, '');
+      sections.push(ext.description || '无描述', '');
+
       for (const tool of ext.tools) {
-        desc += `- **${tool.name}**: ${tool.description || '无描述'}\n`;
-        // 添加参数描述
+        sections.push(`#### ${tool.name}`, '');
+        sections.push(tool.description || '无描述', '');
+
+        // 使用 zodSchemaToMarkdown 解析参数
         if (tool.inputSchema) {
           try {
-            desc += `**参数:**\n\n`;
-            desc += zodSchemaToMarkdown(tool.inputSchema) + '\n\n';
+            const schemaMarkdown = zodSchemaToTable(tool.inputSchema);
+            sections.push('**参数:**', ' ');
+            sections.push(schemaMarkdown || '无', ' ');
           } catch (e) {
-            // 忽略转换错误
+            logger.warn('Agent', `转换工具 ${tool.name} 的参数描述失败`, e.message);
+            // 降级处理：手动解析常见 Zod 类型
+            sections.push('**参数:**', ' ');
+            sections.push(this._fallbackSchemaToText(tool.inputSchema), ' ');
           }
         }
+
+        sections.push('');
       }
-      desc += '\n';
     }
 
-    desc += '**调用格式:**\n';
-    desc += '```\next_call({ plugin: "插件名", tool: "工具名", args: {参数} })\n';
-    desc += '```\n';
-    return desc.trim();
+    sections.push(
+      '---',
+      '',
+      '## 调用示例',
+      '',
+      '**格式:**',
+      '```',
+      'ext_call({ plugin: "插件名", tool: "工具名", args: {参数} })',
+      '```',
+      '',
+      '**示例 - 获取余额:**',
+      '```',
+      'ext_call({ plugin: "gate-trading", tool: "gate_get_account_balance", args: {} })',
+      '```',
+      '',
+      '**示例 - HTTP 请求:**',
+      '```',
+      'ext_call({ plugin: "web", tool: "web_request", args: { method: "GET", path: "/api/data" } })',
+      '```'
+    );
+
+    return sections.join('\n').trim();
+  }
+
+  /**
+   * 降级处理：当 zodSchemaToMarkdown 解析失败时的备用方案
+   * @param {Object} schema - Zod schema 对象
+   * @returns {string} 参数描述文本
+   */
+  _fallbackSchemaToText(schema) {
+    if (!schema || !schema.shape) {
+      return '- （参数描述不可用）';
+    }
+
+    const lines = [];
+    for (const [name, field] of Object.entries(schema.shape)) {
+      const type = this._inferZodType(field);
+      const desc = field.description || field._def?.description || '';
+      const isOptional = type.includes('optional') ? '（可选）' : '（必填）';
+      lines.push(`- ${name} (${type}) ${isOptional}${desc ? `: ${desc}` : ''}`);
+    }
+
+    return lines.join('\n') || '- （参数描述不可用）';
+  }
+
+  /**
+   * 从 Zod schema 推断类型名称
+   * @param {Object} field - Zod schema 字段
+   * @returns {string} 类型名称
+   */
+  _inferZodType(field) {
+    const typeName = field._def?.typeName || field.constructor?.name || '';
+
+    const typeMap = {
+      ZodString: 'string',
+      ZodNumber: 'number',
+      ZodBoolean: 'boolean',
+      ZodArray: 'array',
+      ZodObject: 'object',
+      ZodOptional: 'optional',
+      ZodDefault: 'any',
+      ZodEnum: 'enum',
+      ZodUnion: 'union',
+      ZodRecord: 'record',
+    };
+
+    return typeMap[typeName] || typeName.replace('Zod', '').toLowerCase() || 'any';
   }
 
   _buildMcpToolsDescription() {
@@ -293,6 +457,7 @@ class Agent extends EventEmitter {
 
   /**
    * 构建子Agent描述
+   * 使用数组收集 + join 模式优化字符串拼接
    * 动态从配置文件读取每个子Agent的专业领域
    */
   _buildSubAgentsDescription() {
@@ -305,7 +470,8 @@ class Agent extends EventEmitter {
       return '';
     }
 
-    let desc = '【子 Agent 匹配表 - 优先使用】\n';
+    // 使用数组收集 + join 模式优化字符串拼接
+    const lines = ['【子 Agent 匹配表 - 优先使用】'];
 
     // 动态从配置文件读取每个子Agent的核心能力
     for (const plugin of allSubAgents) {
@@ -322,30 +488,32 @@ class Agent extends EventEmitter {
         if (skills && skills.length > 0) {
           info += ` (技能: ${skills.join(', ')})`;
         }
-        desc += `  - ${name}: ${info}\n`;
+        lines.push(`  - ${name}: ${info}`);
       } else {
         // 回退到旧逻辑
-        desc += `  - ${name}: ${role || goal || '子代理'}\n`;
+        lines.push(`  - ${name}: ${role || goal || '子代理'}`);
       }
     }
 
     // 通用规则
-    desc += '\n【子Agent匹配规则 - 必须遵守】\n';
-    desc += '  - 根据上述【子 Agent 匹配表】，将任务委托给最匹配的子Agent处理\n';
-    desc += '  - 使用 subagent_call 工具并指定 agentName 来委托任务\n';
-    desc += '  - 只有当没有匹配的子Agent时，才直接调用工具\n';
+    lines.push('');
+    lines.push('【子Agent匹配规则 - 必须遵守】');
+    lines.push('  - 根据上述【子 Agent 匹配表】，将任务委托给最匹配的子Agent处理');
+    lines.push('  - 使用 subagent_call 工具并指定 agentName 来委托任务');
+    lines.push('  - 只有当没有匹配的子Agent时，才直接调用工具');
 
-    return desc.trim();
+    return lines.join('\n').trim();
   }
 
   /**
    * 从配置文件动态读取子Agent的核心能力
    * 支持 .json 和 .md 格式
    * @private
+   * @returns {Promise<string|null>}
    */
-  _getSubAgentCapabilities(name) {
+  async _getSubAgentCapabilities(name) {
     try {
-      const fs = require('fs');
+      const fs = require('fs').promises;
       const path = require('path');
       const agentsDir = path.join(process.cwd(), '.agent', 'agents');
 
@@ -357,7 +525,12 @@ class Agent extends EventEmitter {
 
       let filePath = null;
       for (const p of possiblePaths) {
-        if (fs.existsSync(p)) {
+        if (
+          await fs
+            .access(p)
+            .then(() => true)
+            .catch(() => false)
+        ) {
           filePath = p;
           break;
         }
@@ -367,7 +540,7 @@ class Agent extends EventEmitter {
         return null;
       }
 
-      const content = fs.readFileSync(filePath, 'utf-8');
+      const content = await fs.readFile(filePath, 'utf-8');
 
       // .json 格式
       if (filePath.endsWith('.json')) {
@@ -382,6 +555,7 @@ class Agent extends EventEmitter {
 
       return null;
     } catch (e) {
+      logger.warn('Agent', `读取子Agent配置 ${name} 失败`, e.message);
       return null;
     }
   }
@@ -397,7 +571,7 @@ class Agent extends EventEmitter {
           .split('\n')
           .map((line) => line.replace(/^[·\-*]\s*/, '').trim())
           .filter((line) => line && !line.startsWith('你是一个'))
-          .slice(0, 4)
+          .slice(0, AGENT_CONFIG.CAPABILITY_MAX_PARTS)
           .join('、');
         return capabilities || config.description;
       }
@@ -442,13 +616,13 @@ class Agent extends EventEmitter {
       const parts = desc.split(/[,，、]/).map((s) => s.trim());
       // 取第一部分（通常是最核心的能力描述）
       const firstPart = parts[0];
-      // 如果第一部分太长（说明是句子），取前50个字符
-      if (firstPart.length > 50) {
-        return firstPart.substring(0, 50).trim() + '...';
+      // 如果第一部分太长（说明是句子），取前指定长度字符
+      if (firstPart.length > AGENT_CONFIG.CAPABILITY_MAX_LENGTH) {
+        return firstPart.substring(0, AGENT_CONFIG.CAPABILITY_MAX_LENGTH).trim() + '...';
       }
-      // 如果有多个部分，取前3个
+      // 如果有多个部分，取前指定数量
       if (parts.length > 1) {
-        return parts.slice(0, 3).join('、');
+        return parts.slice(0, AGENT_CONFIG.CAPABILITY_MAX_PARTS).join('、');
       }
       return firstPart;
     }
@@ -673,7 +847,8 @@ class Agent extends EventEmitter {
       if (scheduler && scheduler.instance && scheduler.instance.getPendingNotifications) {
         const results = scheduler.instance.getPendingNotifications();
         if (results.length > 0) {
-          const notifications = results.slice(-5).reverse(); // 最多5条，最新的在前
+          // 使用常量替代硬编码数字
+          const notifications = results.slice(-AGENT_CONFIG.MAX_NOTIFICATIONS).reverse();
           // 清除已发送的通知
           if (scheduler.instance.clearDeliveredNotifications) {
             scheduler.instance.clearDeliveredNotifications(notifications.length);
@@ -682,7 +857,7 @@ class Agent extends EventEmitter {
         }
       }
     } catch (err) {
-      // 忽略错误，避免影响主流程
+      logger.warn('Agent', '获取调度通知失败', err.message);
     }
     return [];
   }
@@ -696,11 +871,12 @@ class Agent extends EventEmitter {
       if (think && think.instance && think.instance.getPendingThoughts) {
         const thoughts = think.instance.getPendingThoughts();
         if (thoughts.length > 0) {
-          return thoughts.slice(-5).reverse(); // 最多5条，最新的在前
+          // 使用常量替代硬编码数字
+          return thoughts.slice(-AGENT_CONFIG.MAX_NOTIFICATIONS).reverse();
         }
       }
     } catch (err) {
-      // 忽略错误，避免影响主流程
+      logger.warn('Agent', '获取思考通知失败', err.message);
     }
     return [];
   }
@@ -760,6 +936,7 @@ class Agent extends EventEmitter {
       return result;
     } catch (err) {
       this._status = 'error';
+      logger.error('Agent', `chat 方法执行失败: ${err.message}`, { stack: err.stack });
       this.emit('status', { status: 'error', error: err.message });
       throw err;
     }
@@ -815,6 +992,7 @@ class Agent extends EventEmitter {
       this.emit('status', { status: 'idle' });
     } catch (err) {
       this._status = 'error';
+      logger.error('Agent', `chatStream 方法执行失败: ${err.message}`, { stack: err.stack });
       this.emit('status', { status: 'error', error: err.message });
 
       throw err;
@@ -879,6 +1057,14 @@ class Agent extends EventEmitter {
     return this._status;
   }
 
+  /**
+   * 获取Agent ID
+   * @returns {string} Agent名称
+   */
+  getCurrentAgentId() {
+    return this.name;
+  }
+
   /**
    * 重置状态（从卡住状态恢复）
    */
@@ -898,6 +1084,7 @@ class Agent extends EventEmitter {
     this._tools.clear();
     this.removeAllListeners();
     this.emit('destroyed');
+    logger.info('Agent', `Agent "${this.name}" 已销毁`);
   }
 }