koishi-plugin-kkk 1.0.0

package/lib/karin/module/utils/runtime-report.js

@@ -0,0 +1,140 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.collectRuntimeReport = exports.getLocalChangelog = void 0;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_karin_1 = require("../../../compat/node-karin.js");
+const root_1 = require("../../root");
+const build_metadata_1 = require("./build-metadata");
+const Config_1 = require("./Config");
+const helpers_1 = require("./Network/helpers");
+/**
+ * 将秒数格式化为适合诊断海报展示的紧凑时长。
+ *
+ * @param seconds 原始秒数
+ * @returns 例如 `2天 6小时 18分钟`
+ */
+const formatDuration = (seconds) => {
+    if (!Number.isFinite(seconds) || seconds < 0)
+        return '未知';
+    const totalMinutes = Math.floor(seconds / 60);
+    const days = Math.floor(totalMinutes / 1440);
+    const hours = Math.floor((totalMinutes % 1440) / 60);
+    const minutes = totalMinutes % 60;
+    if (days > 0)
+        return `${days}天 ${hours}小时 ${minutes}分钟`;
+    if (hours > 0)
+        return `${hours}小时 ${minutes}分钟`;
+    if (minutes > 0)
+        return `${minutes}分钟`;
+    return `${Math.floor(seconds)}秒`;
+};
+/**
+ * 从随包发布的 CHANGELOG 中提取指定数量的本地版本记录。
+ * 读取失败时返回空字符串，让调用方决定降级展示或抛出错误。
+ *
+ * @param length 需要提取的版本数量
+ */
+const getLocalChangelog = (length) => {
+    try {
+        const changelogPath = node_path_1.default.join(root_1.Root.pluginPath, 'CHANGELOG.md');
+        const changelogContent = node_fs_1.default.readFileSync(changelogPath, 'utf8');
+        return (0, node_karin_1.logs)({
+            version: root_1.Root.pluginVersion,
+            data: changelogContent,
+            length
+        });
+    }
+    catch {
+        return '';
+    }
+};
+exports.getLocalChangelog = getLocalChangelog;
+/**
+ * 采集 `#kkk版本` 使用的安全运行环境快照。
+ *
+ * 不采集账号、主机名、用户目录、网络地址、环境变量内容、启动参数或适配器鉴权信息，
+ * 保证该命令在群聊中触发时不会把机器身份和凭据写入图片。
+ *
+ * @param event 当前消息事件
+ */
+const collectRuntimeReport = (event) => {
+    const packageMetadata = root_1.Root.pkg;
+    const adapter = event.bot.adapter;
+    const cpus = node_os_1.default.cpus();
+    const memory = process.memoryUsage();
+    const totalMemory = node_os_1.default.totalmem();
+    const usedMemory = Math.max(0, totalMemory - node_os_1.default.freemem());
+    const buildMetadata = (0, build_metadata_1.getBuildMetadata)();
+    const currentChangelog = (0, exports.getLocalChangelog)(1);
+    const renderScale = Math.min(2, Math.max(0.5, Number(Config_1.Config.app.renderScale) / 100));
+    const buildState = !buildMetadata ? 'unavailable' : buildMetadata.version === root_1.Root.pluginVersion ? 'matched' : 'mismatched';
+    return {
+        snapshotAt: new Intl.DateTimeFormat('zh-CN', {
+            year: 'numeric',
+            month: '2-digit',
+            day: '2-digit',
+            hour: '2-digit',
+            minute: '2-digit',
+            second: '2-digit',
+            hour12: false
+        }).format(new Date()),
+        identity: {
+            pluginName: root_1.Root.pluginName,
+            pluginVersion: root_1.Root.pluginVersion,
+            karinVersion: root_1.Root.karinVersion || '未知',
+            releaseType: /^\d+\.\d+\.\d+$/.test(root_1.Root.pluginVersion) ? 'Stable' : 'Preview',
+            requiredNodeVersion: packageMetadata.engines?.node ?? '未声明',
+            requiredKarinVersion: packageMetadata.karin?.engines ?? packageMetadata.engines?.karin ?? '未声明'
+        },
+        build: {
+            state: buildState,
+            version: buildMetadata?.version,
+            buildTime: buildMetadata?.buildTime ? (0, build_metadata_1.formatBuildTime)(buildMetadata.buildTime) : undefined,
+            shortCommitHash: buildMetadata?.shortCommitHash
+        },
+        runtime: {
+            nodeVersion: process.version,
+            nodeEnv: process.env.NODE_ENV ?? '未设置',
+            os: `${node_os_1.default.type()} ${node_os_1.default.release()}`,
+            platform: node_os_1.default.platform(),
+            arch: node_os_1.default.arch(),
+            timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || '未知',
+            container: node_karin_1.isDocker,
+            systemUptime: formatDuration(node_os_1.default.uptime()),
+            processUptime: formatDuration(process.uptime())
+        },
+        adapter: {
+            name: adapter.name || '未知',
+            version: adapter.version || '未知',
+            platform: String(adapter.platform || '未知'),
+            protocol: String(adapter.protocol || '未知'),
+            standard: String(adapter.standard || '未知'),
+            communication: String(adapter.communication || '未知'),
+            connectedFor: formatDuration(Math.max(0, (Date.now() - adapter.connectTime) / 1000))
+        },
+        renderer: {
+            scale: `${renderScale.toFixed(2)}x`,
+            timeout: `${Config_1.Config.app.RenderWaitTime}秒`,
+            multiPage: Config_1.Config.app.multiPageRender && adapter.protocol !== 'qqbot'
+        },
+        resources: {
+            cpuModel: cpus[0]?.model?.trim() || '未知处理器',
+            cpuCores: cpus.length,
+            totalMemory: (0, helpers_1.formatBytes)(totalMemory),
+            usedMemory: (0, helpers_1.formatBytes)(usedMemory),
+            memoryUsagePercent: totalMemory > 0 ? `${((usedMemory / totalMemory) * 100).toFixed(1)}%` : '未知',
+            processRss: (0, helpers_1.formatBytes)(memory.rss),
+            heapUsed: (0, helpers_1.formatBytes)(memory.heapUsed)
+        },
+        releaseNotes: {
+            markdown: currentChangelog,
+            available: currentChangelog.length > 0
+        }
+    };
+};
+exports.collectRuntimeReport = collectRuntimeReport;

package/lib/karin/module/utils/semver.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSemverGreater = void 0;
+/**
+ * 语义化版本比较
+ * @param remote 远程版本字符串
+ * @param local 本地版本字符串
+ * @returns 如果远程版本大于本地版本则返回true，否则返回false
+ */
+const isSemverGreater = (remote, local) => {
+    if (!remote || !local)
+        return false;
+    const parse = (v) => {
+        v = v.trim();
+        if (v.startsWith('v') || v.startsWith('V'))
+            v = v.slice(1);
+        const [preBuild] = v.split('+', 2);
+        const [core, pre] = preBuild.split('-', 2);
+        const parts = core.split('.');
+        const major = parseInt(parts[0] || '0', 10) || 0;
+        const minor = parseInt(parts[1] || '0', 10) || 0;
+        const patch = parseInt(parts[2] || '0', 10) || 0;
+        const prerelease = pre ? pre.split('.') : [];
+        return { major, minor, patch, prerelease };
+    };
+    const cmpId = (a, b) => {
+        const an = /^\d+$/.test(a);
+        const bn = /^\d+$/.test(b);
+        if (an && bn) {
+            const na = parseInt(a, 10);
+            const nb = parseInt(b, 10);
+            if (na === nb)
+                return 0;
+            return na > nb ? 1 : -1;
+        }
+        if (an && !bn)
+            return -1;
+        if (!an && bn)
+            return 1;
+        if (a === b)
+            return 0;
+        return a > b ? 1 : -1;
+    };
+    const r = parse(remote);
+    const l = parse(local);
+    if (r.major !== l.major)
+        return r.major > l.major;
+    if (r.minor !== l.minor)
+        return r.minor > l.minor;
+    if (r.patch !== l.patch)
+        return r.patch > l.patch;
+    const ra = r.prerelease;
+    const la = l.prerelease;
+    if (ra.length === 0 && la.length === 0)
+        return false;
+    if (ra.length === 0 && la.length > 0)
+        return true;
+    if (ra.length > 0 && la.length === 0)
+        return false;
+    const len = Math.min(ra.length, la.length);
+    for (const [i, raItem] of ra.entries()) {
+        if (i >= len)
+            break;
+        const c = cmpId(raItem, la[i]);
+        if (c !== 0)
+            return c > 0;
+    }
+    if (ra.length !== la.length)
+        return ra.length > la.length;
+    return false;
+};
+exports.isSemverGreater = isSemverGreater;

package/lib/karin/module/utils/statisticsAggregate.js

@@ -0,0 +1,415 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aggregateGlobal = exports.aggregateGroup = exports.buildWeekdayAverages = exports.fiveNumberSummary = exports.bucketIndexOf = exports.weekdayIndexOf = exports.startOfLocalDay = exports.trimEmptyBuckets = exports.buildMetricDistributions = exports.sumBy = exports.buildDateWindow = exports.GROUP_USER_BUCKETS = exports.USER_PARSE_BUCKETS = exports.USER_GROUP_BUCKETS = exports.SILENCE_BUCKETS = exports.SIZE_BUCKETS = exports.TOP_USER_LIMIT = exports.TREND_DAYS = void 0;
+const db_1 = require("../../module/db");
+/**
+ * 统计海报的**纯聚合层**。
+ *
+ * 从 `apps/statistics.ts` 里抽出来的原因：原来这些计算散在两个 handler 闭包里，
+ * 除了「跑一遍真实命令」之外没有任何办法验证 —— 而海报模板的测试用的是手写夹具，
+ * 只能证明「给模板这些数据能画出来」，证明不了「后端真能算出这些数据」。
+ * 抽成纯函数之后，可以用真实的库写入 → 真实查询 → 真实聚合做端到端断言。
+ *
+ * 这里只做「行 → 图表数据」的变换，不碰数据库、不碰 bot API、不碰渲染。
+ */
+/** 趋势图回看天数 */
+exports.TREND_DAYS = 30;
+/** 活跃用户榜取前 N 名 */
+exports.TOP_USER_LIMIT = 10;
+/** 群规模分桶的边界（右开区间，最后一档无上界） */
+exports.SIZE_BUCKETS = [
+    { label: '1-10', min: 1, max: 10 },
+    { label: '11-50', min: 11, max: 50 },
+    { label: '51-200', min: 51, max: 200 },
+    { label: '201-1000', min: 201, max: 1000 },
+    { label: '1000+', min: 1001, max: Number.MAX_SAFE_INTEGER }
+];
+/** 群沉默分桶：按最后一次解析距今的天数 */
+exports.SILENCE_BUCKETS = [
+    { label: '今天', min: 0, max: 0 },
+    { label: '1-7天', min: 1, max: 7 },
+    { label: '8-30天', min: 8, max: 30 },
+    { label: '31-90天', min: 31, max: 90 },
+    { label: '90天+', min: 91, max: Number.MAX_SAFE_INTEGER }
+];
+/**
+ * 用户活跃度热力图的横轴档：按用过几个群。
+ * 上界统一是 `value < max`，所以「1 个群」的 max 是 2。
+ */
+exports.USER_GROUP_BUCKETS = [
+    { label: '1 个群', max: 2 },
+    { label: '2-3 个群', max: 4 },
+    { label: '4-6 个群', max: 7 },
+    { label: '7-9 个群', max: 10 },
+    { label: '10+ 个群', max: Number.MAX_SAFE_INTEGER }
+];
+/** 热力图纵轴档：按用户总解析次数 */
+exports.USER_PARSE_BUCKETS = [
+    { label: '<50', max: 50 },
+    { label: '50-200', max: 200 },
+    { label: '200-500', max: 500 },
+    { label: '500-1k', max: 1000 },
+    { label: '1k+', max: Number.MAX_SAFE_INTEGER }
+];
+/** 群组活跃度箱线图的横轴档：按群内使用人数 */
+exports.GROUP_USER_BUCKETS = [
+    { label: '<20', max: 20 },
+    { label: '20-50', max: 50 },
+    { label: '50-100', max: 100 },
+    { label: '100-300', max: 300 },
+    { label: '300+', max: Number.MAX_SAFE_INTEGER }
+];
+/** 生成最近 N 天的 UTC 日期窗口（升序），与写入端 `toISOString().split('T')[0]` 同口径 */
+const buildDateWindow = (days) => {
+    const today = new Date();
+    const dates = [];
+    for (let offset = days - 1; offset >= 0; offset--) {
+        const day = new Date(today);
+        day.setUTCDate(day.getUTCDate() - offset);
+        dates.push(day.toISOString().split('T')[0]);
+    }
+    return dates;
+};
+exports.buildDateWindow = buildDateWindow;
+/**
+ * 平台计数表 → 排行榜用的堆叠分段（次数降序）。
+ * 顺序固定成「多的在前」，堆叠条的色块从粗到细，读起来有主次。
+ */
+const toSegments = (byPlatform) => [...(byPlatform ?? new Map()).entries()]
+    .map(([platform, count]) => ({ platform, count }))
+    .filter((segment) => segment.count > 0)
+    .sort((a, b) => b.count - a.count);
+/** 统计每个群在每个平台上的去重用户数 */
+const sumBy = (rows) => {
+    const merged = new Map();
+    for (const row of rows) {
+        merged.set(row.key, (merged.get(row.key) ?? 0) + row.count);
+    }
+    return [...merged.entries()]
+        .map(([key, count]) => ({ key, count }))
+        .filter((item) => item.count > 0)
+        .sort((a, b) => b.count - a.count);
+};
+exports.sumBy = sumBy;
+/**
+ * 把耗时分桶行整理成「桶序固定、缺的补 0」的结构。
+ *
+ * 桶序必须按 `METRIC_BUCKETS` 的定义走，不能按字典序 —— 否则 `<1s` 会排到 `3-5s` 后面。
+ * 一次都没采到就返回空数组，模板侧据此不渲染那张图。
+ */
+const buildMetricDistributions = (rows) => Object.keys(db_1.METRIC_BUCKETS)
+    .map((metric) => {
+    const all = db_1.METRIC_BUCKETS[metric].map((bucket) => ({
+        label: bucket.label,
+        upper: bucket.upper,
+        count: rows.find((row) => row.metric === metric && row.bucket === bucket.label)?.count ?? 0
+    }));
+    return { metric, buckets: (0, exports.trimEmptyBuckets)(all) };
+})
+    .filter((item) => item.buckets.length > 0);
+exports.buildMetricDistributions = buildMetricDistributions;
+/**
+ * 裁掉两端连续为空的档，只留「有数据的范围 + 左右各一个空档」。
+ *
+ * 横轴不能写死：档位按最慢的情况铺到了 10min+，正常部署下末尾一大半永远是空的；
+ * 反过来如果部署整体偏慢，前面一大半又永远是空的 —— 两头都会把真正有数据的区间挤成一小撮。
+ * 左右各留一个空档，是为了让累计曲线有个从 0% 起来的起点、以及到 100% 之后的平台段，
+ * 只剩一个数据档时也不至于退化成孤零零一个点。
+ * @param buckets 按档位顺序排好的桶
+ * @returns 裁剪后的桶；整条都没数据时返回空数组
+ */
+const trimEmptyBuckets = (buckets) => {
+    const first = buckets.findIndex((bucket) => bucket.count > 0);
+    if (first < 0)
+        return [];
+    let last = buckets.length - 1;
+    while (last > first && buckets[last].count === 0)
+        last--;
+    return buckets.slice(Math.max(0, first - 1), Math.min(buckets.length, last + 2));
+};
+exports.trimEmptyBuckets = trimEmptyBuckets;
+/** 把日期/时间戳归到「本地时区当天零点」，用来算跨了几个自然日 */
+const startOfLocalDay = (value) => {
+    const date = new Date(value);
+    return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+};
+exports.startOfLocalDay = startOfLocalDay;
+/** 日期字符串 → 0(周一) ~ 6(周日) */
+const weekdayIndexOf = (date) => (new Date(`${date}T00:00:00Z`).getUTCDay() + 6) % 7;
+exports.weekdayIndexOf = weekdayIndexOf;
+/** 取数值落在第几档；超出最后一档归到最后一格 */
+const bucketIndexOf = (buckets, value) => {
+    const index = buckets.findIndex((bucket) => value < bucket.max);
+    return index === -1 ? buckets.length - 1 : index;
+};
+exports.bucketIndexOf = bucketIndexOf;
+/**
+ * 五数概括 `[最小, Q1, 中位数, Q3, 最大]`，线性插值取分位。
+ * 空数组返回全 0 —— 调用方会按 count 过滤掉空档，不会把 0 当成真数据画出去。
+ */
+const fiveNumberSummary = (values) => {
+    if (values.length === 0)
+        return [0, 0, 0, 0, 0];
+    const sorted = [...values].sort((a, b) => a - b);
+    const quantile = (q) => {
+        const position = (sorted.length - 1) * q;
+        const low = Math.floor(position);
+        const high = Math.ceil(position);
+        return Math.round(sorted[low] + (sorted[high] - sorted[low]) * (position - low));
+    };
+    return [sorted[0], quantile(0.25), quantile(0.5), quantile(0.75), sorted[sorted.length - 1]];
+};
+exports.fiveNumberSummary = fiveNumberSummary;
+/**
+ * 把「按天的数值」折算成「每个星期几的日均」。
+ *
+ * 关键在于分母：必须用**窗口里有几个该星期几**，而不是有几天有数据。
+ * 30 天窗口里周一/周二各 5 天、其余各 4 天，不除的话条形高度里会混进 25% 的曝光偏差。
+ * @param windowDates 窗口内的全部日期（升序），用来数每个星期几出现几次
+ * @param rows 有数据的天
+ */
+const buildWeekdayAverages = (windowDates, rows) => {
+    const occurrences = new Array(7).fill(0);
+    const totals = new Array(7).fill(0);
+    for (const date of windowDates)
+        occurrences[(0, exports.weekdayIndexOf)(date)] += 1;
+    for (const row of rows)
+        totals[(0, exports.weekdayIndexOf)(row.date)] += row.count;
+    return totals.map((total, index) => (occurrences[index] > 0 ? Math.round(total / occurrences[index]) : 0));
+};
+exports.buildWeekdayAverages = buildWeekdayAverages;
+/**
+ * 群海报的聚合：把六组查询结果变成模板直接可用的形状。
+ * @param input 群相关的各维度行
+ */
+const aggregateGroup = (input) => {
+    const { groupStats, groupHistory, hourRows, workTypeRows, metricRows, globalHistory, activeDays, uniqueUsers } = input;
+    const groupTotalParses = groupStats.reduce((sum, stat) => sum + stat.parseCount, 0);
+    // 平台分布：按平台聚合并降序，只留有数据的平台
+    const platformUsers = new Map();
+    for (const stat of groupStats) {
+        if (!platformUsers.has(stat.platform))
+            platformUsers.set(stat.platform, new Set());
+        platformUsers.get(stat.platform).add(stat.userId);
+    }
+    const platformData = (0, exports.sumBy)(groupStats.map((stat) => ({ key: stat.platform, count: stat.parseCount }))).map((item) => ({
+        platform: item.key,
+        count: item.count,
+        users: platformUsers.get(item.key)?.size ?? 0
+    }));
+    // 趋势：按天补齐窗口，缺的那天补 0 —— 不补的话折线会把断档直接连成直线
+    const windowDates = (0, exports.buildDateWindow)(exports.TREND_DAYS);
+    const dailyTotals = new Map();
+    for (const row of groupHistory) {
+        dailyTotals.set(row.date, (dailyTotals.get(row.date) ?? 0) + row.parseCount);
+    }
+    const trend = windowDates.map((date) => ({ date, count: dailyTotals.get(date) ?? 0 }));
+    // 全局日均：给本群趋势当参照基准
+    const globalDailyAverage = globalHistory.length > 0 ? globalHistory.reduce((sum, row) => sum + row.totalParses, 0) / globalHistory.length : 0;
+    // 24 小时分布：补满 24 格，跨平台求和
+    const hourly = new Array(24).fill(0);
+    for (const row of hourRows) {
+        if (row.hour >= 0 && row.hour < 24)
+            hourly[row.hour] += row.parseCount;
+    }
+    // 周内分布：算「该星期几的日均」而不是累计总量。
+    // 30 天窗口不是 7 的整数倍（末尾那两天对应的星期几各出现 5 次，其余各 4 次），
+    // 直接求和的话那两个星期几会凭空高出 25%，纯粹是曝光天数造成的，跟用户行为无关。
+    // 出现天数必须按窗口日期数，不能按有数据的行为准 —— 没记录的那天也算出现了一次。
+    const weekday = (0, exports.buildWeekdayAverages)(windowDates, groupHistory.map((row) => ({ date: row.date, count: row.parseCount })));
+    // 平台 × 时段：ParseHourStats 本身就带 platform，直接铺成矩阵
+    const platformHourMap = new Map();
+    for (const row of hourRows) {
+        if (row.hour < 0 || row.hour > 23)
+            continue;
+        if (!platformHourMap.has(row.platform))
+            platformHourMap.set(row.platform, new Array(24).fill(0));
+        platformHourMap.get(row.platform)[row.hour] += row.parseCount;
+    }
+    const platformHourly = platformData
+        .filter((item) => platformHourMap.has(item.platform))
+        .map((item) => ({ platform: item.platform, values: platformHourMap.get(item.platform) }));
+    // 每个用户的平台构成，给活跃用户榜做堆叠条
+    const userPlatforms = new Map();
+    for (const stat of groupStats) {
+        if (!userPlatforms.has(stat.userId))
+            userPlatforms.set(stat.userId, new Map());
+        const byPlatform = userPlatforms.get(stat.userId);
+        byPlatform.set(stat.platform, (byPlatform.get(stat.platform) ?? 0) + stat.parseCount);
+    }
+    return {
+        groupTotalParses,
+        groupUniqueUsers: uniqueUsers,
+        parsesPerUser: uniqueUsers > 0 ? groupTotalParses / uniqueUsers : 0,
+        activeDays,
+        topPlatform: platformData[0]?.platform,
+        platformData,
+        trend,
+        globalDailyAverage,
+        /** 活跃用户榜的原始行，昵称由调用方补（要打 bot API） */
+        topUserRows: (0, exports.sumBy)(groupStats.map((stat) => ({ key: stat.userId, count: stat.parseCount })))
+            .slice(0, exports.TOP_USER_LIMIT)
+            .map((row) => ({ ...row, segments: toSegments(userPlatforms.get(row.key)) })),
+        hourly,
+        weekday,
+        platformHourly,
+        workTypes: (0, exports.sumBy)(workTypeRows.map((row) => ({ key: row.workType, count: row.parseCount }))).map((item) => ({
+            workType: item.key,
+            count: item.count
+        })),
+        metrics: (0, exports.buildMetricDistributions)(metricRows)
+    };
+};
+exports.aggregateGroup = aggregateGroup;
+/**
+ * 全局海报的聚合：把六组查询结果变成模板直接可用的形状。
+ * @param input 全局各维度行
+ */
+const aggregateGlobal = (input) => {
+    const { allStats, historyData, firstSeen, workTypeRows, metricRows, historyCompleteFrom, nowMs = Date.now() } = input;
+    const totalParses = allStats.reduce((sum, stat) => sum + stat.parseCount, 0);
+    const totalUsers = new Set(allStats.map((stat) => stat.userId)).size;
+    // 每个平台覆盖了多少群、多少用户
+    const platformGroups = new Map();
+    const platformUsers = new Map();
+    for (const stat of allStats) {
+        if (!platformGroups.has(stat.platform)) {
+            platformGroups.set(stat.platform, new Set());
+            platformUsers.set(stat.platform, new Set());
+        }
+        platformGroups.get(stat.platform).add(stat.groupId);
+        platformUsers.get(stat.platform).add(stat.userId);
+    }
+    const platformData = (0, exports.sumBy)(allStats.map((stat) => ({ key: stat.platform, count: stat.parseCount }))).map((item) => ({
+        platform: item.key,
+        count: item.count,
+        groups: platformGroups.get(item.key)?.size ?? 0,
+        users: platformUsers.get(item.key)?.size ?? 0
+    }));
+    // 全局趋势：按天补齐窗口
+    const historyByDate = new Map(historyData.map((row) => [row.date, row]));
+    const windowDates = (0, exports.buildDateWindow)(exports.TREND_DAYS);
+    const trend = windowDates.map((date) => ({ date, count: historyByDate.get(date)?.totalParses ?? 0 }));
+    const dailyAverage = trend.length > 0 ? trend.reduce((sum, point) => sum + point.count, 0) / trend.length : 0;
+    // 分平台趋势：ParseHistory 带各平台列，直接铺开
+    const platformTrend = {
+        dates: windowDates,
+        series: platformData.map((item) => ({
+            platform: item.platform,
+            values: windowDates.map((date) => historyByDate.get(date)?.[item.platform] ?? 0)
+        }))
+    };
+    // 周内分布：同群维度，取「该星期几的日均」
+    const weekday = (0, exports.buildWeekdayAverages)(windowDates, historyData.map((row) => ({ date: row.date, count: row.totalParses })));
+    // 按群聚合：总次数 + 使用人数
+    const groupAgg = new Map();
+    const lastSeenByGroup = new Map();
+    for (const stat of allStats) {
+        const entry = groupAgg.get(stat.groupId) ?? { totalParses: 0, users: new Set(), platforms: new Map() };
+        entry.totalParses += stat.parseCount;
+        entry.users.add(stat.userId);
+        entry.platforms.set(stat.platform, (entry.platforms.get(stat.platform) ?? 0) + stat.parseCount);
+        groupAgg.set(stat.groupId, entry);
+        const prev = lastSeenByGroup.get(stat.groupId);
+        if (!prev || stat.updatedAt > prev)
+            lastSeenByGroup.set(stat.groupId, stat.updatedAt);
+    }
+    // 群规模分布
+    const sizeBuckets = exports.SIZE_BUCKETS.map((bucket) => ({
+        label: bucket.label,
+        count: [...groupAgg.values()].filter((agg) => agg.totalParses >= bucket.min && agg.totalParses <= bucket.max).length
+    }));
+    // 群沉默分布：每个群最后一次解析距今几个**自然日**。
+    // 用 24 小时整除的话，昨晚 23:00 解析过的群会被算进「今天」，
+    // 而标签上写的是自然日口径，读起来对不上。
+    const todayStart = (0, exports.startOfLocalDay)(nowMs);
+    const silenceBuckets = exports.SILENCE_BUCKETS.map((bucket) => ({
+        label: bucket.label,
+        count: [...lastSeenByGroup.values()].filter((iso) => {
+            const days = Math.round((todayStart - (0, exports.startOfLocalDay)(iso)) / 86400000);
+            return days >= bucket.min && days <= bucket.max;
+        }).length
+    }));
+    // 群组增长：按首次出现日期做累计，窗口外的老群计入起点基数
+    const firstSeenByDate = new Map();
+    let growthBase = 0;
+    const windowStart = windowDates[0];
+    for (const row of firstSeen) {
+        const date = row.firstSeen.split('T')[0];
+        if (date < windowStart) {
+            growthBase++;
+            continue;
+        }
+        firstSeenByDate.set(date, (firstSeenByDate.get(date) ?? 0) + 1);
+    }
+    let cumulative = growthBase;
+    const groupGrowth = windowDates.map((date) => {
+        cumulative += firstSeenByDate.get(date) ?? 0;
+        return { date, count: cumulative };
+    });
+    // 用户聚合：跨了几个群、总共解析多少次
+    const userAgg = new Map();
+    for (const stat of allStats) {
+        const entry = userAgg.get(stat.userId) ?? { parses: 0, groups: new Set() };
+        entry.parses += stat.parseCount;
+        entry.groups.add(stat.groupId);
+        userAgg.set(stat.userId, entry);
+    }
+    // 用户活跃度热力图：把**全部**用户打进二维矩阵。
+    // 这里刻意不做 TopN 截断 —— 分布图一旦只取最活跃的那批，口径就废了
+    // （会得到「人人都是重度用户」的假象）。矩阵本身只有 5×5 格，聚合后传输量反而最小。
+    const heatCounts = new Map();
+    for (const agg of userAgg.values()) {
+        const x = (0, exports.bucketIndexOf)(exports.USER_GROUP_BUCKETS, agg.groups.size);
+        const y = (0, exports.bucketIndexOf)(exports.USER_PARSE_BUCKETS, agg.parses);
+        const key = `${x}:${y}`;
+        heatCounts.set(key, (heatCounts.get(key) ?? 0) + 1);
+    }
+    const heatCells = [...heatCounts.entries()].map(([key, count]) => {
+        const [x, y] = key.split(':').map(Number);
+        return [x, y, count];
+    });
+    // 群组活跃度箱线：按群人数分档，看各档的解析次数分布。
+    // 空档直接丢掉，否则轴上会出现一根没有意义的零箱体。
+    const groupActivity = exports.GROUP_USER_BUCKETS.map((bucket, index) => {
+        const inBucket = [...groupAgg.values()].filter((agg) => (0, exports.bucketIndexOf)(exports.GROUP_USER_BUCKETS, agg.users.size) === index);
+        return { label: bucket.label, count: inBucket.length, box: (0, exports.fiveNumberSummary)(inBucket.map((agg) => agg.totalParses)) };
+    }).filter((item) => item.count > 0);
+    return {
+        totalGroups: groupAgg.size,
+        totalUsers,
+        totalParses,
+        activePlatforms: platformData.length,
+        platformData,
+        trend,
+        trendCompleteFrom: historyCompleteFrom,
+        dailyAverage,
+        platformTrend,
+        weekday,
+        /** 群组排行的原始行，群名由调用方补（要打 bot API） */
+        topGroupRows: [...groupAgg.entries()]
+            .sort((a, b) => b[1].totalParses - a[1].totalParses)
+            .slice(0, exports.TOP_USER_LIMIT)
+            .map(([groupId, agg]) => ({
+            groupId,
+            totalParses: agg.totalParses,
+            uniqueUsers: agg.users.size,
+            segments: toSegments(agg.platforms)
+        })),
+        sizeBuckets,
+        groupGrowth,
+        userActivity: {
+            xLabels: exports.USER_GROUP_BUCKETS.map((bucket) => bucket.label),
+            yLabels: exports.USER_PARSE_BUCKETS.map((bucket) => bucket.label),
+            cells: heatCells,
+            max: heatCells.reduce((max, [, , count]) => Math.max(max, count), 0)
+        },
+        groupActivity,
+        silenceBuckets,
+        workTypes: workTypeRows
+            .filter((row) => row.parseCount > 0)
+            .map((row) => ({ platform: row.platform, workType: row.workType, count: row.parseCount })),
+        metrics: (0, exports.buildMetricDistributions)(metricRows)
+    };
+};
+exports.aggregateGlobal = aggregateGlobal;