性能优化 (#2126)

* 性能优化

* 代码改进

* 优化浏览器代际切换逻辑

* 统一缓存与生命周期

* 添加aiomysql依赖

* 优化插件路径处理逻辑，简化条件判断；在虚拟环境包管理器中添加编码和错误处理参数以增强稳定性

* 🚨 auto fix by pre-commit hooks

* 优化Windows下的关闭逻辑

* 代码优化

* bugfix:修复配置重载问题

* bugfix:修复插件加载启动竞态问题

* 收敛事件入口和权限上下文

* 优化 Windows launcher 关闭重启兜底

---------

Co-authored-by: HibiKier <775757368@qq.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

zhenxun/builtin_plugins/hooks/auth/auth_admin.py

@@ -7,9 +7,10 @@ from zhenxun.models.level_user import LevelUser
 from zhenxun.models.plugin_info import PluginInfo
 from zhenxun.services.cache.runtime_cache import LevelUserMemoryCache, LevelUserSnapshot
 from zhenxun.services.log import logger
-from zhenxun.utils.utils import get_entity_ids
+from zhenxun.utils.utils import EntityIDs, get_entity_ids
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .context import PermissionContext
 from .exception import SkipPluginException
 
 
@@ -20,6 +21,9 @@ async def auth_admin(
         LevelUser | LevelUserSnapshot | None, LevelUser | LevelUserSnapshot | None
     ]
     | None = None,
+    *,
+    context: PermissionContext | None = None,
+    entity: EntityIDs | None = None,
 ):
     """管理员命令 个人权限
 
@@ -33,7 +37,12 @@ async def auth_admin(
         return
 
     try:
-        entity = get_entity_ids(session)
+        if context is not None:
+            entity = context.entity
+            if cached_levels is None:
+                cached_levels = context.admin_levels
+        if entity is None:
+            entity = get_entity_ids(session)
 
         global_user: LevelUser | LevelUserSnapshot | None = None
         group_users: LevelUser | LevelUserSnapshot | None = None
@@ -42,7 +51,7 @@ async def auth_admin(
             global_user, group_users = cached_levels
         else:
             global_user, group_users = await LevelUserMemoryCache.get_levels(
-                session.user.id, entity.group_id
+                entity.user_id, entity.group_id
             )
 
         user_level = global_user.user_level if global_user else 0
@@ -53,7 +62,7 @@ async def auth_admin(
                 raise SkipPluginException(
                     f"{plugin.name}({plugin.module}) 管理员权限不足...",
                     tip_message=[
-                        At(flag="user", target=session.user.id),
+                        At(flag="user", target=entity.user_id),
                         f"你的权限不足喔，该功能需要的权限等级: {plugin.admin_level}",
                     ],
                     tip_check_tag=entity.user_id,

zhenxun/builtin_plugins/hooks/auth/auth_ban.py

@@ -1,4 +1,3 @@
-import asyncio
 import time
 
 from nonebot.matcher import Matcher
@@ -8,7 +7,6 @@ from nonebot_plugin_uninfo import Uninfo
 from zhenxun.configs.config import Config
 from zhenxun.models.ban_console import BanConsole
 from zhenxun.models.plugin_info import PluginInfo
-from zhenxun.services.cache.cache_containers import CacheDict
 from zhenxun.services.cache.runtime_cache import BanMemoryCache
 from zhenxun.services.db_context import DB_TIMEOUT_SECONDS
 from zhenxun.services.log import logger
@@ -16,6 +14,7 @@ from zhenxun.utils.enum import PluginType
 from zhenxun.utils.utils import EntityIDs, get_entity_ids
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .context import PermissionContext
 from .exception import SkipPluginException
 from .utils import freq
 
@@ -25,37 +24,6 @@ Config.add_plugin_config(
     "才不会给你发消息.",
     help="对被ban用户发送的消息",
 )
-BAN_CACHE_TTL = 2
-BAN_CACHE_TTL_POSITIVE = 30
-BAN_CACHE_TTL_NEGATIVE = 5
-
-BAN_CACHE = (
-    CacheDict("AUTH_BAN_CACHE", expire=0)
-    if max(BAN_CACHE_TTL_POSITIVE, BAN_CACHE_TTL_NEGATIVE) > 0
-    else None
-)
-
-
-def _ban_cache_key(user_id: str | None, group_id: str | None) -> str:
-    return f"{user_id or ''}:{group_id or ''}"
-
-
-def _ban_cache_get(key: str) -> int | None:
-    if not BAN_CACHE:
-        return None
-    try:
-        return BAN_CACHE[key]
-    except KeyError:
-        return None
-
-
-def _ban_cache_set(key: str, value: int) -> None:
-    if not BAN_CACHE:
-        return
-    ttl = BAN_CACHE_TTL_POSITIVE if value else BAN_CACHE_TTL_NEGATIVE
-    if ttl <= 0:
-        return
-    BAN_CACHE.set(key, value, expire=ttl)
 
 
 async def calculate_ban_time(ban_record: BanConsole | None) -> int:
@@ -214,6 +182,7 @@ async def auth_ban(
     session: Uninfo,
     plugin: PluginInfo,
     *,
+    context: PermissionContext | None = None,
     entity: EntityIDs | None = None,
     is_superuser: bool = False,
 ) -> None:
@@ -229,28 +198,18 @@ async def auth_ban(
             return
         if not matcher.plugin_name:
             return
+        if context is not None:
+            entity = context.entity
+            is_superuser = context.is_superuser
         if entity is None:
             entity = get_entity_ids(session)
         if is_superuser:
             return
         if entity.group_id:
-            try:
-                await asyncio.wait_for(
-                    group_handle(entity.group_id), timeout=DB_TIMEOUT_SECONDS
-                )
-            except asyncio.TimeoutError:
-                logger.error(f"群组ban检查超时: {entity.group_id}", LOGGER_COMMAND)
-                # 超时时不阻塞，继续执行
+            await group_handle(entity.group_id)
 
         if entity.user_id:
-            try:
-                await asyncio.wait_for(
-                    user_handle(plugin, entity, session),
-                    timeout=DB_TIMEOUT_SECONDS,
-                )
-            except asyncio.TimeoutError:
-                logger.error(f"用户ban检查超时: {entity.user_id}", LOGGER_COMMAND)
-                # 超时时不阻塞，继续执行
+            await user_handle(plugin, entity, session)
     finally:
         # 记录总执行时间
         elapsed = time.time() - start_time

zhenxun/builtin_plugins/hooks/auth/auth_bot.py

@@ -7,6 +7,7 @@ from zhenxun.services.log import logger
 from zhenxun.utils.common_utils import CommonUtils
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .context import PermissionContext
 from .exception import SkipPluginException
 
 
@@ -16,6 +17,8 @@ async def auth_bot(
     bot_data: BotConsole | BotSnapshot | None = None,
     skip_fetch: bool = False,
     allow_sleep_bypass: bool = False,
+    *,
+    context: PermissionContext | None = None,
 ):
     """bot层面的权限检查
 
@@ -30,6 +33,9 @@ async def auth_bot(
     start_time = time.time()
 
     try:
+        if context is not None:
+            bot_id = context.event.bot_id
+            bot_data = context.bot_data
         bot: BotConsole | BotSnapshot | None = bot_data
         if bot is None and not skip_fetch:
             bot = await BotMemoryCache.get(bot_id)

zhenxun/builtin_plugins/hooks/auth/auth_cost.py

@@ -7,13 +7,18 @@ from zhenxun.models.user_console import UserConsole
 from zhenxun.services.log import logger
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .context import PermissionContext
 from .exception import SkipPluginException
 
 DEFAULT_GOLD = 100
 
 
 async def auth_cost(
-    user: UserConsole | None, plugin: PluginInfo, session: Uninfo
+    user: UserConsole | None,
+    plugin: PluginInfo,
+    session: Uninfo,
+    *,
+    context: PermissionContext | None = None,
 ) -> int:
     """检测是否满足金币条件
 
@@ -28,6 +33,8 @@ async def auth_cost(
     start_time = time.time()
 
     try:
+        if context is not None and user is None:
+            user = context.user
         user_gold = user.gold if user else DEFAULT_GOLD
         if user_gold < plugin.cost_gold:
             """插件消耗金币不足"""

zhenxun/builtin_plugins/hooks/auth/auth_group.py

@@ -7,6 +7,7 @@ from zhenxun.services.cache.runtime_cache import GroupSnapshot
 from zhenxun.services.log import logger
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD, SwitchEnum
+from .context import PermissionContext
 from .exception import SkipPluginException
 
 _GROUP_WAKE_PATTERN = re.compile(r"^醒来$", re.IGNORECASE)
@@ -34,6 +35,8 @@ async def auth_group(
     group: GroupConsole | GroupSnapshot | None,
     text: str | None,
     group_id: str | None,
+    *,
+    context: PermissionContext | None = None,
 ):
     """群黑名单检测 群总开关检测
 
@@ -42,6 +45,11 @@ async def auth_group(
         group: GroupConsole
         message: UniMsg
     """
+    if context is not None:
+        group = context.group or group
+        text = context.plain_text
+        group_id = context.group_id
+
     if not group_id:
         return
 

zhenxun/builtin_plugins/hooks/auth/auth_limit.py

@@ -19,9 +19,10 @@ 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.time_utils import TimeUtils
-from zhenxun.utils.utils import get_entity_ids
+from zhenxun.utils.utils import EntityIDs, get_entity_ids
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .context import PermissionContext
 from .exception import SkipPluginException
 
 driver = nonebot.get_driver()
@@ -31,7 +32,7 @@ _LIMIT_NOTICE_LIMITER = FreqLimiter(_LIMIT_NOTICE_CD)
 _LIMIT_NOTICE_TASKS: set[asyncio.Task] = set()
 
 
-@PriorityLifecycle.on_startup(priority=5)
+@PriorityLifecycle.on_startup(priority=7)
 async def _():
     """初始化限制"""
     await LimitManager.init_limit()
@@ -117,6 +118,7 @@ class LimitManager:
             cls.cd_limit = {}
             cls.block_limit = {}
             cls.count_limit = {}
+            cls.module_limit_cache.clear()
             # 添加新数据
             for limit in limit_list:
                 cls.add_limit(limit)
@@ -137,22 +139,22 @@ class LimitManager:
         """
         if limit.module not in cls.add_module:
             cls.add_module.append(limit.module)
-            if limit.limit_type == PluginLimitType.BLOCK:
-                cls.block_limit[limit.module] = Limit(
-                    limit=limit, limiter=UserBlockLimiter()
-                )
-            elif limit.limit_type == PluginLimitType.CD:
-                cd_value = int(limit.cd or 0)
-                cls.cd_limit[limit.module] = Limit(
-                    limit=limit, limiter=FreqLimiter(cd_value)
-                )
-            elif limit.limit_type == PluginLimitType.COUNT:
-                max_count = int(limit.max_count or 0)
-                if max_count <= 0:
-                    return
-                cls.count_limit[limit.module] = Limit(
-                    limit=limit, limiter=CountLimiter(max_count)
-                )
+        if limit.limit_type == PluginLimitType.BLOCK:
+            cls.block_limit[limit.module] = Limit(
+                limit=limit, limiter=UserBlockLimiter()
+            )
+        elif limit.limit_type == PluginLimitType.CD:
+            cd_value = int(limit.cd or 0)
+            cls.cd_limit[limit.module] = Limit(
+                limit=limit, limiter=FreqLimiter(cd_value)
+            )
+        elif limit.limit_type == PluginLimitType.COUNT:
+            max_count = int(limit.max_count or 0)
+            if max_count <= 0:
+                return
+            cls.count_limit[limit.module] = Limit(
+                limit=limit, limiter=CountLimiter(max_count)
+            )
 
     @classmethod
     def unblock(
@@ -322,14 +324,23 @@ class LimitManager:
                 limiter.increase(key_type)
 
 
-async def auth_limit(plugin: PluginInfo, session: Uninfo):
+async def auth_limit(
+    plugin: PluginInfo,
+    session: Uninfo,
+    *,
+    context: PermissionContext | None = None,
+    entity: EntityIDs | None = None,
+):
     """插件限制
 
     参数:
         plugin: PluginInfo
         session: Uninfo
     """
-    entity = get_entity_ids(session)
+    if context is not None:
+        entity = context.entity
+    if entity is None:
+        entity = get_entity_ids(session)
     try:
         await asyncio.wait_for(
             LimitManager.check(

zhenxun/builtin_plugins/hooks/auth/auth_plugin.py

@@ -10,6 +10,7 @@ from zhenxun.services.log import logger
 from zhenxun.utils.enum import BlockType
 
 from .config import LOGGER_COMMAND, WARNING_THRESHOLD
+from .context import PermissionContext
 from .exception import IsSuperuserException, SkipPluginException
 from .utils import freq, is_poke
 
@@ -107,11 +108,16 @@ class GroupCheck:
 
 class PluginCheck:
     def __init__(
-        self, group: GroupConsole | GroupSnapshot | None, session: Uninfo, is_poke: bool
+        self,
+        group: GroupConsole | GroupSnapshot | None,
+        session: Uninfo,
+        is_poke: bool,
+        user_id: str | None,
     ):
         self.session = session
         self.is_poke = is_poke
         self.group_data = group
+        self.user_id = user_id or session.user.id
         self.group_id = None
         if group:
             self.group_id = group.group_id
@@ -126,13 +132,11 @@ class PluginCheck:
             IgnoredException: 忽略插件
         """
         if plugin.block_type == BlockType.PRIVATE:
-            should_tip = freq.is_send_limit_message(
-                plugin, self.session.user.id, self.is_poke
-            )
+            should_tip = freq.is_send_limit_message(plugin, self.user_id, self.is_poke)
             raise SkipPluginException(
                 f"{plugin.name}({plugin.module}) 该插件在私聊中已被禁用...",
                 tip_message="该功能在私聊中已被禁用..." if should_tip else None,
-                tip_check_tag=self.session.user.id if should_tip else None,
+                tip_check_tag=self.user_id if should_tip else None,
                 tip_background=should_tip,
             )
 
@@ -153,7 +157,7 @@ class PluginCheck:
             if self.group_data and self.group_data.is_super:
                 raise IsSuperuserException()
 
-            sid = self.group_id or self.session.user.id
+            sid = self.group_id or self.user_id
             should_tip = freq.is_send_limit_message(plugin, sid, self.is_poke)
             raise SkipPluginException(
                 f"{plugin.name}({plugin.module}) 全局未开启此功能...",
@@ -176,7 +180,9 @@ async def auth_plugin(
     session: Uninfo,
     event: Event,
     *,
+    context: PermissionContext | None = None,
     skip_group_block: bool = False,
+    user_id: str | None = None,
 ):
     """插件状态
 
@@ -187,8 +193,11 @@ async def auth_plugin(
     """
     start_time = time.time()
     try:
+        if context is not None:
+            group = context.group or group
+            user_id = context.user_id
         is_poke_event = is_poke(event)
-        user_check = PluginCheck(group, session, is_poke_event)
+        user_check = PluginCheck(group, session, is_poke_event, user_id)
 
         if group:
             block_set, super_block_set = _get_group_block_sets(group)

zhenxun/builtin_plugins/hooks/auth/bot_filter.py

@@ -3,6 +3,7 @@ from nonebot_plugin_uninfo import Uninfo
 
 from zhenxun.configs.config import Config
 
+from .context import PermissionContext
 from .exception import SkipPluginException
 
 Config.add_plugin_config(
@@ -15,7 +16,12 @@ Config.add_plugin_config(
 )
 
 
-def bot_filter(session: Uninfo):
+def bot_filter(
+    session: Uninfo,
+    *,
+    context: PermissionContext | None = None,
+    user_id: str | None = None,
+):
     """过滤bot调用bot
 
     参数:
@@ -26,10 +32,13 @@ def bot_filter(session: Uninfo):
     """
     if not Config.get_config("hook", "FILTER_BOT"):
         return
+    if context is not None:
+        user_id = context.user_id
     bot_ids = list(nonebot.get_bots().keys())
-    if session.user.id == session.self_id:
+    checked_user_id = user_id or session.user.id
+    if checked_user_id == session.self_id:
         return
-    if session.user.id in bot_ids:
+    if checked_user_id in bot_ids:
         raise SkipPluginException(
-            f"bot:{session.self_id} 尝试调用 bot:{session.user.id}"
+            f"bot:{session.self_id} 尝试调用 bot:{checked_user_id}"
         )

zhenxun/builtin_plugins/hooks/auth/context.py

@@ -0,0 +1,321 @@
+from __future__ import annotations
+
+import asyncio
+import contextlib
+from dataclasses import dataclass, field
+from typing import Any
+
+from nonebot.adapters import Bot, Event
+from nonebot_plugin_alconna import UniMsg
+from nonebot_plugin_uninfo import Uninfo
+
+from zhenxun.services.cache.cache_containers import CacheDict
+from zhenxun.utils.platform import PlatformUtils
+from zhenxun.utils.utils import EntityIDs, get_entity_ids
+
+AUTH_EVENT_CACHE_TTL = 5
+
+STATE_EVENT_CONTEXT = "_zx_event_context"
+STATE_PERMISSION_CONTEXT = "_zx_permission_context"
+STATE_ENTITY = "_zx_entity"
+STATE_EVENT_CACHE = "_zx_event_cache"
+STATE_PLAIN_TEXT = "_zx_plain_text"
+STATE_ROUTE_MODULES = "_zx_route_modules"
+STATE_IS_SUPERUSER = "_zx_is_superuser"
+STATE_PERMISSION_SIDE_EFFECTS = "_zx_permission_side_effects"
+EVENT_CACHE_PERMISSION_SIDE_EFFECTS = "permission_side_effects"
+
+EVENT_CACHE = (
+    CacheDict("AUTH_EVENT_CACHE", expire=AUTH_EVENT_CACHE_TTL)
+    if AUTH_EVENT_CACHE_TTL > 0
+    else None
+)
+
+
+@dataclass
+class EventContext:
+    bot_id: str
+    platform: str
+    event_type: str
+    message_id: str | int | None
+    entity: EntityIDs
+    plain_text: str = ""
+    route_modules: set[str] = field(default_factory=set)
+    route_modules_loaded: bool = False
+    is_superuser: bool = False
+    event_cache: dict[str, Any] | None = None
+
+    @property
+    def user_id(self) -> str:
+        return self.entity.user_id
+
+    @property
+    def group_id(self) -> str | None:
+        return self.entity.group_id
+
+    @property
+    def channel_id(self) -> str | None:
+        return self.entity.channel_id
+
+
+@dataclass
+class PermissionSideEffectCache:
+    auth_results: dict[str, tuple[bool, str | None]] = field(default_factory=dict)
+    module_locks: dict[str, asyncio.Lock] = field(default_factory=dict)
+
+    def lock_for(self, module: str) -> asyncio.Lock:
+        lock = self.module_locks.get(module)
+        if lock is None:
+            lock = asyncio.Lock()
+            self.module_locks[module] = lock
+        return lock
+
+
+@dataclass
+class PermissionContext:
+    event: EventContext
+    module: str
+    plugin: Any = None
+    user: Any = None
+    group: Any = None
+    bot_data: Any = None
+    admin_levels: Any = None
+
+    @property
+    def entity(self) -> EntityIDs:
+        return self.event.entity
+
+    @property
+    def user_id(self) -> str:
+        return self.event.user_id
+
+    @property
+    def group_id(self) -> str | None:
+        return self.event.group_id
+
+    @property
+    def channel_id(self) -> str | None:
+        return self.event.channel_id
+
+    @property
+    def plain_text(self) -> str:
+        return self.event.plain_text
+
+    @property
+    def is_superuser(self) -> bool:
+        return self.event.is_superuser
+
+
+def resolve_actor_user_id(event: Event, fallback_user_id: str | None) -> str:
+    """优先使用事件发起者 ID，避免 notice 场景 session.user 指向 bot 自身。"""
+    event_user_id = getattr(event, "user_id", None)
+    if event_user_id is None:
+        return fallback_user_id or ""
+    resolved = str(event_user_id)
+    return resolved or fallback_user_id or ""
+
+
+def resolve_event_group_id(event: Event, fallback_group_id: str | None) -> str | None:
+    """notice 场景 session.group 可能缺失，回退到事件上的 group_id。"""
+    event_group_id = getattr(event, "group_id", None)
+    if event_group_id is None:
+        return fallback_group_id
+    resolved = str(event_group_id)
+    return resolved or fallback_group_id
+
+
+def resolve_event_channel_id(
+    event: Event, fallback_channel_id: str | None
+) -> str | None:
+    """频道场景回退到事件上的 channel_id。"""
+    event_channel_id = getattr(event, "channel_id", None)
+    if event_channel_id is None:
+        return fallback_channel_id
+    resolved = str(event_channel_id)
+    return resolved or fallback_channel_id
+
+
+def resolve_entity_ids(event: Event, session: Uninfo) -> EntityIDs:
+    entity = get_entity_ids(session)
+    entity.user_id = resolve_actor_user_id(event, entity.user_id)
+    entity.group_id = resolve_event_group_id(event, entity.group_id)
+    entity.channel_id = resolve_event_channel_id(event, entity.channel_id)
+    return entity
+
+
+def extract_plain_text(message: UniMsg | None, event: Event) -> str:
+    if message is not None:
+        with contextlib.suppress(Exception):
+            return message.extract_plain_text()
+    with contextlib.suppress(Exception):
+        plain = event.get_plaintext()
+        if plain:
+            return plain.strip()
+    return ""
+
+
+def _event_message_id(event: Event) -> str | int | None:
+    msg_id = getattr(event, "message_id", None)
+    if msg_id is None:
+        msg_id = getattr(event, "id", None)
+    return msg_id
+
+
+def event_cache_key(
+    event: Event,
+    *,
+    bot_id: str,
+    platform: str,
+    entity: EntityIDs,
+) -> str:
+    msg_id = _event_message_id(event)
+    if msg_id is None:
+        msg_id = id(event)
+    group_id = entity.group_id or ""
+    channel_id = entity.channel_id or ""
+    return f"{platform}:{bot_id}:{entity.user_id}:{group_id}:{channel_id}:{msg_id}"
+
+
+def get_event_cache(
+    event: Event,
+    *,
+    bot_id: str,
+    platform: str,
+    entity: EntityIDs,
+) -> dict[str, Any] | None:
+    if not EVENT_CACHE:
+        return None
+    key = event_cache_key(event, bot_id=bot_id, platform=platform, entity=entity)
+    try:
+        return EVENT_CACHE[key]
+    except KeyError:
+        cache: dict[str, Any] = {}
+        EVENT_CACHE[key] = cache
+        return cache
+
+
+def _sync_context_state(state: dict[str, Any], context: EventContext) -> None:
+    state[STATE_EVENT_CONTEXT] = context
+    state[STATE_ENTITY] = context.entity
+    state[STATE_EVENT_CACHE] = context.event_cache
+    state[STATE_PLAIN_TEXT] = context.plain_text
+    state[STATE_ROUTE_MODULES] = context.route_modules
+    state[STATE_IS_SUPERUSER] = context.is_superuser
+    get_permission_side_effect_cache(state=state, event_cache=context.event_cache)
+
+
+def get_permission_side_effect_cache(
+    *,
+    state: dict[str, Any] | None = None,
+    event_cache: dict[str, Any] | None = None,
+) -> PermissionSideEffectCache:
+    side_effects = None
+    if state is not None:
+        side_effects = state.get(STATE_PERMISSION_SIDE_EFFECTS)
+    if (
+        not isinstance(side_effects, PermissionSideEffectCache)
+        and event_cache is not None
+    ):
+        side_effects = event_cache.get(EVENT_CACHE_PERMISSION_SIDE_EFFECTS)
+    if not isinstance(side_effects, PermissionSideEffectCache):
+        side_effects = PermissionSideEffectCache()
+    if state is not None:
+        state[STATE_PERMISSION_SIDE_EFFECTS] = side_effects
+    if event_cache is not None:
+        event_cache[EVENT_CACHE_PERMISSION_SIDE_EFFECTS] = side_effects
+    return side_effects
+
+
+def get_event_context(state: dict[str, Any] | None) -> EventContext | None:
+    if state is None:
+        return None
+    context = state.get(STATE_EVENT_CONTEXT)
+    return context if isinstance(context, EventContext) else None
+
+
+def get_or_create_event_context(
+    bot: Bot,
+    event: Event,
+    session: Uninfo,
+    state: dict[str, Any],
+    *,
+    message: UniMsg | None = None,
+) -> EventContext:
+    context = get_event_context(state)
+    if context is not None:
+        _sync_context_state(state, context)
+        return context
+
+    entity = state.get(STATE_ENTITY)
+    if not isinstance(entity, EntityIDs):
+        entity = resolve_entity_ids(event, session)
+
+    platform = PlatformUtils.get_platform(session)
+    bot_id = str(bot.self_id)
+    event_cache = state.get(STATE_EVENT_CACHE)
+    if not isinstance(event_cache, dict):
+        event_cache = get_event_cache(
+            event,
+            bot_id=bot_id,
+            platform=platform,
+            entity=entity,
+        )
+
+    text = state.get(STATE_PLAIN_TEXT)
+    if not isinstance(text, str):
+        cached_text = event_cache.get("plain_text") if event_cache is not None else None
+        text = (
+            cached_text
+            if isinstance(cached_text, str)
+            else extract_plain_text(message, event)
+        )
+    if event_cache is not None:
+        event_cache["plain_text"] = text
+
+    route_modules_loaded = STATE_ROUTE_MODULES in state
+    route_modules = state.get(STATE_ROUTE_MODULES)
+    if not isinstance(route_modules, set):
+        cached_routes = (
+            event_cache.get("route_modules") if event_cache is not None else None
+        )
+        route_modules = cached_routes if isinstance(cached_routes, set) else set()
+        route_modules_loaded = isinstance(cached_routes, set)
+
+    is_superuser = state.get(STATE_IS_SUPERUSER)
+    if not isinstance(is_superuser, bool):
+        is_superuser = entity.user_id in bot.config.superusers
+
+    context = EventContext(
+        bot_id=bot_id,
+        platform=platform,
+        event_type=event.get_type(),
+        message_id=_event_message_id(event),
+        entity=entity,
+        plain_text=text,
+        route_modules=route_modules,
+        route_modules_loaded=route_modules_loaded,
+        is_superuser=is_superuser,
+        event_cache=event_cache,
+    )
+    _sync_context_state(state, context)
+    return context
+
+
+def set_route_modules(
+    state: dict[str, Any] | None,
+    context: EventContext,
+    route_modules: set[str],
+) -> None:
+    context.route_modules = route_modules
+    context.route_modules_loaded = True
+    if context.event_cache is not None:
+        context.event_cache["route_modules"] = route_modules
+    if state is not None:
+        _sync_context_state(state, context)
+
+
+def store_permission_context(
+    state: dict[str, Any] | None, context: PermissionContext
+) -> None:
+    if state is not None:
+        state[STATE_PERMISSION_CONTEXT] = context