koishi-plugin-chat-analyse 0.2.4 → 0.2.6

package/lib/Collector.d.ts

@@ -1,71 +1,96 @@
 import { Context } from 'koishi';
+import { Config } from './index';
 declare module 'koishi' {
     interface Tables {
-        analyse_msg: {
-            id: number;
+        analyse_user: {
+            uid: number;
             channelId: string;
             userId: string;
+            channelName: string;
+            userName: string;
+        };
+        analyse_cmd: {
+            uid: number;
+            command: string;
+            count: number;
+            timestamp: Date;
+        };
+        analyse_msg: {
+            uid: number;
             type: string;
-            content: string;
+            count: number;
             timestamp: Date;
         };
-        analyse_name: {
+        analyse_cache: {
+            id: number;
             channelId: string;
-            channelName: string;
             userId: string;
-            userName: string;
+            content: string;
+            timestamp: Date;
         };
     }
 }
 /**
  * @class Collector
- * @description 负责收集、缓冲并持久化消息数据，同时高效缓存用户与群组的名称信息。
+ * @description 核心数据收集器。根据插件配置，高效地监听、收集、缓冲并持久化聊天数据。
  */
 export declare class Collector {
     private ctx;
+    private config;
+    /** @const {number} FLUSH_INTERVAL - 内存缓存区自动刷新到数据库的时间间隔。 */
     private static readonly FLUSH_INTERVAL;
+    /** @const {number} BUFFER_THRESHOLD - 内存缓存区触发自动刷新的消息数量阈值。 */
     private static readonly BUFFER_THRESHOLD;
-    private msgBuffer;
-    private nameCache;
-    private pendingNameRequests;
+    /** @member {Omit<Tables['analyse_cache'], 'id'>[]} cacheBuffer - 用于暂存原始消息的内存缓冲区，以减少数据库写入频率。 */
+    private cacheBuffer;
+    /** @member {Map<string, number>} uidCache - 用户 uid 的内存缓存，避免重复查询数据库。*/
+    private uidCache;
+    /** @member {Map<string, Promise<number>>} pendingUidRequests - 用于处理并发获取 uid 的请求锁。*/
+    private pendingUidRequests;
     private flushInterval;
     /**
      * @constructor
-     * @param ctx {Context} Koishi 上下文，用于访问框架核心功能。
-     */
-    constructor(ctx: Context);
-    /**
-     * 核心消息处理器，对消息进行格式化并存入缓冲区。
-     * @param session {Session} 消息会话对象。
+     * @param {Context} ctx - Koishi 的插件上下文。
+     * @param {Config} config - 插件的配置对象。
      */
-    private handleMessage;
+    constructor(ctx: Context, config: Config);
     /**
-     * 汇总消息元素的类型，生成紧凑的类型字符串。
-     * @param elements {Element[]} 消息元素数组。
-     * @returns {string} 类型汇总字符串，如 `[text][img]`。
+     * @private
+     * @method defineModels
+     * @description 定义插件所需的所有数据表模型。
      */
-    private summarizeElementTypes;
+    private defineModels;
     /**
-     * 清理并格式化消息内容，提取关键信息。
-     * @param elements {Element[]} 消息元素数组。
-     * @returns {string} 处理后的内容字符串。
+     * @private
+     * @async
+     * @method handleMessage
+     * @description 统一的消息和命令处理器。它会解析收到的消息，提取关键信息并更新相应的统计数据。
+     * @param {Session} session - Koishi 的会话对象，包含消息的全部信息。
      */
-    private sanitizeContent;
+    private handleMessage;
     /**
-     * 将内存缓冲区的消息批量写入数据库，并处理写入失败的情况。
+     * @private
+     * @async
+     * @method getOrCreateUser
+     * @description 高效地获取或创建用户的中央记录 (`analyse_user`)。
+     * @param {Session} session - Koishi 会话对象，用于获取用户信息和 Bot 实例。
+     * @param {string} channelId - 消息所在的频道或群组 ID。
+     * @returns {Promise<number | null>} 返回用户的唯一 `uid`，如果操作失败则返回 `null`。
      */
-    private flushBuffer;
+    private getOrCreateUser;
     /**
-     * 检查用户和群组名称是否需要更新，利用缓存和请求锁机制避免重复调用。
-     * @param session {Session} 消息会话对象。
-     * @param effectiveId {string} 有效的频道/群组ID。
+     * @private
+     * @method sanitizeContent
+     * @description 将 Koishi 的消息元素 (Element) 数组净化为纯文本字符串，以便存储和分析。
+     * @param {Element[]} elements - 消息元素的数组。
+     * @returns {string} 净化后的纯文本字符串。
      */
-    private updateNameIfNeeded;
+    private sanitizeContent;
     /**
-     * 异步获取用户和群组的最新名称，并更新到数据库和内存缓存。
-     * @param session {Session} 消息会话对象。
-     * @param effectiveId {string} 频道/群组ID。
-     * @param cacheKey {string} 用于缓存的键。
+     * @private
+     * @async
+     * @method flushCacheBuffer
+     * @description 将内存中的消息缓存 (`cacheBuffer`) 批量写入数据库。
      */
-    private fetchAndUpdateNames;
+    private flushCacheBuffer;
 }

package/lib/Renderer.d.ts

@@ -1,11 +1,12 @@
 import { Context } from 'koishi';
 /**
- * 定义渲染列表中的单行数据格式。
- * @example ['ping', 150, new Date()]
+ * @typedef {Array<string | number | Date>} RenderListItem
+ * @description 定义了统计列表中单行数据的格式，它是一个由字符串、数字或日期组成的元组。
  */
 export type RenderListItem = (string | number | Date)[];
 /**
- * 定义渲染图片所需的数据结构。
+ * @interface ListRenderData
+ * @description 定义了调用渲染器生成列表图片时所需的完整数据结构。
  */
 export interface ListRenderData {
     title: string;
@@ -15,33 +16,41 @@ export interface ListRenderData {
 }
 /**
  * @class Renderer
- * @description 通用列表渲染器，通过 Puppeteer 将数据渲染为包含精美表格的图片。
+ * @description 一个通用的列表渲染器。它使用 Koishi 的 Puppeteer 服务将结构化的 `ListRenderData` 数据
+ *              渲染为一张包含精美表格的图片。
  */
 export declare class Renderer {
     private ctx;
     /**
      * @constructor
-     * @param ctx {Context} Koishi 上下文，用于访问 puppeteer 服务。
+     * @param {Context} ctx - Koishi 的插件上下文，用于访问 puppeteer 服务。
      */
     constructor(ctx: Context);
     /**
-     * 将列表数据渲染为图片。
-     * @param data {ListRenderData} 待渲染的列表数据。
-     * @param headers {string[]} (可选) 表头文案数组，若不提供则不渲染表头。
-     * @returns {Promise<string | Buffer>} 成功时返回图片 Buffer，无数据时返回提示文本。
+     * @public
+     * @async
+     * @method renderList
+     * @description 将列表数据渲染为图片。
+     * @param {ListRenderData} data - 待渲染的完整列表数据。
+     * @param {string[]} [headers] - (可选) 表头文案数组。如果提供，将会在表格顶部渲染表头。
+     * @returns {Promise<string | Buffer>} 渲染成功时返回图片的 Buffer 数据；如果输入数据为空，则返回提示文本。
      */
     renderList(data: ListRenderData, headers?: string[]): Promise<string | Buffer>;
     /**
-     * 智能格式化日期，提供相对时间（如“刚刚”，“x分钟前”）和绝对日期。
-     * @param date {Date} 待格式化的日期对象。
+     * @private
+     * @method formatDate
+     * @description 智能格式化日期。对于近期的时间，提供更人性化的相对时间描述（如“刚刚”，“x 分钟前”）；对于较早的时间，则显示标准的“年-月-日”格式。
+     * @param {Date} date - 待格式化的 Date 对象。
      * @returns {string} 格式化后的日期字符串。
      */
     private formatDate;
     /**
-     * 根据数据动态生成渲染图片所需的完整 HTML 字符串。
-     * @param data {ListRenderData} 列表数据。
-     * @param headers {string[]} (可选) 表头数组。
-     * @returns {string | null} 生成的 HTML 字符串，若无数据则返回 null。
+     * @private
+     * @method generateListHtml
+     * @description 根据传入的结构化数据和表头，动态生成用于 Puppeteer 渲染的完整 HTML 字符串。
+     * @param {ListRenderData} data - 列表数据对象。
+     * @param {string[]} [headers] - (可选) 表头数组。
+     * @returns {string | null} 返回生成的 HTML 字符串。如果列表数据为空，则返回 `null`。
      */
     private generateListHtml;
 }

package/lib/Stat.d.ts

@@ -0,0 +1,56 @@
+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;
+    /**
+     * @constructor
+     * @param {Context} ctx - Koishi 的插件上下文。
+     * @param {Config} config - 插件的配置对象。
+     */
+    constructor(ctx: Context, config: Config);
+    /**
+     * @method registerCommands
+     * @description 根据插件配置，动态地将 `.command` 和 `.message` 子命令注册到主 `analyse` 命令下。
+     * @param {Command} analyse - 主 `analyse` 命令实例。
+     */
+    registerCommands(analyse: Command): void;
+    /**
+     * @private
+     * @async
+     * @method _generateTitle
+     * @description 通用的标题生成器。根据查询参数 (guildId, userId) 和统计类型动态生成易于理解的图片标题。
+     * @param {Session} session - 当前会话，备用。
+     * @param {string} [guildId] - (可选) 查询的群组 ID。
+     * @param {string} [userId] - (可选) 查询的用户 ID。
+     * @param {'命令' | '消息'} type - 统计类型，用于嵌入标题文本中。
+     * @returns {Promise<string>} 生成的标题字符串。
+     */
+    private _generateTitle;
+    /**
+     * @private
+     * @async
+     * @method getCommandStats
+     * @description 从数据库中获取并聚合命令使用统计数据。
+     * @param {string} [guildId] - (可选) 若提供，则将范围限制在此群组。
+     * @param {string} [userId] - (可选) 若提供，则将范围限制在此用户。
+     * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 返回一个包含列表和总数的对象，或在无数据时返回提示字符串。
+     */
+    private getCommandStats;
+    /**
+     * @private
+     * @async
+     * @method getMessageStats
+     * @description 从数据库中获取并聚合消息类型统计数据。
+     * @param {string} [guildId] - (可选) 若提供，则将范围限制在此群组。
+     * @param {string} [userId] - (可选) 若提供，则将范围限制在此用户。
+     * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 返回一个包含列表和总数的对象，或在无数据时返回提示字符串。
+     */
+    private getMessageStats;
+}

package/lib/index.d.ts

@@ -1,12 +1,30 @@
 import { Context, Schema } from 'koishi';
+/**
+ * @name 插件使用说明
+ * @description 在 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[];
+/**
+ * @interface Config
+ * @description 定义插件的配置项结构。
+ */
 export interface Config {
+    enableListener: boolean;
+    enableCmdStat: boolean;
+    enableMsgStat: boolean;
+    enableAdvanced: boolean;
 }
+/**
+ * @const {Schema<Config>} Config
+ * @description 使用 Koishi 的 `Schema` 来定义配置项的类型、默认值和在控制台中的交互界面。
+ */
 export declare const Config: Schema<Config>;
 /**
- * Koishi 插件主入口函数。
- * @param ctx {Context} Koishi 上下文，用于访问和扩展框架功能。
+ * @function apply
+ * @description Koishi 插件的主入口函数。
+ * @param {Context} ctx - Koishi 的插件上下文，提供了访问核心 API 的能力。
+ * @param {Config} config - 用户在 `koishi.config.js` 或控制台中配置的对象。
  */
-export declare function apply(ctx: Context): void;
+export declare function apply(ctx: Context, config: Config): void;

package/lib/index.js

@@ -27,171 +27,213 @@ __export(src_exports, {
   using: () => using
 });
 module.exports = __toCommonJS(src_exports);
-var import_koishi3 = require("koishi");
+var import_koishi4 = require("koishi");
 
 // src/Collector.ts
+var import_koishi = require("koishi");
 var Collector = class _Collector {
   /**
    * @constructor
-   * @param ctx {Context} Koishi 上下文，用于访问框架核心功能。
+   * @param {Context} ctx - Koishi 的插件上下文。
+   * @param {Config} config - 插件的配置对象。
    */
-  constructor(ctx) {
+  constructor(ctx, config) {
     this.ctx = ctx;
-    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"] });
-    ctx.model.extend("analyse_name", {
-      channelId: "string",
-      channelName: "string",
-      userId: "string",
-      userName: "string"
-    }, { primary: ["channelId", "userId"] });
+    this.config = config;
+    this.defineModels();
     ctx.on("message", (session) => this.handleMessage(session));
-    this.flushInterval = setInterval(() => this.flushBuffer(), _Collector.FLUSH_INTERVAL);
-    ctx.on("dispose", () => {
-      clearInterval(this.flushInterval);
-      this.flushBuffer();
-    });
+    if (this.config.enableAdvanced) {
+      this.flushInterval = setInterval(() => this.flushCacheBuffer(), _Collector.FLUSH_INTERVAL);
+      ctx.on("dispose", () => {
+        clearInterval(this.flushInterval);
+        this.flushCacheBuffer();
+      });
+    }
   }
   static {
     __name(this, "Collector");
   }
-  // 数据刷新配置
+  /** @const {number} FLUSH_INTERVAL - 内存缓存区自动刷新到数据库的时间间隔。 */
   static FLUSH_INTERVAL = 60 * 1e3;
-  // 每分钟刷新一次
+  /** @const {number} BUFFER_THRESHOLD - 内存缓存区触发自动刷新的消息数量阈值。 */
   static BUFFER_THRESHOLD = 100;
-  // 缓冲区达到100条消息时刷新
-  // 消息和名称缓存
-  msgBuffer = [];
-  nameCache = /* @__PURE__ */ new Map();
-  pendingNameRequests = /* @__PURE__ */ new Map();
+  /** @member {Omit<Tables['analyse_cache'], 'id'>[]} cacheBuffer - 用于暂存原始消息的内存缓冲区，以减少数据库写入频率。 */
+  cacheBuffer = [];
+  /** @member {Map<string, number>} uidCache - 用户 uid 的内存缓存，避免重复查询数据库。*/
+  uidCache = /* @__PURE__ */ new Map();
+  /** @member {Map<string, Promise<number>>} pendingUidRequests - 用于处理并发获取 uid 的请求锁。*/
+  pendingUidRequests = /* @__PURE__ */ new Map();
   flushInterval;
   /**
-   * 核心消息处理器，对消息进行格式化并存入缓冲区。
-   * @param session {Session} 消息会话对象。
+   * @private
+   * @method defineModels
+   * @description 定义插件所需的所有数据表模型。
    */
-  async handleMessage(session) {
-    const { userId, channelId, guildId, content, timestamp, argv, elements } = session;
-    const effectiveId = channelId || guildId;
-    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);
-    this.msgBuffer.push({
-      channelId: effectiveId,
-      userId,
-      type,
-      content: finalContent,
-      timestamp: new Date(timestamp)
-    });
-    if (this.msgBuffer.length >= _Collector.BUFFER_THRESHOLD) await this.flushBuffer();
+  defineModels() {
+    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"] });
+    if (this.config.enableAdvanced) {
+      this.ctx.model.extend("analyse_cache", {
+        id: "unsigned",
+        channelId: "string",
+        userId: "string",
+        content: "text",
+        timestamp: "timestamp"
+      }, { primary: "id", autoInc: true });
+    }
   }
   /**
-   * 汇总消息元素的类型，生成紧凑的类型字符串。
-   * @param elements {Element[]} 消息元素数组。
-   * @returns {string} 类型汇总字符串，如 `[text][img]`。
+   * @private
+   * @async
+   * @method handleMessage
+   * @description 统一的消息和命令处理器。它会解析收到的消息，提取关键信息并更新相应的统计数据。
+   * @param {Session} session - Koishi 的会话对象，包含消息的全部信息。
    */
-  summarizeElementTypes(elements) {
-    const types = new Set(elements.map((e) => `[${e.type}]`));
-    return Array.from(types).join("");
+  async handleMessage(session) {
+    try {
+      const { userId, channelId, guildId, content, timestamp, argv, elements } = session;
+      const effectiveId = channelId || guildId;
+      if (!effectiveId || !userId || !timestamp || !content?.trim()) return;
+      const uid = await this.getOrCreateUser(session, effectiveId);
+      if (!uid) return;
+      const now = /* @__PURE__ */ new Date();
+      if (argv?.command) {
+        await this.ctx.database.upsert("analyse_cmd", (row) => [{
+          uid,
+          command: argv.command.name,
+          count: import_koishi.$.add(import_koishi.$.ifNull(row.count, import_koishi.$.literal(0)), 1),
+          timestamp: now
+        }]);
+      }
+      const uniqueElementTypes = new Set(elements.map((e) => e.type));
+      for (const type of uniqueElementTypes) {
+        await this.ctx.database.upsert("analyse_msg", (row) => [{
+          uid,
+          type,
+          count: import_koishi.$.add(import_koishi.$.ifNull(row.count, import_koishi.$.literal(0)), 1),
+          timestamp: now
+        }]);
+      }
+      if (this.config.enableAdvanced) {
+        this.cacheBuffer.push({
+          channelId: effectiveId,
+          userId,
+          content: this.sanitizeContent(elements),
+          timestamp: new Date(timestamp)
+        });
+        if (this.cacheBuffer.length >= _Collector.BUFFER_THRESHOLD) await this.flushCacheBuffer();
+      }
+    } catch (error) {
+      this.ctx.logger.warn("消息处理出错:", error);
+    }
   }
   /**
-   * 清理并格式化消息内容，提取关键信息。
-   * @param elements {Element[]} 消息元素数组。
-   * @returns {string} 处理后的内容字符串。
+   * @private
+   * @async
+   * @method getOrCreateUser
+   * @description 高效地获取或创建用户的中央记录 (`analyse_user`)。
+   * @param {Session} session - Koishi 会话对象，用于获取用户信息和 Bot 实例。
+   * @param {string} channelId - 消息所在的频道或群组 ID。
+   * @returns {Promise<number | null>} 返回用户的唯一 `uid`，如果操作失败则返回 `null`。
    */
-  sanitizeContent(elements) {
-    return elements.map((e) => {
-      switch (e.type) {
-        case "text":
-          return e.attrs.content;
-        case "img":
-          return e.attrs.summary === "[动画表情]" ? "[gif]" : "[img]";
-        case "at":
-          return `[at:${e.attrs.id}]`;
-        default:
-          return `[${e.type}]`;
+  async getOrCreateUser(session, channelId) {
+    const { userId, bot, guildId } = session;
+    const cacheKey = `${channelId}:${userId}`;
+    if (this.uidCache.has(cacheKey)) return this.uidCache.get(cacheKey);
+    if (this.pendingUidRequests.has(cacheKey)) return this.pendingUidRequests.get(cacheKey);
+    const promise = (async () => {
+      try {
+        const existing = await this.ctx.database.get("analyse_user", { channelId, userId }, ["uid"]);
+        if (existing.length > 0) {
+          this.uidCache.set(cacheKey, existing[0].uid);
+          return existing[0].uid;
+        }
+        const [guild, member] = await Promise.all([
+          guildId ? bot.getGuild(guildId).catch(() => null) : Promise.resolve(null),
+          guildId ? bot.getGuildMember(guildId, userId).catch(() => null) : Promise.resolve(null)
+        ]);
+        const user = !member ? await bot.getUser(userId).catch(() => null) : null;
+        const newUser = await this.ctx.database.create("analyse_user", {
+          channelId,
+          userId,
+          channelName: guild?.name || channelId,
+          userName: member?.nick || member?.name || user?.name || userId
+        });
+        this.uidCache.set(cacheKey, newUser.uid);
+        return newUser.uid;
+      } catch (error) {
+        this.ctx.logger.error(`创建或获取用户(${cacheKey}) UID 失败:`, error);
+        return null;
+      } finally {
+        this.pendingUidRequests.delete(cacheKey);
       }
-    }).join("");
+    })();
+    this.pendingUidRequests.set(cacheKey, promise);
+    return promise;
   }
   /**
-   * 将内存缓冲区的消息批量写入数据库，并处理写入失败的情况。
+   * @private
+   * @method sanitizeContent
+   * @description 将 Koishi 的消息元素 (Element) 数组净化为纯文本字符串，以便存储和分析。
+   * @param {Element[]} elements - 消息元素的数组。
+   * @returns {string} 净化后的纯文本字符串。
    */
-  async flushBuffer() {
-    if (this.msgBuffer.length === 0) return;
-    const bufferToFlush = this.msgBuffer;
-    this.msgBuffer = [];
-    try {
-      await this.ctx.database.upsert("analyse_msg", bufferToFlush);
-    } catch (error) {
-      this.ctx.logger.error("数据写入失败:", error);
-      this.msgBuffer.unshift(...bufferToFlush);
+  sanitizeContent = /* @__PURE__ */ __name((elements) => elements.map((e) => {
+    switch (e.type) {
+      case "text":
+        return e.attrs.content;
+      case "img":
+        return e.attrs.summary === "[动画表情]" ? "[gif]" : "[img]";
+      case "at":
+        return `[at:${e.attrs.id}]`;
+      default:
+        return `[${e.type}]`;
     }
-  }
+  }).join(""), "sanitizeContent");
   /**
-   * 检查用户和群组名称是否需要更新，利用缓存和请求锁机制避免重复调用。
-   * @param session {Session} 消息会话对象。
-   * @param effectiveId {string} 有效的频道/群组ID。
+   * @private
+   * @async
+   * @method flushCacheBuffer
+   * @description 将内存中的消息缓存 (`cacheBuffer`) 批量写入数据库。
    */
-  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);
-    if (cached && Date.now() - cached.timestamp < CACHE_EXPIRATION) return;
-    const promise = this.fetchAndUpdateNames(session, effectiveId, cacheKey);
-    this.pendingNameRequests.set(cacheKey, promise);
-    promise.finally(() => this.pendingNameRequests.delete(cacheKey));
-  }
-  /**
-   * 异步获取用户和群组的最新名称，并更新到数据库和内存缓存。
-   * @param session {Session} 消息会话对象。
-   * @param effectiveId {string} 频道/群组ID。
-   * @param cacheKey {string} 用于缓存的键。
-   */
-  async fetchAndUpdateNames(session, effectiveId, cacheKey) {
+  async flushCacheBuffer() {
+    if (this.cacheBuffer.length === 0) return;
+    const bufferToFlush = this.cacheBuffer;
+    this.cacheBuffer = [];
     try {
-      const { userId, guildId, bot } = session;
-      const [guild, member] = await Promise.all([
-        guildId ? bot.getGuild(guildId).catch(() => null) : Promise.resolve(null),
-        guildId && userId ? bot.getGuildMember(guildId, userId).catch(() => null) : Promise.resolve(null)
-      ]);
-      const channelName = guild?.name;
-      const userName = member?.nick || member?.name;
-      if (!channelName || !userName) {
-        this.nameCache.set(cacheKey, { name: null, timestamp: Date.now() });
-        return;
-      }
-      await this.ctx.database.upsert("analyse_name", [{
-        channelId: effectiveId,
-        userId,
-        channelName,
-        userName
-      }]);
-      this.nameCache.set(cacheKey, { name: userName, timestamp: Date.now() });
+      await this.ctx.database.upsert("analyse_cache", bufferToFlush);
     } catch (error) {
-      this.nameCache.set(cacheKey, { name: null, timestamp: Date.now() });
+      this.ctx.logger.error("写入缓存出错:", error);
     }
   }
 };
 
-// src/CmdStat.ts
-var import_koishi2 = require("koishi");
+// src/Stat.ts
+var import_koishi3 = require("koishi");
 
 // src/Renderer.ts
-var import_koishi = require("koishi");
+var import_koishi2 = require("koishi");
 var Renderer = class {
   /**
    * @constructor
-   * @param ctx {Context} Koishi 上下文，用于访问 puppeteer 服务。
+   * @param {Context} ctx - Koishi 的插件上下文，用于访问 puppeteer 服务。
    */
   constructor(ctx) {
     this.ctx = ctx;
@@ -200,10 +242,13 @@ var Renderer = class {
     __name(this, "Renderer");
   }
   /**
-   * 将列表数据渲染为图片。
-   * @param data {ListRenderData} 待渲染的列表数据。
-   * @param headers {string[]} (可选) 表头文案数组，若不提供则不渲染表头。
-   * @returns {Promise<string | Buffer>} 成功时返回图片 Buffer，无数据时返回提示文本。
+   * @public
+   * @async
+   * @method renderList
+   * @description 将列表数据渲染为图片。
+   * @param {ListRenderData} data - 待渲染的完整列表数据。
+   * @param {string[]} [headers] - (可选) 表头文案数组。如果提供，将会在表格顶部渲染表头。
+   * @returns {Promise<string | Buffer>} 渲染成功时返回图片的 Buffer 数据；如果输入数据为空，则返回提示文本。
    */
   async renderList(data, headers) {
     const htmlContent = this.generateListHtml(data, headers);
@@ -211,23 +256,27 @@ var Renderer = class {
     return this.ctx.puppeteer.render(htmlContent);
   }
   /**
-   * 智能格式化日期，提供相对时间（如“刚刚”，“x分钟前”）和绝对日期。
-   * @param date {Date} 待格式化的日期对象。
+   * @private
+   * @method formatDate
+   * @description 智能格式化日期。对于近期的时间，提供更人性化的相对时间描述（如“刚刚”，“x 分钟前”）；对于较早的时间，则显示标准的“年-月-日”格式。
+   * @param {Date} date - 待格式化的 Date 对象。
    * @returns {string} 格式化后的日期字符串。
    */
   formatDate(date) {
     if (!date) return "未知";
     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)} 小时前`;
+    if (diff < import_koishi2.Time.minute) return "刚刚";
+    if (diff < import_koishi2.Time.hour) return `${Math.floor(diff / import_koishi2.Time.minute)} 分钟前`;
+    if (diff < import_koishi2.Time.day) return `${Math.floor(diff / import_koishi2.Time.hour)} 小时前`;
     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。
+   * @private
+   * @method generateListHtml
+   * @description 根据传入的结构化数据和表头，动态生成用于 Puppeteer 渲染的完整 HTML 字符串。
+   * @param {ListRenderData} data - 列表数据对象。
+   * @param {string[]} [headers] - (可选) 表头数组。
+   * @returns {string | null} 返回生成的 HTML 字符串。如果列表数据为空，则返回 `null`。
    */
   generateListHtml(data, headers) {
     const { title, time, total, list } = data;
@@ -292,102 +341,164 @@ var Renderer = class {
   }
 };
 
-// src/CmdStat.ts
-var CmdStat = class {
-  constructor(ctx) {
+// src/Stat.ts
+var Stat = class {
+  /**
+   * @constructor
+   * @param {Context} ctx - Koishi 的插件上下文。
+   * @param {Config} config - 插件的配置对象。
+   */
+  constructor(ctx, config) {
     this.ctx = ctx;
+    this.config = config;
     this.renderer = new Renderer(ctx);
-    this.ctx.model.extend("analyse_cmd", {
-      channelId: "string",
-      userId: "string",
-      command: "string",
-      count: "unsigned",
-      timestamp: "timestamp"
-    }, { primary: ["channelId", "userId", "command"] });
-    this.ctx.on("command/before-execute", async ({ command, session }) => {
-      const { userId, guildId } = session;
-      if (!guildId || !userId) return;
-      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),
-        timestamp: /* @__PURE__ */ new Date()
-      }]);
-    });
   }
   static {
-    __name(this, "CmdStat");
+    __name(this, "Stat");
   }
   renderer;
   /**
-   * 注册所有相关的子命令到主 `analyse` 命令下。
-   * @param analyse {Command} 主 `analyse` 命令实例。
+   * @method registerCommands
+   * @description 根据插件配置，动态地将 `.command` 和 `.message` 子命令注册到主 `analyse` 命令下。
+   * @param {Command} analyse - 主 `analyse` 命令实例。
    */
   registerCommands(analyse) {
-    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 "私聊中请使用 -g <群组ID> 指定群组。";
-        guildId = session.guildId;
-      }
-      try {
-        const stats = await this.getCommandStats(guildId, userId);
-        if (typeof stats === "string") return stats;
-        const title = await this.generateTitle(session, guildId, userId);
-        const renderData = {
-          title,
-          time: /* @__PURE__ */ new Date(),
-          total: stats.total,
-          list: stats.list
-        };
-        const headers = ["命令", "次数", "上次使用"];
-        const result = await this.renderer.renderList(renderData, headers);
-        return Buffer.isBuffer(result) ? import_koishi2.Element.image(result, "image/png") : result;
-      } catch (error) {
-        this.ctx.logger.error("渲染统计图片失败:", error);
-        return "渲染统计图片失败";
-      }
-    });
+    if (this.config.enableCmdStat) {
+      analyse.subcommand(".command", "命令使用统计").option("user", "-u [user:user] 查看指定用户的统计").option("guild", "-g [guildId:string] 查看指定群组的统计 (默认当前群)").usage("查询命令使用统计。支持按用户、按群组或组合查询。").action(async ({ session, options }) => {
+        const userId = options.user ? import_koishi3.h.select(options.user, "user")[0]?.attrs.id : void 0;
+        let guildId = options.guild;
+        if (options.guild === "" && !options.user) {
+          if (!session.guildId) return "私聊中请使用 -g <群组ID> 指定群组。";
+          guildId = session.guildId;
+        }
+        try {
+          const stats = await this.getCommandStats(guildId, userId);
+          if (typeof stats === "string") return stats;
+          const title = await this._generateTitle(session, guildId, userId, "命令");
+          const renderData = {
+            title,
+            time: /* @__PURE__ */ new Date(),
+            total: stats.total,
+            list: stats.list
+          };
+          const headers = ["命令", "次数", "上次使用"];
+          const result = await this.renderer.renderList(renderData, headers);
+          return Buffer.isBuffer(result) ? import_koishi3.Element.image(result, "image/png") : result;
+        } catch (error) {
+          this.ctx.logger.error("渲染命令统计图片失败:", error);
+          return "渲染命令统计图片失败";
+        }
+      });
+    }
+    if (this.config.enableMsgStat) {
+      analyse.subcommand(".message", "消息类型统计").option("user", "-u [user:user] 查看指定用户的统计").option("guild", "-g [guildId:string] 查看指定群组的统计 (默认当前群)").usage("查询消息类型统计。支持按用户、按群组或组合查询。").action(async ({ session, options }) => {
+        const userId = options.user ? import_koishi3.h.select(options.user, "user")[0]?.attrs.id : void 0;
+        let guildId = options.guild;
+        if (options.guild === "" && !options.user) {
+          if (!session.guildId) return "私聊中请使用 -g <群组ID> 指定群组。";
+          guildId = session.guildId;
+        }
+        try {
+          const stats = await this.getMessageStats(guildId, userId);
+          if (typeof stats === "string") return stats;
+          const title = await this._generateTitle(session, guildId, userId, "消息");
+          const renderData = {
+            title,
+            time: /* @__PURE__ */ new Date(),
+            total: stats.total,
+            list: stats.list
+          };
+          const headers = ["消息类型", "条数", "上次发送"];
+          const result = await this.renderer.renderList(renderData, headers);
+          return Buffer.isBuffer(result) ? import_koishi3.Element.image(result, "image/png") : result;
+        } catch (error) {
+          this.ctx.logger.error("渲染消息统计图片失败:", error);
+          return "渲染消息统计图片失败";
+        }
+      });
+    }
   }
   /**
-   * 根据查询参数动态生成图片标题。
+   * @private
+   * @async
+   * @method _generateTitle
+   * @description 通用的标题生成器。根据查询参数 (guildId, userId) 和统计类型动态生成易于理解的图片标题。
+   * @param {Session} session - 当前会话，备用。
+   * @param {string} [guildId] - (可选) 查询的群组 ID。
+   * @param {string} [userId] - (可选) 查询的用户 ID。
+   * @param {'命令' | '消息'} type - 统计类型，用于嵌入标题文本中。
+   * @returns {Promise<string>} 生成的标题字符串。
    */
-  async generateTitle(session, guildId, userId) {
+  async _generateTitle(session, guildId, userId, type) {
     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} 的命令统计`;
+      const user = await this.ctx.database.get("analyse_user", { channelId: guildId, userId }, ["userName"]);
+      const guild = await this.ctx.database.get("analyse_user", { channelId: guildId }, ["channelName"]);
+      const userName = user[0]?.userName || userId;
+      const guildName = guild[0]?.channelName || guildId;
+      return `${userName} 在 ${guildName} 的${type}统计`;
     }
     if (userId) {
-      const userName = (await session.bot.getUser(userId).catch(() => null))?.name || userId;
-      return `${userName} 的全局命令统计`;
+      const user = await this.ctx.database.get("analyse_user", { userId }, ["userName"]);
+      const userName = user[0]?.userName || userId;
+      return `${userName} 的全局${type}统计`;
     }
     if (guildId) {
-      const guildName = (await session.bot.getGuild(guildId).catch(() => null))?.name || guildId;
-      return `${guildName} 的命令统计`;
+      const guild = await this.ctx.database.get("analyse_user", { channelId: guildId }, ["channelName"]);
+      const guildName = guild[0]?.channelName || guildId;
+      return `${guildName} 的${type}统计`;
     }
-    return "全局命令统计";
+    return `全局${type}统计`;
   }
   /**
-   * 从数据库获取并聚合命令统计数据。
-   * @param guildId {string} (可选) 群组ID。
-   * @param userId {string} (可选) 用户ID。
-   * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 包含结果列表和总数的对象，或错误/提示信息。
+   * @private
+   * @async
+   * @method getCommandStats
+   * @description 从数据库中获取并聚合命令使用统计数据。
+   * @param {string} [guildId] - (可选) 若提供，则将范围限制在此群组。
+   * @param {string} [userId] - (可选) 若提供，则将范围限制在此用户。
+   * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 返回一个包含列表和总数的对象，或在无数据时返回提示字符串。
    */
   async getCommandStats(guildId, userId) {
-    const query = {};
-    if (guildId) query.channelId = guildId;
-    if (userId) query.userId = userId;
-    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")
+    const userQuery = {};
+    if (guildId) userQuery.channelId = guildId;
+    if (userId) userQuery.userId = userId;
+    const users = await this.ctx.database.get("analyse_user", userQuery, ["uid"]);
+    if (users.length === 0) return "暂无目标用户的统计数据";
+    const uids = users.map((u) => u.uid);
+    const aggregatedStats = await this.ctx.database.select("analyse_cmd").where({ uid: { $in: 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 (aggregatedStats.length === 0) return "暂无统计数据";
     const totalCount = aggregatedStats.reduce((sum, record) => sum + record.count, 0);
     const list = aggregatedStats.map((item) => [item.command, item.count, item.lastUsed]);
     return { list, total: totalCount };
   }
+  /**
+   * @private
+   * @async
+   * @method getMessageStats
+   * @description 从数据库中获取并聚合消息类型统计数据。
+   * @param {string} [guildId] - (可选) 若提供，则将范围限制在此群组。
+   * @param {string} [userId] - (可选) 若提供，则将范围限制在此用户。
+   * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 返回一个包含列表和总数的对象，或在无数据时返回提示字符串。
+   */
+  async getMessageStats(guildId, userId) {
+    const userQuery = {};
+    if (guildId) userQuery.channelId = guildId;
+    if (userId) userQuery.userId = userId;
+    const users = await this.ctx.database.get("analyse_user", userQuery, ["uid"]);
+    if (users.length === 0) return "暂无目标用户的统计数据";
+    const uids = users.map((u) => u.uid);
+    const aggregatedStats = await this.ctx.database.select("analyse_msg").where({ uid: { $in: uids } }).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 (aggregatedStats.length === 0) return "暂无统计数据";
+    const totalCount = aggregatedStats.reduce((sum, record) => sum + record.count, 0);
+    const list = aggregatedStats.map((item) => [item.type, item.count, item.lastUsed]);
+    return { list, total: totalCount };
+  }
 };
 
 // src/index.ts
@@ -405,12 +516,20 @@ var usage = `
 `;
 var name = "chat-analyse";
 var using = ["database", "puppeteer"];
-var Config = import_koishi3.Schema.object({});
-function apply(ctx) {
-  new Collector(ctx);
-  const cmd = new CmdStat(ctx);
+var Config = import_koishi4.Schema.intersect([
+  import_koishi4.Schema.object({
+    enableListener: import_koishi4.Schema.boolean().default(true).description("开启监听")
+  }).description("基本设置"),
+  import_koishi4.Schema.object({
+    enableCmdStat: import_koishi4.Schema.boolean().default(true).description("启用命令统计"),
+    enableMsgStat: import_koishi4.Schema.boolean().default(true).description("启用消息统计"),
+    enableAdvanced: import_koishi4.Schema.boolean().default(true).description("启用原始记录")
+  }).description("功能开关")
+]);
+function apply(ctx, config) {
+  if (config.enableListener) new Collector(ctx, config);
   const analyse = ctx.command("analyse", "聊天记录分析");
-  cmd.registerCommands(analyse);
+  new Stat(ctx, config).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.2.4",
+  "version": "0.2.6",
   "contributors": [
     "Yis_Rime <yis_rime@outlook.com>"
   ],

package/lib/CmdStat.d.ts

@@ -1,38 +0,0 @@
-import { Context, Command } from 'koishi';
-import { Renderer } from './Renderer';
-declare module 'koishi' {
-    interface Tables {
-        analyse_cmd: {
-            channelId: string;
-            userId: string;
-            command: string;
-            count: number;
-            timestamp: Date;
-        };
-    }
-}
-/**
- * @class CmdStat
- * @description 提供命令统计服务，处理用户查询并渲染结果。
- */
-export declare class CmdStat {
-    private ctx;
-    renderer: Renderer;
-    constructor(ctx: Context);
-    /**
-     * 注册所有相关的子命令到主 `analyse` 命令下。
-     * @param analyse {Command} 主 `analyse` 命令实例。
-     */
-    registerCommands(analyse: Command): void;
-    /**
-     * 根据查询参数动态生成图片标题。
-     */
-    private generateTitle;
-    /**
-     * 从数据库获取并聚合命令统计数据。
-     * @param guildId {string} (可选) 群组ID。
-     * @param userId {string} (可选) 用户ID。
-     * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 包含结果列表和总数的对象，或错误/提示信息。
-     */
-    private getCommandStats;
-}