Metadata-Version: 2.4
Name: nonebot-plugin-time-card
Version: 1.0.2
Summary: Nonebot 2 plugin for auto-updating bot's group nickname with real-time time
Author: meng
License: MIT License
        
        Copyright (c) 2025 Meng
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
Project-URL: Homepage, https://github.com/MengdeUser/nonebot-plugin-time-card
Project-URL: Issue Tracker, https://github.com/MengdeUser/nonebot-plugin-time-card/issues
Keywords: nonebot2,nonebot-plugin,qqbot,time-card
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Utilities
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: nonebot2<3.0.0,>=2.4.3
Requires-Dist: nonebot-adapter-onebot<3.0.0,>=2.2.0
Requires-Dist: python<3.12,>=3.8
Dynamic: license-file

<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 框架重大更新，可能需要适配调整。
