koishi-plugin-bind-bot 2.1.0 → 2.1.2

package/lib/types/database.d.ts

@@ -4,27 +4,77 @@
  */
 /**
  * MCIDBIND表结构 - MC和B站账号绑定主表
+ *
+ * @remarks
+ * 该表存储用户的 Minecraft 账号和 B站账号绑定信息
+ * - 使用 qqId 作为主键
+ * - mcUsername 具有唯一性约束
+ * - 支持单独绑定 MC 或 B站账号
+ *
+ * @example
+ * ```typescript
+ * {
+ *   qqId: '12345678',
+ *   mcUsername: 'Notch',
+ *   mcUuid: '069a79f4-44e9-4726-a5be-fca90e38aaf5',
+ *   lastModified: new Date(),
+ *   isAdmin: false,
+ *   whitelist: ['survival', 'creative'],
+ *   tags: ['VIP', '建筑师'],
+ *   buidUid: '87654321',
+ *   buidUsername: 'B站用户名',
+ *   guardLevel: 3,
+ *   guardLevelText: '舰长',
+ *   maxGuardLevel: 3,
+ *   maxGuardLevelText: '舰长',
+ *   medalName: '粉丝牌',
+ *   medalLevel: 20,
+ *   wealthMedalLevel: 15,
+ *   lastActiveTime: new Date(),
+ *   reminderCount: 0
+ * }
+ * ```
  */
 export interface MCIDBIND {
+    /** 纯QQ号 (作为主键, 不包含 'qq:' 前缀) */
     qqId: string;
+    /** MC用户名 (具有唯一性约束) */
     mcUsername: string;
+    /** MC UUID (格式: 带连字符的标准UUID) */
     mcUuid: string;
+    /** MC用户名上次检查时间 (用于改名检测缓存) */
     usernameLastChecked?: Date;
+    /** 用户名检查失败次数 (连续失败计数, 失败≥3次延长冷却期至72小时) */
     usernameCheckFailCount?: number;
+    /** 上次修改时间 (绑定/解绑操作的时间戳) */
     lastModified: Date;
+    /** 是否为MC绑定管理员 (拥有管理员权限) */
     isAdmin: boolean;
+    /** 已添加白名单的服务器ID列表 */
     whitelist: string[];
+    /** 用户标签列表 (用于分类管理) */
     tags: string[];
+    /** B站UID */
     buidUid: string;
+    /** B站用户名 */
     buidUsername: string;
+    /** 当前舰长等级 (0=无, 1=总督, 2=提督, 3=舰长) */
     guardLevel: number;
+    /** 当前舰长等级文本 (例: '舰长', '提督', '总督') */
     guardLevelText: string;
+    /** 历史最高舰长等级 */
     maxGuardLevel: number;
+    /** 历史最高舰长等级文本 */
     maxGuardLevelText: string;
+    /** 粉丝牌名称 */
     medalName: string;
+    /** 粉丝牌等级 */
     medalLevel: number;
+    /** 荣耀等级 (财富勋章等级) */
     wealthMedalLevel: number;
+    /** 最后活跃时间 (B站活跃时间) */
     lastActiveTime: Date;
+    /** 随机提醒次数 (用于天选时刻等功能) */
     reminderCount: number;
 }
 /**

package/lib/types/update-data.d.ts

@@ -3,43 +3,126 @@
  */
 /**
  * MC绑定更新数据接口
+ *
+ * @remarks
+ * 用于更新 MCIDBIND 表中的 MC 相关字段
+ * 所有字段都是可选的，只更新提供的字段
+ *
+ * @example
+ * ```typescript
+ * // 仅更新用户名
+ * {
+ *   mcUsername: 'NewUsername'
+ * }
+ *
+ * // 更新用户名和UUID
+ * {
+ *   mcUsername: 'NewUsername',
+ *   mcUuid: '069a79f4-44e9-4726-a5be-fca90e38aaf5',
+ *   lastModified: new Date()
+ * }
+ * ```
  */
 export interface UpdateMcBindData {
+    /** MC用户名 */
     mcUsername?: string;
+    /** MC UUID */
     mcUuid?: string;
+    /** 上次修改时间 */
     lastModified?: Date;
+    /** 是否为管理员 */
     isAdmin?: boolean;
+    /** 用户名上次检查时间 */
     usernameLastChecked?: Date;
+    /** 用户名检查失败次数 */
     usernameCheckFailCount?: number;
 }
 /**
  * BUID绑定更新数据接口（完整更新）
+ *
+ * @remarks
+ * 用于更新 MCIDBIND 表中的 B站相关字段
+ * 该接口会同时更新 lastModified 字段，表示绑定操作时间
+ *
+ * @see {@link UpdateBuidInfoData} 仅刷新信息不更新 lastModified
+ *
+ * @example
+ * ```typescript
+ * {
+ *   buidUid: '87654321',
+ *   buidUsername: 'B站用户名',
+ *   guardLevel: 3,
+ *   guardLevelText: '舰长',
+ *   maxGuardLevel: 3,
+ *   maxGuardLevelText: '舰长',
+ *   medalName: '粉丝牌',
+ *   medalLevel: 20,
+ *   wealthMedalLevel: 15,
+ *   lastActiveTime: new Date(),
+ *   lastModified: new Date()
+ * }
+ * ```
  */
 export interface UpdateBuidBindData {
+    /** B站UID (数据库中存储为字符串) */
     buidUid?: string;
+    /** B站用户名 */
     buidUsername?: string;
+    /** 当前舰长等级 */
     guardLevel?: number;
+    /** 当前舰长等级文本 */
     guardLevelText?: string;
+    /** 历史最高舰长等级 */
     maxGuardLevel?: number;
+    /** 历史最高舰长等级文本 */
     maxGuardLevelText?: string;
+    /** 粉丝牌名称 */
     medalName?: string;
+    /** 粉丝牌等级 */
     medalLevel?: number;
+    /** 荣耀等级 */
     wealthMedalLevel?: number;
+    /** 最后活跃时间 */
     lastActiveTime?: Date;
+    /** 上次修改时间 (绑定操作时间) */
     lastModified?: Date;
 }
 /**
  * BUID信息更新数据接口（仅更新信息，不更新lastModified）
+ *
+ * @remarks
+ * 用于查询时刷新 B站信息，不影响绑定时间
+ * 与 {@link UpdateBuidBindData} 的区别是不包含 lastModified 字段
+ *
+ * @example
+ * ```typescript
+ * // 查询时刷新B站信息
+ * {
+ *   buidUsername: '新用户名',
+ *   guardLevel: 3,
+ *   guardLevelText: '舰长',
+ *   medalLevel: 21
+ * }
+ * ```
  */
 export interface UpdateBuidInfoData {
+    /** B站用户名 */
     buidUsername?: string;
+    /** 当前舰长等级 */
     guardLevel?: number;
+    /** 当前舰长等级文本 */
     guardLevelText?: string;
+    /** 历史最高舰长等级 */
     maxGuardLevel?: number;
+    /** 历史最高舰长等级文本 */
     maxGuardLevelText?: string;
+    /** 粉丝牌名称 */
     medalName?: string;
+    /** 粉丝牌等级 */
     medalLevel?: number;
+    /** 荣耀等级 */
     wealthMedalLevel?: number;
+    /** 最后活跃时间 */
     lastActiveTime?: Date;
 }
 /**

package/lib/utils/error-utils.js

@@ -51,10 +51,14 @@ function getUserFacingErrorMessage(errorMsg) {
     }
     // RCON相关错误
     if (errorMsg.includes('RCON') || errorMsg.includes('服务器')) {
-        if (errorMsg.includes('authentication') || errorMsg.includes('auth') || errorMsg.includes('认证')) {
+        if (errorMsg.includes('authentication') ||
+            errorMsg.includes('auth') ||
+            errorMsg.includes('认证')) {
             return 'RCON认证失败，服务器拒绝访问，请联系管理员检查密码';
         }
-        if (errorMsg.includes('ECONNREFUSED') || errorMsg.includes('ETIMEDOUT') || errorMsg.includes('无法连接')) {
+        if (errorMsg.includes('ECONNREFUSED') ||
+            errorMsg.includes('ETIMEDOUT') ||
+            errorMsg.includes('无法连接')) {
             return '无法连接到游戏服务器，请确认服务器是否在线或联系管理员';
         }
         if (errorMsg.includes('command') || errorMsg.includes('执行命令')) {
@@ -101,11 +105,6 @@ function isWarningError(errorMsg) {
  * @returns 是否为严重错误
  */
 function isCriticalError(errorMsg) {
-    const criticalPatterns = [
-        '无法连接',
-        'RCON认证失败',
-        '服务器通信失败',
-        '数据库操作出错'
-    ];
+    const criticalPatterns = ['无法连接', 'RCON认证失败', '服务器通信失败', '数据库操作出错'];
     return criticalPatterns.some(pattern => errorMsg.includes(pattern));
 }

package/lib/utils/helpers.js

@@ -32,7 +32,7 @@ exports.extractBuidUsernameFromNickname = extractBuidUsernameFromNickname;
 function normalizeQQId(userId, logger) {
     // 处理空值情况
     if (!userId) {
-        logger?.warn(`[用户ID] 收到空用户ID`);
+        logger?.warn('[用户ID] 收到空用户ID');
         return '';
     }
     let extractedId = '';
@@ -165,7 +165,7 @@ function getStarlightSkinUrl(username, logger) {
         'dungeons', // 地下城风格
         'facepalm', // 捂脸
         'mojavatar', // Mojave姿态
-        'head', // 头部特写
+        'head' // 头部特写
     ];
     // 随机选择一个动作
     const randomPose = poses[Math.floor(Math.random() * poses.length)];
@@ -186,7 +186,39 @@ function checkIrrelevantInput(state, content) {
     if (!content)
         return false;
     // 常见的聊天用语或明显无关的内容
-    const chatKeywords = ['你好', 'hello', 'hi', '在吗', '在不在', '怎么样', '什么', '为什么', '好的', '谢谢', '哈哈', '呵呵', '早上好', '晚上好', '晚安', '再见', '拜拜', '666', '牛', '厉害', '真的吗', '不是吧', '哇', '哦', '嗯', '好吧', '行', '可以', '没事', '没问题', '没关系'];
+    const chatKeywords = [
+        '你好',
+        'hello',
+        'hi',
+        '在吗',
+        '在不在',
+        '怎么样',
+        '什么',
+        '为什么',
+        '好的',
+        '谢谢',
+        '哈哈',
+        '呵呵',
+        '早上好',
+        '晚上好',
+        '晚安',
+        '再见',
+        '拜拜',
+        '666',
+        '牛',
+        '厉害',
+        '真的吗',
+        '不是吧',
+        '哇',
+        '哦',
+        '嗯',
+        '好吧',
+        '行',
+        '可以',
+        '没事',
+        '没问题',
+        '没关系'
+    ];
     const lowercaseContent = content.toLowerCase();
     // 检查是否包含明显的聊天用语
     if (chatKeywords.some(keyword => lowercaseContent.includes(keyword))) {
@@ -212,7 +244,10 @@ function checkIrrelevantInput(state, content) {
             return true;
         }
         // 如果是明显的指令格式
-        if (content.startsWith('.') || content.startsWith('/') || content.startsWith('mcid') || content.startsWith('buid')) {
+        if (content.startsWith('.') ||
+            content.startsWith('/') ||
+            content.startsWith('mcid') ||
+            content.startsWith('buid')) {
             return true;
         }
     }
@@ -230,7 +265,10 @@ function checkIrrelevantInput(state, content) {
                 return true;
             }
             // 如果是明显的指令格式
-            if (content.startsWith('.') || content.startsWith('/') || content.startsWith('mcid') || content.startsWith('buid')) {
+            if (content.startsWith('.') ||
+                content.startsWith('/') ||
+                content.startsWith('mcid') ||
+                content.startsWith('buid')) {
                 return true;
             }
         }
@@ -265,7 +303,7 @@ function cleanUserInput(content, session, botNickname, logger) {
         // @Bot昵称 格式（如果配置了botNickname）
         botNickname ? new RegExp(`^@${escapeRegExp(botNickname)}\\s+`, 'i') : null,
         // @botUserId 格式
-        new RegExp(`^@${escapeRegExp(botUserId)}\\s+`, 'i'),
+        new RegExp(`^@${escapeRegExp(botUserId)}\\s+`, 'i')
     ].filter(Boolean);
     let cleanedContent = content.trim();
     // 尝试匹配并移除@Bot前缀
@@ -333,7 +371,7 @@ function calculateSimilarity(str1, str2) {
  */
 function normalizeUsername(username, logger) {
     if (!username) {
-        logger?.warn(`[用户名规范化] 收到空用户名`);
+        logger?.warn('[用户名规范化] 收到空用户名');
         return '';
     }
     // 移除首尾空格

package/lib/utils/message-utils.js

@@ -47,8 +47,12 @@ class MessageUtils {
             // 处理私聊和群聊的消息格式
             // 主动消息不引用原消息
             const promptMessage = session.channelId?.startsWith('private:')
-                ? (isProactiveMessage ? content : [koishi_1.h.quote(session.messageId), ...content])
-                : (isProactiveMessage ? [koishi_1.h.at(normalizedQQId), '\n', ...content] : [koishi_1.h.quote(session.messageId), koishi_1.h.at(normalizedQQId), '\n', ...content]);
+                ? isProactiveMessage
+                    ? content
+                    : [koishi_1.h.quote(session.messageId), ...content]
+                : isProactiveMessage
+                    ? [koishi_1.h.at(normalizedQQId), '\n', ...content]
+                    : [koishi_1.h.quote(session.messageId), koishi_1.h.at(normalizedQQId), '\n', ...content];
             // 发送消息并获取返回的消息ID
             const messageResult = await session.send(promptMessage);
             this.logger.debug('消息', `成功向QQ(${normalizedQQId})发送消息，频道: ${session.channelId}`);
@@ -58,11 +62,18 @@ class MessageUtils {
                 // 但如果用户在绑定会话中发送聊天消息（不包括指令），不撤回
                 // 主动消息不撤回用户消息
                 const bindingSession = this.getBindingSessionFn(session.userId, session.channelId);
-                const isBindingCommand = session.content && (session.content.trim() === '绑定' ||
-                    session.content.includes('@') && session.content.includes('绑定'));
-                const shouldNotRecallUserMessage = bindingSession && session.content &&
-                    !isBindingCommand && (0, helpers_1.checkIrrelevantInput)(bindingSession.state, session.content.trim());
-                if (this.config.recallUserMessage && isGroupMessage && session.messageId && !shouldNotRecallUserMessage && !isProactiveMessage) {
+                const isBindingCommand = session.content &&
+                    (session.content.trim() === '绑定' ||
+                        (session.content.includes('@') && session.content.includes('绑定')));
+                const shouldNotRecallUserMessage = bindingSession &&
+                    session.content &&
+                    !isBindingCommand &&
+                    (0, helpers_1.checkIrrelevantInput)(bindingSession.state, session.content.trim());
+                if (this.config.recallUserMessage &&
+                    isGroupMessage &&
+                    session.messageId &&
+                    !shouldNotRecallUserMessage &&
+                    !isProactiveMessage) {
                     setTimeout(async () => {
                         try {
                             await session.bot.deleteMessage(session.channelId, session.messageId);
@@ -78,7 +89,7 @@ class MessageUtils {
                     this.logger.debug('消息', `QQ(${normalizedQQId})在绑定会话中发送聊天消息，跳过撤回用户消息`);
                 }
                 else if (isProactiveMessage) {
-                    this.logger.debug('消息', `主动发送的消息，跳过撤回用户消息`);
+                    this.logger.debug('消息', '主动发送的消息，跳过撤回用户消息');
                 }
                 // 处理撤回机器人消息 - 只在群聊中撤回机器人自己的消息
                 // 检查是否为不应撤回的重要提示消息（只有绑定会话超时提醒）
@@ -105,9 +116,10 @@ class MessageUtils {
                     }
                     else if (messageResult && typeof messageResult === 'object') {
                         // 尝试提取各种可能的消息ID格式
-                        messageId = messageResult.messageId ||
-                            messageResult.id ||
-                            messageResult.message_id;
+                        messageId =
+                            messageResult.messageId ||
+                                messageResult.id ||
+                                messageResult.message_id;
                     }
                     if (messageId) {
                         // 设置定时器延迟撤回
@@ -123,11 +135,11 @@ class MessageUtils {
                         this.logger.debug('消息', `已设置 ${this.config.autoRecallTime} 秒后自动撤回机器人消息 ${messageId}`);
                     }
                     else {
-                        this.logger.warn('消息', `无法获取消息ID，自动撤回功能无法生效`);
+                        this.logger.warn('消息', '无法获取消息ID，自动撤回功能无法生效');
                     }
                 }
                 else {
-                    this.logger.debug('消息', `检测到私聊消息，不撤回机器人回复`);
+                    this.logger.debug('消息', '检测到私聊消息，不撤回机器人回复');
                 }
             }
         }
@@ -151,7 +163,7 @@ class MessageUtils {
             const actualUserId = targetUserId || session.userId;
             const normalizedUserId = (0, helpers_1.normalizeQQId)(actualUserId);
             // 根据MC绑定状态设置不同的格式（临时用户名视为未绑定）
-            const mcInfo = (mcUsername && !mcUsername.startsWith('_temp_')) ? mcUsername : "未绑定";
+            const mcInfo = mcUsername && !mcUsername.startsWith('_temp_') ? mcUsername : '未绑定';
             let currentBuidUsername = buidUsername;
             const newNickname = `${currentBuidUsername}（ID:${mcInfo}）`;
             // 使用指定的群ID，如果没有指定则使用配置的默认群ID
@@ -184,30 +196,31 @@ class MessageUtils {
                                 this.logger.debug('群昵称设置', `API返回B站用户名: "${latestBuidUser.username}"`);
                                 // 2. 智能三层判断
                                 // 情况A: API返回 == 当前群昵称中的名称
-                                if (currentNicknameUsername && latestBuidUser.username === currentNicknameUsername) {
+                                if (currentNicknameUsername &&
+                                    latestBuidUser.username === currentNicknameUsername) {
                                     this.logger.info('群昵称设置', `✅ 当前群昵称"${currentNickname}"已包含正确的B站名称"${currentNicknameUsername}"`);
                                     // 群昵称已经正确，仅需更新数据库（如果数据库是旧的）
                                     if (latestBuidUser.username !== buidUsername) {
                                         this.logger.info('群昵称设置', `数据库中的B站名称需要更新: "${buidUsername}" → "${latestBuidUser.username}"`);
                                         try {
                                             await this.updateBuidInfoOnly(normalizedUserId, latestBuidUser);
-                                            this.logger.info('群昵称设置', `已更新数据库中的B站用户名`);
+                                            this.logger.info('群昵称设置', '已更新数据库中的B站用户名');
                                         }
                                         catch (updateError) {
                                             this.logger.warn('群昵称设置', `更新数据库失败: ${updateError.message}`);
                                         }
                                     }
                                     else {
-                                        this.logger.debug('群昵称设置', `数据库中的B站名称已是最新，无需更新`);
+                                        this.logger.debug('群昵称设置', '数据库中的B站名称已是最新，无需更新');
                                     }
                                     // 跳过群昵称修改
-                                    this.logger.info('群昵称设置', `群昵称格式正确且名称最新，跳过修改`);
+                                    this.logger.info('群昵称设置', '群昵称格式正确且名称最新，跳过修改');
                                     return;
                                 }
                                 // 情况B: API返回 == 数据库（都是旧的）
                                 if (latestBuidUser.username === buidUsername) {
                                     this.logger.warn('群昵称设置', `⚠️ API返回的B站名称"${latestBuidUser.username}"与数据库一致，但与群昵称不符`);
-                                    this.logger.warn('群昵称设置', `可能是API缓存未刷新，采用保守策略：不修改群昵称`);
+                                    this.logger.warn('群昵称设置', '可能是API缓存未刷新，采用保守策略：不修改群昵称');
                                     return;
                                 }
                                 // 情况C: API返回新数据（!= 群昵称 且 != 数据库）
@@ -258,7 +271,7 @@ class MessageUtils {
                     // 如果获取当前昵称失败，直接尝试设置新昵称
                     this.logger.warn('群昵称设置', `获取QQ(${normalizedUserId})当前群昵称失败: ${getInfoError.message}`);
                     this.logger.warn('群昵称设置', `错误详情: ${JSON.stringify(getInfoError)}`);
-                    this.logger.debug('群昵称设置', `将直接尝试设置新昵称...`);
+                    this.logger.debug('群昵称设置', '将直接尝试设置新昵称...');
                     // 如果传入了 buidUid，尝试获取最新的B站用户信息
                     if (buidUid && this.validateBUID && this.updateBuidInfoOnly) {
                         this.logger.debug('群昵称设置', `尝试获取B站UID ${buidUid} 的最新信息...`);
@@ -269,7 +282,7 @@ class MessageUtils {
                                 // 智能判断：API返回 == 数据库（都是旧的）
                                 if (latestBuidUser.username === buidUsername) {
                                     this.logger.warn('群昵称设置', `⚠️ API返回的B站名称"${latestBuidUser.username}"与数据库一致`);
-                                    this.logger.warn('群昵称设置', `可能是API缓存未刷新，且无法获取当前群昵称，采用保守策略：跳过修改`);
+                                    this.logger.warn('群昵称设置', '可能是API缓存未刷新，且无法获取当前群昵称，采用保守策略：跳过修改');
                                     return;
                                 }
                                 // API返回新数据（!= 数据库）
@@ -285,7 +298,7 @@ class MessageUtils {
                                 }
                             }
                             else {
-                                this.logger.warn('群昵称设置', `获取最新B站用户信息失败`);
+                                this.logger.warn('群昵称设置', '获取最新B站用户信息失败');
                             }
                         }
                         catch (validateError) {
@@ -307,7 +320,7 @@ class MessageUtils {
                             }
                             else {
                                 this.logger.warn('群昵称设置', `⚠️ 验证失败，期望"${nicknameToSet}"，实际"${verifyNickname}"，可能是权限不足`);
-                                this.logger.warn('群昵称设置', `建议检查: 1.机器人是否为群管理员 2.群设置是否允许管理员修改昵称 3.OneBot实现是否支持该功能`);
+                                this.logger.warn('群昵称设置', '建议检查: 1.机器人是否为群管理员 2.群设置是否允许管理员修改昵称 3.OneBot实现是否支持该功能');
                             }
                         }
                         catch (verifyError) {

package/lib/utils/session-manager.js

@@ -48,7 +48,12 @@ class SessionManager {
             // 发送超时消息，@用户
             const normalizedUser = (0, helpers_1.normalizeQQId)(userId);
             this.ctx.bots.forEach(bot => {
-                bot.sendMessage(channelId, [koishi_1.h.at(normalizedUser), koishi_1.h.text(' 绑定会话已超时，请重新开始绑定流程\n\n⚠️ 温馨提醒：若在管理员多次提醒后仍不配合绑定账号信息，将按群规进行相应处理。')]).catch(() => { });
+                bot
+                    .sendMessage(channelId, [
+                    koishi_1.h.at(normalizedUser),
+                    koishi_1.h.text(' 绑定会话已超时，请重新开始绑定流程\n\n⚠️ 温馨提醒：若在管理员多次提醒后仍不配合绑定账号信息，将按群规进行相应处理。')
+                ])
+                    .catch(() => { });
             });
             this.logger.info('交互绑定', `QQ(${normalizedUser})的绑定会话因超时被清理`, true);
         }, this.sessionTimeout);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-bind-bot",
   "description": "[WittF自用] BIND-BOT - 账号绑定管理机器人，支持Minecraft账号和B站账号绑定与管理。",
-  "version": "2.1.0",
+  "version": "2.1.2",
   "main": "lib/index.js",
   "typings": "lib/index.d.ts",
   "files": [
@@ -9,7 +9,8 @@
   ],
   "license": "CC-BY-NC-SA-4.0",
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "lint:fix": "eslint src --ext .ts --fix && prettier --write \"src/**/*.ts\""
   },
   "keywords": [
     "chatbot",
@@ -25,7 +26,16 @@
     }
   },
   "devDependencies": {
+    "@types/jest": "^30.0.0",
     "@types/node": "^20.10.0",
+    "@typescript-eslint/eslint-plugin": "^8.46.2",
+    "@typescript-eslint/parser": "^8.46.2",
+    "eslint": "^9.38.0",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
+    "jest": "^30.2.0",
+    "prettier": "^3.6.2",
+    "ts-jest": "^29.4.5",
     "typescript": "^5.5.4"
   },
   "peerDependencies": {