koishi-plugin-statistical-ranking

统计命令使用和成员发言记录，支持分命令/群组/用户统计，支持统计发言排行，支持输出图片

功能

• 自动统计群组内的命令使用和成员发言数据
• 支持按用户、群组、平台筛选统计数据
• 支持黑名单和白名单过滤显示内容
• 支持数据导入导出（可配置开关）
• 支持从历史数据库导入
• 支持清除统计数据（需要管理员权限）
• 支持查看统计对象列表
• 支持生成统计数据可视化图表（需安装puppeteer插件）
• 支持多种排序方式（按次数、时间、名称）
• 支持发言排行榜，展示成员发言增量排行及排名变化

前置依赖

• 必需：database - 提供数据存储功能
• 可选：puppeteer - 提供图片生成功能，启用后可以生成可视化统计图表
• 可选：cron - 提供定时任务功能，启用排行榜功能需要

配置项

• enableDataTransfer: 是否启用数据导入导出功能（默认开启）
• defaultImageMode: 是否默认使用图片模式展示（默认关闭）
• silentMode: 是否启用静默模式，限制插件只在特定群组中响应（默认关闭）
• allowedGuilds: 静默模式白名单群组ID列表，只有列表中的群组可以使用统计命令
• enableRank: 是否启用排行榜功能（默认关闭）
• updateInterval: 排行榜快照更新频率，可选 hourly/6h/12h/daily（默认每天）
• displayWhitelist: 显示过滤白名单，仅展示匹配的记录（优先级高于黑名单）
  • 例如: ['onebot:12345:67890', '.help']
• displayBlacklist: 显示过滤黑名单，不默认展示匹配的记录
  • 例如: ['qq:1234:5678', '.message']

命令

stat [页码|all]

查看个人统计信息，包含命令使用和发言情况的汇总

• -v, --visual 切换可视化模式（反转默认图片模式设置）
• -s, --sort [count|time|key] 指定排序方式（默认按次数排序）
• -u, --user [用户ID] 指定查看某用户的统计信息（需要权限等级2）

stat.command [页码|all]

查看命令统计，显示命令使用频率和最后使用时间

• -u, --user [用户] 指定用户统计
• -g, --guild [群组] 指定群组统计
• -p, --platform [平台] 指定平台统计
• -v, --visual 切换可视化模式
• -a, --all 显示全局统计
• -s, --sort [count|time|key] 指定排序方式

stat.user [页码|all]

查看发言统计，显示用户发言频率和最后发言时间

• -g, --guild [群组] 指定群组统计
• -p, --platform [平台] 指定平台统计
• -v, --visual 切换可视化模式
• -a, --all 显示全局统计
• -s, --sort [count|time|key] 指定排序方式

stat.guild [页码|all]

查看群组统计数据，显示群组活跃度和最后活跃时间

• -u, --user [用户] 指定用户统计
• -p, --platform [平台] 指定平台统计
• -c, --command [命令] 指定命令统计
• -v, --visual 切换可视化模式
• -s, --sort [count|time|key] 指定排序方式

stat.rank [页码|all]

查看发言排行榜（需启用排行榜功能）

• -g, --guild [群组] 指定群组排行（需要权限2）
• -p, --platform [平台] 指定平台排行（需要权限2）
• -t, --time [时间范围] 指定时间范围（格式说明见下方）
• -e, --endTime [结束时间] 指定结束时间（同样使用时间范围格式）
• -v, --visual 切换可视化模式
• -a, --all 显示全局排行

排行榜支持展示成员在指定时间段内的发言增量、当前排名、排名变化等信息。支持图片和文本两种模式。

时间范围格式：

• h 或 1h - 1小时
• d 或 1d - 1天（默认）
• w 或 1w - 1周
• m 或 1m - 1个月（30天）
• y 或 1y - 1年

stat.list

查看统计列表（需要权限等级3）

• -u, --user 显示用户列表
• -g, --guild 显示群组列表

不带参数时默认显示平台列表和命令列表。

stat.clear

清除统计数据（需要权限等级4）

• -u, --user [用户] 指定用户
• -g, --guild [群组] 指定群组
• -p, --platform [平台] 指定平台
• -c, --command [命令] 指定命令
• -b, --below [次数] 删除少于指定次数的记录
• -t, --time [天数] 删除指定天数之前的记录
• -r, --rank 只删除排行数据，保留统计数据
• -d, --drop 不重建数据表（危险操作）

可以组合使用，例如 stat.clear -u 123456 -b 5 会删除用户123456的所有少于5次的记录。

stat.export

导出统计数据（需要权限等级4且enableDataTransfer=true）

• -u, --user [用户] 指定用户
• -p, --platform [平台] 指定平台
• -g, --guild [群组] 指定群组
• -c, --command [命令] 指定命令

导出的数据会保存到 data/statistical-ranking 目录下，文件格式为JSON。

stat.import [序号]

导入统计数据（需要权限等级4且enableDataTransfer=true）

• -f, --force 覆盖现有数据
• -d, --database 从历史数据库导入

不带序号参数时会显示可导入的文件列表。可以导入从 stat.export 命令导出的数据文件， 也可以导入 analytics 插件的历史数据库。

图片模式说明

通过配置 defaultImageMode 可以设置默认是否使用图片模式。使用图片模式可以：

1. 展示更美观的统计数据表格
2. 显示更多统计信息，包括占比、统计条数等
3. 支持分页显示大量数据
4. 支持排行榜展示当前排名和排名变化

使用图片模式需要安装并启用 puppeteer 插件。