foliko 1.0.74 → 1.0.76

package/src/utils/error.js

@@ -0,0 +1,374 @@
+/**
+ * Foliko Error - 统一错误处理系统
+ * 标准化项目中的所有错误类型
+ */
+
+/**
+ * Foliko 错误基类
+ */
+class FolikoError extends Error {
+  /**
+   * @param {string} message - 错误消息
+   * @param {Object} [options]
+   * @param {string} [options.code] - 错误代码
+   * @param {Object} [options.context] - 错误上下文
+   * @param {string} [options.stack] - 自定义堆栈
+   */
+  constructor(message, options = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = options.code || 'FOLIKO_ERROR';
+    this.context = options.context || {};
+
+    // 保留原始堆栈跟踪
+    if (options.stack) {
+      this.stack = options.stack;
+    } else {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+
+  /**
+   * 将错误转换为 JSON
+   * @returns {Object}
+   */
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      code: this.code,
+      context: this.context,
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * 插件相关错误
+ */
+class PluginError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'PLUGIN_ERROR',
+      context: options.context,
+    });
+  }
+}
+
+/**
+ * 工具执行错误
+ */
+class ToolError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'TOOL_ERROR',
+      context: {
+        toolName: options.toolName,
+        args: options.args,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * AI 执行错误
+ */
+class AIError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'AI_ERROR',
+      context: {
+        model: options.model,
+        provider: options.provider,
+        statusCode: options.statusCode,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * 会话相关错误
+ */
+class SessionError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'SESSION_ERROR',
+      context: {
+        sessionId: options.sessionId,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * 配置错误
+ */
+class ConfigError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'CONFIG_ERROR',
+      context: {
+        configKey: options.configKey,
+        expected: options.expected,
+        actual: options.actual,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * 工作流执行错误
+ */
+class WorkflowError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'WORKFLOW_ERROR',
+      context: {
+        workflowName: options.workflowName,
+        stepName: options.stepName,
+        stepIndex: options.stepIndex,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * 验证错误
+ */
+class ValidationError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'VALIDATION_ERROR',
+      context: {
+        field: options.field,
+        value: options.value,
+        expected: options.expected,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * 工具未找到错误
+ */
+class ToolNotFoundError extends ToolError {
+  constructor(toolName) {
+    super(`Tool not found: ${toolName}`, { toolName });
+    this.code = 'TOOL_NOT_FOUND';
+  }
+}
+
+/**
+ * 插件未找到错误
+ */
+class PluginNotFoundError extends PluginError {
+  constructor(pluginName) {
+    super(`Plugin not found: ${pluginName}`, {
+      context: { pluginName },
+    });
+    this.code = 'PLUGIN_NOT_FOUND';
+  }
+}
+
+/**
+ * 检查错误类型
+ * @param {Error} error
+ * @param {Function} ErrorClass
+ * @returns {boolean}
+ */
+
+/**
+ * 网络相关错误
+ */
+class NetworkError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'NETWORK_ERROR',
+      context: {
+        host: options.host,
+        port: options.port,
+        code: options.code,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * 认证/授权错误
+ */
+class AuthError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'AUTH_ERROR',
+      context: {
+        authType: options.authType,
+        userId: options.userId,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * 限流错误
+ */
+class RateLimitError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'RATE_LIMIT_ERROR',
+      context: {
+        retryAfter: options.retryAfter,
+        limit: options.limit,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * 超时错误
+ */
+class TimeoutError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'TIMEOUT_ERROR',
+      context: {
+        timeout: options.timeout,
+        operation: options.operation,
+        ...options.context,
+      },
+    });
+  }
+}
+
+/**
+ * 文件系统错误
+ */
+class FileSystemError extends FolikoError {
+  constructor(message, options = {}) {
+    super(message, {
+      code: 'FS_ERROR',
+      context: {
+        path: options.path,
+        operation: options.operation,
+        ...options.context,
+      },
+    });
+  }
+}
+
+function isErrorOfType(error, ErrorClass) {
+  return error instanceof ErrorClass;
+}
+
+/**
+ * 安全地获取错误信息
+ * @param {Error} error
+ * @returns {Object}
+ */
+function safeErrorInfo(error) {
+  if (error instanceof FolikoError) {
+    return error.toJSON();
+  }
+  return {
+    name: error.name || 'Error',
+    message: error.message,
+    code: 'UNKNOWN_ERROR',
+    context: {},
+    stack: error.stack,
+  };
+}
+
+/**
+ * 错误工厂函数 - 根据错误类型快速创建错误
+ * @param {string} type - 错误类型
+ * @param {string} message - 错误消息
+ * @param {Object} options - 错误选项
+ * @returns {FolikoError}
+ */
+function createError(type, message, options = {}) {
+  const errorClasses = {
+    plugin: PluginError,
+    tool: ToolError,
+    ai: AIError,
+    session: SessionError,
+    config: ConfigError,
+    workflow: WorkflowError,
+    validation: ValidationError,
+    network: NetworkError,
+    auth: AuthError,
+    rateLimit: RateLimitError,
+    timeout: TimeoutError,
+    fs: FileSystemError,
+  };
+  const ErrorClass = errorClasses[type] || FolikoError;
+  return new ErrorClass(message, options);
+}
+
+/**
+ * 判断错误是否可重试
+ * @param {Error} error
+ * @returns {boolean}
+ */
+function isRetryable(error) {
+  if (error instanceof RateLimitError) return true;
+  if (error instanceof TimeoutError) return true;
+  if (error instanceof NetworkError) return true;
+  if (error instanceof FolikoError) {
+    const retryableCodes = ['RATE_LIMIT_ERROR', 'TIMEOUT_ERROR', 'NETWORK_ERROR'];
+    return retryableCodes.includes(error.code);
+  }
+  return false;
+}
+
+/**
+ * 获取用户友好的错误消息
+ * @param {Error} error
+ * @returns {string}
+ */
+function getFriendlyMessage(error) {
+  if (error instanceof FolikoError) {
+    const messages = {
+      PLUGIN_NOT_FOUND: '插件未找到，请检查配置',
+      TOOL_NOT_FOUND: '工具未找到，请检查工具名称',
+      CONFIG_ERROR: '配置错误，请检查配置文件',
+      VALIDATION_ERROR: '输入验证失败，请检查输入数据',
+      RATE_LIMIT_ERROR: '请求过于频繁，请稍后再试',
+      TIMEOUT_ERROR: '请求超时，请检查网络连接',
+      NETWORK_ERROR: '网络错误，请检查网络连接',
+      AUTH_ERROR: '认证失败，请检查凭据是否正确',
+    };
+    return messages[error.code] || error.message;
+  }
+  return error.message || '发生未知错误';
+}
+
+module.exports = {
+  FolikoError,
+  PluginError,
+  ToolError,
+  AIError,
+  SessionError,
+  ConfigError,
+  WorkflowError,
+  ValidationError,
+  ToolNotFoundError,
+  PluginNotFoundError,
+  NetworkError,
+  AuthError,
+  RateLimitError,
+  TimeoutError,
+  FileSystemError,
+  isErrorOfType,
+  safeErrorInfo,
+  createError,
+  isRetryable,
+  getFriendlyMessage,
+};

package/src/utils/event-emitter.js

@@ -1,97 +1,97 @@
-/**
- * EventEmitter 事件发射器
- * 简单的事件总线实现
- */
-
-class EventEmitter {
-  constructor() {
-    this._events = new Map()
-  }
-
-  /**
-   * 监听事件
-   * @param {string} event - 事件名
-   * @param {Function} handler - 处理函数
-   * @returns {this}
-   */
-  on(event, handler) {
-    if (!this._events.has(event)) {
-      this._events.set(event, new Set())
-    }
-    this._events.get(event).add(handler)
-    return this
-  }
-
-  /**
-   * 监听一次性事件
-   * @param {string} event - 事件名
-   * @param {Function} handler - 处理函数
-   * @returns {this}
-   */
-  once(event, handler) {
-    const wrapper = (...args) => {
-      handler(...args)
-      this.off(event, wrapper)
-    }
-    return this.on(event, wrapper)
-  }
-
-  /**
-   * 取消监听
-   * @param {string} event - 事件名
-   * @param {Function} handler - 处理函数
-   * @returns {this}
-   */
-  off(event, handler) {
-    const handlers = this._events.get(event)
-    if (handlers) {
-      handlers.delete(handler)
-    }
-    return this
-  }
-
-  /**
-   * 触发事件
-   * @param {string} event - 事件名
-   * @param {...any} args - 参数
-   * @returns {this}
-   */
-  emit(event, ...args) {
-    const handlers = this._events.get(event)
-    if (handlers) {
-      for (const handler of handlers) {
-        try {
-          handler(...args)
-        } catch (err) {
-          console.error(`[EventEmitter] Error in handler for '${event}':`, err)
-        }
-      }
-    }
-    return this
-  }
-
-  /**
-   * 移除所有监听器
-   * @param {string} [event] - 可选，指定事件名
-   * @returns {this}
-   */
-  removeAllListeners(event) {
-    if (event) {
-      this._events.delete(event)
-    } else {
-      this._events.clear()
-    }
-    return this
-  }
-
-  /**
-   * 获取监听器数量
-   * @param {string} event - 事件名
-   * @returns {number}
-   */
-  listenerCount(event) {
-    return this._events.get(event)?.size || 0
-  }
-}
-
-module.exports = { EventEmitter }
+/**
+ * EventEmitter 事件发射器
+ * 简单的事件总线实现
+ */
+
+class EventEmitter {
+  constructor() {
+    this._events = new Map();
+  }
+
+  /**
+   * 监听事件
+   * @param {string} event - 事件名
+   * @param {Function} handler - 处理函数
+   * @returns {this}
+   */
+  on(event, handler) {
+    if (!this._events.has(event)) {
+      this._events.set(event, new Set());
+    }
+    this._events.get(event).add(handler);
+    return this;
+  }
+
+  /**
+   * 监听一次性事件
+   * @param {string} event - 事件名
+   * @param {Function} handler - 处理函数
+   * @returns {this}
+   */
+  once(event, handler) {
+    const wrapper = (...args) => {
+      handler(...args);
+      this.off(event, wrapper);
+    };
+    return this.on(event, wrapper);
+  }
+
+  /**
+   * 取消监听
+   * @param {string} event - 事件名
+   * @param {Function} handler - 处理函数
+   * @returns {this}
+   */
+  off(event, handler) {
+    const handlers = this._events.get(event);
+    if (handlers) {
+      handlers.delete(handler);
+    }
+    return this;
+  }
+
+  /**
+   * 触发事件
+   * @param {string} event - 事件名
+   * @param {...any} args - 参数
+   * @returns {this}
+   */
+  emit(event, ...args) {
+    const handlers = this._events.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        try {
+          handler(...args);
+        } catch (err) {
+          // EventEmitter error: Error in handler for '${event}':`, err)
+        }
+      }
+    }
+    return this;
+  }
+
+  /**
+   * 移除所有监听器
+   * @param {string} [event] - 可选，指定事件名
+   * @returns {this}
+   */
+  removeAllListeners(event) {
+    if (event) {
+      this._events.delete(event);
+    } else {
+      this._events.clear();
+    }
+    return this;
+  }
+
+  /**
+   * 获取监听器数量
+   * @param {string} event - 事件名
+   * @returns {number}
+   */
+  listenerCount(event) {
+    return this._events.get(event)?.size || 0;
+  }
+}
+
+module.exports = { EventEmitter };

package/src/utils/id.js

@@ -0,0 +1,133 @@
+/**
+ * Foliko ID 生成器 - 统一 ID 生成
+ * 支持 UUID、ULID、雪花ID、自定义前缀
+ */
+
+const crypto = require('crypto');
+
+/**
+ * 生成标准 UUID v4
+ * @returns {string}
+ */
+function uuid() {
+  if (crypto.randomUUID) {
+    return crypto.randomUUID();
+  }
+  // 回退实现 (Node.js < 14.17)
+  return ([1e7] + -1e3 + -4e3 + -8e3 + -1e11).replace(/[018]/g, (c) =>
+    (c ^ (crypto.randomBytes(1)[0] & (15 >> (c / 4)))).toString(16)
+  );
+}
+
+/**
+ * 生成带前缀的 UUID
+ * @param {string} prefix - 前缀，如 'agent', 'session', 'task'
+ * @returns {string}
+ */
+function prefixedId(prefix = 'id') {
+  return `${prefix}_${uuid()}`;
+}
+
+/**
+ * 生成短 ID (无连字符)
+ * @param {number} length - 长度，默认 12
+ * @returns {string}
+ */
+function shortId(length = 12) {
+  return uuid().replace(/-/g, '').slice(0, length);
+}
+
+/**
+ * 生成雪花 ID (Twitter Snowflake 简化版)
+ * @returns {string}
+ */
+let snowflakeEpoch = 1609459200000; // 2021-01-01
+let snowflakeSequence = 0;
+let snowflakeLastTime = 0;
+
+function snowflake() {
+  const now = Date.now();
+
+  if (now === snowflakeLastTime) {
+    snowflakeSequence = (snowflakeSequence + 1) & 4095;
+  } else {
+    snowflakeSequence = 0;
+    snowflakeLastTime = now;
+  }
+
+  const timestamp = now - snowflakeEpoch;
+  const workerId = 1;
+
+  const id = (BigInt(timestamp) << 22n) | (BigInt(workerId) << 12n) | BigInt(snowflakeSequence);
+
+  return id.toString();
+}
+
+/**
+ * 生成任务 ID (向后兼容原有格式)
+ * @param {string} [prefix] - 可选前缀
+ * @returns {string}
+ */
+function taskId(prefix) {
+  const suffix = crypto.randomBytes(8).toString('base64url');
+  return prefix ? `${prefix}_${suffix}` : suffix;
+}
+
+/**
+ * 生成目标 ID (向后兼容原有格式)
+ * @returns {string}
+ */
+function goalId() {
+  const random = crypto.randomBytes(8).toString('base64url');
+  return `goal_${Date.now()}_${random}`;
+}
+
+/**
+ * 生成会话 ID (向后兼容原有格式)
+ * @returns {string}
+ */
+function sessionId() {
+  const random = crypto.randomBytes(8).toString('base64url');
+  return `session_${Date.now()}_${random}`;
+}
+
+/**
+ * 生成邮箱消息 ID
+ * @returns {string}
+ */
+function messageId() {
+  const timestamp = Date.now();
+  const random = crypto.randomBytes(10).toString('base64url');
+  return `<${timestamp}.${random}@foliko>`;
+}
+
+/**
+ * 生成规则 ID
+ * @returns {string}
+ */
+function ruleId() {
+  const random = crypto.randomBytes(8).toString('base64url');
+  return `rule_${Date.now()}_${random}`;
+}
+
+/**
+ * 重置雪花 ID 计数器 (用于测试)
+ */
+function resetSnowflake() {
+  snowflakeSequence = 0;
+  snowflakeLastTime = 0;
+}
+
+// 导出所有函数
+module.exports = {
+  uuid,
+  prefixedId,
+  shortId,
+  snowflake,
+  taskId,
+  goalId,
+  sessionId,
+  messageId,
+  ruleId,
+  resetSnowflake,
+};