nonebot-plugin-dialectlist 2.0.4__tar.gz → 2.1.4__tar.gz

nonebot_plugin_dialectlist-2.1.4/PKG-INFO

@@ -0,0 +1,203 @@
+Metadata-Version: 2.1
+Name: nonebot_plugin_dialectlist
+Version: 2.1.4
+Summary: 看看你群群友有多能说
+Author-email: Chen_Xu233 <woyerpa@outlook.com>
+License: MIT
+Requires-Python: <4.0,>=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: nonebot2>=2.3.1
+Requires-Dist: nonebot-plugin-chatrecorder>=0.6.0
+Requires-Dist: pygal>=3.0.4
+Requires-Dist: requests>=2.32.3
+Requires-Dist: nonebot-plugin-apscheduler>=0.4.0
+Requires-Dist: nonebot-plugin-alconna>=0.46.6
+Requires-Dist: nonebot-plugin-cesaa>=0.4.0
+Requires-Dist: nonebot-plugin-userinfo>=0.2.4
+Requires-Dist: pyecharts>=2.0.5
+Requires-Dist: nonebot-plugin-htmlrender>=0.3.2
+Provides-Extra: dev
+Requires-Dist: ruff>=0.4.9; extra == "dev"
+Requires-Dist: setuptools>=70.0.0; extra == "dev"
+Requires-Dist: twine>=5.1.0; extra == "dev"
+Requires-Dist: nb-cli>=0.7.6; extra == "dev"
+
+<div align="center">
+  <a href="https://v2.nonebot.dev/store"><img src="./docs/NoneBotPlugin.svg" width="400" alt="NoneBotPluginLogo"></a>
+  <br>
+  <p><img src="https://s2.loli.net/2022/06/16/xsVUGRrkbn1ljTD.png" width="240" alt="NoneBotPluginText"></p>
+</div>
+
+<div align="center">
+
+# 📃话痨排行榜
+nonebot-plugin-dialectlist
+
+<p align="center">
+  <a href="https://pypi.python.org/pypi/nonebot-plugin-wordcloud">
+    <img src="https://img.shields.io/pypi/v/nonebot-plugin-wordcloud.svg" alt="pypi">
+  </a>
+  
+  <img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="python">
+  
+  <a href="https://qm.qq.com/q/Yty2yc9Bee">
+    <img src="https://img.shields.io/badge/QQ%E7%BE%A4-1128359833-orange?style=flat-square" alt="QQ Chat Group">
+  </a>
+</p>
+
+\>💬**看看群友们这些天在群里水了多少话**💬<
+</div>
+
+## 💿 安装
+
+通过`pip`或`nb`安装；
+
+>**通过 pip **安装
+
+`pip install nonebot-plugin-dialectlist`
+
+>**通过 nb **安装
+
+`nb plugin install nonebot-plugin-dialectlist`
+
+### ✅ 插件依赖于
+
+1. [nonebot-plugin-datastore](https://github.com/he0119/nonebot-plugin-datastore) ————储存历史的消息
+2. [nonebot-plugin-userinfo](https://github.com/noneplugin/nonebot-plugin-userinfo) ————获取用户信息
+3. [nonebot-plugin-apscheduler](https://github.com/nonebot/plugin-apscheduler) ————定时发送排行榜信息
+4. [nonebot-plugin-alconna](https://github.com/ArcletProject/nonebot-plugin-alconna) ————实现命令解析
+5. [nonebot-plugin-cesaa](https://github.com/MountainDash/nonebot-plugin-send-anything-anywhere) ————实现多平台
+  
+## ⚙ 配置
+
+需要**提前配置**本插件所**依赖的插件**！
+
+在 .env 中，可以添加以下配置项
+```python
+dialectlist__string_format = '第{index}名：\n{nickname},{chatdatanum}条消息、n' #消息格式
+dialectlist__string_suffix_format = '你们的职业是水群吗？————MYX\n 计算花费时间：{timecost}秒' #消息后缀格式
+dialectlist__get_num = 10 #获取人数数量
+dialectlist__visualization = True #是否可视化
+dialectlist__visualization_type = '圆环图' #可视化方案
+dialectlist__font = 'SimHei'#字体格式
+dialectlist__excluded_people = []#排除的人的 QQ 号（或频道号？（未经测试）)
+dialectlist__excluded_self = True #是否排除机器人自己 QQ
+```
+💭也可以不进行配置，这将会使插件按照默认配置运行
+
+ ### ⚠ 注意！！
+
+> 在旧版插件（2.0.0 以下）中，dialectlist 与后面的配置项只隔了一个下划线，若更新到新版本以后需要俩个下划线。
+
+## 🗨命令
+__！！注意！！__
+新版本指令调用方式改变，改为更易理解也更好打的 B 话榜。
+同时也可以用类似 `/今日废话榜` 的方式(只要改前面的就好了)（算是给[盘古之白](https://github.com/vinta/pangu.js)风格爱好者的福利吧？）
+
+### 🎨一般用法
+
+-`/B话榜` ————看看有史以来（机器人存在以来）群友们发了多少消息！ (好像没写)
+
+-`/今日B话榜` ————看看今天的群友发了多少消息！
+
+-`/昨日B话榜` ————看看昨天的群友发了多少消息！
+
+-`/前日B话榜` ————看看前天的群友发了多少消息！
+
+-`/本周B话榜` ————看看本周的群友发了多少消息！
+  
+-`/上周B话榜` ————看看上周的群友发了多少消息！
+
+-`/本月B话榜` ————看看这个月的群友发了多少消息！
+
+-`/年度B话榜` ————看看今年的群友发了多少消息！
+
+-`/历史B话榜` ————看看历史上（机器人存在以来）的群友发了多少消息！
+
+### 🚀进阶用法
+
+`/{时间类型(今日|年度)?}{B话榜|废话榜} {时间类型?} {ISO8601格式时间} {群号}`
+
+如：`/B话榜 历史 2024-01-01~2024-01-02 12345678`
+
+
+## 📖版本
+  
+### V1.0
+  
+  - 看看群里群友能有多话痨
+  
+### V1.1
+  
+  - 支持频道咯！(*^_^*)
+  
+### V1.2
+  
+  - 排行榜可视化
+  
+### V1.3
+
+  - 添加了一些可配置项
+  
+### V1.4
+
+  - 适配新版本的 chatrecorder, 暂时停止频道支持
+
+### V2.0
+
+  - 理论支持全平台！暂停图片支持。
+
+## 💪 目前支持的平台
+
+| 平台 | 是否经过测试 | 是否能够正常工作 | 测试环境 |
+|:-----:|:----:|:----:| :----: |
+| Onebot | ✅ | ✅ | NapCat + Window11|
+| 飞书  | ❌ | ❓ | 🤔 |
+| Red  | ❌ | ❓ | 🤔 |
+| DoDo  | ❌ | ❓ | 🤔 |
+| Mirai  | ❌ | ❓ | 🤔 |
+| 开黑啦  | ❌ | ❓ | 🤔 |
+| Kritor  | ❌ | ❓ | 🤔 |
+| Ntchat  | ❌ | ❓ | 🤔 |
+| Satori  | ❌ | ❓ | 🤔 |
+| Telegram | ❌ | ❓ | 🤔  |
+| Discord  | ❌ | ❓ | 🤔 |
+| Tailchat  | ❌ | ❓ | 🤔 |
+| QQ 官方接口  | ❌ | ❓ | 🤔 |
+| Rocket.Chat  | ❌ | ❓ | 🤔 |
+
+- 如果你测试过能够使用，请在 Issue 中指出
+
+## 📦另外
+
+### 😳加入作者的 BUG 反馈群 ~~（🥵女装粉丝群）~~
+
+[群连接](https://qm.qq.com/q/Yty2yc9Bee)
+
+<details>
+<summary>群二维码 点我展开</summary>
+
+![7a4bd22dea47d25d9b632d4b2696d4cd](https://github.com/ChenXu233/nonebot_plugin_dialectlist/assets/91937041/61fd7010-e2b2-4f13-b209-9c0faf8a517f)
+
+</details>
+
+### 💕感谢
+
+本插件的__init__.py 中的处理函数参考了词云中的方法 ~~（其实大部分都是 Ctrl+C Ctr+V）~~
+
+[nonebot-plugin-wordcloud](https://github.com/he0119/nonebot-plugin-wordcloud)
+  
+### 🎀TODO
+
+- [x] 适配全平台
+
+- [ ] 私聊的查询（超级用户可以任意查询群聊的信息）
+
+- [ ] 关键词查询
+
+- [ ] 尝试利用 jinja2 模板引擎制作可视化图片 ((（真的可以吗？))
+  
+ 待补充。.....
+
+### 👾题外话
+~~整个项目快被我写成屎山了~~

nonebot_plugin_dialectlist-2.1.4/README.md

@@ -0,0 +1,179 @@
+<div align="center">
+  <a href="https://v2.nonebot.dev/store"><img src="./docs/NoneBotPlugin.svg" width="400" alt="NoneBotPluginLogo"></a>
+  <br>
+  <p><img src="https://s2.loli.net/2022/06/16/xsVUGRrkbn1ljTD.png" width="240" alt="NoneBotPluginText"></p>
+</div>
+
+<div align="center">
+
+# 📃话痨排行榜
+nonebot-plugin-dialectlist
+
+<p align="center">
+  <a href="https://pypi.python.org/pypi/nonebot-plugin-wordcloud">
+    <img src="https://img.shields.io/pypi/v/nonebot-plugin-wordcloud.svg" alt="pypi">
+  </a>
+  
+  <img src="https://img.shields.io/badge/python-3.9+-blue.svg" alt="python">
+  
+  <a href="https://qm.qq.com/q/Yty2yc9Bee">
+    <img src="https://img.shields.io/badge/QQ%E7%BE%A4-1128359833-orange?style=flat-square" alt="QQ Chat Group">
+  </a>
+</p>
+
+\>💬**看看群友们这些天在群里水了多少话**💬<
+</div>
+
+## 💿 安装
+
+通过`pip`或`nb`安装；
+
+>**通过 pip **安装
+
+`pip install nonebot-plugin-dialectlist`
+
+>**通过 nb **安装
+
+`nb plugin install nonebot-plugin-dialectlist`
+
+### ✅ 插件依赖于
+
+1. [nonebot-plugin-datastore](https://github.com/he0119/nonebot-plugin-datastore) ————储存历史的消息
+2. [nonebot-plugin-userinfo](https://github.com/noneplugin/nonebot-plugin-userinfo) ————获取用户信息
+3. [nonebot-plugin-apscheduler](https://github.com/nonebot/plugin-apscheduler) ————定时发送排行榜信息
+4. [nonebot-plugin-alconna](https://github.com/ArcletProject/nonebot-plugin-alconna) ————实现命令解析
+5. [nonebot-plugin-cesaa](https://github.com/MountainDash/nonebot-plugin-send-anything-anywhere) ————实现多平台
+  
+## ⚙ 配置
+
+需要**提前配置**本插件所**依赖的插件**！
+
+在 .env 中，可以添加以下配置项
+```python
+dialectlist__string_format = '第{index}名：\n{nickname},{chatdatanum}条消息、n' #消息格式
+dialectlist__string_suffix_format = '你们的职业是水群吗？————MYX\n 计算花费时间：{timecost}秒' #消息后缀格式
+dialectlist__get_num = 10 #获取人数数量
+dialectlist__visualization = True #是否可视化
+dialectlist__visualization_type = '圆环图' #可视化方案
+dialectlist__font = 'SimHei'#字体格式
+dialectlist__excluded_people = []#排除的人的 QQ 号（或频道号？（未经测试）)
+dialectlist__excluded_self = True #是否排除机器人自己 QQ
+```
+💭也可以不进行配置，这将会使插件按照默认配置运行
+
+ ### ⚠ 注意！！
+
+> 在旧版插件（2.0.0 以下）中，dialectlist 与后面的配置项只隔了一个下划线，若更新到新版本以后需要俩个下划线。
+
+## 🗨命令
+__！！注意！！__
+新版本指令调用方式改变，改为更易理解也更好打的 B 话榜。
+同时也可以用类似 `/今日废话榜` 的方式(只要改前面的就好了)（算是给[盘古之白](https://github.com/vinta/pangu.js)风格爱好者的福利吧？）
+
+### 🎨一般用法
+
+-`/B话榜` ————看看有史以来（机器人存在以来）群友们发了多少消息！ (好像没写)
+
+-`/今日B话榜` ————看看今天的群友发了多少消息！
+
+-`/昨日B话榜` ————看看昨天的群友发了多少消息！
+
+-`/前日B话榜` ————看看前天的群友发了多少消息！
+
+-`/本周B话榜` ————看看本周的群友发了多少消息！
+  
+-`/上周B话榜` ————看看上周的群友发了多少消息！
+
+-`/本月B话榜` ————看看这个月的群友发了多少消息！
+
+-`/年度B话榜` ————看看今年的群友发了多少消息！
+
+-`/历史B话榜` ————看看历史上（机器人存在以来）的群友发了多少消息！
+
+### 🚀进阶用法
+
+`/{时间类型(今日|年度)?}{B话榜|废话榜} {时间类型?} {ISO8601格式时间} {群号}`
+
+如：`/B话榜 历史 2024-01-01~2024-01-02 12345678`
+
+
+## 📖版本
+  
+### V1.0
+  
+  - 看看群里群友能有多话痨
+  
+### V1.1
+  
+  - 支持频道咯！(*^_^*)
+  
+### V1.2
+  
+  - 排行榜可视化
+  
+### V1.3
+
+  - 添加了一些可配置项
+  
+### V1.4
+
+  - 适配新版本的 chatrecorder, 暂时停止频道支持
+
+### V2.0
+
+  - 理论支持全平台！暂停图片支持。
+
+## 💪 目前支持的平台
+
+| 平台 | 是否经过测试 | 是否能够正常工作 | 测试环境 |
+|:-----:|:----:|:----:| :----: |
+| Onebot | ✅ | ✅ | NapCat + Window11|
+| 飞书  | ❌ | ❓ | 🤔 |
+| Red  | ❌ | ❓ | 🤔 |
+| DoDo  | ❌ | ❓ | 🤔 |
+| Mirai  | ❌ | ❓ | 🤔 |
+| 开黑啦  | ❌ | ❓ | 🤔 |
+| Kritor  | ❌ | ❓ | 🤔 |
+| Ntchat  | ❌ | ❓ | 🤔 |
+| Satori  | ❌ | ❓ | 🤔 |
+| Telegram | ❌ | ❓ | 🤔  |
+| Discord  | ❌ | ❓ | 🤔 |
+| Tailchat  | ❌ | ❓ | 🤔 |
+| QQ 官方接口  | ❌ | ❓ | 🤔 |
+| Rocket.Chat  | ❌ | ❓ | 🤔 |
+
+- 如果你测试过能够使用，请在 Issue 中指出
+
+## 📦另外
+
+### 😳加入作者的 BUG 反馈群 ~~（🥵女装粉丝群）~~
+
+[群连接](https://qm.qq.com/q/Yty2yc9Bee)
+
+<details>
+<summary>群二维码 点我展开</summary>
+
+![7a4bd22dea47d25d9b632d4b2696d4cd](https://github.com/ChenXu233/nonebot_plugin_dialectlist/assets/91937041/61fd7010-e2b2-4f13-b209-9c0faf8a517f)
+
+</details>
+
+### 💕感谢
+
+本插件的__init__.py 中的处理函数参考了词云中的方法 ~~（其实大部分都是 Ctrl+C Ctr+V）~~
+
+[nonebot-plugin-wordcloud](https://github.com/he0119/nonebot-plugin-wordcloud)
+  
+### 🎀TODO
+
+- [x] 适配全平台
+
+- [ ] 私聊的查询（超级用户可以任意查询群聊的信息）
+
+- [ ] 关键词查询
+
+- [ ] 尝试利用 jinja2 模板引擎制作可视化图片 ((（真的可以吗？))
+  
+ 待补充。.....
+
+### 👾题外话
+~~整个项目快被我写成屎山了~~

{nonebot_plugin_dialectlist-2.0.4 → nonebot_plugin_dialectlist-2.1.4}/nonebot_plugin_dialectlist/__init__.py

@@ -8,12 +8,9 @@ require("nonebot_plugin_alconna")
 require("nonebot_plugin_cesaa")
 
 import re
+import os
 import nonebot_plugin_saa as saa
 
-from pyecharts.charts import Bar
-from pyecharts import options as opts
-from pyecharts.globals import ThemeType
-
 from typing import Union, Optional, List
 from datetime import datetime, timedelta
 from arclet.alconna import ArparmaBehavior
@@ -50,13 +47,13 @@ from nonebot_plugin_session import Session, SessionIdType, extract_session
 # from .function import *
 from .config import Config, plugin_config
 from .usage import __usage__
+from .time import get_datetime_fromisoformat_with_timezone, get_datetime_now_with_timezone,parse_datetime
+from .model import UserRankInfo
 from .utils import (
-    get_datetime_fromisoformat_with_timezone,
-    get_datetime_now_with_timezone,
     got_rank,
     msg_counter,
     persist_id2user_id,
-    parse_datetime
+    get_rank_image
 )
 
 __plugin_meta__ = PluginMetadata(
@@ -81,17 +78,19 @@ class SameTime(ArparmaBehavior):
         if type is None and time:
             interface.behave_fail()
 
+
 def wrapper(slot: Union[int, str], content: Optional[str]) -> str:
     if slot == "type" and content:
         return content
     return ""  # pragma: no cover
 
+
 rank_cmd = on_alconna(
     Alconna(
         "B话榜",
         Args["type?", ["今日", "昨日", "本周", "上周", "本月", "上月", "年度", "历史"]][
-            "time?", str,
-            "group_id?", int
+            "time?",str,][
+            "group_id?", str
         ],
         behaviors=[SameTime()],
     ),
@@ -110,6 +109,7 @@ rank_cmd.shortcut(
     },
 )
 
+
 # 这段函数完全抄的词云
 @rank_cmd.handle()
 async def _group_message(
@@ -117,13 +117,15 @@ async def _group_message(
     session: Session = Depends(extract_session),
     type: Optional[str] = None,
     time: Optional[str] = None,
-    group_id: Optional[int] = None,
+    group_id: Optional[str] = None,
 ):
 
     dt = get_datetime_now_with_timezone()
 
-    if not group_id:
-        state["group_id"] = session.id2
+    if group_id is None:
+        group_id = session.id2
+
+    state["group_id"] = group_id
 
     if not type:
         await rank_cmd.finish(__plugin_meta__.usage)
@@ -191,15 +193,25 @@ async def _group_message(
     prompt="请输入你要查询的结束日期（如 2022-02-22）",
     parameterless=[Depends(parse_datetime("stop"))],
 )
+@rank_cmd.got("group_id", prompt="请输入你要查询的群号。")
 async def handle_rank(
     bot: Bot,
     event: Event,
     session: Session = Depends(extract_session),
     start: datetime = Arg(),
     stop: datetime = Arg(),
+    group_id: str = Arg(),
 ):
+    if group_id:
+        id = group_id
+    else:
+        id = session.id2
+
+    if not id:
+        await saa.Text("没有指定群哦").finish()
+
     messages = await get_message_records(
-        session=session,
+        id2s=[id],
         id_type=SessionIdType.GROUP,
         include_bot_id=False,
         include_bot_type=False,
@@ -208,42 +220,45 @@ async def handle_rank(
         time_stop=stop,
         exclude_id1s=plugin_config.excluded_people,
     )
-
     rank = got_rank(msg_counter(messages))
+    rank2: List[UserRankInfo] = []
     ids = await persist_id2user_id([int(i[0]) for i in rank])
     for i in range(len(rank)):
         rank[i][0] = str(ids[i])
+        logger.debug(rank[i])
+
+    total = sum([i[1] for i in rank])
 
-    string: str = ""
-    nicknames: List = []
     for i in rank:
         if user_info := await get_user_info(bot, event, user_id=str(i[0])):
-            (
-                nicknames.append(user_info.user_displayname)
-                if user_info.user_displayname
-                else (
-                    nicknames.append(user_info.user_name)
-                    if user_info.user_name
-                    else nicknames.append(user_info.user_id)
-                )
+            user_nickname = user_info.user_displayname\
+                                if user_info.user_displayname\
+                                else user_info.user_name\
+                                    if user_info.user_name\
+                                    else\
+                                        user_info.user_id
+            user_avatar = await user_info.user_avatar.get_image()\
+                            if user_info.user_avatar\
+                            else open(os.path.dirname(os.path.abspath(__file__))+"/template/avatar/default.jpg", "rb").read()
+            user = UserRankInfo(**user_info.model_dump(),
+                                user_bnum=i[1],
+                                user_proportion= round(i[1] / total * 100, 2),
+                                user_index= rank.index(i) + 1,
+                                user_nickname=user_nickname,
+                                user_avatar_bytes= user_avatar,
             )
-        else:
-            nicknames.append(None)
-    logger.debug(nicknames)
+            user.user_gender="她" if user_info.user_gender == "female" else "他" if user_info.user_gender == "male" else "ta"
+            rank2.append(user)
+            
+    string: str = ""
     for i in range(len(rank)):
-        index = i + 1
-        nickname, chatdatanum = nicknames[i], rank[i][1]
         str_example = plugin_config.string_format.format(
-            index=index, nickname=nickname, chatdatanum=chatdatanum
+            index=rank2[i].user_index, 
+            nickname=rank2[i].user_nickname, 
+            chatdatanum=rank2[i].user_bnum
         )
         string += str_example
+    
+    image = await get_rank_image(rank2)
 
-    bar = Bar(init_opts=opts.InitOpts(theme=ThemeType.LIGHT))
-    bar.add_xaxis(nicknames)
-    bar.add_yaxis("B话数量", [i[1] for i in rank]) # type: ignore
-    bar.render(str(get_cache_file("nonebot_plugin_dialectlist","cache.html")))
-    with open(get_cache_file("nonebot_plugin_dialectlist","cache.html")) as f:
-        a = f.read()
-    image = await html_to_pic(a,device_scale_factor=3.2)
-
-    await (saa.Text(string)+saa.Image(image)).finish(reply=True)
+    await (saa.Text(string) + saa.Image(image)).finish(reply=True)

{nonebot_plugin_dialectlist-2.0.4 → nonebot_plugin_dialectlist-2.1.4}/nonebot_plugin_dialectlist/config.py

@@ -1,6 +1,6 @@
 from typing import Optional, Literal, List
 from nonebot import get_driver, get_plugin_config
-from pydantic import BaseModel, field_validator
+from pydantic import BaseModel
 
 
 class ScopedConfig(BaseModel):
@@ -9,6 +9,7 @@ class ScopedConfig(BaseModel):
     timezone: Optional[str] = "Asia/Shanghai"
     excluded_self: bool = True
     string_format: str = "第{index}名：\n{nickname},{chatdatanum}条消息\n"  # 消息格式
+    template_path: str = "./template/rank_template.j2"  # 模板路径
     visualization: bool = True  # 是否可视化
     excluded_people: List[str] = []  # 排除的人的QQ号
     visualization_type: Literal["饼图", "圆环图", "柱状图"] = "圆环图"  # 可视化方案

nonebot_plugin_dialectlist-2.1.4/nonebot_plugin_dialectlist/model.py

@@ -0,0 +1,11 @@
+from typing import Optional, Literal, List, Union
+from pydantic import BaseModel
+from nonebot_plugin_userinfo import get_user_info, UserInfo
+
+
+class UserRankInfo(UserInfo):
+    user_bnum: int
+    user_proportion: float
+    user_nickname: str
+    user_index: Union[int,str]
+    user_avatar_bytes: bytes

{nonebot_plugin_dialectlist-2.0.4 → nonebot_plugin_dialectlist-2.1.4}/nonebot_plugin_dialectlist/storage.py

@@ -1 +1 @@
-# TODO 使用计数缓存进行数据库查询优化，避免一次性查询过多消息导致内存爆炸。
+# TODO 使用计数缓存进行数据库查询优化，避免一次性查询过多消息导致内存爆炸。

nonebot_plugin_dialectlist-2.1.4/nonebot_plugin_dialectlist/time.py

@@ -0,0 +1,80 @@
+# TODO 时间处理模块，用于处理时间相关操作。
+from datetime import datetime, time, tzinfo
+from typing import Optional, Union
+from zoneinfo import ZoneInfo
+
+from nonebot.typing import T_State
+from nonebot.params import Arg
+from nonebot.adapters import Message
+
+from nonebot_plugin_apscheduler import scheduler
+from nonebot_plugin_alconna import AlconnaMatcher
+
+
+from .config import plugin_config
+
+
+def parse_datetime(key: str):
+    """解析数字，并将结果存入 state 中"""
+
+    async def _key_parser(
+        matcher: AlconnaMatcher,
+        state: T_State,
+        input: Union[datetime, Message] = Arg(key),
+    ):
+        if isinstance(input, datetime):
+            return
+
+        plaintext = input.extract_plain_text()
+        try:
+            state[key] = get_datetime_fromisoformat_with_timezone(plaintext)
+        except ValueError:
+            await matcher.reject_arg(key, "请输入正确的日期，不然我没法理解呢！")
+
+    return _key_parser
+
+
+def get_datetime_now_with_timezone() -> datetime:
+    """获取当前时间，并包含时区信息"""
+    if plugin_config.timezone:
+        return datetime.now(ZoneInfo(plugin_config.timezone))
+    else:
+        return datetime.now().astimezone()
+
+
+def get_datetime_fromisoformat_with_timezone(date_string: str) -> datetime:
+    """从 ISO-8601 格式字符串中获取时间，并包含时区信息"""
+    if not plugin_config.timezone:
+        return datetime.fromisoformat(date_string).astimezone()
+    raw = datetime.fromisoformat(date_string)
+    return (
+        raw.astimezone(ZoneInfo(plugin_config.timezone))
+        if raw.tzinfo
+        else raw.replace(tzinfo=ZoneInfo(plugin_config.timezone))
+    )
+
+
+def time_astimezone(time: time, tz: Optional[tzinfo] = None) -> time:
+    """将 time 对象转换为指定时区的 time 对象
+
+    如果 tz 为 None，则转换为本地时区
+    """
+    local_time = datetime.combine(datetime.today(), time)
+    return local_time.astimezone(tz).timetz()
+
+
+def get_time_fromisoformat_with_timezone(time_string: str) -> time:
+    """从 iso8601 格式字符串中获取时间，并包含时区信息"""
+    if not plugin_config.timezone:
+        return time_astimezone(time.fromisoformat(time_string))
+    raw = time.fromisoformat(time_string)
+    return (
+        time_astimezone(raw, ZoneInfo(plugin_config.timezone))
+        if raw.tzinfo
+        else raw.replace(tzinfo=ZoneInfo(plugin_config.timezone))
+    )
+
+
+def get_time_with_scheduler_timezone(time: time) -> time:
+    """获取转换到 APScheduler 时区的时间"""
+    return time_astimezone(time, scheduler.timezone)