refactor :2.0.0

Author: 006lp

.env.example

@@ -0,0 +1,85 @@
+# nonebot-plugin-qqdetail 配置示例
+
+# ============ 基础配置 ============
+
+# 仅管理员可用
+# 如果设为 true，只有超级用户和群管理员可以查询他人资料
+QQDETAIL_ONLY_ADMIN=false
+
+# 黑名单用户列表
+# 这些用户的资料无法被查询
+QQDETAIL_BOX_BLACKLIST=[]
+
+# 群聊白名单
+# 仅这些群可使用命令，留空则所有群都可用
+QQDETAIL_WHITELIST_GROUPS=[]
+
+# ============ 自动获取配置 ============
+
+# 自动获取新入群用户信息
+QQDETAIL_AUTO_BOX_CONFIG__INCREASE_BOX=false
+
+# 自动获取退群用户信息
+QQDETAIL_AUTO_BOX_CONFIG__DECREASE_BOX=false
+
+# 自动获取功能的群聊白名单
+# 留空则所有群都启用自动获取
+QQDETAIL_AUTO_BOX_CONFIG__WHITE_GROUPS=[]
+
+# ============ 速率限制配置 ============
+
+# 速率限制时间（分钟）
+# 0 表示不限制，建议设置为 3-10 分钟
+QQDETAIL_RATE_LIMIT_CONFIG__TIME=0
+
+# 速率限制白名单群聊
+# 这些群不受速率限制
+QQDETAIL_RATE_LIMIT_CONFIG__WHITE_GROUPS=[]
+
+# 速率限制白名单用户
+# 这些用户不受速率限制
+QQDETAIL_RATE_LIMIT_CONFIG__WHITE_USERS=[]
+
+# ============ 显示配置 ============
+
+# 群信息
+QQDETAIL_DISPLAY_CONFIG__CARD=true
+QQDETAIL_DISPLAY_CONFIG__TITLE=true
+QQDETAIL_DISPLAY_CONFIG__LEVEL=true
+QQDETAIL_DISPLAY_CONFIG__JOIN_TIME=true
+
+# 基本信息
+QQDETAIL_DISPLAY_CONFIG__SEX=true
+QQDETAIL_DISPLAY_CONFIG__AGE=true
+
+# 生日相关
+QQDETAIL_DISPLAY_CONFIG__BIRTHDAY_CONFIG__ENABLE=true
+QQDETAIL_DISPLAY_CONFIG__BIRTHDAY_CONFIG__CONSTELLATION=true
+QQDETAIL_DISPLAY_CONFIG__BIRTHDAY_CONFIG__ZODIAC=true
+
+# 联系信息（建议关闭手机号以保护隐私）
+QQDETAIL_DISPLAY_CONFIG__PHONE_NUM=false
+QQDETAIL_DISPLAY_CONFIG__EMAIL=true
+QQDETAIL_DISPLAY_CONFIG__POST_CODE=true
+
+# 地理信息
+QQDETAIL_DISPLAY_CONFIG__HOME_TOWN=true
+QQDETAIL_DISPLAY_CONFIG__ADDRESS=true
+
+# 其他信息
+QQDETAIL_DISPLAY_CONFIG__BLOOD_TYPE=true
+QQDETAIL_DISPLAY_CONFIG__CAREER=true
+QQDETAIL_DISPLAY_CONFIG__REMARK=true
+QQDETAIL_DISPLAY_CONFIG__LABELS=true
+QQDETAIL_DISPLAY_CONFIG__UNFRIENDLY=true
+
+# VIP 信息
+QQDETAIL_DISPLAY_CONFIG__VIP_CONFIG__ENABLE=true
+QQDETAIL_DISPLAY_CONFIG__VIP_CONFIG__YEARS_VIP=true
+QQDETAIL_DISPLAY_CONFIG__VIP_CONFIG__VIP_LEVEL=true
+
+# 活动信息
+QQDETAIL_DISPLAY_CONFIG__LOGIN_DAYS=true
+
+# 个性签名
+QQDETAIL_DISPLAY_CONFIG__LONG_NICK=true

LICENSE

@@ -630,7 +630,7 @@ state the exclusion of warranty; and each file should have at least
 the "copyright" line and a pointer to where the full notice is found.
 
     <one line to give the program's name and a brief idea of what it does.>
-    Copyright (C) <year>  <name of author>
+    Copyright (C) 2025  006lp
 
     This program is free software: you can redistribute it and/or modify
     it under the terms of the GNU Affero General Public License as published

README.md

@@ -6,7 +6,7 @@
 
 <div align="center">
 
-## ✨ *基于 Nonebot2 的 QQ 详细信息查询插件* ✨
+## ✨ *基于 NoneBot2 的 QQ 用户信息查询插件* ✨
 
 <a href="./LICENSE">
     <img src="https://img.shields.io/github/license/006lp/nonebot-plugin-qqdetail.svg" alt="license">
@@ -25,20 +25,40 @@
 
 ## 📖 介绍
 
-一个简单的 NoneBot2 插件，允许机器人通过 QQ 号或 @用户 查询 QQ 用户的公开详细信息（如昵称、头像、QID、等级、IP归属地等）。数据来源于第三方 API。
+一个基于 NoneBot2 的插件，用于查询 QQ 用户的公开信息。通过 QQ 号或 @用户 方式获取用户资料，包括昵称、头像、等级、生日、VIP 等信息。数据来源于 OneBot 协议提供的用户信息接口。
 
-仅支持 OneBot V11 协议。
+目前仅支持 OneBot V11 协议。
+
+## 📁 项目结构
+
+```
+nonebot-plugin-qqdetail/
+├── __init__.py           # 插件入口，包含 PluginMetadata
+├── config.py             # 配置模型（使用 Pydantic v2）
+├── matchers.py           # 事件处理器（命令和通知）
+├── utils.py              # 工具函数和数据处理
+├── draw.py               # 图片生成逻辑
+├── assets/               # 资源文件夹（需手动创建）
+│   ├── 可爱字体.ttf      # 中文字体
+│   └── NotoColorEmoji.ttf       # Emoji 字体
+├── pyproject.toml        # 项目配置
+├── README.md             # 使用文档
+├── .env.example          # 配置示例
+└── .gitignore            # Git 忽略文件
+```
 
 ## 💿 安装
 
 <details open>
 <summary>使用 nb-cli 安装</summary>
-在 NoneBot2 项目的根目录下打开命令行，输入以下指令即可安装
+
+在 NoneBot2 项目的根目录下打开命令行，运行以下命令进行安装：
 
 ```bash
 nb plugin install nonebot-plugin-qqdetail --upgrade
 ```
-如果需要使用 PyPI 镜像源（例如清华源）：
+
+如需使用国内镜像源（如清华源）加速安装：
 
 ```bash
 nb plugin install nonebot-plugin-qqdetail --upgrade -i https://pypi.tuna.tsinghua.edu.cn/simple
@@ -47,7 +67,8 @@ nb plugin install nonebot-plugin-qqdetail --upgrade -i https://pypi.tuna.tsinghu
 
 <details>
 <summary>使用包管理器安装</summary>
-在 NoneBot2 项目的插件目录下（或项目根目录，取决于你的项目结构和包管理器），打开命令行，根据你使用的包管理器，输入相应的安装命令：
+
+在 NoneBot2 项目的根目录下（或插件目录，取决于项目结构），打开命令行，使用你偏好的包管理器运行相应命令：
 
 <details open>
 <summary>uv</summary>
@@ -104,58 +125,122 @@ plugins = ["nonebot_plugin_qqdetail"] # 确保你的插件代码在 nonebot_plug
 
 ## ⚙️ 配置
 
-插件支持通过 `.env` 文件进行配置。
-
-| 配置项               | 必填  | 默认值 | 说明                                                                      |
-| :------------------- | :---: | :----: | :------------------------------------------------------------------------ |
-| `QQDETAIL_WHITELIST` |  否   |  `[]`  | QQ 号码列表。白名单内的用户，只有超级用户才能查询其信息（自己查自己除外） |
+插件通过 `.env` 文件进行配置，所有配置项均为可选，默认为推荐设置。
+
+### 基础配置
+
+| 配置项                    | 必填  | 默认值  | 说明                                      |
+| :------------------------ | :---: | :-----: | :---------------------------------------- |
+| `QQDETAIL_ONLY_ADMIN`     |  否   | `false` | 仅管理员可用（默认：false）               |
+| `QQDETAIL_BOX_BLACKLIST`  |  否   |  `[]`   | 黑名单用户列表（这些用户的资料无法被查询） |
+| `QQDETAIL_WHITELIST_GROUPS` |  否   |  `[]`   | 群聊白名单（仅这些群可使用命令，留空则所有群都可用） |
+
+### 自动获取配置
+
+| 配置项                               | 必填  | 默认值  | 说明                                      |
+| :----------------------------------- | :---: | :-----: | :---------------------------------------- |
+| `QQDETAIL_AUTO_BOX_CONFIG__INCREASE_BOX` |  否   | `false` | 自动获取新入群用户信息                    |
+| `QQDETAIL_AUTO_BOX_CONFIG__DECREASE_BOX` |  否   | `false` | 自动获取退群用户信息                      |
+| `QQDETAIL_AUTO_BOX_CONFIG__WHITE_GROUPS` |  否   |  `[]`   | 自动获取功能的群聊白名单（留空则所有群都启用） |
+
+### 速率限制配置
+
+| 配置项                                   | 必填  | 默认值 | 说明                                      |
+| :--------------------------------------- | :---: | :----: | :---------------------------------------- |
+| `QQDETAIL_RATE_LIMIT_CONFIG__TIME`       |  否   |  `0`   | 速率限制时间（分钟），0表示不限制         |
+| `QQDETAIL_RATE_LIMIT_CONFIG__WHITE_GROUPS` |  否   |  `[]`   | 速率限制白名单群聊（这些群不受速率限制） |
+| `QQDETAIL_RATE_LIMIT_CONFIG__WHITE_USERS` |  否   |  `[]`   | 速率限制白名单用户（这些用户不受速率限制） |
+
+### 显示配置
+
+你可以精细控制要显示的用户信息字段（默认为全部显示）：
+
+| 分类     | 配置项                                           | 说明         |
+| :------- | :----------------------------------------------- | :----------- |
+| **基本信息** | `QQDETAIL_DISPLAY_CONFIG__CARD`                | 群昵称       |
+|          | `QQDETAIL_DISPLAY_CONFIG__TITLE`               | 群头衔       |
+|          | `QQDETAIL_DISPLAY_CONFIG__SEX`                 | 性别         |
+|          | `QQDETAIL_DISPLAY_CONFIG__AGE`                 | 年龄         |
+| **生日相关** | `QQDETAIL_DISPLAY_CONFIG__BIRTHDAY_CONFIG__ENABLE` | 生日         |
+|          | `QQDETAIL_DISPLAY_CONFIG__BIRTHDAY_CONFIG__CONSTELLATION` | 星座     |
+|          | `QQDETAIL_DISPLAY_CONFIG__BIRTHDAY_CONFIG__ZODIAC` | 生肖         |
+| **联系信息** | `QQDETAIL_DISPLAY_CONFIG__PHONE_NUM`            | 手机号码     |
+|          | `QQDETAIL_DISPLAY_CONFIG__EMAIL`               | 邮箱         |
+|          | `QQDETAIL_DISPLAY_CONFIG__POST_CODE`           | 邮编         |
+| **地理信息** | `QQDETAIL_DISPLAY_CONFIG__HOME_TOWN`            | 家乡         |
+|          | `QQDETAIL_DISPLAY_CONFIG__ADDRESS`             | 现居地       |
+| **其他信息** | `QQDETAIL_DISPLAY_CONFIG__BLOOD_TYPE`           | 血型         |
+|          | `QQDETAIL_DISPLAY_CONFIG__CAREER`              | 职业         |
+|          | `QQDETAIL_DISPLAY_CONFIG__REMARK`              | 备注         |
+|          | `QQDETAIL_DISPLAY_CONFIG__LABELS`              | 标签         |
+|          | `QQDETAIL_DISPLAY_CONFIG__UNFRIENDLY`          | 风险账号标记 |
+| **VIP 信息** | `QQDETAIL_DISPLAY_CONFIG__VIP_CONFIG__ENABLE`   | VIP          |
+|          | `QQDETAIL_DISPLAY_CONFIG__VIP_CONFIG__YEARS_VIP` | 年VIP        |
+|          | `QQDETAIL_DISPLAY_CONFIG__VIP_CONFIG__VIP_LEVEL` | VIP等级      |
+| **活动信息** | `QQDETAIL_DISPLAY_CONFIG__LOGIN_DAYS`           | 连续登录天数 |
+|          | `QQDETAIL_DISPLAY_CONFIG__LEVEL`               | 群等级       |
+|          | `QQDETAIL_DISPLAY_CONFIG__JOIN_TIME`           | 加群时间     |
+| **个性签名** | `QQDETAIL_DISPLAY_CONFIG__LONG_NICK`            | 个性签名     |
 
 **`.env` 文件配置示例：**
 
 ```env
-# QQDetail 插件配置
-# 白名单内的 QQ 号，只有 Superuser 可以查询 (除了用户自己查自己)
-# 值需要是有效的 JSON 列表字符串，例如: '["10001", "10002"]'
-QQDETAIL_WHITELIST='["12345678", "87654321"]'
+# 基础配置
+QQDETAIL_ONLY_ADMIN=false
+QQDETAIL_BOX_BLACKLIST=["123456789", "987654321"]
+QQDETAIL_WHITELIST_GROUPS=["123456789"]
+
+# 自动获取配置
+QQDETAIL_AUTO_BOX_CONFIG__INCREASE_BOX=false
+QQDETAIL_AUTO_BOX_CONFIG__DECREASE_BOX=false
+QQDETAIL_AUTO_BOX_CONFIG__WHITE_GROUPS=["123456789"]
+
+# 速率限制配置
+QQDETAIL_RATE_LIMIT_CONFIG__TIME=5
+QQDETAIL_RATE_LIMIT_CONFIG__WHITE_GROUPS=["123456789"]
+QQDETAIL_RATE_LIMIT_CONFIG__WHITE_USERS=["123456789"]
+
+# 显示配置（关闭手机号显示以保护隐私）
+QQDETAIL_DISPLAY_CONFIG__PHONE_NUM=false
 ```
 
-**注意:** `.env` 文件中的列表通常需要以 JSON 字符串的形式提供。
+**注意:** `.env` 具体示例参见`.env.example`。另外，文件中的列表通常需要以 JSON 字符串的形式提供。
 
 ## 🎉 使用
 
 ### 指令表
 
 | 指令                            |  别名  | 权限  | 需要@ |   范围    | 说明                                                                            |
 | :------------------------------ | :----: | :---: | :---: | :-------: | :------------------------------------------------------------------------------ |
-| `/detail <QQ号 或 @用户 或 无>` | `info` | 群员  | 可选  | 群聊/私聊 | 查询目标QQ用户的详细信息。参数可以是5-11位QQ号，@提及用户，或不带参数查询自己。 |
+| `/detail <QQ号 或 @用户 或 无>` | `info` | 群员  | 可选  | 群聊/私聊 | 查询目标 QQ 用户的详细信息。支持 QQ 号、@用户，或不带参数查询自己。 |
 
-### 说明
+### 使用说明
 
-*   **`<QQ号>`**: 必须是 5 到 11 位的纯数字。
-*   **`@用户`**: 在群聊中可以直接 @ 群成员。
-*   **无参数**: 如果直接发送 `/detail` 或 `/info`，则查询发送者本人的信息。
-*   **数据来源**: 本插件使用 `https://api.yyy001.com/` 提供的公开接口查询信息，结果的准确性和可用性取决于该 API。
-*   **白名单**: 如果配置了 `QQDETAIL_WHITELIST`，则列表中的 QQ 号只有超级用户 (`SUPERUSERS`) 可以查询，除非用户是自己查询自己。
+*   **`<QQ号>`**: 输入 5-11 位的有效 QQ 号码
+*   **`@用户`**: 在群聊中直接 @ 指定的群成员
+*   **无参数**: 直接发送指令查询发送者本人的信息
+*   **数据来源**: 基于 OneBot 协议获取用户信息，准确性取决于连接的 OneBot 实现
+*   **权限控制**: 支持多种权限控制，如管理员专用、用户黑名单等
 
 ### 🎨 返回示例
 
-*查询成功示例:*
+**查询成功示例：**
 ```
-[图片：用户头像]
-查询对象：123456789
+[图片：用户头像和彩色文字]
+QQ号：123456789
 昵称：示例昵称
-QID：example_qid
 性别：男
 年龄：20
-等级：Lv.50
-VIP等级：VIP7
-注册时间：2010-01-01
+生日：05-15
+星座：金牛座
+生肖：龙
+现居：广东-深圳
+QQ等级：50级
+注册时间：2010年
 签名：这是一个示例签名。
-IP城市：广东 深圳
-......
 ```
 
-*格式错误示例:*
+**格式错误示例：**
 ```
 命令格式错误、QQ号无效或包含多余参数。
 请使用：
@@ -164,23 +249,34 @@ IP城市：广东 深圳
 /detail (查询自己)
 ```
 
-*查询失败示例:*
+**查询失败示例：**
 ```
-获取QQ信息失败 (UID: 123456789)。
-原因：API请求失败: 404
+获取 QQ 信息失败 (UID: 123456789)。
+原因：用户信息获取失败
 ```
 
-## ⚠️ 使用警告
+## ⚠️ 重要提醒
+
+*   **学习交流用途**：本插件仅供学习和交流使用，请勿用于任何非法目的
+*   **隐私保护**：查询用户信息时请尊重他人隐私，确保使用符合相关法律法规
+*   **免责声明**：用户需对自身使用行为负责，开发者不对使用本插件产生的任何后果承担责任
+
+## 📄 许可证
+
+本项目采用 [AGPL-3.0](./LICENSE) (GNU Affero General Public License v3.0) 开源许可证。
+
+### AGPL-3.0 许可证说明
 
-*   **仅供学习交流使用！** 请勿用于非法用途。
-*   **尊重隐私！** 查询他人信息可能涉及隐私，请确保你的使用符合相关法律法规和平台规定。
-*   **数据准确性！** 插件依赖第三方 API，无法保证信息的绝对准确性和实时性。
-*   用户应对自己的使用行为负责，开发者不承担任何因使用此插件造成的直接或间接责任。
+AGPL-3.0 是 GNU 自由软件基金会发布的开源许可证，特别适用于网络应用。其主要特点包括：
 
-## 📃 许可证
+* **网络服务条款**：如果您修改本软件并通过网络提供服务，必须公开修改后的完整源代码
+* **Copyleft 特性**：任何基于本项目的衍生作品必须采用相同的许可证
+* **用户自由保护**：确保用户在使用网络服务时享有修改和再分发的自由
 
-本项目采用 [AGPL-3.0](./LICENSE) 许可证。
+有关许可证的完整条款，请查看 [LICENSE](./LICENSE) 文件或访问 [GNU 官网](https://www.gnu.org/licenses/agpl-3.0.html)。
 
 ## 🙏 致谢
 
-*   **API 提供方**: [https://api.yyy001.com/](https://api.yyy001.com/)
+*   **NoneBot2 社区**：提供了优秀的机器人开发框架
+*   **OneBot 协议**：提供了标准化的机器人通信协议
+*   **AstrbotPlugin-ProfileSearch**：本插件参考了其设计思路