koishi-plugin-bind-bot 2.0.0 → 2.0.3

package/lib/handlers/whitelist.handler.d.ts

@@ -56,10 +56,6 @@ export declare class WhitelistHandler extends BaseHandler {
      * 私有辅助方法：计算两个字符串的相似度
      */
     private similarityScore;
-    /**
-     * 私有辅助方法：计算Levenshtein距离
-     */
-    private levenshteinDistance;
     /**
      * 私有辅助方法：检查用户是否在特定服务器的白名单中
      */

package/lib/handlers/whitelist.handler.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.WhitelistHandler = void 0;
 const koishi_1 = require("koishi");
 const base_handler_1 = require("./base.handler");
+const helpers_1 = require("../utils/helpers");
 /**
  * 白名单命令处理器
  * 处理所有 mcid.whitelist 子命令
@@ -756,38 +757,8 @@ class WhitelistHandler extends base_handler_1.BaseHandler {
         if (b.includes(a)) {
             return a.length / b.length;
         }
-        // 否则计算Levenshtein距离的相似度
-        const maxLength = Math.max(a.length, b.length);
-        const editDistance = this.levenshteinDistance(a, b);
-        return 1 - (editDistance / maxLength);
-    }
-    /**
-     * 私有辅助方法：计算Levenshtein距离
-     */
-    levenshteinDistance(a, b) {
-        const matrix = [];
-        // 初始化矩阵
-        for (let i = 0; i <= b.length; i++) {
-            matrix[i] = [i];
-        }
-        for (let j = 0; j <= a.length; j++) {
-            matrix[0][j] = j;
-        }
-        // 填充矩阵
-        for (let i = 1; i <= b.length; i++) {
-            for (let j = 1; j <= a.length; j++) {
-                if (b.charAt(i - 1) === a.charAt(j - 1)) {
-                    matrix[i][j] = matrix[i - 1][j - 1];
-                }
-                else {
-                    matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // 替换
-                    matrix[i][j - 1] + 1, // 插入
-                    matrix[i - 1][j] + 1 // 删除
-                    );
-                }
-            }
-        }
-        return matrix[b.length][a.length];
+        // 否则使用工具函数计算Levenshtein距离的相似度
+        return (0, helpers_1.calculateSimilarity)(a, b);
     }
     /**
      * 私有辅助方法：检查用户是否在特定服务器的白名单中
@@ -808,11 +779,13 @@ class WhitelistHandler extends base_handler_1.BaseHandler {
                 return false;
             }
             // 重新获取最新的用户绑定信息
-            const freshBind = await this.deps.getBindInfo(mcBind.qqId);
+            let freshBind = await this.deps.getBindInfo(mcBind.qqId);
             if (!freshBind || !freshBind.mcUsername) {
                 this.logger.warn('白名单', `用户QQ(${mcBind.qqId})可能在操作过程中解绑了MC账号`);
                 return false;
             }
+            // 智能检测用户名变更（带缓存，避免频繁API调用）
+            freshBind = await this.deps.checkAndUpdateUsernameWithCache(freshBind);
             // 检查最新状态是否已在白名单中
             if (freshBind.whitelist && freshBind.whitelist.includes(server.id)) {
                 this.logger.info('白名单', `用户QQ(${mcBind.qqId})已在服务器${server.name}的白名单中`);
@@ -889,11 +862,13 @@ class WhitelistHandler extends base_handler_1.BaseHandler {
                 return false;
             }
             // 重新获取最新的用户绑定信息
-            const freshBind = await this.deps.getBindInfo(mcBind.qqId);
+            let freshBind = await this.deps.getBindInfo(mcBind.qqId);
             if (!freshBind || !freshBind.mcUsername) {
                 this.logger.warn('白名单', `用户QQ(${mcBind.qqId})可能在操作过程中解绑了MC账号`);
                 return false;
             }
+            // 智能检测用户名变更（带缓存，避免频繁API调用）
+            freshBind = await this.deps.checkAndUpdateUsernameWithCache(freshBind);
             // 检查最新状态是否在白名单中
             if (!freshBind.whitelist || !freshBind.whitelist.includes(server.id)) {
                 this.logger.info('白名单', `用户QQ(${mcBind.qqId})不在服务器${server.name}的白名单中`);

package/lib/index.js

@@ -12,6 +12,8 @@ const export_utils_1 = require("./export-utils");
 const logger_1 = require("./utils/logger");
 const rcon_manager_1 = require("./managers/rcon-manager");
 const rate_limiter_1 = require("./utils/rate-limiter");
+const helpers_1 = require("./utils/helpers");
+const error_utils_1 = require("./utils/error-utils");
 const mcidbind_repository_1 = require("./repositories/mcidbind.repository");
 const schedule_mute_repository_1 = require("./repositories/schedule-mute.repository");
 const handlers_1 = require("./handlers");
@@ -911,88 +913,6 @@ function apply(ctx, config) {
         return extractedId;
     };
     // 获取用户友好的错误信息
-    const getFriendlyErrorMessage = (error) => {
-        const errorMsg = error instanceof Error ? error.message : error;
-        // 拆分错误信息
-        const userError = getUserFacingErrorMessage(errorMsg);
-        // 将警告级别错误标记出来
-        if (isWarningError(userError)) {
-            return `⚠️ ${userError}`;
-        }
-        // 将严重错误标记出来
-        if (isCriticalError(userError)) {
-            return `❌ ${userError}`;
-        }
-        return userError;
-    };
-    // 提取用户友好的错误信息
-    const getUserFacingErrorMessage = (errorMsg) => {
-        // Mojang API相关错误
-        if (errorMsg.includes('ECONNABORTED') || errorMsg.includes('timeout')) {
-            return '无法连接到Mojang服务器，请稍后再试';
-        }
-        if (errorMsg.includes('404')) {
-            return '该Minecraft用户名不存在';
-        }
-        if (errorMsg.includes('network') || errorMsg.includes('connect')) {
-            return '网络连接异常，请稍后再试';
-        }
-        // 数据库相关错误
-        if (errorMsg.includes('unique') || errorMsg.includes('duplicate')) {
-            return '该Minecraft用户名已被其他用户绑定';
-        }
-        // RCON相关错误
-        if (errorMsg.includes('RCON') || errorMsg.includes('服务器')) {
-            if (errorMsg.includes('authentication') || errorMsg.includes('auth') || errorMsg.includes('认证')) {
-                return 'RCON认证失败，服务器拒绝访问，请联系管理员检查密码';
-            }
-            if (errorMsg.includes('ECONNREFUSED') || errorMsg.includes('ETIMEDOUT') || errorMsg.includes('无法连接')) {
-                return '无法连接到游戏服务器，请确认服务器是否在线或联系管理员';
-            }
-            if (errorMsg.includes('command') || errorMsg.includes('执行命令')) {
-                return '服务器命令执行失败，请稍后再试';
-            }
-            return '与游戏服务器通信失败，请稍后再试';
-        }
-        // 用户名相关错误
-        if (errorMsg.includes('用户名') || errorMsg.includes('username')) {
-            if (errorMsg.includes('不存在')) {
-                return '该Minecraft用户名不存在，请检查拼写';
-            }
-            if (errorMsg.includes('已被')) {
-                return '该Minecraft用户名已被其他用户绑定，请使用其他用户名';
-            }
-            if (errorMsg.includes('格式')) {
-                return 'Minecraft用户名格式不正确，应为3-16位字母、数字和下划线';
-            }
-            return '用户名验证失败，请检查用户名并重试';
-        }
-        // 默认错误信息
-        return '操作失败，请稍后再试';
-    };
-    // 判断是否为警告级别错误（用户可能输入有误）
-    const isWarningError = (errorMsg) => {
-        const warningPatterns = [
-            '用户名不存在',
-            '格式不正确',
-            '已被其他用户绑定',
-            '已在白名单中',
-            '不在白名单中',
-            '未绑定MC账号',
-            '冷却期内'
-        ];
-        return warningPatterns.some(pattern => errorMsg.includes(pattern));
-    };
-    // 判断是否为严重错误（系统问题）
-    const isCriticalError = (errorMsg) => {
-        const criticalPatterns = [
-            '无法连接',
-            'RCON认证失败',
-            '服务器通信失败',
-            '数据库操作出错'
-        ];
-        return criticalPatterns.some(pattern => errorMsg.includes(pattern));
-    };
     // 封装发送消息的函数，处理私聊和群聊的不同格式
     const sendMessage = async (session, content, options) => {
         try {
@@ -1256,8 +1176,8 @@ function apply(ctx, config) {
             return false;
         }
     };
-    // 检查MC用户名是否已被其他QQ号绑定
-    const checkUsernameExists = async (username, currentUserId) => {
+    // 检查MC用户名是否已被其他QQ号绑定（支持不区分大小写和UUID检查）
+    const checkUsernameExists = async (username, currentUserId, uuid) => {
         try {
             // 验证输入参数
             if (!username) {
@@ -1268,8 +1188,8 @@ function apply(ctx, config) {
             if (username.startsWith('_temp_')) {
                 return false;
             }
-            // 查询新表中是否已有此用户名的绑定
-            const bind = await getMcBindByUsername(username);
+            // 使用不区分大小写的查询
+            const bind = await mcidbindRepo.findByUsernameIgnoreCase(username);
             // 如果没有绑定，返回false
             if (!bind)
                 return false;
@@ -1277,6 +1197,16 @@ function apply(ctx, config) {
             if (bind.mcUsername && bind.mcUsername.startsWith('_temp_')) {
                 return false;
             }
+            // 如果提供了 UUID，检查是否为同一个 MC 账号（用户改名场景）
+            if (uuid && bind.mcUuid) {
+                const cleanUuid = uuid.replace(/-/g, '');
+                const bindCleanUuid = bind.mcUuid.replace(/-/g, '');
+                if (cleanUuid === bindCleanUuid) {
+                    // 同一个 UUID，说明是用户改名，允许绑定
+                    logger.info(`[绑定检查] 检测到MC账号改名: UUID=${uuid}, 旧用户名=${bind.mcUsername}, 新用户名=${username}`);
+                    return false;
+                }
+            }
             // 如果提供了当前用户ID，需要排除当前用户
             if (currentUserId) {
                 const normalizedCurrentId = normalizeQQId(currentUserId);
@@ -1727,8 +1657,10 @@ function apply(ctx, config) {
                 logger.warn(`[用户名更新] 无法获取UUID "${bind.mcUuid}" 的最新用户名`);
                 return bind;
             }
-            // 如果用户名与数据库中的不同，更新数据库
-            if (latestUsername !== bind.mcUsername) {
+            // 如果用户名与数据库中的不同，更新数据库（使用规范化比较，不区分大小写）
+            const normalizedLatest = (0, helpers_1.normalizeUsername)(latestUsername);
+            const normalizedCurrent = (0, helpers_1.normalizeUsername)(bind.mcUsername);
+            if (normalizedLatest !== normalizedCurrent) {
                 logger.info(`[用户名更新] 用户 QQ(${bind.qqId}) 的Minecraft用户名已变更: ${bind.mcUsername} -> ${latestUsername}`);
                 // 更新数据库中的用户名
                 await ctx.database.set('mcidbind', { qqId: bind.qqId }, {
@@ -1744,6 +1676,88 @@ function apply(ctx, config) {
             return bind;
         }
     };
+    /**
+     * 智能缓存版本的改名检测函数
+     * 特性：
+     * - 24小时冷却期（失败>=3次时延长到72小时）
+     * - 失败计数追踪
+     * - 成功时重置失败计数
+     * @param bind 绑定记录
+     * @returns 更新后的绑定记录
+     */
+    const checkAndUpdateUsernameWithCache = async (bind) => {
+        try {
+            if (!bind || !bind.mcUuid) {
+                logger.warn(`[改名检测缓存] 无法检查用户名更新: 空绑定或空UUID`);
+                return bind;
+            }
+            const now = new Date();
+            const failCount = bind.usernameCheckFailCount || 0;
+            // 根据失败次数决定冷却期：普通24小时，失败>=3次则72小时
+            const cooldownHours = failCount >= 3 ? 72 : 24;
+            // 检查是否在冷却期内
+            if (bind.usernameLastChecked) {
+                const lastCheck = new Date(bind.usernameLastChecked);
+                const hoursSinceCheck = (now.getTime() - lastCheck.getTime()) / (1000 * 60 * 60);
+                if (hoursSinceCheck < cooldownHours) {
+                    logger.debug(`[改名检测缓存] QQ(${bind.qqId}) 在冷却期内(${hoursSinceCheck.toFixed(1)}h/${cooldownHours}h)，跳过检查`);
+                    return bind;
+                }
+            }
+            logger.debug(`[改名检测缓存] QQ(${bind.qqId}) 开始检查用户名变更（失败计数: ${failCount}）`);
+            // 执行实际的改名检测
+            const oldUsername = bind.mcUsername;
+            const updatedBind = await checkAndUpdateUsername(bind);
+            // 判断检测是否成功
+            const detectionSuccess = updatedBind.mcUsername !== null && updatedBind.mcUsername !== undefined;
+            if (detectionSuccess) {
+                // 检测成功
+                const usernameChanged = (0, helpers_1.normalizeUsername)(updatedBind.mcUsername) !== (0, helpers_1.normalizeUsername)(oldUsername);
+                // 更新检查时间和重置失败计数
+                await mcidbindRepo.update(bind.qqId, {
+                    usernameLastChecked: now,
+                    usernameCheckFailCount: 0
+                });
+                if (usernameChanged) {
+                    logger.info(`[改名检测缓存] QQ(${bind.qqId}) 用户名已变更: ${oldUsername} -> ${updatedBind.mcUsername}`);
+                }
+                else {
+                    logger.debug(`[改名检测缓存] QQ(${bind.qqId}) 用户名无变更: ${updatedBind.mcUsername}`);
+                }
+                // 更新返回对象的缓存字段
+                updatedBind.usernameLastChecked = now;
+                updatedBind.usernameCheckFailCount = 0;
+            }
+            else {
+                // 检测失败��API失败或返回null）
+                const newFailCount = failCount + 1;
+                await mcidbindRepo.update(bind.qqId, {
+                    usernameLastChecked: now,
+                    usernameCheckFailCount: newFailCount
+                });
+                logger.warn(`[改名检测缓存] QQ(${bind.qqId}) 检测失败，失败计数: ${newFailCount}`);
+                // 更新返回对象的缓存字段
+                updatedBind.usernameLastChecked = now;
+                updatedBind.usernameCheckFailCount = newFailCount;
+            }
+            return updatedBind;
+        }
+        catch (error) {
+            logger.error(`[改名检测缓存] 检查和更新用户名失败: ${error.message}`);
+            // 失败时也更新检查时间和递增失败计数
+            try {
+                const failCount = bind.usernameCheckFailCount || 0;
+                await mcidbindRepo.update(bind.qqId, {
+                    usernameLastChecked: new Date(),
+                    usernameCheckFailCount: failCount + 1
+                });
+            }
+            catch (updateError) {
+                logger.error(`[改名检测缓存] 更新失败计数时出错: ${updateError.message}`);
+            }
+            return bind;
+        }
+    };
     // 安全地替换命令模板
     const safeCommandReplace = (template, mcid) => {
         // 过滤可能导致命令注入的字符
@@ -1773,41 +1787,11 @@ function apply(ctx, config) {
             const lowerServerName = serverName.toLowerCase().trim();
             // 最小相似度阈值，低于此值的匹配结果将被忽略
             const MIN_SIMILARITY = 0.6; // 60%的相似度
-            // 计算Levenshtein距离的函数
-            const levenshteinDistance = (str1, str2) => {
-                const matrix = [];
-                for (let i = 0; i <= str2.length; i++) {
-                    matrix[i] = [i];
-                }
-                for (let j = 0; j <= str1.length; j++) {
-                    matrix[0][j] = j;
-                }
-                for (let i = 1; i <= str2.length; i++) {
-                    for (let j = 1; j <= str1.length; j++) {
-                        if (str2.charAt(i - 1) === str1.charAt(j - 1)) {
-                            matrix[i][j] = matrix[i - 1][j - 1];
-                        }
-                        else {
-                            matrix[i][j] = Math.min(matrix[i - 1][j - 1] + 1, // 替换
-                            matrix[i][j - 1] + 1, // 插入
-                            matrix[i - 1][j] + 1 // 删除
-                            );
-                        }
-                    }
-                }
-                return matrix[str2.length][str1.length];
-            };
-            // 计算相似度（0到1之间，1表示完全相同）
-            const calculateSimilarity = (str1, str2) => {
-                const distance = levenshteinDistance(str1, str2);
-                const maxLength = Math.max(str1.length, str2.length);
-                return 1 - distance / maxLength;
-            };
             // 查找最相似的服务器名称
             let bestMatch = null;
             let bestSimilarity = 0;
             for (const s of enabledServers) {
-                const similarity = calculateSimilarity(lowerServerName, s.name.toLowerCase().trim());
+                const similarity = (0, helpers_1.calculateSimilarity)(lowerServerName, s.name.toLowerCase().trim());
                 if (similarity > bestSimilarity && similarity >= MIN_SIMILARITY) {
                     bestSimilarity = similarity;
                     bestMatch = s;
@@ -1861,10 +1845,30 @@ function apply(ctx, config) {
         checkCooldown,
         getCrafatarUrl,
         getStarlightSkinUrl,
+        // Database operations (for McidCommandHandler)
+        getMcBindByQQId,
+        getMcBindByUsername,
+        createOrUpdateMcBind,
+        deleteMcBind,
+        checkUsernameExists,
+        checkAndUpdateUsername,
+        checkAndUpdateUsernameWithCache,
+        // API operations
+        validateUsername,
+        validateBUID,
+        updateBuidInfoOnly,
+        // Permission check functions
+        isAdmin,
+        isMaster,
         // Business functions
         sendMessage,
         autoSetGroupNickname,
+        checkNicknameFormat,
         getBindInfo: getMcBindByQQId,
+        // Config operations
+        getServerConfigById,
+        // Error handling
+        getFriendlyErrorMessage: error_utils_1.getFriendlyErrorMessage,
         // Service instances
         rconManager,
         messageUtils,
@@ -1889,49 +1893,9 @@ function apply(ctx, config) {
     tagHandler.register();
     whitelistHandler.register();
     buidHandler.register();
-    // =========== MC命令组 ===========
-    const cmd = ctx.command('mcid', 'Minecraft 账号绑定管理');
-    // 创建McidHandler的依赖对象
-    const mcidHandlerDeps = {
-        config,
-        logger: loggerService,
-        mcidbindRepo,
-        groupExporter,
-        // 辅助函数依赖
-        normalizeQQId,
-        formatCommand,
-        formatUuid,
-        checkCooldown,
-        getCrafatarUrl,
-        getStarlightSkinUrl,
-        // 数据库操作
-        getMcBindByQQId,
-        getMcBindByUsername,
-        createOrUpdateMcBind,
-        deleteMcBind,
-        checkUsernameExists,
-        checkAndUpdateUsername,
-        // API操作
-        validateUsername,
-        validateBUID,
-        updateBuidInfoOnly,
-        // 权限检查
-        isAdmin,
-        isMaster,
-        // 消息操作
-        sendMessage,
-        autoSetGroupNickname,
-        checkNicknameFormat,
-        // 会话管理
-        removeBindingSession,
-        // 服务器配置
-        getServerConfigById,
-        // 工具函数
-        getFriendlyErrorMessage
-    };
     // 实例化McidCommandHandler并注册命令
-    const mcidHandler = new handlers_1.McidCommandHandler(ctx, mcidHandlerDeps);
-    mcidHandler.registerCommands(cmd);
+    const mcidHandler = new handlers_1.McidCommandHandler(ctx, config, loggerService, repositories, handlerDependencies);
+    mcidHandler.register();
     // 自定义文本前缀匹配
     if (config.allowTextPrefix && config.botNickname) {
         // 创建一个前缀匹配器
@@ -2303,7 +2267,7 @@ function apply(ctx, config) {
             }
         }
         // 检查用户名是否已被其他人绑定
-        if (await checkUsernameExists(username, session.userId)) {
+        if (await checkUsernameExists(username, session.userId, uuid)) {
             logger.warn(`[交互绑定] MC用户名"${username}"已被其他用户绑定`);
             await sendMessage(session, [koishi_1.h.text(`❌ 用户名 ${username} 已被其他用户绑定\n\n请输入其他MC用户名或发送"跳过"完成绑定`)]);
             return;

package/lib/repositories/mcidbind.repository.d.ts

@@ -16,11 +16,23 @@ export declare class MCIDBINDRepository {
      */
     findByQQId(qqId: string): Promise<MCIDBIND | null>;
     /**
-     * 根据 MC 用户名查询绑定信息
+     * 根据 MC 用户名查询绑定信息（精确匹配）
      * @param mcUsername MC用户名
      * @returns 绑定信息或 null
      */
     findByMCUsername(mcUsername: string): Promise<MCIDBIND | null>;
+    /**
+     * 根据 MC 用户名查询绑定信息（不区分大小写）
+     * @param mcUsername MC用户名
+     * @returns 绑定信息或 null
+     */
+    findByUsernameIgnoreCase(mcUsername: string): Promise<MCIDBIND | null>;
+    /**
+     * 根据 MC UUID 查询绑定信息
+     * @param mcUuid MC UUID（可带或不带连字符）
+     * @returns 绑定信息或 null
+     */
+    findByUuid(mcUuid: string): Promise<MCIDBIND | null>;
     /**
      * 根据 B站 UID 查询绑定信息
      * @param buidUid B站UID

package/lib/repositories/mcidbind.repository.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MCIDBINDRepository = void 0;
+const helpers_1 = require("../utils/helpers");
 /**
  * MCIDBIND 数据仓储类
  * 封装所有 MCIDBIND 表的数据库操作
@@ -29,7 +30,7 @@ class MCIDBINDRepository {
         }
     }
     /**
-     * 根据 MC 用户名查询绑定信息
+     * 根据 MC 用户名查询绑定信息（精确匹配）
      * @param mcUsername MC用户名
      * @returns 绑定信息或 null
      */
@@ -44,6 +45,54 @@ class MCIDBINDRepository {
             return null;
         }
     }
+    /**
+     * 根据 MC 用户名查询绑定信息（不区分大小写）
+     * @param mcUsername MC用户名
+     * @returns 绑定信息或 null
+     */
+    async findByUsernameIgnoreCase(mcUsername) {
+        try {
+            const normalizedInput = (0, helpers_1.normalizeUsername)(mcUsername, this.logger.getRawLogger());
+            this.logger.debug('数据库', `查询MC用户名(${mcUsername} -> ${normalizedInput})的绑定信息（不区分大小写）`);
+            // 获取所有绑定记录，然后在应用层过滤（因为 Koishi 数据库不支持不区分大小写查询）
+            const allBinds = await this.ctx.database.get('mcidbind', {});
+            const match = allBinds.find(bind => bind.mcUsername && (0, helpers_1.normalizeUsername)(bind.mcUsername) === normalizedInput);
+            return match || null;
+        }
+        catch (error) {
+            this.logger.error('数据库', `查询MC用户名(${mcUsername})绑定信息失败（不区分大小写）: ${error.message}`);
+            return null;
+        }
+    }
+    /**
+     * 根据 MC UUID 查询绑定信息
+     * @param mcUuid MC UUID（可带或不带连字符）
+     * @returns 绑定信息或 null
+     */
+    async findByUuid(mcUuid) {
+        try {
+            // 规范化 UUID（移除连字符）
+            const cleanUuid = mcUuid.replace(/-/g, '');
+            this.logger.debug('数据库', `查询MC UUID(${cleanUuid})的绑定信息`);
+            // 先尝试精确匹配
+            let binds = await this.ctx.database.get('mcidbind', { mcUuid: cleanUuid });
+            if (binds.length > 0)
+                return binds[0];
+            // 尝试带连字符的格式
+            const formattedUuid = `${cleanUuid.substring(0, 8)}-${cleanUuid.substring(8, 12)}-${cleanUuid.substring(12, 16)}-${cleanUuid.substring(16, 20)}-${cleanUuid.substring(20)}`;
+            binds = await this.ctx.database.get('mcidbind', { mcUuid: formattedUuid });
+            if (binds.length > 0)
+                return binds[0];
+            // 如果都没有，在应用层过滤（去除连字符后比较）
+            const allBinds = await this.ctx.database.get('mcidbind', {});
+            const match = allBinds.find(bind => bind.mcUuid && bind.mcUuid.replace(/-/g, '') === cleanUuid);
+            return match || null;
+        }
+        catch (error) {
+            this.logger.error('数据库', `查询MC UUID(${mcUuid})绑定信息失败: ${error.message}`);
+            return null;
+        }
+    }
     /**
      * 根据 B站 UID 查询绑定信息
      * @param buidUid B站UID

package/lib/types/database.d.ts

@@ -9,6 +9,8 @@ export interface MCIDBIND {
     qqId: string;
     mcUsername: string;
     mcUuid: string;
+    usernameLastChecked?: Date;
+    usernameCheckFailCount?: number;
     lastModified: Date;
     isAdmin: boolean;
     whitelist: string[];

package/lib/utils/error-utils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * 错误处理工具函数集合
+ * 提供统一的错误信息格式化和分类功能
+ */
+/**
+ * 获取用户友好的错误信息
+ * 将技术性错误转换为用户可理解的提示
+ * @param error 错误对象或错误消息字符串
+ * @returns 格式化后的用户友好错误信息
+ */
+export declare function getFriendlyErrorMessage(error: Error | string): string;
+/**
+ * 提取用户友好的错误信息
+ * 根据错误消息内容返回对应的用户提示
+ * @param errorMsg 原始错误消息
+ * @returns 用户可理解的错误提示
+ */
+export declare function getUserFacingErrorMessage(errorMsg: string): string;
+/**
+ * 判断是否为警告级别错误（用户可能输入有误）
+ * @param errorMsg 错误消息
+ * @returns 是否为警告级别错误
+ */
+export declare function isWarningError(errorMsg: string): boolean;
+/**
+ * 判断是否为严重错误（系统问题）
+ * @param errorMsg 错误消息
+ * @returns 是否为严重错误
+ */
+export declare function isCriticalError(errorMsg: string): boolean;