✨ feat(limit, message): 引入声明式限流系统并增强消息格式化功能 (#1978)

- 新增 Cooldown、RateLimit、ConcurrencyLimit 三种限流依赖
- MessageUtils 支持动态格式化字符串 (format_args 参数)
- 插件CD限制消息显示精确剩余时间

- 重构限流逻辑至 utils/limiters.py，新增时间工具模块
- 整合时间工具函数并优化时区处理
- 新增 limiter_hook 自动释放资源，CooldownError 优化异常处理

- 冷却提示从固定文本改为动态显示剩余时间
- 示例：总结功能冷却中，请等待 1分30秒 后再试~

Co-authored-by: webjoin111 <455457521@qq.com>
Co-authored-by: HibiKier <45528451+HibiKier@users.noreply.github.com>

zhenxun/builtin_plugins/hooks/auth/auth_limit.py

@@ -11,14 +11,11 @@ from zhenxun.models.plugin_limit import PluginLimit
 from zhenxun.services.db_context import DB_TIMEOUT_SECONDS
 from zhenxun.services.log import logger
 from zhenxun.utils.enum import LimitWatchType, PluginLimitType
+from zhenxun.utils.limiters import CountLimiter, FreqLimiter, UserBlockLimiter
 from zhenxun.utils.manager.priority_manager import PriorityLifecycle
 from zhenxun.utils.message import MessageUtils
-from zhenxun.utils.utils import (
-    CountLimiter,
-    FreqLimiter,
-    UserBlockLimiter,
-    get_entity_ids,
-)
+from zhenxun.utils.time_utils import TimeUtils
+from zhenxun.utils.utils import get_entity_ids
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
 from .exception import SkipPluginException
@@ -273,9 +270,16 @@ class LimitManager:
             key_type = channel_id or group_id
         if is_limit and not limiter.check(key_type):
             if limit.result:
+                format_kwargs = {}
+                if isinstance(limiter, FreqLimiter):
+                    left_time = limiter.left_time(key_type)
+                    cd_str = TimeUtils.format_duration(left_time)
+                    format_kwargs = {"cd": cd_str}
                 try:
                     await asyncio.wait_for(
-                        MessageUtils.build_message(limit.result).send(),
+                        MessageUtils.build_message(
+                            limit.result, format_args=format_kwargs
+                        ).send(),
                         timeout=DB_TIMEOUT_SECONDS,
                     )
                 except asyncio.TimeoutError:

zhenxun/builtin_plugins/hooks/limiter_hook.py

@@ -0,0 +1,15 @@
+from nonebot.matcher import Matcher
+from nonebot.message import run_postprocessor
+
+from zhenxun.utils.limiters import ConcurrencyLimiter
+
+
+@run_postprocessor
+async def _concurrency_release_hook(matcher: Matcher):
+    """
+    后处理器：在事件处理结束后，释放并发限制的信号量。
+    """
+    if concurrency_info := matcher.state.get("_concurrency_limiter_info"):
+        limiter: ConcurrencyLimiter = concurrency_info["limiter"]
+        key = concurrency_info["key"]
+        limiter.release(key)