koishi-plugin-chat-analyse 1.3.0 → 1.3.1

package/lib/Stat.d.ts

@@ -0,0 +1,28 @@
+import { Context, Command } from 'koishi';
+import { Renderer } from './Renderer';
+import { Config } from './index';
+/**
+ * @class Stat
+ * @description 提供统一的统计查询服务。负责注册查询命令，从数据库获取数据，并调用渲染器生成图表。
+ */
+export declare class Stat {
+    private ctx;
+    private config;
+    renderer: Renderer;
+    /**
+     * @param ctx - Koishi 的插件上下文。
+     * @param config - 插件的配置对象。
+     */
+    constructor(ctx: Context, config: Config);
+    /**
+     * @private @method parseScope
+     * @description 根据选项解析查询范围，返回 uids 和范围描述
+     */
+    private parseScope;
+    /**
+     * @public @method registerCommands
+     * @description 根据配置，动态地将子命令注册到主命令下。
+     * @param cmd - 主命令实例。
+     */
+    registerCommands(cmd: Command): void;
+}

package/lib/index.js

@@ -1808,141 +1808,168 @@ var Stat = class {
     __name(this, "Stat");
   }
   renderer;
+  /**
+   * @private @method parseScope
+   * @description 根据选项解析查询范围，返回 uids 和范围描述
+   */
+  async parseScope(session, options) {
+    const scopeDesc = { guildId: void 0, userId: void 0 };
+    const query = {};
+    if (options.all) return { uids: void 0, scopeDesc };
+    if (options.user) scopeDesc.userId = import_koishi3.h.select(options.user, "at")[0]?.attrs.id ?? options.user.trim();
+    if (options.guild) scopeDesc.guildId = options.guild;
+    if (!scopeDesc.guildId && !scopeDesc.userId) scopeDesc.guildId = session.guildId;
+    if (!scopeDesc.guildId && !scopeDesc.userId) return { error: "请指定查询范围", scopeDesc };
+    if (scopeDesc.guildId) query.channelId = scopeDesc.guildId;
+    if (scopeDesc.userId) query.userId = scopeDesc.userId;
+    const users = await this.ctx.database.get("analyse_user", query, ["uid"]);
+    if (users.length === 0) return { error: "暂无统计数据", scopeDesc };
+    return { uids: users.map((u) => u.uid), scopeDesc };
+  }
   /**
    * @public @method registerCommands
    * @description 根据配置，动态地将子命令注册到主命令下。
    * @param cmd - 主命令实例。
    */
   registerCommands(cmd) {
-    const createHandler = /* @__PURE__ */ __name((handler) => {
-      return async ({ session, options }) => {
-        const scope = await parseQueryScope(this.ctx, session, options);
-        if (scope.error) return scope.error;
-        try {
-          const result = await handler(scope, options);
-          if (typeof result === "string") return result;
-          for await (const buffer of result) await session.send(import_koishi3.h.image(buffer, "image/png"));
-        } catch (error) {
-          this.ctx.logger.error("图片渲染失败:", error);
-          return "图片渲染失败";
-        }
-      };
-    }, "createHandler");
+    const handleAction = /* @__PURE__ */ __name(async (session, promise) => {
+      try {
+        const result = await promise;
+        if (typeof result === "string") return result;
+        for await (const buffer of result) await session.send(import_koishi3.h.image(buffer, "image/png"));
+      } catch (error) {
+        this.ctx.logger.error("图片渲染失败:", error);
+        return "图片渲染失败";
+      }
+    }, "handleAction");
     if (this.config.enableCmdStat) {
-      cmd.subcommand("cmdstat", "命令统计").usage("查询命令统计，可指定查询范围，默认当前群组。").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("separate", "-s 分离展示").option("all", "-a 全局").action(createHandler(async (scope, options) => {
-        const stats = await this.ctx.database.select("analyse_cmd").where({ uid: { $in: scope.uids } }).groupBy("command", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count"), lastUsed: /* @__PURE__ */ __name((row) => import_koishi3.$.max(row.timestamp), "lastUsed") }).orderBy("count", "desc").execute();
+      cmd.subcommand("cmdstat", "命令统计").usage("查询命令统计，可指定查询范围，默认当前群组。").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("separate", "-s 分离展示").option("all", "-a 全局统计").action(({ session, options }) => handleAction(session, (async () => {
+        const scope = await this.parseScope(session, options);
+        if (scope.error) return scope.error;
+        const query = scope.uids ? { uid: { $in: scope.uids } } : {};
+        const stats = await this.ctx.database.select("analyse_cmd").where(query).groupBy("command", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count"), lastUsed: /* @__PURE__ */ __name((row) => import_koishi3.$.max(row.timestamp), "lastUsed") }).orderBy("count", "desc").execute();
         if (stats.length === 0) return "暂无统计数据";
         let processedStats;
         if (options.separate) {
           processedStats = stats;
         } else {
-          const mergedStatsMap = /* @__PURE__ */ new Map();
+          const merged = /* @__PURE__ */ new Map();
           for (const stat of stats) {
-            const mainCommand = stat.command.split(".")[0];
-            const existing = mergedStatsMap.get(mainCommand) || { count: 0, lastUsed: /* @__PURE__ */ new Date(0) };
+            const mainCmd = stat.command.split(".")[0];
+            const existing = merged.get(mainCmd) || { count: 0, lastUsed: /* @__PURE__ */ new Date(0) };
             existing.count += stat.count;
             if (stat.lastUsed > existing.lastUsed) existing.lastUsed = stat.lastUsed;
-            mergedStatsMap.set(mainCommand, existing);
+            merged.set(mainCmd, existing);
           }
-          processedStats = Array.from(mergedStatsMap.entries()).map(([command, data]) => ({
-            command,
-            count: data.count,
-            lastUsed: data.lastUsed
-          })).sort((a, b) => b.count - a.count);
+          processedStats = Array.from(merged.entries()).map(([command, data]) => ({ ...data, command })).sort((a, b) => b.count - a.count);
         }
-        const total = processedStats.reduce((sum, record) => sum + record.count, 0);
+        const total = processedStats.reduce((sum, r) => sum + r.count, 0);
         const list = processedStats.map((item) => [item.command, item.count, item.lastUsed]);
         const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "命令" });
         return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list }, ["命令", "次数", "最后使用"]);
-      }));
+      })()));
     }
     if (this.config.enableMsgStat) {
-      cmd.subcommand("msgstat", "发言统计").usage("查询发言统计，可指定查询范围，默认当前群组。").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("type", "-t <type:string> 指定类型").option("all", "-a 全局").action(createHandler(async (scope, options) => {
-        const { type } = options;
-        const query = { uid: { $in: scope.uids } };
-        if (type) query.type = type;
-        const users = await this.ctx.database.get("analyse_user", { uid: { $in: scope.uids } }, ["uid", "userName"]);
-        const userNameMap = new Map(users.map((u) => [u.uid, u.userName]));
+      cmd.subcommand("msgstat", "发言统计").usage("查询发言统计，可指定查询范围，默认当前群组。").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("type", "-t <type:string> 指定类型").option("all", "-a 全局统计").action(({ session, options }) => handleAction(session, (async () => {
+        const scope = await this.parseScope(session, options);
+        if (scope.error) return scope.error;
+        const query = scope.uids ? { uid: { $in: scope.uids } } : {};
+        if (options.type) query.type = options.type;
+        const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "发言", subtype: options.type });
+        if (options.user && options.guild) {
+          const stats2 = await this.ctx.database.select("analyse_msg").where(query).groupBy("type", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count"), lastUsed: /* @__PURE__ */ __name((row) => import_koishi3.$.max(row.timestamp), "lastUsed") }).orderBy("count", "desc").execute();
+          if (stats2.length === 0) return "暂无统计数据";
+          const total2 = stats2.reduce((sum, r) => sum + r.count, 0);
+          const list2 = stats2.map((item) => [item.type, item.count, item.lastUsed]);
+          return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total: total2, list: list2 }, ["类型", "条数", "最后发言"]);
+        }
+        if (options.user) {
+          const userRecords = await this.ctx.database.get("analyse_user", { uid: { $in: scope.uids } });
+          const uidToChannelMap = new Map(userRecords.map((u) => [u.uid, u.channelName || u.channelId]));
+          const stats2 = await this.ctx.database.select("analyse_msg").where(query).groupBy("uid", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count"), lastUsed: /* @__PURE__ */ __name((row) => import_koishi3.$.max(row.timestamp), "lastUsed") }).orderBy("count", "desc").execute();
+          if (stats2.length === 0) return "暂无统计数据";
+          const total2 = stats2.reduce((sum, r) => sum + r.count, 0);
+          const list2 = stats2.map((item) => [uidToChannelMap.get(item.uid) || `未知群组`, item.count, item.lastUsed]);
+          return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total: total2, list: list2 }, ["群组", "条数", "最后发言"]);
+        }
         const stats = await this.ctx.database.select("analyse_msg").where(query).groupBy("uid", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count"), lastUsed: /* @__PURE__ */ __name((row) => import_koishi3.$.max(row.timestamp), "lastUsed") }).orderBy("count", "desc").execute();
         if (stats.length === 0) return "暂无统计数据";
+        const allUids = stats.map((s) => s.uid);
+        const users = await this.ctx.database.get("analyse_user", { uid: { $in: allUids } }, ["uid", "userName"]);
+        const userNameMap = new Map(users.map((u) => [u.uid, u.userName]));
         const total = stats.reduce((sum, r) => sum + r.count, 0);
         const list = stats.map((item) => [userNameMap.get(item.uid) || `UID ${item.uid}`, item.count, item.lastUsed]);
-        const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "发言", subtype: type });
-        const headers = type ? ["用户", "条数", "最后发言"] : ["用户", "总计发言", "最后发言"];
-        return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list }, headers);
-      }));
+        return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list }, ["用户", "总计发言", "最后发言"]);
+      })()));
     }
     if (this.config.enableRankStat) {
-      cmd.subcommand("rankstat", "发言排行").usage("查询发言排行，可指定查询范围，默认当前群组。").option("guild", "-g <guildId:string> 指定群组").option("type", "-t <type:string> 指定类型").option("hours", "-o <hours:number> 指定时长", { fallback: 24 }).option("all", "-a 全局").action(createHandler(async (scope, options) => {
-        const { hours, type } = options;
-        const since = new Date(Date.now() - hours * import_koishi3.Time.hour);
-        const query = { uid: { $in: scope.uids }, timestamp: { $gte: since } };
-        if (type) query.type = type;
-        const rankStats = await this.ctx.database.select("analyse_rank").where(query).groupBy("uid", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count") }).orderBy("count", "desc").execute();
-        if (rankStats.length === 0) return "暂无统计数据";
-        const users = await this.ctx.database.get("analyse_user", { uid: { $in: scope.uids } }, ["uid", "userName"]);
+      cmd.subcommand("rankstat", "发言排行").usage("查询发言排行，可指定查询范围，默认当前群组。").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("type", "-t <type:string> 指定类型").option("duration", "-n <hours:number> 指定时长", { fallback: 24 }).option("offset", "-o <hours:number> 指定偏移").option("all", "-a 全局统计").action(({ session, options }) => handleAction(session, (async () => {
+        const scope = await this.parseScope(session, options);
+        if (scope.error) return scope.error;
+        const until = new Date(Date.now() - options.offset * import_koishi3.Time.hour);
+        const since = new Date(until.getTime() - options.duration * import_koishi3.Time.hour);
+        const query = { timestamp: { $gte: since, $lt: until } };
+        if (scope.uids) query.uid = { $in: scope.uids };
+        if (options.type) query.type = options.type;
+        const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "发言排行", timeRange: options.duration, subtype: options.type });
+        if (options.user && options.guild) {
+          const stats2 = await this.ctx.database.select("analyse_rank").where(query).groupBy("type", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count") }).orderBy("count", "desc").execute();
+          if (stats2.length === 0) return "暂无统计数据";
+          const total2 = stats2.reduce((sum, r) => sum + r.count, 0);
+          const list2 = stats2.map((r) => [r.type, r.count, total2 > 0 ? `${(r.count / total2 * 100).toFixed(2)}%` : "0.00%"]);
+          return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total: total2, list: list2 }, ["类型", "条数", "占比"]);
+        }
+        if (options.user) {
+          const userRecords = await this.ctx.database.get("analyse_user", { uid: { $in: scope.uids } });
+          const uidToChannelMap = new Map(userRecords.map((u) => [u.uid, u.channelName || u.channelId]));
+          const stats2 = await this.ctx.database.select("analyse_rank").where(query).groupBy("uid", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count") }).orderBy("count", "desc").execute();
+          if (stats2.length === 0) return "暂无统计数据";
+          const total2 = stats2.reduce((sum, r) => sum + r.count, 0);
+          const list2 = stats2.map((r) => [uidToChannelMap.get(r.uid) || "未知群组", r.count, total2 > 0 ? `${(r.count / total2 * 100).toFixed(2)}%` : "0.00%"]);
+          return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total: total2, list: list2 }, ["群组", "条数", "占比"]);
+        }
+        const stats = await this.ctx.database.select("analyse_rank").where(query).groupBy("uid", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count") }).orderBy("count", "desc").execute();
+        if (stats.length === 0) return "暂无统计数据";
+        const allUids = stats.map((s) => s.uid);
+        const users = await this.ctx.database.get("analyse_user", { uid: { $in: allUids } }, ["uid", "userName"]);
         const userNameMap = new Map(users.map((u) => [u.uid, u.userName]));
-        const total = rankStats.reduce((sum, record) => sum + record.count, 0);
-        const list = rankStats.map((item) => [userNameMap.get(item.uid) || `UID ${item.uid}`, item.count]);
-        const listWithPercentage = list.map((row) => [...row, total > 0 ? `${(row[1] / total * 100).toFixed(2)}%` : "0.00%"]);
-        const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "发言排行", timeRange: hours, subtype: type });
-        return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list: listWithPercentage }, ["用户", "总计发言", "占比"]);
-      }));
+        const total = stats.reduce((sum, r) => sum + r.count, 0);
+        const list = stats.map((r) => [userNameMap.get(r.uid) || `UID ${r.uid}`, r.count, total > 0 ? `${(r.count / total * 100).toFixed(2)}%` : "0.00%"]);
+        return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list }, ["用户", "总计发言", "占比"]);
+      })()));
     }
     if (this.config.enableActivity) {
-      cmd.subcommand("activity", "活跃统计").usage("查询活跃统计，可指定查询范围，默认当前群组。").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("hours", "-t <hours:number> 指定偏移时长").option("all", "-a 全局").option("days", "-d 切换至天数").action(createHandler(async (scope, options) => {
-        const { days, hours } = options;
-        if (days) {
-          const timeRangeInDays = 24;
-          const since = new Date(Date.now() - timeRangeInDays * import_koishi3.Time.day);
-          const stats = await this.ctx.database.select("analyse_rank").where({ uid: { $in: scope.uids }, timestamp: { $gte: since } }).project(["timestamp", "count"]).execute();
-          if (stats.length === 0) return "暂无统计数据";
-          const startOfToday = /* @__PURE__ */ new Date();
-          startOfToday.setHours(0, 0, 0, 0);
-          const dailyCounts = Array(timeRangeInDays).fill(0);
-          const dayLabels = Array(timeRangeInDays).fill("");
-          for (let i = 0; i < timeRangeInDays; i++) {
-            const d = new Date(startOfToday.getTime() - i * import_koishi3.Time.day);
-            dayLabels[timeRangeInDays - 1 - i] = String(d.getDate());
-          }
-          stats.forEach((stat) => {
-            const statDayStart = new Date(stat.timestamp);
-            statDayStart.setHours(0, 0, 0, 0);
-            const daysAgo = Math.round((startOfToday.getTime() - statDayStart.getTime()) / import_koishi3.Time.day);
-            if (daysAgo >= 0 && daysAgo < timeRangeInDays) {
-              const index = timeRangeInDays - 1 - daysAgo;
-              dailyCounts[index] += stat.count;
-            }
-          });
-          const totalMessages = dailyCounts.reduce((a, b) => a + b, 0);
-          const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "活跃", timeRange: timeRangeInDays, timeUnit: "天" });
-          return this.renderer.renderCircadianChart({ title, time: /* @__PURE__ */ new Date(), total: totalMessages, data: dailyCounts, labels: dayLabels });
-        } else {
-          const timeWindowHours = 24;
-          const offsetHours = typeof hours === "number" ? hours : 0;
-          const now = /* @__PURE__ */ new Date();
-          const until = new Date(now.getTime() - offsetHours * import_koishi3.Time.hour);
-          const since = new Date(until.getTime() - timeWindowHours * import_koishi3.Time.hour);
-          const hourlyStats = await this.ctx.database.select("analyse_rank").where({ uid: { $in: scope.uids }, timestamp: { $gte: since, $lt: until } }).groupBy("timestamp", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count") }).execute();
-          if (hourlyStats.length === 0) return "暂无统计数据";
-          const processedCounts = Array(timeWindowHours).fill(0);
-          const hourLabels = Array(timeWindowHours).fill("");
-          for (let i = 0; i < timeWindowHours; i++) {
-            const d = new Date(until.getTime() - (i + 1) * import_koishi3.Time.hour);
-            hourLabels[timeWindowHours - 1 - i] = String(d.getHours());
-          }
-          hourlyStats.forEach((stat) => {
-            const hoursBeforeUntil = Math.floor((until.getTime() - stat.timestamp.getTime()) / import_koishi3.Time.hour);
-            if (hoursBeforeUntil >= 0 && hoursBeforeUntil < timeWindowHours) {
-              const index = timeWindowHours - 1 - hoursBeforeUntil;
-              processedCounts[index] += stat.count;
-            }
-          });
-          const totalMessages = processedCounts.reduce((a, b) => a + b, 0);
-          const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "活跃", timeRange: timeWindowHours, timeUnit: "小时" });
-          return this.renderer.renderCircadianChart({ title, time: /* @__PURE__ */ new Date(), total: totalMessages, data: processedCounts, labels: hourLabels });
+      cmd.subcommand("activity", "活跃统计").usage("查询活跃统计，可指定查询范围，默认当前群组。").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("duration", "-n <units:number> 指定时长", { fallback: 24 }).option("offset", "-o <units:number> 指定偏移").option("days", "-d 切换至天").option("all", "-a 全局统计").action(({ session, options }) => handleAction(session, (async () => {
+        const scope = await this.parseScope(session, options);
+        if (scope.error) return scope.error;
+        const timeUnit = options.days ? import_koishi3.Time.day : import_koishi3.Time.hour;
+        const timeUnitName = options.days ? "天" : "小时";
+        const points = options.days ? 24 : 24;
+        const until = new Date(Date.now() - options.offset * timeUnit);
+        const since = new Date(until.getTime() - options.duration * timeUnit);
+        const query = { timestamp: { $gte: since, $lt: until } };
+        if (scope.uids) query.uid = { $in: scope.uids };
+        const stats = await this.ctx.database.select("analyse_rank").where(query).project(["timestamp", "count"]).execute();
+        if (stats.length === 0) return "暂无统计数据";
+        const counts = Array(points).fill(0);
+        const labels = Array(points).fill("");
+        const now = /* @__PURE__ */ new Date();
+        now.setMinutes(0, 0, 0);
+        for (let i = 0; i < points; i++) {
+          const pointTime = new Date(until.getTime() - (i + 1) * timeUnit);
+          labels[points - 1 - i] = options.days ? String(pointTime.getDate()) : String(pointTime.getHours());
         }
-      }));
+        stats.forEach((stat) => {
+          const diff = until.getTime() - stat.timestamp.getTime();
+          const index = points - 1 - Math.floor(diff / timeUnit);
+          if (index >= 0 && index < points) {
+            counts[index] += stat.count;
+          }
+        });
+        const total = counts.reduce((a, b) => a + b, 0);
+        const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "活跃", timeRange: options.duration, timeUnit: timeUnitName });
+        return this.renderer.renderCircadianChart({ title, time: /* @__PURE__ */ new Date(), total, data: counts, labels });
+      })()));
     }
   }
 };
@@ -1975,12 +2002,12 @@ var WhoAt = class {
   registerCommand(cmd) {
     cmd.subcommand("whoatme", "谁提及我").usage("查看最近提及我的消息，查看后自动删除。").action(async ({ session }) => {
       if (!session.userId) return "无法获取用户信息";
+      const records = await this.ctx.database.get("analyse_at", { target: session.userId }, {
+        sort: { timestamp: "asc" },
+        limit: 100
+      });
+      if (records.length === 0) return "最近没有人提及您";
       try {
-        const records = await this.ctx.database.get("analyse_at", { target: session.userId }, {
-          sort: { timestamp: "asc" },
-          limit: 100
-        });
-        if (records.length === 0) return "最近没有人提及您";
         const uids = [...new Set(records.map((r) => r.uid))];
         const users = await this.ctx.database.get("analyse_user", { uid: { $in: uids } }, ["uid", "userName", "userId"]);
         const userInfoMap = new Map(users.map((u) => [u.uid, { name: u.userName, id: u.userId }]));
@@ -1989,9 +2016,9 @@ var WhoAt = class {
           const author = (0, import_koishi4.h)("author", { id: senderInfo.id, name: senderInfo.name });
           return (0, import_koishi4.h)("message", {}, [author, import_koishi4.h.text(record.content)]);
         });
+        await session.send((0, import_koishi4.h)("message", { forward: true }, messageElements));
         const recordIdsToDelete = records.map((r) => r.id);
         await this.ctx.database.remove("analyse_at", { id: { $in: recordIdsToDelete } });
-        return (0, import_koishi4.h)("message", { forward: true }, messageElements);
       } catch (error) {
         this.ctx.logger.error("查询提及记录失败:", error);
         return "查询失败，请稍后重试";
@@ -2174,7 +2201,7 @@ var Analyse = class {
    */
   registerCommands(cmd) {
     if (this.config.enableWordCloud) {
-      cmd.subcommand("wordcloud", "生成词云").usage("基于聊天记录生成词云图，可指定范围，默认当前群组。").option("guild", "-g <guildId:string> 指定群组").option("user", "-u <user:string> 指定用户").option("hours", "-t <hours:number> 指定时长", { fallback: 24 }).option("all", "-a 全局").action(async ({ session, options }) => {
+      cmd.subcommand("wordcloud", "生成词云").usage("基于聊天记录生成词云图，可指定范围，默认当前群组。").option("guild", "-g <guildId:string> 指定群组").option("user", "-u <user:string> 指定用户").option("hours", "-t <hours:number> 指定时长", { fallback: 24 }).action(async ({ session, options }) => {
         try {
           if (!this.jieba) return "Jieba 分词服务未就绪";
           const scope = await parseQueryScope(this.ctx, session, options);
@@ -2196,7 +2223,7 @@ var Analyse = class {
           const wordList = Array.from(wordCounts.entries()).sort((a, b) => b[1] - a[1]);
           const topWordsPreview = wordList.slice(0, 10).map((item) => item[0]).join(", ");
           session.send(`正在生成词云，热门词汇：${topWordsPreview}...`);
-          const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "词云" });
+          const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "词云", timeRange: options.hours });
           const imageGenerator = this.renderer.renderWordCloud({ title, time: /* @__PURE__ */ new Date(), words: wordList });
           for await (const buffer of imageGenerator) await session.send(import_koishi6.h.image(buffer, "image/png"));
         } catch (error) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-chat-analyse",
   "description": "强大而全面的聊天数据分析，支持统计命令，发言，消息类型，活跃度，支持发言排行和生成词云",
-  "version": "1.3.0",
+  "version": "1.3.1",
   "contributors": [
     "Yis_Rime <yis_rime@outlook.com>"
   ],

package/readme.md

@@ -37,23 +37,58 @@
 
 | 指令 | 别名 | 描述 | 选项 |
 | --- | --- | --- | --- |
-| `analyse.cmdstat` | 命令统计 | 查询命令使用情况 | `-u <user>` (指定用户), `-g <guild>` (指定群组), `-a` (全局), `-h` (分离子指令) |
-| `analyse.msgstat` | 发言统计 | 查询用户发言统计 | `-u <user>`, `-g <guild>`, `-a` (全局), `-t <type>` (指定消息类型) |
-| `analyse.rankstat` | 发言排行 | 查询指定时间内的发言排行 | `-g <guild>`, `-a` (全局), `-t <type>`, `-h <hours>` (默认24小时) |
-| `analyse.activity` | 活跃统计 | 查询周期性活跃度图表 | `-u <user>`, `-g <guild>`, `-a` (全局), `-d` (按天), `-h <hours>` (小时偏移) |
-| `analyse.wordcloud` | 生成词云 | 基于聊天记录生成词云图 | `-u <user>`, `-g <guild>`, `-a` (全局), `-h <hours>` (默认24小时) |
+| `analyse.cmdstat` | 命令统计 | 查询命令使用情况，展示方式根据选项变化 | `-u <user>`, `-g <guild>`, `-a` (全局), `-s` (分离子指令) |
+| `analyse.msgstat` | 发言统计 | 查询用户发言统计，展示方式根据选项变化 | `-u <user>`, `-g <guild>`, `-a` (全局), `-t <type>` (指定消息类型) |
+| `analyse.rankstat` | 发言排行 | 查询指定时间内的发言排行，展示方式根据选项变化 | `-u <user>`, `-g <guild>`, `-a` (全局), `-t <type>`, `-n <hours>`, `-o <hours>` |
+| `analyse.activity` | 活跃统计 | 查询周期性活跃度图表 | `-u <user>`, `-g <guild>`, `-a` (全局), `-d` (按天), `-n <units>`, `-o <units>` |
+| `analyse.wordcloud` | 生成词云 | 基于聊天记录生成词云图 | `-u <user>`, `-g <guild>`, `-t <hours>` (默认24小时) |
 | `analyse.whoatme` | 谁提及我 | 查看最近谁提及了您 | (无) |
 | `analyse.list` | 列出数据 | 列出已记录的频道和命令 | (无) |
 | `analyse.backup` | 备份数据 | 将所有数据备份为本地 JSON 文件 | (无) |
 | `analyse.restore` | 恢复数据 | 从本地 JSON 文件恢复数据 | (无) |
 | `analyse.clear` | 清除数据 | 根据条件精确清理数据 | `-t <table>`, `-g <guild>`, `-u <user>`, `-d <days>`, `-c <command>`, `-a` (全部) |
 
-**通用查询范围说明：**
+### 🔎 指令详解
 
-- 不带任何范围选项时，默认查询**当前群组**。
-- 使用 `-u <user>` 可指定用户 (支持 @某人)。
-- 使用 `-g <guild>` 可指定群组 ID。
-- 使用 `-a` 将忽略其他范围限制，查询**全局**数据。
+#### `analyse.cmdstat` (命令统计)
+
+- **`analyse cmdstat`**: 查询**当前群组**所有用户的命令统计。
+- **`analyse cmdstat -u @用户`**: 查询**指定用户**在**所有群组**的命令统计。
+- **`analyse cmdstat -g <群组ID>`**: 查询**指定群组**所有用户的命令统计。
+- **`analyse cmdstat -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的命令统计。
+- **`analyse cmdstat -a`**: 查询**全局**（所有用户+所有群组）的命令统计。
+- **选项 `-s`**: 分离展示子命令，不合并到主命令。
+
+#### `analyse.msgstat` (发言统计)
+
+- **`analyse msgstat`**: 查询**当前群组**的发言统计 (按**用户**展示)。
+- **`analyse msgstat -u @用户`**: 查询**指定用户**的发言统计 (按**群组**展示)。
+- **`analyse msgstat -g <群组ID>`**: 查询**指定群组**的发言统计 (按**用户**展示)。
+- **`analyse msgstat -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的发言统计 (按**消息类型**展示)。
+- **`analyse msgstat -a`**: 查询**全局**发言统计 (按**用户**展示)。
+- **选项 `-t <类型>`**: 筛选指定消息类型，不改变上述展示逻辑。
+
+#### `analyse.rankstat` (发言排行)
+
+- **`analyse rankstat`**: 查询**当前群组**的发言排行 (按**用户**排名)。
+- **`analyse rankstat -u @用户`**: 查询**指定用户**的发言排行 (按**群组**排名)。
+- **`analyse rankstat -g <群组ID>`**: 查询**指定群组**的发言排行 (按**用户**排名)。
+- **`analyse rankstat -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的发言排行 (按**消息类型**排名)。
+- **`analyse rankstat -a`**: 查询**全局**发言排行 (按**用户**排名)。
+- **选项 `-n <小时数>`**: 指定查询范围的时长，默认为 `24`。
+- **选项 `-o <小时数>`**: 指定查询结束时间的偏移量（从现在往前推的小时数），默认为 `0`。
+- **选项 `-t <类型>`**: 筛选指定消息类型，不改变上述展示逻辑。
+
+#### `analyse.activity` (活跃统计)
+
+- **`analyse activity`**: 查询**当前群组**的活跃度。
+- **`analyse activity -u @用户`**: 查询**指定用户**在**所有群组**的活跃度。
+- **`analyse activity -g <群组ID>`**: 查询**指定群组**的活跃度。
+- **`analyse activity -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的活跃度。
+- **`analyse activity -a`**: 查询**全局**活跃度。
+- **选项 `-n <数值>`**: 指定查询范围的时长，默认为 `24`。
+- **选项 `-o <数值>`**: 指定查询结束时间的偏移量，默认为 `0`。
+- **选项 `-d`**: 将 `-n` 和 `-o` 的单位从**小时**切换为**天**。
 
 ### 配置项
 
@@ -70,12 +105,12 @@
 - `enableMsgStat`: **启用消息统计**。 (默认: `true`)
 - `enableActivity`: **启用活跃统计**。 (默认: `true`)
 - `enableRankStat`: **启用发言排行**。 (默认: `true`)
-- `rankRetentionDays`: **排行保留天数**。发言排行数据的保留时长（天），`0` 为永久保留。 (默认: `31`)
+- `rankRetentionDays`: **排行保留天数**。发言排行数据的保留时长（天），`0` 为永久保留。 (默认: `180`)
 - `enableWhoAt`: **启用提及记录**。 (默认: `true`)
-- `atRetentionDays`: **提及保留天数**。`whoatme` 数据的保留时长（天），`0` 为永久保留。 (默认: `7`)
+- `atRetentionDays`: **提及保留天数**。`whoatme` 数据的保留时长（天），`0` 为永久保留。 (默认: `3`)
 
 #### 高级分析配置
 
 - `enableOriRecord`: **启用原始记录**。是否记录原始消息内容以供词云等功能使用。 (默认: `true`)
 - `enableWordCloud`: **启用词云生成**。 (默认: `true`)
-- `cacheRetentionDays`: **原始记录保留天数**。原始消息记录的保留时长（天），`0` 为永久保留。 (默认: `180`)
+- `cacheRetentionDays`: **原始记录保留天数**。原始消息记录的保留时长（天），`0` 为永久保留。 (默认: `30`)