cfix 1.0.0

package/src/utils/project-lock.js

@@ -0,0 +1,246 @@
+const { logger } = require('../logger');
+
+/**
+ * 项目锁管理器
+ * 用于防止同一项目的多个任务并发执行，避免 Git 冲突
+ */
+class ProjectLockManager {
+  constructor() {
+    // 项目锁映射：{ projectPath: { taskId, promise, waitingTasks: [] } }
+    this.locks = new Map();
+
+    // 统计信息
+    this.stats = {
+      totalLocks: 0,
+      currentLocks: 0,
+      waitingTasks: 0,
+      maxWaitTime: 0,
+    };
+  }
+
+  /**
+   * 获取项目的唯一标识
+   * @param {string} projectPath - 项目路径
+   * @returns {string} 标准化的项目标识
+   */
+  getProjectKey(projectPath) {
+    if (!projectPath) {
+      return null;
+    }
+
+    // 标准化路径（处理 Windows/Linux 路径差异）
+    const normalized = projectPath
+      .replace(/\\/g, '/')  // 统一使用 /
+      .toLowerCase()        // 不区分大小写
+      .replace(/\/$/, '');  // 移除尾部斜杠
+
+    return normalized;
+  }
+
+  /**
+   * 尝试获取项目锁
+   * @param {string} projectPath - 项目路径
+   * @param {string} taskId - 任务ID
+   * @returns {Promise<void>} 获取锁成功后 resolve
+   */
+  async acquireLock(projectPath, taskId) {
+    const projectKey = this.getProjectKey(projectPath);
+
+    if (!projectKey) {
+      // 没有项目路径，直接通过（如首次克隆）
+      return;
+    }
+
+    const existingLock = this.locks.get(projectKey);
+
+    if (!existingLock) {
+      // 没有锁，直接获取
+      logger.info(`🔓 项目锁已获取: ${projectKey}`, { taskId, projectPath });
+
+      this.locks.set(projectKey, {
+        taskId,
+        projectPath,
+        acquiredAt: Date.now(),
+        waitingTasks: [],
+      });
+
+      this.stats.totalLocks++;
+      this.stats.currentLocks++;
+
+      return;
+    }
+
+    // 已有锁，需要等待
+    logger.warn(`⏳ 项目已被锁定，任务进入等待队列`, {
+      taskId,
+      projectPath,
+      lockHolder: existingLock.taskId,
+      waitingCount: existingLock.waitingTasks.length,
+    });
+
+    this.stats.waitingTasks++;
+
+    // 创建一个 Promise，等待前面的任务完成
+    return new Promise((resolve) => {
+      const waitStartTime = Date.now();
+
+      existingLock.waitingTasks.push({
+        taskId,
+        projectPath,
+        resolve,
+        waitStartTime,
+      });
+
+      logger.info(`📋 任务已加入等待队列 (位置: ${existingLock.waitingTasks.length})`, {
+        taskId,
+        projectPath,
+      });
+    });
+  }
+
+  /**
+   * 释放项目锁
+   * @param {string} projectPath - 项目路径
+   * @param {string} taskId - 任务ID
+   */
+  releaseLock(projectPath, taskId) {
+    const projectKey = this.getProjectKey(projectPath);
+
+    if (!projectKey) {
+      return;
+    }
+
+    const lock = this.locks.get(projectKey);
+
+    if (!lock) {
+      logger.warn(`⚠️ 尝试释放不存在的锁`, { taskId, projectPath });
+      return;
+    }
+
+    if (lock.taskId !== taskId) {
+      logger.warn(`⚠️ 任务不持有此锁，无法释放`, {
+        taskId,
+        lockHolder: lock.taskId,
+        projectPath,
+      });
+      return;
+    }
+
+    const lockDuration = Date.now() - lock.acquiredAt;
+
+    logger.info(`🔓 项目锁已释放`, {
+      taskId,
+      projectPath,
+      duration: `${(lockDuration / 1000).toFixed(2)}s`,
+      waitingCount: lock.waitingTasks.length,
+    });
+
+    this.stats.currentLocks--;
+
+    // 如果有等待的任务，唤醒第一个
+    if (lock.waitingTasks.length > 0) {
+      const nextTask = lock.waitingTasks.shift();
+      this.stats.waitingTasks--;
+
+      const waitTime = Date.now() - nextTask.waitStartTime;
+
+      if (waitTime > this.stats.maxWaitTime) {
+        this.stats.maxWaitTime = waitTime;
+      }
+
+      logger.info(`🔓 唤醒等待任务`, {
+        taskId: nextTask.taskId,
+        projectPath,
+        waitTime: `${(waitTime / 1000).toFixed(2)}s`,
+        remainingWaiting: lock.waitingTasks.length,
+      });
+
+      // 更新锁的持有者
+      this.locks.set(projectKey, {
+        taskId: nextTask.taskId,
+        projectPath: nextTask.projectPath,
+        acquiredAt: Date.now(),
+        waitingTasks: lock.waitingTasks, // 保留剩余的等待队列
+      });
+
+      this.stats.totalLocks++;
+      this.stats.currentLocks++;
+
+      // 唤醒等待的任务
+      nextTask.resolve();
+    } else {
+      // 没有等待的任务，删除锁
+      this.locks.delete(projectKey);
+      logger.debug(`🗑️ 项目锁已删除（无等待任务）`, { projectPath });
+    }
+  }
+
+  /**
+   * 检查项目是否被锁定
+   * @param {string} projectPath - 项目路径
+   * @returns {Object|null} 锁信息或 null
+   */
+  isLocked(projectPath) {
+    const projectKey = this.getProjectKey(projectPath);
+
+    if (!projectKey) {
+      return null;
+    }
+
+    const lock = this.locks.get(projectKey);
+
+    if (!lock) {
+      return null;
+    }
+
+    return {
+      locked: true,
+      taskId: lock.taskId,
+      waitingCount: lock.waitingTasks.length,
+      duration: Date.now() - lock.acquiredAt,
+    };
+  }
+
+  /**
+   * 获取统计信息
+   * @returns {Object} 统计数据
+   */
+  getStats() {
+    return {
+      ...this.stats,
+      activeLocks: this.locks.size,
+      locks: Array.from(this.locks.entries()).map(([projectKey, lock]) => ({
+        projectKey,
+        taskId: lock.taskId,
+        waitingCount: lock.waitingTasks.length,
+        duration: Date.now() - lock.acquiredAt,
+      })),
+    };
+  }
+
+  /**
+   * 强制释放所有锁（用于紧急情况）
+   */
+  releaseAll() {
+    logger.warn('⚠️ 强制释放所有项目锁');
+
+    for (const [projectKey, lock] of this.locks.entries()) {
+      logger.warn(`🔓 强制释放锁: ${projectKey}`, {
+        taskId: lock.taskId,
+        waitingCount: lock.waitingTasks.length,
+      });
+
+      // 拒绝所有等待的任务
+      lock.waitingTasks.forEach((waitingTask) => {
+        logger.error(`❌ 等待任务被强制中止: ${waitingTask.taskId}`);
+      });
+    }
+
+    this.locks.clear();
+    this.stats.currentLocks = 0;
+    this.stats.waitingTasks = 0;
+  }
+}
+
+// 单例模式
+module.exports = new ProjectLockManager();

package/src/utils/retry.js

@@ -0,0 +1,110 @@
+const { logger } = require('../logger');
+
+/**
+ * 重试工具类
+ * 提供带重试机制的异步函数执行
+ */
+class RetryUtil {
+  /**
+   * 带重试的异步函数执行
+   * @param {Function} fn - 要执行的异步函数
+   * @param {Object} options - 配置选项
+   * @param {number} options.maxRetries - 最大重试次数，默认 3
+   * @param {number} options.delay - 初始延迟时间（毫秒），默认 1000
+   * @param {boolean} options.exponentialBackoff - 是否使用指数退避，默认 true
+   * @param {string} options.operation - 操作名称（用于日志），默认 '操作'
+   * @param {Function} options.shouldRetry - 判断是否应该重试的函数，默认总是重试
+   * @returns {Promise<*>} 函数执行结果
+   */
+  static async withRetry(fn, options = {}) {
+    const {
+      maxRetries = 3,
+      delay = 1000,
+      exponentialBackoff = true,
+      operation = '操作',
+      shouldRetry = () => true,
+    } = options;
+
+    let lastError;
+
+    for (let attempt = 1; attempt <= maxRetries; attempt++) {
+      try {
+        return await fn();
+      } catch (error) {
+        lastError = error;
+
+        // 判断是否应该重试
+        if (!shouldRetry(error)) {
+          logger.error(`${operation}失败且不可重试`, {
+            error: error.message,
+            attempt,
+          });
+          throw error;
+        }
+
+        // 如果已达最大重试次数，抛出错误
+        if (attempt === maxRetries) {
+          logger.error(`${operation}失败，已达最大重试次数 ${maxRetries}`, {
+            error: error.message,
+          });
+          throw error;
+        }
+
+        // 计算等待时间
+        const waitTime = exponentialBackoff
+          ? delay * Math.pow(2, attempt - 1)
+          : delay;
+
+        logger.warn(
+          `${operation}失败，${waitTime}ms 后进行第 ${attempt}/${maxRetries} 次重试`,
+          { error: error.message }
+        );
+
+        // 等待后重试
+        await new Promise(resolve => setTimeout(resolve, waitTime));
+      }
+    }
+
+    // 理论上不会到这里，但为了类型安全
+    throw lastError;
+  }
+
+  /**
+   * 带超时的异步函数执行
+   * @param {Function} fn - 要执行的异步函数
+   * @param {number} timeoutMs - 超时时间（毫秒）
+   * @param {string} operation - 操作名称
+   * @returns {Promise<*>} 函数执行结果
+   */
+  static async withTimeout(fn, timeoutMs, operation = '操作') {
+    return Promise.race([
+      fn(),
+      new Promise((_, reject) =>
+        setTimeout(() => {
+          reject(new Error(`${operation}超时 (${timeoutMs}ms)`));
+        }, timeoutMs)
+      ),
+    ]);
+  }
+
+  /**
+   * 带重试和超时的异步函数执行
+   * @param {Function} fn - 要执行的异步函数
+   * @param {Object} options - 配置选项
+   * @returns {Promise<*>} 函数执行结果
+   */
+  static async withRetryAndTimeout(fn, options = {}) {
+    const {
+      timeoutMs = 30000,
+      operation = '操作',
+      ...retryOptions
+    } = options;
+
+    return this.withRetry(
+      () => this.withTimeout(fn, timeoutMs, operation),
+      { ...retryOptions, operation }
+    );
+  }
+}
+
+module.exports = RetryUtil;

package/src/utils/sanitizer.js

@@ -0,0 +1,174 @@
+/**
+ * 输入清理工具
+ * 用于验证和清理用户输入，防止安全漏洞
+ */
+class InputSanitizer {
+  /**
+   * 清理需求描述
+   * @param {string} requirement - 需求描述
+   * @returns {string} 清理后的需求描述
+   */
+  static sanitizeRequirement(requirement) {
+    if (typeof requirement !== 'string') {
+      throw new Error('需求描述必须是字符串');
+    }
+
+    // 长度限制
+    if (requirement.length === 0) {
+      throw new Error('需求描述不能为空');
+    }
+
+    if (requirement.length > 2000) {
+      throw new Error('需求描述过长，最多 2000 字符');
+    }
+
+    // 移除危险字符
+    return requirement
+      .replace(/[`$]/g, '') // 移除反引号和美元符号，防止命令注入
+      .replace(/\n{3,}/g, '\n\n') // 限制连续换行
+      .trim();
+  }
+
+  /**
+   * 清理用户名（用于分支命名）
+   * @param {string} username - 用户名
+   * @returns {string} 清理后的用户名
+   */
+  static sanitizeUsername(username) {
+    if (typeof username !== 'string') {
+      return 'system';
+    }
+
+    // 只允许字母、数字、下划线、连字符
+    const cleaned = username.replace(/[^a-zA-Z0-9_-]/g, '_');
+
+    if (cleaned.length === 0 || cleaned.length > 50) {
+      return 'system';
+    }
+
+    return cleaned.toLowerCase();
+  }
+
+  /**
+   * 清理分支名称
+   * @param {string} name - 分支名称
+   * @returns {string} 清理后的分支名称
+   */
+  static sanitizeBranchName(name) {
+    // Git 分支名安全字符
+    return name
+      .replace(/[^a-zA-Z0-9_\-\/]/g, '_')
+      .replace(/_{2,}/g, '_')
+      .replace(/^[_\-]+|[_\-]+$/g, '');
+  }
+
+  /**
+   * 清理项目路径
+   * @param {string} projectPath - 项目路径
+   * @returns {string} 清理后的项目路径
+   */
+  static sanitizeProjectPath(projectPath) {
+    if (typeof projectPath !== 'string') {
+      throw new Error('项目路径必须是字符串');
+    }
+
+    // 防止路径遍历攻击
+    if (projectPath.includes('..')) {
+      throw new Error('项目路径不能包含 ..');
+    }
+
+    // Windows 路径长度限制
+    if (projectPath.length > 260) {
+      throw new Error('项目路径过长');
+    }
+
+    return projectPath.trim();
+  }
+
+  /**
+   * 清理仓库 URL
+   * @param {string} repoUrl - 仓库地址
+   * @returns {string} 清理后的仓库地址
+   */
+  static sanitizeRepoUrl(repoUrl) {
+    if (typeof repoUrl !== 'string') {
+      throw new Error('仓库地址必须是字符串');
+    }
+
+    const trimmed = repoUrl.trim();
+
+    // 支持多种 Git 仓库地址格式：
+    // 1. HTTP/HTTPS: https://github.com/user/repo.git
+    // 2. Git 协议: git://github.com/user/repo.git
+    // 3. SSH (git@): git@github.com:user/repo.git
+    // 4. SSH (ssh://): ssh://git@github.com/user/repo.git
+    const patterns = [
+      /^https?:\/\/.+/i,           // HTTP/HTTPS
+      /^git:\/\/.+/i,              // Git 协议
+      /^git@[\w\.\-]+:.+/i,        // SSH git@
+      /^ssh:\/\/(git@)?[\w\.\-]+\/.+/i  // SSH ssh://
+    ];
+
+    const isValid = patterns.some(pattern => pattern.test(trimmed));
+
+    if (!isValid) {
+      throw new Error('无效的仓库地址格式，支持格式：https://、git://、git@ 或 ssh://');
+    }
+
+    return trimmed;
+  }
+
+  /**
+   * 验证 AI 引擎
+   * @param {string} engine - AI 引擎名称
+   * @returns {string} 验证后的引擎名称
+   */
+  static validateAIEngine(engine) {
+    const validEngines = ['claude-cli', 'zhipu', 'claude'];
+
+    if (engine && !validEngines.includes(engine)) {
+      throw new Error(`无效的 AI 引擎: ${engine}，支持的引擎: ${validEngines.join(', ')}`);
+    }
+
+    return engine;
+  }
+
+  /**
+   * 验证基准分支名称
+   * @param {string} branch - 分支名称
+   * @returns {string} 验证后的分支名称
+   */
+  static validateBranchName(branch) {
+    if (!branch) {
+      return null;
+    }
+
+    if (typeof branch !== 'string') {
+      throw new Error('分支名称必须是字符串');
+    }
+
+    // Git 分支名规则
+    const invalidPatterns = [
+      /\.\./,           // 不能包含 ..
+      /^[.-]/,          // 不能以 . 或 - 开头
+      /[\/.]$/,         // 不能以 / 或 . 结尾
+      /\/\//,           // 不能包含连续的 /
+      /[@{\\\^~:?*\[\]]/, // 不能包含特殊字符
+    ];
+
+    for (const pattern of invalidPatterns) {
+      if (pattern.test(branch)) {
+        throw new Error(`无效的分支名称: ${branch}`);
+      }
+    }
+
+    // 长度限制
+    if (branch.length > 255) {
+      throw new Error('分支名称过长，最多 255 字符');
+    }
+
+    return branch.trim();
+  }
+}
+
+module.exports = InputSanitizer;