koishi-plugin-chat-analyse 0.5.3 → 0.5.4

package/lib/Collector.d.ts

@@ -49,9 +49,7 @@ declare module 'koishi' {
 export declare class Collector {
     private ctx;
     private config;
-    /** @property FLUSH_INTERVAL - 内存缓存区定时刷入数据库的间隔（毫秒）。 */
     private static readonly FLUSH_INTERVAL;
-    /** @property BUFFER_THRESHOLD - 内存缓存区触发刷新的消息数量阈值。 */
     private static readonly BUFFER_THRESHOLD;
     private msgStatBuffer;
     private rankStatBuffer;

package/lib/Data.d.ts

@@ -0,0 +1,17 @@
+import { Context, Command } from 'koishi';
+/**
+ * @class Data
+ * @description 提供数据备份、恢复和清理等高级管理功能。
+ */
+export declare class Data {
+    private ctx;
+    private dataDir;
+    constructor(ctx: Context);
+    /**
+     * @public
+     * @method registerCommands
+     * @description 在主命令下注册所有数据管理相关的子命令。
+     * @param cmd - 主命令实例。
+     */
+    registerCommands(cmd: Command): void;
+}

package/lib/Renderer.d.ts

@@ -1,6 +1,4 @@
 import { Context } from 'koishi';
-/** 定义了渲染列表中单行数据的格式，是一个由字符串、数字或 `Date` 对象构成的数组。 */
-export type RenderListItem = (string | number | Date)[];
 /**
  * @interface ListRenderData
  * @description 定义了调用 `renderList` 方法所需的数据结构。
@@ -9,7 +7,7 @@ export interface ListRenderData {
     title: string;
     time: Date;
     total?: string | number;
-    list: RenderListItem[];
+    list: (string | number | Date)[][];
 }
 /**
  * @interface CircadianChartData
@@ -23,27 +21,57 @@ export interface CircadianChartData {
 }
 /**
  * @class Renderer
- * @description 负责将结构化的列表数据渲染为设计精美的 PNG 图片。
+ * @description 负责将结构化的数据渲染为设计精美的 PNG 图片。
  */
 export declare class Renderer {
     private ctx;
+    private readonly COMMON_STYLE;
     /**
-     * @private @readonly
-     * @property COMMON_STYLE - 存储所有卡片共享的基础 CSS 样式。
+     * @constructor
+     * @description Renderer 类的构造函数。
+     * @param {Context} ctx - Koishi 的插件上下文，用于访问 logger 和 puppeteer 服务。
      */
-    private readonly COMMON_STYLE;
     constructor(ctx: Context);
     /**
      * @private
      * @method generateFullHtml
-     * @description 将卡片内容和特定样式组合成一个完整的 HTML 文档。
-     * @param cardContent - 卡片部分的 HTML 字符串。
-     * @param specificStyles - 该卡片类型独有的 CSS 样式字符串。
-     * @returns 完整的 HTML 字符串。
+     * @description 将卡片内容和特定样式组合成一个完整的 HTML 文档，以便进行渲染。
+     * @param {string} cardContent - 卡片主体部分的 HTML 字符串。
+     * @param {string} specificStyles - 针对该卡片类型的特定 CSS 样式字符串。
+     * @returns {string} - 一个完整的、可被浏览器渲染的 HTML 字符串。
      */
     private generateFullHtml;
+    /**
+     * @private
+     * @method htmlToImage
+     * @description 使用 puppeteer 将给定的 HTML 字符串内容渲染成 PNG 图片的 Buffer。
+     * @param {string} fullHtmlContent - 完整的 HTML 内容字符串。
+     * @returns {Promise<Buffer | null>} - 成功时返回包含 PNG 图片数据的 Buffer，失败则返回 null。
+     */
     private htmlToImage;
+    /**
+     * @private
+     * @method formatDate
+     * @description 将 Date 对象格式化为易于理解的相对时间字符串（如“刚刚”，“5分钟前”）。
+     * @param {Date} date - 需要格式化的日期对象。
+     * @returns {string} - 格式化后的时间字符串。
+     */
     private formatDate;
+    /**
+     * @public
+     * @method renderList
+     * @description 将表格型数据渲染成一个或多个列表形式的图片。如果数据过多，会自动进行分页渲染。
+     * @param {ListRenderData} data - 包含标题、时间、总计和列表数据的对象。
+     * @param {string[]} [headers] - （可选）列表的表头数组。
+     * @returns {Promise<string | Buffer[]>} - 成功时返回包含图片 Buffer 的数组，失败或无数据时返回提示字符串。
+     */
     renderList(data: ListRenderData, headers?: string[]): Promise<string | Buffer[]>;
+    /**
+     * @public
+     * @method renderCircadianChart
+     * @description 将 24 小时制的活跃度数据渲染成一张柱状图图片。
+     * @param {CircadianChartData} data - 包含标题、时间、总计和 24 小时数据数组的对象。
+     * @returns {Promise<string | Buffer[]>} - 成功时返回包含图片 Buffer 的数组，失败或无数据时返回提示字符串。
+     */
     renderCircadianChart(data: CircadianChartData): Promise<string | Buffer[]>;
 }

package/lib/Stat.d.ts

@@ -16,10 +16,10 @@ export declare class Stat {
     constructor(ctx: Context, config: Config);
     /**
      * @public @method registerCommands
-     * @description 根据配置，动态地将子命令注册到主 `analyse` 命令下。
-     * @param analyse - 主 `analyse` 命令实例。
+     * @description 根据配置，动态地将子命令注册到主命令下。
+     * @param cmd - 主命令实例。
      */
-    registerCommands(analyse: Command): void;
+    registerCommands(cmd: Command): void;
     /**
      * @private @method parseQueryScope
      * @description 解析命令选项，转换为包含 UIDs 和描述性信息的统一查询范围对象。

package/lib/WhoAt.d.ts

@@ -0,0 +1,21 @@
+import { Context, Command } from 'koishi';
+import { Config } from './index';
+/**
+ * @class WhoAt
+ * @description 负责处理谁提及我相关功能，包括查询和定时清理。
+ */
+export declare class WhoAt {
+    private ctx;
+    private config;
+    /**
+     * @param ctx - Koishi 的插件上下文。
+     * @param config - 插件的配置对象。
+     */
+    constructor(ctx: Context, config: Config);
+    /**
+     * @public @method registerCommand
+     * @description 在主命令下注册子命令。
+     * @param cmd - 主命令实例。
+     */
+    registerCommand(cmd: Command): void;
+}

package/lib/index.d.ts

@@ -12,14 +12,14 @@ export interface Config {
     enableCmdStat: boolean;
     enableMsgStat: boolean;
     enableRankStat: boolean;
-    enableActivityStat: boolean;
+    enableActivity: boolean;
     enableOriRecord: boolean;
     enableWhoAt: boolean;
-    enableData: boolean;
+    enableDataIO: boolean;
     atRetentionDays: number;
     rankRetentionDays: number;
 }
-/** @description 插件的配置项定义，使用 Koishi Schema 构建。 */
+/** @description 插件的配置项定义 */
 export declare const Config: Schema<Config>;
 /**
  * @function apply

package/lib/index.js

@@ -50,11 +50,21 @@ var Collector = class _Collector {
     this.ctx = ctx;
     this.config = config;
     this.ctx.model.extend("analyse_user", { uid: "unsigned", channelId: "string", userId: "string", channelName: "string", userName: "string" }, { primary: "uid", autoInc: true, indexes: ["channelId", "userId"] });
-    this.ctx.model.extend("analyse_cmd", { uid: "unsigned", command: "string", count: "unsigned", timestamp: "timestamp" }, { primary: ["uid", "command"] });
-    this.ctx.model.extend("analyse_msg", { uid: "unsigned", type: "string", count: "unsigned", timestamp: "timestamp" }, { primary: ["uid", "type"] });
-    this.ctx.model.extend("analyse_rank", { uid: "unsigned", type: "string", count: "unsigned", timestamp: "timestamp" }, { primary: ["uid", "timestamp", "type"] });
-    if (this.config.enableOriRecord) this.ctx.model.extend("analyse_cache", { id: "unsigned", uid: "unsigned", content: "text", timestamp: "timestamp" }, { primary: "id", autoInc: true, indexes: ["uid", "timestamp"] });
-    if (this.config.enableWhoAt) this.ctx.model.extend("analyse_at", { id: "unsigned", uid: "unsigned", target: "string", content: "text", timestamp: "timestamp" }, { primary: "id", autoInc: true, indexes: ["target", "uid"] });
+    if (config.enableCmdStat) {
+      this.ctx.model.extend("analyse_cmd", { uid: "unsigned", command: "string", count: "unsigned", timestamp: "timestamp" }, { primary: ["uid", "command"] });
+    }
+    if (config.enableMsgStat) {
+      this.ctx.model.extend("analyse_msg", { uid: "unsigned", type: "string", count: "unsigned", timestamp: "timestamp" }, { primary: ["uid", "type"] });
+    }
+    if (config.enableRankStat || config.enableActivity) {
+      this.ctx.model.extend("analyse_rank", { uid: "unsigned", type: "string", count: "unsigned", timestamp: "timestamp" }, { primary: ["uid", "timestamp", "type"] });
+    }
+    if (this.config.enableOriRecord) {
+      this.ctx.model.extend("analyse_cache", { id: "unsigned", uid: "unsigned", content: "text", timestamp: "timestamp" }, { primary: "id", autoInc: true, indexes: ["uid", "timestamp"] });
+    }
+    if (this.config.enableWhoAt) {
+      this.ctx.model.extend("analyse_at", { id: "unsigned", uid: "unsigned", target: "string", content: "text", timestamp: "timestamp" }, { primary: "id", autoInc: true, indexes: ["target", "uid"] });
+    }
     ctx.on("message", (session) => this.onMessage(session));
     this.flushInterval = setInterval(() => this.flushBuffers(), _Collector.FLUSH_INTERVAL);
     ctx.on("dispose", () => {
@@ -65,11 +75,9 @@ var Collector = class _Collector {
   static {
     __name(this, "Collector");
   }
-  /** @property FLUSH_INTERVAL - 内存缓存区定时刷入数据库的间隔（毫秒）。 */
   static FLUSH_INTERVAL = import_koishi.Time.minute;
-  /** @property BUFFER_THRESHOLD - 内存缓存区触发刷新的消息数量阈值。 */
   static BUFFER_THRESHOLD = 60;
-  // 统一的数据缓冲区
+  // 数据缓冲区
   msgStatBuffer = /* @__PURE__ */ new Map();
   rankStatBuffer = /* @__PURE__ */ new Map();
   cmdStatBuffer = /* @__PURE__ */ new Map();
@@ -131,7 +139,7 @@ var Collector = class _Collector {
     if (!user) return;
     const { uid } = user;
     const messageTime = new Date(timestamp);
-    if (argv?.command) {
+    if (this.config.enableCmdStat && argv?.command) {
       const key = `${uid}:${argv.command.name}`;
       const entry = this.cmdStatBuffer.get(key) ?? { uid, command: argv.command.name, count: 0, timestamp: messageTime };
       entry.count++;
@@ -140,15 +148,19 @@ var Collector = class _Collector {
     }
     const hourStart = new Date(messageTime.getFullYear(), messageTime.getMonth(), messageTime.getDate(), messageTime.getHours());
     for (const type of new Set(elements.map((e) => e.type))) {
-      const msgKey = `${uid}:${type}`;
-      const msgEntry = this.msgStatBuffer.get(msgKey) ?? { uid, type, count: 0, timestamp: messageTime };
-      msgEntry.count++;
-      msgEntry.timestamp = messageTime;
-      this.msgStatBuffer.set(msgKey, msgEntry);
-      const rankKey = `${uid}:${hourStart.toISOString()}:${type}`;
-      const rankEntry = this.rankStatBuffer.get(rankKey) ?? { uid, timestamp: hourStart, type, count: 0 };
-      rankEntry.count++;
-      this.rankStatBuffer.set(rankKey, rankEntry);
+      if (this.config.enableMsgStat) {
+        const msgKey = `${uid}:${type}`;
+        const msgEntry = this.msgStatBuffer.get(msgKey) ?? { uid, type, count: 0, timestamp: messageTime };
+        msgEntry.count++;
+        msgEntry.timestamp = messageTime;
+        this.msgStatBuffer.set(msgKey, msgEntry);
+      }
+      if (this.config.enableRankStat || this.config.enableActivity) {
+        const rankKey = `${uid}:${hourStart.toISOString()}:${type}`;
+        const rankEntry = this.rankStatBuffer.get(rankKey) ?? { uid, timestamp: hourStart, type, count: 0 };
+        rankEntry.count++;
+        this.rankStatBuffer.set(rankKey, rankEntry);
+      }
     }
     if (this.config.enableWhoAt) {
       const sanitizedContent = this.sanitizeContent(elements.filter((e) => e.type !== "at"));
@@ -210,63 +222,126 @@ var import_koishi3 = require("koishi");
 // src/Renderer.ts
 var import_koishi2 = require("koishi");
 var Renderer = class {
+  /**
+   * @constructor
+   * @description Renderer 类的构造函数。
+   * @param {Context} ctx - Koishi 的插件上下文，用于访问 logger 和 puppeteer 服务。
+   */
   constructor(ctx) {
     this.ctx = ctx;
   }
   static {
     __name(this, "Renderer");
   }
-  /**
-   * @private @readonly
-   * @property COMMON_STYLE - 存储所有卡片共享的基础 CSS 样式。
-   */
-  COMMON_STYLE = `:root{--card-bg:#fff;--text-color:#111827;--header-color:#111827;--sub-text-color:#6b7280;--border-color:#e5e7eb;--accent-color:#4a6ee0;--chip-bg:#f3f4f6;--stripe-bg:#f9fafb;--gold:#f59e0b;--silver:#9ca3af;--bronze:#a16207}body{display:inline-block;font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,'Helvetica Neue',Arial,sans-serif;background:0 0;margin:0;padding:8px;-webkit-font-smoothing:antialiased}.container{display:inline-block;background:var(--card-bg);border-radius:12px;padding:0;overflow:hidden;box-shadow:0 2px 4px rgba(0,0,0,.05)}.header{padding:10px 14px}.header-table{border-collapse:collapse;width:100%}.header-table-left,.header-table-right{width:1%;white-space:nowrap}.header-table-left{text-align:left}.header-table-center{text-align:center}.header-table-right{text-align:right}.title-text{font-size:18px;font-weight:600;color:var(--header-color);margin:0}.stat-chip,.time-label{display:inline-flex;align-items:baseline;padding:4px 8px;border-radius:8px;background:var(--chip-bg);font-size:13px;color:var(--sub-text-color)}.stat-chip span{font-weight:600;color:var(--text-color);margin-left:4px}`;
+  COMMON_STYLE = `
+    :root {
+      --card-bg: #fff; --text-color: #111827; --header-color: #111827;
+      --sub-text-color: #6b7280; --border-color: #e5e7eb; --accent-color: #4a6ee0;
+      --chip-bg: #f3f4f6; --stripe-bg: #f9fafb; --gold: #f59e0b;
+      --silver: #9ca3af; --bronze: #a16207;
+    }
+    body {
+      display: inline-block; font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI',
+      Roboto, 'Helvetica Neue', Arial, sans-serif;
+      background: transparent; margin: 0; padding: 8px;
+      -webkit-font-smoothing: antialiased;
+    }
+    .container {
+      display: inline-block; background: var(--card-bg); border-radius: 12px;
+      padding: 0; overflow: hidden; box-shadow: 0 4px 6px rgba(0,0,0,.05);
+    }
+    .header {
+      padding: 12px 16px;
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      border-bottom: 1px solid var(--border-color);
+    }
+    .title-text {
+      font-size: 18px; font-weight: 600; color: var(--header-color);
+      margin: 0; text-align: center;
+    }
+    .stat-chip, .time-label {
+      display: inline-flex; align-items: baseline; padding: 4px 8px;
+      border-radius: 8px; background: var(--chip-bg);
+      font-size: 13px; color: var(--sub-text-color);
+      white-space: nowrap;
+    }
+    .stat-chip span {
+      font-weight: 600; color: var(--text-color); margin-left: 4px;
+    }
+  `;
   /**
    * @private
    * @method generateFullHtml
-   * @description 将卡片内容和特定样式组合成一个完整的 HTML 文档。
-   * @param cardContent - 卡片部分的 HTML 字符串。
-   * @param specificStyles - 该卡片类型独有的 CSS 样式字符串。
-   * @returns 完整的 HTML 字符串。
+   * @description 将卡片内容和特定样式组合成一个完整的 HTML 文档，以便进行渲染。
+   * @param {string} cardContent - 卡片主体部分的 HTML 字符串。
+   * @param {string} specificStyles - 针对该卡片类型的特定 CSS 样式字符串。
+   * @returns {string} - 一个完整的、可被浏览器渲染的 HTML 字符串。
    */
   generateFullHtml(cardContent, specificStyles) {
     return `<!DOCTYPE html>
       <html>
-      <head>
-        <meta charset="UTF-8">
-        <style>${this.COMMON_STYLE}${specificStyles}</style>
-      </head>
-      <body>
-        ${cardContent}
-      </body>
+        <head>
+          <meta charset="UTF-8">
+          <style>${this.COMMON_STYLE}${specificStyles}</style>
+        </head>
+        <body>
+          ${cardContent}
+        </body>
       </html>`;
   }
+  /**
+   * @private
+   * @method htmlToImage
+   * @description 使用 puppeteer 将给定的 HTML 字符串内容渲染成 PNG 图片的 Buffer。
+   * @param {string} fullHtmlContent - 完整的 HTML 内容字符串。
+   * @returns {Promise<Buffer | null>} - 成功时返回包含 PNG 图片数据的 Buffer，失败则返回 null。
+   */
   async htmlToImage(fullHtmlContent) {
     const page = await this.ctx.puppeteer.page();
     try {
-      await page.setViewport({ width: 720, height: 1080, deviceScaleFactor: 2 });
+      await page.setViewport({ width: 720, height: 10, deviceScaleFactor: 2 });
       await page.setContent(fullHtmlContent, { waitUntil: "networkidle0" });
-      const dimensions = await page.evaluate(() => ({ width: document.body.scrollWidth, height: document.body.scrollHeight }));
-      await page.setViewport({ ...dimensions, deviceScaleFactor: 2 });
-      return await page.screenshot({ type: "png", fullPage: true, omitBackground: true });
+      const { width, height } = await page.evaluate(() => ({
+        width: document.body.scrollWidth,
+        height: document.body.scrollHeight
+      }));
+      await page.setViewport({ width, height, deviceScaleFactor: 2 });
+      return await page.screenshot({ type: "png", omitBackground: true });
     } catch (error) {
       this.ctx.logger.error("图片渲染失败:", error);
       return null;
     } finally {
-      if (page) await page.close().catch((e) => this.ctx.logger.error("关闭页面失败:", e));
+      await page.close().catch((e) => this.ctx.logger.error("关闭页面失败:", e));
     }
   }
+  /**
+   * @private
+   * @method formatDate
+   * @description 将 Date 对象格式化为易于理解的相对时间字符串（如“刚刚”，“5分钟前”）。
+   * @param {Date} date - 需要格式化的日期对象。
+   * @returns {string} - 格式化后的时间字符串。
+   */
   formatDate(date) {
     if (!date) return "未知";
     const diff = Date.now() - date.getTime();
     if (diff < import_koishi2.Time.minute) return "刚刚";
-    if (diff > 365 * import_koishi2.Time.day) return date.toLocaleDateString("zh-CN").replace(/\//g, "-");
-    const timeUnits = [["月", 30 * import_koishi2.Time.day], ["天", import_koishi2.Time.day], ["时", import_koishi2.Time.hour], ["分", import_koishi2.Time.minute]];
-    for (const [unit, ms] of timeUnits) {
+    if (diff > 365 * import_koishi2.Time.day) return date.toLocaleDateString("zh-CN");
+    const units = [["月", 30 * import_koishi2.Time.day], ["天", import_koishi2.Time.day], ["小时", import_koishi2.Time.hour], ["分钟", import_koishi2.Time.minute]];
+    for (const [unit, ms] of units) {
       if (diff >= ms) return `${Math.floor(diff / ms)}${unit}前`;
     }
     return "刚刚";
   }
+  /**
+   * @public
+   * @method renderList
+   * @description 将表格型数据渲染成一个或多个列表形式的图片。如果数据过多，会自动进行分页渲染。
+   * @param {ListRenderData} data - 包含标题、时间、总计和列表数据的对象。
+   * @param {string[]} [headers] - （可选）列表的表头数组。
+   * @returns {Promise<string | Buffer[]>} - 成功时返回包含图片 Buffer 的数组，失败或无数据时返回提示字符串。
+   */
   async renderList(data, headers) {
     const { title, time, list } = data;
     if (!list?.length) return "暂无数据可供渲染";
@@ -278,43 +353,106 @@ var Renderer = class {
     const renderCell = /* @__PURE__ */ __name((cell, i) => {
       const headerText = headers?.[i] || "";
       if (headerText.includes("占比")) {
-        const percentValue = parseFloat(String(cell).replace("%", ""));
-        return `<td class="percent-cell"><div class="percent-bar" style="width: ${percentValue}%;"></div><span class="percent-text">${cell}</span></td>`;
+        return `<td class="percent-cell"><div class="percent-bar" style="width: ${String(cell)};"></div><span class="percent-text">${cell}</span></td>`;
       }
       if (cell instanceof Date) return `<td class="date-cell">${this.formatDate(cell)}</td>`;
       if (typeof cell === "number") return `<td class="count-cell">${cell.toLocaleString()}</td>`;
       return `<td class="name-cell">${String(cell)}</td>`;
     }, "renderCell");
-    const totalPages = Math.ceil(totalItems / CHUNK_SIZE);
-    const listStyles = `.table-container{border-top:1px solid var(--border-color)}.main-table{border-collapse:collapse;width:100%}.main-table th,.main-table td{padding:8px 14px;vertical-align:middle}.main-table th{font-size:12px;font-weight:500;color:var(--sub-text-color);text-transform:uppercase;letter-spacing:.05em;background:var(--stripe-bg)}.main-table td{font-size:14px;color:var(--text-color)}.main-table tbody tr:nth-child(even){background-color:var(--stripe-bg)}.main-table .name-cell,.main-table .name-header{text-align:left}.main-table .rank-cell,.main-table .count-cell,.main-table .date-cell,.main-table .percent-cell,.main-table .header-right-align{text-align:right;white-space:nowrap;width:1%;font-variant-numeric:tabular-nums}.name-cell{font-weight:500}.rank-cell{font-weight:500;color:var(--sub-text-color)}.count-cell{font-weight:600;color:var(--accent-color)}.date-cell{color:var(--sub-text-color)}.rank-gold,.rank-silver,.rank-bronze{font-weight:600}.rank-gold{color:var(--gold)!important}.rank-silver{color:var(--silver)!important}.rank-bronze{color:var(--bronze)!important}.percent-cell{position:relative}.percent-bar{position:absolute;top:0;right:0;height:100%;background-color:var(--accent-color);opacity:.15}.percent-text{position:relative;z-index:1}`;
+    const listStyles = `
+      .table-container { padding: 0; }
+      .main-table { border-collapse: collapse; width: 100%; }
+      .main-table th, .main-table td { padding: 9px 16px; vertical-align: middle; text-align: left; }
+      .main-table thead { border-bottom: 1px solid var(--border-color); }
+      .main-table th { font-size: 12px; font-weight: 500; color: var(--sub-text-color); text-transform: uppercase; }
+      .main-table td { font-size: 14px; color: var(--text-color); }
+      .main-table tbody tr:nth-child(even) { background-color: var(--stripe-bg); }
+      .rank-cell, .count-cell, .date-cell, .percent-cell { text-align: right; white-space: nowrap; width: 1%; font-variant-numeric: tabular-nums; }
+      .name-cell { font-weight: 500; }
+      .rank-cell { font-weight: 600; color: var(--sub-text-color); }
+      .count-cell { font-weight: 600; color: var(--accent-color); }
+      .rank-gold, .rank-silver, .rank-bronze { font-weight: 700; }
+      .rank-gold { color: var(--gold) !important; }
+      .rank-silver { color: var(--silver) !important; }
+      .rank-bronze { color: var(--bronze) !important; }
+      .percent-cell { position: relative; padding-right: 20px; }
+      .percent-bar { position: absolute; top: 50%; right: 0; transform: translateY(-50%); height: 6px; background-color: var(--accent-color); opacity: .2; border-radius: 3px; }
+      .percent-text { position: relative; z-index: 1; }
+    `;
     for (let i = 0; i < totalItems; i += CHUNK_SIZE) {
       const chunk = list.slice(i, i + CHUNK_SIZE);
       const pageNum = Math.floor(i / CHUNK_SIZE) + 1;
-      const pageTitle = totalPages > 1 ? `${title} (第 ${pageNum}/${totalPages} 页)` : title;
-      const tableRowsHtml = chunk.map((row, index) => {
+      const pageTitle = totalItems > CHUNK_SIZE ? `${title} (第 ${pageNum}/${Math.ceil(totalItems / CHUNK_SIZE)} 页)` : title;
+      const cardHtml = `
+        <div class="container">
+          <div class="header">
+            <div class="stat-chip">总计: <span>${typeof totalCount === "number" ? totalCount.toLocaleString() : totalCount}</span></div>
+            <h1 class="title-text">${pageTitle}</h1>
+            <div class="time-label">${time.toLocaleString("zh-CN", { hour12: false })}</div>
+          </div>
+          <div class="table-container">
+            <table class="main-table">
+              ${headers?.length ? `
+                <thead>
+                  <tr>
+                    <th class="rank-cell">#</th>
+                    ${headers.map((h4) => `<th>${h4}</th>`).join("")}
+                  </tr>
+                </thead>` : ""}
+              <tbody>
+                ${chunk.map((row, index) => {
         const rank = i + index + 1;
         const rankClass = rank === 1 ? "rank-gold" : rank === 2 ? "rank-silver" : rank === 3 ? "rank-bronze" : "";
         return `<tr><td class="rank-cell ${rankClass}">${rank}</td>${row.map(renderCell).join("")}</tr>`;
-      }).join("");
-      const tableHeadHtml = headers?.length ? `<thead><tr><th class="rank-cell">#</th>${headers.map((h4) => `<th class="${typeof list[0]?.[headers.indexOf(h4)] === "string" ? "name-header" : "header-right-align"}">${h4}</th>`).join("")}</tr></thead>` : "";
-      const cardHtml = `<div class="container"><div class="header"><table class="header-table"><tr><td class="header-table-left"><div class="stat-chip">总计: <span>${typeof totalCount === "number" ? totalCount.toLocaleString() : totalCount}</span></div></td><td class="header-table-center"><h1 class="title-text">${pageTitle}</h1></td><td class="header-table-right"><div class="time-label">${time.toLocaleString("zh-CN", { hour12: false }).replace(/\//g, "-")}</div></td></tr></table></div><div class="table-container"><table class="main-table">${tableHeadHtml}<tbody>${tableRowsHtml}</tbody></table></div></div>`;
+      }).join("")}
+              </tbody>
+            </table>
+          </div>
+        </div>`;
       const fullHtml = this.generateFullHtml(cardHtml, listStyles);
       const imageBuffer = await this.htmlToImage(fullHtml);
       if (imageBuffer) imageBuffers.push(imageBuffer);
     }
     return imageBuffers.length > 0 ? imageBuffers : "图片渲染失败";
   }
+  /**
+   * @public
+   * @method renderCircadianChart
+   * @description 将 24 小时制的活跃度数据渲染成一张柱状图图片。
+   * @param {CircadianChartData} data - 包含标题、时间、总计和 24 小时数据数组的对象。
+   * @returns {Promise<string | Buffer[]>} - 成功时返回包含图片 Buffer 的数组，失败或无数据时返回提示字符串。
+   */
   async renderCircadianChart(data) {
     const { title, time, total, data: hourlyCounts } = data;
     if (!hourlyCounts || hourlyCounts.every((c) => c === 0)) return "暂无数据可供渲染";
     const maxCount = Math.max(...hourlyCounts, 1);
-    const barsHtml = hourlyCounts.map((count, hour) => {
-      const barHeight = count / maxCount * 100;
-      const isPeak = count > 0 && count === maxCount;
-      return `<div class="bar-wrapper"><div class="bar-value ${count === 0 ? "hidden" : ""}">${count}</div><div class="bar-container"><div class="bar ${isPeak ? "peak" : ""}" style="height: ${barHeight}%;"></div></div><div class="bar-label">${hour}</div></div>`;
-    }).join("");
-    const cardHtml = `<div class="container"><div class="header"><table class="header-table"><tr><td class="header-table-left"><div class="stat-chip">总计: <span>${typeof total === "number" ? total.toLocaleString() : total}</span></div></td><td class="header-table-center"><h1 class="title-text">${title}</h1></td><td class="header-table-right"><div class="time-label">${time.toLocaleString("zh-CN", { hour12: false }).replace(/\//g, "-")}</div></td></tr></table></div><div class="chart-container">${barsHtml}</div></div>`;
-    const chartStyles = `.chart-container{display:flex;align-items:flex-end;gap:4px;height:180px;padding:30px 15px 10px;border-top:1px solid var(--border-color)}.bar-wrapper{flex:1;text-align:center;display:flex;flex-direction:column;height:100%;justify-content:flex-end}.bar-value{font-size:11px;color:var(--sub-text-color);height:16px;line-height:16px;font-weight:500}.bar-value.hidden{visibility:hidden}.bar-container{flex-grow:1;display:flex;align-items:flex-end;width:100%}.bar{width:100%;background-color:var(--accent-color);opacity:.7;border-radius:3px 3px 0 0;transition:height .3s ease-out}.bar.peak{opacity:1;background-color:var(--gold)!important}.bar-label{font-size:10px;color:var(--sub-text-color);margin-top:4px;height:12px}`;
+    const chartStyles = `
+      .chart-container { display: flex; align-items: flex-end; gap: 4px; height: 180px; padding: 30px 15px 10px; }
+      .bar-wrapper { flex: 1; text-align: center; display: flex; flex-direction: column; justify-content: flex-end; height: 100%; }
+      .bar-value { font-size: 11px; color: var(--sub-text-color); height: 16px; line-height: 16px; font-weight: 500; visibility: ${maxCount > 50 ? "hidden" : "visible"}; }
+      .bar-container { flex-grow: 1; display: flex; align-items: flex-end; width: 100%; }
+      .bar { width: 100%; background-color: var(--accent-color); opacity: .7; border-radius: 3px 3px 0 0; transition: height .3s ease-out; }
+      .bar.peak { opacity: 1; background-color: var(--gold); }
+      .bar-label { font-size: 10px; color: var(--sub-text-color); margin-top: 4px; height: 12px; }
+    `;
+    const cardHtml = `
+      <div class="container">
+        <div class="header">
+          <div class="stat-chip">总计: <span>${typeof total === "number" ? total.toLocaleString() : total}</span></div>
+          <h1 class="title-text">${title}</h1>
+          <div class="time-label">${time.toLocaleString("zh-CN", { hour12: false })}</div>
+        </div>
+        <div class="chart-container">
+          ${hourlyCounts.map((count, hour) => `
+            <div class="bar-wrapper">
+              <div class="bar-value">${count > 0 ? count : ""}</div>
+              <div class="bar-container">
+                <div class="bar ${count === maxCount ? "peak" : ""}" style="height: ${count / maxCount * 100}%;"></div>
+              </div>
+              <div class="bar-label">${hour}</div>
+            </div>`).join("")}
+        </div>
+      </div>`;
     const fullHtml = this.generateFullHtml(cardHtml, chartStyles);
     const imageBuffer = await this.htmlToImage(fullHtml);
     return imageBuffer ? [imageBuffer] : "图片渲染失败";
@@ -331,10 +469,10 @@ var Stat = class {
     this.ctx = ctx;
     this.config = config;
     this.renderer = new Renderer(ctx);
-    if (this.config.rankRetentionDays > 0) {
+    if (this.config.enableRankStat && this.config.rankRetentionDays > 0) {
       this.ctx.cron("0 0 * * *", async () => {
         const cutoffDate = new Date(Date.now() - this.config.rankRetentionDays * import_koishi3.Time.day);
-        await this.ctx.database.remove("analyse_rank", { timestamp: { $lt: cutoffDate } }).catch((e) => this.ctx.logger.error("清理发言排行历史记录失败:", e));
+        await this.ctx.database.remove("analyse_rank", { timestamp: { $lt: cutoffDate } }).catch((e) => this.ctx.logger.error("清理发言排行记录失败:", e));
       });
     }
   }
@@ -344,10 +482,10 @@ var Stat = class {
   renderer;
   /**
    * @public @method registerCommands
-   * @description 根据配置，动态地将子命令注册到主 `analyse` 命令下。
-   * @param analyse - 主 `analyse` 命令实例。
+   * @description 根据配置，动态地将子命令注册到主命令下。
+   * @param cmd - 主命令实例。
    */
-  registerCommands(analyse) {
+  registerCommands(cmd) {
     const createHandler = /* @__PURE__ */ __name((handler) => {
       return async ({ session, options }) => {
         const scope = await this.parseQueryScope(session, options);
@@ -355,102 +493,73 @@ var Stat = class {
         try {
           const result = await handler(scope, options);
           if (typeof result === "string") return result;
-          if (Array.isArray(result)) {
-            if (result.length === 0) return "图片渲染失败";
+          if (Array.isArray(result) && result.length > 0) {
             for (const buffer of result) await session.sendQueued(import_koishi3.h.image(buffer, "image/png"));
             return;
           }
-          if (Buffer.isBuffer(result)) return import_koishi3.h.image(result, "image/png");
         } catch (error) {
           this.ctx.logger.error("渲染统计图片失败:", error);
-          return "渲染统计图片失败";
+          return "图片渲染失败";
         }
       };
     }, "createHandler");
-    if (this.config.enableCmdStat) analyse.subcommand(".cmd", "命令使用统计").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("all", "-a 全局").action(createHandler(async (scope) => {
-      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();
-      if (stats.length === 0) return "暂无匹配指令统计数据";
-      const total = stats.reduce((sum, record) => sum + record.count, 0);
-      const list = stats.map((item) => [item.command, item.count, item.lastUsed]);
-      const title = await this.generateTitle(scope.scopeDesc, { main: "命令使用" });
-      return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list }, ["命令", "次数", "最后使用"]);
-    }));
-    if (this.config.enableMsgStat) analyse.subcommand(".msg", "消息发送统计").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.type;
-      if (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]));
-        const stats = await this.ctx.database.select("analyse_msg").where({ uid: { $in: scope.uids }, type }).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 `暂无“${type}”类型消息数据`;
-        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 this.generateTitle(scope.scopeDesc, { main: "消息", subtype: type });
-        return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list }, ["用户", "条数", "最后发言"]);
-      } else {
+    if (this.config.enableCmdStat) {
+      cmd.subcommand("cmdstat", "命令统计").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("all", "-a 全局").action(createHandler(async (scope) => {
+        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();
+        if (stats.length === 0) return "暂无统计数据";
+        const total = stats.reduce((sum, record) => sum + record.count, 0);
+        const list = stats.map((item) => [item.command, item.count, item.lastUsed]);
+        const title = await this.generateTitle(scope.scopeDesc, { main: "命令" });
+        return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list }, ["命令", "次数", "最后使用"]);
+      }));
+    }
+    if (this.config.enableMsgStat) {
+      cmd.subcommand("msgstat", "发言统计").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]));
-        const stats = await this.ctx.database.select("analyse_msg").where({ uid: { $in: scope.uids } }).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 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 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 this.generateTitle(scope.scopeDesc, { main: "消息发送" });
-        return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list }, ["用户", "总计发言", "最后发言"]);
-      }
-    }));
-    if (this.config.enableRankStat) analyse.subcommand(".rank", "用户发言排行").option("guild", "-g <guildId:string> 指定群组").option("type", "-t <type:string> 指定类型").option("hours", "-h <hours:number> 指定时长", { fallback: 24 }).option("all", "-a 全局").action(async ({ session, options }) => {
-      const guildId = options.all ? void 0 : options.guild || session.guildId;
-      if (!guildId && !options.all) return "请指定群组或查询全局";
-      try {
+        const title = await this.generateTitle(scope.scopeDesc, { main: "发言", subtype: type });
+        const headers = type ? ["用户", "条数", "最后发言"] : ["用户", "总计发言", "最后发言"];
+        return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list }, headers);
+      }));
+    }
+    if (this.config.enableRankStat) {
+      cmd.subcommand("rankstat", "发言排行").option("guild", "-g <guildId:string> 指定群组").option("type", "-t <type:string> 指定类型").option("hours", "-h <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 baseQuery = { timestamp: { $gte: since } };
-        if (type) baseQuery.type = type;
-        const uidsInScope = guildId ? (await this.ctx.database.get("analyse_user", { channelId: guildId }, ["uid"])).map((u) => u.uid) : void 0;
-        if (guildId && uidsInScope.length === 0) return "暂无指定时段内发言记录";
-        if (uidsInScope) baseQuery.uid = { $in: uidsInScope };
-        const rankStats = await this.ctx.database.select("analyse_rank").where(baseQuery).groupBy("uid", { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count") }).orderBy("count", "desc").execute();
-        if (rankStats.length === 0) return "暂无指定时段内发言记录";
-        const uids = rankStats.map((s) => s.uid);
-        const users = await this.ctx.database.get("analyse_user", { uid: { $in: uids } }, ["uid", "userName"]);
+        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"]);
         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 this.generateTitle({ guildId }, { main: "发言排行", timeRange: hours, subtype: type });
-        const result = await this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list: listWithPercentage }, ["用户", "总计发言", "占比"]);
-        if (typeof result === "string") return result;
-        if (Array.isArray(result)) {
-          if (result.length === 0) return "图片渲染失败";
-          for (const buffer of result) await session.sendQueued(import_koishi3.h.image(buffer, "image/png"));
-          return;
-        }
-      } catch (error) {
-        this.ctx.logger.error("渲染发言排行图片失败:", error);
-        return "渲染发言排行图片失败";
-      }
-    });
-    if (this.config.enableActivityStat) analyse.subcommand(".activity", "用户活跃分析").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("all", "-a 全局").action(createHandler(async (scope) => {
-      const hourlyStats = await this.ctx.database.select("analyse_rank").where({ uid: { $in: scope.uids } }).groupBy(
-        ["timestamp"],
-        { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count") }
-      ).execute();
-      if (hourlyStats.length === 0) return "暂无消息数据";
-      const hourlyCounts = Array(24).fill(0);
-      let totalMessages = 0;
-      hourlyStats.forEach((stat) => {
-        const hour = stat.timestamp.getHours();
-        hourlyCounts[hour] = stat.count;
-        totalMessages += stat.count;
-      });
-      const title = await this.generateTitle(scope.scopeDesc, { main: "活跃分析" });
-      const result = await this.renderer.renderCircadianChart({
-        title,
-        time: /* @__PURE__ */ new Date(),
-        total: totalMessages,
-        data: hourlyCounts
-      });
-      return result;
-    }));
+        const title = await this.generateTitle(scope.scopeDesc, { main: "发言排行", timeRange: hours, subtype: type });
+        return this.renderer.renderList({ title, time: /* @__PURE__ */ new Date(), total, list: listWithPercentage }, ["用户", "总计发言", "占比"]);
+      }));
+    }
+    if (this.config.enableActivity) {
+      cmd.subcommand("activity", "活跃统计").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").option("all", "-a 全局").action(createHandler(async (scope) => {
+        const hourlyStats = await this.ctx.database.select("analyse_rank").where({ uid: { $in: scope.uids } }).groupBy(["timestamp"], { count: /* @__PURE__ */ __name((row) => import_koishi3.$.sum(row.count), "count") }).execute();
+        if (hourlyStats.length === 0) return "暂无统计数据";
+        const hourlyCounts = Array(24).fill(0);
+        let totalMessages = 0;
+        hourlyStats.forEach((stat) => {
+          hourlyCounts[stat.timestamp.getHours()] += stat.count;
+          totalMessages += stat.count;
+        });
+        const title = await this.generateTitle(scope.scopeDesc, { main: "活跃" });
+        return this.renderer.renderCircadianChart({ title, time: /* @__PURE__ */ new Date(), total: totalMessages, data: hourlyCounts });
+      }));
+    }
   }
   /**
    * @private @method parseQueryScope
@@ -463,12 +572,13 @@ var Stat = class {
     const scopeDesc = { guildId: options.guild, userId: void 0 };
     if (options.user) scopeDesc.userId = import_koishi3.h.select(options.user, "at")[0]?.attrs.id ?? options.user.trim();
     if (!options.all && !scopeDesc.guildId && !scopeDesc.userId) scopeDesc.guildId = session.guildId;
-    if (!options.all && !scopeDesc.guildId) return { error: "请指定群组或查询全局", scopeDesc };
+    if (!options.all && !scopeDesc.guildId && !scopeDesc.userId) return { error: "请指定查询范围", scopeDesc };
     const query = {};
     if (scopeDesc.guildId) query.channelId = scopeDesc.guildId;
     if (scopeDesc.userId) query.userId = scopeDesc.userId;
+    if (Object.keys(query).length === 0) return { uids: void 0, scopeDesc };
     const users = await this.ctx.database.get("analyse_user", query, ["uid"]);
-    if (users.length === 0) return { error: "在指定范围内未找到任何记录", scopeDesc };
+    if (users.length === 0) return { error: "暂无统计数据", scopeDesc };
     return { uids: users.map((u) => u.uid), scopeDesc };
   }
   /**
@@ -477,19 +587,25 @@ var Stat = class {
    * @returns 生成的标题字符串。
    */
   async generateTitle(scopeDesc, options) {
-    let scopeText = "全局";
+    let guildName = "", userName = "", scopeText = "全局";
     if (scopeDesc.guildId) {
       const [guild] = await this.ctx.database.get("analyse_user", { channelId: scopeDesc.guildId }, ["channelName"]);
-      scopeText = guild?.channelName || scopeDesc.guildId;
+      guildName = guild?.channelName || scopeDesc.guildId;
     }
     if (scopeDesc.userId) {
       const [user] = await this.ctx.database.get("analyse_user", { userId: scopeDesc.userId }, ["userName"]);
-      const userName = user?.userName || scopeDesc.userId;
-      scopeText = scopeDesc.guildId ? `${userName} 在 ${scopeText}` : `${userName} 的全局`;
+      userName = user?.userName || scopeDesc.userId;
     }
     const typeText = options.subtype ? `“${options.subtype}”` : "";
-    if (options.main.includes("排行")) return `${scopeText}${options.timeRange}小时${typeText}消息排行`;
-    return `${scopeText}${typeText}${options.main}统计`;
+    const mainText = options.main;
+    if (mainText.includes("排行")) {
+      scopeText = guildName || "全局";
+      return `${options.timeRange}小时${scopeText}${typeText}${mainText}`;
+    }
+    if (userName && guildName) scopeText = `${guildName} ${userName}`;
+    else if (userName) scopeText = userName;
+    else if (guildName) scopeText = guildName;
+    return `${scopeText}${typeText}${mainText}统计`;
   }
 };
 
@@ -503,10 +619,10 @@ var WhoAt = class {
   constructor(ctx, config) {
     this.ctx = ctx;
     this.config = config;
-    if (this.config.atRetentionDays > 0) {
+    if (this.config.enableWhoAt && this.config.atRetentionDays > 0) {
       this.ctx.cron("0 0 * * *", async () => {
         const cutoffDate = new Date(Date.now() - this.config.atRetentionDays * import_koishi4.Time.day);
-        await this.ctx.database.remove("analyse_at", { timestamp: { $lt: cutoffDate } }).catch((e) => this.ctx.logger.error("清理 @ 历史记录失败:", e));
+        await this.ctx.database.remove("analyse_at", { timestamp: { $lt: cutoffDate } }).catch((e) => this.ctx.logger.error("清理提及记录失败:", e));
       });
     }
   }
@@ -515,11 +631,11 @@ var WhoAt = class {
   }
   /**
    * @public @method registerCommand
-   * @description 在主 `analyse` 命令下注册 `whoatme` 子命令。
-   * @param analyse - 主 `analyse` 命令实例。
+   * @description 在主命令下注册子命令。
+   * @param cmd - 主命令实例。
    */
-  registerCommand(analyse) {
-    analyse.subcommand(".whoatme", "谁@我").action(async ({ session }) => {
+  registerCommand(cmd) {
+    cmd.subcommand("whoatme", "谁提及我").usage("查看最近提及我的消息，不分群组。").action(async ({ session }) => {
       if (!session.userId) return "无法获取用户信息";
       try {
         const records = await this.ctx.database.get("analyse_at", { target: session.userId }, {
@@ -531,7 +647,7 @@ var WhoAt = class {
         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 }]));
         const messageElements = records.map((record) => {
-          const senderInfo = userInfoMap.get(record.uid) ?? { name: "未知用户", id: "0" };
+          const senderInfo = userInfoMap.get(record.uid);
           return (0, import_koishi4.h)("message", {}, [
             (0, import_koishi4.h)("author", { userId: senderInfo.id, nickname: senderInfo.name }),
             import_koishi4.h.text(record.content)
@@ -539,7 +655,7 @@ var WhoAt = class {
         });
         return (0, import_koishi4.h)("message", { forward: true }, messageElements);
       } catch (error) {
-        this.ctx.logger.error("查询 @ 记录失败:", error);
+        this.ctx.logger.error("查询提及记录失败:", error);
         return "查询失败，请稍后重试";
       }
     });
@@ -564,11 +680,11 @@ var Data = class {
   /**
    * @public
    * @method registerCommands
-   * @description 在 `analyse` 命令下注册所有数据管理相关的子命令 (`.backup`, `.restore`, `.clear`, `.list`)。
-   * @param analyse - 主 `analyse` 命令实例。
+   * @description 在主命令下注册所有数据管理相关的子命令。
+   * @param cmd - 主命令实例。
    */
-  registerCommands(analyse) {
-    analyse.subcommand(".backup", "备份统计数据", { authority: 4 }).action(async () => {
+  registerCommands(cmd) {
+    cmd.subcommand(".backup", "备份数据", { authority: 4 }).usage("将所有统计数据导出为 JSON 文件并保存到本地。").action(async () => {
       try {
         await fs.mkdir(this.dataDir, { recursive: true });
         const allUsers = await this.ctx.database.get("analyse_user", {});
@@ -595,7 +711,7 @@ var Data = class {
         return "数据备份失败";
       }
     });
-    analyse.subcommand(".restore", "恢复统计数据", { authority: 4 }).action(async () => {
+    cmd.subcommand(".restore", "恢复数据", { authority: 4 }).usage(`从本地的 JSON 文件中恢复统计数据。`).action(async () => {
       try {
         const userTablePath = path.join(this.dataDir, "analyse_user.json");
         const usersToImport = JSON.parse(await fs.readFile(userTablePath, "utf-8").catch(() => "[]"));
@@ -620,15 +736,14 @@ var Data = class {
         return "数据恢复失败";
       }
     });
-    analyse.subcommand(".clear", "清理统计数据", { authority: 4 }).option("table", "-t <table:string> 指定表名").option("guild", "-g <guildId:string> 指定群组").option("user", "-u <user:string> 指定用户").option("days", "-d <days:number> 指定天数").option("all", "-a 清理全部数据").action(async ({ options }) => {
-      if (Object.keys(options).length === 0) return "请提供清理条件";
+    cmd.subcommand(".clear", "清除数据", { authority: 4 }).option("table", "-t <table:string> 指定表名").option("guild", "-g <guildId:string> 指定群组").option("user", "-u <user:string> 指定用户").option("days", "-d <days:number> 指定天数").option("command", "-c <command:string> 指定命令").option("all", "-a 清除全部").usage(`根据指定条件清理统计数据，可以组合多个选项以精确控制清除范围。`).action(async ({ options }) => {
+      if (Object.keys(options).length === 0) return "请指定清除条件";
+      if (options.table && !ALL_TABLES.includes(options.table)) return `表名 ${options.table} 无效`;
       try {
         if (options.all) {
-          await Promise.all(ALL_TABLES.map((tableName) => this.ctx.database.remove(tableName, {})));
-          return "已清除所有聊天分析数据";
+          await Promise.all(ALL_TABLES.map((tableName) => this.ctx.database.drop(tableName)));
+          return "已清除所有数据，请重新初始化插件";
         }
-        const tablesToClear = options.table ? [options.table] : ALL_TABLES.filter((t) => t !== "analyse_user");
-        if (options.table && !ALL_TABLES.includes(options.table)) return `无效表名: ${options.table}。`;
         const query = {};
         const descParts = [];
         if (options.guild || options.user) {
@@ -638,35 +753,54 @@ var Data = class {
             descParts.push(`群组 ${options.guild}`);
           }
           if (options.user) {
-            userQuery.userId = import_koishi5.Element.select(options.user, "at")[0]?.attrs.id ?? options.user;
-            descParts.push(`用户 ${userQuery.userId}`);
+            const userId = import_koishi5.Element.select(options.user, "at")[0]?.attrs.id ?? options.user;
+            userQuery.userId = userId;
+            descParts.push(`用户 ${userId}`);
           }
           const uidsToClear = (await this.ctx.database.get("analyse_user", userQuery)).map((u) => u.uid);
-          if (uidsToClear.length === 0) return "未找到匹配记录";
+          if (uidsToClear.length === 0) return "未找到相关数据";
           query.uid = { $in: [...new Set(uidsToClear)] };
         }
         if (options.days > 0) {
           query.timestamp = { $lt: new Date(Date.now() - options.days * import_koishi5.Time.day) };
-          descParts.push(`超过 ${options.days} 天`);
+          descParts.push(`${options.days} 天前`);
+        }
+        if (options.command) {
+          query.command = options.command;
+          descParts.push(`命令 ${options.command}`);
         }
+        const tablesToClear = options.command ? ["analyse_cmd"] : options.table ? [options.table] : ALL_TABLES.filter((t) => t !== "analyse_user");
+        let foundData = false;
+        for (const tableName of tablesToClear) {
+          const records = await this.ctx.database.get(tableName, query, ["uid"]);
+          if (records.length > 0) {
+            foundData = true;
+            break;
+          }
+        }
+        if (!foundData) return "未找到相关数据";
         for (const tableName of tablesToClear) await this.ctx.database.remove(tableName, query);
-        const targetStr = options.table ? `表 ${options.table}` : "所有相关表";
-        return `已成功清理${targetStr}中${descParts.join("且")}的数据`;
+        const tableString = options.table ? `表 ${options.table}` : "所有表";
+        const descString = descParts.join("、");
+        if (descString) {
+          return `已清除${tableString}中 ${descString} 的数据`;
+        } else {
+          return `已清除${tableString}中的所有数据`;
+        }
       } catch (error) {
         this.ctx.logger.error("数据清理失败:", error);
         return "数据清理失败";
       }
     });
-    analyse.subcommand(".list", "列出频道和命令", { authority: 4 }).action(async () => {
+    cmd.subcommand(".list", "列出数据", { authority: 4 }).usage("列出数据库中的频道和命令列表。").action(async () => {
       const [allChannelInfo, commands] = await Promise.all([
         this.ctx.database.get("analyse_user", {}, ["channelId", "channelName"]),
-        this.ctx.database.select("analyse_cmd").distinct("command").execute()
+        this.ctx.database.select("analyse_cmd").groupBy("command").execute()
       ]);
       const uniqueChannels = [...new Map(allChannelInfo.map((item) => [item.channelId, item])).values()];
-      const channelOutput = uniqueChannels.length ? "已记录频道列表:\n" + uniqueChannels.map((c) => `[${c.channelId}] ${c.channelName}`).join("\n") : "暂无频道记录";
-      const commandOutput = commands.length ? "已记录命令列表:\n" + commands.join(", ") : "暂无命令记录";
+      const channelOutput = uniqueChannels.length ? "频道列表:\n" + uniqueChannels.map((c) => `[${c.channelId}] ${c.channelName}`).join("\n") : "暂无频道记录";
+      const commandOutput = commands.length ? "命令列表:\n" + commands.join(", ") : "暂无命令记录";
       return `${channelOutput}
-
 ${commandOutput}`;
     });
   }
@@ -690,29 +824,27 @@ var using = ["database", "puppeteer", "cron"];
 var Config = import_koishi6.Schema.intersect([
   import_koishi6.Schema.object({
     enableListener: import_koishi6.Schema.boolean().default(true).description("启用消息监听"),
-    enableData: import_koishi6.Schema.boolean().default(false).description("启用数据管理")
-  }).description("基础配置"),
+    enableDataIO: import_koishi6.Schema.boolean().default(true).description("启用数据管理")
+  }).description("杂项配置"),
   import_koishi6.Schema.object({
     enableCmdStat: import_koishi6.Schema.boolean().default(true).description("启用命令统计"),
     enableMsgStat: import_koishi6.Schema.boolean().default(true).description("启用消息统计"),
-    enableActivityStat: import_koishi6.Schema.boolean().default(true).description("启用活跃分析"),
-    enableOriRecord: import_koishi6.Schema.boolean().default(true).description("启用原始记录")
-  }).description("功能配置"),
-  import_koishi6.Schema.object({
+    enableActivity: import_koishi6.Schema.boolean().default(true).description("启用活跃统计"),
     enableRankStat: import_koishi6.Schema.boolean().default(true).description("启用发言排行"),
-    rankRetentionDays: import_koishi6.Schema.number().min(0).default(31).description("记录保留天数")
-  }).description("发言排行配置"),
+    rankRetentionDays: import_koishi6.Schema.number().min(0).default(31).description("排行保留天数"),
+    enableWhoAt: import_koishi6.Schema.boolean().default(true).description("启用提及记录"),
+    atRetentionDays: import_koishi6.Schema.number().min(0).default(7).description("提及保留天数")
+  }).description("基础分析配置"),
   import_koishi6.Schema.object({
-    enableWhoAt: import_koishi6.Schema.boolean().default(true).description("启用@记录"),
-    atRetentionDays: import_koishi6.Schema.number().min(0).default(7).description("记录保留天数")
-  }).description("@记录配置")
+    enableOriRecord: import_koishi6.Schema.boolean().default(true).description("启用原始记录")
+  }).description("高级分析配置")
 ]);
 function apply(ctx, config) {
   if (config.enableListener) new Collector(ctx, config);
-  const analyse = ctx.command("analyse", "聊天记录分析");
+  const analyse = ctx.command("analyse", "数据分析");
   new Stat(ctx, config).registerCommands(analyse);
   if (config.enableWhoAt) new WhoAt(ctx, config).registerCommand(analyse);
-  if (config.enableData) new Data(ctx).registerCommands(analyse);
+  if (config.enableDataIO) new Data(ctx).registerCommands(analyse);
 }
 __name(apply, "apply");
 // Annotate the CommonJS export names for ESM import in node:

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-chat-analyse",
   "description": "聊天记录分析",
-  "version": "0.5.3",
+  "version": "0.5.4",
   "contributors": [
     "Yis_Rime <yis_rime@outlook.com>"
   ],