From 25229ba1d15914319a9dcd3c7d24e4e57a8e4517 Mon Sep 17 00:00:00 2001 From: Lishiling Date: Mon, 12 Jan 2026 20:06:30 +0800 Subject: [PATCH 1/4] docs: standardize Context class documentation formatting - Unified all method docstrings to standard format - Fixed mixed language and formatting issues - Added complete parameter and return descriptions - Enhanced developer experience for plugin creators - Fixes #4429 --- astrbot/core/star/context.py | 280 +++++++++++++++++++++++++---------- 1 file changed, 205 insertions(+), 75 deletions(-) diff --git a/astrbot/core/star/context.py b/astrbot/core/star/context.py index a64d2a9ee..be547cb49 100644 --- a/astrbot/core/star/context.py +++ b/astrbot/core/star/context.py @@ -49,7 +49,7 @@ class Context: registered_web_apis: list = [] - # back compatibility + # 向后兼容的变量 _register_tasks: list[Awaitable] = [] _star_manager = None @@ -73,12 +73,19 @@ def __init__( self._db = db """AstrBot 数据库""" self.provider_manager = provider_manager + """模型提供商管理器""" self.platform_manager = platform_manager + """平台适配器管理器""" self.conversation_manager = conversation_manager + """会话管理器""" self.message_history_manager = message_history_manager + """平台消息历史管理器""" self.persona_manager = persona_manager + """人格角色设定管理器""" self.astrbot_config_mgr = astrbot_config_mgr + """配置文件管理器(非webui)""" self.kb_manager = knowledge_base_manager + """知识库管理器""" async def llm_generate( self, @@ -91,22 +98,29 @@ async def llm_generate( contexts: list[Message] | None = None, **kwargs: Any, ) -> LLMResponse: - """Call the LLM to generate a response. The method will not automatically execute tool calls. If you want to use tool calls, please use `tool_loop_agent()`. + """调用 LLM 生成响应。 - .. versionadded:: 4.5.7 (sdk) + 该方法不会自动执行工具调用。如果想使用工具调用，请使用 `tool_loop_agent()`。 Args: - chat_provider_id: The chat provider ID to use. - prompt: The prompt to send to the LLM, if `contexts` and `prompt` are both provided, `prompt` will be appended as the last user message - image_urls: List of image URLs to include in the prompt, if `contexts` and `prompt` are both provided, `image_urls` will be appended to the last user message - tools: ToolSet of tools available to the LLM - system_prompt: System prompt to guide the LLM's behavior, if provided, it will always insert as the first system message in the context - contexts: context messages for the LLM - **kwargs: Additional keyword arguments for LLM generation, OpenAI compatible + chat_provider_id: 要使用的聊天提供者 ID。 + prompt: 发送给 LLM 的提示词，如果同时提供 `contexts` 和 `prompt`， + `prompt` 会作为最后一条用户消息。 + image_urls: 包含在提示词中的图片 URL 列表。 + tools: LLM 可用的工具集。 + system_prompt: 指导 LLM 行为的系统提示词。 + contexts: LLM 的上下文消息。 + **kwargs: LLM 生成的额外关键字参数，兼容 OpenAI 格式。 + + Returns: + LLM 生成的响应对象。 Raises: - ChatProviderNotFoundError: If the specified chat provider ID is not found - Exception: For other errors during LLM generation + ChatProviderNotFoundError: 指定的聊天提供者 ID 未找到。 + Exception: LLM 生成过程中的其他错误。 + + Note: + 版本 4.5.7 新增。 """ prov = await self.provider_manager.get_provider_by_id(chat_provider_id) if not prov or not isinstance(prov, Provider): @@ -135,34 +149,35 @@ async def tool_loop_agent( tool_call_timeout: int = 60, **kwargs: Any, ) -> LLMResponse: - """Run an agent loop that allows the LLM to call tools iteratively until a final answer is produced. - If you do not pass the agent_context parameter, the method will recreate a new agent context. - - .. versionadded:: 4.5.7 (sdk) + """运行一个允许 LLM 迭代调用工具直到产生最终答案的代理循环。 Args: - chat_provider_id: The chat provider ID to use. - prompt: The prompt to send to the LLM, if `contexts` and `prompt` are both provided, `prompt` will be appended as the last user message - image_urls: List of image URLs to include in the prompt, if `contexts` and `prompt` are both provided, `image_urls` will be appended to the last user message - tools: ToolSet of tools available to the LLM - system_prompt: System prompt to guide the LLM's behavior, if provided, it will always insert as the first system message in the context - contexts: context messages for the LLM - max_steps: Maximum number of tool calls before stopping the loop - **kwargs: Additional keyword arguments. The kwargs will not be passed to the LLM directly for now, but can include: - stream: bool - whether to stream the LLM response - agent_hooks: BaseAgentRunHooks[AstrAgentContext] - hooks to run during agent execution - agent_context: AstrAgentContext - context to use for the agent - - other kwargs will be DIRECTLY passed to the runner.reset() method + event: 消息事件对象。 + chat_provider_id: 要使用的聊天提供者 ID。 + prompt: 发送给 LLM 的提示词。 + image_urls: 图片 URL 列表。 + tools: LLM 可用的工具集。 + system_prompt: 系统提示词。 + contexts: 上下文消息。 + max_steps: 停止循环前的最大工具调用次数。 + tool_call_timeout: 工具调用超时时间（秒）。 + **kwargs: 额外关键字参数。支持以下参数： + - stream: bool - 是否流式传输 LLM 响应 + - agent_hooks: BaseAgentRunHooks[AstrAgentContext] - 代理执行期间的钩子 + - agent_context: AstrAgentContext - 要使用的代理上下文 Returns: - The final LLMResponse after tool calls are completed. + 工具调用完成后最终的 LLM 响应。 Raises: - ChatProviderNotFoundError: If the specified chat provider ID is not found - Exception: For other errors during LLM generation + ChatProviderNotFoundError: 指定的聊天提供者 ID 未找到。 + Exception: LLM 生成过程中的其他错误。 + + Note: + 如果不传递 agent_context 参数，该方法会重新创建一个新的代理上下文。 + 版本 4.5.7 新增。 """ - # Import here to avoid circular imports + # 延迟导入以避免循环导入 from astrbot.core.astr_agent_context import ( AgentContextWrapper, AstrAgentContext, @@ -226,14 +241,20 @@ async def tool_loop_agent( return llm_resp async def get_current_chat_provider_id(self, umo: str) -> str: - """Get the ID of the currently used chat provider. + """获取当前使用的聊天提供者 ID。 Args: - umo(str): unified_message_origin value, if provided and user has enabled provider session isolation, the provider preferred by that session will be used. + umo: unified_message_origin 值，如果提供并且用户启用了提供者会话隔离， + 将使用该会话偏好的提供者。 + + Returns: + 当前使用的聊天提供者 ID。 Raises: - ProviderNotFoundError: If the specified chat provider is not found + ProviderNotFoundError: 指定的聊天提供者未找到。 + Note: + 该方法会自动处理会话级别的提供者偏好设置。 """ prov = self.get_using_provider(umo) if not prov: @@ -255,20 +276,27 @@ def get_llm_tool_manager(self) -> FunctionToolManager: return self.provider_manager.llm_tools def activate_llm_tool(self, name: str) -> bool: - """激活一个已经注册的函数调用工具。注册的工具默认是激活状态。 + """激活一个已经注册的函数调用工具。 + + Args: + name: 工具名称。 Returns: - 如果没找到，会返回 False + 如果成功激活返回 True，如果没找到工具返回 False。 + Note: + 注册的工具默认是激活状态。 """ return self.provider_manager.llm_tools.activate_llm_tool(name, star_map) def deactivate_llm_tool(self, name: str) -> bool: """停用一个已经注册的函数调用工具。 - Returns: - 如果没找到，会返回 False + Args: + name: 工具名称。 + Returns: + 如果成功停用返回 True，如果没找到工具返回 False。 """ return self.provider_manager.llm_tools.deactivate_llm_tool(name) @@ -278,7 +306,17 @@ def get_provider_by_id( ) -> ( Provider | TTSProvider | STTProvider | EmbeddingProvider | RerankProvider | None ): - """通过 ID 获取对应的 LLM Provider。""" + """通过 ID 获取对应的 LLM Provider。 + + Args: + provider_id: 提供者 ID。 + + Returns: + 提供者实例，如果未找到则返回 None。 + + Note: + 如果提供者 ID 存在但未找到提供者，会记录警告日志。 + """ prov = self.provider_manager.inst_map.get(provider_id) if provider_id and not prov: logger.warning( @@ -303,11 +341,20 @@ def get_all_embedding_providers(self) -> list[EmbeddingProvider]: return self.provider_manager.embedding_provider_insts def get_using_provider(self, umo: str | None = None) -> Provider: - """获取当前使用的用于文本生成任务的 LLM Provider(Chat_Completion 类型)。通过 /provider 指令切换。 + """获取当前使用的用于文本生成任务的 LLM Provider(Chat_Completion 类型)。 Args: - umo(str): unified_message_origin 值，如果传入并且用户启用了提供商会话隔离，则使用该会话偏好的提供商。 + umo: unified_message_origin 值，如果传入并且用户启用了提供商会话隔离， + 则使用该会话偏好的提供商。 + + Returns: + 当前使用的文本生成提供者。 + + Raises: + ValueError: 返回的提供者不是 Provider 类型。 + Note: + 通过 /provider 指令可以切换提供者。 """ prov = self.provider_manager.get_using_provider( provider_type=ProviderType.CHAT_COMPLETION, @@ -321,8 +368,13 @@ def get_using_tts_provider(self, umo: str | None = None) -> TTSProvider | None: """获取当前使用的用于 TTS 任务的 Provider。 Args: - umo(str): unified_message_origin 值，如果传入，则使用该会话偏好的提供商。 + umo: unified_message_origin 值，如果传入，则使用该会话偏好的提供商。 + Returns: + 当前使用的 TTS 提供者，如果未设置则返回 None。 + + Raises: + ValueError: 返回的提供者不是 TTSProvider 类型。 """ prov = self.provider_manager.get_using_provider( provider_type=ProviderType.TEXT_TO_SPEECH, @@ -336,8 +388,13 @@ def get_using_stt_provider(self, umo: str | None = None) -> STTProvider | None: """获取当前使用的用于 STT 任务的 Provider。 Args: - umo(str): unified_message_origin 值，如果传入，则使用该会话偏好的提供商。 + umo: unified_message_origin 值，如果传入，则使用该会话偏好的提供商。 + Returns: + 当前使用的 STT 提供者，如果未设置则返回 None。 + + Raises: + ValueError: 返回的提供者不是 STTProvider 类型。 """ prov = self.provider_manager.get_using_provider( provider_type=ProviderType.SPEECH_TO_TEXT, @@ -348,9 +405,19 @@ def get_using_stt_provider(self, umo: str | None = None) -> STTProvider | None: return prov def get_config(self, umo: str | None = None) -> AstrBotConfig: - """获取 AstrBot 的配置。""" + """获取 AstrBot 的配置。 + + Args: + umo: unified_message_origin 值，用于获取特定会话的配置。 + + Returns: + AstrBot 配置对象。 + + Note: + 如果不提供 umo 参数，将返回默认配置。 + """ if not umo: - # using default config + # 使用默认配置 return self._config return self.astrbot_config_mgr.get_conf(umo) @@ -361,14 +428,19 @@ async def send_message( ) -> bool: """根据 session(unified_msg_origin) 主动发送消息。 - @param session: 消息会话。通过 event.session 或者 event.unified_msg_origin 获取。 - @param message_chain: 消息链。 + Args: + session: 消息会话。通过 event.session 或者 event.unified_msg_origin 获取。 + message_chain: 消息链。 - @return: 是否找到匹配的平台。 + Returns: + 是否找到匹配的平台。 - 当 session 为字符串时，会尝试解析为 MessageSesion 对象，如果解析失败，会抛出 ValueError 异常。 + Raises: + ValueError: session 字符串不合法时抛出。 - NOTE: qq_official(QQ 官方 API 平台) 不支持此方法 + Note: + 当 session 为字符串时，会尝试解析为 MessageSesion 对象。 + qq_official(QQ 官方 API 平台) 不支持此方法。 """ if isinstance(session, str): try: @@ -383,7 +455,14 @@ async def send_message( return False def add_llm_tools(self, *tools: FunctionTool) -> None: - """添加 LLM 工具。""" + """添加 LLM 工具。 + + Args: + *tools: 要添加的函数工具对象。 + + Note: + 如果工具已存在，会替换已存在的工具。 + """ tool_name = {tool.name for tool in self.provider_manager.llm_tools.func_list} module_path = "" for tool in tools: @@ -416,6 +495,17 @@ def register_web_api( methods: list, desc: str, ): + """注册 Web API。 + + Args: + route: API 路由路径。 + view_handler: 异步视图处理函数。 + methods: HTTP 方法列表。 + desc: API 描述。 + + Note: + 如果相同路由和方法已注册，会替换现有的 API。 + """ for idx, api in enumerate(self.registered_web_apis): if api[0] == route and methods == api[2]: self.registered_web_apis[idx] = (route, view_handler, methods, desc) @@ -434,7 +524,14 @@ def get_event_queue(self) -> Queue: def get_platform(self, platform_type: PlatformAdapterType | str) -> Platform | None: """获取指定类型的平台适配器。 - 该方法已经过时，请使用 get_platform_inst 方法。(>= AstrBot v4.0.0) + Args: + platform_type: 平台类型或平台名称。 + + Returns: + 平台适配器实例，如果未找到则返回 None。 + + Note: + 该方法已经过时，请使用 get_platform_inst 方法。(>= AstrBot v4.0.0) """ for platform in self.platform_manager.platform_insts: name = platform.meta().name @@ -451,22 +548,32 @@ def get_platform_inst(self, platform_id: str) -> Platform | None: """获取指定 ID 的平台适配器实例。 Args: - platform_id (str): 平台适配器的唯一标识符。你可以通过 event.get_platform_id() 获取。 + platform_id: 平台适配器的唯一标识符。 Returns: - Platform: 平台适配器实例，如果未找到则返回 None。 + 平台适配器实例，如果未找到则返回 None。 + Note: + 可以通过 event.get_platform_id() 获取平台 ID。 """ for platform in self.platform_manager.platform_insts: if platform.meta().id == platform_id: return platform def get_db(self) -> BaseDatabase: - """获取 AstrBot 数据库。""" + """获取 AstrBot 数据库。 + + Returns: + 数据库实例。 + """ return self._db def register_provider(self, provider: Provider): - """注册一个 LLM Provider(Chat_Completion 类型)。""" + """注册一个 LLM Provider(Chat_Completion 类型)。 + + Args: + provider: 提供者实例。 + """ self.provider_manager.provider_insts.append(provider) def register_llm_tool( @@ -476,14 +583,18 @@ def register_llm_tool( desc: str, func_obj: Callable[..., Awaitable[Any]], ) -> None: - """[DEPRECATED]为函数调用（function-calling / tools-use）添加工具。 - - @param name: 函数名 - @param func_args: 函数参数列表，格式为 [{"type": "string", "name": "arg_name", "description": "arg_description"}, ...] - @param desc: 函数描述 - @param func_obj: 异步处理函数。 + """为函数调用（function-calling / tools-use）添加工具。 - 异步处理函数会接收到额外的的关键词参数：event: AstrMessageEvent, context: Context。 + Args: + name: 函数名。 + func_args: 函数参数列表，格式为 + [{"type": "string", "name": "arg_name", "description": "arg_description"}, ...]。 + desc: 函数描述。 + func_obj: 异步处理函数。 + + Note: + 异步处理函数会接收到额外的关键词参数：event: AstrMessageEvent, context: Context。 + 该方法已弃用，请使用新的注册方式。 """ md = StarHandlerMetadata( event_type=EventType.OnLLMRequestEvent, @@ -498,7 +609,15 @@ def register_llm_tool( self.provider_manager.llm_tools.add_func(name, func_args, desc, func_obj) def unregister_llm_tool(self, name: str) -> None: - """[DEPRECATED]删除一个函数调用工具。如果再要启用，需要重新注册。""" + """删除一个函数调用工具。 + + Args: + name: 工具名称。 + + Note: + 如果再要启用，需要重新注册。 + 该方法已弃用。 + """ self.provider_manager.llm_tools.remove_func(name) def register_commands( @@ -513,14 +632,17 @@ def register_commands( ): """注册一个命令。 - [Deprecated] 推荐使用装饰器注册指令。该方法将在未来的版本中被移除。 - - @param star_name: 插件（Star）名称。 - @param command_name: 命令名称。 - @param desc: 命令描述。 - @param priority: 优先级。1-10。 - @param awaitable: 异步处理函数。 - + Args: + star_name: 插件（Star）名称。 + command_name: 命令名称。 + desc: 命令描述。 + priority: 优先级。1-10。 + awaitable: 异步处理函数。 + use_regex: 是否使用正则表达式匹配命令。 + ignore_prefix: 是否忽略命令前缀。 + + Note: + [已弃用] 推荐使用装饰器注册指令。该方法将在未来的版本中被移除。 """ md = StarHandlerMetadata( event_type=EventType.AdapterMessageEvent, @@ -540,5 +662,13 @@ def register_commands( star_handlers_registry.append(md) def register_task(self, task: Awaitable, desc: str): - """[DEPRECATED]注册一个异步任务。""" + """注册一个异步任务。 + + Args: + task: 异步任务。 + desc: 任务描述。 + + Note: + 该方法已弃用。 + """ self._register_tasks.append(task) From 7644a037ce4d20bf6e8bfc845664349d06f72353 Mon Sep 17 00:00:00 2001 From: Lishiling Date: Mon, 12 Jan 2026 20:43:57 +0800 Subject: [PATCH 2/4] docs: fix Context class documentation issues per review - Restored Sphinx directives for versionadded notes - Fixed MessageSesion typo to MessageSession throughout file - Added clarification for kwargs propagation in tool_loop_agent - Unified deprecation marker format - Fixes #4429 --- astrbot/core/star/context.py | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) diff --git a/astrbot/core/star/context.py b/astrbot/core/star/context.py index be547cb49..2e0a5b14f 100644 --- a/astrbot/core/star/context.py +++ b/astrbot/core/star/context.py @@ -102,6 +102,8 @@ async def llm_generate( 该方法不会自动执行工具调用。如果想使用工具调用，请使用 `tool_loop_agent()`。 + .. versionadded:: 4.5.7 (sdk) + Args: chat_provider_id: 要使用的聊天提供者 ID。 prompt: 发送给 LLM 的提示词，如果同时提供 `contexts` 和 `prompt`， @@ -151,6 +153,8 @@ async def tool_loop_agent( ) -> LLMResponse: """运行一个允许 LLM 迭代调用工具直到产生最终答案的代理循环。 + .. versionadded:: 4.5.7 (sdk) + Args: event: 消息事件对象。 chat_provider_id: 要使用的聊天提供者 ID。 @@ -174,6 +178,7 @@ async def tool_loop_agent( Exception: LLM 生成过程中的其他错误。 Note: + kwargs 参数不会被直接传递给LLM，而是由代理循环/运行器处理（例如 `stream`、`agent_hooks`、`agent_context` 等 `runner.reset()` 的参数）。 如果不传递 agent_context 参数，该方法会重新创建一个新的代理上下文。 版本 4.5.7 新增。 """ @@ -439,7 +444,7 @@ async def send_message( ValueError: session 字符串不合法时抛出。 Note: - 当 session 为字符串时，会尝试解析为 MessageSesion 对象。 + 当 session 为字符串时，会尝试解析为 MessageSession 对象。(类名为MessageSesion是因为历史遗留拼写错误) qq_official(QQ 官方 API 平台) 不支持此方法。 """ if isinstance(session, str): @@ -583,7 +588,7 @@ def register_llm_tool( desc: str, func_obj: Callable[..., Awaitable[Any]], ) -> None: - """为函数调用（function-calling / tools-use）添加工具。 + """[DEPRECATED]为函数调用（function-calling / tools-use）添加工具。 Args: name: 函数名。 @@ -609,7 +614,7 @@ def register_llm_tool( self.provider_manager.llm_tools.add_func(name, func_args, desc, func_obj) def unregister_llm_tool(self, name: str) -> None: - """删除一个函数调用工具。 + """[DEPRECATED]删除一个函数调用工具。 Args: name: 工具名称。 @@ -630,7 +635,7 @@ def register_commands( use_regex=False, ignore_prefix=False, ): - """注册一个命令。 + """[DEPRECATED]注册一个命令。 Args: star_name: 插件（Star）名称。 @@ -642,7 +647,7 @@ def register_commands( ignore_prefix: 是否忽略命令前缀。 Note: - [已弃用] 推荐使用装饰器注册指令。该方法将在未来的版本中被移除。 + 推荐使用装饰器注册指令。该方法将在未来的版本中被移除。 """ md = StarHandlerMetadata( event_type=EventType.AdapterMessageEvent, @@ -662,7 +667,7 @@ def register_commands( star_handlers_registry.append(md) def register_task(self, task: Awaitable, desc: str): - """注册一个异步任务。 + """[DEPRECATED]注册一个异步任务。 Args: task: 异步任务。 From 98de58711029d91e5148092901c8f36f5f0442d2 Mon Sep 17 00:00:00 2001 From: Lishiling Date: Tue, 13 Jan 2026 09:08:07 +0800 Subject: [PATCH 3/4] Convert developer API comments to English --- astrbot/core/star/context.py | 71 +++++++++++++++--------------------- 1 file changed, 29 insertions(+), 42 deletions(-) diff --git a/astrbot/core/star/context.py b/astrbot/core/star/context.py index 2e0a5b14f..dffd2061b 100644 --- a/astrbot/core/star/context.py +++ b/astrbot/core/star/context.py @@ -98,31 +98,22 @@ async def llm_generate( contexts: list[Message] | None = None, **kwargs: Any, ) -> LLMResponse: - """调用 LLM 生成响应。 - - 该方法不会自动执行工具调用。如果想使用工具调用，请使用 `tool_loop_agent()`。 + """Call the LLM to generate a response. The method will not automatically execute tool calls. If you want to use tool calls, please use `tool_loop_agent()`. .. versionadded:: 4.5.7 (sdk) Args: - chat_provider_id: 要使用的聊天提供者 ID。 - prompt: 发送给 LLM 的提示词，如果同时提供 `contexts` 和 `prompt`， - `prompt` 会作为最后一条用户消息。 - image_urls: 包含在提示词中的图片 URL 列表。 - tools: LLM 可用的工具集。 - system_prompt: 指导 LLM 行为的系统提示词。 - contexts: LLM 的上下文消息。 - **kwargs: LLM 生成的额外关键字参数，兼容 OpenAI 格式。 - - Returns: - LLM 生成的响应对象。 + chat_provider_id: The chat provider ID to use. + prompt: The prompt to send to the LLM, if `contexts` and `prompt` are both provided, `prompt` will be appended as the last user message + image_urls: List of image URLs to include in the prompt, if `contexts` and `prompt` are both provided, `image_urls` will be appended to the last user message + tools: ToolSet of tools available to the LLM + system_prompt: System prompt to guide the LLM's behavior, if provided, it will always insert as the first system message in the context + contexts: context messages for the LLM + **kwargs: Additional keyword arguments for LLM generation, OpenAI compatible Raises: - ChatProviderNotFoundError: 指定的聊天提供者 ID 未找到。 - Exception: LLM 生成过程中的其他错误。 - - Note: - 版本 4.5.7 新增。 + ChatProviderNotFoundError: If the specified chat provider ID is not found + Exception: For other errors during LLM generation """ prov = await self.provider_manager.get_provider_by_id(chat_provider_id) if not prov or not isinstance(prov, Provider): @@ -151,38 +142,34 @@ async def tool_loop_agent( tool_call_timeout: int = 60, **kwargs: Any, ) -> LLMResponse: - """运行一个允许 LLM 迭代调用工具直到产生最终答案的代理循环。 + """Run an agent loop that allows the LLM to call tools iteratively until a final answer is produced. + If you do not pass the agent_context parameter, the method will recreate a new agent context. .. versionadded:: 4.5.7 (sdk) Args: - event: 消息事件对象。 - chat_provider_id: 要使用的聊天提供者 ID。 - prompt: 发送给 LLM 的提示词。 - image_urls: 图片 URL 列表。 - tools: LLM 可用的工具集。 - system_prompt: 系统提示词。 - contexts: 上下文消息。 - max_steps: 停止循环前的最大工具调用次数。 - tool_call_timeout: 工具调用超时时间（秒）。 - **kwargs: 额外关键字参数。支持以下参数： - - stream: bool - 是否流式传输 LLM 响应 - - agent_hooks: BaseAgentRunHooks[AstrAgentContext] - 代理执行期间的钩子 - - agent_context: AstrAgentContext - 要使用的代理上下文 + chat_provider_id: The chat provider ID to use. + prompt: The prompt to send to the LLM, if `contexts` and `prompt` are both provided, `prompt` will be appended as the last user message + image_urls: List of image URLs to include in the prompt, if `contexts` and `prompt` are both provided, `image_urls` will be appended to the last user message + tools: ToolSet of tools available to the LLM + system_prompt: System prompt to guide the LLM's behavior, if provided, it will always insert as the first system message in the context + contexts: context messages for the LLM + max_steps: Maximum number of tool calls before stopping the loop + **kwargs: Additional keyword arguments. The kwargs will not be passed to the LLM directly for now, but can include: + stream: bool - whether to stream the LLM response + agent_hooks: BaseAgentRunHooks[AstrAgentContext] - hooks to run during agent execution + agent_context: AstrAgentContext - context to use for the agent + + other kwargs will be DIRECTLY passed to the runner.reset() method Returns: - 工具调用完成后最终的 LLM 响应。 + The final LLMResponse after tool calls are completed. Raises: - ChatProviderNotFoundError: 指定的聊天提供者 ID 未找到。 - Exception: LLM 生成过程中的其他错误。 - - Note: - kwargs 参数不会被直接传递给LLM，而是由代理循环/运行器处理（例如 `stream`、`agent_hooks`、`agent_context` 等 `runner.reset()` 的参数）。 - 如果不传递 agent_context 参数，该方法会重新创建一个新的代理上下文。 - 版本 4.5.7 新增。 + ChatProviderNotFoundError: If the specified chat provider ID is not found + Exception: For other errors during LLM generation """ - # 延迟导入以避免循环导入 + # Import here to avoid circular imports from astrbot.core.astr_agent_context import ( AgentContextWrapper, AstrAgentContext, From c82fe5d5853f0bf0f3f75402860230a2de0cbef8 Mon Sep 17 00:00:00 2001 From: Soulter <37870767+Soulter@users.noreply.github.com> Date: Wed, 14 Jan 2026 23:45:21 +0800 Subject: [PATCH 4/4] chore: revise comments --- astrbot/core/star/context.py | 12 ++++-------- 1 file changed, 4 insertions(+), 8 deletions(-) diff --git a/astrbot/core/star/context.py b/astrbot/core/star/context.py index dffd2061b..9c47ba3a7 100644 --- a/astrbot/core/star/context.py +++ b/astrbot/core/star/context.py @@ -233,20 +233,16 @@ async def tool_loop_agent( return llm_resp async def get_current_chat_provider_id(self, umo: str) -> str: - """获取当前使用的聊天提供者 ID。 + """获取当前使用的聊天模型 Provider ID。 Args: - umo: unified_message_origin 值，如果提供并且用户启用了提供者会话隔离， - 将使用该会话偏好的提供者。 + umo: unified_message_origin。消息会话来源 ID。 Returns: - 当前使用的聊天提供者 ID。 + 指定消息会话来源当前使用的聊天模型 Provider ID。 Raises: - ProviderNotFoundError: 指定的聊天提供者未找到。 - - Note: - 该方法会自动处理会话级别的提供者偏好设置。 + ProviderNotFoundError: 未找到。 """ prov = self.get_using_provider(umo) if not prov: