📊 发言统计插件 (Speaker Statistics Plugin)

✨ Yunzai-Bot 专业的群聊发言统计系统

插件 by QingYing & AI

📦 简介

发言统计插件是 Yunzai-Bot 的群聊统计解决方案，用于统计并展示群成员的发言次数、字数、活跃情况，并提供群聊分析、词云、归档清理和锅巴配置能力。

文档版本：5.1.1
发布日期：2026-06-07

核心特性

📊 多维度统计：总榜、日榜、周榜、月榜、年榜、趋势全覆盖
👤 个人查询：支持个人统计、跨群列表、@ 查询他人
🪪 当前群昵称展示：个人查询和排行榜优先显示用户在当前群的群名片 / 群昵称
🎨 排行榜个人背景：支持私聊生成短期链接，通过 Web 页面设置自己的排行榜行背景
🤖 群聊分析：支持基础总结、活跃图表、AI 话题分析、金句和称号
☁️ 词云能力：支持群词云和个人词云
⚙️ 可视化配置：支持通过 Guoba-Plugin 图形化管理配置
🌐 Web 管理端：支持浏览统计概览、群组列表和排行查询
🔒 数据治理：僵尸群归档、自动恢复、定时清理
🗄️ 双数据库支持：支持 PostgreSQL 和 SQLite
🔁 Redis 统计同步：支持从数据库补齐当前群或全部群的 Redis 消息类型统计
♻️ 当前架构：已切换到 apps/ + core/ + guoba/ + resources/ 目录结构

🚀 安装方法

前置要求

Node.js 16+
Yunzai-Bot
数据库二选一：
- PostgreSQL 12+（推荐生产环境）
- SQLite 3+（推荐轻量部署）

安装步骤

克隆插件

Gitee（国内推荐）

git clone https://gitee.com/qingyingxbot/Speaker-statistics-plugin.git ./plugins/Speaker-statistics-plugin

GitHub

git clone https://github.com/QingYingX-Bot/Speaker-statistics-plugin.git ./plugins/Speaker-statistics-plugin

安装依赖

在 Yunzai 根目录执行：

pnpm install --filter=Speaker-statistics-plugin

💡 提示：

pnpm install --filter=Speaker-statistics-plugin 会按 Yunzai 根目录的 pnpm workspace 安装插件依赖。

单独进入插件目录安装时，也可以使用 npm install，会按 package-lock.json 安装。

如果只使用 PostgreSQL，可忽略 SQLite 相关依赖的安装提示。

配置数据库

编辑 plugins/Speaker-statistics-plugin/data/config/database.json

方式一：使用 SQLite（推荐新手）

{
  "type": "sqlite",
  "path": "speech_statistics_db.db"
}

💡 路径说明：

只写文件名：默认放在插件 data 目录下

相对路径：相对于插件目录

绝对路径：直接使用该路径

方式二：使用 PostgreSQL（推荐生产环境）

{
  "type": "postgresql",
  "host": "127.0.0.1",
  "port": 5432,
  "database": "speech_statistics_db",
  "user": "speech_statistics_db",
  "password": "your_password",
  "pool": {
    "max": 20,
    "min": 5,
    "idleTimeoutMillis": 30000,
    "connectionTimeoutMillis": 2000
  },
  "ssl": false
}

启动插件

重启 Yunzai-Bot，插件会自动初始化数据库表结构与相关服务。

📊 功能详情

排行榜功能

功能	命令	说明
总榜	`#水群总榜`	查看历史累计发言排行
日榜	`#水群日榜`	查看今日发言排行
周榜	`#水群周榜`	查看本周发言排行
月榜	`#水群月榜` / `#水群榜`	查看本月发言排行
年榜	`#水群年榜`	查看今年发言排行
群统计	`#水群统计`	查看当前群聊统计信息
群信息	`#水群信息`	查看当前群聊详细信息
全局统计	`#水群总统计 [群数\|all]`	查看全局统计数据
总统计别名	`#总水群统计 [群数\|all]`	全局统计别名命令
发言趋势	`#水群趋势`	查看最近趋势（默认参数由命令逻辑决定）
自定义趋势	`#水群趋势 30`	查看最近 N 天发言趋势

个人查询功能

功能	命令	说明
个人统计	`#水群查询`	查看自己的发言统计（时/日/周/月/年/总）
查询他人	`#水群查询 @用户`	查看指定用户统计
群列表	`#水群查询群列表`	查看自己活跃过的群列表
查询他人群列表	`#水群查询群列表 @用户`	查看指定用户群列表
排行榜背景	`#水群设置背景` / `#水群背景设置`	私聊生成短期链接，设置自己的排行榜行背景

💡 昵称说明：

#水群查询、#水群查询 @用户 和排行榜会优先展示用户在当前群的群名片 / 群昵称。

统计数据仍按用户 ID 聚合，改名只影响展示名称。

#水群设置背景 / #水群背景设置 仅支持私聊使用，生成的链接会绑定当前用户并在过期后失效。

水群分析功能

功能	命令	说明
群聊分析	`#水群分析`	生成当前群聊分析报告
指定日期分析	`#水群分析今天`	支持今天、昨天、前天、`YYYY-MM-DD`
指定群分析	`#水群分析 <群号> <日期>`	手动分析指定群和日期
强制分析	`#水群强制分析 <群号> <日期>`	主人权限，忽略常规限制

💡 说明：

未配置 AI Key 时，仍可生成基础统计报告。

配置 OpenAI 兼容接口后，可启用话题分析、金句提取、用户称号等增强能力。

词云功能

功能	命令	说明
群词云	`#水群词云`	生成当天群词云
群词云（三天）	`#水群词云三天`	生成最近三天群词云
群词云（七天）	`#水群词云七天`	生成最近七天群词云
个人词云	`#我的词云`	生成自己的当天词云
个人词云（三天）	`#我的词云三天`	生成自己的最近三天词云
个人词云（七天）	`#我的词云七天`	生成自己的最近七天词云

💡 说明：

词云功能不依赖 AI Key。

词云和分析能力均受 group-analysis.json 总开关控制。

Web 管理端

配置项	说明
`web.enabled`	是否启动 Web 管理端
`web.host` / `web.port`	监听地址与端口，默认 `127.0.0.1:2655`
`web.basePath`	页面访问路径，默认 `/`
`web.apiBasePath`	API 访问路径，默认 `/api`
`web.localOnly`	是否仅允许本机访问
`web.allowExternalManageAccess`	`web.localOnly` 关闭时，是否允许公网访问普通管理端页面和统计 API
`web.accessLog`	是否记录页面访问、背景设置、上传、删除和访问拒绝日志
`web.queryLog`	网页查询概览和群组列表时是否输出全局统计计算日志
`web.backgroundEditor.enabled`	是否启用排行榜背景编辑器
`web.backgroundEditor.tokenTtlMinutes`	背景设置链接有效期，单位分钟
`web.backgroundEditor.maxImageMB`	背景图片大小限制，单位 MB

💡 说明：

Web 管理端提供统计概览、群组列表和排行查询。

默认仅本机访问，公网访问建议放在反向代理、HTTPS 和访问控制之后。

若 web.localOnly=false 且 web.allowExternalManageAccess=false，公网只能访问带 backgroundToken 的背景设置页面，局域网 IP 访问管理端保持可用。

日榜、周榜、月榜、年榜在未填写群号时按全部当前群聚合统计。

管理端“背景”页支持查看、搜索、上传替换和删除所有用户的排行榜个人背景。

排行榜背景设置链接由私聊命令生成，图片保存在 data/backgrounds/ranking/。

管理功能（仅主人）

功能	命令	说明
清除统计	`#水群清除统计`	清除当前群统计数据
同步 Redis 统计	`#水群同步Redis统计`	从数据库补当前群 Redis 消息类型统计
总同步 Redis 统计	`#水群总同步Redis统计`	从数据库补全部群 Redis 消息类型统计
设置显示人数	`#水群设置人数+<数字>`	设置排行榜显示人数
切换转发	`#水群设置开启/关闭转发`	切换转发模式
切换图片	`#水群设置开启/关闭图片`	切换图片模式
切换记录	`#水群设置开启/关闭记录`	切换消息记录
切换日志	`#水群设置开启/关闭日志`	切换调试日志
更新插件	`#水群更新`	常规更新插件
强制更新	`#水群强制更新`	覆盖本地改动并更新
归档僵尸群	`#水群归档僵尸群`	检查可归档群
确认归档	`#水群确认归档`	确认执行归档
查看归档	`#水群查看归档列表`	查看已归档群列表
刷新昵称	`#水群刷新昵称`	从当前群成员列表刷新统计昵称
总刷新昵称	`#水群总刷新昵称`	刷新所有当前群统计昵称
清理无效记录	`#水群清理无效记录`	清理当前群已退群用户统计记录
总清理无效记录	`#水群总清理无效记录`	清理所有当前群已退群用户统计记录
清理缓存	`#水群清理缓存`	清理插件缓存
帮助	`#水群帮助`	查看帮助面板

💡 统计与归档说明：

统计范围只包含当前有效群，不包含已归档群。

僵尸群是“数据库中存在，但机器人当前已不在群中的群”。

归档群若重新有消息，会自动恢复。

超过保留天数的归档群会被定时任务永久清理。

⚙️ 配置说明

配置文件结构

config/
├── configTemplate.js         # 聚合配置模板
└── templates/                # 各分组模板

data/
├── config/
│   ├── global.json           # 全局开关
│   ├── display.json          # 显示配置
│   ├── message.json          # 消息统计策略
│   ├── database.json         # 数据库配置
│   ├── storage.json          # 数据存储策略
│   ├── archived-groups.json  # 归档群清理策略
│   ├── group-analysis.json   # 水群分析 / 词云 / AI / 消息采集
│   └── web.json              # Web 管理端

配置管理

方式一：通过 Guoba-Plugin 图形界面配置（推荐）

访问 Guoba-Plugin 控制台 → 插件配置 → 发言统计插件，可管理：

✅ 全局设置
✅ 显示设置
✅ 消息统计设置
✅ 数据库配置
✅ 归档清理配置
✅ 水群分析与词云配置
✅ Web 管理端配置

方式二：直接编辑配置文件

全局配置：data/config/global.json
显示配置：data/config/display.json
消息统计配置：data/config/message.json
数据库配置：data/config/database.json
归档清理配置：data/config/archived-groups.json
水群分析配置：data/config/group-analysis.json
Web 管理端配置：data/config/web.json

重点配置说明

`global.json`

控制统计总开关、消息记录、调试日志等

`display.json`

控制显示人数、图片模式、转发模式

`message.json`

控制是否只统计文本消息
控制是否统计机器人消息
控制是否每条消息后立即刷新排行榜缓存

`database.json`

控制数据库类型与连接参数

`archived-groups.json`

控制定时清理是否启用
控制清理时间、间隔和保留天数

`group-analysis.json`

控制消息采集、词云、AI、定时报告和分析开关

`web.json`

控制 Web 管理端监听地址、端口、访问路径和本机访问限制
控制网页查询是否输出全局统计计算日志

🗂️ 数据存储

数据表结构

插件当前核心表：

表名	说明
`message_granular_stats`	小时粒度消息统计
`user_agg_stats`	用户聚合统计
`group_info`	群信息表
`archived_groups`	已归档群表

💡 说明：

旧版统计表结构不再作为当前主结构。

插件启动时会自动初始化当前版本所需表结构。

🧱 项目结构

Speaker-statistics-plugin/
├── apps/                 # 应用入口
│   └── commands/         # 命令处理
├── core/                 # 核心能力
│   ├── database/         # 数据库服务与适配器
│   ├── render/           # 渲染与模板管理
│   ├── services/         # 分析、词云、AI 等服务
│   ├── web/              # Web 管理端服务与排行辅助
│   └── utils/            # 工具模块
├── config/               # 配置模板
├── data/config/          # 运行期配置
├── guoba/                # Guoba 支持
├── resources/            # 页面模板、Web 管理端构建产物与静态资源
├── Speaker-statistics-Web/ # Web 前端源码独立仓库，插件仓库忽略该目录
├── index.js              # 插件入口
└── guoba.support.js      # Guoba 接入入口

🔄 兼容性说明

本版本重新提供轻量 Web 管理端，并支持排行榜个人背景设置与管理。
本版本已移除旧 src/* 路径。
当前版本以 data/config/*.json 为唯一主配置入口。

💬 问题反馈

如有问题或建议，欢迎：

🐛 Gitee Issues: https://gitee.com/qingyingxbot/Speaker-statistics-plugin/issues
🐛 GitHub Issues: https://github.com/QingYingX-Bot/Speaker-statistics-plugin/issues
📝 提交 Pull Request

📄 许可证

本项目采用 MIT 许可证

🙏 致谢

QingYingX & AI
group-insight
Trss-Yunzai
Guoba-Plugin
所有贡献者和测试用户

Name		Name	Last commit message	Last commit date
Latest commit History 81 Commits
apps		apps
config		config
core		core
guoba		guoba
resources		resources
.gitignore		.gitignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
README.md		README.md
guoba.support.js		guoba.support.js
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

📊 发言统计插件 (Speaker Statistics Plugin)

📦 简介

核心特性

🚀 安装方法

前置要求

安装步骤

Gitee（国内推荐）

GitHub

📊 功能详情

排行榜功能

个人查询功能

水群分析功能

词云功能

Web 管理端

管理功能（仅主人）

⚙️ 配置说明

配置文件结构

配置管理

方式一：通过 Guoba-Plugin 图形界面配置（推荐）

方式二：直接编辑配置文件

重点配置说明

global.json

display.json

message.json

database.json

archived-groups.json

group-analysis.json

web.json

🗂️ 数据存储

数据表结构

🧱 项目结构

🔄 兼容性说明

💬 问题反馈

📄 许可证

🙏 致谢

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

`global.json`

`display.json`

`message.json`

`database.json`

`archived-groups.json`

`group-analysis.json`

`web.json`

Packages