hydro-ai-helper 1.8.5

package/src/handlers/teacherHandler.ts

@@ -0,0 +1,317 @@
+/**
+ * 教师端 Handler
+ * 处理教师查看对话列表和详情的请求
+ */
+
+import { Handler, PRIV, db } from 'hydrooj';
+import { ConversationModel } from '../models/conversation';
+import { MessageModel } from '../models/message';
+import { ObjectId } from '../utils/mongo';
+import { setJsonResponse, setErrorResponse, setTemplateResponse, expectsJson } from '../lib/httpHelpers';
+import { parsePaginationParams } from '../lib/queryHelpers';
+import { getDomainId } from '../utils/domainHelper';
+import type { UserDocument } from '../types/hydrooj';
+
+/**
+ * 批量获取用户名映射
+ * @param uids 用户 ID 数组
+ * @returns uid -> uname 映射表
+ */
+async function getUserNameMap(uids: number[]): Promise<Map<number, string>> {
+  const uniqueUids = [...new Set(uids)];
+  const userMap = new Map<number, string>();
+
+  if (uniqueUids.length === 0) {
+    return userMap;
+  }
+
+  try {
+    // 直接使用 HydroOJ db 访问 user 集合
+    const userColl = db.collection('user');
+    const users = await userColl.find({ _id: { $in: uniqueUids } }).toArray();
+    for (const user of users) {
+      const u = user as UserDocument;
+      userMap.set(u._id, u.uname || '已删除用户');
+    }
+    // 对于不存在的用户，设置默认值
+    for (const uid of uniqueUids) {
+      if (!userMap.has(uid)) {
+        userMap.set(uid, '已删除用户');
+      }
+    }
+  } catch (err) {
+    console.error('[AI Helper] Failed to fetch user names:', err);
+    // 出错时全部使用默认值
+    for (const uid of uniqueUids) {
+      userMap.set(uid, '已删除用户');
+    }
+  }
+
+  return userMap;
+}
+
+/**
+ * 对话概要接口
+ */
+interface ConversationSummary {
+  _id: string;
+  userId: number;
+  userName: string;
+  classId?: string;
+  problemId: string;
+  problemUrl?: string;  // T031: 题目详情页 URL
+  startTime: string;
+  endTime: string;
+  messageCount: number;
+  isEffective: boolean;
+  tags: string[];
+  teacherNote?: string;
+  metadata?: {
+    problemTitle?: string;
+    problemContent?: string;
+  };
+  firstMessageSummary?: string;  // T048: 学生首条消息摘要（前100字）
+}
+
+/**
+ * T031/T032: 生成题目详情页 URL
+ * @param domainId 域 ID
+ * @param problemId 题目 ID
+ * @returns 题目详情页 URL
+ */
+function buildProblemUrl(domainId: string, problemId: string): string {
+  if (!problemId) return '';
+  // 域前缀格式：/d/:domainId/p/:problemId
+  // 主站格式：/p/:problemId
+  if (domainId && domainId !== 'system') {
+    return `/d/${domainId}/p/${problemId}`;
+  }
+  return `/p/${problemId}`;
+}
+
+/**
+ * ConversationListHandler - 获取对话列表
+ * GET /ai-helper/conversations
+ * GET /d/:domainId/ai-helper/conversations
+ */
+export class ConversationListHandler extends Handler {
+  async get() {
+    try {
+      const wantJson = expectsJson(this);
+      const conversationModel: ConversationModel = this.ctx.get('conversationModel');
+
+      // 获取当前域 ID（用于域隔离）
+      const domainId = getDomainId(this);
+
+      // 从查询参数读取筛选条件
+      const {
+        startDate,
+        endDate,
+        problemId,
+        classId,
+        userId,
+        page = '1',
+        limit = '50'
+      } = this.request.query;
+
+      // 解析分页参数
+      const { page: pageNum, limit: limitNum } = parsePaginationParams(page as string, limit as string);
+
+      // 构造筛选条件（始终包含 domainId 以实现域隔离）
+      const filters: {
+        domainId?: string;
+        startDate?: string;
+        endDate?: string;
+        problemId?: string;
+        classId?: string;
+        userId?: number;
+      } = {
+        domainId  // 域隔离：只查询当前域的对话
+      };
+
+      if (startDate) {
+        filters.startDate = startDate as string;
+      }
+
+      if (endDate) {
+        filters.endDate = endDate as string;
+      }
+
+      if (problemId) {
+        filters.problemId = problemId as string;
+      }
+
+      if (classId) {
+        filters.classId = classId as string;
+      }
+
+      if (userId) {
+        filters.userId = parseInt(userId as string, 10);
+      }
+
+      // 查询对话列表（已通过 domainId 实现域隔离）
+      const { conversations, total } = await conversationModel.findByFilters(
+        filters,
+        pageNum,
+        limitNum
+      );
+
+      // 批量获取用户名（避免 N+1 查询）
+      const uids = conversations.map(conv => conv.userId);
+      const userNameMap = await getUserNameMap(uids);
+
+      // T048: 批量获取每个会话的第一条学生消息
+      const messageModel: MessageModel = this.ctx.get('messageModel');
+      const conversationIds = conversations.map(conv => conv._id);
+      const firstMessagesMap = await messageModel.findFirstStudentMessagesForConversations(conversationIds);
+
+      // T031: 转换为响应格式（包含 problemUrl 和 firstMessageSummary）
+      const conversationSummaries: ConversationSummary[] = conversations.map(conv => {
+        const convIdStr = conv._id.toString();
+        const firstMsg = firstMessagesMap.get(convIdStr);
+        // T048: 截取前100字作为摘要
+        let firstMessageSummary: string | undefined;
+        if (firstMsg?.content) {
+          firstMessageSummary = firstMsg.content.length > 100
+            ? firstMsg.content.substring(0, 100) + '...'
+            : firstMsg.content;
+        }
+
+        return {
+          _id: convIdStr,
+          userId: conv.userId,
+          userName: userNameMap.get(conv.userId) || '已删除用户',
+          classId: conv.classId,
+          problemId: conv.problemId,
+          problemUrl: buildProblemUrl(domainId, conv.problemId),  // T031: 题目链接
+          startTime: conv.startTime.toISOString(),
+          endTime: conv.endTime.toISOString(),
+          messageCount: conv.messageCount,
+          isEffective: conv.isEffective,
+          tags: conv.tags,
+          teacherNote: conv.teacherNote,
+          metadata: conv.metadata,
+          firstMessageSummary  // T048: 学生问题摘要
+        };
+      });
+
+      if (wantJson) {
+        setJsonResponse(this, {
+          conversations: conversationSummaries,
+          total,
+          page: pageNum,
+          limit: limitNum
+        });
+        return;
+      }
+
+      setTemplateResponse(this, 'ai-helper/teacher_conversations.html', {
+        total,
+        page: pageNum,
+        limit: limitNum
+      });
+    } catch (err) {
+      console.error('[AI Helper] ConversationListHandler error:', err);
+      setErrorResponse(this, 'INTERNAL_ERROR', err instanceof Error ? err.message : '服务器内部错误', 500);
+    }
+  }
+}
+
+/**
+ * ConversationDetailHandler - 获取对话详情
+ * GET /ai-helper/conversations/:id
+ * GET /d/:domainId/ai-helper/conversations/:id
+ */
+export class ConversationDetailHandler extends Handler {
+  async get({ id }: { id: string }) {
+    try {
+      const wantJson = expectsJson(this);
+      const conversationModel: ConversationModel = this.ctx.get('conversationModel');
+      const messageModel: MessageModel = this.ctx.get('messageModel');
+
+      // 获取当前域 ID（用于域隔离验证）
+      const domainId = getDomainId(this);
+
+      if (!ObjectId.isValid(id)) {
+        setErrorResponse(this, 'INVALID_ID', '无效的会话 ID');
+        return;
+      }
+
+      // 查询会话详情
+      const conversation = await conversationModel.findById(id);
+
+      if (!conversation) {
+        setErrorResponse(this, 'NOT_FOUND', '会话不存在', 404);
+        return;
+      }
+
+      // 域隔离验证：确保对话属于当前域
+      // 特殊处理：
+      // 1. 对话的 domainId 为 'system'（历史数据迁移默认值）时，允许任何域访问
+      // 2. 当前访问域为 'system'（主站访问）时，允许访问所有域的对话
+      const conversationDomain = conversation.domainId || 'system';
+      if (conversationDomain !== domainId && conversationDomain !== 'system' && domainId !== 'system') {
+        setErrorResponse(this, 'FORBIDDEN', '无权访问此对话', 403);
+        return;
+      }
+
+      // 查询会话的所有消息 (按时间升序)
+      const messages = await messageModel.findByConversationId(id);
+
+      // 转换消息格式
+      const messagesFormatted = messages.map(msg => ({
+        _id: msg._id.toString(),
+        role: msg.role,
+        content: msg.content,
+        timestamp: msg.timestamp.toISOString(),
+        questionType: msg.questionType,
+        attachedCode: msg.attachedCode,
+        attachedError: msg.attachedError,
+        metadata: msg.metadata
+      }));
+
+      // 获取用户名
+      const userNameMap = await getUserNameMap([conversation.userId]);
+      const userName = userNameMap.get(conversation.userId) || '已删除用户';
+
+      // T032: 对话详情响应（包含 problemUrl）
+      const conversationData = {
+        _id: conversation._id.toString(),
+        userId: conversation.userId,
+        userName,
+        classId: conversation.classId,
+        problemId: conversation.problemId,
+        problemUrl: buildProblemUrl(domainId, conversation.problemId),  // T032: 题目链接
+        startTime: conversation.startTime.toISOString(),
+        endTime: conversation.endTime.toISOString(),
+        messageCount: conversation.messageCount,
+        isEffective: conversation.isEffective,
+        tags: conversation.tags,
+        teacherNote: conversation.teacherNote,
+        metadata: conversation.metadata
+      };
+
+      if (wantJson) {
+        setJsonResponse(this, {
+          conversation: conversationData,
+          messages: messagesFormatted
+        });
+        return;
+      }
+
+      setTemplateResponse(this, 'ai-helper/teacher_conversation_detail.html', {
+        conversation: conversationData,
+        messages: messagesFormatted
+      });
+    } catch (err) {
+      console.error('[AI Helper] ConversationDetailHandler error:', err);
+      setErrorResponse(this, 'INTERNAL_ERROR', err instanceof Error ? err.message : '服务器内部错误', 500);
+    }
+  }
+}
+
+// 导出路由权限配置
+// 使用 PRIV.PRIV_EDIT_SYSTEM (root-only 权限)
+// AI 对话数据敏感，目前仅允许系统管理员访问
+export const ConversationListHandlerPriv = PRIV.PRIV_EDIT_SYSTEM;
+export const ConversationDetailHandlerPriv = PRIV.PRIV_EDIT_SYSTEM;

package/src/handlers/testHandler.ts

@@ -0,0 +1,25 @@
+/**
+ * 测试路由 Handler
+ * 用于验证插件加载和路由注册是否成功
+ */
+
+import { Handler, PRIV } from 'hydrooj';
+
+/**
+ * Hello 测试 Handler
+ * GET /ai-helper/hello - 返回插件状态信息
+ */
+export class HelloHandler extends Handler {
+  async get() {
+    this.response.body = {
+      message: 'AI Helper Plugin Loaded',
+      version: '0.1.0',
+      timestamp: new Date().toISOString(),
+      status: 'ok'
+    };
+    this.response.type = 'application/json';
+  }
+}
+
+// 导出路由权限配置（最低权限 - 任何人可访问）
+export const HelloHandlerPriv = PRIV.PRIV_NONE;

package/src/handlers/updateHandler.ts

@@ -0,0 +1,85 @@
+/**
+ * UpdateHandler - 插件更新 API 处理器
+ *
+ * 提供插件在线更新接口：
+ * GET /ai-helper/admin/update/info - 获取更新信息
+ * POST /ai-helper/admin/update - 执行更新
+ */
+
+import { Handler, PRIV } from 'hydrooj';
+import { UpdateService } from '../services/updateService';
+import { setJsonResponse, setErrorResponse } from '../lib/httpHelpers';
+
+/**
+ * UpdateInfoHandler - 获取更新信息
+ * GET /ai-helper/admin/update/info
+ *
+ * 响应：
+ * {
+ *   pluginPath: string,      // 插件安装路径
+ *   isValid: boolean,        // 路径是否有效
+ *   message: string          // 验证消息
+ * }
+ */
+export class UpdateInfoHandler extends Handler {
+  async get() {
+    try {
+      const updateService = new UpdateService();
+      const info = updateService.getPluginInfo();
+
+      setJsonResponse(this, info);
+    } catch (err) {
+      console.error('[UpdateInfoHandler] Error:', err);
+      setErrorResponse(this, 'UPDATE_INFO_FAILED', err instanceof Error ? err.message : '获取更新信息失败', 500);
+    }
+  }
+}
+
+// 导出路由权限配置 - root-only
+export const UpdateInfoHandlerPriv = PRIV.PRIV_EDIT_SYSTEM;
+
+/**
+ * UpdateHandler - 执行更新
+ * POST /ai-helper/admin/update
+ *
+ * 响应：
+ * {
+ *   success: boolean,
+ *   step: string,
+ *   message: string,
+ *   logs: string[],
+ *   pluginPath?: string,
+ *   error?: string
+ * }
+ */
+export class UpdateHandler extends Handler {
+  async post() {
+    try {
+      const updateService = new UpdateService();
+
+      // 收集所有日志
+      const allLogs: string[] = [];
+
+      // 执行更新
+      const result = await updateService.performUpdate((step, log) => {
+        allLogs.push(`[${step}] ${log}`);
+        console.log(`[UpdateHandler] ${step}: ${log}`);
+      });
+
+      setJsonResponse(this, {
+        success: result.success,
+        step: result.step,
+        message: result.message,
+        logs: result.logs,
+        pluginPath: result.pluginPath,
+        error: result.error
+      });
+    } catch (err) {
+      console.error('[UpdateHandler] Error:', err);
+      setErrorResponse(this, 'UPDATE_FAILED', err instanceof Error ? err.message : '更新失败', 500);
+    }
+  }
+}
+
+// 导出路由权限配置 - root-only
+export const UpdateHandlerPriv = PRIV.PRIV_EDIT_SYSTEM;

package/src/handlers/versionHandler.ts

@@ -0,0 +1,62 @@
+/**
+ * Version Handler - 版本检测 API 处理器
+ *
+ * T051: 提供版本检测接口
+ * GET /ai-helper/version/check - 检查版本更新
+ */
+
+import { Handler, PRIV } from 'hydrooj';
+import { VersionService } from '../services/versionService';
+import { setJsonResponse, setErrorResponse } from '../lib/httpHelpers';
+
+/**
+ * VersionCheckHandler - 检查版本更新
+ * GET /ai-helper/version/check
+ * GET /d/:domainId/ai-helper/version/check
+ *
+ * 查询参数：
+ * - refresh: 是否强制刷新（忽略缓存），默认 false
+ *
+ * 响应：
+ * {
+ *   currentVersion: string,    // 当前安装版本
+ *   latestVersion: string,     // 远程最新版本
+ *   hasUpdate: boolean,        // 是否有可用更新
+ *   releaseUrl: string,        // 发布页面 URL
+ *   releaseNotes?: string,     // 更新说明（如有）
+ *   checkedAt: string,         // 检查时间（ISO 格式）
+ *   fromCache: boolean         // 是否来自缓存
+ * }
+ */
+export class VersionCheckHandler extends Handler {
+  async get() {
+    try {
+      const versionService: VersionService = this.ctx.get('versionService');
+
+      // 检查是否强制刷新
+      const refresh = this.request.query.refresh === 'true';
+
+      // 检查版本更新
+      const result = await versionService.checkForUpdates(refresh);
+
+      setJsonResponse(this, {
+        currentVersion: result.currentVersion,
+        latestVersion: result.latestVersion,
+        hasUpdate: result.hasUpdate,
+        releaseUrl: result.releaseUrl,
+        releaseNotes: result.releaseNotes,
+        checkedAt: result.checkedAt.toISOString(),
+        fromCache: result.fromCache,
+        source: result.source
+      });
+    } catch (err) {
+      console.error('[VersionCheckHandler] Error:', err);
+      setErrorResponse(this, 'VERSION_CHECK_FAILED', err instanceof Error ? err.message : '版本检查失败', 500);
+    }
+  }
+}
+
+// 导出路由权限配置
+// 使用 PRIV.PRIV_EDIT_SYSTEM (root-only 权限)
+// 版本检查仅限管理员访问
+export const VersionCheckHandlerPriv = PRIV.PRIV_EDIT_SYSTEM;

package/src/index.ts

@@ -0,0 +1,198 @@
+/**
+ * HydroOJ AI Learning Assistant Plugin
+ *
+ * 教学优先的 AI 辅助学习插件
+ * - 引导式学习，不提供完整代码
+ * - 对话记录可追踪
+ * - 符合教学研究需求
+ */
+
+console.log('[AI-Helper] Loading plugin...');
+
+import { Context, definePlugin, Schema } from 'hydrooj';
+console.log('[AI-Helper] hydrooj imports OK');
+
+import { HelloHandler, HelloHandlerPriv } from './handlers/testHandler';
+console.log('[AI-Helper] testHandler OK');
+
+import { ChatHandler, ChatHandlerPriv, ProblemStatusHandler, ProblemStatusHandlerPriv } from './handlers/studentHandler';
+console.log('[AI-Helper] studentHandler OK');
+
+import {
+  ConversationListHandler,
+  ConversationListHandlerPriv,
+  ConversationDetailHandler,
+  ConversationDetailHandlerPriv
+} from './handlers/teacherHandler';
+console.log('[AI-Helper] teacherHandler OK');
+
+import { AnalyticsHandler, AnalyticsHandlerPriv } from './handlers/analyticsHandler';
+console.log('[AI-Helper] analyticsHandler OK');
+
+import { AdminConfigHandler, AdminConfigHandlerPriv } from './handlers/adminConfigHandler';
+console.log('[AI-Helper] adminConfigHandler OK');
+
+import { AIHelperDashboardHandler, AIHelperDashboardHandlerPriv } from './handlers/dashboardHandler';
+console.log('[AI-Helper] dashboardHandler OK');
+
+import { ExportHandler, ExportHandlerPriv } from './handlers/exportHandler';
+console.log('[AI-Helper] exportHandler OK');
+
+import { TestConnectionHandler, TestConnectionHandlerPriv, FetchModelsHandler, FetchModelsHandlerPriv } from './handlers/adminHandler';
+console.log('[AI-Helper] adminHandler OK');
+
+import { VersionCheckHandler, VersionCheckHandlerPriv } from './handlers/versionHandler';
+console.log('[AI-Helper] versionHandler OK');
+
+import { UpdateInfoHandler, UpdateInfoHandlerPriv, UpdateHandler, UpdateHandlerPriv } from './handlers/updateHandler';
+console.log('[AI-Helper] updateHandler OK');
+
+import { ConversationModel } from './models/conversation';
+import { MessageModel } from './models/message';
+import { RateLimitRecordModel } from './models/rateLimitRecord';
+import { AIConfigModel } from './models/aiConfig';
+import { JailbreakLogModel } from './models/jailbreakLog';
+import { VersionCacheModel } from './models/versionCache';
+import { PluginInstallModel } from './models/pluginInstall';
+console.log('[AI-Helper] models OK');
+
+import { MigrationService } from './services/migrationService';
+import { VersionService } from './services/versionService';
+import { TelemetryService } from './services/telemetryService';
+console.log('[AI-Helper] services OK');
+
+console.log('[AI-Helper] All imports completed successfully');
+
+/**
+ * 插件配置接口
+ */
+export interface AIHelperConfig {
+  // 未来可在此添加配置项
+}
+
+/**
+ * 插件入口函数
+ * @param ctx HydroOJ Context
+ * @param config 插件配置
+ */
+const configSchema = Schema.object({}).description('AI 助手插件配置（预留）').default({});
+
+const aiHelperPlugin = definePlugin<AIHelperConfig>({
+  name: 'hydro-ai-helper',
+  schema: configSchema,
+  async apply(ctx: Context) {
+    // 初始化数据库模型
+    const db = ctx.db;
+    const conversationModel = new ConversationModel(db);
+    const messageModel = new MessageModel(db);
+    const rateLimitRecordModel = new RateLimitRecordModel(db);
+    const aiConfigModel = new AIConfigModel(db);
+    const jailbreakLogModel = new JailbreakLogModel(db);
+    const versionCacheModel = new VersionCacheModel(db);
+    const pluginInstallModel = new PluginInstallModel(db);
+
+    // 创建数据库索引
+    await conversationModel.ensureIndexes();
+    await messageModel.ensureIndexes();
+    await rateLimitRecordModel.ensureIndexes();
+    await aiConfigModel.ensureIndexes();
+    await jailbreakLogModel.ensureIndexes();
+    await versionCacheModel.ensureIndexes();
+    await pluginInstallModel.ensureIndexes();
+
+    // 执行数据迁移（为历史数据添加 domainId）
+    const migrationService = new MigrationService(db);
+    await migrationService.runAllMigrations();
+
+    // 初始化插件安装记录
+    const packageJson = require('../package.json');
+    const currentVersion = packageJson.version || '1.8.0';
+    await pluginInstallModel.createIfMissing(currentVersion);
+
+    // 将模型实例注入到 ctx 中,供 Handler 使用
+    ctx.provide('conversationModel', conversationModel);
+    ctx.provide('messageModel', messageModel);
+    ctx.provide('rateLimitRecordModel', rateLimitRecordModel);
+    ctx.provide('aiConfigModel', aiConfigModel);
+    ctx.provide('jailbreakLogModel', jailbreakLogModel);
+    ctx.provide('versionCacheModel', versionCacheModel);
+    ctx.provide('pluginInstallModel', pluginInstallModel);
+
+    // 初始化版本服务
+    const versionService = new VersionService(versionCacheModel);
+    ctx.provide('versionService', versionService);
+
+    // 初始化遥测服务（延迟 5 秒启动，避免阻塞插件加载）
+    const telemetryService = new TelemetryService(pluginInstallModel, conversationModel);
+    setTimeout(() => {
+      telemetryService.init().catch(err => {
+        console.error('[AI-Helper] Telemetry service initialization failed:', err);
+      });
+    }, 5000);
+
+    // 注册测试路由
+    // GET /ai-helper/hello - 返回插件状态
+    ctx.Route('ai_helper_hello', '/ai-helper/hello', HelloHandler, HelloHandlerPriv);
+
+    // 注册学生端对话路由 (支持域前缀)
+    // POST /ai-helper/chat - 学生提交问题获得 AI 回答
+    ctx.Route('ai_helper_chat', '/ai-helper/chat', ChatHandler, ChatHandlerPriv);
+    // 域前缀路由: /d/:domainId/ai-helper/chat
+    ctx.Route('ai_helper_chat_domain', '/d/:domainId/ai-helper/chat', ChatHandler, ChatHandlerPriv);
+
+    // GET /ai-helper/problem-status/:problemId - 查询用户在该题的提交状态（是否已 AC）
+    ctx.Route('ai_helper_problem_status', '/ai-helper/problem-status/:problemId', ProblemStatusHandler, ProblemStatusHandlerPriv);
+    ctx.Route('ai_helper_problem_status_domain', '/d/:domainId/ai-helper/problem-status/:problemId', ProblemStatusHandler, ProblemStatusHandlerPriv);
+
+    // 注册教师端路由 (支持域前缀)
+    // 当前设计：AI 学习助手对话统计非常敏感，仅允许 root 访问。
+    // 注意：这里使用的是 root-only 的系统权限（PRIV.PRIV_EDIT_SYSTEM），普通老师也无权访问。
+    // TODO(如需求变更): 未来若有专门的教师统计角色，再考虑降低权限。
+
+    // 注入控制面板菜单项（统一入口）
+    ctx.injectUI('ControlPanel', 'ai_helper');
+
+    // AI 助手统一入口路由
+    ctx.Route('ai_helper', '/ai-helper', AIHelperDashboardHandler, AIHelperDashboardHandlerPriv);
+    ctx.Route('ai_helper_domain', '/d/:domainId/ai-helper', AIHelperDashboardHandler, AIHelperDashboardHandlerPriv);
+
+    // GET /ai-helper/conversations - 获取对话列表
+    ctx.Route('ai_helper_conversations', '/ai-helper/conversations', ConversationListHandler, ConversationListHandlerPriv);
+    ctx.Route('ai_helper_conversations_domain', '/d/:domainId/ai-helper/conversations', ConversationListHandler, ConversationListHandlerPriv);
+
+    // GET /ai-helper/conversations/:id - 获取对话详情
+    ctx.Route('ai_helper_conversation_detail', '/ai-helper/conversations/:id', ConversationDetailHandler, ConversationDetailHandlerPriv);
+    ctx.Route('ai_helper_conversation_detail_domain', '/d/:domainId/ai-helper/conversations/:id', ConversationDetailHandler, ConversationDetailHandlerPriv);
+
+    // GET /ai-helper/analytics - AI 使用统计页面
+    ctx.Route('ai_helper_analytics', '/ai-helper/analytics', AnalyticsHandler, AnalyticsHandlerPriv);
+    ctx.Route('ai_helper_analytics_domain', '/d/:domainId/ai-helper/analytics', AnalyticsHandler, AnalyticsHandlerPriv);
+
+    // GET /ai-helper/admin/config - AI 配置页面 & JSON API（通过 Accept 头区分）
+    ctx.Route('ai_helper_admin_config', '/ai-helper/admin/config', AdminConfigHandler, AdminConfigHandlerPriv);
+
+    // GET /ai-helper/export - 数据导出 API
+    ctx.Route('ai_helper_export', '/ai-helper/export', ExportHandler, ExportHandlerPriv);
+    ctx.Route('ai_helper_export_domain', '/d/:domainId/ai-helper/export', ExportHandler, ExportHandlerPriv);
+
+    // POST /ai-helper/admin/test-connection - 测试连接
+    ctx.Route('ai_helper_admin_test_connection', '/ai-helper/admin/test-connection', TestConnectionHandler, TestConnectionHandlerPriv);
+
+    // POST /ai-helper/admin/fetch-models - 获取可用模型列表
+    ctx.Route('ai_helper_admin_fetch_models', '/ai-helper/admin/fetch-models', FetchModelsHandler, FetchModelsHandlerPriv);
+
+    // T052: GET /ai-helper/version/check - 版本检测
+    ctx.Route('ai_helper_version_check', '/ai-helper/version/check', VersionCheckHandler, VersionCheckHandlerPriv);
+    ctx.Route('ai_helper_version_check_domain', '/d/:domainId/ai-helper/version/check', VersionCheckHandler, VersionCheckHandlerPriv);
+
+    // 插件更新路由
+    // GET /ai-helper/admin/update/info - 获取更新信息
+    ctx.Route('ai_helper_update_info', '/ai-helper/admin/update/info', UpdateInfoHandler, UpdateInfoHandlerPriv);
+    // POST /ai-helper/admin/update - 执行更新
+    ctx.Route('ai_helper_update', '/ai-helper/admin/update', UpdateHandler, UpdateHandlerPriv);
+  }
+});
+
+export const Config = configSchema;
+export const apply = aiHelperPlugin.apply;
+export default aiHelperPlugin;