koishi-plugin-chat-analyse

强大而全面的聊天数据分析插件。支持多维度统计（命令、发言、消息类型、活跃度），可生成发言排行、词云图，并提供完善的数据管理和 AI 分析功能。

✨ 功能特性

高效数据收集：采用异步、高并发和缓存机制，在不影响机器人性能的前提下，精确高效地收集聊天数据。 多维度统计分析： 命令统计 (cmdstat)：追踪指令使用频率，了解用户最常用的功能，支持按次数或时间排序。 发言统计 (msgstat)：分析用户发言类型与数量，掌握核心用户群体，支持按条数或时间排序。 发言排行 (rankstat)：生成指定时间范围内的用户发言排行榜，发掘群聊中的“龙王”。 活跃度分析 (activity)：以小时或天为单位，生成直观的周期性活跃度图表，洞察社群活跃时段。 高级文本分析： 词云生成 (wordcloud)：基于聊天记录，利用 Jieba 分词生成热门话题词云图，快速了解近期热点。 相似活跃分析 (simiactive)：分析指定时间内，找出与您作息模式最相似的群友，并通过对比图表直观展示。 提及追踪 (whoatme)：轻松查询谁在什么时候因为什么内容提及了您，不再错过重要信息。 AI 聊天分析 (chatreview)：接入大语言模型，对指定时间范围内的聊天记录进行总结、归纳或回答特定问题，实现更高层次的智能分析。 强大的数据管理： 备份与恢复 (.backup/.restore)：一键备份所有统计数据至本地，并可随时恢复，保障数据安全。 精确清理 (.clear)：提供多维度的筛选条件（如按时间、用户、群组、发言数），精确清理不再需要的数据。 记录查看 (.view)：可回溯查看指定时间点之前的原始消息记录。 精美图表渲染：借助 Puppeteer 服务，将复杂的统计数据渲染成美观、易读的图片，方便在聊天中分享。 高度可配置：所有功能模块均可独立开关，并可自定义数据保留时长等核心参数，以适应不同场景的需求。

⚙️ 前置服务

本插件依赖以下 Koishi 服务，请确保您已正确安装并启用了它们：

database：用于存储所有统计分析数据。 puppeteer：用于将统计结果渲染成图片。 cron：用于执行数据定时清理任务。

📝 使用说明

所有功能都集成在主指令 analyse 之下。大部分指令不加任何参数时，默认查询当前群组的数据。

指令列表

| 指令 | 别名 | 描述 | 选项 | | :--- | :--- | :--- | :--- | | cmdstat | 命令统计 | 查询命令使用情况，展示方式根据选项变化 | -u, -g, -l, -p, -s, -a | | msgstat | 发言统计 | 查询用户发言统计，展示方式根据选项变化 | -u, -g, -t, -l, -s, -a | | rankstat | 发言排行 | 查询指定时间内的发言排行 | -u, -g, -t, -n, -o, -l, -a | | activity | 活跃统计 | 查询周期性活跃度图表 | -u, -g, -d, -n, -o, -a | | wordcloud | 生成词云 | 基于聊天记录生成词云图 | -u, -g, -t | | simiactive| 相似活跃分析 | 分析并找出与您作息相似的群友 | -n, -p | | chatreview <prompt> | 聊天分析 | 使用模型进行聊天记录分析 | -u, -g, -t | | whoatme | 谁提及我 | 查看最近谁提及了您 | (无) | | analyse.view <time>| 查询记录 | (管理) 查询指定时间点之前的消息记录 | -u, -g, -n | | analyse.list | 列出数据 | (管理) 列出已记录的频道和命令 | (无) | | analyse.backup | 备份数据 | (管理) 将所有数据备份为本地 JSON 文件 | -a | | analyse.restore | 恢复数据 | (管理) 从本地 JSON 文件恢复数据 | -a | | analyse.archive [date]| 手动归档 | (管理) 手动归档指定日期的原始消息记录 | (无) | | analyse.clear | 清除数据 | (管理) 根据条件精确清理数据 | -t, -g, -u, -d, -c, -l, -a |

通用选项说明:

-u, --user <user>: 指定用户 (可使用 @ 或 userID)。 -g, --guild <guild>: 指定群组 (需使用群组ID)。 -a, --all: 查询全局数据。 -l, --limit <count>: 限制返回的条目数量。

🔎 指令详解

cmdstat (命令统计)

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, img 等)，不改变上述展示逻辑。 选项 -s, --sortByTime: 按最后发言时间降序排序（默认按发言条数）。

rankstat (发言排行)

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 的单位从小时切换为天。

wordcloud (生成词云)

wordcloud: 基于当前群组最近 24 小时聊天记录生成词云。 选项 -u, --user <user>: 指定用户。 选项 -g, --guild <guild>: 指定群组。 选项 -t, --hours <小时数>: 指定查询时长，默认为 24。

simiactive (相似活跃分析)

simiactive: 在当前群组中，分析最近 24 小时内与您作息最相似的群友。 simiactive -n 48: 指定分析最近 48 小时的数据。 选项 -n, --hours <小时数>: 指定查询范围的时长，默认为 24。 选项 -p, --separate: 分离小时数据，不按天聚合进行分析。

chatreview (AI 聊天分析)

该指令利用大语言模型分析聊天记录，需提供具体的分析任务。

analyse.chatreview 总结一下最近6小时的聊天内容 analyse.chatreview -t 24 昨天聊了哪些关于游戏的话题？ analyse.chatreview -u @用户 -t 12 分析这位用户的情绪

选项 -u, --user <user>: 指定用户。 选项 -g, --guild <guild>: 指定群组。 选项 -t, --hours <小时数>: 指定查询时长，默认为 6。

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 | 【高危】 清除插件产生的所有数据表，相当于重置插件。 |

🔧 配置项

您可以在插件的配置页面中调整以下选项：

杂项配置

enableListener: 启用消息监听。总开关，关闭后插件将停止所有数据收集。 (默认: true) enableDataIO: 启用数据管理。控制 .backup, .restore, .clear, .list, .view 等管理指令的可用性。 (默认: true)

基础配置

enableCmdStat: 启用命令统计。 (默认: true) enableMsgStat: 启用消息统计。 (默认: true) enableActivity: 启用活跃统计。 (默认: true) enableSimiActivity: 启用活跃比较。(默认: true) enableRankStat: 启用发言排行。 (默认: true) enableWhoAt: 启用提及记录。 (默认: true) rankRetentionDays: 排行保留天数。发言排行数据的保留时长（天），0 为永久保留。 (默认: 365) atRetentionDays: 提及保留天数。whoatme 数据的保留时长（天），0 为永久保留。 (默认: 3)

高级配置

enableOriRecord: 启用原始记录。是否记录原始消息内容。这是 .view、wordcloud 和 chatreview 功能的基础。 (默认: true) enableWordCloud: 启用词云生成。 > ! 此功能依赖 启用原始记录。 (默认: true) enableAiSummary: 启用模型分析。 > ! 此功能依赖 启用原始记录。 (默认: false) tokenPerRequest: 每次请求的最大 Token 数。单次向 AI 模型发送请求时，允许的最大内容长度（近似值）。 (默认: 2000) enableAutoBackup: 启用自动归档。每日自动将前一天的原始消息记录备份为 JSON 文件。 (默认: true) cacheRetentionDays: 记录保留天数。原始消息记录在数据库中的保留时长（天），0 为永久保留。 (默认: 7) endpoints: 模型端点。配置用于 AI 分析的大语言模型 API 接口。可以配置多个备用端点，插件会在请求失败时自动轮换。 - url: 端点地址 (Endpoint)，例如 https://api.openai.com/v1。 - key: 密钥 (API Key)。 - model: 模型 (Model)，例如 gpt-3.5-turbo。

词云配置

| 配置项 | 描述 | 默认值 | | :--- | :--- | :--- | | maxWords| 最大词量：词云显示的最多词汇数量。 | 1024 | | ellipticity | 长宽比：形状的扁平程度(0-1)，仅对非方形形状有效。 | 1 | | rotationSteps| 旋转步数：旋转角度的选择方式。0表示随机，2表示只在最小/最大角度中二选一。 | 3 | | minRotation | 最小旋转角：单词随机旋转的最小角度(弧度)。 | -1.570796 (-π/2) | | maxRotation | 最大旋转角：单词随机旋转的最大角度(弧度)。 | 1.570796 (π/2) | | shape | 词云形状：预设值包括 circle, cardioid, diamond, square, triangle, pentagon, star。 | square | | color | 词云颜色：可设为 random-light、random-dark、CSS颜色值(如#ff0000)或一个返回颜色的JS函数。 | random-light | | fontFamily | 词云字体：用于渲染词云的字体列表。 | "Noto Sans CJK SC", Arial, sans-serif | | maskImage | 蒙版图片：提供一个图片的URL作为词云的形状蒙版。注意：这会覆盖“词云形状”选项。 | (空) | | excludeWords| 屏蔽词：以下词汇不会显示在词云中，使用英文逗号分隔。 | (空) |

📌 注意事项

1. Puppeteer 配置：本插件的图片渲染强依赖 puppeteer 服务。请确保您已正确安装并配置了该服务，包括正确设置了可执行文件路径（如有需要）。渲染失败通常与此有关。
2. 初始数据积累：插件启用后，需要一段时间来收集数据。因此，在刚安装插件后立即查询可能不会返回任何结果。
3. 数据清理：插件会根据您设置的保留天数自动清理过期数据。对于手动清理 (.clear)，请谨慎操作，特别是 -a (清除全部) 选项，该操作不可逆。
4. 性能考虑：尽管插件经过优化，但在极大规模的机器人（数千群聊）上，长时间积累的大量数据仍可能对数据库造成压力。建议定期使用 .clear -d <天数> 清理过旧的数据。