koishi-plugin-chat-analyse 1.3.10 → 1.4.1

package/lib/Data.d.ts

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

package/lib/index.d.ts

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

package/lib/index.js

@@ -1620,7 +1620,7 @@ var Renderer = class {
     const { title, time, list } = data;
     const CHUNK_SIZE = 100;
     const totalItems = list.length;
-    const countHeaderIndex = headers?.findIndex((h6) => ["总计发言", "条数", "次数", "数量"].includes(h6)) ?? -1;
+    const countHeaderIndex = headers?.findIndex((h7) => ["总计发言", "条数", "次数", "数量"].includes(h7)) ?? -1;
     const totalCount = data.total || (countHeaderIndex > -1 ? list.reduce((sum, row) => sum + (Number(row[countHeaderIndex]) || 0), 0) : totalItems);
     const renderCell = /* @__PURE__ */ __name((cell, i) => {
       const headerText = headers?.[i] || "";
@@ -1668,7 +1668,7 @@ var Renderer = class {
                 <thead>
                   <tr>
                     <th class="rank-cell">#</th>
-                    ${headers.map((h6) => `<th>${h6}</th>`).join("")}
+                    ${headers.map((h7) => `<th>${h7}</th>`).join("")}
                   </tr>
                 </thead>` : ""}
               <tbody>
@@ -2104,16 +2104,51 @@ var import_koishi5 = require("koishi");
 var fs = __toESM(require("fs/promises"));
 var path = __toESM(require("path"));
 var ALL_TABLES = ["analyse_user", "analyse_cmd", "analyse_msg", "analyse_rank", "analyse_at", "analyse_cache"];
-var BATCH_SIZE = 100;
+var DEFAULT_BACKUP_TABLES = ["analyse_user", "analyse_cmd", "analyse_msg", "analyse_rank"];
+var BATCH_SIZE = 1e3;
 var Data = class {
-  constructor(ctx) {
+  constructor(ctx, config) {
     this.ctx = ctx;
+    this.config = config;
     this.dataDir = path.join(this.ctx.baseDir, "data", "chat-analyse");
+    if (this.config.enableAutoBackup) this.ctx.cron("0 0 1 * *", () => {
+      this.backupCache();
+    });
   }
   static {
     __name(this, "Data");
   }
   dataDir;
+  /**
+   * @private
+   * @method backupCache
+   * @description 备份 analyse_cache 表到 JSON 文件。
+   */
+  async backupCache() {
+    try {
+      await fs.mkdir(this.dataDir, { recursive: true });
+      const now = /* @__PURE__ */ new Date();
+      const lastMonth = new Date(now.getFullYear(), now.getMonth() - 1, 1);
+      const year = lastMonth.getFullYear();
+      const month = (lastMonth.getMonth() + 1).toString().padStart(2, "0");
+      const filename = `analyse_cache_${year}-${month}.json`;
+      const filepath = path.join(this.dataDir, filename);
+      const allUsers = await this.ctx.database.get("analyse_user", {});
+      if (allUsers.length === 0) return;
+      const uidToUserInfoMap = new Map(allUsers.map((u) => [u.uid, u]));
+      const records = await this.ctx.database.get("analyse_cache", {});
+      if (records.length === 0) return;
+      const dataToExport = records.map((record) => {
+        const userInfo = uidToUserInfoMap.get(record.uid);
+        if (!userInfo) return null;
+        const { id, uid, ...restOfRecord } = record;
+        return { userId: userInfo.userId, channelId: userInfo.channelId, ...restOfRecord };
+      }).filter(Boolean);
+      await fs.writeFile(filepath, JSON.stringify(dataToExport, null, 2));
+    } catch (error) {
+      this.ctx.logger.error("原始记录备份失败:", error);
+    }
+  }
   /**
    * @public
    * @method registerCommands
@@ -2121,12 +2156,13 @@ var Data = class {
    * @param cmd - 主命令实例。
    */
   registerCommands(cmd) {
-    cmd.subcommand(".backup", "备份数据", { authority: 4 }).usage("将所有统计数据导出为 JSON 文件并保存到本地。").action(async () => {
+    cmd.subcommand(".backup", "备份数据", { authority: 4 }).usage("将统计数据导出为 JSON 文件，并保存到本地。").option("all", "-a 全量备份").action(async ({ options }) => {
+      const tablesToProcess = options.all ? ALL_TABLES : DEFAULT_BACKUP_TABLES;
       try {
         await fs.mkdir(this.dataDir, { recursive: true });
         const allUsers = await this.ctx.database.get("analyse_user", {});
         const uidToUserInfoMap = new Map(allUsers.map((u) => [u.uid, u]));
-        for (const tableName of ALL_TABLES) {
+        for (const tableName of tablesToProcess) {
           const filepath = path.join(this.dataDir, `${tableName}.json`);
           let dataToExport;
           if (tableName === "analyse_user") {
@@ -2148,14 +2184,15 @@ var Data = class {
         return "数据备份失败";
       }
     });
-    cmd.subcommand(".restore", "恢复数据", { authority: 4 }).usage(`从本地的 JSON 文件中恢复统计数据。`).action(async () => {
+    cmd.subcommand(".restore", "恢复数据", { authority: 4 }).usage("从本地的 JSON 文件中恢复统计数据。").option("all", "-a 全量恢复").action(async ({ options }) => {
       try {
         const userTablePath = path.join(this.dataDir, "analyse_user.json");
         const usersToImport = JSON.parse(await fs.readFile(userTablePath, "utf-8").catch(() => "[]"));
         if (usersToImport.length) for (let i = 0; i < usersToImport.length; i += BATCH_SIZE) await this.ctx.database.upsert("analyse_user", usersToImport.slice(i, i + BATCH_SIZE));
         const allUsers = await this.ctx.database.get("analyse_user", {});
         const userToUidMap = new Map(allUsers.map((u) => [`${u.channelId}:${u.userId}`, u.uid]));
-        for (const tableName of ALL_TABLES.filter((t) => t !== "analyse_user")) {
+        const tablesToProcess = options.all ? ALL_TABLES.filter((t) => t !== "analyse_user") : DEFAULT_BACKUP_TABLES.filter((t) => t !== "analyse_user");
+        for (const tableName of tablesToProcess) {
           const filepath = path.join(this.dataDir, `${tableName}.json`);
           const recordsToImport = JSON.parse(await fs.readFile(filepath, "utf-8").catch(() => "[]"));
           if (!recordsToImport.length) continue;
@@ -2243,6 +2280,48 @@ var Data = class {
         return "数据清理失败";
       }
     });
+    if (this.config.enableOriRecord) {
+      cmd.subcommand(".view <time:string>", "查询消息记录", { authority: 4 }).usage("查询指定时间点后的消息记录，默认查询当前群组。").option("user", "-u <user:string> 指定用户").option("guild", "-g <guildId:string> 指定群组").action(async ({ session, options }, time) => {
+        if (!time) return '请以"YYYY-MM-DD HH:MM:SS"格式输入起始时间';
+        const since = new Date(time);
+        if (isNaN(since.getTime())) return "时间格式无效";
+        try {
+          const userQuery = {};
+          if (!options.guild && !options.user) {
+            if (!session.guildId) return "请指定查询范围";
+            userQuery.channelId = session.guildId;
+          } else {
+            if (options.guild) userQuery.channelId = options.guild;
+            if (options.user) userQuery.userId = import_koishi5.Element.select(options.user, "at")[0]?.attrs.id ?? options.user;
+          }
+          const usersInScope = await this.ctx.database.get("analyse_user", userQuery);
+          if (usersInScope.length === 0) return "暂无用户数据";
+          const uids = usersInScope.map((u) => u.uid);
+          const records = await this.ctx.database.get("analyse_cache", {
+            uid: { $in: uids },
+            timestamp: { $gte: since }
+          }, {
+            sort: { timestamp: "asc" },
+            limit: 100
+          });
+          if (records.length === 0) return "暂无统计数据";
+          const recordUids = [...new Set(records.map((r) => r.uid))];
+          const users = await this.ctx.database.get("analyse_user", { uid: { $in: recordUids } }, ["uid", "userName", "userId"]);
+          const userInfoMap = new Map(users.map((u) => [u.uid, { name: u.userName, id: u.userId }]));
+          const messageElements = records.map((record) => {
+            const senderInfo = userInfoMap.get(record.uid) || { name: `UID ${record.uid}`, id: "unknown" };
+            const timeStr = record.timestamp.toLocaleTimeString("zh-CN", { hour12: false });
+            const author = (0, import_koishi5.h)("author", { id: senderInfo.id, name: senderInfo.name });
+            const content = import_koishi5.h.text(`[${timeStr}] ${record.content}`);
+            return (0, import_koishi5.h)("message", {}, [author, content]);
+          });
+          await session.send((0, import_koishi5.h)("message", { forward: true }, messageElements));
+        } catch (error) {
+          this.ctx.logger.error("查询消息记录失败:", error);
+          return "查询消息记录失败";
+        }
+      });
+    }
     cmd.subcommand(".list", "列出数据", { authority: 4 }).usage("列出数据库中的频道和命令列表。").action(async () => {
       const [allChannelInfo, commands] = await Promise.all([
         this.ctx.database.get("analyse_user", {}, ["channelId", "channelName"]),
@@ -2429,13 +2508,14 @@ 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(180).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(3).description("提及保留天数")
   }).description("基础分析配置"),
   import_koishi7.Schema.object({
     enableOriRecord: import_koishi7.Schema.boolean().default(true).description("启用原始记录"),
-    cacheRetentionDays: import_koishi7.Schema.number().min(0).default(30).description("记录保留天数"),
+    cacheRetentionDays: import_koishi7.Schema.number().min(0).default(31).description("记录保留天数"),
+    enableAutoBackup: import_koishi7.Schema.boolean().default(false).description("启用自动备份"),
     enableWordCloud: import_koishi7.Schema.boolean().default(true).description("启用词云生成"),
     enableSimilarActivity: import_koishi7.Schema.boolean().default(true).description("启用相似活跃分析")
   }).description("高级分析配置")
@@ -2483,7 +2563,7 @@ function apply(ctx, config) {
   const analyse = ctx.command("analyse", "数据分析");
   new Stat(ctx, config).registerCommands(analyse);
   if (config.enableWhoAt) new WhoAt(ctx, config).registerCommand(analyse);
-  if (config.enableDataIO) new Data(ctx).registerCommands(analyse);
+  if (config.enableDataIO) new Data(ctx, config).registerCommands(analyse);
   if (config.enableWordCloud || config.enableSimilarActivity) new Analyse(ctx, config).registerCommands(analyse);
 }
 __name(apply, "apply");

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "koishi-plugin-chat-analyse",
-  "description": "强大而全面的聊天数据分析，支持统计命令，发言，消息类型，活跃度，支持发言排行和生成词云",
-  "version": "1.3.10",
+  "description": "强大而全面的聊天数据分析插件。支持多维度统计（命令、发言、消息类型、活跃度），可生成发言排行、词云图，并提供完善的数据管理。",
+  "version": "1.4.1",
   "contributors": [
     "Yis_Rime <yis_rime@outlook.com>"
   ],

package/readme.md

@@ -2,33 +2,34 @@
 
 [![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 分词生成热门话题词云图，快速了解近期热点。
-  - **相似活跃分析** (`simiactive`): 分析指定时间内，找出与您作息模式最相似的群友，并通过对比图表直观展示。
-  - **提及追踪** (`whoatme`)：轻松查询谁在什么时候因为什么内容提及了您，不再错过重要信息。
-- **强大的数据管理**：
-  - **备份与恢复** (`.backup`/`.restore`)：一键备份所有统计数据至本地，并可随时恢复，保障数据安全。
-  - **精确清理** (`.clear`)：提供多维度的筛选条件（如按时间、用户、群组、发言数），精确清理不再需要的数据。
-- **精美图表渲染**：借助 Puppeteer 服务，将复杂的统计数据渲染成美观、易读的图片，方便在聊天中分享。
-- **高度可配置**：所有功能模块均可独立开关，并可自定义数据保留时长等核心参数，以适应不同场景的需求。
+**高效数据收集**：采用异步、高并发和缓存机制，在不影响机器人性能的前提下，精确高效地收集聊天数据。
+**多维度统计分析**：
+  **命令统计** (`cmdstat`)：追踪指令使用频率，了解用户最常用的功能，支持按次数或时间排序。
+  **发言统计** (`msgstat`)：分析用户发言类型与数量，掌握核心用户群体，支持按条数或时间排序。
+  **发言排行** (`rankstat`)：生成指定时间范围内的用户发言排行榜，发掘群聊中的“龙王”。
+  **活跃度分析** (`activity`)：以小时或天为单位，生成直观的周期性活跃度图表，洞察社群活跃时段。
+**高级文本分析**：
+  **词云生成** (`wordcloud`)：基于聊天记录，利用 Jieba 分词生成热门话题词云图，快速了解近期热点。
+  **相似活跃分析** (`simiactive`): 分析指定时间内，找出与您作息模式最相似的群友，并通过对比图表直观展示。
+  **提及追踪** (`whoatme`)：轻松查询谁在什么时候因为什么内容提及了您，不再错过重要信息。
+**强大的数据管理**：
+  **备份与恢复** (`.backup`/`.restore`)：一键备份所有统计数据至本地，并可随时恢复，保障数据安全。
+  **精确清理** (`.clear`)：提供多维度的筛选条件（如按时间、用户、群组、发言数），精确清理不再需要的数据。
+  **记录查看** (`.view`): 可回溯查看指定时间点后的原始消息记录。
+**精美图表渲染**：借助 Puppeteer 服务，将复杂的统计数据渲染成美观、易读的图片，方便在聊天中分享。
+**高度可配置**：所有功能模块均可独立开关，并可自定义数据保留时长等核心参数，以适应不同场景的需求。
 
 ## ⚙️ 前置服务
 
 本插件依赖以下 Koishi 服务，请确保您已正确安装并启用了它们：
 
-- **`database`**：用于存储所有统计分析数据。
-- **`puppeteer`**：用于将统计结果渲染成图片。
-- **`cron`**：用于执行数据定时清理任务。
+**`database`**：用于存储所有统计分析数据。
+**`puppeteer`**：用于将统计结果渲染成图片。
+**`cron`**：用于执行数据定时清理任务。
 
 ## 📝 使用说明
 
@@ -37,7 +38,7 @@
 ### 指令列表
 
 | 指令 | 别名 | 描述 | 选项 |
-| :--- | :--- | :--- | :--- |
+| :--| :--| :--| :--|
 | `cmdstat` | 命令统计 | 查询命令使用情况，展示方式根据选项变化 | `-u`, `-g`, `-a`, `-p`, `-s` |
 | `msgstat` | 发言统计 | 查询用户发言统计，展示方式根据选项变化 | `-u`, `-g`, `-a`, `-t`, `-s` |
 | `rankstat` | 发言排行 | 查询指定时间内的发言排行 | `-u`, `-g`, `-a`, `-t`, `-n`, `-o` |
@@ -45,6 +46,7 @@
 | `wordcloud` | 生成词云 | 基于聊天记录生成词云图 | `-u`, `-g`, `-t` |
 | `simiactive`| 相似活跃分析 | 分析并找出与您作息相似的群友 | `-n`, `-p` |
 | `whoatme` | 谁提及我 | 查看最近谁提及了您 | (无) |
+| `analyse.view <time>`| 查询记录 | (管理) 查询指定时间点后的消息记录 | `-u`, `-g` |
 | `analyse.list` | 列出数据 | (管理) 列出已记录的频道和命令 | (无) |
 | `analyse.backup` | 备份数据 | (管理) 将所有数据备份为本地 JSON 文件 | (无) |
 | `analyse.restore` | 恢复数据 | (管理) 从本地 JSON 文件恢复数据 | (无) |
@@ -52,57 +54,78 @@
 
 **通用选项说明:**
 
-- `-u, --user <user>`: 指定用户 (可使用 @ 或 userID)。
-- `-g, --guild <guild>`: 指定群组 (需使用群组ID)。
-- `-a, --all`: 查询全局数据。
+`-u, --user <user>`: 指定用户 (可使用 @ 或 userID)。
+`-g, --guild <guild>`: 指定群组 (需使用群组ID)。
+`-a, --all`: 查询全局数据。
 
 ### 🔎 指令详解
 
 #### `cmdstat` (命令统计)
 
-- **`cmdstat`**: 查询**当前群组**所有用户的命令统计。
-- **`cmdstat -u @用户`**: 查询**指定用户**在**所有群组**的命令统计。
-- **`cmdstat -g <群组ID>`**: 查询**指定群组**所有用户的命令统计。
-- **`cmdstat -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的命令统计。
-- **`cmdstat -a`**: 查询**全局**（所有用户+所有群组）的命令统计。
-- **选项 `-p, --separate`**: 分离展示子命令，不合并到主命令。
-- **选项 `-s, --sortByTime`**: 按最后使用时间降序排序（默认按使用次数）。
+**`cmdstat`**: 查询**当前群组**所有用户的命令统计。
+**`cmdstat -u @用户`**: 查询**指定用户**在**所有群组**的命令统计。
+**`cmdstat -g <群组ID>`**: 查询**指定群组**所有用户的命令统计。
+**`cmdstat -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的命令统计。
+**`cmdstat -a`**: 查询**全局**（所有用户+所有群组）的命令统计。
+**选项 `-p, --separate`**: 分离展示子命令，不合并到主命令。
+**选项 `-s, --sortByTime`**: 按最后使用时间降序排序（默认按使用次数）。
 
 #### `msgstat` (发言统计)
 
-- **`msgstat`**: 查询**当前群组**的发言统计 (按**用户**展示)。
-- **`msgstat -u @用户`**: 查询**指定用户**的发言统计 (按**群组**展示)。
-- **`msgstat -g <群组ID>`**: 查询**指定群组**的发言统计 (按**用户**展示)。
-- **`msgstat -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的发言统计 (按**消息类型**展示)。
-- **`msgstat -a`**: 查询**全局**发言统计 (按**用户**展示)。
-- **选项 `-t, --type <类型>`**: 筛选指定消息类型 (`text`, `face`, `image` 等)，不改变上述展示逻辑。
-- **选项 `-s, --sortByTime`**: 按最后发言时间降序排序（默认按发言条数）。
+**`msgstat`**: 查询**当前群组**的发言统计 (按**用户**展示)。
+**`msgstat -u @用户`**: 查询**指定用户**的发言统计 (按**群组**展示)。
+**`msgstat -g <群组ID>`**: 查询**指定群组**的发言统计 (按**用户**展示)。
+**`msgstat -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的发言统计 (按**消息类型**展示)。
+**`msgstat -a`**: 查询**全局**发言统计 (按**用户**展示)。
+**选项 `-t, --type <类型>`**: 筛选指定消息类型 (`text`, `face`, `image` 等)，不改变上述展示逻辑。
+**选项 `-s, --sortByTime`**: 按最后发言时间降序排序（默认按发言条数）。
 
 #### `rankstat` (发言排行)
 
-- **`rankstat`**: 查询**当前群组**的发言排行 (按**用户**排名)。
-- **`rankstat -u @用户`**: 查询**指定用户**的发言排行 (按**群组**排名)。
-- **`rankstat -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的发言排行 (按**消息类型**排名)。
-- **`rankstat -a`**: 查询**全局**发言排行 (按**用户**排名)。
-- **选项 `-n, --duration <小时数>`**: 指定查询范围的时长，默认为 `24`。
-- **选项 `-o, --offset <小时数>`**: 指定查询结束时间的偏移量（从现在往前推的小时数），默认为 `0`。
-- **选项 `-t, --type <类型>`**: 筛选指定消息类型。
+**`rankstat`**: 查询**当前群组**的发言排行 (按**用户**排名)。
+**`rankstat -u @用户`**: 查询**指定用户**的发言排行 (按**群组**排名)。
+**`rankstat -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的发言排行 (按**消息类型**排名)。
+**`rankstat -a`**: 查询**全局**发言排行 (按**用户**排名)。
+**选项 `-n, --duration <小时数>`**: 指定查询范围的时长，默认为 `24`。
+**选项 `-o, --offset <小时数>`**: 指定查询结束时间的偏移量（从现在往前推的小时数），默认为 `0`。
+**选项 `-t, --type <类型>`...**: 筛选指定消息类型。
 
 #### `activity` (活跃统计)
 
-- **`activity`**: 查询**当前群组**的活跃度。
-- **`activity -a`**: 查询**全局**活跃度。
-- **`activity -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的活跃度。
-- **选项 `-n, --duration <数值>`**: 指定查询范围的时长，默认为 `24`。
-- **选项 `-o, --offset <数值>`**: 指定查询结束时间的偏移量，默认为 `0`。
-- **选项 `-d, --days`**: 将 `-n` 和 `-o` 的单位从**小时**切换为**天**。
+**`activity`**: 查询**当前群组**的活跃度。
+**`activity -a`**: 查询**全局**活跃度。
+**`activity -u @用户 -g <群组ID>`**: 查询**指定用户**在**指定群组**的活跃度。
+**选项 `-n, --duration <数值>`**: 指定查询范围的时长，默认为 `24`。
+**选项 `-o, --offset <数值>`**: 指定查询结束时间的偏移量，默认为 `0`。
+**选项 `-d, --days`**: 将 `-n` 和 `-o` 的单位从**小时**切换为**天**。
+
+#### `wordcloud` (生成词云)
+
+**`wordcloud`**: 基于**当前群组**最近 `24` 小时聊天记录生成词云。
+**选项 `-u, --user <user>`**: 指定用户。
+**选项 `-g, --guild <guild>`**: 指定群组。
+**选项 `-t, --hours <小时数>`**: 指定查询时长，默认为 `24`。
 
 #### `simiactive` (相似活跃分析)
 
-- **`simiactive`**: 在**当前群组**中，分析最近 **24 小时**内与您作息最相似的群友。
-- **`simiactive -n 48`**: 指定分析最近 **48 小时**的数据。
-- **选项 `-n, --hours <小时数>`**: 指定查询范围的时长，默认为 `24`。
-- **选项 `-p, --separate`**: 分离小时数据，不按天聚合进行分析。
+**`simiactive`**: 在**当前群组**中，分析最近 **24 小时**内与您作息最相似的群友。
+**`simiactive -n 48`**: 指定分析最近 **48 小时**的数据。
+**选项 `-n, --hours <小时数>`**: 指定查询范围的时长，默认为 `24`。
+**选项 `-p, --separate`**: 分离小时数据，不按天聚合进行分析。
+
+#### `analyse.clear` (清除数据)
+
+该指令用于高级数据管理，请谨慎使用。
+
+| 选项 | 别名 | 描述 |
+| :--| :--| :--|
+| `--table <表名>` | `-t` | 指定要清除的表名 (如 `analyse_cmd`)。若不指定，则默认清理除 `analyse_user` 外的所有表。 |
+| `--guild <群组ID>` | `-g` | 仅清除指定群组的数据。 |
+| `--user <用户>` | `-u` | 仅清除指定用户的数据。 |
+| `--days <天数>` | `-d` | 清除指定天数之前的所有数据 (例如 `-d 30` 会删除30天前的数据)。 |
+| `--command <命令>` | `-c` | 仅清除 `analyse_cmd` 表中指定的命令记录。 |
+| `--limit <次数>` | `-l` | 清除总发言数小于指定次数的用户的所有记录。 |
+| `--all` | `-a` | **【高危】** 清除插件产生的所有数据表，相当于重置插件。 |
 
 ## 🔧 配置项
 
@@ -110,25 +133,28 @@
 
 ### 杂项配置
 
-- `enableListener`: **启用消息监听**。总开关，关闭后插件将停止所有数据收集。 (默认: `true`)
-- `enableDataIO`: **启用数据管理**。控制 `.backup`, `.restore`, `.clear`, `.list` 等管理指令的可用性。 (默认: `true`)
+`enableListener`: **启用消息监听**。总开关，关闭后插件将停止所有数据收集。 (默认: `true`)
+`enableDataIO`: **启用数据管理**。控制 `.backup`, `.restore`, `.clear`, `.list`, `.view` 等管理指令的可用性。 (默认: `true`)
 
 ### 基础分析配置
 
-- `enableCmdStat`: **启用命令统计**。 (默认: `true`)
-- `enableMsgStat`: **启用消息统计**。 (默认: `true`)
-- `enableActivity`: **启用活跃统计**。 (默认: `true`)
-- `enableRankStat`: **启用发言排行**。 (默认: `true`)
-- `rankRetentionDays`: **排行保留天数**。发言排行数据的保留时长（天），`0` 为永久保留。 (默认: `180`)
-- `enableWhoAt`: **启用提及记录**。 (默认: `true`)
-- `atRetentionDays`: **提及保留天数**。`whoatme` 数据的保留时长（天），`0` 为永久保留。 (默认: `3`)
+`enableCmdStat`: **启用命令统计**。 (默认: `true`)
+`enableMsgStat`: **启用消息统计**。 (默认: `true`)
+`enableActivity`: **启用活跃统计**。 (默认: `true`)
+`enableRankStat`: **启用发言排行**。 (默认: `true`)
+`rankRetentionDays`: **排行保留天数**。发言排行数据的保留时长（天），`0` 为永久保留。 (默认: `180`)
+`enableWhoAt`: **启用提及记录**。 (默认: `true`)
+`atRetentionDays`: **提及保留天数**。`whoatme` 数据的保留时长（天），`0` 为永久保留。 (默认: `3`)
 
 ### 高级分析配置
 
-- `enableOriRecord`: **启用原始记录**。是否记录原始消息内容以供词云等功能使用。 (默认: `true`)
-- `cacheRetentionDays`: **原始记录保留天数**。原始消息记录的保留时长（天），`0` 为永久保留。 (默认: `30`)
-- `enableWordCloud`: **启用词云生成** (依赖`原始记录`)。 (默认: `true`)
-- `enableSimilarActivity`: **启用相似活跃分析** (依赖`发言排行`或`活跃统计`)。 (默认: `true`)
+`enableOriRecord`: **启用原始记录**。是否记录原始消息内容。这是 `.view` 和 `wordcloud` 功能的基础。 (默认: `true`)
+`cacheRetentionDays`: **原始记录保留天数**。原始消息记录的保留时长（天），`0` 为永久保留。 (默认: `30`)
+`enableAutoBackup`: **启用自动备份记录**。是否开启每月自动备份原始消息记录。 (默认: `false`)
+`enableWordCloud`: **启用词云生成**。
+  > **!** 此功能依赖 **`启用原始记录`**。 (默认: `true`)
+`enableSimilarActivity`: **启用相似活跃分析**。
+  > **!** 此功能依赖 **`启用发言排行`** 或 **`启用活跃统计`**。 (默认: `true`)
 
 ## 📌 注意事项