foliko 1.0.73 → 1.0.75

package/src/core/framework.js

@@ -3,22 +3,23 @@
  * 管理所有子系统，提供统一入口
  */
 
-const path = require('path')
-const { AsyncLocalStorage } = require('async_hooks')
-const { EventEmitter } = require('../utils/event-emitter')
-const { PluginManager } = require('./plugin-manager')
-const { ToolRegistry } = require('./tool-registry')
-const { Agent } = require('./agent')
+const path = require('path');
+const { AsyncLocalStorage } = require('async_hooks');
+const { EventEmitter } = require('../utils/event-emitter');
+const { PluginManager } = require('./plugin-manager');
+const { ToolRegistry } = require('./tool-registry');
+const { Agent } = require('./agent');
+const { SubAgentConfigManager } = require('./sub-agent-config');
 
 // 添加框架目录的 node_modules 到全局搜索路径
 // 让项目插件能 require 框架内置的包（如 zod）
-const frameworkNodeModules = path.join(__dirname, '..', '..', 'node_modules')
+const frameworkNodeModules = path.join(__dirname, '..', '..', 'node_modules');
 if (!module.paths.includes(frameworkNodeModules)) {
-  module.paths.unshift(frameworkNodeModules)
+  module.paths.unshift(frameworkNodeModules);
 }
 
 // AsyncLocalStorage 实现真正的上下文隔离（支持并行处理）
-const asyncLocalStorage = new AsyncLocalStorage()
+const asyncLocalStorage = new AsyncLocalStorage();
 
 class Framework extends EventEmitter {
   /**
@@ -26,30 +27,62 @@ class Framework extends EventEmitter {
    * @param {boolean} [config.debug=false] - 调试模式
    */
   constructor(config = {}) {
-    super()
+    super();
 
-    this._debug = config.debug || false
-    this._ready = false
-    this._readyPromise = null
-    this._resolveReady = null
+    this._debug = config.debug || false;
+    this._ready = false;
+    this._readyPromise = null;
+    this._resolveReady = null;
 
     // 初始化子系统
-    this.toolRegistry = new ToolRegistry()
-    this.pluginManager = new PluginManager(this)
+    this.toolRegistry = new ToolRegistry();
+    this.pluginManager = new PluginManager(this);
 
     // Agent 管理
-    this._agents = []           // 所有创建的 agent
-    this._mainAgent = null      // 主 agent
+    this._agents = []; // 所有创建的 agent
+    this._mainAgent = null; // 主 agent
+
+    // 子代理配置管理器
+    this._subAgentConfigManager = null;
 
     // 执行上下文（工具调用时可用）
-    this._executionContext = null
+    this._executionContext = null;
 
     // 事件转发
     this.toolRegistry.on('tool:registered', (tool) => {
-      this.emit('tool:registered', tool)
-    })
+      this.emit('tool:registered', tool);
+    });
 
-    this._registerBuiltinTools()
+    this._registerBuiltinTools();
+  }
+
+  /**
+   * 从 AI 插件合并配置到目标配置对象
+   * @param {Object} target - 目标配置对象
+   * @private
+   */
+  _mergeAIConfig(target) {
+    if (target.apiKey) return target; // 已有 apiKey 不需要合并
+
+    const aiPlugin = this.pluginManager.get('ai');
+    if (!aiPlugin) return target;
+
+    const defaults = {
+      apiKey: aiPlugin.config.apiKey,
+      provider: aiPlugin.config.provider,
+      model: aiPlugin.config.model,
+      baseURL: aiPlugin.config.baseURL,
+      providerOptions: aiPlugin.config.providerOptions || {},
+    };
+
+    return {
+      ...target,
+      apiKey: target.apiKey || defaults.apiKey,
+      provider: target.provider || defaults.provider,
+      model: target.model || defaults.model,
+      baseURL: target.baseURL || defaults.baseURL,
+      providerOptions: target.providerOptions || defaults.providerOptions,
+    };
   }
 
   /**
@@ -57,17 +90,17 @@ class Framework extends EventEmitter {
    * @param {Plugin|Object} plugin - 插件
    */
   registerPlugin(plugin) {
-    this.pluginManager.register(plugin)
-    return this
+    this.pluginManager.register(plugin);
+    return this;
   }
 
   /**
-   * 加载并启动插件
+   * 加载并启动插件）
    * @param {Plugin|Object} plugin - 插件
    */
   async loadPlugin(plugin) {
-    await this.pluginManager.load(plugin)
-    return this
+    await this.pluginManager.load(plugin);
+    return this;
   }
 
   /**
@@ -75,8 +108,8 @@ class Framework extends EventEmitter {
    * @param {string} name - 插件名称
    */
   async unloadPlugin(name) {
-    await this.pluginManager.unload(name)
-    return this
+    await this.pluginManager.unload(name);
+    return this;
   }
 
   /**
@@ -84,16 +117,16 @@ class Framework extends EventEmitter {
    * @param {string} name - 插件名称
    */
   async reloadPlugin(name) {
-    await this.pluginManager.reload(name)
-    return this
+    await this.pluginManager.reload(name);
+    return this;
   }
 
   /**
-   * 重载所有插件
+   * 重载所有插件）
    */
   async reloadAllPlugins() {
-    await this.pluginManager.reloadAll()
-    return this
+    await this.pluginManager.reloadAll();
+    return this;
   }
 
   /**
@@ -101,8 +134,8 @@ class Framework extends EventEmitter {
    * @param {string} name - 插件名称
    */
   async enablePlugin(name) {
-    await this.pluginManager.enable(name)
-    return this
+    await this.pluginManager.enable(name);
+    return this;
   }
 
   /**
@@ -110,8 +143,8 @@ class Framework extends EventEmitter {
    * @param {string} name - 插件名称
    */
   async disablePlugin(name) {
-    await this.pluginManager.disable(name)
-    return this
+    await this.pluginManager.disable(name);
+    return this;
   }
 
   /**
@@ -120,7 +153,7 @@ class Framework extends EventEmitter {
    * @param {Object} config - 新配置
    */
   updatePluginConfig(name, config) {
-    return this.pluginManager.updatePluginConfig(name, config)
+    return this.pluginManager.updatePluginConfig(name, config);
   }
 
   /**
@@ -128,16 +161,48 @@ class Framework extends EventEmitter {
    * @param {Object} tool - 工具定义
    */
   registerTool(tool) {
-    this.toolRegistry.register(tool)
-    return this
+    this.toolRegistry.register(tool);
+    return this;
   }
 
   /**
-   * 获取所有工具
+   * 获取所有工具）
    * @returns {Array<Object>}
    */
   getTools() {
-    return this.toolRegistry.getAll()
+    return this.toolRegistry.getAll();
+  }
+
+  // ============================================================================
+  // 事件描述注册（供 Ambient Agent 使用）
+  // ============================================================================
+
+  /**
+   * 注册事件描述
+   * @param {string} eventType - 事件类型，如 'tool:result'
+   * @param {string} description - 事件描述
+   * @param {Object} schema - 事件参数 Schema（可选）
+   */
+  registerEventDescription(eventType, description, schema = null) {
+    this.pluginManager.registerEventDescription(eventType, description, schema);
+    return this;
+  }
+
+  /**
+   * 获取所有已注册的事件描述
+   * @returns {Map<string, Object>} 事件描述 Map
+   */
+  getEventDescriptions() {
+    return this.pluginManager.getEventDescriptions();
+  }
+
+  /**
+   * 获取单个事件描述
+   * @param {string} eventType - 事件类型
+   * @returns {Object|null} 事件描述
+   */
+  getEventDescription(eventType) {
+    return this.pluginManager.getEventDescription(eventType);
   }
 
   /**
@@ -146,7 +211,7 @@ class Framework extends EventEmitter {
    * @param {Object} args - 参数
    */
   async executeTool(name, args) {
-    return this.toolRegistry.execute(name, args, this)
+    return this.toolRegistry.execute(name, args, this);
   }
 
   /**
@@ -156,7 +221,7 @@ class Framework extends EventEmitter {
    * @returns {Promise}
    */
   runWithContext(context, fn) {
-    return asyncLocalStorage.run(context, fn)
+    return asyncLocalStorage.run(context, fn);
   }
 
   /**
@@ -164,7 +229,7 @@ class Framework extends EventEmitter {
    * @returns {Object|null}
    */
   getExecutionContext() {
-    return asyncLocalStorage.getStore() || null
+    return asyncLocalStorage.getStore() || null;
   }
 
   /**
@@ -182,61 +247,45 @@ class Framework extends EventEmitter {
    * @param {Object} config - Agent 配置
    */
   createAgent(config) {
-    // 如果配置了 AI 相关参数但没有 apiKey，尝试从 AI 插件获取
-    if (!config.apiKey) {
-      const aiPlugin = this.pluginManager.get('ai')
-      if (aiPlugin) {
-        config.apiKey = aiPlugin.config.apiKey
-        config.provider = config.provider || aiPlugin.config.provider
-        config.model = config.model || aiPlugin.config.model
-        config.baseURL = config.baseURL || aiPlugin.config.baseURL
-      }
-    }
+    // 合并 AI 插件配置
+    config = this._mergeAIConfig(config);
 
-    const agent = new Agent(this, config)
+    const agent = new Agent(this, config);
 
     // 跟踪 agent
-    this._agents.push(agent)
+    this._agents.push(agent);
     if (!this._mainAgent) {
-      this._mainAgent = agent
+      this._mainAgent = agent;
     }
 
-    this.emit('agent:created', agent)
-    return agent
+    this.emit('agent:created', agent);
+    return agent;
   }
 
   /**
-   * 为指定 session 创建独立的 Agent 实例
+   * 为指定 session 创建独立 Agent 实例
    * @param {string} sessionId - session ID
    * @param {Object} config - Agent 配置
    */
   createSessionAgent(sessionId, config = {}) {
     const agentConfig = {
       name: `session_${sessionId}`,
-      ...config
-    }
+      ...config,
+    };
 
-    // 如果没有提供 AI 相关参数，从 AI 插件获取
-    if (!agentConfig.apiKey) {
-      const aiPlugin = this.pluginManager.get('ai')
-      if (aiPlugin) {
-        agentConfig.apiKey = aiPlugin.config.apiKey
-        agentConfig.provider = agentConfig.provider || aiPlugin.config.provider
-        agentConfig.model = agentConfig.model || aiPlugin.config.model
-        agentConfig.baseURL = agentConfig.baseURL || aiPlugin.config.baseURL,
-        agentConfig.providerOptions||aiPlugin.config.providerOptions||{}
-      }
-    }
-    const agent = new Agent(this, agentConfig)
-    this._agents.push(agent)
+    // 合并 AI 插件配置
+    const merged = this._mergeAIConfig(agentConfig);
+
+    const agent = new Agent(this, merged);
+    this._agents.push(agent);
 
-    // 如果提供了 systemPrompt，需要更新 AgentChatHandler
-    if (agentConfig.systemPrompt) {
-      agent.setSystemPrompt(agentConfig.systemPrompt)
+    // 如果提供了 systemPrompt，需要替换 AgentChatHandler
+    if (merged.systemPrompt) {
+      agent.setSystemPrompt(merged.systemPrompt);
     }
 
-    this.emit('agent:created', agent)
-    return agent
+    this.emit('agent:created', agent);
+    return agent;
   }
 
   /**
@@ -244,9 +293,9 @@ class Framework extends EventEmitter {
    * @param {Object} config - 子Agent配置
    * @param {string} config.name - 子Agent名称
    * @param {string} config.role - 角色描述（用于智能选择）
-   * @param {string} [config.description] - 供主Agent理解的描述
+   * @param {string} [config.description] - 供主Agent理解的描述）
    * @param {Object} [config.tools] - 自定义工具 { name: toolDef }
-   * @param {string[]} [config.parentTools] - 从父Agent继承的工具名称列表
+   * @param {string[]} [config.parentTools] - 从父Agent继承的工具名称列表）
    * @param {Object} [config.llmConfig] - 独立LLM配置
    * @returns {Agent} 创建的子Agent
    */
@@ -256,32 +305,23 @@ class Framework extends EventEmitter {
       role,
       description = '',
       tools = {},
-      parentTools,  // 如果不传，默认继承主agent所有工具
-      llmConfig = null
-    } = config
+      parentTools, // 如果不传，默认继承主agent所有工具
+      llmConfig = null,
+    } = config;
 
     // 构建子Agent配置
     const agentConfig = {
       name: `subagent_${name}`,
       role: role,
-      systemPrompt: role,  // 使用 role 作为 systemPrompt
-      ...(llmConfig || {})  // 如果提供了独立LLM配置，合并
-    }
+      systemPrompt: role, // 使用 role 作为 systemPrompt
+      ...(llmConfig || {}), // 如果提供了独立LLM配置，合并
+    };
 
-    // 如果没有提供 AI 相关参数，从 AI 插件获取
-    if (!agentConfig.apiKey) {
-      const aiPlugin = this.pluginManager.get('ai')
-      if (aiPlugin) {
-        agentConfig.apiKey = aiPlugin.config.apiKey
-        agentConfig.provider = agentConfig.provider || aiPlugin.config.provider
-        agentConfig.model = agentConfig.model || aiPlugin.config.model
-        agentConfig.baseURL = agentConfig.baseURL || aiPlugin.config.baseURL
-        agentConfig.providerOptions = agentConfig.providerOptions || aiPlugin.config.providerOptions || {}
-      }
-    }
+    // 合并 AI 插件配置
+    const merged = this._mergeAIConfig(agentConfig);
 
     // 创建 Agent
-    const agent = new Agent(this, agentConfig)
+    const agent = new Agent(this, merged);
 
     // 注册自定义工具
     for (const [toolName, toolDef] of Object.entries(tools)) {
@@ -290,33 +330,33 @@ class Framework extends EventEmitter {
           name: toolName,
           description: toolDef.description || '',
           inputSchema: toolDef.inputSchema,
-          execute: toolDef.execute
-        })
+          execute: toolDef.execute,
+        });
       }
     }
 
     // 从父Agent继承工具
     if (this._mainAgent) {
-      const parentToolsDefs = this._mainAgent.getTools()
+      const parentToolsDefs = this._mainAgent.getTools();
       if (parentTools === undefined) {
         // 如果没有指定 parentTools，默认继承所有工具
         for (const toolDef of parentToolsDefs) {
-          agent.registerTool(toolDef)
+          agent.registerTool(toolDef);
         }
       } else if (Array.isArray(parentTools) && parentTools.length > 0) {
         // 指定了要继承的工具列表
         for (const toolName of parentTools) {
-          const toolDef = parentToolsDefs.find(t => t.name === toolName)
+          const toolDef = parentToolsDefs.find((t) => t.name === toolName);
           if (toolDef) {
-            agent.registerTool(toolDef)
+            agent.registerTool(toolDef);
           }
         }
       }
     }
 
-    this._agents.push(agent)
-    this.emit('agent:created', agent)
-    return agent
+    this._agents.push(agent);
+    this.emit('agent:created', agent);
+    return agent;
   }
 
   /**
@@ -324,40 +364,44 @@ class Framework extends EventEmitter {
    * @returns {Object|undefined}
    */
   getAIPlugin() {
-    return this.pluginManager.get('ai')
+    return this.pluginManager.get('ai');
   }
 
   /**
    * Bootstrap - 使用默认配置启动框架
-   * 自动加载 .agent/ 目录下的配置和所有默认插件
+   * 自动加载 .agent/ 目录下的配置和所有默认插件）
    * @param {Object} config - 配置
    * @param {string} [config.agentDir='.agent'] - Agent 配置目录
    * @param {Object} [config.aiConfig] - AI 配置（可选，覆盖文件配置）
    * @returns {Promise<Framework>}
    */
   async bootstrap(config = {}) {
-    const { bootstrapDefaults, DefaultPlugins, loadAgentConfig } = require('../../plugins/default-plugins')
+    const {
+      bootstrapDefaults,
+      DefaultPlugins,
+      loadAgentConfig,
+    } = require('../../plugins/default-plugins');
 
     // 先加载默认插件配置
     const defaultsPlugin = new DefaultPlugins({
-      agentDir: config.agentDir || '.agent'
-    })
+      agentDir: config.agentDir || '.agent',
+    });
 
-    await this.loadPlugin(defaultsPlugin)
+    await this.loadPlugin(defaultsPlugin);
 
     // 获取配置
-    const agentConfig = defaultsPlugin.getConfig()
+    const agentConfig = defaultsPlugin.getConfig();
 
     // 如果提供了 AI 配置，覆盖文件配置
     if (config.aiConfig) {
-      agentConfig.ai = { ...agentConfig.ai, ...config.aiConfig }
+      agentConfig.ai = { ...agentConfig.ai, ...config.aiConfig };
     }
 
     // 加载所有默认插件（传入已加载的配置避免重复加载）
-    await bootstrapDefaults(this, { _config: agentConfig, _skipConfigLoad: true })
+    await bootstrapDefaults(this, { _config: agentConfig, _skipConfigLoad: true });
 
-    this._setReady()
-    return this
+    this._setReady();
+    return this;
   }
 
   /**
@@ -365,17 +409,17 @@ class Framework extends EventEmitter {
    */
   async ready() {
     if (this._ready) {
-      return this
+      return this;
     }
 
     if (!this._readyPromise) {
       this._readyPromise = new Promise((resolve) => {
-        this._resolveReady = resolve
-      })
+        this._resolveReady = resolve;
+      });
     }
 
-    await this._readyPromise
-    return this
+    await this._readyPromise;
+    return this;
   }
 
   /**
@@ -383,21 +427,11 @@ class Framework extends EventEmitter {
    * @private
    */
   _setReady() {
-    this._ready = true
+    this._ready = true;
     if (this._resolveReady) {
-      this._resolveReady(this)
-    }
-    this.emit('framework:ready', this)
-  }
-
-  /**
-   * 调试日志
-   * @private
-   */
-  _log(...args) {
-    if (this._debug) {
-      console.log('[Framework]', ...args)
+      this._resolveReady(this);
     }
+    this.emit('framework:ready', this);
   }
 
   /**
@@ -405,27 +439,27 @@ class Framework extends EventEmitter {
    * @private
    */
   _registerBuiltinTools() {
-    // 内置工具会在 Agent 创建时添加
+    // 内置工具会在 Agent 创建时添加）
   }
 
   /**
-   * 销毁框架
+   * 销毁框架）
    */
   async destroy() {
-    // 卸载所有插件
-    const plugins = this.pluginManager.getAll()
+    // 卸载所有插件）
+    const plugins = this.pluginManager.getAll();
     for (const { name } of plugins) {
-      await this.pluginManager.unload(name)
+      await this.pluginManager.unload(name);
     }
 
     // 清空工具
-    this.toolRegistry.clear()
+    this.toolRegistry.clear();
 
     // 清空事件
-    this.removeAllListeners()
+    this.removeAllListeners();
 
-    this.emit('framework:destroyed')
+    this.emit('framework:destroyed');
   }
 }
 
-module.exports = { Framework }
+module.exports = { Framework };

package/src/core/index.js

@@ -2,12 +2,12 @@
  * 核心模块统一导出
  */
 
-const { Framework } = require('./framework')
-const { Agent } = require('./agent')
-const { Plugin } = require('./plugin-base')
-const { PluginManager } = require('./plugin-manager')
-const { ToolRegistry } = require('./tool-registry')
-const { EventEmitter } = require('../utils/event-emitter')
+const { Framework } = require('./framework');
+const { Agent } = require('./agent');
+const { Plugin } = require('./plugin-base');
+const { PluginManager } = require('./plugin-manager');
+const { ToolRegistry } = require('./tool-registry');
+const { EventEmitter } = require('../utils/event-emitter');
 
 module.exports = {
   Framework,
@@ -15,5 +15,5 @@ module.exports = {
   Plugin,
   PluginManager,
   ToolRegistry,
-  EventEmitter
-}
+  EventEmitter,
+};