koishi-plugin-chat-analyse 0.7.0 → 1.0.0

package/lib/index.d.ts

@@ -19,6 +19,7 @@ export interface Config {
     atRetentionDays: number;
     rankRetentionDays: number;
     enableWordCloud: boolean;
+    cacheRetentionDays: number;
 }
 /** @description 插件的配置项定义 */
 export declare const Config: Schema<Config>;

package/lib/index.js

@@ -879,6 +879,12 @@ var Analyse = class {
     this.config = config;
     this.renderer = new Renderer(ctx);
     if (config.enableWordCloud) this.jieba = import_jieba.Jieba.withDict(import_dict.dict);
+    if (this.config.enableOriRecord && this.config.cacheRetentionDays > 0) {
+      this.ctx.cron("0 0 * * *", async () => {
+        const cutoffDate = new Date(Date.now() - this.config.cacheRetentionDays * import_koishi6.Time.day);
+        await this.ctx.database.remove("analyse_cache", { timestamp: { $lt: cutoffDate } }).catch((e) => this.ctx.logger.error("清理原始记录缓存失败:", e));
+      });
+    }
   }
   static {
     __name(this, "Analyse");
@@ -923,7 +929,7 @@ var Analyse = class {
         });
         if (!words.length) return "暂无有效词语";
         const wordCounts = words.reduce((map, word) => map.set(word, (map.get(word) || 0) + 1), /* @__PURE__ */ new Map());
-        const wordList = Array.from(wordCounts.entries()).sort((a, b) => b[1] - a[1]).slice(0, 150);
+        const wordList = Array.from(wordCounts.entries()).sort((a, b) => b[1] - a[1]);
         const title = await generateTitle(this.ctx, scope.scopeDesc, { main: "词云" });
         const result = await this.renderer.renderWordCloud({ title, time: /* @__PURE__ */ new Date(), words: wordList });
         if (typeof result === "string") return result;
@@ -960,12 +966,13 @@ var Config3 = import_koishi7.Schema.intersect([
     enableMsgStat: import_koishi7.Schema.boolean().default(true).description("启用消息统计"),
     enableActivity: import_koishi7.Schema.boolean().default(true).description("启用活跃统计"),
     enableRankStat: import_koishi7.Schema.boolean().default(true).description("启用发言排行"),
-    rankRetentionDays: import_koishi7.Schema.number().min(0).default(31).description("排行保留天数"),
+    rankRetentionDays: import_koishi7.Schema.number().min(0).default(365).description("排行保留天数"),
     enableWhoAt: import_koishi7.Schema.boolean().default(true).description("启用提及记录"),
     atRetentionDays: import_koishi7.Schema.number().min(0).default(7).description("提及保留天数")
   }).description("基础分析配置"),
   import_koishi7.Schema.object({
     enableOriRecord: import_koishi7.Schema.boolean().default(true).description("启用原始记录"),
+    cacheRetentionDays: import_koishi7.Schema.number().min(0).default(180).description("记录保留天数"),
     enableWordCloud: import_koishi7.Schema.boolean().default(true).description("启用词云生成")
   }).description("高级分析配置")
 ]);

package/package.json

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

package/readme.md

@@ -2,4 +2,80 @@
 
 [![npm](https://img.shields.io/npm/v/koishi-plugin-chat-analyse?style=flat-square)](https://www.npmjs.com/package/koishi-plugin-chat-analyse)
 
-聊天记录分析
+强大而全面的聊天数据分析，支持统计命令，发言，消息类型，活跃度，支持发言排行和生成词云
+
+## ✨ 功能特性
+
+- **高效数据收集**：采用异步、高并发和缓存机制，在不影响机器人性能的前提下，精确高效地收集聊天数据。
+- **多维度统计分析**：
+  - **命令统计** (`cmdstat`)：追踪指令使用频率，了解用户最常用的功能。
+  - **发言统计** (`msgstat`)：分析用户发言类型与数量，掌握核心用户群体。
+  - **发言排行** (`rankstat`)：生成指定时间范围内的用户发言排行榜。
+  - **活跃度分析** (`activity`)：以小时或天为单位，生成直观的周期性活跃度图表。
+- **高级文本分析**：
+  - **词云生成** (`wordcloud`)：基于聊天记录，利用 Jieba 分词生成热门话题词云图。
+  - **提及追踪** (`whoatme`)：轻松查询谁在什么时候因为什么内容提及了您。
+- **强大的数据管理**：
+  - **备份与恢复** (`backup`/`restore`)：一键备份所有统计数据至本地，并可随时恢复，保障数据安全。
+  - **精确清理** (`clear`)：提供多维度的筛选条件（如按时间、用户、群组、命令），精确清理不再需要的数据。
+- **精美图表渲染**：借助 Puppeteer 服务，将复杂的统计数据渲染成美观、易读的图片，方便在聊天中分享。
+- **高度可配置**：所有功能模块均可独立开关，并可自定义数据保留时长等核心参数，以适应不同场景的需求。
+
+### 前置服务
+
+本插件依赖以下 Koishi 服务，请确保您已正确安装并启用了它们：
+
+- `database`：用于存储所有统计分析数据。
+- `puppeteer`：用于将统计结果渲染成图片。
+- `cron`：用于执行数据定时清理任务。
+
+## 📝 使用说明
+
+所有功能都集成在主指令 `analyse` 之下。
+
+### 指令列表
+
+| 指令 | 别名 | 描述 | 选项 |
+| --- | --- | --- | --- |
+| `analyse.cmdstat` | 命令统计 | 查询命令使用情况 | `-u <user>` (指定用户), `-g <guild>` (指定群组), `-a` (全局), `-h` (分离子指令) |
+| `analyse.msgstat` | 发言统计 | 查询用户发言统计 | `-u <user>`, `-g <guild>`, `-a` (全局), `-t <type>` (指定消息类型) |
+| `analyse.rankstat` | 发言排行 | 查询指定时间内的发言排行 | `-g <guild>`, `-a` (全局), `-t <type>`, `-h <hours>` (默认24小时) |
+| `analyse.activity` | 活跃统计 | 查询周期性活跃度图表 | `-u <user>`, `-g <guild>`, `-a` (全局), `-d` (按天), `-h <hours>` (小时偏移) |
+| `analyse.wordcloud` | 生成词云 | 基于聊天记录生成词云图 | `-u <user>`, `-g <guild>`, `-a` (全局), `-h <hours>` (默认24小时) |
+| `analyse.whoatme` | 谁提及我 | 查看最近谁提及了您 | (无) |
+| `analyse.list` | 列出数据 | 列出已记录的频道和命令 | (无) |
+| `analyse.backup` | 备份数据 | 将所有数据备份为本地 JSON 文件 | (无) |
+| `analyse.restore` | 恢复数据 | 从本地 JSON 文件恢复数据 | (无) |
+| `analyse.clear` | 清除数据 | 根据条件精确清理数据 | `-t <table>`, `-g <guild>`, `-u <user>`, `-d <days>`, `-c <command>`, `-a` (全部) |
+
+**通用查询范围说明：**
+
+- 不带任何范围选项时，默认查询**当前群组**。
+- 使用 `-u <user>` 可指定用户 (支持 @某人)。
+- 使用 `-g <guild>` 可指定群组 ID。
+- 使用 `-a` 将忽略其他范围限制，查询**全局**数据。
+
+### 配置项
+
+您可以在插件的配置页面中调整以下选项：
+
+#### 杂项配置
+
+- `enableListener`: **启用消息监听**。总开关，关闭后插件将停止所有数据收集。 (默认: `true`)
+- `enableDataIO`: **启用数据管理**。控制 `.backup`, `.restore`, `.clear`, `.list` 等指令的可用性。 (默认: `true`)
+
+#### 基础分析配置
+
+- `enableCmdStat`: **启用命令统计**。 (默认: `true`)
+- `enableMsgStat`: **启用消息统计**。 (默认: `true`)
+- `enableActivity`: **启用活跃统计**。 (默认: `true`)
+- `enableRankStat`: **启用发言排行**。 (默认: `true`)
+- `rankRetentionDays`: **排行保留天数**。发言排行数据的保留时长（天），`0` 为永久保留。 (默认: `31`)
+- `enableWhoAt`: **启用提及记录**。 (默认: `true`)
+- `atRetentionDays`: **提及保留天数**。`whoatme` 数据的保留时长（天），`0` 为永久保留。 (默认: `7`)
+
+#### 高级分析配置
+
+- `enableOriRecord`: **启用原始记录**。是否记录原始消息内容以供词云等功能使用。 (默认: `true`)
+- `enableWordCloud`: **启用词云生成**。 (默认: `true`)
+- `cacheRetentionDays`: **原始记录保留天数**。原始消息记录的保留时长（天），`0` 为永久保留。 (默认: `180`)

package/lib/Analyse.d.ts

@@ -1,24 +0,0 @@
-import { Context, Command } from 'koishi';
-import { Config } from './index';
-export interface WordCloudData {
-    title: string;
-    time: Date;
-    words: [string, number][];
-}
-/**
- * @class Analyse
- * @description 提供文本分析功能，如生成词云。
- */
-export declare class Analyse {
-    private ctx;
-    private config;
-    private renderer;
-    private readonly jieba;
-    constructor(ctx: Context, config: Config);
-    /**
-     * @public @method registerCommands
-     * @description 在主命令下注册子命令。
-     * @param cmd - 主命令实例。
-     */
-    registerCommands(cmd: Command): void;
-}

package/lib/Collector.d.ts

@@ -1,86 +0,0 @@
-import { Context } from 'koishi';
-import { Config } from './index';
-declare module 'koishi' {
-    interface Tables {
-        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;
-            count: number;
-            timestamp: Date;
-        };
-        analyse_rank: {
-            uid: number;
-            type: string;
-            count: number;
-            timestamp: Date;
-        };
-        analyse_cache: {
-            id: number;
-            uid: number;
-            content: string;
-            timestamp: Date;
-        };
-        analyse_at: {
-            id: number;
-            uid: number;
-            target: string;
-            content: string;
-            timestamp: Date;
-        };
-    }
-}
-/**
- * @class Collector
- * @description 核心数据收集器。根据配置，高效地监听、收集、缓冲并持久化聊天数据。
- */
-export declare class Collector {
-    private ctx;
-    private config;
-    private static readonly FLUSH_INTERVAL;
-    private static readonly BUFFER_THRESHOLD;
-    private msgStatBuffer;
-    private rankStatBuffer;
-    private cmdStatBuffer;
-    private oriCacheBuffer;
-    private whoAtBuffer;
-    private userCache;
-    private channelCache;
-    private pendingRequests;
-    private flushInterval;
-    /**
-     * @param ctx - Koishi 的插件上下文。
-     * @param config - 插件的配置对象。
-     */
-    constructor(ctx: Context, config: Config);
-    /**
-     * @private @method onMessage
-     * @description 统一的消息事件处理器，解析消息并更新各类统计数据的缓冲区。
-     * @param session - Koishi 的会话对象。
-     */
-    private onMessage;
-    /**
-     * @private @method sanitizeContent
-     * @description 将 Koishi 消息元素数组净化为纯文本字符串。
-     * @param elements - 消息元素数组。
-     * @returns 净化后的纯文本。
-     */
-    private sanitizeContent;
-    /**
-     * @private @method flushBuffers
-     * @description 将所有内存中的数据缓冲区批量写入数据库，并清空缓冲区。
-     */
-    private flushBuffers;
-}

package/lib/Data.d.ts

@@ -1,17 +0,0 @@
-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,87 +0,0 @@
-import { Context } from 'koishi';
-import { WordCloudData } from './Analyse';
-/**
- * @interface ListRenderData
- * @description 定义了调用 `renderList` 方法所需的数据结构。
- */
-export interface ListRenderData {
-    title: string;
-    time: Date;
-    total?: string | number;
-    list: (string | number | Date)[][];
-}
-/**
- * @interface CircadianChartData
- * @description 定义了调用 `renderCircadianChart` 方法所需的数据结构。
- */
-export interface CircadianChartData {
-    title: string;
-    time: Date;
-    total: string | number;
-    data: number[];
-    labels?: string[];
-}
-/**
- * @class Renderer
- * @description 负责将结构化的数据渲染为设计精美的 PNG 图片。
- */
-export declare class Renderer {
-    private ctx;
-    private readonly COMMON_STYLE;
-    /**
-     * @constructor
-     * @description Renderer 类的构造函数。
-     * @param {Context} ctx - Koishi 的插件上下文，用于访问 logger 和 puppeteer 服务。
-     */
-    constructor(ctx: Context);
-    /**
-     * @private
-     * @method generateFullHtml
-     * @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[]>;
-    /**
-     * @public
-     * @method renderWordCloud
-     * @description 将词频数据渲染成一张词云图片，使用 Puppeteer 和 wordcloud2.js。
-     * @param {WordCloudData} data - 包含标题、时间和词汇列表的对象。
-     * @returns {Promise<string | Buffer[]>} - 成功时返回图片 Buffer 数组，否则返回提示。
-     */
-    renderWordCloud(data: WordCloudData): Promise<string | Buffer[]>;
-}

package/lib/Stat.d.ts

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

package/lib/WhoAt.d.ts

@@ -1,21 +0,0 @@
-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;
-}