hydro-ai-helper 1.8.5

package/src/models/pluginInstall.ts

@@ -0,0 +1,138 @@
+/**
+ * PluginInstall Model - 插件安装与遥测数据模型
+ *
+ * 用于记录插件安装信息和遥测配置
+ */
+
+import type { Db, Collection } from 'mongodb';
+import { randomUUID } from 'crypto';
+
+/**
+ * 插件安装记录接口
+ */
+export interface PluginInstall {
+  _id: string;              // 固定为 'install'
+  instanceId: string;       // 随机 UUID，用于去重
+  installedAt: Date;        // 首次启动时间
+  firstUsedAt?: Date;       // 首次 AI 对话时间
+  lastUsedAt?: Date;        // 最近使用时间
+  installedVersion: string; // 安装时的版本号
+  lastVersion: string;      // 当前运行版本
+  domainsSeen: string[];    // 见过的 domainId 列表
+  telemetryEnabled: boolean;// 是否允许远程上报（默认 true）
+  lastReportAt?: Date;      // 最后一次上报时间
+}
+
+/**
+ * PluginInstall Model 操作类
+ * 封装插件安装记录的 CRUD 操作
+ */
+export class PluginInstallModel {
+  private collection: Collection<PluginInstall>;
+  private readonly FIXED_ID = 'install'; // 固定记录 ID
+
+  constructor(db: Db) {
+    this.collection = db.collection<PluginInstall>('ai_plugin_install');
+  }
+
+  /**
+   * 确保索引已创建
+   * (单条记录无需复杂索引，仅用于一致性)
+   */
+  async ensureIndexes(): Promise<void> {
+    console.log('[PluginInstallModel] Collection initialized');
+  }
+
+  /**
+   * 获取安装记录
+   * @returns 安装记录或 null
+   */
+  async getInstall(): Promise<PluginInstall | null> {
+    return this.collection.findOne({ _id: this.FIXED_ID });
+  }
+
+  /**
+   * 创建安装记录（如果不存在）
+   * @param version 当前版本号
+   */
+  async createIfMissing(version: string): Promise<void> {
+    const existing = await this.getInstall();
+
+    if (!existing) {
+      const now = new Date();
+      await this.collection.insertOne({
+        _id: this.FIXED_ID,
+        instanceId: randomUUID(),
+        installedAt: now,
+        installedVersion: version,
+        lastVersion: version,
+        domainsSeen: [],
+        telemetryEnabled: true
+      } as PluginInstall);
+
+      console.log('[PluginInstallModel] Install record created');
+    } else {
+      // 更新版本号
+      await this.collection.updateOne(
+        { _id: this.FIXED_ID },
+        { $set: { lastVersion: version } }
+      );
+      console.log('[PluginInstallModel] Install record already exists, version updated');
+    }
+  }
+
+  /**
+   * 标记首次使用时间
+   */
+  async markFirstUse(): Promise<void> {
+    const existing = await this.getInstall();
+    if (existing && !existing.firstUsedAt) {
+      await this.collection.updateOne(
+        { _id: this.FIXED_ID },
+        { $set: { firstUsedAt: new Date() } }
+      );
+    }
+  }
+
+  /**
+   * 更新最近使用时间
+   */
+  async markLastUse(): Promise<void> {
+    await this.collection.updateOne(
+      { _id: this.FIXED_ID },
+      { $set: { lastUsedAt: new Date() } }
+    );
+  }
+
+  /**
+   * 添加 domainId（如果不存在）
+   * @param domainId 域 ID
+   */
+  async addDomain(domainId: string): Promise<void> {
+    await this.collection.updateOne(
+      { _id: this.FIXED_ID },
+      { $addToSet: { domainsSeen: domainId } }
+    );
+  }
+
+  /**
+   * 更新最后上报时间
+   */
+  async updateLastReportTime(): Promise<void> {
+    await this.collection.updateOne(
+      { _id: this.FIXED_ID },
+      { $set: { lastReportAt: new Date() } }
+    );
+  }
+
+  /**
+   * 更新遥测开关
+   * @param enabled 是否启用
+   */
+  async updateTelemetryEnabled(enabled: boolean): Promise<void> {
+    await this.collection.updateOne(
+      { _id: this.FIXED_ID },
+      { $set: { telemetryEnabled: enabled } }
+    );
+  }
+}

package/src/models/rateLimitRecord.ts

@@ -0,0 +1,81 @@
+/**
+ * RateLimitRecord Model - 频率限制记录数据模型
+ *
+ * 用于记录每个用户每分钟的请求次数，并通过 TTL 自动清理
+ */
+
+import type { Db, Collection } from 'mongodb';
+import { type ObjectIdType } from '../utils/mongo';
+
+/**
+ * 频率限制记录接口
+ */
+export interface RateLimitRecord {
+  _id?: ObjectIdType;       // MongoDB ObjectId
+  domainId: string;         // 域 ID (用于多租户隔离)
+  userId: number;           // 用户 ID（与 HydroOJ 用户系统保持一致）
+  minuteKey: string;        // 形如 "2025-11-18T09:32" 的分钟粒度时间键
+  count: number;            // 当前分钟内已请求次数
+  expireAt: Date;           // TTL 过期时间（通常为当前分钟结束后略多一些）
+}
+
+/**
+ * RateLimitRecord Model 操作类
+ * 封装频率限制记录的操作
+ */
+export class RateLimitRecordModel {
+  private collection: Collection<RateLimitRecord>;
+
+  constructor(db: Db) {
+    this.collection = db.collection<RateLimitRecord>('ai_rate_limit_records');
+  }
+
+  /**
+   * 确保索引已创建
+   * 创建 TTL 索引，自动清理过期记录
+   */
+  async ensureIndexes(): Promise<void> {
+    // 创建 TTL 索引：expireAt 字段，过期后自动删除
+    await this.collection.createIndex(
+      { expireAt: 1 },
+      {
+        name: 'idx_expireAt_ttl',
+        expireAfterSeconds: 0  // 到达 expireAt 时间后立即删除
+      }
+    );
+
+    // 创建复合唯一索引：domainId + userId + minuteKey（确保每个域内每个用户每分钟只有一条记录）
+    await this.collection.createIndex(
+      { domainId: 1, userId: 1, minuteKey: 1 },
+      {
+        name: 'idx_domainId_userId_minuteKey',
+        unique: true
+      }
+    );
+
+    // 创建索引: 域 ID (用于域隔离查询)
+    await this.collection.createIndex(
+      { domainId: 1 },
+      { name: 'idx_domainId' }
+    );
+
+    console.log('[RateLimitRecordModel] Indexes created successfully');
+  }
+
+  /**
+   * 获取集合对象（供 RateLimitService 使用）
+   * @returns MongoDB Collection
+   */
+  getCollection(): Collection<RateLimitRecord> {
+    return this.collection;
+  }
+}
+
+/**
+ * 工厂函数：获取频率限制记录集合
+ * @param db MongoDB Database 对象
+ * @returns Collection<RateLimitRecord>
+ */
+export function getRateLimitCollection(db: Db): Collection<RateLimitRecord> {
+  return db.collection<RateLimitRecord>('ai_rate_limit_records');
+}

package/src/models/versionCache.ts

@@ -0,0 +1,127 @@
+/**
+ * VersionCache Model - 版本缓存数据模型
+ *
+ * 用于缓存从 Gitee 获取的最新版本信息，避免频繁请求外部 API
+ * 缓存有效期为 24 小时
+ */
+
+import type { Db, Collection } from 'mongodb';
+import { type ObjectIdType } from '../utils/mongo';
+
+/**
+ * 版本缓存记录接口
+ */
+export interface VersionCache {
+  _id?: ObjectIdType;          // MongoDB ObjectId
+  key: string;                 // 缓存键（如 'latest_version'）
+  currentVersion: string;      // 当前安装版本
+  latestVersion: string;       // 远程最新版本
+  releaseUrl?: string;         // 发布页面 URL
+  releaseNotes?: string;       // 版本更新说明
+  hasUpdate: boolean;          // 是否有可用更新
+  checkedAt: Date;             // 检查时间
+  expireAt: Date;              // 缓存过期时间（用于 TTL）
+}
+
+/**
+ * 缓存有效期：24 小时（毫秒）
+ */
+export const VERSION_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * VersionCache Model 操作类
+ * 封装版本缓存的 CRUD 操作
+ */
+export class VersionCacheModel {
+  private collection: Collection<VersionCache>;
+
+  constructor(db: Db) {
+    this.collection = db.collection<VersionCache>('ai_version_cache');
+  }
+
+  /**
+   * 确保索引已创建
+   * 创建 TTL 索引，自动清理过期记录
+   */
+  async ensureIndexes(): Promise<void> {
+    // 创建 TTL 索引：expireAt 字段，过期后自动删除
+    await this.collection.createIndex(
+      { expireAt: 1 },
+      {
+        name: 'idx_expireAt_ttl',
+        expireAfterSeconds: 0  // 到达 expireAt 时间后立即删除
+      }
+    );
+
+    // 创建唯一索引：key 字段
+    await this.collection.createIndex(
+      { key: 1 },
+      {
+        name: 'idx_key',
+        unique: true
+      }
+    );
+
+    console.log('[VersionCacheModel] Indexes created successfully');
+  }
+
+  /**
+   * 获取缓存的版本信息
+   * @param key 缓存键
+   * @returns 版本缓存记录或 null（不存在或已过期）
+   */
+  async get(key: string): Promise<VersionCache | null> {
+    const cache = await this.collection.findOne({ key });
+
+    // 如果缓存存在但已过期，返回 null
+    if (cache && cache.expireAt < new Date()) {
+      return null;
+    }
+
+    return cache;
+  }
+
+  /**
+   * 设置版本缓存
+   * @param data 版本缓存数据
+   */
+  async set(data: Omit<VersionCache, '_id' | 'expireAt'>): Promise<void> {
+    const now = new Date();
+    const expireAt = new Date(now.getTime() + VERSION_CACHE_TTL_MS);
+
+    await this.collection.updateOne(
+      { key: data.key },
+      {
+        $set: {
+          ...data,
+          checkedAt: now,
+          expireAt
+        }
+      },
+      { upsert: true }
+    );
+  }
+
+  /**
+   * 删除指定缓存
+   * @param key 缓存键
+   */
+  async delete(key: string): Promise<void> {
+    await this.collection.deleteOne({ key });
+  }
+
+  /**
+   * 清除所有缓存
+   */
+  async clear(): Promise<void> {
+    await this.collection.deleteMany({});
+  }
+
+  /**
+   * 获取集合对象
+   * @returns MongoDB Collection
+   */
+  getCollection(): Collection<VersionCache> {
+    return this.collection;
+  }
+}

package/src/services/effectivenessService.ts

@@ -0,0 +1,161 @@
+/**
+ * EffectivenessService - 有效对话判定服务
+ *
+ * 根据规则判定会话是否为「有效对话」，并更新数据库
+ */
+
+import type { Context } from 'hydrooj';
+import { ObjectId, type ObjectIdType } from '../utils/mongo';
+import type { MessageModel } from '../models/message';
+import type { ConversationModel } from '../models/conversation';
+import type { JailbreakLogModel } from '../models/jailbreakLog';
+import type { QuestionType } from './promptService';
+
+/**
+ * 有效对话判定规则
+ */
+const EFFECTIVENESS_RULES = {
+  // 最小消息数量要求
+  MIN_STUDENT_MESSAGES: 2,
+  MIN_AI_MESSAGES: 2,
+
+  // 学生消息平均长度要求（字符数）
+  MIN_STUDENT_AVG_LENGTH: 20,
+
+  // 学习相关关键词（至少匹配一个）
+  LEARNING_KEYWORDS: [
+    '理解', '思路', '算法', '复杂度', '优化', '错误', '调试'
+  ]
+};
+
+/**
+ * EffectivenessService 类
+ * 负责分析会话并判定是否为有效对话
+ */
+export class EffectivenessService {
+  private ctx: Context;
+
+  constructor(ctx: Context) {
+    this.ctx = ctx;
+  }
+
+  /**
+   * 分析会话并判定是否为有效对话
+   *
+   * @param conversationId 会话 ID（字符串或 ObjectId）
+   * @returns boolean - 是否为有效对话
+   */
+  async analyzeConversation(conversationId: string | ObjectIdType): Promise<boolean> {
+    try {
+      // 获取模型实例
+      const messageModel: MessageModel = this.ctx.get('messageModel');
+      const conversationModel: ConversationModel = this.ctx.get('conversationModel');
+
+      // 转换为 ObjectId
+      const convObjectId = typeof conversationId === 'string'
+        ? new ObjectId(conversationId)
+        : conversationId;
+
+      // 从数据库读取所有消息（按时间升序）
+      const messages = await messageModel.findByConversationId(convObjectId);
+
+      if (!messages.length) {
+        // 没有消息，标记为无效
+        await conversationModel.updateEffectiveness(convObjectId, false);
+        return false;
+      }
+
+      // 1. 按 role 划分学生/AI 消息
+      const studentMessages = messages.filter(msg => msg.role === 'student');
+      const aiMessages = messages.filter(msg => msg.role === 'ai');
+
+      // 2. 检查消息数量要求
+      const hasEnoughStudentMessages = studentMessages.length >= EFFECTIVENESS_RULES.MIN_STUDENT_MESSAGES;
+      const hasEnoughAiMessages = aiMessages.length >= EFFECTIVENESS_RULES.MIN_AI_MESSAGES;
+
+      if (!hasEnoughStudentMessages || !hasEnoughAiMessages) {
+        // 消息数量不足，标记为无效
+        await conversationModel.updateEffectiveness(convObjectId, false);
+        return false;
+      }
+
+      // 3. 计算学生消息平均长度
+      const totalStudentLength = studentMessages.reduce((sum, msg) => sum + msg.content.length, 0);
+      const avgStudentLength = totalStudentLength / studentMessages.length;
+
+      if (avgStudentLength <= EFFECTIVENESS_RULES.MIN_STUDENT_AVG_LENGTH) {
+        // 平均长度不足，标记为无效
+        await conversationModel.updateEffectiveness(convObjectId, false);
+        return false;
+      }
+
+      // 4. 检查关键词命中情况
+      const hasLearningKeyword = studentMessages.some(msg => {
+        const content = msg.content;
+        return EFFECTIVENESS_RULES.LEARNING_KEYWORDS.some(keyword => content.includes(keyword));
+      });
+
+      if (!hasLearningKeyword) {
+        // 未命中任何学习关键词，标记为无效
+        await conversationModel.updateEffectiveness(convObjectId, false);
+        return false;
+      }
+
+      // 所有条件都满足，标记为有效
+      await conversationModel.updateEffectiveness(convObjectId, true);
+      return true;
+
+    } catch (err) {
+      // 记录错误日志，但不抛出异常（保守处理为 false）
+      this.ctx.logger.error('EffectivenessService analyzeConversation error', err);
+
+      // 出现错误时，尝试将会话标记为无效（如果可能）
+      try {
+        const conversationModel: ConversationModel = this.ctx.get('conversationModel');
+        const convObjectId = typeof conversationId === 'string'
+          ? new ObjectId(conversationId)
+          : conversationId;
+        await conversationModel.updateEffectiveness(convObjectId, false);
+      } catch (updateErr) {
+        this.ctx.logger.error('EffectivenessService updateEffectiveness error', updateErr);
+      }
+
+      return false;
+    }
+  }
+
+  /**
+   * 记录越狱尝试日志，供管理员分析
+   */
+  async logJailbreakAttempt(payload: {
+    userId?: number;
+    problemId?: string;
+    conversationId?: string | ObjectIdType;
+    questionType?: QuestionType;
+    matchedPattern: string;
+    matchedText: string;
+    createdAt?: Date;
+  }): Promise<void> {
+    try {
+      const jailbreakLogModel: JailbreakLogModel = this.ctx.get('jailbreakLogModel');
+      const formattedConversationId =
+        payload.conversationId === undefined
+          ? undefined
+          : typeof payload.conversationId === 'string'
+            ? new ObjectId(payload.conversationId)
+            : payload.conversationId;
+
+      await jailbreakLogModel.create({
+        userId: payload.userId,
+        problemId: payload.problemId,
+        conversationId: formattedConversationId,
+        questionType: payload.questionType,
+        matchedPattern: payload.matchedPattern,
+        matchedText: payload.matchedText,
+        createdAt: payload.createdAt ?? new Date()
+      });
+    } catch (err) {
+      this.ctx.logger.error('EffectivenessService logJailbreakAttempt error', err);
+    }
+  }
+}

package/src/services/exportService.ts

@@ -0,0 +1,191 @@
+/**
+ * Export Service - 数据导出服务
+ *
+ * 支持按筛选条件导出会话数据为 CSV 格式
+ */
+
+import type { Context } from 'hydrooj';
+import type { Collection, Filter } from 'mongodb';
+import { ConversationModel, Conversation } from '../models/conversation';
+
+/**
+ * 导出筛选条件接口
+ */
+export interface ConversationExportFilters {
+  domainId?: string;     // 域 ID (用于域隔离)
+  startDate?: Date;      // 开始日期 (会话 startTime >= startDate)
+  endDate?: Date;        // 结束日期 (会话 startTime <= endDate)
+  classId?: string;      // 班级 ID
+  problemId?: string;    // 题目 ID
+  userId?: string;       // 学生用户 ID (字符串类型,用于传递)
+}
+
+/**
+ * 导出选项接口
+ */
+export interface ConversationExportOptions {
+  includeSensitive?: boolean;  // 是否包含敏感信息(真实 userId),默认 false
+}
+
+/**
+ * ExportService 类
+ * 负责导出会话级数据为 CSV 字符串
+ */
+export class ExportService {
+  private conversationModel: ConversationModel;
+
+  constructor(private ctx: Context) {
+    this.conversationModel = ctx.get('conversationModel');
+  }
+
+  /**
+   * 导出会话列表为 CSV 字符串
+   *
+   * @param filters 筛选条件
+   * @param options 导出选项
+   * @returns CSV 字符串
+   */
+  async exportConversations(
+    filters: ConversationExportFilters,
+    options: ConversationExportOptions = {}
+  ): Promise<string> {
+    // 1. 构造查询条件
+    const query: Filter<Conversation> = {};
+    const projection: Partial<Record<keyof Conversation, 1 | 0>> = {
+      _id: 1,
+      userId: 1,
+      classId: 1,
+      problemId: 1,
+      startTime: 1,
+      endTime: 1,
+      messageCount: 1,
+      isEffective: 1,
+      teacherNote: 1,
+      tags: 1,
+      metadata: 1
+    };
+
+    // 域隔离：只导出当前域的数据
+    if (filters.domainId) {
+      query.domainId = filters.domainId;
+    }
+
+    // 时间范围筛选
+    if (filters.startDate || filters.endDate) {
+      query.startTime = {};
+      if (filters.startDate) {
+        query.startTime.$gte = filters.startDate;
+      }
+      if (filters.endDate) {
+        query.startTime.$lte = filters.endDate;
+      }
+    }
+
+    // 班级/题目/用户筛选
+    if (filters.classId) {
+      query.classId = filters.classId;
+    }
+    if (filters.problemId) {
+      query.problemId = filters.problemId;
+    }
+    if (filters.userId) {
+      query.userId = parseInt(filters.userId, 10); // 转换为 number
+    }
+
+    // 2. 查询所有符合条件的会话记录(按开始时间升序排序)
+    const collection = this.ctx.db.collection('ai_conversations') as unknown as Collection<Conversation>;
+    const cursor = collection
+      .find(query, { projection })
+      .sort({ startTime: 1 });
+
+    // 3. 脱敏逻辑(如果 includeSensitive=false)
+    const userIdMap = new Map<number, string>();
+    let userCounter = 1;
+
+    const getAnonymousId = (realUserId: number): string => {
+      if (options.includeSensitive) {
+        return realUserId.toString();
+      }
+      if (!userIdMap.has(realUserId)) {
+        const anonymousId = `user_${String(userCounter).padStart(3, '0')}`;
+        userIdMap.set(realUserId, anonymousId);
+        userCounter++;
+      }
+      // 安全断言: 上面的 if 语句确保了 userIdMap 中一定存在 realUserId
+      const anonymousId = userIdMap.get(realUserId);
+      return anonymousId as string;
+    };
+
+    // 4. 构建 CSV 数据
+    const rows: string[][] = [];
+
+    // 表头
+    const headers = [
+      'conversationId',
+      options.includeSensitive ? 'userId' : 'anonymousId',
+      'classId',
+      'problemId',
+      'problemTitle',
+      'startTime',
+      'endTime',
+      'messageCount',
+      'isEffective',
+      'teacherNote',
+      'tags'
+    ];
+    rows.push(headers);
+
+    // 数据行
+    for await (const conv of cursor) {
+      const row = [
+        conv._id.toString(),
+        getAnonymousId(conv.userId),
+        conv.classId || '',
+        conv.problemId || '',
+        conv.metadata?.problemTitle || '',
+        conv.startTime.toISOString(),
+        conv.endTime.toISOString(),
+        conv.messageCount.toString(),
+        conv.isEffective ? 'true' : 'false',
+        conv.teacherNote || '',
+        Array.isArray(conv.tags) ? conv.tags.join(';') : ''
+      ];
+      rows.push(row);
+    }
+
+    // 5. 转换为 CSV 字符串
+    return this.convertToCsv(rows);
+  }
+
+  /**
+   * 将二维数组转换为 CSV 字符串
+   *
+   * @param rows 二维数组,第一行为表头,后续为数据行
+   * @returns CSV 字符串
+   */
+  private convertToCsv(rows: string[][]): string {
+    return rows.map(row => row.map(this.escapeCsvField).join(',')).join('\n');
+  }
+
+  /**
+   * 转义 CSV 字段
+   * 如果字段包含逗号、双引号或换行,则用双引号包裹,并转义内部双引号
+   *
+   * @param value 字段值
+   * @returns 转义后的字符串
+   */
+  private escapeCsvField(value: unknown): string {
+    if (value === null || value === undefined) {
+      return '';
+    }
+
+    const str = String(value);
+
+    // 如果包含逗号、双引号或换行,则用双引号包裹
+    if (/[",\n]/.test(str)) {
+      return `"${str.replace(/"/g, '""')}"`;
+    }
+
+    return str;
+  }
+}