feat: add on_waiting_llm_request event hook (#4319)

* 加入on_waiting_llm_request钩子

* ruff check

astrbot/api/event/filter/__init__.py

@@ -21,6 +21,9 @@ from astrbot.core.star.register import (
 from astrbot.core.star.register import register_on_llm_request as on_llm_request
 from astrbot.core.star.register import register_on_llm_response as on_llm_response
 from astrbot.core.star.register import register_on_platform_loaded as on_platform_loaded
+from astrbot.core.star.register import (
+    register_on_waiting_llm_request as on_waiting_llm_request,
+)
 from astrbot.core.star.register import register_permission_type as permission_type
 from astrbot.core.star.register import (
     register_platform_adapter_type as platform_adapter_type,
@@ -46,6 +49,7 @@ __all__ = [
     "on_llm_request",
     "on_llm_response",
     "on_platform_loaded",
+    "on_waiting_llm_request",
     "permission_type",
     "platform_adapter_type",
     "regex",

astrbot/core/pipeline/process_stage/method/agent_sub_stages/internal.py

@@ -364,6 +364,10 @@ class InternalAgentSubStage(Stage):
                 streaming_response = bool(enable_streaming)
 
             logger.debug("ready to request llm provider")
+
+            # 通知等待调用 LLM（在获取锁之前）
+            await call_event_hook(event, EventType.OnWaitingLLMRequestEvent)
+
             async with session_lock_manager.acquire_lock(event.unified_msg_origin):
                 logger.debug("acquired session lock for llm request")
                 if event.get_extra("provider_request"):

astrbot/core/star/register/__init__.py

@@ -12,6 +12,7 @@ from .star_handler import (
     register_on_llm_request,
     register_on_llm_response,
     register_on_platform_loaded,
+    register_on_waiting_llm_request,
     register_permission_type,
     register_platform_adapter_type,
     register_regex,
@@ -30,6 +31,7 @@ __all__ = [
     "register_on_llm_request",
     "register_on_llm_response",
     "register_on_platform_loaded",
+    "register_on_waiting_llm_request",
     "register_permission_type",
     "register_platform_adapter_type",
     "register_regex",

astrbot/core/star/register/star_handler.py

@@ -339,6 +339,30 @@ def register_on_platform_loaded(**kwargs):
     return decorator
 
 
+def register_on_waiting_llm_request(**kwargs):
+    """当等待调用 LLM 时的通知事件（在获取锁之前）
+
+    此钩子在消息确定要调用 LLM 但还未开始排队等锁时触发，
+    适合用于发送"正在思考中..."等用户反馈提示。
+
+    Examples:
+    ```py
+    @on_waiting_llm_request()
+    async def on_waiting_llm(self, event: AstrMessageEvent) -> None:
+        await event.send("🤔 正在思考中...")
+    ```
+
+    """
+
+    def decorator(awaitable):
+        _ = get_handler_or_create(
+            awaitable, EventType.OnWaitingLLMRequestEvent, **kwargs
+        )
+        return awaitable
+
+    return decorator
+
+
 def register_on_llm_request(**kwargs):
     """当有 LLM 请求时的事件
 

astrbot/core/star/star_handler.py

@@ -184,6 +184,7 @@ class EventType(enum.Enum):
     OnPlatformLoadedEvent = enum.auto()  # 平台加载完成
 
     AdapterMessageEvent = enum.auto()  # 收到适配器发来的消息
+    OnWaitingLLMRequestEvent = enum.auto()  # 等待调用 LLM（在获取锁之前，仅通知）
     OnLLMRequestEvent = enum.auto()  # 收到 LLM 请求（可以是用户也可以是插件）
     OnLLMResponseEvent = enum.auto()  # LLM 响应后
     OnDecoratingResultEvent = enum.auto()  # 发送消息前