koishi-plugin-ll-mc 1.0.0

package/lib/index.js

@@ -0,0 +1,2659 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = exports.inject = exports.name = void 0;
+exports.apply = apply;
+const koishi_1 = require("koishi");
+const path_1 = __importDefault(require("path"));
+const fs = __importStar(require("fs/promises"));
+const fs_1 = require("fs");
+const crypto = __importStar(require("crypto"));
+const assetsDir = path_1.default.resolve(__dirname, "..", "assets");
+let fallbackBase64 = [""];
+exports.name = "mc";
+exports.inject = {
+    required: ["database", "cron"],
+    optional: ["markdownToImage", "puppeteer", "canvas"],
+};
+const logger = new koishi_1.Logger("mc");
+// --- 定义字体选项常量 ---
+const FONT_OPTIONS = {
+    TITLE: "HarmonyOS_Sans_Medium",
+    NICKNAME: "HarmonyOS_Sans_Medium",
+};
+// pz*
+// pz*
+exports.Config = koishi_1.Schema.intersect([
+    // --- 核心功能 ---
+    koishi_1.Schema.object({
+        isBotMessageTrackingEnabled: koishi_1.Schema.boolean()
+            .default(false)
+            .description("是否统计 Bot 自己发送的消息。"),
+    }).description("核心功能"),
+    // --- 排行榜设置 ---
+    koishi_1.Schema.object({
+        defaultMaxDisplayCount: koishi_1.Schema.number()
+            .min(0)
+            .default(20)
+            .description("排行榜默认显示的人数。设置为 0 则显示所有。"),
+        isTimeInfoSupplementEnabled: koishi_1.Schema.boolean()
+            .default(true)
+            .description("是否在排行榜标题中显示生成时间。"),
+        isUserMessagePercentageVisible: koishi_1.Schema.boolean()
+            .default(true)
+            .description("是否在排行榜中显示用户的消息数占比。"),
+        hiddenUserIdsInLeaderboard: koishi_1.Schema.array(String)
+            .role("table")
+            .description("全局隐藏的用户 ID 列表，在所有用户排行榜中生效。"),
+        hiddenChannelIdsInLeaderboard: koishi_1.Schema.array(String)
+            .role("table")
+            .description("全局隐藏的频道 ID 列表，在群排行榜中生效。"),
+        excludedChannelIds: koishi_1.Schema.array(String)
+            .role("table")
+            .description("排除统计的频道 ID 列表，这些群的消息不会被计数。"),
+    }).description("排行榜设置"),
+    // --- 图片生成 ---
+    koishi_1.Schema.intersect([
+        koishi_1.Schema.object({
+            isTextToImageConversionEnabled: koishi_1.Schema.boolean()
+                .default(false)
+                .description("是否将文本排行榜转为 Markdown 图片（依赖 `markdownToImage` 服务）。"),
+            isLeaderboardToHorizontalBarChartConversionEnabled: koishi_1.Schema.boolean()
+                .default(false)
+                .description("是否将排行榜渲染为水平柱状图（依赖 `puppeteer` 服务）。"),
+        }).description("图片生成"),
+        // 仅在开启柱状图功能时显示以下详细选项
+        koishi_1.Schema.union([
+            koishi_1.Schema.intersect([
+                koishi_1.Schema.object({
+                    isLeaderboardToHorizontalBarChartConversionEnabled: koishi_1.Schema.const(true).required(),
+                    imageType: koishi_1.Schema.union(["png", "jpeg", "webp"])
+                        .default("png")
+                        .description(`生成的柱状图图片格式。`),
+                }).description("柱状图基础设置"),
+                koishi_1.Schema.object({
+                    chartViewportWidth: koishi_1.Schema.number()
+                        .min(1)
+                        .default(1080)
+                        .description("渲染页面的视口宽度（像素）。此值会影响图片清晰度及背景图的展示。"),
+                    deviceScaleFactor: koishi_1.Schema.number()
+                        .min(0.1)
+                        .max(4)
+                        .step(0.1)
+                        .default(1)
+                        .description("设备像素比 (DPR)。更高的值可生成更清晰的图片（如 2 倍图），但会增加文件体积。"),
+                    waitUntil: koishi_1.Schema.union([
+                        "load",
+                        "domcontentloaded",
+                        "networkidle0",
+                        "networkidle2",
+                    ])
+                        .default("networkidle0")
+                        .description("页面加载等待策略，影响图片生成速度和稳定性。`networkidle0` 最稳定。"),
+                }).description("渲染与性能"),
+                koishi_1.Schema.object({
+                    avatarCacheTTL: koishi_1.Schema.number()
+                        .default(86400) // 24 hours
+                        .description("头像缓存有效期（秒）。设置为 0 则永不刷新。过短的有效期会增加网络请求。"),
+                    avatarFailureCacheTTL: koishi_1.Schema.number()
+                        .default(300) // 5 minutes
+                        .description("头像获取失败后的重试间隔（秒）。期间将使用默认头像，避免频繁请求无效链接。"),
+                }).description("缓存设置"),
+                koishi_1.Schema.object({
+                    shouldMoveIconToBarEndLeft: koishi_1.Schema.boolean()
+                        .default(true)
+                        .description("是否将自定义图标显示在进度条的末端。关闭则显示在用户名旁。"),
+                    showStarInChart: koishi_1.Schema.boolean()
+                        .default(true)
+                        .description("是否在图表中对触发指令的用户/群聊名称前添加 ★ 以高亮显示。"),
+                    horizontalBarBackgroundOpacity: koishi_1.Schema.number()
+                        .min(0)
+                        .max(1)
+                        .step(0.05)
+                        .default(0.6)
+                        .description("自定义背景图在进度条区域的不透明度。"),
+                    horizontalBarBackgroundFullOpacity: koishi_1.Schema.number()
+                        .min(0)
+                        .max(1)
+                        .step(0.05)
+                        .default(0)
+                        .description("自定义背景图在整行背景区域的不透明度。"),
+                }).description("样式定制"),
+                koishi_1.Schema.object({
+                    maxBarBgWidth: koishi_1.Schema.number()
+                        .min(0)
+                        .default(850)
+                        .description("允许上传的背景图最大宽度（像素）。0为不限制。"),
+                    maxBarBgHeight: koishi_1.Schema.number()
+                        .min(0)
+                        .default(50)
+                        .description("允许上传的背景图最大高度（像素）。0为不限制。"),
+                    maxBarBgSize: koishi_1.Schema.number()
+                        .min(0)
+                        .default(5)
+                        .description("允许上传的背景图最大体积（MB）。0为不限制。"),
+                }).description("上传限制"),
+                // 背景设置（条件化）
+                koishi_1.Schema.intersect([
+                    koishi_1.Schema.object({
+                        backgroundType: koishi_1.Schema.union([
+                            koishi_1.Schema.const("none").description("默认渐变"),
+                            koishi_1.Schema.const("api").description("API 获取"),
+                            koishi_1.Schema.const("css").description("自定义 CSS"),
+                        ])
+                            .default("none")
+                            .description("图片整体背景类型。"),
+                    }),
+                    koishi_1.Schema.union([
+                        koishi_1.Schema.object({
+                            backgroundType: koishi_1.Schema.const("api").required(),
+                            apiBackgroundConfig: koishi_1.Schema.object({
+                                apiUrl: koishi_1.Schema.string()
+                                    .description("获取背景图的 API 地址。")
+                                    .required(),
+                                apiKey: koishi_1.Schema.string()
+                                    .role("secret")
+                                    .description("API 的访问凭证（可选）。"),
+                                responseType: koishi_1.Schema.union(["binary", "url", "base64"])
+                                    .default("binary")
+                                    .description("API 返回的数据类型。"),
+                            })
+                                .description("API 背景配置")
+                                .collapse(),
+                        }),
+                        koishi_1.Schema.object({
+                            backgroundType: koishi_1.Schema.const("css").required(),
+                            backgroundValue: koishi_1.Schema.string()
+                                .role("textarea", { rows: [2, 4] })
+                                .default(`html {\n  background: linear-gradient(135deg, #f6f8f9 0%, #e5ebee 100%);\n}`)
+                                .description("自定义背景的 CSS 代码。建议使用 `html` 选择器来设置背景。"),
+                        }),
+                        koishi_1.Schema.object({}),
+                    ]),
+                ]).description("背景设置"),
+                koishi_1.Schema.object({
+                    chartTitleFont: koishi_1.Schema.string()
+                        .default(FONT_OPTIONS.TITLE)
+                        .description(`标题字体。填写 'data/mc/fonts' 目录中的字体文件名（不含后缀）。`),
+                    chartNicknameFont: koishi_1.Schema.string()
+                        .default(FONT_OPTIONS.NICKNAME)
+                        .description(`昵称与计数字体。填写 'data/mc/fonts' 目录中的字体文件名（不含后缀），或使用通用字体名称。`),
+                }).description("字体设置"),
+            ]),
+            koishi_1.Schema.object({}),
+        ]),
+    ]),
+    // --- 自动推送 ---
+    koishi_1.Schema.intersect([
+        koishi_1.Schema.object({
+            autoPush: koishi_1.Schema.boolean()
+                .default(false)
+                .description("是否启用定时自动推送排行榜功能。"),
+        }).description("自动推送"),
+        koishi_1.Schema.union([
+            koishi_1.Schema.intersect([
+                koishi_1.Schema.object({
+                    autoPush: koishi_1.Schema.const(true).required(),
+                    shouldSendDailyLeaderboardAtMidnight: koishi_1.Schema.boolean()
+                        .default(true)
+                        .description("每日 0 点自动发送昨日排行榜。"),
+                    shouldSendWeeklyLeaderboard: koishi_1.Schema.boolean()
+                        .default(false)
+                        .description("每周一 0 点自动发送上周排行榜。"),
+                    shouldSendMonthlyLeaderboard: koishi_1.Schema.boolean()
+                        .default(false)
+                        .description("每月一日 0 点自动发送上月排行榜。"),
+                    shouldSendYearlyLeaderboard: koishi_1.Schema.boolean()
+                        .default(false)
+                        .description("每年一日 0 点自动发送去年排行榜。"),
+                    dailyScheduledTimers: koishi_1.Schema.array(String)
+                        .role("table")
+                        .description("其他定时发送今日排行榜的时间点（24小时制，如 `08:00`）。"),
+                }).description("推送时机"),
+                koishi_1.Schema.object({
+                    pushChannelIds: koishi_1.Schema.array(String)
+                        .role("table")
+                        .description("需要接收自动推送的频道 ID 列表。"),
+                    shouldSendLeaderboardNotificationsToAllChannels: koishi_1.Schema.boolean()
+                        .default(false)
+                        .description("是否向机器人所在的所有群聊推送（可能造成打扰，请谨慎开启）。"),
+                    excludedLeaderboardChannels: koishi_1.Schema.array(String)
+                        .role("table")
+                        .description("当“向所有群聊推送”开启时，此处指定的频道将不会收到推送。"),
+                }).description("推送目标"),
+                koishi_1.Schema.object({
+                    isGeneratingRankingListPromptVisible: koishi_1.Schema.boolean()
+                        .default(true)
+                        .description("发送排行榜前，是否先发送一条“正在生成”的提示消息。"),
+                    leaderboardGenerationWaitTime: koishi_1.Schema.number()
+                        .min(0)
+                        .default(3)
+                        .description("发送提示消息后，等待多少秒再发送排行榜图片。"),
+                    delayBetweenGroupPushesInSeconds: koishi_1.Schema.number()
+                        .min(0)
+                        .default(5)
+                        .description("批量推送时，每个群之间的基础发送延迟（秒），以防风控。"),
+                    groupPushDelayRandomizationSeconds: koishi_1.Schema.number()
+                        .min(0)
+                        .default(10)
+                        .description("在基础延迟之上，增加一个随机波动范围（秒），以模拟人工操作。"),
+                }).description("推送行为"),
+            ]),
+            koishi_1.Schema.object({}),
+        ]),
+    ]),
+    // --- 龙王禁言 ---
+    koishi_1.Schema.intersect([
+        koishi_1.Schema.object({
+            enableMostActiveUserMuting: koishi_1.Schema.boolean()
+                .default(false)
+                .description("是否在每日 0 点自动禁言昨日发言最多的人（“抓龙王”）。"),
+        }).description("龙王禁言"),
+        koishi_1.Schema.union([
+            koishi_1.Schema.object({
+                enableMostActiveUserMuting: koishi_1.Schema.const(true).required(),
+                dragonKingDetainmentTime: koishi_1.Schema.number()
+                    .min(0)
+                    .default(5)
+                    .description("0 点后，等待多少秒再执行禁言操作。"),
+                detentionDuration: koishi_1.Schema.number()
+                    .min(1)
+                    .default(1)
+                    .description("禁言时长（天）。"),
+                muteChannelIds: koishi_1.Schema.array(String)
+                    .role("table")
+                    .description("在哪些频道中执行“抓龙王”操作。"),
+            }),
+            koishi_1.Schema.object({}),
+        ]),
+    ]),
+]);
+const periodMapping = {
+    today: { field: "todayPostCount", name: "今日" },
+    yesterday: { field: "yesterdayPostCount", name: "昨日" },
+    week: { field: "thisWeekPostCount", name: "本周" },
+    month: { field: "thisMonthPostCount", name: "本月" },
+    year: { field: "thisYearPostCount", name: "今年" },
+    total: { field: "totalPostCount", name: "总" },
+};
+async function apply(ctx, config) {
+    // cl*
+    // 定义一个唯一的 Symbol 作为处理标记，防止与其他插件冲突
+    const PROCESSED = Symbol("message-counter.processed");
+    // --- 资源路径和缓存初始化 ---
+    const dataRoot = path_1.default.join(ctx.baseDir, "data");
+    const messageCounterRoot = path_1.default.join(dataRoot, "mc"); // 统一资源根目录
+    const iconsPath = path_1.default.join(messageCounterRoot, "icons");
+    const barBgImgsPath = path_1.default.join(messageCounterRoot, "barBgImgs");
+    const fontsPath = path_1.default.join(messageCounterRoot, "fonts"); // 字体目录路径
+    const avatarsPath = path_1.default.join(messageCounterRoot, "avatars");
+    const emptyHtmlPath = path_1.default
+        .join(messageCounterRoot, "emptyHtml.html")
+        .replace(/\\/g, "/");
+    // 兼容旧版插件的资源路径
+    const oldIconsPath = path_1.default.join(dataRoot, "mcIcons");
+    const oldBarBgImgsPath = path_1.default.join(dataRoot, "mcBarBgImgs");
+    // 自动创建所有必要的目录
+    await fs.mkdir(fontsPath, { recursive: true });
+    await fs.mkdir(iconsPath, { recursive: true });
+    await fs.mkdir(barBgImgsPath, { recursive: true });
+    await fs.mkdir(avatarsPath, { recursive: true });
+    await migrateFolder(oldIconsPath, iconsPath);
+    await migrateFolder(oldBarBgImgsPath, barBgImgsPath);
+    // 确保 emptyHtml.html 存在，用于 puppeteer 渲染
+    try {
+        await fs.access(emptyHtmlPath, fs_1.constants.F_OK);
+    }
+    catch {
+        // 文件不存在，则创建一个空文件
+        await fs.writeFile(emptyHtmlPath, "");
+        logger.info(`已创建空的渲染模板文件: emptyHtml.html`);
+    }
+    // 加载内置回退头像 base64
+    try {
+        const fallbackJson = await fs.readFile(path_1.default.join(assetsDir, "fallbackBase64.json"), "utf-8");
+        fallbackBase64 = JSON.parse(fallbackJson);
+    }
+    catch (error) {
+        logger.warn("无法加载 fallbackBase64.json，将使用空的回退头像。", error);
+    }
+    // 拷贝内置字体
+    const fontFiles = ["HarmonyOS_Sans_Medium.ttf"];
+    for (const fontFile of fontFiles) {
+        await copyAssetIfNotExists(path_1.default.join(assetsDir, "fonts"), fontsPath, fontFile);
+    }
+    // 缓存
+    const avatarCache = new Map();
+    let iconCache = [];
+    let barBgImgCache = [];
+    let fontFilesCache = []; // 字体文件缓存
+    // --- 数据库表定义 ---
+    ctx.model.extend("message_counter_records", {
+        // id: "unsigned",
+        channelId: "string",
+        channelName: "string",
+        userId: "string",
+        username: "string",
+        userAvatar: "string",
+        todayPostCount: "unsigned",
+        thisWeekPostCount: "unsigned",
+        thisMonthPostCount: "unsigned",
+        thisYearPostCount: "unsigned",
+        totalPostCount: "unsigned",
+        yesterdayPostCount: "unsigned",
+    }, {
+        primary: ["channelId", "userId"],
+    });
+    ctx.model.extend("message_counter_state", {
+        key: "string",
+        value: "timestamp",
+    }, { primary: "key" });
+    // 限定在群组中
+    const channelCtx = ctx.channel();
+    // 在插件启动完成后设置定时任务
+    ctx.on("ready", async () => {
+        // 启动时加载缓存
+        await reloadIconCache();
+        await reloadBarBgImgCache();
+        await reloadFontCache();
+        // 执行非破坏性的状态初始化
+        await initializeResetStates();
+        // 安全地检查并弥补真正错过的重置任务
+        await checkForMissedResets();
+        // --- 设置所有定时任务 ---
+        // 1. 自动推送排行榜的定时任务
+        if (config.autoPush) {
+            if (config.shouldSendDailyLeaderboardAtMidnight) {
+                const task = ctx.cron("1 0 * * *", () => generateAndPushLeaderboard("yesterday"));
+                scheduledTasks.push(task);
+                logger.info("[自动推送] 已设置每日 00:01 推送昨日排行榜的任务。");
+            }
+            (config.dailyScheduledTimers || []).forEach((time) => {
+                const match = /^([0-1]?[0-9]|2[0-3]):([0-5]?[0-9])$/.exec(time);
+                if (match) {
+                    const [_, hour, minute] = match;
+                    const cron = `${minute} ${hour} * * *`;
+                    const task = ctx.cron(cron, () => generateAndPushLeaderboard("today"));
+                    scheduledTasks.push(task);
+                    logger.info(`[自动推送] 已设置每日 ${time} 推送今日排行榜的任务。`);
+                }
+                else {
+                    logger.warn(`[自动推送] 无效的时间格式: "${time}"，已跳过。请使用 "HH:mm" 格式。`);
+                }
+            });
+        }
+        // 2. 抓龙王（禁言）的定时任务
+        if (config.enableMostActiveUserMuting) {
+            const task = ctx.cron("1 0 * * *", () => performDragonKingMuting());
+            scheduledTasks.push(task);
+            logger.info("[抓龙王] 已设置每日 00:01 执行的禁言任务。");
+        }
+        // 3. 统一的推送与数据库重置定时任务
+        // 此任务在每天 00:00 执行
+        const resetTask = ctx.cron("0 0 * * *", async () => {
+            const now = new Date();
+            const dayOfMonth = now.getDate();
+            const month = now.getMonth(); // 0-11
+            const dayOfWeek = now.getDay(); // 0 = Sunday, 1 = Monday
+            // --- 周期性推送 (在数据重置之前执行) ---
+            // 在每年1月1日 00:00，重置年度数据前，推送去年的排行榜
+            if (config.autoPush &&
+                config.shouldSendYearlyLeaderboard &&
+                dayOfMonth === 1 &&
+                month === 0) {
+                await generateAndPushLeaderboard("year");
+            }
+            // 在每月1日 00:00，重置月度数据前，推送上个月的排行榜
+            if (config.autoPush &&
+                config.shouldSendMonthlyLeaderboard &&
+                dayOfMonth === 1) {
+                await generateAndPushLeaderboard("month");
+            }
+            // 在每周一 00:00，重置周数据前，推送上一周的排行榜
+            if (config.autoPush &&
+                config.shouldSendWeeklyLeaderboard &&
+                dayOfWeek === 1) {
+                await generateAndPushLeaderboard("week");
+            }
+            // --- 数据重置 (在周期性推送之后执行) ---
+            // 每日重置 (总是执行), 它会先把 today 备份到 yesterday
+            await resetCounter("todayPostCount", "今日发言榜已成功置空！", "daily");
+            // 每周重置 (在周一 00:00 执行)
+            if (dayOfWeek === 1) {
+                await resetCounter("thisWeekPostCount", "本周发言榜已成功置空！", "weekly");
+            }
+            // 每月重置 (在每月1号 00:00 执行)
+            if (dayOfMonth === 1) {
+                await resetCounter("thisMonthPostCount", "本月发言榜已成功置空！", "monthly");
+            }
+            // 每年重置 (在1月1号 00:00 执行)
+            if (dayOfMonth === 1 && month === 0) {
+                await resetCounter("thisYearPostCount", "今年发言榜已成功置空！", "yearly");
+            }
+        });
+        // 将这一个统一的任务添加到待清理列表
+        scheduledTasks.push(resetTask);
+        logger.info("已设置统一的推送与数据重置任务（每日、周、月、年）。");
+    });
+    // --- 资源清理 ---
+    ctx.on("dispose", () => {
+        // 调用 disposer 函数来取消定时任务
+        scheduledTasks.forEach((task) => task());
+        avatarCache.clear();
+        iconCache = [];
+        barBgImgCache = [];
+        fontFilesCache = [];
+        logger.info("所有已安排的任务和缓存都已清除。");
+    });
+    // --- 核心消息监听器 ---
+    // jt*
+    channelCtx.middleware(async (session, next) => {
+        // 检查此消息是否已被本插件处理过，如果是，则直接跳过
+        if (session[PROCESSED])
+            return next();
+        // 忽略无效会话或机器人自身消息（除非配置允许）
+        if (!session.userId ||
+            !session.channelId ||
+            (session.author?.isBot && !config.isBotMessageTrackingEnabled)) {
+            return next();
+        }
+        // 排除指定群聊的统计
+        if (config.excludedChannelIds?.includes(session.channelId))
+            return next();
+        session[PROCESSED] = true;
+        const { userId, channelId, author } = session;
+        let sessionChannelName = session.event.channel.name;
+        const username = author?.nick || author?.name || userId;
+        const userAvatar = author?.avatar;
+        try {
+            const channelName = sessionChannelName ||
+                (channelId ? await getChannelName(session.bot, channelId) : channelId);
+            await ctx.database.upsert("message_counter_records", (row) => [
+                {
+                    channelId,
+                    userId,
+                    username,
+                    userAvatar: userAvatar || row.userAvatar,
+                    channelName: channelName || row.channelName,
+                    todayPostCount: koishi_1.$.add(row.todayPostCount, 1),
+                    thisWeekPostCount: koishi_1.$.add(row.thisWeekPostCount, 1),
+                    thisMonthPostCount: koishi_1.$.add(row.thisMonthPostCount, 1),
+                    thisYearPostCount: koishi_1.$.add(row.thisYearPostCount, 1),
+                    totalPostCount: koishi_1.$.add(row.totalPostCount, 1),
+                },
+            ], ["channelId", "userId"]);
+        }
+        catch (error) {
+            logger.error("Failed to update message count for user %s in channel %s:", userId, channelId, error);
+        }
+        // 继续消息处理链
+        return next();
+    }, true);
+    // 统计机器人自身消息
+    if (config.isBotMessageTrackingEnabled) {
+        ctx.before("send", async (session) => {
+            if (!session.channelId)
+                return;
+            const { channelId, bot } = session;
+            let sessionChannelName = session.event.channel.name;
+            const botUser = bot.user;
+            if (!botUser) {
+                logger.warn("Bot user is undefined, skipping bot message tracking.");
+                return;
+            }
+            try {
+                const channelName = sessionChannelName ||
+                    (await getChannelName(bot, channelId)) ||
+                    channelId;
+                await ctx.database.upsert("message_counter_records", (row) => [
+                    {
+                        channelId,
+                        userId: botUser.id,
+                        username: botUser.name,
+                        userAvatar: botUser.avatar,
+                        channelName: channelName || row.channelName,
+                        todayPostCount: koishi_1.$.add(row.todayPostCount, 1),
+                        thisWeekPostCount: koishi_1.$.add(row.thisWeekPostCount, 1),
+                        thisMonthPostCount: koishi_1.$.add(row.thisMonthPostCount, 1),
+                        thisYearPostCount: koishi_1.$.add(row.thisYearPostCount, 1),
+                        totalPostCount: koishi_1.$.add(row.totalPostCount, 1),
+                    },
+                ], ["channelId", "userId"]);
+            }
+            catch (error) {
+                logger.error("Failed to update bot message count in channel %s:", channelId, error);
+            }
+        });
+    }
+    // --- 指令定义 ---
+    // zl*
+    ctx
+        .command("mc", "查看消息统计帮助")
+        .action(({ session }) => session?.execute(`help mc`));
+    ctx
+        .command("mc.初始化", "初始化", { authority: 3 })
+        .action(async ({ session }) => {
+        if (!session)
+            return;
+        await session.send("正在清空所有发言记录，请稍候...");
+        await ctx.database.remove("message_counter_records", {});
+        await session.send("所有发言记录已清空！");
+    });
+    // 查询指令
+    ctx
+        .command("mc.查询 [targetUser:text]", "查询指定用户的发言次数信息")
+        .userFields(["id", "name"])
+        .option("yesterday", "--yd 昨日发言")
+        .option("day", "-d 今日发言")
+        .option("week", "-w 本周发言")
+        .option("month", "-m 本月发言")
+        .option("year", "-y 今年发言")
+        .option("total", "-t 总发言")
+        .option("ydag", "跨群昨日发言")
+        .option("dag", "跨群今日发言")
+        .option("wag", "跨群本周发言")
+        .option("mag", "跨群本月发言")
+        .option("yag", "跨群本年发言")
+        .option("across", "-a 跨群总发言")
+        .action(async ({ session, options }, targetUser) => {
+        // -- 1. 选项解析 --
+        const optionKeys = [
+            "day",
+            "week",
+            "month",
+            "year",
+            "total",
+            "yesterday",
+            "dag",
+            "wag",
+            "mag",
+            "yag",
+            "ydag",
+            "across",
+        ];
+        const selectedOptions = {};
+        let noOptionSelected = true;
+        for (const key of optionKeys) {
+            if (options[key]) {
+                selectedOptions[key] = true;
+                noOptionSelected = false;
+            }
+        }
+        if (noOptionSelected) {
+            for (const key of optionKeys) {
+                selectedOptions[key] = true;
+            }
+        }
+        // -- 2. 用户信息与数据获取 --
+        let channelId = session?.channelId;
+        let userId = session?.userId;
+        let targetUserRecord = [];
+        if (targetUser) {
+            if (session)
+                targetUser = await replaceAtTags(session, targetUser);
+            const match = targetUser.match(/<at id="([^"]+)"/);
+            if (match)
+                userId = match[1];
+        }
+        targetUserRecord = await ctx.database.get("message_counter_records", {
+            channelId,
+            userId,
+        });
+        if (targetUserRecord.length === 0)
+            return `被查询对象无任何发言记录。`;
+        const channelUsers = await ctx.database.get("message_counter_records", {
+            channelId,
+        });
+        const allUsers = await ctx.database.get("message_counter_records", {});
+        const channelStats = [];
+        const acrossStats = [];
+        // 累加总数
+        const accumulate = (records) => records.reduce((sums, user) => {
+            for (const key in periodMapping) {
+                sums[periodMapping[key].field] =
+                    (sums[periodMapping[key].field] || 0) +
+                        user[periodMapping[key].field];
+            }
+            return sums;
+        }, {});
+        const channelTotals = accumulate(channelUsers);
+        const acrossTotals = accumulate(allUsers);
+        // 获取排名
+        const getRank = (records, field, uid) => {
+            const sorted = [...records].sort((a, b) => b[field] - a[field]);
+            const index = sorted.findIndex((u) => u.userId === uid);
+            return index !== -1 ? index + 1 : null;
+        };
+        const getAcrossRank = (records, field, uid) => {
+            const userTotals = records.reduce((acc, cur) => {
+                acc[cur.userId] = (acc[cur.userId] || 0) + cur[field];
+                return acc;
+            }, {});
+            const sorted = Object.entries(userTotals).sort(([, a], [, b]) => b - a);
+            const index = sorted.findIndex(([id]) => id === uid);
+            return index !== -1 ? index + 1 : null;
+        };
+        const getAcrossCount = (records, field, uid) => {
+            return records
+                .filter((r) => r.userId === uid)
+                .reduce((sum, r) => sum + r[field], 0);
+        };
+        // 填充本群数据
+        channelStats.push({
+            label: "昨日",
+            count: targetUserRecord[0].yesterdayPostCount,
+            total: channelTotals.yesterdayPostCount,
+            rank: getRank(channelUsers, "yesterdayPostCount", userId),
+            enabled: selectedOptions.yesterday,
+        });
+        channelStats.push({
+            label: "今日",
+            count: targetUserRecord[0].todayPostCount,
+            total: channelTotals.todayPostCount,
+            rank: getRank(channelUsers, "todayPostCount", userId),
+            enabled: selectedOptions.day,
+        });
+        channelStats.push({
+            label: "本周",
+            count: targetUserRecord[0].thisWeekPostCount,
+            total: channelTotals.thisWeekPostCount,
+            rank: getRank(channelUsers, "thisWeekPostCount", userId),
+            enabled: selectedOptions.week,
+        });
+        channelStats.push({
+            label: "本月",
+            count: targetUserRecord[0].thisMonthPostCount,
+            total: channelTotals.thisMonthPostCount,
+            rank: getRank(channelUsers, "thisMonthPostCount", userId),
+            enabled: selectedOptions.month,
+        });
+        channelStats.push({
+            label: "全年",
+            count: targetUserRecord[0].thisYearPostCount,
+            total: channelTotals.thisYearPostCount,
+            rank: getRank(channelUsers, "thisYearPostCount", userId),
+            enabled: selectedOptions.year,
+        });
+        channelStats.push({
+            label: "总计",
+            count: targetUserRecord[0].totalPostCount,
+            total: channelTotals.totalPostCount,
+            rank: getRank(channelUsers, "totalPostCount", userId),
+            enabled: selectedOptions.total,
+        });
+        // 填充跨群数据
+        acrossStats.push({
+            label: "昨日",
+            count: getAcrossCount(allUsers, "yesterdayPostCount", userId),
+            total: acrossTotals.yesterdayPostCount,
+            rank: getAcrossRank(allUsers, "yesterdayPostCount", userId),
+            enabled: selectedOptions.ydag,
+        });
+        acrossStats.push({
+            label: "今日",
+            count: getAcrossCount(allUsers, "todayPostCount", userId),
+            total: acrossTotals.todayPostCount,
+            rank: getAcrossRank(allUsers, "todayPostCount", userId),
+            enabled: selectedOptions.dag,
+        });
+        acrossStats.push({
+            label: "本周",
+            count: getAcrossCount(allUsers, "thisWeekPostCount", userId),
+            total: acrossTotals.thisWeekPostCount,
+            rank: getAcrossRank(allUsers, "thisWeekPostCount", userId),
+            enabled: selectedOptions.wag,
+        });
+        acrossStats.push({
+            label: "本月",
+            count: getAcrossCount(allUsers, "thisMonthPostCount", userId),
+            total: acrossTotals.thisMonthPostCount,
+            rank: getAcrossRank(allUsers, "thisMonthPostCount", userId),
+            enabled: selectedOptions.mag,
+        });
+        acrossStats.push({
+            label: "全年",
+            count: getAcrossCount(allUsers, "thisYearPostCount", userId),
+            total: acrossTotals.thisYearPostCount,
+            rank: getAcrossRank(allUsers, "thisYearPostCount", userId),
+            enabled: selectedOptions.yag,
+        });
+        acrossStats.push({
+            label: "总计",
+            count: getAcrossCount(allUsers, "totalPostCount", userId),
+            total: acrossTotals.totalPostCount,
+            rank: getAcrossRank(allUsers, "totalPostCount", userId),
+            enabled: selectedOptions.across,
+        });
+        // -- 4. 格式化与输出 --
+        const formatPercentage = (count, total) => {
+            if (total === 0)
+                return "(0%)";
+            const percentage = (count / total) * 100;
+            const numStr = percentage % 1 === 0 ? String(percentage) : percentage.toFixed(2);
+            return `(${numStr}%)`;
+        };
+        const formatStatsTable = (title, stats) => {
+            const activeStats = stats.filter((s) => s.enabled && s.count > 0);
+            if (activeStats.length === 0)
+                return "";
+            const counts = activeStats.map((s) => String(s.count));
+            const percents = activeStats.map((s) => formatPercentage(s.count, s.total));
+            const maxCountWidth = Math.max(0, ...counts.map((s) => s.length));
+            const maxPercentWidth = Math.max(0, ...percents.map((s) => s.length));
+            let table = `${title}\n`;
+            for (const row of activeStats) {
+                const label = row.label.padEnd(2, "　"); // 使用全角空格对齐中文
+                const countStr = String(row.count).padStart(maxCountWidth, " ");
+                const percentStr = formatPercentage(row.count, row.total).padEnd(maxPercentWidth, " ");
+                const rankStr = row.rank ? `#${row.rank}` : "#-";
+                table += `${label} ${countStr}  ${percentStr}  ${rankStr}\n`;
+            }
+            return table;
+        };
+        const channelTable = formatStatsTable("群发言", channelStats);
+        const acrossTable = formatStatsTable("跨群发言", acrossStats);
+        const body = [channelTable, acrossTable].filter(Boolean).join("\n");
+        if (!body)
+            return `被查询对象在指定时段内无发言记录。`;
+        // 使用 'sv-SE' locale 可以方便地得到 YYYY-MM-DD HH:MM:SS 格式
+        const timestamp = new Date().toLocaleString("sv-SE", {
+            timeZone: "Asia/Shanghai",
+        });
+        const header = `${timestamp}\n${targetUserRecord[0].username}\n\n`;
+        const message = header + body;
+        // -- 5. 图片转换 --
+        if (config.isTextToImageConversionEnabled && ctx.markdownToImage) {
+            try {
+                const imageBuffer = await ctx.markdownToImage.convertToImage(message);
+                return koishi_1.h.image(imageBuffer, `image/${config.imageType}`);
+            }
+            catch (error) {
+                logger.warn("生成图片失败，将回退到文本输出:", error);
+            }
+        }
+        // -- 6. 文本输出 (如果图片转换失败，或者未开启图片转换) --
+        return message;
+    });
+    // 排行榜指令
+    ctx
+        .command("mc.排行榜 [limit:number]", "用户发言排行榜")
+        .userFields(["id", "name"])
+        .option("whites", "<users:text> 白名单，用空格、逗号等分隔")
+        .option("blacks", "<users:text> 黑名单，用空格、逗号等分隔")
+        .option("yesterday", "--yd")
+        .option("day", "-d")
+        .option("week", "-w")
+        .option("month", "-m")
+        .option("year", "-y")
+        .option("total", "-t")
+        .option("ydag", "跨群昨日")
+        .option("dag", "跨群今日")
+        .option("wag", "跨群本周")
+        .option("mag", "跨群本月")
+        .option("yag", "跨群本年")
+        .option("dragon", "圣龙王榜 (跨群总榜)")
+        .action(async ({ session, options }, limit) => {
+        if (!session)
+            return;
+        const number = limit ?? config.defaultMaxDisplayCount;
+        if (typeof number !== "number" || isNaN(number) || number < 0) {
+            return "请输入大于等于 0 的数字作为排行榜显示人数。";
+        }
+        const whites = parseList(options?.whites);
+        const blacks = [
+            ...parseList(options?.blacks),
+            ...config.hiddenUserIdsInLeaderboard,
+        ];
+        const period = getPeriodFromOptions(options, "today");
+        const isAcross = isAcrossChannel(options);
+        const { field, name: periodName } = periodMapping[period];
+        const scopeName = isAcross ? "跨群" : "本群";
+        const rankTitle = `${scopeName}${periodName}发言排行榜`;
+        const rankTimeTitle = getCurrentBeijingTime();
+        let records;
+        if (isAcross) {
+            records = await ctx.database.get("message_counter_records", {});
+        }
+        else {
+            records = await ctx.database.get("message_counter_records", {
+                channelId: session.channelId,
+            });
+        }
+        const filteredRecords = filterRecordsByWhitesAndBlacks(records, "userId", whites, blacks);
+        if (filteredRecords.length === 0) {
+            return "当前范围内暂无发言记录。";
+        }
+        // 聚合数据
+        const userPostCounts = {};
+        const userInfo = {};
+        let totalCount = 0;
+        for (const record of filteredRecords) {
+            const count = record[field];
+            userPostCounts[record.userId] =
+                (userPostCounts[record.userId] || 0) + count;
+            if (!userInfo[record.userId]) {
+                userInfo[record.userId] = {
+                    username: record.username,
+                    avatar: record.userAvatar ||
+                        `https://q1.qlogo.cn/g?b=qq&nk=${record.userId}&s=640`,
+                };
+            }
+            totalCount += count;
+        }
+        const sortedUsers = Object.entries(userPostCounts).sort(([, a], [, b]) => b - a);
+        const rankingData = prepareRankingData(sortedUsers, userInfo, totalCount, number, session.userId);
+        return renderLeaderboard({
+            rankTimeTitle,
+            rankTitle,
+            rankingData,
+        });
+    });
+    ctx
+        .command("mc.群排行榜 [limit:number]", "群发言排行榜")
+        .option("specificUser", "-s <user:text> 特定用户的群发言榜")
+        .option("whites", "<channels:text> 白名单群号")
+        .option("blacks", "<channels:text> 黑名单群号")
+        .option("yesterday", "--yd")
+        .option("day", "-d")
+        .option("week", "-w")
+        .option("month", "-m")
+        .option("year", "-y")
+        .option("total", "-t")
+        .action(async ({ session, options }, limit) => {
+        if (!session)
+            return;
+        const number = limit ?? config.defaultMaxDisplayCount;
+        if (typeof number !== "number" || isNaN(number) || number < 0) {
+            return "请输入大于等于 0 的数字作为排行榜显示人数。";
+        }
+        const whites = parseList(options?.whites);
+        const blacks = [
+            ...parseList(options?.blacks),
+            ...config.hiddenChannelIdsInLeaderboard,
+        ];
+        const period = getPeriodFromOptions(options, "today");
+        const { field, name: periodName } = periodMapping[period];
+        let records;
+        let rankTitle;
+        const rankTimeTitle = getCurrentBeijingTime();
+        if (options?.specificUser) {
+            const at = koishi_1.h.select(options.specificUser, "at");
+            const userId = at.length ? at[0].attrs.id : options.specificUser;
+            const userRecords = await ctx.database.get("message_counter_records", {
+                userId,
+                channelId: session.channelId,
+            });
+            const username = userRecords.length > 0
+                ? userRecords[0].username || `用户${userId}`
+                : `用户${userId}`;
+            rankTitle = `${username}的${periodName}群发言排行榜`;
+            records = await ctx.database.get("message_counter_records", { userId });
+        }
+        else {
+            rankTitle = `全群${periodName}发言排行榜`;
+            records = await ctx.database.get("message_counter_records", {});
+        }
+        const filteredRecords = filterRecordsByWhitesAndBlacks(records, "channelId", whites, blacks);
+        if (filteredRecords.length === 0) {
+            return `在当前条件下找不到任何群聊发言记录。`;
+        }
+        const { channelPostCounts, channelInfo, totalCount } = aggregateChannelData(filteredRecords, field);
+        const sortedChannels = Object.entries(channelPostCounts).sort(([, a], [, b]) => b - a);
+        const rankingData = prepareChannelRankingData(sortedChannels, channelInfo, totalCount, number, session.channelId);
+        return renderLeaderboard({
+            rankTimeTitle,
+            rankTitle,
+            rankingData,
+        });
+    });
+    // 上传柱状条背景
+    ctx
+        .command("mc.上传柱状条背景", "上传/更新自定义的水平柱状条背景图")
+        .action(async ({ session }) => {
+        if (!session || !session.userId) {
+            return "无法获取用户信息，请稍后再试。";
+        }
+        if (!session.content) {
+            return "请在发送指令的同时附带一张图片。新图片将会覆盖旧的背景。";
+        }
+        const imageElements = koishi_1.h.select(session.content, "img");
+        if (imageElements.length === 0) {
+            return "请在发送指令的同时附带一张图片。新图片将会覆盖旧的背景。";
+        }
+        const { userId } = session;
+        // 辅助函数：清理用户旧的背景图
+        const cleanupOldBackground = async () => {
+            try {
+                const allFiles = await fs.readdir(barBgImgsPath);
+                // 查找所有以 "用户ID." 开头的文件，以匹配不同后缀名
+                const userFiles = allFiles.filter((file) => file.startsWith(`${userId}.`));
+                if (userFiles.length > 0) {
+                    await Promise.all(userFiles.map((file) => fs.unlink(path_1.default.join(barBgImgsPath, file))));
+                }
+            }
+            catch (error) {
+                // 如果目录不存在，则无需处理，这是正常情况
+                if (error.code !== "ENOENT") {
+                    logger.warn(`清理用户 ${userId} 的旧背景图时出错:`, error);
+                }
+            }
+        };
+        try {
+            const imageUrl = imageElements[0].attrs.src;
+            if (!imageUrl) {
+                throw new Error("未能从消息中提取图片 URL。");
+            }
+            const buffer = Buffer.from(await ctx.http.get(imageUrl, { responseType: "arraybuffer" }));
+            // 检查文件大小
+            const imageSizeInMB = buffer.byteLength / 1024 / 1024;
+            if (config.maxBarBgSize > 0 && imageSizeInMB > config.maxBarBgSize) {
+                throw new Error(`图片文件过大（${imageSizeInMB.toFixed(2)}MB），请上传小于 ${config.maxBarBgSize}MB 的图片。`);
+            }
+            // 检查图片尺寸
+            if (ctx.canvas) {
+                try {
+                    const image = await ctx.canvas.loadImage(buffer);
+                    if ((config.maxBarBgWidth > 0 &&
+                        image.naturalWidth > config.maxBarBgWidth) ||
+                        (config.maxBarBgHeight > 0 &&
+                            image.naturalHeight > config.maxBarBgHeight)) {
+                        throw new Error(`图片尺寸（${image.naturalWidth}x${image.naturalHeight}）超出限制（最大 ${config.maxBarBgWidth}x${config.maxBarBgHeight}）。\n建议尺寸为 850x50 像素。`);
+                    }
+                }
+                catch (error) {
+                    logger.error("解析图片尺寸失败:", error);
+                    throw new Error("无法解析图片尺寸，请尝试使用其他标准图片格式（如 PNG, JPEG）。");
+                }
+            }
+            else {
+                logger.warn("Canvas 服务未启用，跳过背景图尺寸检查。");
+            }
+            // 所有检查通过，先清理旧图，再保存新图
+            await cleanupOldBackground();
+            // 统一保存为 png 格式，文件名为 用户ID.png
+            const newFileName = `${userId}.png`;
+            const newFilePath = path_1.default.join(barBgImgsPath, newFileName);
+            await fs.writeFile(newFilePath, buffer);
+            await reloadBarBgImgCache();
+            return "您的自定义柱状条背景已成功更新！";
+        }
+        catch (error) {
+            logger.error(`为用户 ${userId} 上传背景图失败:`, error);
+            // 上传失败，清理旧的背景图
+            await cleanupOldBackground();
+            await reloadBarBgImgCache(); // 清理后同样需要重载缓存
+            const userMessage = error instanceof Error
+                ? error.message
+                : "图片保存时发生未知错误，请联系管理员。";
+            return `图片上传失败: ${userMessage}\n您之前的自定义背景（如有）已被移除。`;
+        }
+    });
+    // 重载资源
+    ctx
+        .command("mc.重载资源", "重载图标、背景和字体资源", {
+        authority: 2,
+    })
+        .action(async ({ session }) => {
+        if (!session)
+            return;
+        await session.send("正在重新加载用户图标、背景图片和字体文件缓存...");
+        await reloadIconCache();
+        await reloadBarBgImgCache();
+        await reloadFontCache(); // 调用字体缓存重载
+        return `资源重载完毕！\n- 已加载 ${iconCache.length} 个用户图标。\n- 已加载 ${barBgImgCache.length} 个柱状条背景图片。\n- 已加载 ${fontFilesCache.length} 个字体文件。`;
+    });
+    // 清理缓存
+    ctx
+        .command("mc.清理缓存", "清理过期的头像缓存文件", {
+        authority: 3,
+    })
+        .option("days", "-d <days:number> 清理超过指定天数未使用的缓存文件 (默认: 30)")
+        .action(async ({ session, options }) => {
+        if (!session)
+            return;
+        const days = options.days ?? 30;
+        if (typeof days !== "number" || days < 0) {
+            return "请输入一个有效的天数（大于等于0）。";
+        }
+        await session.send(`正在开始清理 ${days} 天前的头像缓存，请稍候...`);
+        const cacheDir = avatarsPath; // 使用已定义的头像缓存路径
+        let deletedCount = 0;
+        let totalFreedSize = 0;
+        const now = Date.now();
+        const expirationTime = now - days * 24 * 60 * 60 * 1000;
+        try {
+            const files = await fs.readdir(cacheDir);
+            for (const file of files) {
+                if (!file.endsWith(".json"))
+                    continue; // 只处理 .json 缓存文件
+                const filePath = path_1.default.join(cacheDir, file);
+                try {
+                    const stats = await fs.stat(filePath);
+                    const content = await fs.readFile(filePath, "utf-8");
+                    const entry = JSON.parse(content);
+                    // 检查时间戳是否早于我们设定的过期时间点
+                    if (entry.timestamp < expirationTime) {
+                        await fs.unlink(filePath);
+                        deletedCount++;
+                        totalFreedSize += stats.size;
+                    }
+                }
+                catch (error) {
+                    logger.warn(`处理缓存文件 ${file} 时出错，已跳过:`, error);
+                }
+            }
+            const freedSizeFormatted = formatBytes(totalFreedSize);
+            return `缓存清理完成！\n- 共删除 ${deletedCount} 个过期缓存文件。\n- 释放磁盘空间约 ${freedSizeFormatted}。`;
+        }
+        catch (error) {
+            if (error.code === "ENOENT") {
+                return "头像缓存目录不存在，无需清理。";
+            }
+            logger.error("清理头像缓存时发生未知错误:", error);
+            return "清理过程中发生错误，请查看控制台日志。";
+        }
+    });
+    // --- 辅助函数 ---
+    // hs*
+    /**
+     * 检查字体文件，如果存在不规范的 vhea 版本，则创建一个修复后的副本，并返回可用字体的路径。
+     * @param filePath 原始字体的绝对路径
+     * @returns 一个保证可用的字体文件的绝对路径（可能是原始路径或修复后的副本路径）
+     */
+    async function patchAndGetUsableFontPath(filePath) {
+        let buffer;
+        try {
+            buffer = await fs.readFile(filePath);
+        }
+        catch (readError) {
+            logger.warn(`读取字体文件 "${path_1.default.basename(filePath)}" 失败，已跳过。错误: ${readError.message}`);
+            return filePath; // 返回原始路径，让后续流程处理错误
+        }
+        // --- 核心检查逻辑 (与之前相同) ---
+        if (buffer.length < 12)
+            return filePath;
+        const numTables = buffer.readUInt16BE(4);
+        for (let i = 0; i < numTables; i++) {
+            const recordOffset = 12 + i * 16;
+            if (recordOffset + 16 > buffer.length)
+                break;
+            if (buffer.toString("ascii", recordOffset, recordOffset + 4) === "vhea") {
+                const tableOffset = buffer.readUInt32BE(recordOffset + 8);
+                if (tableOffset + 4 > buffer.length)
+                    break;
+                const version = buffer.readUInt32BE(tableOffset);
+                const INCORRECT_VERSION = 0x00010001; // 65537
+                if (version === INCORRECT_VERSION) {
+                    // --- 新的修复逻辑：创建副本 ---
+                    const parsedPath = path_1.default.parse(filePath);
+                    const patchedFilename = `${parsedPath.name}-patched${parsedPath.ext}`;
+                    const patchedFilePath = path_1.default.join(parsedPath.dir, patchedFilename);
+                    try {
+                        // 检查修复后的文件是否已存在。如果存在，就直接使用它，避免重复写入。
+                        await fs.access(patchedFilePath);
+                        return patchedFilePath;
+                    }
+                    catch (e) {
+                        // 修复后的文件不存在，现在创建它。
+                        logger.info(`检测到字体 "${path_1.default.basename(filePath)}" 不规范，正在创建修复版本 "${patchedFilename}"...`);
+                        const CORRECT_VERSION = 0x00010000; // 65536
+                        buffer.writeUInt32BE(CORRECT_VERSION, tableOffset);
+                        try {
+                            await fs.writeFile(patchedFilePath, buffer);
+                            logger.success(`已成功创建修复后的字体文件 "${patchedFilename}"。`);
+                            return patchedFilePath;
+                        }
+                        catch (writeError) {
+                            logger.warn(`创建修复字体副本失败: ${writeError.message}`);
+                            return filePath; // 创建失败，回退到使用原始文件
+                        }
+                    }
+                }
+                break; // 找到 vhea 表后即可退出
+            }
+        }
+        // 如果字体本身没问题，返回原始路径
+        return filePath;
+    }
+    /**
+     * 将字节数格式化为易于阅读的字符串 (B, KB, MB, GB...)
+     * @param bytes - 要格式化的字节数
+     * @param decimals - 保留的小数位数
+     * @returns 格式化后的字符串
+     */
+    function formatBytes(bytes, decimals = 2) {
+        if (bytes === 0)
+            return "0 Bytes";
+        const k = 1024;
+        const dm = decimals < 0 ? 0 : decimals;
+        const sizes = ["Bytes", "KB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB"];
+        const i = Math.floor(Math.log(bytes) / Math.log(k));
+        return parseFloat((bytes / Math.pow(k, i)).toFixed(dm)) + " " + sizes[i];
+    }
+    /**
+     * 为自动推送功能生成并发送排行榜。
+     * @param period - 排行榜的周期 ('today' 或 'yesterday')。
+     */
+    async function generateAndPushLeaderboard(period) {
+        const pushPeriodConfig = {
+            today: { field: "todayPostCount", name: "今日" },
+            yesterday: { field: "yesterdayPostCount", name: "昨日" },
+            week: { field: "thisWeekPostCount", name: "上周" },
+            month: { field: "thisMonthPostCount", name: "上月" },
+            year: { field: "thisYearPostCount", name: "去年" },
+        };
+        const { field, name: periodName } = pushPeriodConfig[period];
+        logger.info(`[自动推送] 开始执行 ${periodName} 发言排行榜推送任务。`);
+        const scopeName = "本群"; // 自动推送总是基于单个群聊的视角
+        const rankTimeTitle = getCurrentBeijingTime();
+        // 1. 优先获取所有机器人能触及的群聊列表，并建立一个 ID -> 带平台前缀ID 的映射
+        // guildChannelIdMap 仅包含真实的群聊（来自 bot.getGuildList），用于“推送到所有群”
+        // lookupChannelIdMap 在 guild 基础上叠加数据库记录，仅用于解析配置中指定的频道 ID
+        const guildChannelIdMap = new Map();
+        const lookupChannelIdMap = new Map();
+        // 判断是否为私聊频道（Koishi 约定的私聊 channelId 形如 "private:..."）
+        const isDirectChannelId = (id) => {
+            const sepIdx = id.indexOf(":");
+            const unprefixed = sepIdx !== -1 ? id.substring(sepIdx + 1) : id;
+            return (id.startsWith("private:") ||
+                unprefixed.startsWith("private:") ||
+                unprefixed.startsWith("private_"));
+        };
+        // --- 增强获取逻辑，防止 Adapter 报错导致任务中断 ---
+        try {
+            const channelListPromises = ctx.bots.map(async (bot) => {
+                if (!bot.online || !bot.getGuildList)
+                    return [];
+                try {
+                    let next;
+                    do {
+                        const result = await bot.getGuildList(next);
+                        if (!result || !result.data) {
+                            break;
+                        }
+                        // 确保 result.data 是数组
+                        if (Array.isArray(result.data)) {
+                            result.data.forEach((channel) => {
+                                // 跳过私聊目标，避免误将私聊用户当作群聊推送
+                                if (isDirectChannelId(channel.id))
+                                    return;
+                                // 避免因多个机器人同在一个群而覆盖
+                                if (!guildChannelIdMap.has(channel.id)) {
+                                    const prefixed = `${bot.platform}:${channel.id}`;
+                                    guildChannelIdMap.set(channel.id, prefixed);
+                                    lookupChannelIdMap.set(channel.id, prefixed);
+                                }
+                            });
+                        }
+                        next = result.next;
+                    } while (next);
+                }
+                catch (error) {
+                    // 捕获单个 Bot 获取列表时的错误（如 OneBot 的 retcode 1400），避免炸毁整个任务
+                    logger.warn(`[自动推送] 机器人 ${bot.platform} 获取群聊列表失败，将尝试使用数据库记录回退: ${error.message}`);
+                }
+            });
+            await Promise.all(channelListPromises);
+        }
+        catch (error) {
+            logger.error("[自动推送] 获取群聊列表的主流程发生错误:", error);
+        }
+        // --- 数据库回退机制 ---
+        // 仅用于解析配置中显式指定的 pushChannelIds，不会污染“推送到所有群”的目标列表
+        try {
+            const allRecords = await ctx.database.get("message_counter_records", {}, [
+                "channelId",
+            ]);
+            const dbChannelIds = new Set(allRecords.map((r) => r.channelId));
+            const activeBot = ctx.bots.find((b) => b.status === 1);
+            for (const dbCid of dbChannelIds) {
+                if (isDirectChannelId(dbCid))
+                    continue;
+                if (!lookupChannelIdMap.has(dbCid) && activeBot) {
+                    lookupChannelIdMap.set(dbCid, `${activeBot.platform}:${dbCid}`);
+                }
+            }
+        }
+        catch (dbError) {
+            logger.warn("[自动推送] 读取数据库记录进行回退时出错:", dbError);
+        }
+        // 2. 确定需要推送的频道列表（使用 Set 自动去重）
+        const targetChannels = new Set();
+        // 2.1 解析配置中的 pushChannelIds，利用映射表转换为带前缀的 ID
+        for (const channelId of config.pushChannelIds || []) {
+            if (channelId.includes(":")) {
+                // 本身就是带前缀的 ID
+                targetChannels.add(channelId);
+            }
+            else if (lookupChannelIdMap.has(channelId)) {
+                // 在映射表中找到了对应的带前缀 ID
+                targetChannels.add(lookupChannelIdMap.get(channelId));
+            }
+            else {
+                // 如果映射表没找到（且之前 DB 回退也没找到），尝试用第一个在线 Bot 强行构建
+                const activeBot = ctx.bots.find((b) => b.status === 1);
+                if (activeBot) {
+                    targetChannels.add(`${activeBot.platform}:${channelId}`);
+                }
+                else {
+                    logger.warn(`[自动推送] 无法处理配置的频道 ID: ${channelId}，未找到在线 Bot。`);
+                }
+            }
+        }
+        // 2.2 如果开启了“向所有群聊推送”，仅添加来自 getGuildList 的真实群聊，避免私聊误推
+        if (config.shouldSendLeaderboardNotificationsToAllChannels) {
+            guildChannelIdMap.forEach((prefixedId) => targetChannels.add(prefixedId));
+        }
+        // 2.3 应用排除列表
+        const excluded = new Set(config.excludedLeaderboardChannels || []);
+        if (excluded.size > 0) {
+            for (const id of Array.from(targetChannels)) {
+                // 兼容带前缀和不带前缀的排除项
+                const separatorIdx = id.indexOf(":");
+                const unprefixedId = separatorIdx !== -1 ? id.substring(separatorIdx + 1) : id;
+                if (excluded.has(id) || excluded.has(unprefixedId)) {
+                    targetChannels.delete(id);
+                }
+            }
+        }
+        if (targetChannels.size === 0) {
+            logger.info("[自动推送] 没有配置任何需要推送的频道，任务结束。");
+            return;
+        }
+        logger.info(`[自动推送] 将向 ${targetChannels.size} 个频道进行推送。`);
+        // 3. 遍历频道并推送 (修改点在于 field 和 periodName 已被通用化)
+        for (const prefixedChannelId of targetChannels) {
+            try {
+                const platformSeparatorIndex = prefixedChannelId.indexOf(":");
+                const channelId = platformSeparatorIndex === -1
+                    ? prefixedChannelId
+                    : prefixedChannelId.substring(platformSeparatorIndex + 1);
+                const records = await ctx.database.get("message_counter_records", {
+                    channelId,
+                });
+                if (records.length === 0) {
+                    logger.info(`[自动推送] 频道 ${prefixedChannelId} 无发言记录，跳过。`);
+                    continue;
+                }
+                // 聚合数据时，使用我们动态选择的 `field`
+                const userPostCounts = {};
+                const userInfo = {};
+                let totalCount = 0;
+                for (const record of records) {
+                    const count = record[field] || 0; // 读取正确的周期数据
+                    userPostCounts[record.userId] =
+                        (userPostCounts[record.userId] || 0) + count;
+                    if (!userInfo[record.userId]) {
+                        userInfo[record.userId] = {
+                            username: record.username,
+                            avatar: record.userAvatar ||
+                                `https://q1.qlogo.cn/g?b=qq&nk=${record.userId}&s=640`,
+                        };
+                    }
+                    totalCount += count;
+                }
+                const sortedUsers = Object.entries(userPostCounts)
+                    .filter(([, count]) => count > 0)
+                    .sort(([, a], [, b]) => b - a);
+                if (sortedUsers.length === 0) {
+                    logger.info(`[自动推送] 频道 ${prefixedChannelId} 在 ${periodName} 榜单上无有效数据，跳过。`);
+                    continue;
+                }
+                const rankingData = prepareRankingData(sortedUsers, userInfo, totalCount, config.defaultMaxDisplayCount);
+                if (config.isGeneratingRankingListPromptVisible) {
+                    // 忽略发送提示消息的错误（例如禁言导致），不中断后续发送图片
+                    try {
+                        await ctx.broadcast([prefixedChannelId], `正在为本群生成${periodName}发言排行榜...`);
+                    }
+                    catch (e) { }
+                    await (0, koishi_1.sleep)(config.leaderboardGenerationWaitTime * 1000);
+                }
+                // 渲染时，使用我们动态选择的 `periodName`
+                const rankTitle = `${scopeName}${periodName}发言排行榜`;
+                const renderedMessage = await renderLeaderboard({
+                    rankTimeTitle,
+                    rankTitle,
+                    rankingData,
+                });
+                await ctx.broadcast([prefixedChannelId], renderedMessage);
+                logger.success(`[自动推送] 已成功向频道 ${prefixedChannelId} 推送${periodName}排行榜。`);
+                const randomDelay = Math.random() * config.groupPushDelayRandomizationSeconds;
+                const delay = (config.delayBetweenGroupPushesInSeconds + randomDelay) * 1000;
+                if (delay > 0) {
+                    await (0, koishi_1.sleep)(delay);
+                }
+            }
+            catch (error) {
+                logger.error(`[自动推送] 向频道 ${prefixedChannelId} 推送时发生错误:`, error);
+            }
+        }
+        logger.info(`[自动推送] 所有推送任务执行完毕。`);
+    }
+    /**
+     * 执行“抓龙王”禁言操作
+     */
+    async function performDragonKingMuting() {
+        if (!config.enableMostActiveUserMuting ||
+            !config.muteChannelIds ||
+            config.muteChannelIds.length === 0) {
+            return;
+        }
+        logger.info("[抓龙王] 开始执行禁言任务。");
+        // 等待设定的延迟时间
+        await (0, koishi_1.sleep)(config.dragonKingDetainmentTime * 1000);
+        for (const channelId of config.muteChannelIds) {
+            try {
+                const records = await ctx.database.get("message_counter_records", {
+                    channelId,
+                    yesterdayPostCount: { $gt: 0 }, // 只查找昨日有发言的
+                });
+                if (records.length === 0) {
+                    logger.info(`[抓龙王] 频道 ${channelId} 昨日无人发言，跳过。`);
+                    continue;
+                }
+                // 找出昨日发言最多的人
+                const topUser = records.sort((a, b) => b.yesterdayPostCount - a.yesterdayPostCount)[0];
+                if (!topUser)
+                    continue;
+                const durationInMs = config.detentionDuration * 24 * 60 * 60 * 1000;
+                let isMuted = false;
+                // 遍历所有在线的机器人，尝试使用标准 API 执行禁言
+                for (const bot of ctx.bots) {
+                    // 只尝试在线的机器人
+                    if (bot.status !== 1)
+                        continue;
+                    try {
+                        // 使用标准的 bot.muteGuildMember API
+                        await bot.muteGuildMember(channelId, topUser.userId, durationInMs);
+                        // 只要有一个 bot 成功，就标记成功并停止尝试
+                        isMuted = true;
+                        logger.success(`[抓龙王] Bot ${bot.selfId} 已在频道 ${channelId} 将昨日龙王 ${topUser.username} (${topUser.userId}) 禁言 ${config.detentionDuration} 天。`);
+                        break; // 禁言成功，跳出循环
+                    }
+                    catch (e) {
+                        // 这个机器人可能不在该群或权限不足，这是正常现象，静默处理并尝试下一个
+                    }
+                }
+                if (isMuted) {
+                    // 禁言成功后，再向群内发送通知
+                    await ctx.broadcast([channelId], `根据统计，昨日发言最多的是 ${(0, koishi_1.h)("at", {
+                        id: topUser.userId,
+                        name: topUser.username,
+                    })}，现执行禁言 ${config.detentionDuration} 天。`);
+                }
+                else {
+                    // 如果所有机器人都尝试失败了
+                    logger.warn(`[抓龙王] 在频道 ${channelId} 执行禁言失败。可能没有任何机器人拥有该群的管理员权限，或目标用户是管理员。`);
+                }
+            }
+            catch (error) {
+                logger.error(`[抓龙王] 在频道 ${channelId} 查找龙王时出错:`, error);
+            }
+        }
+    }
+    const scheduledTasks = [];
+    /**
+     * 初始化重置状态，防止首次启动时发生破坏性数据清除。
+     * 此函数会在插件启动时运行，为每个周期检查并创建基准重置时间记录。
+     */
+    async function initializeResetStates() {
+        logger.info("正在初始化并验证发言计数器的重置状态...");
+        const now = new Date();
+        const state = await ctx.database.get("message_counter_state", {});
+        const stateMap = new Map(state.map((s) => [s.key, s.value]));
+        const periods = [
+            "daily",
+            "weekly",
+            "monthly",
+            "yearly",
+        ];
+        for (const period of periods) {
+            const key = `last_${period}_reset`;
+            if (!stateMap.has(key)) {
+                // 如果状态不存在，说明是首次运行或数据被清除。
+                // 我们不执行重置，而是创建一个安全的基准时间点。
+                let baselineDate;
+                switch (period) {
+                    case "daily":
+                        baselineDate = new Date();
+                        baselineDate.setHours(0, 0, 0, 0);
+                        break;
+                    case "weekly":
+                        baselineDate = new Date(now);
+                        baselineDate.setDate(now.getDate() - ((now.getDay() + 6) % 7));
+                        baselineDate.setHours(0, 0, 0, 0);
+                        break;
+                    case "monthly":
+                        baselineDate = new Date(now.getFullYear(), now.getMonth(), 1);
+                        baselineDate.setHours(0, 0, 0, 0);
+                        break;
+                    case "yearly":
+                        baselineDate = new Date(now.getFullYear(), 0, 1);
+                        baselineDate.setHours(0, 0, 0, 0);
+                        break;
+                }
+                await ctx.database.upsert("message_counter_state", [
+                    { key, value: baselineDate },
+                ]);
+                logger.info(`已为 '${period}' 周期初始化重置状态，基准时间：${baselineDate.toISOString()}`);
+            }
+        }
+        logger.info("所有周期的重置状态已验证完毕。");
+    }
+    /**
+     * 检查指定周期的重置任务是否应该执行。
+     * 通过查询数据库中的最后重置时间，并与当前周期的起始时间对比，来防止重复执行。
+     * @param period 要检查的周期 ('daily', 'weekly', 'monthly', 'yearly')。
+     * @returns 如果需要重置，则返回 true；否则返回 false。
+     */
+    async function isResetDue(period) {
+        const now = new Date();
+        const state = await ctx.database.get("message_counter_state", {
+            key: `last_${period}_reset`,
+        });
+        // 如果数据库中没有记录，则认为它从未重置过，使用一个很早的时间点。
+        const lastReset = state.length ? new Date(state[0].value) : new Date(0);
+        let periodStart;
+        switch (period) {
+            case "daily":
+                periodStart = new Date();
+                periodStart.setHours(0, 0, 0, 0);
+                break;
+            case "weekly":
+                // 将日期设置为本周的周一。 (day + 6) % 7 是从周一算起的天数。
+                periodStart = new Date(now);
+                periodStart.setDate(now.getDate() - ((now.getDay() + 6) % 7));
+                periodStart.setHours(0, 0, 0, 0);
+                break;
+            case "monthly":
+                periodStart = new Date(now.getFullYear(), now.getMonth(), 1);
+                periodStart.setHours(0, 0, 0, 0);
+                break;
+            case "yearly":
+                periodStart = new Date(now.getFullYear(), 0, 1);
+                periodStart.setHours(0, 0, 0, 0);
+                break;
+        }
+        // 核心判断：如果上次重置时间早于当前周期的起始时间，那么就需要执行重置。
+        return lastReset < periodStart;
+    }
+    /**
+     * 检查并执行错过的重置任务
+     * 现在将使用 isResetDue() 来判断是否需要补上任务。
+     */
+    async function checkForMissedResets() {
+        logger.info("正在检查错过的计数器重置任务...");
+        // 定义任务，以便循环处理
+        const jobDefinitions = [
+            {
+                period: "daily",
+                field: "todayPostCount",
+                message: "已补上错过的每日发言榜重置！",
+            },
+            {
+                period: "weekly",
+                field: "thisWeekPostCount",
+                message: "已补上错过的每周发言榜重置！",
+            },
+            {
+                period: "monthly",
+                field: "thisMonthPostCount",
+                message: "已补上错过的每月发言榜重置！",
+            },
+            {
+                period: "yearly",
+                field: "thisYearPostCount",
+                message: "已补上错过的每年发言榜重置！",
+            },
+        ];
+        for (const job of jobDefinitions) {
+            if (await isResetDue(job.period)) {
+                logger.info(`检测到错过的 ${job.period} 重置任务，正在执行...`);
+                await resetCounter(job.field, job.message, job.period);
+            }
+        }
+        logger.info("错过的计数器重置任务检查完毕。");
+    }
+    /**
+     * 重置计数器并更新状态
+     * @param field 要重置的数据库字段
+     * @param message 重置后发送的消息
+     * @param period 周期标识符
+     */
+    async function resetCounter(field, message, period) {
+        // 当重置“今日”发言时，首先把“今日”的数据备份到“昨日”
+        if (field === "todayPostCount") {
+            logger.info("正在更新昨日发言数...");
+            await ctx.database.set("message_counter_records", {}, (row) => ({
+                yesterdayPostCount: row.todayPostCount,
+            }));
+            logger.success("更新昨日发言数完成。");
+        }
+        // 然后将相应的字段置零
+        await ctx.database.set("message_counter_records", {}, { [field]: 0 });
+        logger.success(message);
+        // 更新状态表，记录本次重置时间
+        await ctx.database.upsert("message_counter_state", [
+            {
+                key: `last_${period}_reset`,
+                value: new Date(),
+            },
+        ]);
+        logger.success(`已更新 ${period} 周期的最后重置时间。`);
+    }
+    // 将数字格式化为保留两位小数的百分比字符串，例如 "12.34%"
+    function formatPercentageForDisplay(count, total) {
+        if (total === 0) {
+            return "(0%)";
+        }
+        const percentage = (count / total) * 100;
+        // 使用 toFixed(2) 保证最多两位小数，然后用 parseFloat 去掉末尾多余的 .0 和 0
+        const formattedNumber = parseFloat(percentage.toFixed(2));
+        return `(${formattedNumber}%)`;
+    }
+    /**
+     * getAvatarAsBase64 函数
+     * 实现了成功的长 TTL 缓存和失败的短 TTL 缓存策略。
+     * @param url 头像的URL
+     * @returns 处理后的头像 base64 字符串
+     */
+    async function getAvatarAsBase64(url) {
+        if (!url) {
+            return fallbackBase64[0];
+        }
+        const now = Date.now();
+        // 从配置中获取成功和失败的缓存有效期（转换为毫秒）
+        const successTtl = config.avatarCacheTTL * 1000;
+        const failureTtl = config.avatarFailureCacheTTL * 1000;
+        // 辅助函数，用于检查缓存条目是否过期
+        const isEntryExpired = (entry) => {
+            // 判断缓存的头像是真实头像还是备用头像
+            const isFallback = entry.base64 === fallbackBase64[0];
+            // 根据情况选择对应的 TTL
+            const ttl = isFallback ? failureTtl : successTtl;
+            // 如果 TTL 设置为 0 且不是失败缓存，则永不过期
+            if (ttl === 0 && !isFallback)
+                return false;
+            // 检查当前时间是否已超过缓存的创建时间+有效期
+            return now - entry.timestamp >= ttl;
+        };
+        // 1. 检查内存缓存 (Hot Cache)，用于最快的响应
+        if (avatarCache.has(url)) {
+            const entry = avatarCache.get(url);
+            if (!isEntryExpired(entry)) {
+                // 内存缓存命中且未过期，直接返回
+                return entry.base64;
+            }
+        }
+        // 2. 检查磁盘缓存 (Persistent Cache)，用于持久化
+        // 使用 URL 的 MD5 哈希作为文件名，避免特殊字符和路径过长问题
+        const hash = crypto.createHash("md5").update(url).digest("hex");
+        const cacheFilePath = path_1.default.join(avatarsPath, `${hash}.json`);
+        try {
+            const cachedFile = await fs.readFile(cacheFilePath, "utf-8");
+            const entry = JSON.parse(cachedFile);
+            if (!isEntryExpired(entry)) {
+                // 磁盘缓存命中且未过期，将其加载到内存并返回
+                avatarCache.set(url, entry); // 更新内存缓存
+                return entry.base64;
+            }
+        }
+        catch (error) {
+            // 捕获错误（如文件不存在、JSON解析失败），意味着磁盘缓存无效，继续执行网络请求
+        }
+        // 3. 从网络获取，并根据结果应用不同的缓存策略
+        let finalBase64 = fallbackBase64[0];
+        try {
+            if (!ctx.canvas) {
+                throw new Error("Canvas service is not available.");
+            }
+            // 设置5秒超时，防止请求卡死
+            const buffer = await ctx.http.get(url, {
+                responseType: "arraybuffer",
+                timeout: 5000,
+            });
+            // 使用 canvas 将图片统一处理为 50x50 的 PNG
+            const image = await ctx.canvas.loadImage(buffer);
+            const canvas = await ctx.canvas.createCanvas(50, 50);
+            const context = canvas.getContext("2d");
+            context.drawImage(image, 0, 0, 50, 50);
+            finalBase64 = (await canvas.toBuffer("image/png")).toString("base64");
+        }
+        catch (error) {
+            logger.warn(`获取或处理头像失败 (URL: ${url})，将使用默认头像并缓存失败状态:`, error.message || error);
+            // 如果获取或处理失败，finalBase64 保持为 fallbackBase64
+        }
+        // 4. 将获取结果（无论成功或失败）写入缓存
+        const newEntry = {
+            base64: finalBase64,
+            timestamp: now,
+        };
+        try {
+            // 同时写入磁盘和内存，确保数据同步
+            await fs.writeFile(cacheFilePath, JSON.stringify(newEntry));
+            avatarCache.set(url, newEntry);
+        }
+        catch (cacheError) {
+            logger.error(`无法写入头像缓存文件 (Path: ${cacheFilePath}):`, cacheError);
+        }
+        return newEntry.base64;
+    }
+    async function reloadIconCache() {
+        iconCache = await loadAssetsFromFolder(iconsPath);
+        logger.info(`已加载 ${iconCache.length} 个用户图标。`);
+    }
+    async function reloadBarBgImgCache() {
+        barBgImgCache = await loadAssetsFromFolder(barBgImgsPath);
+        logger.info(`已加载 ${barBgImgCache.length} 个柱状图背景图片。`);
+    }
+    /**
+     * 重新加载字体缓存，自动修复不规范的 TTF/OTF 文件，并包含 WOFF/WOFF2 等其他格式。
+     */
+    async function reloadFontCache() {
+        try {
+            await fs.access(fontsPath);
+            const files = await fs.readdir(fontsPath);
+            const usableFontBasenames = new Set(); // 使用 Set 自动处理重复项
+            for (const file of files) {
+                // 跳过我们自己创建的 "-patched" 文件，避免将其作为原始文件处理
+                if (file.toLowerCase().includes("-patched.")) {
+                    continue;
+                }
+                const lowerCaseFile = file.toLowerCase();
+                if (lowerCaseFile.endsWith(".ttf") || lowerCaseFile.endsWith(".otf")) {
+                    // 对 TTF/OTF 文件应用修复逻辑
+                    const filePath = path_1.default.join(fontsPath, file);
+                    const usablePath = await patchAndGetUsableFontPath(filePath);
+                    usableFontBasenames.add(path_1.default.basename(usablePath));
+                }
+                else if (lowerCaseFile.endsWith(".woff2") ||
+                    lowerCaseFile.endsWith(".woff")) {
+                    // 对于 WOFF/WOFF2 文件，直接视为可用并添加
+                    usableFontBasenames.add(file);
+                }
+                // 其他非字体文件将被忽略
+            }
+            // 将 Set 转换为数组，更新缓存
+            fontFilesCache = [...usableFontBasenames];
+            logger.info(`已加载 ${fontFilesCache.length} 个可用字体文件。`);
+        }
+        catch (error) {
+            logger.warn(`无法读取或重载字体目录 ${fontsPath}:`, error);
+            fontFilesCache = [];
+        }
+    }
+    // 自动迁移旧资源文件到新目录结构
+    async function migrateFolder(oldPath, newPath) {
+        try {
+            await fs.access(oldPath, fs_1.constants.F_OK); // 检查旧文件夹是否存在
+            logger.info(`检测到旧资源文件夹: ${oldPath}，将迁移至: ${newPath}`);
+            const files = await fs.readdir(oldPath);
+            for (const file of files) {
+                const oldFile = path_1.default.join(oldPath, file);
+                const newFile = path_1.default.join(newPath, file);
+                try {
+                    // 尝试移动，如果目标文件已存在则跳过
+                    await fs.rename(oldFile, newFile);
+                }
+                catch (renameError) {
+                    if (renameError.code !== "EEXIST") {
+                        logger.warn(`迁移文件 ${file} 失败:`, renameError);
+                    }
+                }
+            }
+            await (0, koishi_1.sleep)(100); // 短暂等待以确保文件系统同步
+            await fs.rmdir(oldPath);
+            logger.info(`旧资源文件夹 ${oldPath} 迁移成功并已删除。`);
+        }
+        catch (error) {
+            if (error.code !== "ENOENT") {
+                // ENOENT (Not Found) 是正常情况，说明无需迁移
+                logger.warn(`处理旧文件夹 ${oldPath} 时出错:`, error);
+            }
+        }
+    }
+    // 拷贝渲染所需的核心文件 (HTML 和内置字体)
+    async function copyAssetIfNotExists(sourceDir, destDir, filename) {
+        const destPath = path_1.default.join(destDir, filename);
+        try {
+            // 仅当目标文件不存在时才拷贝
+            await fs.access(destPath, fs_1.constants.F_OK);
+        }
+        catch {
+            const sourcePath = path_1.default.join(sourceDir, filename);
+            try {
+                await fs.access(sourcePath, fs_1.constants.F_OK);
+            }
+            catch {
+                logger.warn(`插件资源文件未找到，无法拷贝: ${filename}`);
+                return;
+            }
+            await fs.copyFile(sourcePath, destPath);
+            logger.info(`已拷贝资源文件 ${filename} 到 ${destDir}`);
+        }
+    }
+    /**
+     * 根据字体缓存动态生成 @font-face CSS 规则。
+     * @param fontFiles - 缓存的字体文件名列表。
+     * @returns 包含所有 @font-face 规则的 CSS 字符串。
+     */
+    function generateFontFacesCSS(fontFiles) {
+        let css = "";
+        for (const file of fontFiles) {
+            // 原始文件名（不含后缀），用于生成安全的 CSS 名称
+            const rawFontName = path_1.default.parse(file).name.replace(/-patched$/i, "");
+            const ext = path_1.default.parse(file).ext.toLowerCase();
+            let format;
+            switch (ext) {
+                case ".woff2":
+                    format = "woff2";
+                    break;
+                case ".woff":
+                    format = "woff";
+                    break;
+                case ".ttf":
+                    format = "truetype";
+                    break;
+                case ".otf":
+                    format = "opentype";
+                    break;
+                default:
+                    continue; // 跳过不支持或非字体的文件
+            }
+            const fontUrl = `fonts/${file}`;
+            css += `
+        @font-face {
+          font-family: '${rawFontName}';
+          src: url("${fontUrl}") format('${format}');
+        }
+      `;
+        }
+        return css;
+    }
+    /** 缓存加载函数 */
+    async function loadAssetsFromFolder(folderPath) {
+        const assetData = [];
+        try {
+            await fs.access(folderPath, fs_1.constants.R_OK); // 检查目录是否存在且可读
+            const files = await fs.readdir(folderPath);
+            for (const file of files) {
+                const userId = path_1.default.parse(file).name.split("-")[0].trim();
+                const filePath = path_1.default.join(folderPath, file);
+                try {
+                    const fileData = await fs.readFile(filePath);
+                    assetData.push({ userId, base64: fileData.toString("base64") });
+                }
+                catch (readError) {
+                    logger.warn(`Failed to read asset file ${filePath}:`, readError);
+                }
+            }
+        }
+        catch (err) {
+            logger.warn(`Error accessing asset folder ${folderPath}:`, err);
+        }
+        return assetData;
+    }
+    /** 聚合群组数据 */
+    function aggregateChannelData(records, field) {
+        const channelPostCounts = {};
+        const channelInfo = {};
+        let totalCount = 0;
+        for (const record of records) {
+            const count = record[field] || 0;
+            channelPostCounts[record.channelId] =
+                (channelPostCounts[record.channelId] || 0) + count;
+            if (!channelInfo[record.channelId]) {
+                channelInfo[record.channelId] = {
+                    channelName: record.channelName || `群聊${record.channelId}`,
+                };
+            }
+            totalCount += count;
+        }
+        return { channelPostCounts, channelInfo, totalCount };
+    }
+    /** 为群组排行榜准备 RankingData，并确保当前群在榜单中 */
+    function prepareChannelRankingData(sortedChannels, channelInfo, totalCount, limit, currentChannelId) {
+        const topChannels = sortedChannels.slice(0, limit);
+        const isCurrentInTop = currentChannelId &&
+            topChannels.some(([channelId]) => channelId === currentChannelId);
+        // 如果当前群聊不在榜单上，则找到它的数据并直接追加到末尾
+        if (currentChannelId && !isCurrentInTop) {
+            const currentChannelData = sortedChannels.find(([channelId]) => channelId === currentChannelId);
+            if (currentChannelData) {
+                topChannels.push(currentChannelData);
+            }
+        }
+        return topChannels.map(([channelId, count]) => ({
+            // 增加★高亮当前群聊
+            name: (channelId === currentChannelId ? "★" : "") +
+                (channelInfo[channelId]?.channelName || `群聊${channelId}`),
+            // 使用 channelId 作为 RankingData 的 userId 和头像源
+            userId: channelId,
+            avatar: `https://p.qlogo.cn/gh/${channelId === "#" ? "426230045" : channelId}/${channelId === "#" ? "426230045" : channelId}/100`, // QQ群头像URL格式
+            count,
+            percentage: calculatePercentage(count, totalCount),
+        }));
+    }
+    // --- 辅助函数：图表生成 ---
+    /**
+     * 生成图表的静态 CSS 样式。
+     * @returns 包含基本元素样式的 CSS 字符串。
+     */
+    function _getChartBaseStyles() {
+        return `
+      html {
+        min-height: 100%;
+      }
+
+      body {
+        font-family: sans-serif;
+        margin: 0;
+        padding: 20px;
+        width: 100%;
+        min-height: 100%;
+        box-sizing: border-box;
+      }
+
+    .ranking-title {
+      text-align: center;
+      margin-bottom: 20px;
+      color: #333;
+      font-style: normal;
+    }
+
+      /* 预加载字体用，不显示 */
+      .font-preload {
+        display: none;
+      }
+    `;
+    }
+    /**
+     * 准备图表的背景样式。
+     * 此函数根据配置生成应用于整个 HTML 页面的背景 CSS。
+     * 通过将样式应用于 `<html>` 标签，确保背景能完全覆盖 `fullPage` 截图的区域。
+     * @param config 插件配置对象。
+     * @returns 一个包含背景样式的 CSS 字符串。
+     */
+    async function _prepareBackgroundStyle(config) {
+        if (config.backgroundType === "api" && config.apiBackgroundConfig?.apiUrl) {
+            try {
+                const { apiUrl, apiKey, responseType } = config.apiBackgroundConfig;
+                const headers = apiKey ? { Authorization: `Bearer ${apiKey}` } : {};
+                let backgroundImage;
+                switch (responseType) {
+                    case "url": {
+                        // API 返回一个包含图片 URL 的 JSON 或纯文本
+                        const response = await ctx.http.get(apiUrl, { headers });
+                        const imageUrl = typeof response === "string" ? response : response?.url;
+                        if (!imageUrl || typeof imageUrl !== "string") {
+                            throw new Error('API response for "url" type is not a valid string.');
+                        }
+                        backgroundImage = `url('${imageUrl}')`;
+                        break;
+                    }
+                    case "base64": {
+                        // API 返回一个包含 Base64 数据的 JSON 或纯文本
+                        const response = await ctx.http.get(apiUrl, { headers });
+                        const base64Data = typeof response === "string" ? response : response?.data;
+                        if (!base64Data || typeof base64Data !== "string") {
+                            throw new Error('API response for "base64" type is not a valid string.');
+                        }
+                        // 自动检测并添加 data URI scheme
+                        const prefix = base64Data.startsWith("data:image")
+                            ? ""
+                            : "data:image/png;base64,";
+                        backgroundImage = `url('${prefix}${base64Data}')`;
+                        break;
+                    }
+                    case "binary":
+                    default: {
+                        // API 返回原始图片数据（二进制）
+                        const responseBuffer = await ctx.http.get(apiUrl, {
+                            headers,
+                            responseType: "arraybuffer",
+                        });
+                        const base64 = Buffer.from(responseBuffer).toString("base64");
+                        backgroundImage = `url('data:image/png;base64,${base64}')`;
+                        break;
+                    }
+                }
+                return `html {
+          background-image: ${backgroundImage};
+          background-size: cover;
+          background-position: center;
+          background-repeat: no-repeat;
+        }`;
+            }
+            catch (error) {
+                logger.error("获取 API 背景图失败，将使用默认背景:", error);
+            }
+        }
+        if (config.backgroundType === "css" && config.backgroundValue) {
+            return config.backgroundValue;
+        }
+        return `html {
+      background: linear-gradient(135deg, #f6f8f9 0%, #e5ebee 100%);
+    }`;
+    }
+    /**
+     * 获取在浏览器端执行的绘图脚本。
+     * @returns 一个 IIFE (立即调用函数表达式) 字符串，用于在浏览器中绘制 Canvas。
+     */
+    function _getClientScript() {
+        // 此函数返回一个字符串，该字符串是将在 Puppeteer 浏览器上下文中执行的完整脚本。
+        // 使用 IIFE (async (...) => { ... }) 格式，以便在 HTML 中清晰地传递参数。
+        return `
+      async ({ rankingData, iconData, barBgImgs, config }) => {
+        // --- 主绘制函数 ---
+        async function drawRanking() {
+          const maxCount = rankingData.reduce((max, item) => Math.max(max, item.count), 0) || 1;
+          const userNum = rankingData.length;
+          const userAvatarSize = 50;
+          const tableWidth = 200 + 7 * 100; // 固定宽度
+          const canvasHeight = 50 * userNum;
+
+          const canvas = document.getElementById('rankingCanvas');
+          let context = canvas.getContext('2d');
+
+          // 根据最大计数的文本宽度动态调整画布宽度，以防数字溢出
+          context.font = \`30px "\${config.chartNicknameFont}", HarmonyOS_Sans_Medium, "Microsoft YaHei", sans-serif\`;
+          // 找到拥有最大发言数的条目，因为它的文本通常最长
+          const maxCountData = rankingData.find(d => d.count === maxCount) || rankingData[0] || { count: 1, percentage: 0 };
+          let maxCountText = maxCount.toString();
+          if (config.isUserMessagePercentageVisible && maxCountData) {
+              const percentage = maxCountData.percentage;
+              let percentageStr = percentage < 0.01 && percentage > 0 ? '<0.01' : percentage.toFixed(percentage < 1 ? 2 : 0);
+              maxCountText += \` ( \${percentageStr}%)\`;
+          }
+          const maxCountTextWidth = context.measureText(maxCountText).width;
+
+          // 最长进度条的宽度是固定的
+          const maxBarWidth = 150 + 700; // 进度条区域总宽度
+
+          // 计算最终画布宽度：头像(50) + 进度条(850) + 文本与进度条间距(10) + 文本宽度 + 右侧留白(20)
+          // 头像左侧的空白由页面 body 的 padding 提供
+          canvas.width = 50 + maxBarWidth + 10 + maxCountTextWidth + 20;
+          canvas.height = canvasHeight;
+
+          // 重新获取上下文，因为尺寸变化会重置状态
+          context = canvas.getContext('2d');
+
+          // 按顺序绘制图层
+          await drawRankingBars(context, maxCount, userAvatarSize, tableWidth); // 传递动态的 canvas.width
+          await drawAvatars(context, userAvatarSize);
+          drawVerticalLines(context, canvas.height, tableWidth); // 竖线仍然可以按旧的固定宽度绘制，不影响主体
+        }
+
+        // --- 核心绘图逻辑 ---
+
+        async function drawRankingBars(context, maxCount, userAvatarSize, canvasWidth) { // 接收 canvasWidth
+          for (const [index, data] of rankingData.entries()) {
+            const countBarWidth = 150 + (700 * data.count) / maxCount;
+            const countBarX = 50; // 头像宽度
+            const countBarY = 50 * index;
+
+            let avgColor = await getAverageColor(data.avatarBase64);
+            const colorWithOpacity = addOpacityToColor(avgColor, 0.5);
+
+            // 绘制底色进度条
+            context.fillStyle = avgColor;
+            context.fillRect(countBarX, countBarY, countBarWidth, userAvatarSize);
+
+            // 绘制自定义背景图
+            const userBarBgImgs = findAssets(data.userId, barBgImgs, 'barBgImgBase64');
+            if (userBarBgImgs.length > 0) {
+              const randomBarBgImgBase64 = userBarBgImgs[Math.floor(Math.random() * userBarBgImgs.length)];
+              avgColor = await drawCustomBarBackground(context, randomBarBgImgBase64, countBarX, countBarY, countBarWidth, userAvatarSize, canvasWidth); // 传递 canvasWidth
+            }
+
+            // 绘制剩余部分灰色背景
+            const remainingBarX = countBarX + countBarWidth;
+            // 确保灰色背景能填满到画布最右侧，减去文本区域
+            context.fillStyle = colorWithOpacity;
+            context.fillRect(remainingBarX, countBarY, canvasWidth - remainingBarX, userAvatarSize);
+
+            // 绘制文本和图标
+            await drawTextAndIcons(context, data, index, avgColor, countBarX, countBarY, countBarWidth, userAvatarSize);
+          }
+        }
+
+        async function drawCustomBarBackground(context, base64, x, y, barWidth, barHeight, canvasWidth) { // 接收 canvasWidth
+            return new Promise(async (resolve) => {
+                const barBgImg = new Image();
+                barBgImg.src = "data:image/png;base64," + base64;
+                barBgImg.onload = async () => {
+                    context.save();
+                    // 绘制整行背景（如果透明度 > 0）
+                    if (config.horizontalBarBackgroundFullOpacity > 0) {
+                        context.globalAlpha = config.horizontalBarBackgroundFullOpacity;
+                        context.drawImage(barBgImg, x, y, canvasWidth - x, barHeight); // 填充到画布右侧
+                    }
+                    // 绘制进度条区域背景
+                    context.globalAlpha = config.horizontalBarBackgroundOpacity;
+                    context.drawImage(barBgImg, 0, 0, barWidth, barHeight, x, y, barWidth, barHeight);
+                    context.restore();
+                    const newAvgColor = await getAverageColor(base64);
+                    resolve(newAvgColor);
+                };
+                barBgImg.onerror = async () => {
+                    const originalColor = await getAverageColor(base64);
+                    resolve(originalColor); // 发生错误则返回原始颜色
+                }
+            });
+        }
+
+        async function drawTextAndIcons(context, data, index, avgColor, barX, barY, barWidth, barHeight) {
+            // 字体栈包含了用户选择的字体、插件内置字体和通用字体，以确保兼容性。
+            context.font = \`30px "\${config.chartNicknameFont}", HarmonyOS_Sans_Medium, "Microsoft YaHei", sans-serif\`;
+            const textY = barY + barHeight / 2 + 10.5;
+
+
+            // 绘制发言次数和百分比
+            let countText = data.count.toString();
+            if (config.isUserMessagePercentageVisible) {
+                const percentage = data.percentage;
+                let percentageStr = percentage < 0.01 && percentage > 0 ? '<0.01' : percentage.toFixed(percentage < 1 ? 2 : 0);
+                countText += \` ( \${percentageStr}%)\`;
+            }
+
+            const countTextWidth = context.measureText(countText).width;
+            const countTextX = barX + barWidth + 10;
+
+            if (countTextX + countTextWidth > context.canvas.width - 5) {
+                context.fillStyle = chooseColorAdjustmentMethod(avgColor);
+                context.textAlign = "right";
+                context.fillText(countText, barX + barWidth - 10, textY);
+            } else {
+                context.fillStyle = "rgba(0, 0, 0, 1)";
+                context.textAlign = "left";
+                context.fillText(countText, countTextX, textY);
+            }
+
+            // 绘制用户名（带截断）
+            context.fillStyle = chooseColorAdjustmentMethod(avgColor);
+            context.textAlign = "left"; // 重置对齐方式，以防被上一部分修改
+
+            let nameText = data.name;
+            const maxNameWidth = barWidth - 60;
+            if (context.measureText(nameText).width > maxNameWidth) {
+                const ellipsis = "...";
+                while (context.measureText(nameText + ellipsis).width > maxNameWidth && nameText.length > 0) {
+                    nameText = nameText.slice(0, -1);
+                }
+                nameText += ellipsis;
+            }
+            const nameTextX = barX + 10;
+            context.fillText(nameText, nameTextX, textY);
+
+            // 绘制用户自定义图标
+            const userIcons = findAssets(data.userId, iconData, 'iconBase64');
+            if (userIcons.length > 0) {
+                await drawUserIcons(context, userIcons, {
+                    nameText: data.name, // 传递原始nameText用于计算位置
+                    nameTextX: context.measureText(nameText).width + nameTextX,
+                    barX: barX,
+                    barWidth: barWidth,
+                    textY: textY
+                });
+            }
+        }
+
+        async function drawUserIcons(context, icons, positions) {
+            const { nameTextX, barX, barWidth, textY } = positions;
+
+            // 使用 Promise.all 等待所有图片加载和绘制
+            await Promise.all(icons.map((iconBase64, i) => {
+                return new Promise((resolve, reject) => {
+                    const icon = new Image();
+                    icon.src = "data:image/png;base64," + iconBase64;
+                    icon.onload = () => {
+                        const iconSize = 40;
+                        const iconY = textY - 30;
+                        let iconX = config.shouldMoveIconToBarEndLeft
+                            ? barX + barWidth - (iconSize * (i + 1))
+                            : nameTextX + (iconSize * i) + 5;
+                        context.drawImage(icon, iconX, iconY, iconSize, iconSize);
+                        resolve(); // 图片绘制成功
+                    };
+                    icon.onerror = () => {
+                        resolve(); // 即使单个图标加载失败，也继续执行，不中断整个排行榜生成
+                    };
+                });
+            }));
+        }
+
+        async function drawAvatars(context, userAvatarSize) {
+          for (const [index, data] of rankingData.entries()) {
+            const image = new Image();
+            image.src = "data:image/png;base64," + data.avatarBase64;
+            // onload不是必需的，因为图片已是base64，但为了健壮性可以保留
+            await new Promise(resolve => {
+                image.onload = () => {
+                    context.drawImage(image, 0, 50 * index, userAvatarSize, userAvatarSize);
+                    resolve();
+                };
+                image.onerror = resolve; // 即使加载失败也继续
+            });
+          }
+        }
+
+        function drawVerticalLines(context, canvasHeight, tableWidth) {
+            context.fillStyle = "rgba(0, 0, 0, 0.12)";
+            const verticalLineWidth = 3;
+            const firstLineX = 200;
+            for (let i = 0; i < 8; i++) {
+                context.fillRect(firstLineX + 100 * i, 0, verticalLineWidth, canvasHeight);
+            }
+        }
+
+
+        // --- 辅助工具函数 ---
+
+        function findAssets(userId, assetList, key) {
+          return assetList
+            .filter(data => data.userId === userId)
+            .map(data => data[key]);
+        }
+
+        function addOpacityToColor(color, opacity) {
+          const opacityHex = Math.round(opacity * 255).toString(16).padStart(2, "0");
+          return \`\${color}\${opacityHex}\`;
+        }
+
+        function chooseColorAdjustmentMethod(hexcolor) {
+            const rgb = hexToRgb(hexcolor)
+            const yiqBrightness = calculateYiqBrightness(rgb)
+            if (yiqBrightness > 0.2 && yiqBrightness < 0.8) {
+                return adjustColorHsl(hexcolor)
+            } else {
+                return adjustColorYiq(hexcolor)
+            }
+        }
+
+        function calculateYiqBrightness(rgb) {
+            return (rgb.r * 299 + rgb.g * 587 + rgb.b * 114) / 1000 / 255
+        }
+
+        function adjustColorYiq(hexcolor) {
+            const rgb = hexToRgb(hexcolor)
+            const yiqBrightness = calculateYiqBrightness(rgb)
+            return yiqBrightness >= 0.8 ? "#000000" : "#FFFFFF"
+        }
+
+        function adjustColorHsl(hexcolor) {
+            const rgb = hexToRgb(hexcolor)
+            let hsl = rgbToHsl(rgb.r, rgb.g, rgb.b)
+            hsl.l = hsl.l < 0.5 ? hsl.l + 0.3 : hsl.l - 0.3
+            hsl.s = hsl.s < 0.5 ? hsl.s + 0.3 : hsl.s - 0.3
+            const contrastRgb = hslToRgb(hsl.h, hsl.s, hsl.l)
+            return rgbToHex(contrastRgb.r, contrastRgb.g, contrastRgb.b)
+        }
+
+        function hexToRgb(hex) {
+            const sanitizedHex = String(hex).replace("#", "")
+            const bigint = parseInt(sanitizedHex, 16)
+            const r = (bigint >> 16) & 255
+            const g = (bigint >> 8) & 255
+            const b = bigint & 255
+            return {r, g, b}
+        }
+
+        function rgbToHsl(r, g, b) {
+            r /= 255, g /= 255, b /= 255
+            const max = Math.max(r, g, b), min = Math.min(r, g, b)
+            let h, s, l = (max + min) / 2
+            if (max === min) {
+                h = s = 0
+            } else {
+                const d = max - min
+                s = l > 0.5 ? d / (2 - max - min) : d / (max + min)
+                switch (max) {
+                    case r: h = (g - b) / d + (g < b ? 6 : 0); break
+                    case g: h = (b - r) / d + 2; break
+                    case b: h = (r - g) / d + 4; break
+                }
+                h /= 6
+            }
+            return {h, s, l}
+        }
+
+        function hslToRgb(h, s, l) {
+            let r, g, b
+            if (s === 0) {
+                r = g = b = l
+            } else {
+                const hue2rgb = (p, q, t) => {
+                    if (t < 0) t += 1
+                    if (t > 1) t -= 1
+                    if (t < 1 / 6) return p + (q - p) * 6 * t
+                    if (t < 1 / 2) return q
+                    if (t < 2 / 3) return p + (q - p) * (2 / 3 - t) * 6
+                    return p
+                }
+                const q = l < 0.5 ? l * (1 + s) : l + s - l * s
+                const p = 2 * l - q
+                r = hue2rgb(p, q, h + 1 / 3)
+                g = hue2rgb(p, q, h)
+                b = hue2rgb(p, q, h - 1 / 3)
+            }
+            return { r: Math.round(r * 255), g: Math.round(g * 255), b: Math.round(b * 255) }
+        }
+
+        function rgbToHex(r, g, b) {
+            const toHex = c => {
+                const hex = c.toString(16)
+                return hex.length === 1 ? "0" + hex : hex
+            }
+            return \`#\${toHex(r)}\${toHex(g)}\${toHex(b)}\`
+        }
+
+        async function getAverageColor(base64) {
+            const image = new Image();
+            image.src = "data:image/png;base64," + base64;
+            await new Promise(r => image.onload = r);
+
+            const canvas = document.createElement('canvas');
+            const ctx = canvas.getContext("2d", { willReadFrequently: true });
+            canvas.width = image.width; canvas.height = image.height;
+            ctx.drawImage(image, 0, 0);
+
+            const data = ctx.getImageData(0, 0, image.width, image.height).data;
+            let r = 0, g = 0, b = 0;
+
+            for (let i = 0; i < data.length; i += 4) {
+                r += data[i]; g += data[i+1]; b += data[i+2];
+            }
+            const count = data.length / 4;
+            r = ~~(r / count); g = ~~(g / count); b = ~~(b / count);
+
+            return \`#\${r.toString(16).padStart(2, "0")}\${g.toString(16).padStart(2, "0")}\${b.toString(16).padStart(2, "0")}\`;
+        }
+
+        // --- 启动绘制 ---
+        await drawRanking();
+      }
+    `;
+    }
+    /**
+     * 组装最终的 HTML 页面内容。
+     * @param params 包含所有渲染所需数据的对象。
+     * @returns 完整的 HTML 字符串。
+     */
+    function _getChartHtmlContent(params) {
+        const { rankTimeTitle, rankTitle, data, iconCache, barBgImgCache, backgroundStyle, fontFacesCSS, chartConfig, } = params;
+        // 准备注入到客户端脚本的数据
+        const clientData = {
+            rankingData: data,
+            iconData: iconCache.map((d) => ({
+                userId: d.userId,
+                iconBase64: d.base64,
+            })),
+            barBgImgs: barBgImgCache.map((d) => ({
+                userId: d.userId,
+                barBgImgBase64: d.base64,
+            })),
+            config: chartConfig,
+        };
+        return `
+      <!DOCTYPE html>
+      <html lang="zh-CN">
+      <head>
+          <meta charset="UTF--8">
+          <meta name="viewport" content="width=device-width, initial-scale=1.0">
+          <title>排行榜</title>
+          <style>${_getChartBaseStyles()}</style>
+          <style>${backgroundStyle}</style>
+          <style>${fontFacesCSS}</style>
+          <style>
+            .ranking-title { font-family: "${chartConfig.chartTitleFont}", "Microsoft YaHei", sans-serif; }
+          </style>
+      </head>
+      <body>
+          <h1 class="ranking-title">${rankTimeTitle}</h1>
+          <h1 class="ranking-title">${rankTitle}</h1>
+          <div class="font-preload">
+            <span style="font-family: '${chartConfig.chartNicknameFont}';">预加载</span>
+            <span style="font-family: '${chartConfig.chartTitleFont}';">预加载</span>
+          </div>
+          <canvas id="rankingCanvas"></canvas>
+          <script>
+            // 立即执行的异步函数，用于绘制图表
+            (async () => {
+              const drawFunction = ${_getClientScript()};
+              await drawFunction(${JSON.stringify(clientData)});
+            })();
+          </script>
+      </body>
+      </html>
+    `;
+    }
+    /**
+     * 生成排行榜图片。
+     * 该函数通过组合多个辅助函数来创建 HTML 页面，并使用 Puppeteer 进行截图。
+     * @param params 包含标题和数据的对象。
+     * @returns 包含图表图片的 Buffer。
+     */
+    async function generateRankingChart({ rankTimeTitle, rankTitle, data, }, { iconCache, barBgImgCache, fontFilesCache, emptyHtmlPath, }) {
+        if (!ctx.puppeteer) {
+            throw new Error("Puppeteer 服务未启用，无法生成图表。");
+        }
+        const browser = ctx.puppeteer.browser;
+        if (!browser) {
+            throw new Error("Puppeteer 浏览器实例不可用。");
+        }
+        const page = await browser.newPage();
+        try {
+            const fontFaces = generateFontFacesCSS(fontFilesCache);
+            const backgroundStyle = await _prepareBackgroundStyle(config);
+            const chartConfigForClient = {
+                shouldMoveIconToBarEndLeft: config.shouldMoveIconToBarEndLeft,
+                horizontalBarBackgroundOpacity: config.horizontalBarBackgroundOpacity,
+                horizontalBarBackgroundFullOpacity: config.horizontalBarBackgroundFullOpacity,
+                isUserMessagePercentageVisible: config.isUserMessagePercentageVisible,
+                chartTitleFont: config.chartTitleFont,
+                chartNicknameFont: config.chartNicknameFont,
+            };
+            const htmlContent = _getChartHtmlContent({
+                rankTimeTitle,
+                rankTitle,
+                data,
+                iconCache,
+                barBgImgCache,
+                backgroundStyle,
+                fontFacesCSS: fontFaces,
+                chartConfig: chartConfigForClient,
+            });
+            // 加载本地空 HTML 文件作为起点
+            const pageUrl = emptyHtmlPath.includes(":")
+                ? `file:///${emptyHtmlPath}`
+                : `file://${emptyHtmlPath}`;
+            await page.goto(pageUrl, { waitUntil: "load" });
+            // 调试：将 html 内容保存到文件中
+            // const debugHtmlPath = path.join(
+            //   ctx.baseDir,
+            //   "data",
+            //   "mc",
+            //   "debug-ranking-chart.html"
+            // );
+            // await fs.writeFile(debugHtmlPath, htmlContent, "utf-8");
+            // logger.info(`排行榜 HTML 已保存到 ${debugHtmlPath}`);
+            await page.setContent(koishi_1.h.unescape(htmlContent), {
+                waitUntil: config.waitUntil,
+            });
+            const calculatedWidth = await page.evaluate(() => {
+                const canvas = document.getElementById("rankingCanvas");
+                const bodyPadding = 40; // 对应 body 的左右 padding (20px + 20px)
+                // 如果 canvas 存在，则返回其宽度加上页面的 padding；否则返回一个默认值。
+                return canvas ? canvas.width + bodyPadding : 1080;
+            });
+            await page.setViewport({
+                // 使用客户端计算出的宽度，但确保不小于用户在配置中设定的值
+                width: Math.max(config.chartViewportWidth, Math.ceil(calculatedWidth)),
+                // 高度在这里是次要的，因为 fullPage: true 会自动调整，但设置一个合理的值可以避免潜在问题
+                height: 256,
+                deviceScaleFactor: config.deviceScaleFactor,
+            });
+            const imageBuffer = await page.screenshot({
+                type: config.imageType,
+                fullPage: true,
+            });
+            return imageBuffer;
+        }
+        catch (error) {
+            logger.error("生成排行榜图表时发生错误:", error);
+            throw error; // 将错误向上抛出，以便调用者可以处理
+        }
+        finally {
+            await page.close(); // 确保页面总是被关闭
+        }
+    }
+    function getUserRankAndRecord(getDragons, userId, postCountType) {
+        if (getDragons.length === 0) {
+            return;
+        }
+        const aggregatedUserRecords = getDragons.reduce((acc, user) => {
+            if (!acc[user.userId]) {
+                acc[user.userId] = {
+                    userId: user.userId,
+                    postCountAll: 0,
+                    username: user.username,
+                };
+            }
+            let postCount = 0;
+            switch (postCountType) {
+                case "todayPostCount":
+                    postCount = user.todayPostCount;
+                    break;
+                case "thisWeekPostCount":
+                    postCount = user.thisWeekPostCount;
+                    break;
+                case "thisMonthPostCount":
+                    postCount = user.thisMonthPostCount;
+                    break;
+                case "thisYearPostCount":
+                    postCount = user.thisYearPostCount;
+                    break;
+                case "totalPostCount":
+                    postCount = user.totalPostCount;
+                    break;
+                case "yesterdayPostCount":
+                    postCount = user.yesterdayPostCount;
+                    break;
+                default:
+                    postCount = user.todayPostCount;
+                    break;
+            }
+            acc[user.userId].postCountAll += postCount;
+            return acc;
+        }, {});
+        const sortedUserRecords = Object.values(aggregatedUserRecords).sort((a, b) => b.postCountAll - a.postCountAll);
+        const userIndex = sortedUserRecords.findIndex((user) => user.userId === userId);
+        const userRecord = sortedUserRecords[userIndex];
+        const acrossRank = userIndex + 1;
+        return { acrossRank, userRecord };
+    }
+    function getSortedDragons(records) {
+        const dragonsMap = {};
+        for (const dragon of records) {
+            const { userId, totalPostCount } = dragon;
+            const key = `${userId}`;
+            dragonsMap[key] = (dragonsMap[key] || 0) + totalPostCount;
+        }
+        return Object.entries(dragonsMap).sort((a, b) => b[1] - a[1]);
+    }
+    async function replaceAtTags(session, content) {
+        const atRegex = /<at id="(\d+)"(?: name="([^"]*)")?\/>/g;
+        let match;
+        while ((match = atRegex.exec(content)) !== null) {
+            const userId = match[1];
+            const name = match[2];
+            if (!name) {
+                let userName = "未知用户";
+                try {
+                    if (typeof session.bot?.getChannelMember === "function" &&
+                        session.channelId) {
+                        const channelMember = await session.bot.getChannelMember(session.channelId, userId);
+                        if (channelMember &&
+                            channelMember.user &&
+                            channelMember.user.name) {
+                            userName = channelMember.user.name;
+                        }
+                    }
+                }
+                catch (error) {
+                    logger.error(error);
+                }
+                const newAtTag = `<at id="${userId}" name="${userName}"/>`;
+                content = content.replace(match[0], newAtTag);
+            }
+        }
+        return content;
+    }
+    async function getChannelName(bot, channelId) {
+        try {
+            const channel = await bot.getChannel(channelId);
+            return channel?.name;
+        }
+        catch (error) {
+            logger.warn(`Failed to get channelId name for ${channelId}:`, error);
+            return undefined;
+        }
+    }
+    function parseList(str) {
+        if (!str)
+            return [];
+        return str.split(/[\s,，、]+/).filter(Boolean);
+    }
+    function getPeriodFromOptions(options, fallback) {
+        if (options?.yesterday || options?.ydag)
+            return "yesterday";
+        if (options?.day || options?.dag)
+            return "today";
+        if (options?.week || options?.wag)
+            return "week";
+        if (options?.month || options?.mag)
+            return "month";
+        if (options?.year || options?.yag)
+            return "year";
+        if (options?.total || options?.across || options?.dragon)
+            return "total";
+        return fallback;
+    }
+    function isAcrossChannel(options) {
+        return ["ydag", "dag", "wag", "mag", "yag", "across", "dragon"].some((opt) => options?.[opt]);
+    }
+    function filterRecordsByWhitesAndBlacks(records, key, whites, blacks) {
+        let result = records;
+        if (whites.length > 0) {
+            result = result.filter((r) => whites.includes(r[key]));
+        }
+        if (blacks.length > 0) {
+            result = result.filter((r) => !blacks.includes(r[key]));
+        }
+        return result;
+    }
+    function prepareRankingData(sortedUsers, userInfo, totalCount, limit, requesterId) {
+        const topUsers = sortedUsers.slice(0, limit);
+        const isRequesterInTop = requesterId && topUsers.some(([userId]) => userId === requesterId);
+        // 如果指令发送者不在榜单上，则找到他的数据并直接追加到末尾
+        if (requesterId && !isRequesterInTop) {
+            const requesterData = sortedUsers.find(([userId]) => userId === requesterId);
+            if (requesterData) {
+                topUsers.push(requesterData);
+            }
+        }
+        return topUsers.map(([userId, count]) => ({
+            // 增加★高亮指令发送者
+            name: (userId === requesterId ? "★" : "") + userInfo[userId].username,
+            userId: userId,
+            avatar: userInfo[userId].avatar,
+            count,
+            percentage: calculatePercentage(count, totalCount),
+        }));
+    }
+    function calculatePercentage(number, total) {
+        if (total === 0)
+            return 0;
+        return (number / total) * 100;
+    }
+    function getCurrentBeijingTime() {
+        return new Date().toLocaleString("zh-CN", { timeZone: "Asia/Shanghai" });
+    }
+    async function renderLeaderboard({ rankTimeTitle, rankTitle, rankingData, }) {
+        // 渲染为水平柱状图
+        if (config.isLeaderboardToHorizontalBarChartConversionEnabled) {
+            if (!ctx.puppeteer) {
+                logger.warn("Puppeteer service is not enabled. Falling back to text.");
+            }
+            else {
+                try {
+                    const chartReadyData = rankingData.map((item) => {
+                        const newItem = { ...item };
+                        if (!config.showStarInChart && newItem.name.startsWith("★")) {
+                            newItem.name = newItem.name.substring(1);
+                        }
+                        return newItem;
+                    });
+                    // 调用新的、带持久化缓存的函数来获取头像
+                    // 旧的逻辑是直接在这里操作内存缓存，现在封装到 getAvatarAsBase64 中
+                    await Promise.all(chartReadyData.map(async (item) => {
+                        item.avatarBase64 = await getAvatarAsBase64(item.avatar);
+                    }));
+                    const imageBuffer = await generateRankingChart({ rankTimeTitle, rankTitle, data: chartReadyData }, { iconCache, barBgImgCache, fontFilesCache, emptyHtmlPath });
+                    return koishi_1.h.image(imageBuffer, `image/${config.imageType}`);
+                }
+                catch (error) {
+                    logger.error("Failed to generate leaderboard chart:", error);
+                }
+            }
+        }
+        // 渲染为 Markdown 图片
+        if (config.isTextToImageConversionEnabled) {
+            if (!ctx.markdownToImage) {
+                logger.warn("markdownToImage service is not enabled. Falling back to text.");
+            }
+            else {
+                const markdown = formatLeaderboardAsMarkdown(rankTimeTitle, rankTitle, rankingData, config.isUserMessagePercentageVisible);
+                const imageBuffer = await ctx.markdownToImage.convertToImage(markdown);
+                return koishi_1.h.image(imageBuffer, `image/${config.imageType}`);
+            }
+        }
+        // 默认渲染为纯文本
+        return formatLeaderboardAsText(rankTimeTitle, rankTitle, rankingData, config.isUserMessagePercentageVisible);
+    }
+    function formatLeaderboardAsMarkdown(title, subtitle, data, showPercentage) {
+        let result = `# ${title}\n## ${subtitle}\n\n`;
+        data.forEach((item, index) => {
+            const percentageStr = showPercentage
+                ? ` (${Math.round(item.percentage)}%)`
+                : "";
+            result += `${index + 1}. **${item.name}**: ${item.count} 次${percentageStr}\n`;
+        });
+        return result;
+    }
+    function formatLeaderboardAsText(title, subtitle, data, showPercentage) {
+        let result = `${title}\n${subtitle}\n\n`;
+        data.forEach((item, index) => {
+            const percentageStr = showPercentage
+                ? ` (${Math.round(item.percentage)}%)`
+                : "";
+            result += `${index + 1}. ${item.name}：${item.count} 次${percentageStr}\n`;
+        });
+        return result.trim();
+    }
+}