nonebot-plugin-time-card 1.0.4

Nonebot 2 plugin for auto-updating bot's group nickname with real-time time

nonebot-plugin-time-card

✨ NoneBot 插件简单描述 ✨

插件介绍

time_card 是一款基于 Nonebot v2.4.3 + OneBot v11 适配器的 QQ 机器人插件，核心功能为自动更新机器人在群聊中的昵称并显示实时时间，支持超级管理员灵活控制功能开关与配置重载，无需重启机器人即可生效。

功能特性

• 🕒 实时时间昵称：机器人昵称自动更新为「前缀 + 当前时间 + 后缀」格式，默认前缀为「梦&专属机器人」
• ⚙️ 全配置化支持：所有核心参数可通过 .env 文件自定义，无需修改代码
• 🔌 灵活控制：超级管理员可单独开关某个群的功能，支持插件热重载
• 🚨 错误反馈：所有操作错误（如权限不足、昵称过长）直接发送到对应群聊，不占用终端输出
• ⏰ 定时更新：可自定义时间更新间隔（默认 60 秒），确保时间准确性

依赖环境

依赖项	版本要求	说明
Nonebot	≥ v2.4.3	插件开发基准框架
OneBot 适配器	≥ v2.2.0	用于与 QQ 协议对接（如 go-cqhttp、LLOneBot 等）
Python	≥ 3.8	运行环境

💿 安装

使用 nb-cli 安装

在 nonebot2 项目的根目录下打开命令行, 输入以下指令即可安装

nb plugin install nonebot-plugin-time-card

使用包管理器安装

在 nonebot2 项目的插件目录下, 打开命令行, 根据你使用的包管理器, 输入相应的安装命令

pip

pip install nonebot-plugin-template

打开 nonebot2 项目根目录下的 pyproject.toml 文件, 在 [tool.nonebot] 部分追加写入

plugins = ["nonebot_plugin_template"]

配置说明

所有配置项均在项目根目录的 .env 文件中定义，支持动态修改（修改后执行「重载时间昵称」命令生效）。

配置项	类型	默认值	说明
time_card_nickname_prefix	字符串	梦&专属机器人	时间昵称的前缀内容
time_card_nickname_suffix	字符串	空字符串	时间昵称的后缀内容（可留空）
time_card_time_format	字符串	%Y-%m-%d %H:%M	时间显示格式（遵循 Python datetime 格式化规则）
time_card_enabled_by_default	布尔值	true	机器人新加入群聊时，是否默认开启时间昵称功能
time_card_update_interval	整数	60	时间昵称的更新间隔（单位：秒，建议 ≥ 30 秒）

配置示例

# .env 文件配置示例
time_card_nickname_prefix="我的专属机器人"
time_card_nickname_suffix="(在线)"
time_card_time_format="%m-%d %H:%M"  # 显示为「月-日 时:分」
time_card_enabled_by_default=true
time_card_update_interval=30  # 每30秒更新一次

使用说明

1. 基础功能

插件加载后，机器人会自动：

• 对已加入的所有群聊，按默认配置生成时间昵称
• 新加入群聊时，根据 time_card_enabled_by_default 配置决定是否开启功能
• 按 time_card_update_interval 配置的间隔自动更新昵称

2. 超级管理员命令

仅 Nonebot 配置的「超级管理员」可使用以下命令（无需@机器人，支持自定义命令前缀）：

命令	功能	适用场景
开关时间昵称	切换当前群的时间昵称功能（开启 ↔ 关闭）	单独关闭某个群的功能，或重新开启
重载时间昵称	重载插件配置与定时任务	修改 .env 配置后生效，或修复功能异常

命令示例

• 发送 开关时间昵称 → 群内回复「【时间昵称】已关闭」（再次发送则开启）
• 发送 重载时间昵称 → 群内回复「【时间昵称】插件已重载（配置与定时任务已更新）」

错误处理

插件会将所有错误信息直接发送到对应群聊，常见错误及解决方案如下：

错误提示	原因	解决方案
修改失败：权限不足或昵称过长	1. 机器人无「修改群昵称」权限 2. 生成的昵称超过 QQ 群昵称长度限制（≤16 字符）	1. 群管理给机器人开放「修改群昵称」权限 2. 缩短 time_card_nickname_prefix 或 time_card_nickname_suffix
更新错误：[具体异常信息]	网络波动、机器人离线或 OneBot 服务异常	1. 检查机器人是否在线 2. 重启 OneBot 服务（如 go-cqhttp）

注意事项

1. 昵称长度限制：QQ 群昵称最大支持 16 个字符，配置时需确保「前缀 + 时间 + 后缀」总长度 ≤ 16（例如默认配置「梦&专属机器人 2024-05-20 14:30」共 15 字符，符合要求）。
2. 权限要求：机器人需拥有「修改群昵称」权限（群管理可在「群设置 → 权限设置」中开启）。
3. 性能建议：若机器人加入大量群聊（≥50 个），建议将 time_card_update_interval 调整为 60~120 秒，避免频繁 API 调用导致性能问题。
4. 热重载限制：重载插件时会重启定时任务，可能导致 1~2 秒内无更新，属于正常现象。

常见问题（FAQ）

Q1：修改 .env 配置后，如何让配置生效？

A：超级管理员在任意群发送 重载时间昵称 命令，配置会立即生效，无需重启 Nonebot。

Q2：如何查看当前群的功能状态？

A：发送 开关时间昵称 命令，群内会回复当前状态（如「已开启」或「已关闭」），同时切换状态。

Q3：插件支持多机器人吗？

A：目前仅支持单机器人实例，多机器人环境下可能出现定时任务冲突，建议单独为每个机器人配置插件。

Q4：为什么机器人入群后没有自动开启功能？

A：检查 .env 中 time_card_enabled_by_default 是否设为 true，若为 false，需手动发送 开关时间昵称 开启。

版本更新记录

版本	更新时间	更新内容
v1.0.0	2024-05	初始版本 - 实现时间昵称自动更新 - 支持超级管理员命令控制 - 全配置化支持

反馈与维护

若遇到插件 Bug 或功能需求，可通过以下方式反馈：

1. 提交 GitHub Issue（若插件托管于 GitHub）
2. 联系插件开发者（需自行补充联系方式）

维护说明：插件基于 Nonebot v2.4.3 开发，后续若 Nonebot 框架重大更新，可能需要适配调整。