nonebot-plugin-time-card 1.0.11
Nonebot 2.4.3 插件：自动更新机器人群聊昵称并显示实时时间，支持超级管理员开关与热重载
Requires Python: >=3.8
Keywords: nonebot2, nonebot-plugin, qqbot, time-card

<div align="center">
  <a href="https://v2.nonebot.dev/store"><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/nbp_logo.png" width="180" height="180" alt="NoneBotPluginLogo"></a>
  <br>
  <p><img src="https://github.com/A-kirami/nonebot-plugin-template/blob/resources/NoneBotPlugin.svg" width="240" alt="NoneBotPluginText"></p>
</div>

<div align="center">

# nonebot-plugin-time-card

_✨ NoneBot 插件简单描述 ✨_


<a href="./LICENSE">
    <img src="https://img.shields.io/github/license/owner/nonebot-plugin-template.svg" alt="license">
</a>
<a href="https://pypi.python.org/pypi/nonebot-plugin-template">
    <img src="https://img.shields.io/pypi/v/nonebot-plugin-template.svg" alt="pypi">
</a>
<img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="python">

</div>

## 插件介绍

`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 | 运行环境 |


## 💿 安装

<details open>
<summary>使用 nb-cli 安装</summary>
在 nonebot2 项目的根目录下打开命令行, 输入以下指令即可安装

    nb plugin install nonebot-plugin-time-card

</details>

<details>
<summary>使用包管理器安装</summary>
在 nonebot2 项目的插件目录下, 打开命令行, 根据你使用的包管理器, 输入相应的安装命令

<details>
<summary>pip</summary>

    pip install nonebot-plugin-template
</details>

打开 nonebot2 项目根目录下的 `pyproject.toml` 文件, 在 `[tool.nonebot]` 部分追加写入

    plugins = ["nonebot_plugin_template"]

</details>

## 配置说明

所有配置项均在项目根目录的 `.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 秒） |

### 配置示例
```ini
# .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. 机器人无「修改群昵称」权限<br>2. 生成的昵称超过 QQ 群昵称长度限制（≤16 字符） | 1. 群管理给机器人开放「修改群昵称」权限<br>2. 缩短 `time_card_nickname_prefix` 或 `time_card_nickname_suffix` |
| `更新错误：[具体异常信息]` | 网络波动、机器人离线或 OneBot 服务异常 | 1. 检查机器人是否在线<br>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 | 初始版本<br>- 实现时间昵称自动更新<br>- 支持超级管理员命令控制<br>- 全配置化支持 |


## 反馈与维护

若遇到插件 Bug 或功能需求，可通过以下方式反馈：
1. 提交 GitHub Issue（若插件托管于 GitHub）
2. 联系插件开发者（需自行补充联系方式）

维护说明：插件基于 Nonebot v2.4.3 开发，后续若 Nonebot 框架重大更新，可能需要适配调整。