koishi-plugin-chat-analyse 0.2.3 → 0.2.4

package/lib/CmdStat.d.ts

@@ -13,22 +13,26 @@ declare module 'koishi' {
 }
 /**
  * @class CmdStat
- * @description 负责提供命令执行所需的服务，并管理插件的核心逻辑。
+ * @description 提供命令统计服务，处理用户查询并渲染结果。
  */
 export declare class CmdStat {
+    private ctx;
     renderer: Renderer;
-    ctx: Context;
-    constructor(context: Context);
+    constructor(ctx: Context);
     /**
-     * @method registerCommands
-     * @description 注册命令，并通过选项支持不同维度的查询。
+     * 注册所有相关的子命令到主 `analyse` 命令下。
+     * @param analyse {Command} 主 `analyse` 命令实例。
      */
     registerCommands(analyse: Command): void;
     /**
-     * @private
-     * @method getCommandStats
-     * @description 从数据库获取并处理命令统计数据，兼容全局、群组和个人查询。
-     * @returns 返回一个包含二维数组列表和总数的对象，或错误字符串。
+     * 根据查询参数动态生成图片标题。
+     */
+    private generateTitle;
+    /**
+     * 从数据库获取并聚合命令统计数据。
+     * @param guildId {string} (可选) 群组ID。
+     * @param userId {string} (可选) 用户ID。
+     * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 包含结果列表和总数的对象，或错误/提示信息。
      */
     private getCommandStats;
 }

package/lib/Collector.d.ts

@@ -19,46 +19,53 @@ declare module 'koishi' {
 }
 /**
  * @class Collector
- * @description
- * 负责初始化数据库表、监听消息，并将处理后的数据高效存入数据库。
+ * @description 负责收集、缓冲并持久化消息数据，同时高效缓存用户与群组的名称信息。
  */
 export declare class Collector {
     private ctx;
     private static readonly FLUSH_INTERVAL;
     private static readonly BUFFER_THRESHOLD;
     private msgBuffer;
-    private flushInterval;
     private nameCache;
     private pendingNameRequests;
+    private flushInterval;
     /**
      * @constructor
-     * @param ctx {Context} Koishi 的上下文对象
+     * @param ctx {Context} Koishi 上下文，用于访问框架核心功能。
      */
     constructor(ctx: Context);
     /**
-     * 核心消息处理函数。
-     * @param session {Session} 消息会话对象
+     * 核心消息处理器，对消息进行格式化并存入缓冲区。
+     * @param session {Session} 消息会话对象。
      */
     private handleMessage;
     /**
-     * 从消息元素中提取并汇总类型。
+     * 汇总消息元素的类型，生成紧凑的类型字符串。
+     * @param elements {Element[]} 消息元素数组。
+     * @returns {string} 类型汇总字符串，如 `[text][img]`。
      */
     private summarizeElementTypes;
     /**
-     * 从消息元素中提取文本化、安全的内容。
+     * 清理并格式化消息内容，提取关键信息。
+     * @param elements {Element[]} 消息元素数组。
+     * @returns {string} 处理后的内容字符串。
      */
     private sanitizeContent;
     /**
-     * 将内存缓冲区的消息数据批量写入数据库。
+     * 将内存缓冲区的消息批量写入数据库，并处理写入失败的情况。
      */
     private flushBuffer;
     /**
-     * 检查并更新用户和群组的名称信息。
+     * 检查用户和群组名称是否需要更新，利用缓存和请求锁机制避免重复调用。
+     * @param session {Session} 消息会话对象。
+     * @param effectiveId {string} 有效的频道/群组ID。
      */
     private updateNameIfNeeded;
     /**
-     * @private
-     * 封装了实际获取和更新名称的异步逻辑。
+     * 异步获取用户和群组的最新名称，并更新到数据库和内存缓存。
+     * @param session {Session} 消息会话对象。
+     * @param effectiveId {string} 频道/群组ID。
+     * @param cacheKey {string} 用于缓存的键。
      */
     private fetchAndUpdateNames;
 }

package/lib/Renderer.d.ts

@@ -1,12 +1,11 @@
 import { Context } from 'koishi';
 /**
- * 渲染列表中的一行数据。每个元素代表一列。
- * 这是一个灵活的元组类型，可以包含字符串、数字或日期。
+ * 定义渲染列表中的单行数据格式。
  * @example ['ping', 150, new Date()]
  */
 export type RenderListItem = (string | number | Date)[];
 /**
- * 渲染列表图片所需的数据结构。
+ * 定义渲染图片所需的数据结构。
  */
 export interface ListRenderData {
     title: string;
@@ -16,34 +15,33 @@ export interface ListRenderData {
 }
 /**
  * @class Renderer
- * @description 使用 Puppeteer 服务将格式化的数据渲染成图片。
- * 这是一个通用的列表渲染器，能够处理任意列数的数据，并根据数据类型智能应用样式。
+ * @description 通用列表渲染器，通过 Puppeteer 将数据渲染为包含精美表格的图片。
  */
 export declare class Renderer {
     private ctx;
     /**
      * @constructor
-     * @param ctx {Context} Koishi 的上下文对象
+     * @param ctx {Context} Koishi 上下文，用于访问 puppeteer 服务。
      */
     constructor(ctx: Context);
     /**
      * 将列表数据渲染为图片。
      * @param data {ListRenderData} 待渲染的列表数据。
-     * @param headers {string[]} (可选) 表头数组。如果不提供或为空，则不渲染表头部分。
-     * @returns {Promise<string | Buffer>} 成功时返回图片 Buffer，失败或无数据时返回提示文本。
+     * @param headers {string[]} (可选) 表头文案数组，若不提供则不渲染表头。
+     * @returns {Promise<string | Buffer>} 成功时返回图片 Buffer，无数据时返回提示文本。
      */
     renderList(data: ListRenderData, headers?: string[]): Promise<string | Buffer>;
     /**
-     * 格式化日期，提供相对时间和绝对时间显示。
-     * @param date {Date} 日期对象
-     * @returns {string} 格式化后的日期字符串
+     * 智能格式化日期，提供相对时间（如“刚刚”，“x分钟前”）和绝对日期。
+     * @param date {Date} 待格式化的日期对象。
+     * @returns {string} 格式化后的日期字符串。
      */
     private formatDate;
     /**
-     * 根据列表数据动态生成 HTML 字符串。
-     * @param data {ListRenderData} 列表数据
-     * @param headers {string[]} (可选) 表头数组
-     * @returns {string | null} 生成的 HTML 字符串，如果无数据则返回 null。
+     * 根据数据动态生成渲染图片所需的完整 HTML 字符串。
+     * @param data {ListRenderData} 列表数据。
+     * @param headers {string[]} (可选) 表头数组。
+     * @returns {string | null} 生成的 HTML 字符串，若无数据则返回 null。
      */
     private generateListHtml;
 }

package/lib/index.d.ts

@@ -1,12 +1,12 @@
 import { Context, Schema } from 'koishi';
 export declare const usage = "\n<div style=\"border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);\">\n  <h2 style=\"margin-top: 0; color: #4a6ee0;\">\uD83D\uDCCC \u63D2\u4EF6\u8BF4\u660E</h2>\n  <p>\uD83D\uDCD6 <strong>\u4F7F\u7528\u6587\u6863</strong>\uFF1A\u8BF7\u70B9\u51FB\u5DE6\u4E0A\u89D2\u7684 <strong>\u63D2\u4EF6\u4E3B\u9875</strong> \u67E5\u770B\u63D2\u4EF6\u4F7F\u7528\u6587\u6863</p>\n  <p>\uD83D\uDD0D <strong>\u66F4\u591A\u63D2\u4EF6</strong>\uFF1A\u53EF\u8BBF\u95EE <a href=\"https://github.com/YisRime\" style=\"color:#4a6ee0;text-decoration:none;\">\u82E1\u6DDE\u7684 GitHub</a> \u67E5\u770B\u672C\u4EBA\u7684\u6240\u6709\u63D2\u4EF6</p>\n</div>\n<div style=\"border-radius: 10px; border: 1px solid #ddd; padding: 16px; margin-bottom: 20px; box-shadow: 0 2px 5px rgba(0,0,0,0.1);\">\n  <h2 style=\"margin-top: 0; color: #e0574a;\">\u2764\uFE0F \u652F\u6301\u4E0E\u53CD\u9988</h2>\n  <p>\uD83C\uDF1F \u559C\u6B22\u8FD9\u4E2A\u63D2\u4EF6\uFF1F\u8BF7\u5728 <a href=\"https://github.com/YisRime\" style=\"color:#e0574a;text-decoration:none;\">GitHub</a> \u4E0A\u7ED9\u6211\u4E00\u4E2A Star\uFF01</p>\n  <p>\uD83D\uDC1B \u9047\u5230\u95EE\u9898\uFF1F\u8BF7\u901A\u8FC7 <strong>Issues</strong> \u63D0\u4EA4\u53CD\u9988\uFF0C\u6216\u52A0\u5165 QQ \u7FA4 <a href=\"https://qm.qq.com/q/PdLMx9Jowq\" style=\"color:#e0574a;text-decoration:none;\"><strong>855571375</strong></a> \u8FDB\u884C\u4EA4\u6D41</p>\n</div>\n";
 export declare const name = "chat-analyse";
+export declare const using: string[];
 export interface Config {
 }
 export declare const Config: Schema<Config>;
-export declare const using: string[];
 /**
- * Koishi 插件的入口函数。
- * @param ctx {Context} Koishi 的上下文对象，用于访问框架核心功能。
+ * Koishi 插件主入口函数。
+ * @param ctx {Context} Koishi 上下文，用于访问和扩展框架功能。
  */
 export declare function apply(ctx: Context): void;

package/lib/index.js

@@ -33,33 +33,25 @@ var import_koishi3 = require("koishi");
 var Collector = class _Collector {
   /**
    * @constructor
-   * @param ctx {Context} Koishi 的上下文对象
+   * @param ctx {Context} Koishi 上下文，用于访问框架核心功能。
    */
   constructor(ctx) {
     this.ctx = ctx;
-    this.ctx.model.extend("analyse_msg", {
+    ctx.model.extend("analyse_msg", {
       id: "unsigned",
       channelId: "string",
       userId: "string",
       type: "string",
       content: "text",
       timestamp: "timestamp"
-    }, {
-      primary: "id",
-      autoInc: true,
-      indexes: ["timestamp", "channelId", "userId", "type"]
-    });
-    this.ctx.model.extend("analyse_name", {
+    }, { primary: "id", autoInc: true, indexes: ["timestamp", "channelId", "userId", "type"] });
+    ctx.model.extend("analyse_name", {
       channelId: "string",
       channelName: "string",
       userId: "string",
       userName: "string"
-    }, {
-      primary: ["channelId", "userId"]
-    });
-    ctx.on("message", (session) => {
-      this.handleMessage(session);
-    });
+    }, { primary: ["channelId", "userId"] });
+    ctx.on("message", (session) => this.handleMessage(session));
     this.flushInterval = setInterval(() => this.flushBuffer(), _Collector.FLUSH_INTERVAL);
     ctx.on("dispose", () => {
       clearInterval(this.flushInterval);
@@ -69,25 +61,28 @@ var Collector = class _Collector {
   static {
     __name(this, "Collector");
   }
+  // 数据刷新配置
   static FLUSH_INTERVAL = 60 * 1e3;
+  // 每分钟刷新一次
   static BUFFER_THRESHOLD = 100;
+  // 缓冲区达到100条消息时刷新
+  // 消息和名称缓存
   msgBuffer = [];
-  flushInterval;
   nameCache = /* @__PURE__ */ new Map();
   pendingNameRequests = /* @__PURE__ */ new Map();
+  flushInterval;
   /**
-   * 核心消息处理函数。
-   * @param session {Session} 消息会话对象
+   * 核心消息处理器，对消息进行格式化并存入缓冲区。
+   * @param session {Session} 消息会话对象。
    */
   async handleMessage(session) {
     const { userId, channelId, guildId, content, timestamp, argv, elements } = session;
     const effectiveId = channelId || guildId;
-    if (!effectiveId || !userId || !timestamp) return;
-    await this.updateNameIfNeeded(session, effectiveId);
+    if (!effectiveId || !userId || !timestamp || !content?.trim()) return;
+    this.updateNameIfNeeded(session, effectiveId);
     const isCommand = !!argv?.command;
     const type = isCommand ? argv.command.name : this.summarizeElementTypes(elements);
     const finalContent = isCommand ? content : this.sanitizeContent(elements);
-    if (!finalContent?.trim()) return;
     this.msgBuffer.push({
       channelId: effectiveId,
       userId,
@@ -95,35 +90,38 @@ var Collector = class _Collector {
       content: finalContent,
       timestamp: new Date(timestamp)
     });
-    if (this.msgBuffer.length >= _Collector.BUFFER_THRESHOLD) {
-      this.flushBuffer();
-    }
+    if (this.msgBuffer.length >= _Collector.BUFFER_THRESHOLD) await this.flushBuffer();
   }
   /**
-   * 从消息元素中提取并汇总类型。
+   * 汇总消息元素的类型，生成紧凑的类型字符串。
+   * @param elements {Element[]} 消息元素数组。
+   * @returns {string} 类型汇总字符串，如 `[text][img]`。
    */
   summarizeElementTypes(elements) {
-    return [...new Set(elements.map((e) => `[${e.type}]`))].join("");
+    const types = new Set(elements.map((e) => `[${e.type}]`));
+    return Array.from(types).join("");
   }
   /**
-   * 从消息元素中提取文本化、安全的内容。
+   * 清理并格式化消息内容，提取关键信息。
+   * @param elements {Element[]} 消息元素数组。
+   * @returns {string} 处理后的内容字符串。
    */
   sanitizeContent(elements) {
-    return elements.map((element) => {
-      switch (element.type) {
+    return elements.map((e) => {
+      switch (e.type) {
         case "text":
-          return element.attrs.content;
+          return e.attrs.content;
         case "img":
-          return element.attrs.summary === "[动画表情]" ? "[gif]" : `[img]`;
+          return e.attrs.summary === "[动画表情]" ? "[gif]" : "[img]";
         case "at":
-          return `[at:${element.attrs.id}]`;
+          return `[at:${e.attrs.id}]`;
         default:
-          return `[${element.type}]`;
+          return `[${e.type}]`;
       }
     }).join("");
   }
   /**
-   * 将内存缓冲区的消息数据批量写入数据库。
+   * 将内存缓冲区的消息批量写入数据库，并处理写入失败的情况。
    */
   async flushBuffer() {
     if (this.msgBuffer.length === 0) return;
@@ -137,27 +135,27 @@ var Collector = class _Collector {
     }
   }
   /**
-   * 检查并更新用户和群组的名称信息。
+   * 检查用户和群组名称是否需要更新，利用缓存和请求锁机制避免重复调用。
+   * @param session {Session} 消息会话对象。
+   * @param effectiveId {string} 有效的频道/群组ID。
    */
   async updateNameIfNeeded(session, effectiveId) {
     const { userId } = session;
     if (!userId) return;
     const cacheKey = `${effectiveId}:${userId}`;
+    const CACHE_EXPIRATION = 24 * 60 * 60 * 1e3;
     if (this.pendingNameRequests.has(cacheKey)) return this.pendingNameRequests.get(cacheKey);
     const cached = this.nameCache.get(cacheKey);
-    const CACHE_EXPIRATION = 24 * 60 * 60 * 1e3;
     if (cached && Date.now() - cached.timestamp < CACHE_EXPIRATION) return;
     const promise = this.fetchAndUpdateNames(session, effectiveId, cacheKey);
     this.pendingNameRequests.set(cacheKey, promise);
-    try {
-      await promise;
-    } finally {
-      this.pendingNameRequests.delete(cacheKey);
-    }
+    promise.finally(() => this.pendingNameRequests.delete(cacheKey));
   }
   /**
-   * @private
-   * 封装了实际获取和更新名称的异步逻辑。
+   * 异步获取用户和群组的最新名称，并更新到数据库和内存缓存。
+   * @param session {Session} 消息会话对象。
+   * @param effectiveId {string} 频道/群组ID。
+   * @param cacheKey {string} 用于缓存的键。
    */
   async fetchAndUpdateNames(session, effectiveId, cacheKey) {
     try {
@@ -193,7 +191,7 @@ var import_koishi = require("koishi");
 var Renderer = class {
   /**
    * @constructor
-   * @param ctx {Context} Koishi 的上下文对象
+   * @param ctx {Context} Koishi 上下文，用于访问 puppeteer 服务。
    */
   constructor(ctx) {
     this.ctx = ctx;
@@ -204,87 +202,61 @@ var Renderer = class {
   /**
    * 将列表数据渲染为图片。
    * @param data {ListRenderData} 待渲染的列表数据。
-   * @param headers {string[]} (可选) 表头数组。如果不提供或为空，则不渲染表头部分。
-   * @returns {Promise<string | Buffer>} 成功时返回图片 Buffer，失败或无数据时返回提示文本。
+   * @param headers {string[]} (可选) 表头文案数组，若不提供则不渲染表头。
+   * @returns {Promise<string | Buffer>} 成功时返回图片 Buffer，无数据时返回提示文本。
    */
   async renderList(data, headers) {
     const htmlContent = this.generateListHtml(data, headers);
+    if (!htmlContent) return "暂无数据可供渲染";
     return this.ctx.puppeteer.render(htmlContent);
   }
   /**
-   * 格式化日期，提供相对时间和绝对时间显示。
-   * @param date {Date} 日期对象
-   * @returns {string} 格式化后的日期字符串
+   * 智能格式化日期，提供相对时间（如“刚刚”，“x分钟前”）和绝对日期。
+   * @param date {Date} 待格式化的日期对象。
+   * @returns {string} 格式化后的日期字符串。
    */
   formatDate(date) {
     if (!date) return "未知";
-    const now = Date.now();
-    const diff = now - date.getTime();
+    const diff = Date.now() - date.getTime();
     if (diff < import_koishi.Time.minute) return "刚刚";
     if (diff < import_koishi.Time.hour) return `${Math.floor(diff / import_koishi.Time.minute)} 分钟前`;
     if (diff < import_koishi.Time.day) return `${Math.floor(diff / import_koishi.Time.hour)} 小时前`;
-    const pad = /* @__PURE__ */ __name((n) => n.toString().padStart(2, "0"), "pad");
-    return `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+    return `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
   }
   /**
-   * 根据列表数据动态生成 HTML 字符串。
-   * @param data {ListRenderData} 列表数据
-   * @param headers {string[]} (可选) 表头数组
-   * @returns {string | null} 生成的 HTML 字符串，如果无数据则返回 null。
+   * 根据数据动态生成渲染图片所需的完整 HTML 字符串。
+   * @param data {ListRenderData} 列表数据。
+   * @param headers {string[]} (可选) 表头数组。
+   * @returns {string | null} 生成的 HTML 字符串，若无数据则返回 null。
    */
   generateListHtml(data, headers) {
     const { title, time, total, list } = data;
-    if (!list || list.length === 0) return null;
-    let tableHeadHtml = "";
-    if (headers && headers.length > 0) {
-      const numDataColumns = list[0].length;
-      const headerCells = [];
-      for (let i = 0; i < numDataColumns; i++) {
-        const headerText = headers[i] || "";
-        headerCells.push(`<th>${headerText}</th>`);
-      }
-      const allHeaders = `<th class="rank-cell">排名</th>${headerCells.join("")}`;
-      tableHeadHtml = `<thead><tr>${allHeaders}</tr></thead>`;
-    }
-    const tableRows = list.map((rowItems, index) => {
+    if (!list?.length) return null;
+    const tableHeadHtml = headers?.length > 0 ? `<thead><tr><th class="rank-cell">排名</th>${headers.map((h2) => `<th>${h2}</th>`).join("")}</tr></thead>` : "";
+    const tableRowsHtml = list.map((row, index) => {
       const rank = index + 1;
-      let rankClass = "";
-      if (rank === 1) rankClass = "rank-gold";
-      if (rank === 2) rankClass = "rank-silver";
-      if (rank === 3) rankClass = "rank-bronze";
+      const rankClass = rank === 1 ? "rank-gold" : rank === 2 ? "rank-silver" : rank === 3 ? "rank-bronze" : "";
       const rankCell = `<td class="rank-cell"><span class="rank-badge ${rankClass}">${rank}</span></td>`;
-      const dataCells = rowItems.map((cellData) => {
-        let cellClass = "data-cell";
-        let content;
-        if (cellData instanceof Date) {
-          cellClass += " date-cell";
-          content = this.formatDate(cellData);
-        } else if (typeof cellData === "number") {
-          cellClass += " count-cell";
-          content = cellData;
-        } else {
-          cellClass += " name-cell";
-          content = String(cellData);
-        }
-        return `<td class="${cellClass}">${content}</td>`;
+      const dataCells = row.map((cell) => {
+        if (cell instanceof Date) return `<td class="data-cell date-cell">${this.formatDate(cell)}</td>`;
+        if (typeof cell === "number") return `<td class="data-cell count-cell">${cell}</td>`;
+        return `<td class="data-cell name-cell">${String(cell)}</td>`;
       }).join("");
       return `<tr>${rankCell}${dataCells}</tr>`;
     }).join("");
-    const metaInfo = total !== void 0 ? `<div class="total-count">总计: ${total}</div>` : "";
-    const timeLabel = `生成于 ${time.getFullYear()}-${String(time.getMonth() + 1).padStart(2, "0")}-${String(time.getDate()).padStart(2, "0")} ${String(time.getHours()).padStart(2, "0")}:${String(time.getMinutes()).padStart(2, "0")}`;
+    const metaInfoHtml = `
+      <div class="meta-group">
+        ${total !== void 0 ? `<div class="total-count">总计: ${total}</div>` : ""}
+        <div class="time-label">生成于 ${time.toLocaleString("zh-CN", { hour12: false })}</div>
+      </div>
+    `;
     const styles = `
       :root {
-        --bg-color: #f7f8fa; --card-bg: #ffffff; --text-color: #333;
-        --header-color: #1f2329; --sub-text-color: #646a73;
-        --border-color: #e4e6eb; --accent-color: #4a6ee0;
+        --bg-color: #f7f8fa; --card-bg: #ffffff; --text-color: #333; --header-color: #1f2329;
+        --sub-text-color: #646a73; --border-color: #e4e6eb; --accent-color: #4a6ee0;
         --gold: #ffc327; --silver: #a8b5c1; --bronze: #d69864;
       }
-      body {
-        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
-        background: var(--bg-color); margin: 0; padding: 20px;
-        width: 700px; box-sizing: border-box;
-        -webkit-font-smoothing: antialiased;
-      }
+      body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif; background: var(--bg-color); margin: 0; padding: 20px; width: 700px; box-sizing: border-box; -webkit-font-smoothing: antialiased; }
       .container { background: var(--card-bg); border-radius: 12px; box-shadow: 0 6px 16px rgba(0,0,0,0.08); padding: 24px; }
       .header { display: flex; justify-content: space-between; align-items: flex-start; border-bottom: 1px solid var(--border-color); padding-bottom: 16px; margin-bottom: 16px; }
       .title-group h1 { font-size: 24px; font-weight: 700; color: var(--header-color); margin: 0; }
@@ -292,15 +264,14 @@ var Renderer = class {
       .meta-group .total-count { font-size: 22px; font-weight: 700; color: var(--accent-color); }
       .meta-group .time-label { font-size: 13px; color: var(--sub-text-color); margin-top: 4px; }
       table { width: 100%; border-collapse: collapse; color: var(--text-color); }
-      th, td { padding: 12px 8px; text-align: left; border-bottom: 1px solid var(--border-color); }
+      th, td { padding: 12px 8px; text-align: left; border-bottom: 1px solid var(--border-color); vertical-align: middle; }
       th { font-size: 13px; font-weight: 600; color: var(--sub-text-color); }
-      td { font-size: 15px; vertical-align: middle; }
+      td { font-size: 15px; }
       tr:last-child td { border-bottom: none; }
       .rank-cell { width: 50px; text-align: center; }
       .rank-badge { display: inline-block; width: 24px; height: 24px; line-height: 24px; border-radius: 50%; font-weight: 600; font-size: 14px; color: var(--header-color); background-color: #eef0f3; }
-      .rank-gold { background-color: var(--gold); color: #fff; }
-      .rank-silver { background-color: var(--silver); color: #fff; }
-      .rank-bronze { background-color: var(--bronze); color: #fff; }
+      .rank-gold, .rank-silver, .rank-bronze { color: #fff; }
+      .rank-gold { background-color: var(--gold); } .rank-silver { background-color: var(--silver); } .rank-bronze { background-color: var(--bronze); }
       .data-cell { word-break: break-all; }
       .name-cell { font-weight: 600; color: var(--header-color); }
       .count-cell { text-align: right; font-weight: 600; color: var(--accent-color); }
@@ -308,33 +279,24 @@ var Renderer = class {
     `;
     return `
       <!DOCTYPE html><html lang="zh-CN">
-      <head><meta charset="UTF-8"><meta name="viewport" content="width=device-width, initial-scale=1.0"><title>${title}</title><style>${styles}</style></head>
+      <head><meta charset="UTF-8"><title>${title}</title><style>${styles}</style></head>
       <body>
         <div class="container">
           <div class="header">
             <div class="title-group"><h1>${title}</h1></div>
-            <div class="meta-group">${metaInfo}<div class="time-label">${timeLabel}</div></div>
+            ${metaInfoHtml}
           </div>
-          <table>
-            ${tableHeadHtml}
-            <tbody>${tableRows}</tbody>
-          </table>
+          <table>${tableHeadHtml}<tbody>${tableRowsHtml}</tbody></table>
         </div>
-      </body></html>
-    `;
+      </body></html>`;
   }
 };
 
 // src/CmdStat.ts
 var CmdStat = class {
-  static {
-    __name(this, "CmdStat");
-  }
-  renderer;
-  ctx;
-  constructor(context) {
-    this.ctx = context;
-    this.renderer = new Renderer(this.ctx);
+  constructor(ctx) {
+    this.ctx = ctx;
+    this.renderer = new Renderer(ctx);
     this.ctx.model.extend("analyse_cmd", {
       channelId: "string",
       userId: "string",
@@ -345,8 +307,7 @@ var CmdStat = class {
     this.ctx.on("command/before-execute", async ({ command, session }) => {
       const { userId, guildId } = session;
       if (!guildId || !userId) return;
-      const commandName = command.name;
-      const query = { channelId: guildId, userId, command: commandName };
+      const query = { channelId: guildId, userId, command: command.name };
       await this.ctx.database.upsert("analyse_cmd", (row) => [{
         ...query,
         count: import_koishi2.$.add(import_koishi2.$.ifNull(row.count, 0), 1),
@@ -354,38 +315,26 @@ var CmdStat = class {
       }]);
     });
   }
+  static {
+    __name(this, "CmdStat");
+  }
+  renderer;
   /**
-   * @method registerCommands
-   * @description 注册命令，并通过选项支持不同维度的查询。
+   * 注册所有相关的子命令到主 `analyse` 命令下。
+   * @param analyse {Command} 主 `analyse` 命令实例。
    */
   registerCommands(analyse) {
-    analyse.subcommand(".command", "命令使用统计").option("user", "-u [user:user] 指定用户").option("guild", "-g [guildId:string] 指定群组").usage(`查询命令使用统计。默认查询全局统计，可通过选项指定用户和群组。`).action(async ({ session, options }) => {
+    analyse.subcommand(".command", "命令使用统计").option("user", "-u [user:user] 查看指定用户的统计").option("guild", "-g [guildId:string] 查看指定群组的统计 (默认当前群)").usage("查询命令使用统计。支持按用户、按群组或组合查询。").action(async ({ session, options }) => {
       const userId = options.user ? import_koishi2.h.select(options.user, "user")[0]?.attrs.id : void 0;
       let guildId = options.guild;
       if (options.guild === "" && !options.user) {
-        if (!session.guildId) return "请指定群组 ID";
+        if (!session.guildId) return "私聊中请使用 -g <群组ID> 指定群组。";
         guildId = session.guildId;
       }
       try {
         const stats = await this.getCommandStats(guildId, userId);
         if (typeof stats === "string") return stats;
-        let title;
-        const titleParts = [];
-        if (userId) {
-          const user = await session.bot.getUser(userId).catch(() => null);
-          titleParts.push(`用户 ${user?.name || userId}`);
-        }
-        if (guildId) {
-          const guild = await session.bot.getGuild(guildId).catch(() => null);
-          titleParts.push(`群组 ${guild?.name || guildId}`);
-        }
-        if (userId && !guildId) {
-          title = `${titleParts[0]}的全局命令统计`;
-        } else if (titleParts.length > 0) {
-          title = `${titleParts.join("、")}的命令统计`;
-        } else {
-          title = "全局命令统计";
-        }
+        const title = await this.generateTitle(session, guildId, userId);
         const renderData = {
           title,
           time: /* @__PURE__ */ new Date(),
@@ -402,34 +351,41 @@ var CmdStat = class {
     });
   }
   /**
-   * @private
-   * @method getCommandStats
-   * @description 从数据库获取并处理命令统计数据，兼容全局、群组和个人查询。
-   * @returns 返回一个包含二维数组列表和总数的对象，或错误字符串。
+   * 根据查询参数动态生成图片标题。
+   */
+  async generateTitle(session, guildId, userId) {
+    if (userId && guildId) {
+      const userName = (await session.bot.getUser(userId).catch(() => null))?.name || userId;
+      const guildName = (await session.bot.getGuild(guildId).catch(() => null))?.name || guildId;
+      return `${userName} 在 ${guildName} 的命令统计`;
+    }
+    if (userId) {
+      const userName = (await session.bot.getUser(userId).catch(() => null))?.name || userId;
+      return `${userName} 的全局命令统计`;
+    }
+    if (guildId) {
+      const guildName = (await session.bot.getGuild(guildId).catch(() => null))?.name || guildId;
+      return `${guildName} 的命令统计`;
+    }
+    return "全局命令统计";
+  }
+  /**
+   * 从数据库获取并聚合命令统计数据。
+   * @param guildId {string} (可选) 群组ID。
+   * @param userId {string} (可选) 用户ID。
+   * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 包含结果列表和总数的对象，或错误/提示信息。
    */
   async getCommandStats(guildId, userId) {
     const query = {};
     if (guildId) query.channelId = guildId;
     if (userId) query.userId = userId;
-    if (userId) {
-      const records = await this.ctx.database.get("analyse_cmd", query);
-      if (records.length === 0) return "暂无统计数据";
-      const totalCount2 = records.reduce((sum, record) => sum + record.count, 0);
-      const sortedList2 = records.map((r) => ({ name: r.command, count: r.count, lastUsed: r.timestamp })).sort((a, b) => b.count - a.count);
-      const list2 = sortedList2.map((item) => [item.name, item.count, item.lastUsed]);
-      return { list: list2, total: totalCount2 };
-    }
-    const aggregatedStats = await this.ctx.database.select("analyse_cmd", query).groupBy(
-      ["command"],
-      {
-        count: /* @__PURE__ */ __name((row) => import_koishi2.$.sum(row.count), "count"),
-        lastUsed: /* @__PURE__ */ __name((row) => import_koishi2.$.max(row.timestamp), "lastUsed")
-      }
-    ).execute();
+    const aggregatedStats = await this.ctx.database.select("analyse_cmd", query).groupBy(["command"], {
+      count: /* @__PURE__ */ __name((row) => import_koishi2.$.sum(row.count), "count"),
+      lastUsed: /* @__PURE__ */ __name((row) => import_koishi2.$.max(row.timestamp), "lastUsed")
+    }).orderBy("count", "desc").execute();
     if (aggregatedStats.length === 0) return "暂无统计数据";
     const totalCount = aggregatedStats.reduce((sum, record) => sum + record.count, 0);
-    const sortedList = aggregatedStats.sort((a, b) => b.count - a.count);
-    const list = sortedList.map((item) => [item.command, item.count, item.lastUsed]);
+    const list = aggregatedStats.map((item) => [item.command, item.count, item.lastUsed]);
     return { list, total: totalCount };
   }
 };
@@ -448,8 +404,8 @@ var usage = `
 </div>
 `;
 var name = "chat-analyse";
-var Config = import_koishi3.Schema.object({});
 var using = ["database", "puppeteer"];
+var Config = import_koishi3.Schema.object({});
 function apply(ctx) {
   new Collector(ctx);
   const cmd = new CmdStat(ctx);

package/package.json

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