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

package/lib/command/tmpServer/tmpServer.js

@@ -1,9 +1,26 @@
 const tmpServerText = require("./tmpServerText");
 const tmpServerImg = require("./tmpServerImg");
+const messageRender = require("../../util/messageRender");
+const qqOfficial = require("../../util/qqOfficial");
+const qqMediaUpload = require("../../util/qqMediaUpload");
+
 /**
- * 查询服务器列表
+ * 查询服务器列表。
+ *
+ * 输出包装：QQ 官方机器人下把文本结果包成 qq:markdown 并附加按钮；
+ * onebot 原样返回，行为与以前完全一致。
  */
-module.exports = async (ctx, cfg, game) => {
+module.exports = async (ctx, cfg, session, game) => {
+    const result = await queryRaw(ctx, cfg, session, game);
+
+    if (!qqOfficial.isQQOfficial(session) || result == null) {
+        return result;
+    }
+    return await decorate(ctx, cfg, session, result, game);
+};
+
+/** 按配置分发（保持原有逻辑不变） */
+async function queryRaw(ctx, cfg, session, game) {
     switch (cfg.tmpServer?.type) {
         case 1:
             return await tmpServerText(ctx, game);
@@ -12,4 +29,31 @@ module.exports = async (ctx, cfg, game) => {
         default:
             return '指令配置错误';
     }
-};
+}
+
+async function decorate(ctx, cfg, session, result, game) {
+    // 图片元素：图片 + 按钮
+    if (typeof result === 'object' && result.type && result.type !== 'text') {
+        return await messageRender.renderImage(session, result, {
+            buttons: buildButtons(game),
+            uploader: await messageRender.buildUploader(ctx, cfg, session),
+        });
+    }
+    const text = typeof result === 'string' ? result : String(result);
+    const isError = /失败|错误|不正确/.test(text);
+    return await messageRender.renderText(session, text, {
+        buttons: isError ? [] : buildButtons(game),
+        markdown: true,
+    });
+}
+
+/** 服务器结果下方按钮：在欧卡/美卡之间快速切换 */
+function buildButtons(game) {
+    const isAts = game === 'ATS';
+    return [
+        [
+            qqOfficial.inputButton(isAts ? '看欧卡' : '看美卡', isAts ? '欧卡服务器' : '美卡服务器', true),
+            qqOfficial.inputButton('路况', '路况 s1'),
+        ],
+    ];
+}

package/lib/command/tmpServer/tmpServerImg.js

@@ -22,7 +22,7 @@ module.exports = async (ctx, game) => {
         const element = await page.$("#container");
         return (segment.image(await element.screenshot({
             encoding: "binary"
-        }), "image/jpg"));
+        }), "image/jpeg"));
     }
     catch {
         return '渲染异常，请重试';

package/lib/command/tmpTraffic/tmpTraffic.js

@@ -1,9 +1,26 @@
 const tmpTrafficMap = require("./tmpTrafficMap");
 const tmpTrafficText = require("./tmpTrafficText");
+const messageRender = require("../../util/messageRender");
+const qqOfficial = require("../../util/qqOfficial");
+const qqMediaUpload = require("../../util/qqMediaUpload");
+
 /**
- * 查询路况
+ * 查询路况。
+ *
+ * 输出包装：QQ 官方机器人下把文本结果包成 qq:markdown 并附加按钮；
+ * onebot 原样返回，行为与以前完全一致。
  */
-module.exports = async (ctx, cfg, serverName) => {
+module.exports = async (ctx, cfg, session, serverName) => {
+    const result = await queryRaw(ctx, cfg, serverName);
+
+    if (!qqOfficial.isQQOfficial(session) || result == null) {
+        return result;
+    }
+    return await decorate(ctx, cfg, session, result, serverName);
+};
+
+/** 按配置分发（保持原有逻辑不变） */
+async function queryRaw(ctx, cfg, serverName) {
     switch (cfg.tmpTraffic?.type) {
         case 1:
             return await tmpTrafficText(ctx, cfg, serverName);
@@ -12,4 +29,48 @@ module.exports = async (ctx, cfg, serverName) => {
         default:
             return '指令配置错误';
     }
-};
+}
+
+async function decorate(ctx, cfg, session, result, serverName) {
+    // 图片（热力图）：图片 + 按钮
+    if (typeof result === 'object' && result.type && result.type !== 'text') {
+        return await messageRender.renderImage(session, result, {
+            buttons: buildButtons(serverName),
+            uploader: await messageRender.buildUploader(ctx, cfg, session),
+        });
+    }
+    const text = typeof result === 'string' ? result : String(result);
+    const isError = /失败|错误|不正确|请输入/.test(text);
+    return await messageRender.renderText(session, text, {
+        buttons: isError ? [] : buildButtons(serverName),
+        markdown: true,
+    });
+}
+
+/**
+ * 常用服务器快捷切换。
+ * 注意：路况指令只认短别名（s1 / s2 / p / a / 美s ...），
+ * 按钮里必须填「路况 s1」这种真实可用的写法，不能写服务器全名。
+ */
+function buildButtons(serverName) {
+    const current = String(serverName || '').toLowerCase();
+    const all = [
+        { alias: 's1', label: 'S1 路况' },
+        { alias: 's2', label: 'S2 路况' },
+        { alias: 'a', label: 'Arcade' },
+        { alias: 'p', label: 'ProMods' },
+    ];
+    // 当前所在服务器不再重复给出按钮
+    const quick = all
+        .filter(x => x.alias !== current)
+        .slice(0, 3)
+        .map(x => qqOfficial.inputButton(x.label, `路况 ${x.alias}`));
+
+    // 每行最多 2 个，避免手机端文字被截断
+    const rows = [];
+    for (let i = 0; i < quick.length; i += 2) {
+        rows.push(quick.slice(i, i + 2));
+    }
+    rows.push([qqOfficial.inputButton('欧卡服务器', '欧卡服务器')]);
+    return rows;
+}

package/lib/command/tmpTraffic/tmpTrafficMap.js

@@ -151,7 +151,7 @@ module.exports = async (ctx, cfg, serverName) => {
                 const element = await page.$("#container");
                 return (segment.image(await element.screenshot({
                     encoding: "binary"
-                }), "image/jpg"));
+                }), "image/jpeg"));
             }
             catch {
                 return '渲染异常，请重试';
@@ -188,7 +188,7 @@ module.exports = async (ctx, cfg, serverName) => {
                 const element = await page.$("#container");
                 return (segment.image(await element.screenshot({
                     encoding: "binary"
-                }), "image/jpg"));
+                }), "image/jpeg"));
             }
             catch {
                 return '渲染异常，请重试';

package/lib/command/tmpVersion.js

@@ -1,14 +1,86 @@
+const { segment } = require("koishi");
+const { resolve } = require("path");
+const common = require("../util/common");
 const truckersMpApi = require("../api/truckersMpApi");
-module.exports = async (ctx) => {
+const messageRender = require("../util/messageRender");
+const qqOfficial = require("../util/qqOfficial");
+
+/**
+ * 查询 TMP 当前版本。
+ *
+ * 输出形式由配置 tmpVersion.type 决定：1=文字，2=图片（默认）。
+ * QQ 官方机器人下会自动附加按钮；onebot 行为与原版一致。
+ */
+module.exports = async (ctx, cfg, session) => {
+    const type = messageRender.readType(cfg, 'tmpVersion.type');
+    // 仅图片模式需要 puppeteer
+    if (messageRender.wantImage(type) && !ctx.puppeteer) {
+        return '未启用 Puppeteer 功能';
+    }
+
     // 查询版本信息
-    let result = await truckersMpApi.version(ctx.http);
-    if (result.error) {
+    const result = await truckersMpApi.version(ctx.http);
+    if (result.error || !result.data) {
         return '查询失败，请稍后再试';
     }
-    // 构建消息返回
-    let message = '';
-    message += `TMP版本：${result.data.name}\n`;
-    message += `欧卡支持版本: ${result.data.supported_game_version}\n`;
-    message += `美卡支持版本: ${result.data.supported_ats_game_version}`;
-    return message;
+
+    const data = result.data;
+    const text = buildVersionText(data);
+    const buttons = buildButtons(session);
+
+    return await messageRender.renderByType(ctx, session, cfg, 'tmpVersion.type', {
+        text,
+        buttons,
+        caption: 'TruckersMP 当前版本',
+        alt: 'TMP 版本',
+        image: async () => {
+            if (!ctx.puppeteer) return null;
+            let page;
+            try {
+                const payload = {
+                    name: data.name,
+                    numeric: data.numeric,
+                    stage: data.stage,
+                    time: data.time,
+                    ets: data.supported_game_version,
+                    ats: data.supported_ats_game_version,
+                };
+                const htmlPath = resolve(__dirname, '../resource/tmp-version.html');
+
+                page = await ctx.puppeteer.page();
+                await page.setViewport({ width: 560, height: 700, deviceScaleFactor: 2 });
+                await page.goto(`file:///${htmlPath}`);
+                await page.evaluate(`setData(${JSON.stringify(payload)})`);
+                await common.sleep(100);
+                await page.waitForNetworkIdle();
+
+                const element = await page.$("#container");
+                if (!element) return null;
+                return segment.image(await element.screenshot({ encoding: "binary" }), "image/jpeg");
+            } catch (e) {
+                ctx.logger.warn(`[tmp版本] 渲染失败，回退文字: ${e.message}`);
+                return null;
+            } finally {
+                if (page) {
+                    try { await page.close(); } catch { }
+                }
+            }
+        }
+    });
 };
+
+/** 文字版（图片渲染失败或配置为文字时使用） */
+function buildVersionText(data) {
+    return `TMP版本：${data.name}\n` +
+        `欧卡支持版本: ${data.supported_game_version}\n` +
+        `美卡支持版本: ${data.supported_ats_game_version}`;
+}
+
+/** 官方机器人下的快捷按钮 */
+function buildButtons(session) {
+    if (!qqOfficial.isQQOfficial(session)) return [];
+    return [
+        [qqOfficial.inputButton('刷新版本', 'tmp版本', true)],
+        [qqOfficial.inputButton('欧卡服务器', '欧卡服务器'), qqOfficial.inputButton('规则查询', '规则查询')],
+    ];
+}

package/lib/command/tmpVersionCheck.js

@@ -18,6 +18,7 @@ class VersionCheckService {
         this.currentVersion = null;
         // 上一次检查时的文件清单快照（FilePath -> {md5, type}），用于比对文件变化
         this.fileManifest = null;
+        this.disposed = false;
         this.timers = [];
         this.logger = this.initLogger();
     }
@@ -53,18 +54,51 @@ class VersionCheckService {
 
     setupVersionCheck() {
         this.logger.info("设置TMP版本检查服务");
-        
-        this.logger.debug("启动时立即检查版本");
-        this.checkVersion();
 
         const checkInterval = this.cfg.checkInterval * 60 * 1000;
         this.logger.info(`设置定时版本检查，间隔: ${this.cfg.checkInterval} 分钟`);
-        
-        const intervalTimer = setInterval(async () => {
-            this.logger.debug("执行定时版本检查");
-            await this.checkVersion();
-        }, checkInterval);
-        this.timers.push(intervalTimer);
+
+        // 顺序很重要：先建立文件清单基线，再开始版本检查。
+        // 否则第一次真发生版本更新时 fileManifest 仍是 null，只能退化成“输出完整列表”。
+        this.runInitialCheck()
+            .catch((error) => {
+                this.logger.error("启动版本检查失败:", error.message);
+            })
+            .finally(() => {
+                // 初始化失败也要把定时器挂上，否则整个功能就停摆了
+                if (this.disposed) return;
+                const intervalTimer = setInterval(async () => {
+                    this.logger.debug("执行定时版本检查");
+                    await this.checkVersion();
+                }, checkInterval);
+                this.timers.push(intervalTimer);
+            });
+    }
+
+    /**
+     * 启动时的初始化：先拉文件清单做基线，再做第一次版本检查。
+     */
+    async runInitialCheck() {
+        await this.initBaselineManifest();
+
+        this.logger.debug("启动时立即检查版本");
+        await this.checkVersion();
+    }
+
+    /**
+     * 建立文件清单基线（FilePath -> {md5, type}）。
+     *
+     * files.json 只有“当前版本”的清单、没有历史归档，所以必须在启动时就把当前清单存下来，
+     * 下次版本更新时才能逐文件比对 MD5。基线建立失败不影响功能，只是首次更新会退化成完整列表。
+     */
+    async initBaselineManifest() {
+        const manifest = await this.fetchFileManifest();
+        if (manifest && manifest.size > 0) {
+            this.fileManifest = manifest;
+            this.logger.info(`已建立文件清单基线，共 ${manifest.size} 个文件（版本更新时可精确比对 MD5）`);
+        } else {
+            this.logger.warn("启动时未能建立文件清单基线，首次版本更新将输出完整文件列表");
+        }
     }
 
     async checkVersion() {
@@ -88,12 +122,20 @@ class VersionCheckService {
 
                 this.logger.info(`获取到TMP版本信息: ${versionInfo.name} (${versionInfo.time})`);
 
+                // 基线可能因启动时网络抖动没建立成功，这里顺带补一次（失败也不影响本次检查）
+                if (!this.fileManifest) {
+                    await this.initBaselineManifest();
+                }
+
                 if (this.currentVersion && this.currentVersion.name !== versionInfo.name) {
                     this.logger.info(`检测到版本更新: ${this.currentVersion.name} -> ${versionInfo.name}`);
 
                     // 比对文件 MD5，找出本次更新实际替换了哪些文件
+                    // 返回 null 表示清单查询失败（区别于“没有变化”的空数组）
                     const changedFiles = await this.detectChangedFiles();
-                    if (changedFiles.length > 0) {
+                    if (changedFiles === null) {
+                        this.logger.warn("文件清单获取失败，本次更新通知不包含文件变化");
+                    } else if (changedFiles.length > 0) {
                         this.logger.info(`本次更新涉及 ${changedFiles.length} 个文件变化`);
                     }
 
@@ -425,6 +467,7 @@ class VersionCheckService {
 
     cleanup() {
         this.logger.debug("插件卸载，开始清理版本检查服务资源");
+        this.disposed = true;
         this.timers.forEach((timer) => {
             clearTimeout(timer);
             clearInterval(timer);

package/lib/command/tmpVtcMileageRanking.js

@@ -4,8 +4,12 @@ const common = require('../util/common');
 const evmOpenApi = require('../api/evmOpenApi');
 const guildBind = require('../database/guildBind');
 const tmpIdPicker = require('../util/tmpIdPicker');
+const messageRender = require('../util/messageRender');
+const qqOfficial = require('../util/qqOfficial');
 module.exports = async (ctx, cfg, session, rankingType, target) => {
-    if (!ctx.puppeteer) {
+    // 仅在图片模式下才需要 puppeteer；文本模式不拦截
+    const wantImage = messageRender.wantImage(messageRender.readType(cfg, 'tmpVtcMileageRanking.type'));
+    if (wantImage && !ctx.puppeteer) {
         return '未启用 Puppeteer 功能';
     }
     const vtcId = cfg.tmpActivityService?.api?.vtcId;
@@ -51,26 +55,75 @@ module.exports = async (ctx, cfg, session, rankingType, target) => {
         mileageRankingList: mileageRankingList.data,
         playerMileageRanking: playerMileageRanking
     };
-    let page;
-    try {
-        page = await ctx.puppeteer.page();
-        await page.setViewport({ width: 1000, height: 1000, deviceScaleFactor: 2 });
-        await page.goto(`file:///${resolve(__dirname, '../resource/mileage-leaderboard.html')}`);
-        await page.evaluate(`setData(${JSON.stringify(data)})`);
-        await page.waitForNetworkIdle();
-        await common.sleep(500);
-        const element = await page.$("#container");
-        return (segment.image(await element.screenshot({
-            encoding: "binary"
-        }), "image/jpg"));
-    }
-    catch (e) {
-        console.info(e);
-        return '渲染异常，请重试';
-    }
-    finally {
-        if (page) {
-            await page.close();
+
+    const buttons = buildRankingButtons(session, cfg, rankingType);
+    const text = buildRankingText(data);
+
+    // 按配置选择文字/图片（QQ 官方机器人会自动附带按钮）
+    return await messageRender.renderByType(ctx, session, cfg, 'tmpVtcMileageRanking.type', {
+        text,
+        buttons,
+        caption: '车队' + (Number(rankingType) === 2 ? '今日' : '总') + '里程排行榜',
+        alt: '里程排行榜',
+        image: async () => {
+            if (!ctx.puppeteer) return null;
+            let page;
+            try {
+                page = await ctx.puppeteer.page();
+                await page.setViewport({ width: 1000, height: 1000, deviceScaleFactor: 2 });
+                await page.goto(`file:///${resolve(__dirname, '../resource/mileage-leaderboard.html')}`);
+                await page.evaluate(`setData(${JSON.stringify(data)})`);
+                await page.waitForNetworkIdle();
+                await common.sleep(500);
+                const element = await page.$("#container");
+                return segment.image(await element.screenshot({ encoding: "binary" }), "image/jpeg");
+            } catch (e) {
+                console.info(e);
+                return null;
+            } finally {
+                if (page) {
+                    try { await page.close(); } catch { }
+                }
+            }
         }
-    }
+    });
 };
+
+/**
+ * 排行榜按钮（仅 QQ 官方机器人可见，onebot 自动忽略）。
+ */
+function buildRankingButtons(session, cfg, rankingType) {
+    if (!qqOfficial.isQQOfficial(session)) return [];
+    const rows = [];
+    const isToday = Number(rankingType) === 2;
+    if (isToday) {
+        rows.push([qqOfficial.inputButton('查看总榜', 'vtc里程排行榜', true)]);
+    } else {
+        rows.push([qqOfficial.inputButton('查看今日榜', 'vtc今日里程排行榜', true)]);
+    }
+    rows.push([qqOfficial.inputButton('我的绑定', '我的绑定')]);
+    return rows;
+}
+
+/**
+ * 排行榜文字版（图片不可用或配置为文字时使用）。
+ */
+function buildRankingText(data) {
+    const typeText = Number(data.rankingType) === 2 ? '今日' : '总';
+    const list = Array.isArray(data.mileageRankingList) ? data.mileageRankingList : [];
+    const lines = [`## 车队${typeText}里程排行榜`, ''];
+    list.slice(0, 10).forEach((p, i) => {
+        lines.push(`${i + 1}. ${p.name || '未知'}  ${formatKm(p.mileage)}`);
+    });
+    if (data.playerMileageRanking) {
+        const me = data.playerMileageRanking;
+        const rank = list.indexOf(me) + 1;
+        lines.push('', `**你的排名**：第 ${rank || '-'} 名  ${formatKm(me.mileage)}`);
+    }
+    return lines.join('\n');
+}
+
+function formatKm(v) {
+    const n = Number(v);
+    return Number.isFinite(n) ? `${n.toLocaleString('en-US')} km` : '-';
+}

package/lib/command/tmpVtcOnline/tmpVtcOnlineImg.js

@@ -37,7 +37,7 @@ module.exports = async (ctx, cfg) => {
     await common.sleep(100);
     await page.waitForNetworkIdle();
     const element = await page.$('#container');
-    return segment.image(await element.screenshot({ encoding: 'binary' }), 'image/jpg');
+    return segment.image(await element.screenshot({ encoding: 'binary' }), 'image/jpeg');
   } catch {
     return '渲染异常，请重试';
   } finally {

package/lib/database/guildBind.js

@@ -66,6 +66,50 @@ module.exports = {
         }
         return guildBindList.sort((a, b) => a.id - b.id);
     },
+    /**
+     * 获取绑定列表，**带跨群兜底**（QQ 官方机器人专用能力）。
+     *
+     * 背景：QQ 官方机器人在不同群下发的 openid 可能不同，
+     * 所以 (platform, user_id) 查不到时，再用 union_id 兜一次 —— 用户只要在任意一个群绑定过，
+     * 换群后依然能查到自己的绑定。
+     *
+     * onebot 完全不受影响：
+     * - onebot 的 session 没有 unionId，`identity` 传 null，走的就是原 list()；
+     * - 原有 `list()` 保持不变，仍然按 (platform, user_id) 精确查。
+     *
+     * @param {object} db 数据源
+     * @param {string} platform 平台
+     * @param {string} userId 用户编号（onebot=QQ号，qq=openid）
+     * @param {object} [identity] QQ 官方身份 {openid, unionId}；onebot 传 null/不传
+     * @returns 绑定行数组（按 id 排序）
+     */
+    async listWithUnion(db, platform, userId, identity) {
+        const own = await this.list(db, platform, userId);
+        if (own.length > 0) {
+            return own;
+        }
+        // 没有 union 身份（onebot / 未申请权限）→ 与 list() 完全一致，不产生额外查询
+        const unionId = identity && identity.unionId;
+        if (!unionId) {
+            return own;
+        }
+        const crossRows = await this.listByUnionId(db, unionId);
+        if (crossRows.length === 0) {
+            return own;
+        }
+        // 只取同一平台的，避免 qq 与 onebot 的数据互相串
+        return crossRows
+            .filter(r => String(r.platform) === String(platform))
+            .sort((a, b) => a.id - b.id);
+    },
+    /**
+     * 获取默认绑定，带跨群兜底（语义同 listWithUnion）。
+     */
+    async getWithUnion(db, platform, userId, identity) {
+        const rows = await this.listWithUnion(db, platform, userId, identity);
+        if (rows.length === 0) return null;
+        return rows.find(r => this.isDefault(r)) || rows[0];
+    },
     /**
      * 获取指定用户（可含平台前缀，如 qq:123）的全部绑定。
      * 用于 @别人 查询：内部统一去掉 `qq:` 这类前缀再匹配，兼容库里两种存法。
@@ -127,6 +171,31 @@ module.exports = {
         const result = await this.setDefault(ctx, db, platform, userId, rows[idx - 1].id);
         return { ...result, total: rows.length };
     },
+    /**
+     * 按序号设为默认（跨群安全版）：直接用「已查到的行」，不再按 (platform,user_id) 反查。
+     * @param rows 调用方已查到的绑定行（顺序即展示顺序）
+     */
+    async setDefaultByIndexFromRows(db, rows, index) {
+        const list = Array.isArray(rows) ? rows : [];
+        const idx = parseInt(index, 10);
+        if (isNaN(idx) || idx < 1 || idx > list.length) {
+            return { row: null, changed: false, total: list.length };
+        }
+        const target = list[idx - 1];
+        if (this.isDefault(target)) {
+            return { row: target, changed: false, total: list.length };
+        }
+        // 同一批行里其他默认标记清掉，保证「至多一个默认」
+        await Promise.all(list
+            .filter(r => r.id !== target.id && this.isDefault(r))
+            .map(r => db.set('tmp_guild_bind', r.id, { is_default: 0 })));
+        await db.set('tmp_guild_bind', target.id, { is_default: 1 });
+        target.is_default = 1;
+        for (const r of list) {
+            if (r.id !== target.id) r.is_default = 0;
+        }
+        return { row: target, changed: true, total: list.length };
+    },
     /**
      * 追加绑定（同一 tmpId 重复绑定时不会重复入库）
      * 第一个绑定自动成为默认绑定。
@@ -134,10 +203,17 @@ module.exports = {
      * @param tmpName TMP 玩家名称（用于多绑定列表展示，可为 null）
      * @returns { exists, row, isDefault } exists=true 表示该 tmpId 已绑定过
      */
-    async add(db, platform, userId, tmpId, tmpName) {
+    /**
+     * 新增绑定。
+     * @param {object} [identity] QQ 官方机器人身份 {openid, unionId}；
+     *        传了就会一并写入 openid / union_id 列（onebot 下不传，保持为 null）
+     */
+    async add(db, platform, userId, tmpId, tmpName, identity) {
         const guildBindList = await this.list(db, platform, userId);
         const existed = guildBindList.find(row => String(row.tmp_id) === String(tmpId));
         if (existed) {
+            // 已绑定过：顺带补齐 openid / union_id（老数据升级路径）
+            await this.fillIdentity(db, existed, identity);
             return { exists: true, row: existed, isDefault: this.isDefault(existed) };
         }
         // 还没有任何默认绑定（含首次绑定、以及历史数据全无标记）时，新绑定即默认
@@ -145,12 +221,85 @@ module.exports = {
         const row = await db.create('tmp_guild_bind', {
             platform: platform,
             user_id: userId,
+            openid: (identity && identity.openid) || null,
+            union_id: (identity && identity.unionId) || null,
             tmp_id: tmpId,
             tmp_name: tmpName || null,
             is_default: needDefault ? 1 : 0
         });
         return { exists: false, row, isDefault: needDefault };
     },
+    /**
+     * 给已有绑定补齐 openid / union_id（只在拿到新值且与库里不同时才写）。
+     */
+    async fillIdentity(db, row, identity) {
+        if (!row || !identity) return row;
+        const patch = {};
+        if (identity.openid && row.openid !== identity.openid) patch.openid = identity.openid;
+        if (identity.unionId && row.union_id !== identity.unionId) patch.union_id = identity.unionId;
+        if (Object.keys(patch).length === 0) return row;
+        await db.set('tmp_guild_bind', row.id, patch);
+        Object.assign(row, patch);
+        return row;
+    },
+    /**
+     * 按 union_id 查全部绑定（跨群统一身份）。
+     *
+     * 场景：QQ 官方机器人在不同群下发的 openid 可能不同，但 union_id 一致。
+     * 用户在 A 群绑定过，去 B 群用同一个 union_id 就能直接认出来。
+     *
+     * @returns 绑定行数组，可能为空数组
+     */
+    async listByUnionId(db, unionId) {
+        if (!unionId) return [];
+        const rows = await db.get('tmp_guild_bind', { union_id: String(unionId) });
+        return rows || [];
+    },
+    /**
+     * 按 openid 查绑定（同群内身份）。
+     */
+    async listByOpenid(db, openid) {
+        if (!openid) return [];
+        const rows = await db.get('tmp_guild_bind', { openid: String(openid) });
+        return rows || [];
+    },
+    /**
+     * 按「已查到的绑定行」删除（跨群安全版）。
+     *
+     * 跨群场景下 user_id 是对方群的 openid，不能再用 (platform,user_id) 反查，
+     * 所以直接把「用户看到的那批行」传进来，删的正是他眼前那一条。
+     *
+     * @param rows 调用方已经查到的绑定行（顺序即展示顺序）
+     * @param id 要删除的行主键
+     * @returns { removedDefault, promoted } 语义同 remove()
+     */
+    async removeFromRows(db, rows, id) {
+        const list = Array.isArray(rows) ? rows : [];
+        const target = list.find(r => r.id === id);
+        const wasDefault = this.isDefault(target);
+        await db.remove('tmp_guild_bind', id);
+        if (!wasDefault) {
+            return { removedDefault: false, promoted: null };
+        }
+        const rest = list.filter(r => r.id !== id);
+        if (rest.length === 0) {
+            return { removedDefault: true, promoted: null };
+        }
+        await db.set('tmp_guild_bind', rest[0].id, { is_default: 1 });
+        rest[0].is_default = 1;
+        return { removedDefault: true, promoted: rest[0] };
+    },
+    /**
+     * 删除「已查到的绑定行」全部（跨群安全版）。
+     * @returns 实际删除的条数
+     */
+    async removeAllFromRows(db, rows) {
+        const list = Array.isArray(rows) ? rows : [];
+        for (const row of list) {
+            await db.remove('tmp_guild_bind', row.id);
+        }
+        return list.length;
+    },
     /**
      * 删除指定主键的绑定；若删掉的正是默认绑定，自动把剩下的第一条顶为默认，
      * 避免「有绑定却没有默认」的空档。