From 7f5cc7cf1a43913399c86e301b285251ee6e1cf9 Mon Sep 17 00:00:00 2001
From: Gao Jinzhe <2968474907@qq.com>
Date: Sun, 4 Jan 2026 16:11:12 +0800
Subject: [PATCH] feat: add on_waiting_llm_request event hook (#4319)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* 加入on_waiting_llm_request钩子

* ruff check
---
 astrbot/api/event/filter/__init__.py          |  4 ++++
 .../method/agent_sub_stages/internal.py       |  4 ++++
 astrbot/core/star/register/__init__.py        |  2 ++
 astrbot/core/star/register/star_handler.py    | 24 +++++++++++++++++++
 astrbot/core/star/star_handler.py             |  1 +
 5 files changed, 35 insertions(+)

diff --git a/astrbot/api/event/filter/__init__.py b/astrbot/api/event/filter/__init__.py
index a8d2b4269..53e224ca9 100644
--- a/astrbot/api/event/filter/__init__.py
+++ b/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",
diff --git a/astrbot/core/pipeline/process_stage/method/agent_sub_stages/internal.py b/astrbot/core/pipeline/process_stage/method/agent_sub_stages/internal.py
index 6aa7de85e..ed6dc32cf 100644
--- a/astrbot/core/pipeline/process_stage/method/agent_sub_stages/internal.py
+++ b/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"):
diff --git a/astrbot/core/star/register/__init__.py b/astrbot/core/star/register/__init__.py
index 15fe1e9c5..701a138f2 100644
--- a/astrbot/core/star/register/__init__.py
+++ b/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",
diff --git a/astrbot/core/star/register/star_handler.py b/astrbot/core/star/register/star_handler.py
index daf36a8f6..085414cd4 100644
--- a/astrbot/core/star/register/star_handler.py
+++ b/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 请求时的事件
 
diff --git a/astrbot/core/star/star_handler.py b/astrbot/core/star/star_handler.py
index be5b4679f..f36acedff 100644
--- a/astrbot/core/star/star_handler.py
+++ b/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()  # 发送消息前