nb plugin install nonebot-plugin-wordcloud如需使用可选文本分析后端，可额外安装：
pip install "nonebot-plugin-wordcloud[rjieba]"Note
如需通过命令设置词云形状，则需使用支持 http 请求的驱动器，如 httpx 和 aiohttp。
请参考 配置驱动器 文档进行设置。
例如：
DRIVER=~httpx
DRIVER=~aiohttp
DRIVER=~fastapi+~httpx
- 查看帮助
待插件启动完成后，发送 /词云 可获取插件使用方法。
- 查看词云
| 功能 | 命令 | 权限 | 说明 |
|---|---|---|---|
| 查看今日词云 | /今日词云 |
所有人（command.wordcloud.query） |
获取今日的词云 |
| 查看昨日词云 | /昨日词云 |
所有人（command.wordcloud.query） |
获取昨日的词云 |
| 查看本周词云 | /本周词云 |
所有人（command.wordcloud.query） |
获取本周的词云 |
| 查看上周词云 | /上周词云 |
所有人（command.wordcloud.query） |
获取上周的词云 |
| 查看本月词云 | /本月词云 |
所有人（command.wordcloud.query） |
获取本月的词云 |
| 查看上月词云 | /上月词云 |
所有人（command.wordcloud.query） |
获取上月的词云 |
| 查看年度词云 | /年度词云 |
所有人（command.wordcloud.query） |
获取年度的词云 |
| 查看历史词云 | /历史词云 |
所有人（command.wordcloud.query） |
获取指定时间段的词云 |
数据范围说明：
- 当
wordcloud_default_personal配置为False（默认）时，上述命令默认获取群组数据 - 当
wordcloud_default_personal配置为True时，上述命令默认获取个人数据 - 可以使用前缀明确指定数据范围：
- 添加
我的前缀获取个人词云，如/我的今日词云 - 添加
本群前缀获取群组词云，如/本群今日词云
- 添加
权限插件说明：
本插件集成 nonebot-plugin-permission， 可通过权限插件管理以下资源：
| 权限资源 | 默认拥有者 | 说明 |
|---|---|---|
command.wordcloud.query |
所有用户 | 使用词云查询命令 |
command.wordcloud.query_other |
PERMISSION_SUPERUSERS |
通过 @ 查看他人词云 |
command.wordcloud.mask |
PERMISSION_SUPERUSERS、群主/管理员 |
设置或删除本群形状 |
command.wordcloud.default_mask |
PERMISSION_SUPERUSERS |
设置或删除默认形状 |
command.wordcloud.schedule |
PERMISSION_SUPERUSERS、群主/管理员 |
管理定时发送 |
- 管理词云
| 功能 | 命令 | 权限 | 说明 |
|---|---|---|---|
| 设置词云形状 | /设置词云形状 |
command.wordcloud.mask |
发送一张图片作为当前群词云形状，每个群各自独立 |
| 删除词云形状 | /删除词云形状 |
command.wordcloud.mask |
删除本群词云形状 |
| 设置词云默认形状 | /设置词云默认形状 |
command.wordcloud.default_mask |
发送一张图片作为所有词云的默认形状，每个群都会改变 |
| 删除词云默认形状 | /删除词云默认形状 |
command.wordcloud.default_mask |
删除默认词云形状，继续使用词云默认的矩形 |
| 开启词云定时发送 | /开启词云<类型>定时发送 或/开启词云<类型>定时发送 + [时间] |
command.wordcloud.schedule |
开启本群定时发送词云，类型支持 每日、每周、每月、每年。默认发送上一完整周期：每日发送昨日词云；每周在周一发送上周词云；每月在 1 日发送上月词云；每年在 1 月 1 日发送去年词云。添加 --last 或使用 开启词云每周周期末定时发送 这样的快捷命令，可在周期最后一天发送截至触发时间的词云；添加 --complete 或使用 开启词云每周完整周期定时发送 可显式使用完整周期模式。没有指定模式时使用 wordcloud_default_schedule_mode。没有指定时间时，完整周期默认在 00:00 发送，周期末默认在 23:59:59 发送；如果配置了 wordcloud_default_schedule_time，则使用该配置。如果时间没有包含时区信息，则根据 wordcloud_timezone 配置项确定时区。时间的格式为 ISO 8601，例如： 开启词云每周定时发送 23:59:59 |
| 关闭词云定时发送 | /关闭词云<类型>定时发送 |
command.wordcloud.schedule |
关闭本群指定类型的词云定时发送 |
| 查看词云定时发送状态 | /词云<类型>定时发送状态 |
command.wordcloud.schedule |
查看指定类型的定时发送状态 |
配置方式：直接在 NoneBot 全局配置文件（.env） 中添加以下配置项
| 配置项 | 类型 | 默认值 | 说明 |
|---|---|---|---|
| wordcloud_width | int | 1920 |
生成图片的宽度 |
| wordcloud_height | int | 1200 |
生成图片的高度 |
| wordcloud_background_color | str | black |
生成图片的背景颜色 |
| wordcloud_colormap | Union[str, List[str]] | viridis |
生成图片的字体 色彩映射表（当值为列表时会随机选择其中之一） |
| wordcloud_font_path | str | 自带的字体（思源黑体） | 生成图片的字体文件位置 |
| wordcloud_analyzer | str | jieba |
文本分析后端，可选 jieba、rjieba。jieba 后端沿用 TF-IDF 关键词权重；rjieba 后端使用词频权重 |
| wordcloud_analyzer_options | Dict[str, Any] | {} |
传递给文本分析后端的额外参数。jieba 支持传递给 jieba.analyse.extract_tags 的参数；rjieba 支持 mode（default、search、all）和 hmm |
| wordcloud_min_word_length | int | 2 |
rjieba 后端统计词频时保留的最小词长 |
| wordcloud_stopwords_path | str | None | 停用词表位置，用来屏蔽某些词语。jieba 后端会传递给 jieba.analyse.set_stop_words；rjieba 后端会按行读取词语并过滤 |
| wordcloud_userdict_path | str | None | 自定义词典位置。jieba 后端会加载为结巴词典；rjieba 后端暂不支持该配置 |
| wordcloud_timezone | str | None | 用户自定义的 时区， 留空则使用系统时区，具体数值可参考：时区列表， 例如： Asia/Shanghai |
| wordcloud_default_schedule_mode | str | 完整周期 |
默认定时发送模式，可选 完整周期 或 周期末 |
| wordcloud_default_schedule_time | str | 根据发送模式决定 | 默认定时发送时间，当开启词云定时发送时没有提供具体时间，将会在这个时间发送词云。 未配置时，完整周期默认为 00:00，周期末默认为 23:59:59；配置后会覆盖所有默认发送模式的时间 |
| wordcloud_options | Dict[str, Any] |
{} |
向 WordCloud 传递的参数。 拥有最高优先级，将会覆盖以上词云的配置项， 例如： {"background_color":"black","max_words":2000,"contour_width":3, "contour_color":"steelblue"} |
| wordcloud_exclude_user_ids | Set[str] |
set() |
排除的用户 ID 列表（全局，不区分平台）， 例如： ["123456","456789"] |
| wordcloud_reply_message | bool | False |
发送词云图片时是否回复触发它的消息 |
| wordcloud_default_personal | bool | False |
是否默认获取个人数据，设为 True 时默认生成个人词云，设为 False 时默认生成群组词云 |
词云生成前会先把聊天文本分析为“词语 -> 权重”的映射，再交给 wordcloud 生成图片。不同后端的分词方式、权重算法和依赖体积不同，可以通过 wordcloud_analyzer 选择。
| 后端 | 额外依赖 | 权重算法 | 适合场景 | 主要限制 |
|---|---|---|---|---|
jieba |
默认安装 | TF-IDF | 默认选择，兼容旧版本生成效果 | jieba 本身维护较慢，但支持停用词和用户词典，行为与旧版本保持一致 |
rjieba |
nonebot-plugin-wordcloud[rjieba] |
词频 | 希望使用更轻量、更快的 jieba 风格分词 | 暂不支持 wordcloud_userdict_path；没有 TF-IDF 关键词抽取 |
jieba 是默认后端，不需要额外配置：
wordcloud_analyzer=jieba它会继续使用 jieba.analyse.extract_tags 提取关键词，权重为 TF-IDF。wordcloud_stopwords_path 会传递给 jieba.analyse.set_stop_words，wordcloud_userdict_path 会传递给 jieba.load_userdict。
wordcloud_analyzer_options 可传递给 jieba.analyse.extract_tags，例如：
{
"topK": 200,
"allowPOS": ["n", "vn", "v"]
}rjieba 使用 Rust 实现的 jieba 风格分词，适合想减少分词耗时、但不需要 TF-IDF 权重的场景：
wordcloud_analyzer=rjieba它会按分词结果统计词频，并使用 wordcloud_min_word_length 和 wordcloud_stopwords_path 过滤词语。当前 rjieba Python 绑定没有暴露用户词典加载接口，因此会忽略 wordcloud_userdict_path 并记录警告。
wordcloud_analyzer_options 支持：
{
"mode": "search",
"hmm": true
}其中 mode 可选 default、search、all。
项目代码使用 MIT License 发布。包内自带的默认字体 SourceHanSans.otf
来自 Source Han Sans，
按 SIL Open Font License 1.1 许可随包分发；完整字体许可证见
nonebot_plugin_wordcloud/SourceHanSans.LICENSE.txt。
插件依赖 nonebot-plugin-chatrecorder 提供消息存储。
感谢以下开发者作出的贡献：