From 24862b067200e339ff25e5ce33623ef8c6c919ff Mon Sep 17 00:00:00 2001
From: Soulter <905617992@qq.com>
Date: Tue, 11 Feb 2025 23:46:35 +0800
Subject: [PATCH] docs: update the comments of register_llm_tool

---
 .../process_stage/method/llm_request.py         |  4 ++--
 astrbot/core/star/register/star_handler.py      | 17 ++++++++++++++++-
 2 files changed, 18 insertions(+), 3 deletions(-)

diff --git a/astrbot/core/pipeline/process_stage/method/llm_request.py b/astrbot/core/pipeline/process_stage/method/llm_request.py
index 38ac3d932..852c2c331 100644
--- a/astrbot/core/pipeline/process_stage/method/llm_request.py
+++ b/astrbot/core/pipeline/process_stage/method/llm_request.py
@@ -111,10 +111,10 @@ class LLMRequestSubStage(Stage):
                         # 尝试调用工具函数
                         wrapper = self._call_handler(self.ctx, event, func_tool.handler, **func_tool_args)
                         async for resp in wrapper:
-                            if resp is not None:
+                            if resp is not None: # 有 return 返回
                                 function_calling_result[func_tool_name] = resp
                             else:
-                                yield
+                                yield # 有生成器返回
                         event.clear_result() # 清除上一个 handler 的结果
                     except BaseException as e:
                         logger.warning(traceback.format_exc())
diff --git a/astrbot/core/star/register/star_handler.py b/astrbot/core/star/register/star_handler.py
index 0055ce05b..c5e1239dd 100644
--- a/astrbot/core/star/register/star_handler.py
+++ b/astrbot/core/star/register/star_handler.py
@@ -204,7 +204,7 @@ def register_llm_tool(name: str = None):
     
     ```
     @llm_tool(name="get_weather") # 如果 name 不填，将使用函数名
-    async def get_weather(event: AstrMessageEvent, location: str) -> MessageEventResult:
+    async def get_weather(event: AstrMessageEvent, location: str):
         \'\'\'获取天气信息。
         
         Args:
@@ -214,7 +214,22 @@ def register_llm_tool(name: str = None):
     ```
     
     可接受的参数类型有：string, number, object, array, boolean。
+    
+    返回值：
+        - 返回 str：结果会被加入下一次 LLM 请求的 prompt 中，用于让 LLM 总结工具返回的结果
+        - 返回 None：结果不会被加入下一次 LLM 请求的 prompt 中。
+        
+    可以使用 yield 发送消息、终止事件。
+    
+    发送消息：请参考文档。
+    
+    终止事件：
+    ```
+    event.stop_event()
+    yield
+    ```
     '''
+    
     name_ = name
     
     def decorator(awaitable: Awaitable):