foliko 1.0.74 → 1.0.76

package/src/utils/index.js

@@ -1,3 +1,217 @@
-exports.cleanResponse=function (text) {
-    return text.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
-}
+/**
+ * Utils 模块导出
+ */
+
+// 日志系统
+const { Logger, logger, LOG_LEVELS } = require('./logger');
+
+// ID 生成器
+const {
+  uuid,
+  prefixedId,
+  shortId,
+  snowflake,
+  taskId,
+  goalId,
+  sessionId,
+  messageId,
+  ruleId,
+  resetSnowflake,
+} = require('./id');
+
+// 错误处理
+const {
+  FolikoError,
+  PluginError,
+  ToolError,
+  AIError,
+  SessionError,
+  ConfigError,
+  WorkflowError,
+  ValidationError,
+  ToolNotFoundError,
+  PluginNotFoundError,
+  isErrorOfType,
+  safeErrorInfo,
+} = require('./error');
+
+// 重试策略
+const { withRetry, retryable, isNetworkError, PRESETS } = require('./retry');
+
+// 错误边界
+const {
+  ErrorBoundary,
+  Severity,
+  RecoveryAction,
+  createErrorBoundary,
+  combineBoundaries,
+} = require('./error-boundary');
+
+/**
+ * 清理 LLM 回复中的思考标记
+ * @param {string} text
+ * @returns {string}
+ */
+function cleanResponse(text) {
+  return text.replace(/<think>[\s\S]*?<\/think>/g, '').trim();
+}
+
+/**
+ * 安全解析 JSON
+ * @param {string} str
+ * @param {*} defaultValue
+ * @returns {*}
+ */
+function safeJsonParse(str, defaultValue = null) {
+  try {
+    return JSON.parse(str);
+  } catch {
+    return defaultValue;
+  }
+}
+
+/**
+ * 深拷贝
+ * @param {*} obj
+ * @returns {*}
+ */
+function deepClone(obj) {
+  if (obj === null || typeof obj !== 'object') return obj;
+  if (obj instanceof Date) return new Date(obj);
+  if (obj instanceof Array) return obj.map((item) => deepClone(item));
+  if (obj instanceof Object) {
+    const copy = {};
+    for (const key in obj) {
+      if (obj.hasOwnProperty(key)) {
+        copy[key] = deepClone(obj[key]);
+      }
+    }
+    return copy;
+  }
+  return obj;
+}
+
+/**
+ * 防抖函数
+ * @param {Function} fn
+ * @param {number} delay
+ * @returns {Function}
+ */
+function debounce(fn, delay) {
+  let timeoutId;
+  return function (...args) {
+    clearTimeout(timeoutId);
+    timeoutId = setTimeout(() => fn.apply(this, args), delay);
+  };
+}
+
+/**
+ * 节流函数
+ * @param {Function} fn
+ * @param {number} limit
+ * @returns {Function}
+ */
+function throttle(fn, limit) {
+  let inThrottle;
+  return function (...args) {
+    if (!inThrottle) {
+      fn.apply(this, args);
+      inThrottle = true;
+      setTimeout(() => (inThrottle = false), limit);
+    }
+  };
+}
+
+/**
+ * 延迟执行
+ * @param {number} ms
+ * @returns {Promise}
+ */
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+/**
+ * 重试函数
+ * @param {Function} fn
+ * @param {Object} options
+ * @returns {Promise}
+ */
+async function retry(fn, options = {}) {
+  const { maxAttempts = 3, delay = 1000, backoff = 2, onRetry } = options;
+
+  let lastError;
+
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+
+      if (attempt < maxAttempts) {
+        const waitTime = delay * Math.pow(backoff, attempt - 1);
+        if (onRetry) {
+          onRetry(attempt, waitTime, error);
+        }
+        await sleep(waitTime);
+      }
+    }
+  }
+
+  throw lastError;
+}
+
+module.exports = {
+  // 日志
+  Logger,
+  logger,
+  LOG_LEVELS,
+
+  // ID 生成
+  uuid,
+  prefixedId,
+  shortId,
+  snowflake,
+  taskId,
+  goalId,
+  sessionId,
+  messageId,
+  ruleId,
+  resetSnowflake,
+
+  // 错误处理
+  FolikoError,
+  PluginError,
+  ToolError,
+  AIError,
+  SessionError,
+  ConfigError,
+  WorkflowError,
+  ValidationError,
+  ToolNotFoundError,
+  PluginNotFoundError,
+  isErrorOfType,
+  safeErrorInfo,
+
+  // 重试策略
+  withRetry,
+  retryable,
+  isNetworkError,
+  PRESETS,
+
+  // 错误边界
+  ErrorBoundary,
+  Severity,
+  RecoveryAction,
+  createErrorBoundary,
+  combineBoundaries,
+
+  // 工具函数
+  cleanResponse,
+  safeJsonParse,
+  deepClone,
+  debounce,
+  throttle,
+  sleep,
+  retry,
+};

package/src/utils/logger.js

@@ -0,0 +1,181 @@
+/**
+ * Foliko Logger - 统一日志系统
+ * 支持日志级别、命名空间、格式化输出
+ */
+
+const LOG_LEVELS = {
+  DEBUG: 0,
+  INFO: 1,
+  WARN: 2,
+  ERROR: 3,
+  NONE: 4,
+};
+
+const LEVEL_NAMES = ['DEBUG', 'INFO', 'WARN', 'ERROR'];
+
+class Logger {
+  /**
+   * @param {Object} options
+   * @param {string} options.namespace - 日志命名空间
+   * @param {number} options.level - 日志级别 (0-4)
+   * @param {boolean} options.enableTimestamp - 是否显示时间戳
+   * @param {boolean} options.enableColors - 是否使用颜色
+   */
+  constructor(options = {}) {
+    this.namespace = options.namespace || 'app';
+    this.level = options.level ?? LOG_LEVELS.INFO;
+    this.enableTimestamp = options.enableTimestamp !== false;
+    this.enableColors = options.enableColors !== false;
+
+    // 颜色代码
+    this.colors = {
+      debug: '\x1b[36m', // 青色
+      info: '\x1b[32m', // 绿色
+      warn: '\x1b[33m', // 黄色
+      error: '\x1b[31m', // 红色
+      reset: '\x1b[0m',
+      dim: '\x1b[2m', // 灰色
+    };
+  }
+
+  /**
+   * 创建子日志器
+   * @param {string} namespace
+   * @returns {Logger}
+   */
+  child(namespace) {
+    return new Logger({
+      namespace: `${this.namespace}:${namespace}`,
+      level: this.level,
+      enableTimestamp: this.enableTimestamp,
+      enableColors: this.enableColors,
+    });
+  }
+
+  /**
+   * 设置日志级别
+   * @param {string|number} level
+   */
+  setLevel(level) {
+    if (typeof level === 'string') {
+      this.level = LOG_LEVELS[level.toUpperCase()] ?? LOG_LEVELS.INFO;
+    } else {
+      this.level = level;
+    }
+  }
+
+  /**
+   * 格式化日志消息
+   * @private
+   */
+  _format(level, levelName, args) {
+    const color = this.colors[levelName.toLowerCase()] || '';
+    const reset = this.colors.reset;
+    const dim = this.colors.dim;
+
+    const parts = [];
+
+    // 命名空间
+    parts.push(`${dim}[${this.namespace}]${reset}`);
+
+    // 时间戳
+    if (this.enableTimestamp) {
+      const timestamp = new Date().toISOString().split('T')[1].slice(0, -1);
+      parts.push(`${dim}${timestamp}${reset}`);
+    }
+
+    // 级别
+    if (this.enableColors) {
+      parts.push(`${color}${levelName.padEnd(5)}${reset}`);
+    } else {
+      parts.push(levelName.padEnd(5));
+    }
+
+    // 消息
+    const message = args
+      .map((arg) => {
+        if (arg instanceof Error) {
+          return `${arg.message}\n${arg.stack}`;
+        }
+        if (typeof arg === 'object') {
+          try {
+            return JSON.stringify(arg, null, 2);
+          } catch {
+            return String(arg);
+          }
+        }
+        return String(arg);
+      })
+      .join(' ');
+
+    parts.push(message);
+    return parts.join(' ');
+  }
+
+  /**
+   * 调试日志
+   * @param {...any} args
+   */
+  debug(...args) {
+    if (this.level <= LOG_LEVELS.DEBUG) {
+      console.debug(this._format('debug', 'DEBUG', args));
+    }
+  }
+
+  /**
+   * 信息日志
+   * @param {...any} args
+   */
+  info(...args) {
+    if (this.level <= LOG_LEVELS.INFO) {
+      console.log(this._format('info', 'INFO', args));
+    }
+  }
+
+  /**
+   * 警告日志
+   * @param {...any} args
+   */
+  warn(...args) {
+    if (this.level <= LOG_LEVELS.WARN) {
+      console.warn(this._format('warn', 'WARN', args));
+    }
+  }
+
+  /**
+   * 错误日志
+   * @param {...any} args
+   */
+  error(...args) {
+    if (this.level <= LOG_LEVELS.ERROR) {
+      console.error(this._format('error', 'ERROR', args));
+    }
+  }
+
+  /**
+   * 性能计时开始
+   * @param {string} label
+   * @returns {function} 结束计时函数
+   */
+  timer(label) {
+    const start = process.hrtime.bigint();
+    return () => {
+      const end = process.hrtime.bigint();
+      const ms = Number(end - start) / 1_000_000;
+      this.debug(`${label}: ${ms.toFixed(2)}ms`);
+    };
+  }
+}
+
+// 全局日志器实例
+const globalLogger = new Logger({
+  namespace: 'foliko',
+  level: process.env.LOG_LEVEL ? LOG_LEVELS[process.env.LOG_LEVEL.toUpperCase()] : LOG_LEVELS.INFO,
+});
+
+// 导出
+module.exports = {
+  Logger,
+  logger: globalLogger,
+  LOG_LEVELS,
+};

package/src/utils/plugin-helpers.js

@@ -0,0 +1,90 @@
+/**
+ * Plugin Helpers - 插件相关的辅助函数
+ * 提供插件路径解析和扫描功能，供 PluginManager 和 DefaultPlugins 共用
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { safeJsonParse } = require('./index');
+
+/**
+ * 解析插件路径
+ * 支持两种结构：
+ * 1. 文件夹结构: .agent/plugins/my-plugin/index.js
+ * 2. 单文件结构: .agent/plugins/my-plugin.js
+ * @param {string} pluginsDir - 插件目录
+ * @param {string} name - 插件名称
+ * @param {Object} options - 选项
+ * @param {Object} options.logger - 日志器（可选）
+ * @returns {{path: string, type: 'folder'|'file'}|null} 插件路径和类型
+ */
+function resolvePluginPath(pluginsDir, name, options = {}) {
+  const logger = options.logger;
+  const folderPath = path.join(pluginsDir, name);
+  const filePath = path.join(pluginsDir, `${name}.js`);
+
+  // 文件夹优先
+  if (fs.existsSync(folderPath) && fs.statSync(folderPath).isDirectory()) {
+    const pkgPath = path.join(folderPath, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = safeJsonParse(fs.readFileSync(pkgPath, 'utf-8'), {});
+        const main = pkg.main || 'index.js';
+        const mainPath = path.join(folderPath, main);
+        if (fs.existsSync(mainPath)) {
+          return { path: mainPath, type: 'folder' };
+        }
+      } catch (err) {
+        logger?.warn(`Failed to parse package.json for ${name}:`, err.message);
+      }
+    }
+    // 默认加载 index.js
+    const indexPath = path.join(folderPath, 'index.js');
+    if (fs.existsSync(indexPath)) {
+      return { path: indexPath, type: 'folder' };
+    }
+    logger?.warn(`No entry point found for plugin folder: ${name}`);
+    return null;
+  }
+
+  // 单文件回退
+  if (fs.existsSync(filePath)) {
+    return { path: filePath, type: 'file' };
+  }
+
+  return null;
+}
+
+/**
+ * 扫描插件目录，返回所有插件名称
+ * @param {string} pluginsDir - 插件目录
+ * @returns {string[]} 插件名称列表
+ */
+function scanPluginNames(pluginsDir) {
+  if (!fs.existsSync(pluginsDir)) {
+    return [];
+  }
+
+  const names = new Set();
+  const entries = fs.readdirSync(pluginsDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      // 文件夹插件
+      names.add(entry.name);
+    } else if (entry.isFile() && entry.name.endsWith('.js')) {
+      // 单文件插件（排除与文件夹同名的）
+      const baseName = entry.name.replace(/\.js$/, '');
+      if (!names.has(baseName)) {
+        names.add(baseName);
+      }
+    }
+  }
+
+  return Array.from(names);
+}
+
+module.exports = {
+  resolvePluginPath,
+  scanPluginNames,
+};

package/src/utils/retry.js

@@ -0,0 +1,122 @@
+/**
+ * Foliko Retry Strategy - 重试策略系统
+ * 提供多种重试策略，支持指数退避、抖动等
+ */
+
+const { logger } = require('./logger');
+
+const log = logger.child('RetryStrategy');
+
+/**
+ * 重试策略配置
+ * @typedef {Object} RetryConfig
+ * @property {number} maxAttempts - 最大重试次数
+ * @property {number} baseDelay - 基础延迟（毫秒）
+ * @property {number} maxDelay - 最大延迟（毫秒）
+ * @property {number} [factor=2] - 退避因子
+ * @property {number} [jitter=0.1] - 抖动因子（0-1）
+ * @property {Function} [shouldRetry] - 判断是否应重试的函数
+ * @property {Function} [onRetry] - 重试前回调
+ */
+
+/**
+ * 预设的重试策略
+ */
+const PRESETS = {
+  /** 快速重试（适合网络瞬时抖动） */
+  fast: {
+    maxAttempts: 3,
+    baseDelay: 100,
+    maxDelay: 1000,
+    factor: 2,
+    jitter: 0.1,
+  },
+  /** 标准重试（适合大多数场景） */
+  standard: {
+    maxAttempts: 3,
+    baseDelay: 1000,
+    maxDelay: 10000,
+    factor: 2,
+    jitter: 0.2,
+  },
+  /** 保守重试（适合外部依赖） */
+  conservative: {
+    maxAttempts: 5,
+    baseDelay: 2000,
+    maxDelay: 30000,
+    factor: 2,
+    jitter: 0.3,
+  },
+  /** 指数退避（适合限流场景） */
+  exponential: {
+    maxAttempts: 5,
+    baseDelay: 1000,
+    maxDelay: 60000,
+    factor: 2,
+    jitter: 0.1,
+  },
+  /** 激进重试（适合紧急恢复，快速多次尝试） */
+  aggressive: {
+    maxAttempts: 5,
+    baseDelay: 200,
+    maxDelay: 2000,
+    factor: 1.5,
+    jitter: 0.05,
+  },
+  /** 空闲连接保活（适合长时间运行的连接检查） */
+  idle: {
+    maxAttempts: 3,
+    baseDelay: 5000,
+    maxDelay: 15000,
+    factor: 1.5,
+    jitter: 0.1,
+    shouldRetry: (error) => {
+      const networkCodes = ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND'];
+      return error.code && networkCodes.includes(error.code);
+    },
+  },
+  /** 数据库重试（适合数据库连接） */
+  database: {
+    maxAttempts: 5,
+    baseDelay: 1000,
+    maxDelay: 30000,
+    factor: 2,
+    jitter: 0.2,
+    shouldRetry: (error) => {
+      const dbCodes = [
+        'ECONNREFUSED',
+        'ECONNRESET',
+        'ETIMEDOUT',
+        'PROTOCOL_CONNECTION_LOST',
+        'ER_CON_COUNT_ERROR',
+      ];
+      const dbKeywords = [
+        'connection',
+        'timeout',
+        'database',
+        'sql',
+        'mysql',
+        'postgres',
+        'mongodb',
+      ];
+      if (error.code && dbCodes.includes(error.code)) return true;
+      const msg = (error.message || '').toLowerCase();
+      return dbKeywords.some((k) => msg.includes(k));
+    },
+  },
+  /** API调用重试（适合第三方API） */
+  api: {
+    maxAttempts: 4,
+    baseDelay: 500,
+    maxDelay: 8000,
+    factor: 2,
+    jitter: 0.15,
+    shouldRetry: (error) => {
+      const status = error.status || error.statusCode;
+      if (status && (status >= 500 || status === 429)) return true;
+      const networkCodes = ['ECONNREFUSED', 'ECONNRESET', 'ETIMEDOUT', 'ENOTFOUND'];
+      if (error.code && networkCodes.includes(error.code)) return true;
+      return false;
+    },
+  },
+};