hydro-ai-helper 1.8.5

package/src/lib/crypto.ts

@@ -0,0 +1,125 @@
+/**
+ * Crypto 加解密工具
+ *
+ * 使用 AES-256-GCM 加密 API Key 等敏感信息
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes, createHash } from 'crypto';
+
+/**
+ * 加密密钥(32 字节)
+ * 从环境变量读取，若不存在则使用默认值(仅开发环境)
+ */
+function getEncryptionKey(): Buffer {
+  const keyRaw = process.env.ENCRYPTION_KEY || 'dev-encryption-key-please-change-me-32';
+
+  // 如果环境变量不存在，打印警告(但不打印密钥本身)
+  if (!process.env.ENCRYPTION_KEY) {
+    console.warn('[Crypto] ⚠️  ENCRYPTION_KEY 环境变量未设置，使用默认密钥(仅开发环境)');
+    console.warn('[Crypto] ⚠️  生产环境请务必设置 ENCRYPTION_KEY 环境变量！');
+  }
+
+  // 使用 SHA-256 哈希生成固定 32 字节密钥
+  return createHash('sha256').update(keyRaw).digest();
+}
+
+const ENCRYPTION_KEY = getEncryptionKey();
+const ALGORITHM = 'aes-256-gcm';
+const IV_LENGTH = 12;        // GCM 推荐 12 字节 IV
+const AUTH_TAG_LENGTH = 16;  // GCM 认证标签长度
+
+/**
+ * 加密文本
+ * @param text 明文
+ * @returns Base64 编码的密文(包含 IV + AuthTag + Encrypted)
+ */
+export function encrypt(text: string): string {
+  if (!text) {
+    throw new Error('加密失败：输入文本不能为空');
+  }
+
+  try {
+    // 生成随机 IV
+    const iv = randomBytes(IV_LENGTH);
+
+    // 创建加密器
+    const cipher = createCipheriv(ALGORITHM, ENCRYPTION_KEY, iv);
+
+    // 加密数据
+    const encrypted = Buffer.concat([
+      cipher.update(text, 'utf8'),
+      cipher.final()
+    ]);
+
+    // 获取认证标签
+    const authTag = cipher.getAuthTag();
+
+    // 拼接: IV(12) + AuthTag(16) + Encrypted(N)
+    const combined = Buffer.concat([iv, authTag, encrypted]);
+
+    // 返回 Base64 编码
+    return combined.toString('base64');
+  } catch (error) {
+    throw new Error(`加密失败: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * 解密文本
+ * @param cipherText Base64 编码的密文
+ * @returns 解密后的明文
+ */
+export function decrypt(cipherText: string): string {
+  if (!cipherText) {
+    throw new Error('解密失败：输入密文不能为空');
+  }
+
+  try {
+    // 解码 Base64
+    const combined = Buffer.from(cipherText, 'base64');
+
+    // 分离 IV + AuthTag + Encrypted
+    const iv = combined.subarray(0, IV_LENGTH);
+    const authTag = combined.subarray(IV_LENGTH, IV_LENGTH + AUTH_TAG_LENGTH);
+    const encrypted = combined.subarray(IV_LENGTH + AUTH_TAG_LENGTH);
+
+    // 创建解密器
+    const decipher = createDecipheriv(ALGORITHM, ENCRYPTION_KEY, iv);
+    decipher.setAuthTag(authTag);
+
+    // 解密数据
+    const decrypted = Buffer.concat([
+      decipher.update(encrypted),
+      decipher.final()
+    ]);
+
+    return decrypted.toString('utf8');
+  } catch (error) {
+    // 解密失败可能是密钥错误或数据损坏
+    throw new Error(`解密失败: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * API Key 脱敏显示
+ * @param apiKeyPlain 明文 API Key
+ * @returns 脱敏后的字符串(如 "sk-12****abcd")
+ */
+export function maskApiKey(apiKeyPlain: string): string {
+  if (!apiKeyPlain) {
+    return '';
+  }
+
+  const len = apiKeyPlain.length;
+
+  // 如果长度 <= 8，简单返回 ****
+  if (len <= 8) {
+    return '****';
+  }
+
+  // 保留前 4 和后 4 位，中间用 **** 替换
+  const start = apiKeyPlain.slice(0, 4);
+  const end = apiKeyPlain.slice(-4);
+
+  return `${start}****${end}`;
+}

package/src/lib/httpHelpers.ts

@@ -0,0 +1,75 @@
+/**
+ * HTTP 响应工具函数
+ * 提供统一的响应格式和错误处理
+ *
+ * @module lib/httpHelpers
+ */
+
+import type { Handler } from 'hydrooj';
+
+/**
+ * 标准错误响应接口
+ */
+export interface ErrorResponse {
+  error: {
+    code: string;
+    message: string;
+  };
+}
+
+/**
+ * 设置 JSON 响应
+ * 统一设置响应类型和状态码
+ *
+ * @param handler Handler 实例
+ * @param data 响应数据
+ * @param status HTTP 状态码,默认 200
+ */
+export function setJsonResponse(handler: Handler, data: unknown, status: number = 200): void {
+  handler.response.status = status;
+  handler.response.body = data;
+  handler.response.type = 'application/json';
+}
+
+/**
+ * 设置错误响应
+ * 统一的错误响应格式
+ *
+ * @param handler Handler 实例
+ * @param code 错误代码,如 'INVALID_INPUT'
+ * @param message 错误信息
+ * @param status HTTP 状态码,默认 400
+ */
+export function setErrorResponse(
+  handler: Handler,
+  code: string,
+  message: string,
+  status: number = 400
+): void {
+  setJsonResponse(handler, { error: { code, message } }, status);
+}
+
+/**
+ * 设置模板响应(HTML 页面)
+ * 统一设置模板和数据
+ *
+ * @param handler Handler 实例
+ * @param template 模板路径
+ * @param data 模板数据
+ */
+export function setTemplateResponse(handler: Handler, template: string, data: unknown = {}): void {
+  handler.response.template = template;
+  handler.response.body = data;
+}
+
+/**
+ * 判断请求是否期望 JSON 响应
+ * 根据 Accept 头部判断
+ *
+ * @param handler Handler 实例
+ * @returns 是否期望 JSON
+ */
+export function expectsJson(handler: Handler): boolean {
+  const accept = handler.request.headers.accept || '';
+  return accept.includes('application/json');
+}

package/src/lib/queryHelpers.ts

@@ -0,0 +1,108 @@
+/**
+ * 查询参数解析工具
+ * 提供统一的查询参数解析和验证
+ *
+ * @module lib/queryHelpers
+ */
+
+/**
+ * 分页参数接口
+ */
+export interface PaginationParams {
+  page: number;
+  limit: number;
+}
+
+/**
+ * 日期范围参数接口
+ */
+export interface DateRangeParams {
+  startDate?: Date;
+  endDate?: Date;
+}
+
+/**
+ * 解析分页参数
+ * 从查询参数中提取并验证分页参数
+ *
+ * @param pageStr 页码字符串,默认 '1'
+ * @param limitStr 每页数量字符串,默认 '50'
+ * @param maxLimit 最大每页数量,默认 100
+ * @returns 解析后的分页参数
+ */
+export function parsePaginationParams(
+  pageStr: string = '1',
+  limitStr: string = '50',
+  maxLimit: number = 100
+): PaginationParams {
+  const page = Math.max(1, parseInt(pageStr, 10) || 1);
+  const limit = Math.min(maxLimit, Math.max(1, parseInt(limitStr, 10) || 50));
+
+  return { page, limit };
+}
+
+/**
+ * 解析日期范围参数
+ * 从查询参数中提取并验证日期范围
+ *
+ * @param startDateStr 开始日期字符串 (ISO 8601 格式)
+ * @param endDateStr 结束日期字符串 (ISO 8601 格式)
+ * @returns 解析后的日期范围参数
+ */
+export function parseDateRangeParams(
+  startDateStr?: string,
+  endDateStr?: string
+): DateRangeParams {
+  const result: DateRangeParams = {};
+
+  if (startDateStr) {
+    try {
+      const date = new Date(startDateStr);
+      if (!isNaN(date.getTime())) {
+        result.startDate = date;
+      }
+    } catch (err) {
+      // 忽略无效日期
+      console.error('[queryHelpers] Invalid startDate:', startDateStr);
+    }
+  }
+
+  if (endDateStr) {
+    try {
+      const date = new Date(endDateStr);
+      if (!isNaN(date.getTime())) {
+        result.endDate = date;
+      }
+    } catch (err) {
+      // 忽略无效日期
+      console.error('[queryHelpers] Invalid endDate:', endDateStr);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * 构建筛选条件对象
+ * 从查询参数中构建筛选条件,过滤掉空值
+ *
+ * @param params 原始查询参数对象
+ * @param allowedFields 允许的字段列表
+ * @returns 筛选条件对象
+ */
+export function buildFilters<T extends Record<string, unknown>>(
+  params: Record<string, unknown>,
+  allowedFields: string[]
+): Partial<T> {
+  const filters: Partial<T> = {};
+
+  for (const field of allowedFields) {
+    const value = params[field];
+    if (value !== undefined && value !== null && value !== '') {
+      // @ts-expect-error - 动态字段赋值
+      filters[field] = value;
+    }
+  }
+
+  return filters;
+}

package/src/models/aiConfig.ts

@@ -0,0 +1,375 @@
+/**
+ * AI Config Model - AI 服务配置数据模型
+ *
+ * 管理全局 AI 服务配置(API Key、模型名称等)
+ * 约定：数据库中最多只有一条配置记录(固定 ID = 'default')
+ *
+ * v2 新增：支持多 API 端点配置、模型自动获取、Fallback 机制
+ */
+
+import type { Db, Collection } from 'mongodb';
+import { randomUUID } from 'crypto';
+
+/** 当前配置版本号 */
+export const CURRENT_CONFIG_VERSION = 2;
+
+/**
+ * API 端点配置
+ */
+export interface APIEndpoint {
+  id: string;                   // 唯一标识 (UUID)
+  name: string;                 // 显示名称
+  apiBaseUrl: string;           // API Base URL
+  apiKeyEncrypted: string;      // 加密后的 API Key
+  models: string[];             // 可用模型列表
+  modelsLastFetched?: Date;     // 模型列表最后获取时间
+  enabled: boolean;             // 是否启用
+}
+
+/**
+ * 选中的模型（按 fallback 顺序排列）
+ */
+export interface SelectedModel {
+  endpointId: string;           // 端点 ID
+  modelName: string;            // 模型名称
+}
+
+/**
+ * AI 配置接口 (v2)
+ */
+export interface AIConfig {
+  _id: string;                  // 固定为 'default'
+  configVersion: number;        // 配置版本号，用于迁移检测
+  endpoints: APIEndpoint[];     // API 端点列表
+  selectedModels: SelectedModel[]; // 选中的模型（��� fallback 顺序）
+  rateLimitPerMinute: number;   // 频率限制(每分钟最大请求数)
+  timeoutSeconds: number;       // 超时时间(秒)
+  systemPromptTemplate?: string; // 系统提示词模板(可选)
+  extraJailbreakPatternsText?: string; // 自定义越狱规则(多行文本)
+  updatedAt: Date;              // 最后更新时间
+  // 保留旧字段用于向后兼容（迁移完成后可能为空）
+  apiBaseUrl?: string;
+  modelName?: string;
+  apiKeyEncrypted?: string;
+}
+
+/**
+ * 旧版配置接口（用于迁移检测）
+ */
+interface LegacyAIConfig {
+  _id: string;
+  apiBaseUrl: string;
+  modelName: string;
+  apiKeyEncrypted: string;
+  rateLimitPerMinute: number;
+  timeoutSeconds: number;
+  systemPromptTemplate?: string;
+  extraJailbreakPatternsText?: string;
+  updatedAt: Date;
+  configVersion?: number;
+  endpoints?: APIEndpoint[];
+  selectedModels?: SelectedModel[];
+}
+
+/**
+ * AI Config Model 操作类
+ * 封装 AI 配置的 CRUD 操作
+ */
+export class AIConfigModel {
+  private collection: Collection<AIConfig>;
+  private readonly FIXED_ID = 'default'; // 固定配置记录 ID
+
+  constructor(db: Db) {
+    this.collection = db.collection<AIConfig>('ai_config');
+  }
+
+  /**
+   * 确保索引已创建
+   * (单条记录无需复杂索引，仅用于一致性)
+   */
+  async ensureIndexes(): Promise<void> {
+    // 创建 _id 索引(MongoDB 自动创建，此处仅占位)
+    console.log('[AIConfigModel] Collection initialized');
+  }
+
+  /**
+   * 获取当前配置（自动执行懒迁移）
+   * @returns 配置对象或 null(若尚未配置)
+   */
+  async getConfig(): Promise<AIConfig | null> {
+    const rawConfig = await this.collection.findOne({ _id: this.FIXED_ID });
+
+    if (!rawConfig) {
+      return null;
+    }
+
+    // 懒迁移：检测并迁移旧版配置
+    if (this.needsMigration(rawConfig as unknown as LegacyAIConfig)) {
+      const migratedConfig = this.migrateFromLegacy(rawConfig as unknown as LegacyAIConfig);
+      // 持久化迁移后的配置
+      await this.collection.updateOne(
+        { _id: this.FIXED_ID },
+        { $set: migratedConfig }
+      );
+      return migratedConfig;
+    }
+
+    return rawConfig;
+  }
+
+  /**
+   * 检测是否需要迁移
+   */
+  private needsMigration(config: LegacyAIConfig): boolean {
+    // 无 configVersion 或版本低于当前版本需要迁移
+    return !config.configVersion || config.configVersion < CURRENT_CONFIG_VERSION;
+  }
+
+  /**
+   * 从旧版配置迁移到新版
+   */
+  private migrateFromLegacy(legacy: LegacyAIConfig): AIConfig {
+    console.log('[AIConfigModel] Migrating from legacy config to v2...');
+
+    // 如果已有 endpoints，规范化并保留现有数据
+    if (legacy.endpoints && legacy.endpoints.length > 0) {
+      const normalizedEndpoints = legacy.endpoints.map((endpoint, index) => ({
+        id: endpoint.id || randomUUID(),
+        name: endpoint.name || `端点 ${index + 1}`,
+        apiBaseUrl: endpoint.apiBaseUrl || legacy.apiBaseUrl || '',
+        apiKeyEncrypted: endpoint.apiKeyEncrypted || legacy.apiKeyEncrypted || '',
+        models: Array.isArray(endpoint.models) ? endpoint.models : [],
+        modelsLastFetched: endpoint.modelsLastFetched,
+        enabled: endpoint.enabled !== false,
+      }));
+
+      const endpointIds = new Set(normalizedEndpoints.map(ep => ep.id));
+      let selectedModels = (legacy.selectedModels || []).filter(sm => endpointIds.has(sm.endpointId));
+
+      // 如果没有有效的 selectedModels，尝试从旧配置或端点模型列表推导
+      if (selectedModels.length === 0) {
+        if (legacy.modelName && normalizedEndpoints[0]) {
+          selectedModels = [{ endpointId: normalizedEndpoints[0].id, modelName: legacy.modelName }];
+        } else {
+          selectedModels = normalizedEndpoints
+            .filter(ep => ep.models.length > 0)
+            .map(ep => ({ endpointId: ep.id, modelName: ep.models[0] }));
+        }
+      }
+
+      return {
+        ...legacy,
+        configVersion: CURRENT_CONFIG_VERSION,
+        endpoints: normalizedEndpoints,
+        selectedModels,
+      } as AIConfig;
+    }
+
+    // 从旧字段创建默认端点
+    const defaultEndpoint: APIEndpoint = {
+      id: randomUUID(),
+      name: '默认端点',
+      apiBaseUrl: legacy.apiBaseUrl || '',
+      apiKeyEncrypted: legacy.apiKeyEncrypted || '',
+      models: legacy.modelName ? [legacy.modelName] : [],
+      modelsLastFetched: undefined,
+      enabled: true,
+    };
+
+    // 创建默认选中模型
+    const selectedModels: SelectedModel[] = legacy.modelName
+      ? [{ endpointId: defaultEndpoint.id, modelName: legacy.modelName }]
+      : [];
+
+    const migratedConfig: AIConfig = {
+      _id: legacy._id,
+      configVersion: CURRENT_CONFIG_VERSION,
+      endpoints: legacy.apiBaseUrl ? [defaultEndpoint] : [],
+      selectedModels,
+      rateLimitPerMinute: legacy.rateLimitPerMinute,
+      timeoutSeconds: legacy.timeoutSeconds,
+      systemPromptTemplate: legacy.systemPromptTemplate,
+      extraJailbreakPatternsText: legacy.extraJailbreakPatternsText,
+      updatedAt: legacy.updatedAt,
+      // 保留旧字段便于回滚
+      apiBaseUrl: legacy.apiBaseUrl,
+      modelName: legacy.modelName,
+      apiKeyEncrypted: legacy.apiKeyEncrypted,
+    };
+
+    console.log('[AIConfigModel] Migration complete. Created endpoint:', defaultEndpoint.id);
+    return migratedConfig;
+  }
+
+  /**
+   * 更新配置(若不存在则创建)
+   * @param partial 要更新的配置字段(部分更新)
+   * @returns 更新后的配置对象
+   */
+  async updateConfig(partial: Partial<Omit<AIConfig, '_id' | 'updatedAt'>>): Promise<AIConfig> {
+    const now = new Date();
+
+    // 确保 configVersion 为最新
+    const updateData = {
+      ...partial,
+      configVersion: CURRENT_CONFIG_VERSION,
+      updatedAt: now
+    };
+
+    // 使用 upsert 更新或创建配置
+    await this.collection.updateOne(
+      { _id: this.FIXED_ID },
+      { $set: updateData },
+      { upsert: true }
+    );
+
+    // 查询更新后的配置
+    const config = await this.collection.findOne({ _id: this.FIXED_ID });
+
+    if (!config) {
+      throw new Error('配置更新失败：无法读取更新后的配置');
+    }
+
+    return config;
+  }
+
+  /**
+   * 添加新端点
+   */
+  async addEndpoint(endpoint: Omit<APIEndpoint, 'id'>): Promise<APIEndpoint> {
+    const config = await this.getConfig();
+    const newEndpoint: APIEndpoint = {
+      ...endpoint,
+      id: randomUUID(),
+    };
+
+    const endpoints = config?.endpoints || [];
+    endpoints.push(newEndpoint);
+
+    await this.updateConfig({ endpoints });
+    return newEndpoint;
+  }
+
+  /**
+   * 更新端点
+   */
+  async updateEndpoint(endpointId: string, updates: Partial<Omit<APIEndpoint, 'id'>>): Promise<void> {
+    const config = await this.getConfig();
+    if (!config) {
+      throw new Error('配置不存在');
+    }
+
+    const endpoints = config.endpoints.map(ep =>
+      ep.id === endpointId ? { ...ep, ...updates } : ep
+    );
+
+    await this.updateConfig({ endpoints });
+  }
+
+  /**
+   * 删除端点
+   */
+  async deleteEndpoint(endpointId: string): Promise<void> {
+    const config = await this.getConfig();
+    if (!config) {
+      throw new Error('配置不存在');
+    }
+
+    const endpoints = config.endpoints.filter(ep => ep.id !== endpointId);
+    // 同时移除引用该端点的 selectedModels
+    const selectedModels = config.selectedModels.filter(sm => sm.endpointId !== endpointId);
+
+    await this.updateConfig({ endpoints, selectedModels });
+  }
+
+  /**
+   * 更新选中的模型列表
+   */
+  async updateSelectedModels(selectedModels: SelectedModel[]): Promise<void> {
+    await this.updateConfig({ selectedModels });
+  }
+
+  /**
+   * 根据端点 ID 获取端点配置
+   */
+  async getEndpointById(endpointId: string): Promise<APIEndpoint | null> {
+    const config = await this.getConfig();
+    if (!config) {
+      return null;
+    }
+    return config.endpoints.find(ep => ep.id === endpointId) || null;
+  }
+
+  /**
+   * 删除配置(用于测试或重置)
+   */
+  async deleteConfig(): Promise<void> {
+    await this.collection.deleteOne({ _id: this.FIXED_ID });
+  }
+
+  /**
+   * 初始化默认配置(若不存在)
+   * @param defaults 默认配置值
+   */
+  async initializeDefaultConfig(defaults: Omit<AIConfig, '_id' | 'updatedAt' | 'configVersion' | 'endpoints' | 'selectedModels'>): Promise<void> {
+    const existing = await this.getConfig();
+
+    if (!existing) {
+      await this.collection.insertOne({
+        _id: this.FIXED_ID,
+        configVersion: CURRENT_CONFIG_VERSION,
+        endpoints: [],
+        selectedModels: [],
+        ...defaults,
+        updatedAt: new Date()
+      } as AIConfig);
+
+      console.log('[AIConfigModel] Default config initialized');
+    } else {
+      console.log('[AIConfigModel] Config already exists, skipping initialization');
+    }
+  }
+
+  /**
+   * 获取解析后的模型配置（用于 MultiModelClient）
+   * 返回按 fallback 顺序排列的完整模型配置
+   */
+  async getResolvedModelConfigs(): Promise<Array<{
+    endpointId: string;
+    endpointName: string;
+    apiBaseUrl: string;
+    apiKeyEncrypted: string;
+    modelName: string;
+    timeoutSeconds: number;
+  }>> {
+    const config = await this.getConfig();
+    if (!config) {
+      return [];
+    }
+
+    const results: Array<{
+      endpointId: string;
+      endpointName: string;
+      apiBaseUrl: string;
+      apiKeyEncrypted: string;
+      modelName: string;
+      timeoutSeconds: number;
+    }> = [];
+
+    for (const selected of config.selectedModels) {
+      const endpoint = config.endpoints.find(ep => ep.id === selected.endpointId);
+      if (endpoint && endpoint.enabled !== false) {
+        results.push({
+          endpointId: endpoint.id,
+          endpointName: endpoint.name,
+          apiBaseUrl: endpoint.apiBaseUrl,
+          apiKeyEncrypted: endpoint.apiKeyEncrypted,
+          modelName: selected.modelName,
+          timeoutSeconds: config.timeoutSeconds,
+        });
+      }
+    }
+
+    return results;
+  }
+}