foliko 1.0.74 → 1.0.75

package/src/index.js

@@ -3,23 +3,11 @@
  * 简约的插件化 Agent 框架
  */
 
-const {
-  Framework,
-  Agent,
-  Plugin,
-  PluginManager,
-  ToolRegistry,
-  EventEmitter
-} = require('./core')
+const { Framework, Agent, Plugin, PluginManager, ToolRegistry, EventEmitter } = require('./core');
 
-const {
-  SkillManagerPlugin,
-  WorkflowPlugin
-} = require('./capabilities')
+const { SkillManagerPlugin, WorkflowPlugin } = require('./capabilities');
 
-const {
-  MCPExecutorPlugin
-} = require('./executors/mcp-executor')
+const { MCPExecutorPlugin } = require('./executors/mcp-executor');
 
 module.exports = {
   // 核心
@@ -33,5 +21,5 @@ module.exports = {
   // 能力插件
   SkillManagerPlugin,
   WorkflowPlugin,
-  MCPExecutorPlugin
-}
+  MCPExecutorPlugin,
+};

package/src/utils/circuit-breaker.js

@@ -0,0 +1,301 @@
+/**
+ * CircuitBreaker 熔断器
+ * 用于防止工具调用失败时持续重试导致资源耗尽
+ */
+
+const { logger } = require('./logger');
+
+/**
+ * 熔断器状态
+ */
+const CircuitState = {
+  CLOSED: 'closed', // 正常状态，允许请求通过
+  OPEN: 'open', // 熔断状态，拒绝请求
+  HALF_OPEN: 'half_open', // 半开状态，允许一个测试请求
+};
+
+/**
+ * 熔断器选项
+ * @typedef {Object} CircuitBreakerOptions
+ * @property {number} [failureThreshold=3] - 连续失败次数达到此值时触发熔断
+ * @property {number} [successThreshold=2] - 半开状态下连续成功次数达到此值时关闭熔断
+ * @property {number} [timeout=60000] - 熔断持续时间（毫秒），超时后进入半开状态
+ * @property {string} [name] - 熔断器名称（用于日志）
+ */
+
+/**
+ * CircuitBreaker 熔断器类
+ * 使用滑动窗口记录请求成功/失败，帮助防止持续失败的工具调用
+ */
+class CircuitBreaker {
+  /**
+   * @param {CircuitBreakerOptions} options
+   */
+  constructor(options = {}) {
+    this.options = {
+      failureThreshold: options.failureThreshold || 3,
+      successThreshold: options.successThreshold || 2,
+      timeout: options.timeout || 60000, // 默认 1 分钟
+      name: options.name || 'default',
+    };
+
+    this._state = CircuitState.CLOSED;
+    this._failureCount = 0;
+    this._successCount = 0;
+    this._lastFailureTime = null;
+    this._halfOpenAttempts = 0;
+
+    this._log = logger.child('CircuitBreaker', { name: this.options.name });
+  }
+
+  /**
+   * 获取当前状态
+   * @returns {string}
+   */
+  getState() {
+    // 检查是否需要从 OPEN 转为 HALF_OPEN
+    if (this._state === CircuitState.OPEN && this._lastFailureTime) {
+      const elapsed = Date.now() - this._lastFailureTime;
+      if (elapsed >= this.options.timeout) {
+        this._transitionTo(CircuitState.HALF_OPEN);
+      }
+    }
+    return this._state;
+  }
+
+  /**
+   * 检查是否允许执行
+   * @returns {boolean}
+   */
+  canExecute() {
+    const state = this.getState();
+    return state === CircuitState.CLOSED || state === CircuitState.HALF_OPEN;
+  }
+
+  /**
+   * 执行带熔断保护的函数
+   * @param {Function} fn - 要执行的异步函数
+   * @returns {Promise<any>}
+   * @throws {Error} 如果熔断器处于 OPEN 状态，抛出错误
+   */
+  async execute(fn) {
+    if (!this.canExecute()) {
+      throw new Error(
+        `Circuit breaker is OPEN for '${this.options.name}'. ` +
+          `Tool calls are temporarily blocked. Try again later.`
+      );
+    }
+
+    try {
+      const result = await fn();
+      this._onSuccess();
+      return result;
+    } catch (err) {
+      this._onFailure(err);
+      throw err;
+    }
+  }
+
+  /**
+   * 记录成功
+   * @private
+   */
+  _onSuccess() {
+    if (this._state === CircuitState.HALF_OPEN) {
+      this._successCount++;
+      this._halfOpenAttempts++;
+      this._log.debug(`Half-open success: ${this._successCount}/${this.options.successThreshold}`);
+
+      if (this._successCount >= this.options.successThreshold) {
+        this._transitionTo(CircuitState.CLOSED);
+      }
+    } else if (this._state === CircuitState.CLOSED) {
+      // 成功后重置失败计数
+      this._failureCount = 0;
+    }
+  }
+
+  /**
+   * 记录失败
+   * @param {Error} err
+   * @private
+   */
+  _onFailure(err) {
+    this._failureCount++;
+    this._lastFailureTime = Date.now();
+
+    if (this._state === CircuitState.HALF_OPEN) {
+      // 半开状态下任何失败都立即打开熔断
+      this._log.warn(`Half-open failure, reopening circuit: ${err.message}`);
+      this._transitionTo(CircuitState.OPEN);
+    } else if (this._state === CircuitState.CLOSED) {
+      this._log.warn(
+        `Tool call failed (${this._failureCount}/${this.options.failureThreshold}): ${err.message}`
+      );
+
+      if (this._failureCount >= this.options.failureThreshold) {
+        this._log.error(
+          `Circuit breaker triggered for '${this.options.name}' after ${this._failureCount} consecutive failures`
+        );
+        this._transitionTo(CircuitState.OPEN);
+      }
+    }
+  }
+
+  /**
+   * 状态转换
+   * @param {string} newState
+   * @private
+   */
+  _transitionTo(newState) {
+    const oldState = this._state;
+    this._state = newState;
+
+    if (newState === CircuitState.CLOSED) {
+      this._failureCount = 0;
+      this._successCount = 0;
+      this._halfOpenAttempts = 0;
+      this._log.info(`Circuit breaker CLOSED (reset)`);
+    } else if (newState === CircuitState.HALF_OPEN) {
+      this._successCount = 0;
+      this._halfOpenAttempts = 0;
+      this._log.info(`Circuit breaker HALF_OPEN (testing after ${this.options.timeout}ms timeout)`);
+    } else if (newState === CircuitState.OPEN) {
+      this._successCount = 0;
+      this._halfOpenAttempts = 0;
+      this._log.warn(`Circuit breaker OPEN (blocking tool calls for ${this.options.timeout}ms)`);
+    }
+  }
+
+  /**
+   * 手动重置熔断器
+   */
+  reset() {
+    this._transitionTo(CircuitState.CLOSED);
+  }
+
+  /**
+   * 获取熔断器状态信息
+   * @returns {Object}
+   */
+  getStatus() {
+    return {
+      name: this.options.name,
+      state: this.getState(),
+      failureCount: this._failureCount,
+      successCount: this._successCount,
+      lastFailureTime: this._lastFailureTime,
+      nextRetryTime:
+        this._state === CircuitState.OPEN && this._lastFailureTime
+          ? new Date(this._lastFailureTime + this.options.timeout).toISOString()
+          : null,
+      config: {
+        failureThreshold: this.options.failureThreshold,
+        successThreshold: this.options.successThreshold,
+        timeout: this.options.timeout,
+      },
+    };
+  }
+}
+
+/**
+ * CircuitBreakerRegistry - 熔断器注册表
+ * 管理多个工具的熔断器
+ */
+class CircuitBreakerRegistry {
+  constructor() {
+    this._breakers = new Map();
+    this._log = logger.child('CircuitBreakerRegistry');
+  }
+
+  /**
+   * 获取或创建熔断器
+   * @param {string} name - 熔断器名称（通常为工具名）
+   * @param {CircuitBreakerOptions} options - 选项
+   * @returns {CircuitBreaker}
+   */
+  getOrCreate(name, options = {}) {
+    if (!this._breakers.has(name)) {
+      this._breakers.set(name, new CircuitBreaker({ ...options, name }));
+    }
+    return this._breakers.get(name);
+  }
+
+  /**
+   * 获取熔断器（如果不存在返回 null）
+   * @param {string} name
+   * @returns {CircuitBreaker|null}
+   */
+  get(name) {
+    return this._breakers.get(name) || null;
+  }
+
+  /**
+   * 检查是否允许执行
+   * @param {string} name
+   * @returns {boolean}
+   */
+  canExecute(name) {
+    const breaker = this._breakers.get(name);
+    return breaker ? breaker.canExecute() : true;
+  }
+
+  /**
+   * 执行带熔断保护的函数
+   * @param {string} name - 熔断器名称
+   * @param {Function} fn - 要执行的函数
+   * @param {CircuitBreakerOptions} options - 选项（首次创建时使用）
+   * @returns {Promise<any>}
+   */
+  async execute(name, fn, options = {}) {
+    const breaker = this.getOrCreate(name, options);
+    return breaker.execute(fn);
+  }
+
+  /**
+   * 获取所有熔断器状态
+   * @returns {Object[]}
+   */
+  getAllStatus() {
+    const result = [];
+    for (const [name, breaker] of this._breakers) {
+      result.push(breaker.getStatus());
+    }
+    return result;
+  }
+
+  /**
+   * 重置所有熔断器
+   */
+  resetAll() {
+    for (const breaker of this._breakers.values()) {
+      breaker.reset();
+    }
+    this._log.info('All circuit breakers reset');
+  }
+
+  /**
+   * 移除熔断器
+   * @param {string} name
+   */
+  remove(name) {
+    this._breakers.delete(name);
+  }
+
+  /**
+   * 清空所有熔断器
+   */
+  clear() {
+    this._breakers.clear();
+  }
+}
+
+// 导出单例
+const globalRegistry = new CircuitBreakerRegistry();
+
+module.exports = {
+  CircuitBreaker,
+  CircuitBreakerRegistry,
+  CircuitState,
+  globalCircuitBreaker: globalRegistry,
+};

package/src/utils/error-boundary.js

@@ -0,0 +1,363 @@
+/**
+ * Foliko Error Boundary - 错误边界系统
+ * 捕获、处理和恢复错误，提供降级方案
+ */
+
+const { EventEmitter } = require('./event-emitter');
+const { logger } = require('./logger');
+const { safeErrorInfo, isErrorOfType } = require('./error');
+
+/**
+ * 错误严重级别
+ */
+const Severity = {
+  LOW: 'low', // 可忽略的小问题
+  MEDIUM: 'medium', // 需要关注但不阻断流程
+  HIGH: 'high', // 阻断当前操作但可恢复
+  CRITICAL: 'critical', // 致命错误，需要完全降级
+};
+
+/**
+ * 错误恢复动作
+ */
+const RecoveryAction = {
+  RETRY: 'retry', // 重试操作
+  SKIP: 'skip', // 跳过当前步骤
+  FALLBACK: 'fallback', // 使用降级方案
+  ABORT: 'abort', // 中止流程
+  IGNORE: 'ignore', // 忽略错误继续
+};
+
+/**
+ * 错误上下文
+ * @typedef {Object} ErrorContext
+ * @property {string} operation - 操作名称
+ * @property {string} component - 组件名称
+ * @property {Object} metadata - 额外元数据
+ * @property {number} attempt - 当前尝试次数
+ */
+
+/**
+ * 错误边界配置
+ * @typedef {Object} ErrorBoundaryConfig
+ * @property {string} name - 边界名称
+ * @property {Function} [onError] - 全局错误处理器
+ * @property {Function} [onRecovery] - 恢复处理器
+ * @property {Function} [fallback] - 降级函数
+ * @property {boolean} [logErrors=true] - 是否记录错误
+ * @property {boolean} [propagateErrors=false] - 是否向上传播错误
+ */
+
+/**
+ * 错误边界类
+ * 用于捕获和管理错误，提供恢复机制
+ */
+class ErrorBoundary extends EventEmitter {
+  /**
+   * @param {ErrorBoundaryConfig} config
+   */
+  constructor(config = {}) {
+    super();
+
+    this.name = config.name || 'AnonymousBoundary';
+    this._onError = config.onError || null;
+    this._onRecovery = config.onRecovery || null;
+    this._fallback = config.fallback || null;
+    this._logErrors = config.logErrors !== false;
+    this._propagateErrors = config.propagateErrors || false;
+    this._logger = logger.child('ErrorBoundary');
+
+    // 错误统计
+    this._errorCount = 0;
+    this._lastError = null;
+    this._errorHistory = [];
+    this._maxHistorySize = config.maxHistorySize || 50;
+  }
+
+  /**
+   * 执行可能抛出错误的操作
+   * @param {Function} operation - 要执行的操作
+   * @param {Object} [context] - 错误上下文
+   * @returns {Promise<{success: boolean, result?: any, error?: Error, recovered?: boolean}>}
+   */
+  async execute(operation, context = {}) {
+    const operationName = context.operation || 'anonymous';
+
+    try {
+      const result = await (typeof operation === 'function' ? operation() : operation);
+      return { success: true, result };
+    } catch (error) {
+      this._errorCount++;
+      this._lastError = error;
+
+      // 记录到历史
+      this._addToHistory(error, context);
+
+      // 记录错误日志
+      if (this._logErrors) {
+        this._logError(error, context);
+      }
+
+      // 触发错误事件
+      this.emit('error', {
+        error,
+        context,
+        boundary: this.name,
+      });
+
+      // 调用全局错误处理器
+      let recoveryAction = RecoveryAction.ABORT;
+      if (this._onError) {
+        try {
+          // 使用 Promise.resolve 以支持 async 函数
+          recoveryAction = await Promise.resolve(this._onError(error, context, this));
+        } catch (handlerError) {
+          this._logger.warn(`Error in onError handler: ${handlerError.message}`);
+        }
+      }
+
+      // 根据恢复动作处理
+      const { action, fallbackResult } = await this._handleRecovery(error, context, recoveryAction);
+
+      // 触发恢复事件
+      if (action !== RecoveryAction.ABORT) {
+        this.emit('recovery', {
+          error,
+          context,
+          action,
+          boundary: this.name,
+        });
+
+        if (this._onRecovery) {
+          try {
+            await this._onRecovery(error, context, action, this);
+          } catch (recoveryError) {
+            log.warn(`Error in onRecovery handler: ${recoveryError.message}`);
+          }
+        }
+      }
+
+      // 如果需要传播错误，或者没有降级方案且要求传播，则抛出错误
+      if (this._propagateErrors || (action === RecoveryAction.ABORT && !fallbackResult)) {
+        throw error;
+      }
+
+      return {
+        success: false,
+        error,
+        recovered: action !== RecoveryAction.ABORT,
+        fallbackResult,
+        action,
+      };
+    }
+  }
+
+  /**
+   * 执行带重试的操作
+   * @param {Function} operation - 要执行的操作
+   * @param {Object} retryConfig - 重试配置
+   * @param {Object} [context] - 错误上下文
+   * @returns {Promise<any>}
+   */
+  async executeWithRetry(operation, retryConfig = {}, context = {}) {
+    const { maxAttempts = 3, baseDelay = 1000, shouldRetry = () => true } = retryConfig;
+
+    let lastError;
+
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      try {
+        return await this.execute(operation, { ...context, attempt });
+      } catch (error) {
+        lastError = error;
+
+        if (attempt >= maxAttempts || !shouldRetry(error, attempt)) {
+          throw error;
+        }
+
+        // 计算延迟
+        const delay = baseDelay * Math.pow(2, attempt - 1);
+        log.debug(`Retry attempt ${attempt}/${maxAttempts} after ${delay}ms...`);
+
+        await new Promise((resolve) => setTimeout(resolve, delay));
+      }
+    }
+
+    throw lastError;
+  }
+
+  /**
+   * 包装一个函数，使其错误被边界捕获
+   * @param {Function} fn - 要包装的函数
+   * @param {Object} [defaultContext] - 默认上下文
+   * @returns {Function}
+   */
+  wrap(fn, defaultContext = {}) {
+    return async (...args) => {
+      const result = await this.execute(() => fn(...args), defaultContext);
+      return result.success ? result.result : result.fallbackResult;
+    };
+  }
+
+  /**
+   * 处理错误恢复
+   * @private
+   */
+  async _handleRecovery(error, context, recoveryAction) {
+    let fallbackResult = null;
+    let action = recoveryAction;
+
+    switch (recoveryAction) {
+      case RecoveryAction.FALLBACK:
+        if (this._fallback) {
+          try {
+            fallbackResult = await this._fallback(error, context, this);
+            action = RecoveryAction.RETRY; // fallback 成功后视为恢复
+          } catch (fallbackError) {
+            log.warn(`Fallback also failed: ${fallbackError.message}`);
+            action = RecoveryAction.ABORT;
+          }
+        }
+        break;
+
+      case RecoveryAction.SKIP:
+        log.debug(`Skipping operation: ${context.operation}`);
+        fallbackResult = null;
+        break;
+
+      case RecoveryAction.IGNORE:
+        log.debug(`Ignoring error: ${error.message}`);
+        fallbackResult = undefined;
+        break;
+
+      default:
+        action = RecoveryAction.ABORT;
+    }
+
+    return { action, fallbackResult };
+  }
+
+  /**
+   * 记录错误
+   * @private
+   */
+  _logError(error, context) {
+    if (!this._logErrors) return;
+
+    const errorInfo = safeErrorInfo(error);
+    const severity = this._determineSeverity(error);
+
+    const logMessage = `[${this.name}] Error in ${context.operation || 'unknown'}: ${error.message}`;
+
+    switch (severity) {
+      case Severity.LOW:
+        this._logger.debug(logMessage);
+        break;
+      case Severity.MEDIUM:
+        this._logger.warn(logMessage);
+        break;
+      case Severity.HIGH:
+        this._logger.error(logMessage);
+        break;
+      case Severity.CRITICAL:
+        this._logger.error(`CRITICAL: ${logMessage}`, { stack: error.stack });
+        break;
+    }
+  }
+
+  /**
+   * 确定错误严重级别
+   * @private
+   */
+  _determineSeverity(error) {
+    if (isErrorOfType(error, require('./error').FolikoError)) {
+      return error.context?.severity || Severity.MEDIUM;
+    }
+
+    // 根据错误类型和消息判断
+    const message = (error.message || '').toLowerCase();
+
+    if (message.includes('timeout') || message.includes('network')) {
+      return Severity.MEDIUM;
+    }
+
+    if (message.includes('memory') || message.includes('fatal')) {
+      return Severity.CRITICAL;
+    }
+
+    return Severity.HIGH;
+  }
+
+  /**
+   * 添加错误到历史记录
+   * @private
+   */
+  _addToHistory(error, context) {
+    this._errorHistory.push({
+      timestamp: new Date().toISOString(),
+      error: safeErrorInfo(error),
+      context,
+    });
+
+    // 保持历史记录大小
+    if (this._errorHistory.length > this._maxHistorySize) {
+      this._errorHistory.shift();
+    }
+  }
+
+  /**
+   * 获取错误统计
+   * @returns {Object}
+   */
+  getStats() {
+    return {
+      totalErrors: this._errorCount,
+      lastError: this._lastError ? safeErrorInfo(this._lastError) : null,
+      historySize: this._errorHistory.length,
+      recentErrors: this._errorHistory.slice(-10),
+    };
+  }
+
+  /**
+   * 清空错误历史
+   */
+  clearHistory() {
+    this._errorHistory = [];
+    this._lastError = null;
+  }
+}
+
+/**
+ * 创建错误边界实例的工厂函数
+ * @param {ErrorBoundaryConfig} config
+ * @returns {ErrorBoundary}
+ */
+function createErrorBoundary(config = {}) {
+  return new ErrorBoundary(config);
+}
+
+/**
+ * 组合多个错误边界
+ * @param {ErrorBoundary[]} boundaries
+ * @returns {ErrorBoundary}
+ */
+function combineBoundaries(boundaries) {
+  const combined = new ErrorBoundary({
+    name: 'CombinedBoundary',
+  });
+
+  // 将错误传播到所有子边界
+  for (const boundary of boundaries) {
+    boundary.on('error', (data) => combined.emit('error', data));
+    boundary.on('recovery', (data) => combined.emit('recovery', data));
+  }
+
+  return combined;
+}
+
+module.exports = {
+  ErrorBoundary,
+  Severity,
+  RecoveryAction,
+  createErrorBoundary,
+  combineBoundaries,
+};