koishi-plugin-bind-bot 2.1.0 → 2.1.2

package/lib/repositories/mcidbind.repository.js

@@ -197,7 +197,7 @@ class MCIDBINDRepository {
      */
     async deleteAll() {
         try {
-            this.logger.debug('数据库', `删除所有绑定记录`);
+            this.logger.debug('数据库', '删除所有绑定记录');
             const result = await this.ctx.database.remove('mcidbind', {});
             this.logger.info('数据库', `成功删除所有绑定记录（删除${result.removed}条）`, true);
             return result.removed;
@@ -324,7 +324,7 @@ class MCIDBINDRepository {
      */
     async findAllAdmins() {
         try {
-            this.logger.debug('数据库', `获取所有管理员`);
+            this.logger.debug('数据库', '获取所有管理员');
             const allRecords = await this.ctx.database.get('mcidbind', {});
             return allRecords.filter(record => record.isAdmin);
         }

package/lib/repositories/schedule-mute.repository.js

@@ -50,7 +50,7 @@ class ScheduleMuteRepository {
      */
     async findAll() {
         try {
-            this.logger.debug('数据库', `获取所有定时禁言任务`);
+            this.logger.debug('数据库', '获取所有定时禁言任务');
             const tasks = await this.ctx.database.get('schedule_mute_tasks', {});
             return tasks;
         }
@@ -65,7 +65,7 @@ class ScheduleMuteRepository {
      */
     async findAllEnabled() {
         try {
-            this.logger.debug('数据库', `获取所有已启用的定时禁言任务`);
+            this.logger.debug('数据库', '获取所有已启用的定时禁言任务');
             const tasks = await this.ctx.database.get('schedule_mute_tasks', { enabled: true });
             return tasks;
         }

package/lib/services/api.service.js

@@ -28,7 +28,7 @@ class ApiService {
             const response = await axios_1.default.get(`https://api.mojang.com/users/profiles/minecraft/${username}`, {
                 timeout: 10000, // 添加10秒超时
                 headers: {
-                    'User-Agent': 'KoishiMCVerifier/1.0', // 添加User-Agent头
+                    'User-Agent': 'KoishiMCVerifier/1.0' // 添加User-Agent头
                 }
             });
             if (response.status === 200 && response.data) {
@@ -54,13 +54,15 @@ class ApiService {
                     : error.message || '未知错误';
                 this.logger.error('Mojang API', `验证用户名"${username}"时发生错误: ${errorMessage}`);
                 // 如果是网络相关错误，尝试使用备用API检查
-                if (axios_1.default.isAxiosError(error) && (error.code === 'ENOTFOUND' ||
-                    error.code === 'ETIMEDOUT' ||
-                    error.code === 'ECONNRESET' ||
-                    error.code === 'ECONNREFUSED' ||
-                    error.code === 'ECONNABORTED' ||
-                    error.response?.status === 429 || // 添加429 (Too Many Requests)
-                    error.response?.status === 403)) { // 添加403 (Forbidden)
+                if (axios_1.default.isAxiosError(error) &&
+                    (error.code === 'ENOTFOUND' ||
+                        error.code === 'ETIMEDOUT' ||
+                        error.code === 'ECONNRESET' ||
+                        error.code === 'ECONNREFUSED' ||
+                        error.code === 'ECONNABORTED' ||
+                        error.response?.status === 429 || // 添加429 (Too Many Requests)
+                        error.response?.status === 403)) {
+                    // 添加403 (Forbidden)
                     // 尝试使用playerdb.co作为备用API
                     this.logger.info('Mojang API', `遇到错误(${error.code || error.response?.status})，将尝试使用备用API`);
                     return this.tryBackupAPI(username);
@@ -84,7 +86,7 @@ class ApiService {
                     'User-Agent': 'KoishiMCVerifier/1.0'
                 }
             });
-            if (backupResponse.status === 200 && backupResponse.data?.code === "player.found") {
+            if (backupResponse.status === 200 && backupResponse.data?.code === 'player.found') {
                 const playerData = backupResponse.data.data.player;
                 const rawId = playerData.raw_id || playerData.id.replace(/-/g, ''); // 确保使用不带连字符的UUID
                 this.logger.info('备用API', `用户名"${username}"验证成功，UUID: ${rawId}，标准名称: ${playerData.username}`);
@@ -117,7 +119,7 @@ class ApiService {
             const response = await axios_1.default.get(`https://api.mojang.com/user/profile/${cleanUuid}`, {
                 timeout: 10000,
                 headers: {
-                    'User-Agent': 'KoishiMCVerifier/1.0',
+                    'User-Agent': 'KoishiMCVerifier/1.0'
                 }
             });
             if (response.status === 200 && response.data) {
@@ -131,13 +133,15 @@ class ApiService {
         }
         catch (error) {
             // 如果是网络相关错误，尝试使用备用API
-            if (axios_1.default.isAxiosError(error) && (error.code === 'ENOTFOUND' ||
-                error.code === 'ETIMEDOUT' ||
-                error.code === 'ECONNRESET' ||
-                error.code === 'ECONNREFUSED' ||
-                error.code === 'ECONNABORTED' ||
-                error.response?.status === 429 || // 添加429 (Too Many Requests)
-                error.response?.status === 403)) { // 添加403 (Forbidden)
+            if (axios_1.default.isAxiosError(error) &&
+                (error.code === 'ENOTFOUND' ||
+                    error.code === 'ETIMEDOUT' ||
+                    error.code === 'ECONNRESET' ||
+                    error.code === 'ECONNREFUSED' ||
+                    error.code === 'ECONNABORTED' ||
+                    error.response?.status === 429 || // 添加429 (Too Many Requests)
+                    error.response?.status === 403)) {
+                // 添加403 (Forbidden)
                 this.logger.info('Mojang API', `通过UUID查询用户名时遇到错误(${error.code || error.response?.status})，将尝试使用备用API`);
                 return this.getUsernameByUuidBackupAPI(uuid);
             }
@@ -161,10 +165,10 @@ class ApiService {
             const response = await axios_1.default.get(`https://playerdb.co/api/player/minecraft/${formattedUuid}`, {
                 timeout: 10000,
                 headers: {
-                    'User-Agent': 'KoishiMCVerifier/1.0',
+                    'User-Agent': 'KoishiMCVerifier/1.0'
                 }
             });
-            if (response.status === 200 && response.data?.code === "player.found") {
+            if (response.status === 200 && response.data?.code === 'player.found') {
                 const playerData = response.data.data.player;
                 this.logger.debug('备用API', `UUID "${formattedUuid}" 当前用户名: ${playerData.username}`);
                 return playerData.username;
@@ -193,11 +197,13 @@ class ApiService {
                 return null;
             }
             this.logger.debug('B站官方API', `开始查询UID ${uid} 的官方信息`);
-            const response = await axios_1.default.get(`https://api.bilibili.com/x/space/acc/info`, {
+            const response = await axios_1.default.get('https://api.bilibili.com/x/space/acc/info', {
                 params: { mid: uid },
                 timeout: 10000,
                 headers: {
-                    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36'
+                    'User-Agent': 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36',
+                    Referer: 'https://space.bilibili.com/',
+                    Origin: 'https://space.bilibili.com'
                 }
             });
             if (response.data.code === 0 && response.data.data) {
@@ -312,7 +318,7 @@ class ApiService {
             'dungeons', // 地下城风格
             'facepalm', // 捂脸
             'mojavatar', // Mojave姿态
-            'head', // 头部特写
+            'head' // 头部特写
         ];
         // 随机选择一个动作
         const randomPose = poses[Math.floor(Math.random() * poses.length)];

package/lib/services/database.service.js

@@ -27,7 +27,7 @@ class DatabaseService {
         try {
             // 处理空值
             if (!qqId) {
-                this.logger.warn('MCIDBIND', `尝试查询空QQ号`);
+                this.logger.warn('MCIDBIND', '尝试查询空QQ号');
                 return null;
             }
             const normalizedQQId = this.normalizeQQId(qqId);
@@ -45,7 +45,7 @@ class DatabaseService {
     async getMcBindByUsername(mcUsername) {
         // 处理空值
         if (!mcUsername) {
-            this.logger.warn('MCIDBIND', `尝试查询空MC用户名`);
+            this.logger.warn('MCIDBIND', '尝试查询空MC用户名');
             return null;
         }
         // 使用 Repository 查询
@@ -58,16 +58,16 @@ class DatabaseService {
         try {
             // 验证输入参数
             if (!userId) {
-                this.logger.error('MCIDBIND', `创建/更新绑定失败: 无效的用户ID`);
+                this.logger.error('MCIDBIND', '创建/更新绑定失败: 无效的用户ID');
                 return false;
             }
             if (!mcUsername) {
-                this.logger.error('MCIDBIND', `创建/更新绑定失败: 无效的MC用户名`);
+                this.logger.error('MCIDBIND', '创建/更新绑定失败: 无效的MC用户名');
                 return false;
             }
             const normalizedQQId = this.normalizeQQId(userId);
             if (!normalizedQQId) {
-                this.logger.error('MCIDBIND', `创建/更新绑定失败: 无法提取有效的QQ号`);
+                this.logger.error('MCIDBIND', '创建/更新绑定失败: 无法提取有效的QQ号');
                 return false;
             }
             // 查询是否已存在绑定记录
@@ -118,12 +118,12 @@ class DatabaseService {
         try {
             // 验证输入参数
             if (!userId) {
-                this.logger.error('MCIDBIND', `删除绑定失败: 无效的用户ID`);
+                this.logger.error('MCIDBIND', '删除绑定失败: 无效的用户ID');
                 return false;
             }
             const normalizedQQId = this.normalizeQQId(userId);
             if (!normalizedQQId) {
-                this.logger.error('MCIDBIND', `删除绑定失败: 无法提取有效的QQ号`);
+                this.logger.error('MCIDBIND', '删除绑定失败: 无法提取有效的QQ号');
                 return false;
             }
             // 查询是否存在绑定记录
@@ -161,7 +161,7 @@ class DatabaseService {
         try {
             // 验证输入参数
             if (!username) {
-                this.logger.warn('绑定检查', `尝试检查空MC用户名`);
+                this.logger.warn('绑定检查', '尝试检查空MC用户名');
                 return false;
             }
             // 跳过临时用户名的检查
@@ -207,7 +207,7 @@ class DatabaseService {
     async getBuidBindByBuid(buid) {
         try {
             if (!buid) {
-                this.logger.warn('B站账号绑定', `尝试查询空B站UID`);
+                this.logger.warn('B站账号绑定', '尝试查询空B站UID');
                 return null;
             }
             const bind = await this.mcidbindRepo.findByBuidUid(buid);
@@ -245,7 +245,7 @@ class DatabaseService {
         try {
             const normalizedQQId = this.normalizeQQId(userId);
             if (!normalizedQQId) {
-                this.logger.error('B站账号绑定', `创建/更新绑定失败: 无法提取有效的QQ号`);
+                this.logger.error('B站账号绑定', '创建/更新绑定失败: 无法提取有效的QQ号');
                 return false;
             }
             // 检查该UID是否已被其他用户绑定（安全检查）
@@ -266,7 +266,9 @@ class DatabaseService {
                 medalName: buidUser.medal?.name || '',
                 medalLevel: buidUser.medal?.level || 0,
                 wealthMedalLevel: buidUser.wealthMedalLevel || 0,
-                lastActiveTime: buidUser.last_active_time ? new Date(buidUser.last_active_time) : new Date(),
+                lastActiveTime: buidUser.last_active_time
+                    ? new Date(buidUser.last_active_time)
+                    : new Date(),
                 lastModified: new Date()
             };
             if (bind) {
@@ -302,7 +304,7 @@ class DatabaseService {
         try {
             const normalizedQQId = this.normalizeQQId(userId);
             if (!normalizedQQId) {
-                this.logger.error('B站账号信息更新', `更新失败: 无法提取有效的QQ号`);
+                this.logger.error('B站账号信息更新', '更新失败: 无法提取有效的QQ号');
                 return false;
             }
             // 查询是否已存在绑定记录
@@ -339,7 +341,7 @@ class DatabaseService {
     async checkAndUpdateUsername(bind) {
         try {
             if (!bind || !bind.mcUuid) {
-                this.logger.warn('用户名更新', `无法检查用户名更新: 空绑定或空UUID`);
+                this.logger.warn('用户名更新', '无法检查用户名更新: 空绑定或空UUID');
                 return bind;
             }
             // 通过UUID查询最新用户名
@@ -377,7 +379,7 @@ class DatabaseService {
     async checkAndUpdateUsernameWithCache(bind) {
         try {
             if (!bind || !bind.mcUuid) {
-                this.logger.warn('改名检测缓存', `无法检查用户名更新: 空绑定或空UUID`);
+                this.logger.warn('改名检测缓存', '无法检查用户名更新: 空绑定或空UUID');
                 return bind;
             }
             const now = new Date();

package/lib/services/nickname.service.js

@@ -28,7 +28,7 @@ class NicknameService {
         if (!nickname || !buidUsername)
             return false;
         // 期望格式：B站名称（ID:MC用户名）或 B站名称（ID:未绑定）
-        const mcInfo = mcUsername && !mcUsername.startsWith('_temp_') ? mcUsername : "未绑定";
+        const mcInfo = mcUsername && !mcUsername.startsWith('_temp_') ? mcUsername : '未绑定';
         const expectedFormat = `${buidUsername}（ID:${mcInfo}）`;
         return nickname === expectedFormat;
     }
@@ -40,14 +40,14 @@ class NicknameService {
         // 1. 尝试获取B站官方API的用户信息（最权威）
         let officialUsername = null;
         try {
-            this.logger.debug('群昵称设置', `正在查询B站官方API...`);
+            this.logger.debug('群昵称设置', '正在查询B站官方API...');
             const officialInfo = await this.getBilibiliOfficialUserInfo(buidUid);
             if (officialInfo && officialInfo.name) {
                 officialUsername = officialInfo.name;
                 this.logger.info('群昵称设置', `[层1-官方API] ✅ "${officialUsername}"`, true);
             }
             else {
-                this.logger.warn('群昵称设置', `[层1-官方API] ❌ 查询失败`);
+                this.logger.warn('群昵称设置', '[层1-官方API] ❌ 查询失败');
             }
         }
         catch (officialError) {
@@ -56,13 +56,13 @@ class NicknameService {
         // 2. 尝试获取ZMINFO API的用户信息（可能有缓存）
         let zminfoUserData = null;
         try {
-            this.logger.debug('群昵称设置', `正在查询ZMINFO API...`);
+            this.logger.debug('群昵称设置', '正在查询ZMINFO API...');
             zminfoUserData = await this.validateBUID(buidUid);
             if (zminfoUserData && zminfoUserData.username) {
                 this.logger.debug('群昵称设置', `[层2-ZMINFO] "${zminfoUserData.username}"`);
             }
             else {
-                this.logger.warn('群昵称设置', `[层2-ZMINFO] 查询失败`);
+                this.logger.warn('群昵称设置', '[层2-ZMINFO] 查询失败');
             }
         }
         catch (zminfoError) {
@@ -101,7 +101,7 @@ class NicknameService {
             return; // 无需更新
         }
         if (!zminfoData) {
-            this.logger.debug('群昵称设置', `无ZMINFO数据，跳过数据库同步`);
+            this.logger.debug('群昵称设置', '无ZMINFO数据，跳过数据库同步');
             return;
         }
         try {
@@ -136,7 +136,7 @@ class NicknameService {
                 else {
                     this.logger.warn('群昵称设置', `⚠️ 验证失败，期望"${nickname}"，实际"${verifyNickname}"，可能是权限不足或API延迟`);
                     if (!currentNickname) {
-                        this.logger.warn('群昵称设置', `建议检查: 1.机器人是否为群管理员 2.群设置是否允许管理员修改昵称 3.OneBot实现是否支持该功能`);
+                        this.logger.warn('群昵称设置', '建议检查: 1.机器人是否为群管理员 2.群设置是否允许管理员修改昵称 3.OneBot实现是否支持该功能');
                     }
                 }
             }
@@ -159,7 +159,7 @@ class NicknameService {
             const actualUserId = targetUserId || session.userId;
             const normalizedUserId = this.normalizeQQId(actualUserId);
             const targetGroupId = specifiedGroupId || this.config.autoNicknameGroupId;
-            const mcInfo = (mcUsername && !mcUsername.startsWith('_temp_')) ? mcUsername : "未绑定";
+            const mcInfo = mcUsername && !mcUsername.startsWith('_temp_') ? mcUsername : '未绑定';
             this.logger.debug('群昵称设置', `开始处理QQ(${normalizedUserId})的群昵称设置，目标群: ${targetGroupId}`);
             // 检查前置条件
             if (!session.bot.internal) {
@@ -173,7 +173,7 @@ class NicknameService {
             // 获取最新的B站用户名
             let latestBuidUsername = buidUsername;
             if (buidUid) {
-                this.logger.debug('群昵称设置', `开始四层判断获取最新B站用户名...`);
+                this.logger.debug('群昵称设置', '开始四层判断获取最新B站用户名...');
                 this.logger.debug('群昵称设置', `[层3-数据库] "${buidUsername}"`);
                 const result = await this.getLatestBuidUsername(buidUid, buidUsername);
                 latestBuidUsername = result.username;
@@ -210,7 +210,7 @@ class NicknameService {
             catch (getInfoError) {
                 // 无法获取当前昵称，直接设置新昵称
                 this.logger.warn('群昵称设置', `获取QQ(${normalizedUserId})当前群昵称失败: ${getInfoError.message}`);
-                this.logger.debug('群昵称设置', `将直接尝试设置新昵称...`);
+                this.logger.debug('群昵称设置', '将直接尝试设置新昵称...');
                 await this.setAndVerifyNickname(session, targetGroupId, normalizedUserId, targetNickname);
             }
         }

package/lib/types/api.d.ts

@@ -5,59 +5,149 @@
 /**
  * Mojang API 响应接口
  * 用于获取MC用户UUID和用户名
+ *
+ * @see https://api.mojang.com/users/profiles/minecraft/{username}
+ * @see https://api.mojang.com/user/profile/{uuid}
+ *
+ * @example
+ * ```json
+ * {
+ *   "id": "069a79f444e94726a5befca90e38aaf5",
+ *   "name": "Notch"
+ * }
+ * ```
  */
 export interface MojangProfile {
+    /** UUID (不带连字符，32位十六进制字符串) */
     id: string;
+    /** 玩家名称 (Mojang返回的标准大小写) */
     name: string;
 }
 /**
  * ZMINFO API - 用户信息接口
+ *
+ * @see {zminfoApiUrl}/api/user/{uid}
+ *
+ * @example
+ * ```json
+ * {
+ *   "uid": "12345678",
+ *   "username": "用户名",
+ *   "avatar_url": "https://...",
+ *   "guard_level": 3,
+ *   "guard_level_text": "总督",
+ *   "max_guard_level": 3,
+ *   "max_guard_level_text": "总督",
+ *   "medal": {
+ *     "name": "粉丝牌",
+ *     "level": 20,
+ *     "uid": "87654321",
+ *     "room": 123456
+ *   },
+ *   "wealthMedalLevel": 15,
+ *   "last_active_time": "2025-10-23T12:00:00Z"
+ * }
+ * ```
  */
 export interface ZminfoUser {
+    /** B站用户UID */
     uid: string;
+    /** B站用户名 */
     username: string;
+    /** 用户头像URL */
     avatar_url: string;
+    /** 当前舰长等级 (0=无, 1=总督, 2=提督, 3=舰长) */
     guard_level: number;
+    /** 当前舰长等级文本描述 */
     guard_level_text: string;
+    /** 历史最高舰长等级 */
     max_guard_level: number;
+    /** 历史最高舰长等级文本描述 */
     max_guard_level_text: string;
+    /** 粉丝牌信息 (如果用户拥有) */
     medal: {
+        /** 粉丝牌名称 */
         name: string;
+        /** 粉丝牌等级 */
         level: number;
+        /** UP主UID */
         uid: string;
+        /** 直播间房间号 */
         room: number;
     } | null;
+    /** 荣耀等级 (财富勋章等级) */
     wealthMedalLevel: number;
+    /** 最后活跃时间 (ISO 8601格式) */
     last_active_time: string;
 }
 /**
  * ZMINFO API 响应接口
+ *
+ * @example 成功响应
+ * ```json
+ * {
+ *   "success": true,
+ *   "message": "success",
+ *   "data": {
+ *     "user": { ... }
+ *   }
+ * }
+ * ```
+ *
+ * @example 失败响应
+ * ```json
+ * {
+ *   "success": false,
+ *   "message": "User not found"
+ * }
+ * ```
  */
 export interface ZminfoApiResponse {
+    /** 请求是否成功 */
     success: boolean;
+    /** 响应消息 */
     message: string;
+    /** 响应数据 (仅成功时存在) */
     data?: {
+        /** 用户信息 */
         user?: ZminfoUser;
     };
 }
 /**
  * Bilibili Live API - 粉丝勋章信息接口
+ *
+ * @see https://api.live.bilibili.com/xlive/app-ucenter/v1/user/GetMyMedals
  */
 export interface MedalInfo {
+    /** UP主UID */
     target_id: number;
+    /** 粉丝牌等级 */
     level: number;
+    /** 粉丝牌名称 */
     medal_name: string;
+    /** 粉丝牌渐变色起始颜色 */
     medal_color_start: number;
+    /** 粉丝牌渐变色结束颜色 */
     medal_color_end: number;
+    /** 粉丝牌边框颜色 */
     medal_color_border: number;
+    /** 舰长等级 (0=无, 1=总督, 2=提督, 3=舰长) */
     guard_level: number;
+    /** 佩戴状态 (0=未佩戴, 1=已佩戴) */
     wearing_status: number;
+    /** 粉丝牌ID */
     medal_id: number;
+    /** 当前亲密度 */
     intimacy: number;
+    /** 下一级所需亲密度 */
     next_intimacy: number;
+    /** 今日亲密度 */
     today_feed: number;
+    /** 每日亲密度上限 */
     day_limit: number;
+    /** 舰长图标URL */
     guard_icon: string;
+    /** 荣耀图标URL */
     honor_icon: string;
 }
 /**

package/lib/types/config.d.ts

@@ -4,43 +4,104 @@
  */
 /**
  * 插件配置接口
+ *
+ * @remarks
+ * 该接口定义了 BIND-BOT 插件的所有配置选项，包括：
+ * - 基础配置 (冷却时间、管理员等)
+ * - 服务器配置
+ * - 显示选项
+ * - B站相关配置
+ * - 天选播报配置
+ * - 强制绑定配置
  */
 export interface Config {
+    /** 绑定冷却天数 (防止频繁更改绑定) */
     cooldownDays: number;
+    /** 主管理员QQ号 (拥有最高权限) */
     masterId: string;
+    /** Minecraft服务器配置列表 */
     servers: ServerConfig[];
+    /** 是否允许文本前缀 (支持不使用命令前缀) */
     allowTextPrefix: boolean;
+    /** 机器人昵称 (用于消息中的称呼) */
     botNickname: string;
+    /** 自动撤回时间 (秒, 0表示不撤回) */
     autoRecallTime: number;
+    /** 是否撤回用户消息 */
     recallUserMessage: boolean;
+    /** 调试模式 (输出详细日志) */
     debugMode: boolean;
+    /** 是否显示B站头像 */
     showAvatar: boolean;
+    /** 是否显示MC皮肤渲染 */
     showMcSkin: boolean;
+    /** ZMINFO API 地址 (用于获取B站用户信息) */
     zminfoApiUrl: string;
+    /** 是否启用天选播报功能 */
     enableLotteryBroadcast: boolean;
+    /** 天选播报目标群ID (为空则不播报到群) */
     lotteryTargetGroupId: string;
+    /** 天选播报私聊目标ID (为空则不私聊播报) */
     lotteryTargetPrivateId: string;
+    /** 自动群昵称设置目标群ID (仅在该群自动设置昵称) */
     autoNicknameGroupId: string;
+    /** 强制绑定使用的SESSDATA (B站Cookie) */
     forceBindSessdata: string;
+    /** 强制绑定目标UP主UID */
     forceBindTargetUpUid: number;
+    /** 强制绑定目标直播间房间号 */
     forceBindTargetRoomId: number;
+    /** 强制绑定目标粉丝牌名称 */
     forceBindTargetMedalName: string;
 }
 /**
  * 服务器配置接口
+ *
+ * @remarks
+ * 定义单个 Minecraft 服务器的配置信息，包括 RCON 连接、白名单命令模板等
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: 'survival',
+ *   name: '生存服',
+ *   rconAddress: '127.0.0.1:25575',
+ *   rconPassword: 'password123',
+ *   addCommand: 'whitelist add {username}',
+ *   removeCommand: 'whitelist remove {username}',
+ *   idType: 'username',
+ *   allowSelfApply: true,
+ *   acceptEmptyResponse: false,
+ *   displayAddress: 'mc.example.com',
+ *   description: '主生存服务器',
+ *   enabled: true
+ * }
+ * ```
  */
 export interface ServerConfig {
+    /** 服务器唯一标识符 */
     id: string;
+    /** 服务器显示名称 */
     name: string;
+    /** RCON 地址 (格式: host:port) */
     rconAddress: string;
+    /** RCON 密码 */
     rconPassword: string;
+    /** 添加白名单命令模板 (支持变量: {username}, {uuid}) */
     addCommand: string;
+    /** 移除白名单命令模板 (支持变量: {username}, {uuid}) */
     removeCommand: string;
+    /** ID 类型 (username: 使用用户名, uuid: 使用UUID) */
     idType: 'username' | 'uuid';
+    /** 是否允许用户自助申请白名单 */
     allowSelfApply: boolean;
+    /** 是否接受 RCON 空响应 (某些服务器返回空字符串表示成功) */
     acceptEmptyResponse?: boolean;
+    /** 服务器展示地址 (用于显示给用户) */
     displayAddress?: string;
+    /** 服务器说明信息 */
     description?: string;
+    /** 服务器是否启用 */
     enabled?: boolean;
 }
 /**