koishi-plugin-ets2-tools-tmp 3.4.3 → 3.4.5

package/lib/command/tmpActivityService/tmpActivityServiceV1.js

@@ -1,43 +1,87 @@
+const evmOpenApi = require('../../api/evmOpenApi');
+
+// serverId 在日志/消息里统一展示：数字型保持数字，其它原样返回
+function numericOrRaw(value) {
+    const n = Number(value);
+    return Number.isFinite(n) ? n : value;
+}
+
 module.exports = {
+    /**
+     * 列表接口最多翻几页（每页 100 条）。
+     * 平台 2.0 的 /activity/info/list 默认按开始时间倒序，今日活动通常在第 1 页，
+     * 但为了不依赖排序（以及以后数据量变大），这里仍然按 totalPage 翻页，只是加个上限防止死循环。
+     */
+    ACTIVITY_LIST_MAX_PAGE: 10,
+    ACTIVITY_LIST_PAGE_SIZE: 100,
+
     async updateTodayActivities() {
         try {
             this.todayActivities = [];
 
             const baseUrl = this.cfg.mainSettings?.url || "open.vtcm.link";
             const token = this.cfg.mainSettings?.token || "";
-            const fullUrl = `https://${baseUrl}/api/activity/info/list?token=${token}&page=1&limit=100&themeName=`;
-            this.logger.api(`请求V1车队平台API: ${fullUrl.replace(token, "***")}`);
+            const pageSize = this.ACTIVITY_LIST_PAGE_SIZE || 100;
+            const buildUrl = (page) => `https://${baseUrl}/api/activity/info/list?token=${token}&page=${page}&limit=${pageSize}&themeName=`;
+
+            this.logger.api(`请求V1车队平台API: ${buildUrl(1).replace(token, "***")}`);
 
             const startTime = Date.now();
-            const response = await this.ctx.http.get(fullUrl, { timeout: 10000 });
+            const firstResponse = await this.ctx.http.get(buildUrl(1), { timeout: 10000 });
             const duration = Date.now() - startTime;
-            this.logger.api(`V1车队平台API响应耗时: ${duration}ms, 状态码: ${response.code}`);
+            this.logger.api(`V1车队平台API响应耗时: ${duration}ms, 状态码: ${firstResponse.code}`);
 
             if (this.cfg.debug?.logApiResponses) {
                 this.logger.api("V1车队平台API响应详情:", {
-                    code: response.code,
-                    totalCount: response.data?.totalCount,
-                    listCount: response.data?.list?.length
+                    code: firstResponse.code,
+                    totalCount: firstResponse.data?.totalCount,
+                    totalPage: firstResponse.data?.totalPage,
+                    listCount: firstResponse.data?.list?.length
                 });
             }
 
-            if (response.code === 0 && response.data?.list) {
-                const now = new Date();
-                const today = `${now.getFullYear()}-${(now.getMonth() + 1).toString().padStart(2, '0')}-${now.getDate().toString().padStart(2, '0')}`;
-                this.logger.debug(`[V1活动更新] 当前本地日期: ${today}, UTC日期: ${new Date().toISOString().split("T")[0]}`);
+            if (firstResponse.code !== 0 || !Array.isArray(firstResponse.data?.list)) {
+                this.logger.error(`[V1活动更新] 车队平台API返回错误: ${firstResponse.msg || '未知错误'} (代码: ${firstResponse.code || '无'})`);
+                this.todayActivities = [];
+                return;
+            }
 
-                const originalCount = response.data.list.length;
-                this.logger.debug(`[V1活动更新] API返回活动总数: ${originalCount}`);
+            let list = firstResponse.data.list.slice();
+            const maxPage = Math.min(Number(firstResponse.data.totalPage) || 1, this.ACTIVITY_LIST_MAX_PAGE || 10);
 
-                this.todayActivities = response.data.list.filter((activity) => {
-                    const activityDate = activity.startTime?.split(" ")[0];
-                    return activityDate === today;
-                });
+            for (let page = 2; page <= maxPage; page++) {
+                try {
+                    const response = await this.ctx.http.get(buildUrl(page), { timeout: 10000 });
+                    if (response.code === 0 && Array.isArray(response.data?.list)) {
+                        list = list.concat(response.data.list);
+                    } else {
+                        this.logger.warn(`[V1活动更新] 第 ${page} 页返回错误: ${response.msg || '未知错误'} (代码: ${response.code || '无'})`);
+                    }
+                } catch (error) {
+                    // 翻页失败不影响第 1 页结果，今日活动通常就在第 1 页
+                    this.logger.warn(`[V1活动更新] 第 ${page} 页请求失败: ${error.message}`);
+                }
+            }
 
-                this.logger.info(`[V1活动更新] 从车队平台找到 ${this.todayActivities.length}/${originalCount} 个今日活动`);
-            } else {
-                this.logger.error(`[V1活动更新] 车队平台API返回错误: ${response.msg || '未知错误'} (代码: ${response.code || '无'})`);
-                this.todayActivities = [];
+            const now = new Date();
+            const today = `${now.getFullYear()}-${(now.getMonth() + 1).toString().padStart(2, '0')}-${now.getDate().toString().padStart(2, '0')}`;
+            this.logger.debug(`[V1活动更新] 当前本地日期: ${today}, UTC日期: ${new Date().toISOString().split("T")[0]}`);
+
+            const originalCount = list.length;
+            this.logger.debug(`[V1活动更新] API返回活动总数: ${originalCount}（共 ${maxPage} 页）`);
+
+            this.todayActivities = list.filter((activity) => {
+                const activityDate = activity.startTime?.split(" ")[0];
+                return activityDate === today;
+            });
+
+            this.logger.info(`[V1活动更新] 从车队平台找到 ${this.todayActivities.length}/${originalCount} 个今日活动`);
+
+            if (this.cfg.debug?.debugMode) {
+                for (const activity of this.todayActivities) {
+                    const profile = this.resolveProfileState(activity);
+                    this.logger.debug(`[V1活动更新] 今日活动 #${activity.id} "${activity.themeName}" 档位状态: ${profile.uploaded ? "已上传" : "未上传"}（来源: ${profile.source}, hasProfile=${activity.hasProfile}, profileFile=${activity.profileFile ? "有" : "空"}, state=${activity.state}）`);
+                }
             }
         } catch (error) {
             this.logger.error("[V1活动更新] 获取车队平台活动列表失败:", error.message);
@@ -45,6 +89,84 @@ module.exports = {
         }
     },
 
+    /**
+     * 判断活动档（profile）是否已上传。
+     *
+     * 平台 2.0 起，列表接口 /api/activity/info/list **不再返回 profileFile**（恒为 null），
+     * 改用布尔字段 hasProfile 表示档位是否已上传；只有详情接口 /api/activity/info/info/{id}
+     * 才带 profileFile。旧版本（1.0）的列表则只有 profileFile。
+     * 所以这里必须优先看 hasProfile，否则会永远判定为“未上传”。
+     *
+     * @returns {{uploaded: boolean, source: 'hasProfile'|'profileFile'|'unknown'}}
+     */
+    resolveProfileState(activity) {
+        if (!activity) return { uploaded: false, source: 'unknown' };
+
+        // 2.0：以 hasProfile 为准（注意 false 也是有效值，不能用 || 兜底）
+        if (typeof activity.hasProfile === 'boolean') {
+            return { uploaded: activity.hasProfile, source: 'hasProfile' };
+        }
+        if (activity.hasProfile === 1 || activity.hasProfile === 0) {
+            return { uploaded: activity.hasProfile === 1, source: 'hasProfile' };
+        }
+        if (activity.hasProfile === '1' || activity.hasProfile === '0') {
+            return { uploaded: activity.hasProfile === '1', source: 'hasProfile' };
+        }
+
+        // 1.0：没有 hasProfile，退回 profileFile 判空
+        if ('profileFile' in activity) {
+            return { uploaded: !!activity.profileFile, source: 'profileFile' };
+        }
+
+        return { uploaded: false, source: 'unknown' };
+    },
+
+    /**
+     * 查 TMP 服务器名（serverId → serverName）。
+     *
+     * 数据源 https://evmapi.cxnnn.cn/server/list?game=1（欧卡）。注意该接口返回的是
+     * **常驻服**（Simulation 1/2、Arcade、ProMods…），活动专属服（如 serverId=13 的
+     * "Revival Event | #26"）并不在里面，此时返回 null 由调用方兜底。
+     *
+     * 一次检查只拉一次列表，结果缓存在实例上（同一次 checkAutoClockStatus 内的多个活动共用）。
+     */
+    async getEvmServerNameMap() {
+        const now = Date.now();
+        // 5 分钟缓存：同一次检查里多个活动共用，也不至于跨天用过期数据
+        if (this._evmServerCache && now - this._evmServerCache.at < 5 * 60 * 1000) {
+            return this._evmServerCache.map;
+        }
+
+        const map = new Map();
+        let ok = false;
+        try {
+            const result = await evmOpenApi.serverList(this.ctx.http, 'ETS2');
+            if (result && !result.error && Array.isArray(result.data)) {
+                for (const server of result.data) {
+                    if (server && server.serverId != null) {
+                        map.set(Number(server.serverId), server.serverName);
+                    }
+                }
+                ok = map.size > 0;
+                if (ok) {
+                    this.logger.debug(`[自动打卡检查] evm 服务器列表已加载，共 ${map.size} 个常驻服`);
+                } else {
+                    this.logger.warn('[自动打卡检查] evm 服务器列表为空，无法确认服务器名称');
+                }
+            } else {
+                this.logger.warn('[自动打卡检查] evm 服务器列表查询失败，无法确认服务器名称');
+            }
+        } catch (error) {
+            this.logger.warn(`[自动打卡检查] evm 服务器列表查询异常: ${error.message}`);
+        }
+
+        // 只在成功时缓存：查询失败不缓存，避免 5 分钟内一直拿空结果
+        if (ok) {
+            this._evmServerCache = { at: now, map };
+        }
+        return map;
+    },
+
     async checkAutoClock(activity) {
         try {
             const baseUrl = this.cfg.mainSettings?.url || "open.vtcm.link";
@@ -60,9 +182,26 @@ module.exports = {
                 const serverId = response.data.serverId;
                 this.logger.debug(`活动 "${activity.themeName}" V1自动打卡状态: ${enableAutoClock}, serverId: ${serverId}`);
 
-                if (enableAutoClock === 1) {
-                    if (serverId != null) {
-                        return { status: 'set', message: '今日活动自动打卡已设置' };
+                // 宽松判断：接口可能给数字 1 或字符串 "1"
+                if (Number(enableAutoClock) === 1) {
+                    if (serverId != null && serverId !== '') {
+                        const resolved = await this.resolveAutoClockServerName(serverId);
+                        let message = '今日活动自动打卡已设置';
+                        if (resolved.reason === 'found') {
+                            message = `今日活动自动打卡已设置，打卡服务器名称：${resolved.name}`;
+                        } else if (resolved.reason === 'not_found') {
+                            // 查不到就如实说，不拿平台的活动名顶替（可能与实际开服不一致）
+                            message = `今日活动自动打卡已设置，但未查到服务器名称（serverId: ${serverId}，可能尚未开服）`;
+                        } else {
+                            message = `今日活动自动打卡已设置，但服务器列表查询失败，无法确认服务器名称（serverId: ${serverId}）`;
+                        }
+                        return {
+                            status: 'set',
+                            message,
+                            serverId: numericOrRaw(serverId),
+                            serverName: resolved.reason === 'found' ? resolved.name : null,
+                            serverNameReason: resolved.reason
+                        };
                     } else {
                         return { status: 'no_server', message: '今日活动打卡服务器未设置' };
                     }
@@ -71,11 +210,43 @@ module.exports = {
                 }
             } else {
                 this.logger.error(`V1活动详情API返回错误: ${response.msg || '未知错误'} (代码: ${response.code || '无'})`);
-                return { status: 'not_set', message: '今日活动打卡未设置' };
+                return { status: 'error', message: '今日活动打卡状态查询失败（接口返回错误）' };
             }
         } catch (error) {
             this.logger.error(`检查V1活动 "${activity.themeName}" 自动打卡状态失败:`, error.message);
-            return { status: 'not_set', message: '今日活动打卡未设置' };
+            return { status: 'error', message: '今日活动打卡状态查询失败（请求异常）' };
         }
+    },
+
+    /**
+     * 按 serverId 在 evm 服务器列表里查服务器名。
+     *
+     * 只认 evm 的权威数据：查不到就如实返回 reason，**绝不回退用平台活动自带的 serverName**
+     * ——平台那个字段是活动创建时填的，与实际开服选择可能不一致，拿来顶替会误导管理。
+     *
+     * @returns {{name: string|null, reason: 'found'|'not_found'|'unavailable'}}
+     */
+    async resolveAutoClockServerName(serverId) {
+        const numericId = Number(serverId);
+
+        let map;
+        try {
+            map = await this.getEvmServerNameMap();
+        } catch (error) {
+            this.logger.warn(`[自动打卡检查] 查询服务器名失败: ${error.message}`);
+            return { name: null, reason: 'unavailable' };
+        }
+
+        // 列表为空说明接口异常（正常至少有 7 个常驻服），按“查不到”处理
+        if (!map || map.size === 0) {
+            return { name: null, reason: 'unavailable' };
+        }
+
+        if (Number.isFinite(numericId) && map.has(numericId)) {
+            return { name: map.get(numericId), reason: 'found' };
+        }
+
+        this.logger.debug(`[自动打卡检查] serverId=${serverId} 不在 evm 服务器列表（可能尚未开服）`);
+        return { name: null, reason: 'not_found' };
     }
 };

package/lib/command/tmpActivityService.js

@@ -323,13 +323,18 @@ class ActivityService {
         this.logger.debug(`开始检查 ${this.todayActivities.length} 个活动的档位状态`);
 
         for (const activity of this.todayActivities) {
-            const hasProfile = !!activity.profileFile;
+            // 平台 2.0 列表接口只给 hasProfile，不再给 profileFile（恒为 null），
+            // 统一走 resolveProfileState 判断，避免永远提示“未上传”。
+            const profileState = typeof this.resolveProfileState === 'function'
+                ? this.resolveProfileState(activity)
+                : { uploaded: !!activity.profileFile, source: 'profileFile' };
+            const hasProfile = profileState.uploaded;
             let message = hasProfile ? this.cfg.messages.profileUploaded : this.cfg.messages.profileNotUploaded;
             if (hasProfile && activity.state == 0) {
                 message += "，当前状态草稿。";
             }
             const fullMessage = `活动 "${activity.themeName || '未知活动'}" - ${message}`;
-            this.logger.message(`活动档位检查: "${activity.themeName || '未知活动'}" - ${hasProfile ? "已上传" : "未上传"}`);
+            this.logger.message(`活动档位检查: "${activity.themeName || '未知活动'}" - ${hasProfile ? "已上传" : "未上传"}（判定依据: ${profileState.source}）`);
 
             for (const groupId of this.cfg.admin.groups) {
                 try {
@@ -723,7 +728,11 @@ class ActivityService {
 
                 let message;
                 if (autoClockResult.status === 'set') {
-                    message = `今日活动自动打卡已设置`;
+                    // checkAutoClock 已拼好服务器名（查不到名时退回不含服务器名的文案）
+                    message = autoClockResult.message || `今日活动自动打卡已设置`;
+                } else if (autoClockResult.status === 'error') {
+                    // 接口异常不冒充“未设置”，避免误报
+                    message = `请注意，今日活动打卡状态查询失败，请手动确认。\n 活动名称： ${activity.themeName || '未知活动'}`;
                 } else if (autoClockResult.status === 'no_server') {
                     message = `请注意，今日活动打卡服务器未设置。\n 活动名称： ${activity.themeName || '未知活动'}`;
                 } else {

package/lib/command/tmpMileageRanking.js

@@ -30,10 +30,10 @@ module.exports = async (ctx, session, rankingType, target) => {
         if (ownerName) tmpIdPicker.cacheAtName(session.platform, ownerKey, ownerName);
     }
     // 排行榜只高亮一个人：直接用默认绑定，不弹序号询问
+    // 这里只用 tmp_id，高亮名字来自排行榜接口返回的数据 → 不必刷新 tmp_name
     const bindings = await guildBind.listOf(ctx.database, session.platform, ownerKey);
     let bindTmpId = null;
     if (bindings.length > 0) {
-        await guildBind.ensureNames(ctx, bindings);
         bindTmpId = String((bindings.find(b => guildBind.isDefault(b)) || bindings[0]).tmp_id);
     }
     let playerMileageRanking = null;

package/lib/command/tmpVersionCheck.js

@@ -3,12 +3,21 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.VersionCheckService = void 0;
 
 const koishi_1 = require("koishi");
+const path_1 = require("path");
+const common_1 = require("../util/common");
+
+// TMP 官方文件清单（含每个文件的 MD5），用于比对版本更新前后哪些文件被替换
+const FILES_API = "https://update.ets2mp.com/files.json";
+// 文字通知里最多列出多少个文件，超出只显示数量，避免消息过长
+const MAX_LISTED_FILES = 30;
 
 class VersionCheckService {
     constructor(ctx, config) {
         this.ctx = ctx;
         this.cfg = config;
         this.currentVersion = null;
+        // 上一次检查时的文件清单快照（FilePath -> {md5, type}），用于比对文件变化
+        this.fileManifest = null;
         this.timers = [];
         this.logger = this.initLogger();
     }
@@ -71,6 +80,7 @@ class VersionCheckService {
             if (response && response.name) {
                 const versionInfo = {
                     name: response.name,
+                    stage: response.stage,
                     time: this.convertToUTC8(response.time),
                     supported_game_version: response.supported_game_version,
                     supported_ats_game_version: response.supported_ats_game_version
@@ -80,7 +90,14 @@ class VersionCheckService {
 
                 if (this.currentVersion && this.currentVersion.name !== versionInfo.name) {
                     this.logger.info(`检测到版本更新: ${this.currentVersion.name} -> ${versionInfo.name}`);
-                    await this.sendVersionUpdateNotification(this.currentVersion, versionInfo);
+
+                    // 比对文件 MD5，找出本次更新实际替换了哪些文件
+                    const changedFiles = await this.detectChangedFiles();
+                    if (changedFiles.length > 0) {
+                        this.logger.info(`本次更新涉及 ${changedFiles.length} 个文件变化`);
+                    }
+
+                    await this.sendVersionUpdateNotification(this.currentVersion, versionInfo, changedFiles);
                 }
 
                 this.currentVersion = versionInfo;
@@ -92,6 +109,108 @@ class VersionCheckService {
         }
     }
 
+    /**
+     * 拉取官方文件清单并转成 { FilePath -> Md5 } 映射。
+     * 失败时返回 null（调用方据此区分“没变化”和“查不到”）。
+     */
+    async fetchFileManifest() {
+        try {
+            const response = await this.ctx.http.get(FILES_API, { timeout: 15000 });
+            const files = response && Array.isArray(response.Files) ? response.Files : null;
+            if (!files) {
+                this.logger.warn("文件清单格式不正确，跳过文件变化比对");
+                return null;
+            }
+
+            const manifest = new Map();
+            for (const file of files) {
+                if (file && file.FilePath) {
+                    manifest.set(file.FilePath, {
+                        md5: String(file.Md5 || "").toLowerCase(),
+                        type: file.Type || ""
+                    });
+                }
+            }
+            this.logger.debug(`文件清单已加载，共 ${manifest.size} 个文件`);
+            return manifest;
+        } catch (error) {
+            this.logger.warn(`获取文件清单失败: ${error.message}`);
+            return null;
+        }
+    }
+
+    /**
+     * 比对「上一次版本的文件清单」与「当前清单」，返回 MD5 变化的文件。
+     *
+     * 说明：files.json 只提供**当前**版本的文件列表，没有历史版本归档
+     * （/0.7.10.0/files.json 等路径均 404）。所以只能在两次检查之间自己留存快照：
+     * - 有上一次快照 → 逐文件比对 MD5，新增/删除/改动都算变化；
+     * - 没有快照（首次运行或重启）→ 退化为“清单中所有文件都视为本次更新内容”，
+     *   并在结果里标注 snapshotMissing，由文案说明这是完整清单而非差异。
+     *
+     * @returns {Array|null} 变化列表；清单获取失败时返回 null（区别于“没有变化”的空数组）
+     */
+    async detectChangedFiles() {
+        const current = await this.fetchFileManifest();
+        if (!current) {
+            // 查不到清单 ≠ 没有变化，不能返回 []，否则会误报“未检测到文件变化”
+            return null;
+        }
+
+        const previous = this.fileManifest;
+        this.fileManifest = current;
+
+        if (!previous) {
+            this.logger.debug("没有上一次的文件清单快照，本次按完整清单输出");
+            return this.buildFullFileList(current, true);
+        }
+
+        const changed = [];
+        for (const [filePath, info] of current) {
+            const old = previous.get(filePath);
+            if (!old) {
+                changed.push({ path: filePath, type: info.type, kind: 'added' });
+            } else if (old.md5 !== info.md5) {
+                changed.push({ path: filePath, type: info.type, kind: 'modified' });
+            }
+        }
+        // 上一次有、这次没有 → 被移除
+        for (const [filePath, info] of previous) {
+            if (!current.has(filePath)) {
+                changed.push({ path: filePath, type: info.type, kind: 'removed' });
+            }
+        }
+
+        // 稳定排序：先 ets2/ats，再 system；同类按路径
+        const typeOrder = { ets2: 0, ats: 1, system: 2 };
+        changed.sort((a, b) => {
+            const ta = typeOrder[a.type] !== undefined ? typeOrder[a.type] : 9;
+            const tb = typeOrder[b.type] !== undefined ? typeOrder[b.type] : 9;
+            if (ta !== tb) return ta - tb;
+            return a.path.localeCompare(b.path);
+        });
+
+        return changed;
+    }
+
+    /** 没有快照时的退化结果：清单内所有文件 */
+    buildFullFileList(manifest, snapshotMissing) {
+        const list = [];
+        for (const [filePath, info] of manifest) {
+            list.push({ path: filePath, type: info.type, kind: 'unknown' });
+        }
+        const typeOrder = { ets2: 0, ats: 1, system: 2 };
+        list.sort((a, b) => {
+            const ta = typeOrder[a.type] !== undefined ? typeOrder[a.type] : 9;
+            const tb = typeOrder[b.type] !== undefined ? typeOrder[b.type] : 9;
+            if (ta !== tb) return ta - tb;
+            return a.path.localeCompare(b.path);
+        });
+        // 用不可枚举标记，避免污染后续 JSON 序列化
+        Object.defineProperty(list, 'snapshotMissing', { value: !!snapshotMissing, enumerable: false });
+        return list;
+    }
+
     convertToUTC8(utcTimeString) {
         try {
             const utcDate = new Date(utcTimeString);
@@ -109,28 +228,175 @@ class VersionCheckService {
         }
     }
 
-    async sendVersionUpdateNotification(oldVersion, newVersion) {
-        const message = `📢 TMP版本更新通知
+    async sendVersionUpdateNotification(oldVersion, newVersion, changedFiles) {
+        // null = 清单查询失败；数组 = 比对结果（可能为空）
+        const fileCount = changedFiles === null ? '查询失败' : `${changedFiles.length}`;
+        this.logger.info(`发送版本更新通知到 ${this.cfg.groups.length} 个群组（变化文件: ${fileCount}）`);
 
-旧版本: ${oldVersion.name}
-新版本: ${newVersion.name}
-
-更新时间: ${newVersion.time}（UTC+8）
-欧卡支持版本: ${newVersion.supported_game_version}
-美卡支持版本: ${newVersion.supported_ats_game_version}`;
-
-        this.logger.info(`发送版本更新通知到 ${this.cfg.groups.length} 个群组`);
+        // 内容只构建一次（图片渲染较慢，不要每个群各渲染一遍）
+        const message = await this.buildUpdateContent(oldVersion, newVersion, changedFiles);
+        const isImage = typeof message === "object" && message !== null;
 
         for (const groupId of this.cfg.groups) {
             try {
                 await this.sendToGroup(groupId, message);
-                this.logger.info(`已发送版本更新通知到群组 ${groupId}`);
+                this.logger.info(`已发送版本更新通知到群组 ${groupId}（${isImage ? "图片" : "文字"}）`);
             } catch (error) {
                 this.logger.error(`发送版本更新通知到群组 ${groupId} 失败:`, error.message);
             }
         }
     }
 
+    /**
+     * 构建通知内容。notifyType：1=文字（默认），2=图片。
+     * 图片渲染失败（如未启用 puppeteer）会**自动回退为文字**，保证通知不丢。
+     * @returns 文字字符串，或图片 segment 元素
+     */
+    async buildUpdateContent(oldVersion, newVersion, changedFiles) {
+        const notifyType = Number(this.cfg.notifyType) || 1;
+        if (notifyType === 2) {
+            const image = await this.renderUpdateImage(oldVersion, newVersion, changedFiles);
+            if (image) {
+                return image;
+            }
+        }
+        return this.buildUpdateText(oldVersion, newVersion, changedFiles);
+    }
+
+    /**
+     * 插件配置里的「更新通知附加文本」，原样追加在通知末尾。
+     * 支持 \n 转义换行，方便在配置面板里写多行。
+     */
+    getExtraText() {
+        const raw = this.cfg.extraText;
+        if (raw == null) return "";
+        const text = String(raw).trim();
+        if (!text) return "";
+        return text.replace(/\\n/g, "\n");
+    }
+
+    buildUpdateText(oldVersion, newVersion, changedFiles) {
+        let message = `📢 TMP版本更新通知
+
+旧版本: ${oldVersion.name}
+新版本: ${newVersion.name}
+
+更新时间: ${newVersion.time}（UTC+8）
+欧卡支持版本: ${this.formatGameVersion(oldVersion.supported_game_version, newVersion.supported_game_version)}
+美卡支持版本: ${this.formatGameVersion(oldVersion.supported_ats_game_version, newVersion.supported_ats_game_version)}`;
+
+        message += this.formatChangedFiles(changedFiles);
+
+        const extra = this.getExtraText();
+        if (extra) {
+            message += `\n\n${extra}`;
+        }
+        return message;
+    }
+
+    /**
+     * 把变化文件列表拼成消息片段。
+     * - files 为 null → 清单获取失败，明确说明“查询失败”，不冒充“无变化”
+     * - 空数组 → 确实没有文件变化
+     * - 超过 MAX_LISTED_FILES 条 → 只列前若干条 + 「等共 N 个」
+     */
+    formatChangedFiles(files) {
+        if (files === null) {
+            return `\n\n更新文件: 文件清单获取失败，无法比对变化`;
+        }
+        if (!files || files.length === 0) {
+            return `\n\n更新文件: 未检测到文件变化`;
+        }
+
+        const snapshotMissing = files.snapshotMissing === true;
+        const title = snapshotMissing
+            ? `更新文件（共 ${files.length} 个，未留存上次清单，以下为完整列表）`
+            : `更新文件（共 ${files.length} 个）`;
+
+        const shown = files.slice(0, MAX_LISTED_FILES);
+        const lines = shown.map((file) => {
+            const mark = file.kind === 'added' ? '[新增] '
+                : file.kind === 'removed' ? '[移除] '
+                : file.kind === 'modified' ? '[更新] '
+                : '';
+            return `· ${mark}${file.path}`;
+        });
+
+        let text = `\n\n${title}\n${lines.join('\n')}`;
+        if (files.length > shown.length) {
+            text += `\n… 等共 ${files.length} 个文件`;
+        }
+        return text;
+    }
+
+    /**
+     * 游戏支持版本：有变化时显示「旧 → 新」，没变则只显示当前值。
+     */
+    formatGameVersion(oldValue, newValue) {
+        if (oldValue && newValue && String(oldValue) !== String(newValue)) {
+            return `${oldValue} → ${newValue}`;
+        }
+        return newValue || oldValue || "未知";
+    }
+
+    /**
+     * 用 puppeteer 渲染版本更新卡片
+     * @returns 图片 segment 元素；渲染不可用时返回 null，由调用方回退文字
+     */
+    async renderUpdateImage(oldVersion, newVersion, changedFiles) {
+        if (!this.ctx.puppeteer) {
+            this.logger.warn("未启用 puppeteer，版本更新通知回退为文字形式");
+            return null;
+        }
+        let page;
+        try {
+            // null = 清单查询失败，交给模板显示对应提示
+            const files = changedFiles === null ? [] : (Array.isArray(changedFiles) ? changedFiles : []);
+            const data = {
+                oldName: oldVersion.name,
+                newName: newVersion.name,
+                time: newVersion.time,
+                stage: newVersion.stage,
+                // 游戏支持版本也带上旧值，卡片才能显示「旧 → 新」对比
+                etsOld: oldVersion.supported_game_version,
+                etsNew: newVersion.supported_game_version,
+                atsOld: oldVersion.supported_ats_game_version,
+                atsNew: newVersion.supported_ats_game_version,
+                // 变化文件：路径 + 变化类型，卡片里按组展示
+                files: files.map((file) => ({
+                    path: file.path,
+                    kind: file.kind || 'unknown',
+                    type: file.type || ''
+                })),
+                filesSnapshotMissing: changedFiles !== null && changedFiles.snapshotMissing === true,
+                filesUnavailable: changedFiles === null,
+                extraText: this.getExtraText()
+            };
+            const htmlPath = path_1.resolve(__dirname, "../resource/version-update.html");
+            this.logger.debug(`渲染版本更新卡片: ${htmlPath}`);
+
+            page = await this.ctx.puppeteer.page();
+            await page.setViewport({ width: 560, height: 900, deviceScaleFactor: 2 });
+            await page.goto(`file:///${htmlPath}`);
+            await page.evaluate(`setData(${JSON.stringify(data)})`);
+            await common_1.sleep(100);
+            await page.waitForNetworkIdle();
+
+            const element = await page.$("#container");
+            if (!element) {
+                throw new Error("未找到 #container");
+            }
+            return koishi_1.segment.image(await element.screenshot({ encoding: "binary" }), "image/jpeg");
+        } catch (error) {
+            this.logger.error(`渲染版本更新卡片失败，回退为文字形式: ${error.message}`);
+            return null;
+        } finally {
+            if (page) {
+                try { await page.close(); } catch { }
+            }
+        }
+    }
+
     async sendToGroup(groupId, message) {
         const onebotBots = this.ctx.bots.filter((bot) => {
             return bot.platform === "onebot";

package/lib/command/tmpVtcMileageRanking.js

@@ -34,10 +34,10 @@ module.exports = async (ctx, cfg, session, rankingType, target) => {
         if (ownerName) tmpIdPicker.cacheAtName(session.platform, ownerKey, ownerName);
     }
     // 排行榜只高亮一个人：直接用默认绑定，不弹序号询问
+    // 这里只用 tmp_id，高亮名字来自排行榜接口返回的数据 → 不必刷新 tmp_name
     const bindings = await guildBind.listOf(ctx.database, session.platform, ownerKey);
     let bindTmpId = null;
     if (bindings.length > 0) {
-        await guildBind.ensureNames(ctx, bindings);
         bindTmpId = String((bindings.find(b => guildBind.isDefault(b)) || bindings[0]).tmp_id);
     }
     let playerMileageRanking = null;