koishi-plugin-chat-analyse 0.4.9 → 0.4.10

package/lib/Collector.d.ts

@@ -44,14 +44,14 @@ declare module 'koishi' {
 }
 /**
  * @class Collector
- * @description 核心数据收集器。根据插件配置，高效地监听、收集、缓冲并持久化聊天数据。
+ * @description 核心数据收集器。根据配置，高效地监听、收集、缓冲并持久化聊天数据。
  */
 export declare class Collector {
     private ctx;
     private config;
-    /** @const {number} FLUSH_INTERVAL - 内存缓存区自动刷新到数据库的时间间隔。 */
+    /** @property FLUSH_INTERVAL - 内存缓存区定时刷入数据库的间隔（毫秒）。 */
     private static readonly FLUSH_INTERVAL;
-    /** @const {number} BUFFER_THRESHOLD - 内存缓存区触发自动刷新的消息数量阈值。 */
+    /** @property BUFFER_THRESHOLD - 内存缓存区触发刷新的消息数量阈值。 */
     private static readonly BUFFER_THRESHOLD;
     private msgStatBuffer;
     private rankStatBuffer;
@@ -62,48 +62,26 @@ export declare class Collector {
     private pendingUserRequests;
     private flushInterval;
     /**
-     * @constructor
-     * @param {Context} ctx - Koishi 的插件上下文。
-     * @param {Config} config - 插件的配置对象。
+     * @param ctx - Koishi 的插件上下文。
+     * @param config - 插件的配置对象。
      */
     constructor(ctx: Context, config: Config);
     /**
-     * @private
-     * @method defineModels
-     * @description 定义插件所需的所有数据表模型。
+     * @private @method onMessage
+     * @description 统一的消息事件处理器，解析消息并更新各类统计数据的缓冲区。
+     * @param session - Koishi 的会话对象。
      */
-    private defineModels;
+    private onMessage;
     /**
-     * @private
-     * @async
-     * @method handleMessage
-     * @description 统一的消息和命令处理器。它会解析收到的消息，提取关键信息并更新相应的统计数据。
-     * @param {Session} session - Koishi 的会话对象，包含消息的全部信息。
-     */
-    private handleMessage;
-    /**
-     * @private
-     * @async
-     * @method getOrCreateCachedUser
-     * @description 高效地获取或创建用户的中央记录，并全面利用缓存。
-     * @param {Session} session - Koishi 会话对象，用于获取用户信息和 Bot 实例。
-     * @param {string} channelId - 消息所在的频道或群组 ID。
-     * @returns {Promise<UserCache | null>} 返回用户的缓存对象，如果操作失败则返回 `null`。
-     */
-    private getOrCreateCachedUser;
-    /**
-     * @private
-     * @method sanitizeContent
-     * @description 将 Koishi 的消息元素 (Element) 数组净化为纯文本字符串，以便存储和分析。
-     * @param {Element[]} elements - 消息元素的数组。
-     * @returns {string} 净化后的纯文本字符串。
+     * @private @method sanitizeContent
+     * @description 将 Koishi 消息元素数组净化为纯文本字符串。
+     * @param elements - 消息元素数组。
+     * @returns 净化后的纯文本。
      */
     private sanitizeContent;
     /**
-     * @private
-     * @async
-     * @method flushBuffers
-     * @description 将所有内存中的缓冲区数据批量写入数据库。
+     * @private @method flushBuffers
+     * @description 将所有内存中的数据缓冲区批量写入数据库，并清空缓冲区。
      */
     private flushBuffers;
 }

package/lib/Data.d.ts

@@ -1,9 +1,7 @@
 import { Context, Command } from 'koishi';
 /**
  * @class Data
- * @description
- * 提供数据备份、恢复和清理的管理功能，恢复逻辑采用分批处理以优化性能。
- * 清理功能支持按表、时间范围和用户范围进行精确操作。
+ * @description 提供数据备份、恢复和清理等高级管理功能。恢复逻辑采用分批处理以优化性能。
  */
 export declare class Data {
     private ctx;
@@ -12,8 +10,8 @@ export declare class Data {
     /**
      * @public
      * @method registerCommands
-     * @description 在 'analyse.admin' 命令下注册所有数据管理相关的子命令。
-     * @param {Command} analyse - '.admin' 命令实例。
+     * @description 在 `analyse` 命令下注册所有数据管理相关的子命令 (`.backup`, `.restore`, `.clear`, `.list`)。
+     * @param analyse - 主 `analyse` 命令实例。
      */
     registerCommands(analyse: Command): void;
 }

package/lib/Renderer.d.ts

@@ -1,12 +1,9 @@
 import { Context } from 'koishi';
-/**
- * 定义了渲染列表中单行数据的格式。它是一个由字符串、数字或 `Date` 对象组成的数组。
- */
+/** 定义了渲染列表中单行数据的格式，是一个由字符串、数字或 `Date` 对象构成的数组。 */
 export type RenderListItem = (string | number | Date)[];
 /**
  * @interface ListRenderData
- * @description 定义了调用 `renderList` 方法所需的数据结构。
- * 它包含了渲染一张完整列表图片所必需的所有信息。
+ * @description 定义了调用 `renderList` 方法所需的数据结构，包含了渲染一张完整列表图片所必需的所有信息。
  */
 export interface ListRenderData {
     title: string;
@@ -16,45 +13,37 @@ export interface ListRenderData {
 }
 /**
  * @class Renderer
- * @classdesc
- * 负责将结构化的数据（特别是列表）转换为设计精美的PNG图片。
- * 其核心特性是能够动态计算内容尺寸，生成布局紧凑、自适应的图片。
+ * @description 负责将结构化的列表数据渲染为设计精美的 PNG 图片。其核心特性是能够动态计算内容尺寸，生成布局紧凑、自适应的图片。
  */
 export declare class Renderer {
     private ctx;
     /**
-     * @param {Context} ctx - Koishi 的插件上下文，用于访问核心服务如 `puppeteer` 和 `logger`。
+     * @param ctx - Koishi 的插件上下文，用于访问 `puppeteer` 等核心服务。
      */
     constructor(ctx: Context);
     /**
      * @private
      * @method htmlToImage
-     * @description
-     * 负责将任意HTML字符串转换为PNG图片Buffer。
-     * @param {string} html - 要渲染的HTML主体内容（不包含 `<html>` 和 `<body>` 标签）。
-     * @returns {Promise<Buffer>} 返回一个包含PNG图片数据的 Buffer 对象。
-     * @throws {Error} 如果 Puppeteer 截图过程中发生错误，将抛出异常。
+     * @description 将 HTML 字符串转换为 PNG 图片 Buffer。
+     * @param html - 要渲染的 HTML 主体内容。
+     * @returns 返回一个包含 PNG 图片数据的 Buffer。
      */
     private htmlToImage;
     /**
      * @private
      * @method formatDate
-     * @description
-     * 将 `Date` 对象格式化为人类友好的相对时间字符串。
-     * @param {Date} date - 需要格式化的日期对象。
-     * @returns {string} - 格式化后的时间字符串。
+     * @description 将 `Date` 对象格式化为易于理解的相对时间或绝对日期字符串。
+     * @param date - 需要格式化的日期对象。
+     * @returns 格式化后的时间字符串。
      */
     private formatDate;
     /**
      * @public
      * @method renderList
-     * @description
-     * 接收一个标准化的 `ListRenderData` 对象和可选的表头数组，
-     * 然后构建一个包含标题、统计信息和数据表格的完整HTML卡片。
-     * @param {ListRenderData} data - 包含渲染所需全部信息的对象。
-     * @param {string[]} [headers] - (可选) 表格的表头字符串数组。如果提供，将渲染表头。
-     * @returns {Promise<string | Buffer>}
-     * 如果成功，返回包含PNG图片的 Buffer。如果输入的数据列表为空，则返回一个提示性字符串。
+     * @description 构建并渲染一个包含标题、统计信息和数据表格的 HTML 卡片为图片。
+     * @param data - 包含渲染所需全部信息的对象。
+     * @param headers - (可选) 表格的表头字符串数组。
+     * @returns 成功时返回包含 PNG 图片的 Buffer，若列表为空则返回提示字符串。
      */
     renderList(data: ListRenderData, headers?: string[]): Promise<string | Buffer>;
 }

package/lib/Stat.d.ts

@@ -10,98 +10,28 @@ export declare class Stat {
     private config;
     renderer: Renderer;
     /**
-     * @constructor
-     * @param {Context} ctx - Koishi 的插件上下文。
-     * @param {Config} config - 插件的配置对象。
+     * @param ctx - Koishi 的插件上下文。
+     * @param config - 插件的配置对象。
      */
     constructor(ctx: Context, config: Config);
     /**
-     * @private
-     * @method setupCleanupTask
-     * @description 设置一个定时清理任务。
-     * 此任务会根据配置中的 `rankRetentionDays` 定期删除过期的发言排行数据，以防止数据库膨胀。
-     */
-    private setupCleanupTask;
-    /**
-     * @public
-     * @method registerCommands
-     * @description 根据插件配置，动态地将 `.cmd`, `.msg`, `.rank` 子命令注册到主 `analyse` 命令下。
-     * @param {Command} analyse - 主 `analyse` 命令实例。
+     * @public @method registerCommands
+     * @description 根据配置，动态地将 `.cmd`, `.msg`, `.rank` 子命令注册到主 `analyse` 命令下。
+     * @param analyse - 主 `analyse` 命令实例。
      */
     registerCommands(analyse: Command): void;
     /**
-     * @private
-     * @method parseQueryScope
-     * @description 解析命令的选项，将其转换为统一的查询范围对象（userId 和 guildId）。
-     * @param {Session} session - 当前会话对象。
-     * @param {QueryScopeOptions} options - 命令传入的选项。
-     * @returns {QueryScopeResult} 包含 userId、guildId 或 error 信息的查询范围对象。
+     * @private @method parseQueryScope
+     * @description 解析命令选项，转换为包含 UIDs 和描述性信息的统一查询范围对象。
+     * @param session - 当前会话对象。
+     * @param options - 命令选项。
+     * @returns 包含 uids、错误或范围描述的查询范围对象。
      */
     private parseQueryScope;
     /**
-     * @private
-     * @async
-     * @method getUidsInScope
-     * @description 根据查询范围（guildId, userId）获取匹配用户的 UID 列表。
-     * @param {string} [guildId] - (可选) 群组 ID。
-     * @param {string} [userId] - (可选) 用户 ID。
-     * @returns {Promise<{ uids?: number[], error?: string }>} 包含 UID 数组或错误信息的对象。
-     */
-    private getUidsInScope;
-    /**
-     * @private
-     * @async
-     * @method generateTitle
-     * @description 通用的标题生成器。根据查询参数和类型选项动态生成易于理解的图片标题。
-     * @param {string} [guildId] - (可选) 查询的群组 ID。
-     * @param {string} [userId] - (可选) 查询的用户 ID。
-     * @param {object} options - 标题的配置选项。
-     * @param {'命令' | '消息' | '排行'} options.main - 标题主类型。
-     * @param {string} [options.subtype] - (可选) 消息类型的子类型。
-     * @param {number} [options.timeRange] - (可选) 排行的时间范围（小时）。
-     * @returns {Promise<string>} 生成的标题字符串。
+     * @private @method generateTitle
+     * @description 根据查询范围和类型动态生成易于理解的图片标题。
+     * @returns 生成的标题字符串。
      */
     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 getUserMessageStats
-     * @description 从数据库中获取并聚合每个用户的消息统计数据。
-     * @param {string} [guildId] - (可选) 若提供，则将范围限制在此群组。
-     * @param {string} [userId] - (可选) 若提供，则将范围限制在此用户。
-     * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 返回一个包含列表和总数的对象，或在无数据时返回提示字符串。
-     */
-    private getUserMessageStats;
-    /**
-     * @private
-     * @async
-     * @method getMessageStatsByType
-     * @description 按指定消息类型，从数据库中获取并聚合用户排行数据。
-     * @param {string} type - 要查询的消息类型。
-     * @param {string} [guildId] - (可选) 若提供，则将范围限制在此群组。
-     * @param {string} [userId] - (可选) 若提供，则将范围限制在此用户。
-     * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 返回一个包含列表和总数的对象，或在无数据时返回提示字符串。
-     */
-    private getMessageStatsByType;
-    /**
-     * @private
-     * @async
-     * @method getActiveUserStats
-     * @description 从数据库中获取并聚合指定时间范围内的活跃用户排行数据。
-     * @param {number} hours - 查询过去的小时数。
-     * @param {string} [guildId] - (可选) 要查询的群组 ID。若不提供，则进行全局排行。
-     * @param {string} [type] - (可选) 要筛选的消息类型。
-     * @returns {Promise<{ list: RenderListItem[], total: number } | string>} 返回一个包含列表和总数的对象，或在无数据时返回提示字符串。
-     */
-    private getActiveUserStats;
 }

package/lib/WhoAt.d.ts

@@ -2,33 +2,20 @@ import { Context, Command } from 'koishi';
 import { Config } from './index';
 /**
  * @class WhoAt
- * @description
- * 负责处理与“谁@我”相关的功能。
- * 该类会注册一个 'whoatme' 子命令，允许用户查询在何时被谁提及。
- * 查询结果将以合并转发的形式发送给用户。
- * 此外，该类还包含一个定时任务，用于定期清理数据库中旧的@记录。
+ * @description 负责处理“谁@我”相关功能，包括查询和定时清理。
  */
 export declare class WhoAt {
     private ctx;
     private config;
     /**
-     * WhoAt 类的构造函数。
-     * @param {Context} ctx - Koishi 的插件上下文，用于访问框架核心功能和数据库等服务。
-     * @param {Config} config - 插件的配置对象，包含如记录保留天数等设置。
+     * @param ctx - Koishi 的插件上下文。
+     * @param config - 插件的配置对象。
      */
     constructor(ctx: Context, config: Config);
     /**
-     * @private
-     * @method setupCleanupTask
-     * @description 设置一个定时清理任务。
-     * 此任务会根据配置中的 `atRetentionDays` 定期删除过期的@记录，以防止数据库膨胀。
-     */
-    private setupCleanupTask;
-    /**
-     * @public
-     * @method registerCommand
+     * @public @method registerCommand
      * @description 在主 `analyse` 命令下注册 `whoatme` 子命令。
-     * @param {Command} analyse - 用户传入的主 `analyse` 命令实例，`whoatme` 将作为其子命令。
+     * @param analyse - 主 `analyse` 命令实例。
      */
     registerCommand(analyse: Command): void;
 }

package/lib/index.d.ts

@@ -1,8 +1,5 @@
 import { Context, Schema } from 'koishi';
-/**
- * @name 插件使用说明
- * @description 在 Koishi 控制台中显示的插件介绍和帮助信息。
- */
+/** @name 插件使用说明 */
 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[];
@@ -21,15 +18,12 @@ export interface Config {
     atRetentionDays: number;
     rankRetentionDays: number;
 }
-/**
- * @const {Schema<Config>} Config
- * @description 使用 Koishi 的 `Schema` 来定义配置项的类型、默认值和在控制台中的交互界面。
- */
+/** @description 插件的配置项定义，使用 Koishi Schema 构建。 */
 export declare const Config: Schema<Config>;
 /**
  * @function apply
- * @description Koishi 插件的主入口函数。
- * @param {Context} ctx - Koishi 的插件上下文，提供了访问核心 API 的能力。
- * @param {Config} config - 用户在 `koishi.config.js` 或控制台中配置的对象。
+ * @description Koishi 插件的主入口函数，负责初始化和注册所有功能模块。
+ * @param ctx - Koishi 的插件上下文。
+ * @param config - 用户配置对象。
  */
 export declare function apply(ctx: Context, config: Config): void;