chore: improve documentation for extra_user_content_parts in Provider classes

fixes: #4176

README.md

@@ -1,4 +1,4 @@
-![AstrBot-Logo-Simplified](https://github.com/user-attachments/assets/ffd99b6b-3272-4682-beaa-6fe74250f7d9)
+![astrbot-banner-xmas](https://github.com/user-attachments/assets/bf2341de-ec7a-45a7-a04a-02ad36450e99)
 
 <div align="center">
 

astrbot/cli/__init__.py

@@ -1 +1 @@
-__version__ = "4.10.0"
+__version__ = "4.10.2"

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -77,10 +77,11 @@ class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
     async def _iter_llm_responses(self) -> T.AsyncGenerator[LLMResponse, None]:
         """Yields chunks *and* a final LLMResponse."""
         payload = {
-            "contexts": self.run_context.messages,
+            "contexts": self.run_context.messages,  # list[Message]
             "func_tool": self.req.func_tool,
             "model": self.req.model,  # NOTE: in fact, this arg is None in most cases
             "session_id": self.req.session_id,
+            "extra_user_content_parts": self.req.extra_user_content_parts,  # list[ContentPart]
         }
 
         if self.streaming:

astrbot/core/config/default.py

@@ -5,7 +5,7 @@ from typing import Any, TypedDict
 
 from astrbot.core.utils.astrbot_path import get_astrbot_data_path
 
-VERSION = "4.10.0"
+VERSION = "4.10.2"
 DB_PATH = os.path.join(get_astrbot_data_path(), "data_v4.db")
 
 WEBHOOK_SUPPORTED_PLATFORMS = [

astrbot/core/platform/sources/aiocqhttp/aiocqhttp_platform_adapter.py

@@ -385,10 +385,25 @@ class AiocqhttpAdapter(Platform):
                         logger.error(f"获取 @ 用户信息失败: {e}，此消息段将被忽略。")
 
                 message_str += "".join(at_parts)
+            elif t == "markdown":
+                text = m["data"].get("markdown") or m["data"].get("content", "")
+                abm.message.append(Plain(text=text))
+                message_str += text
             else:
                 for m in m_group:
-                    a = ComponentTypes[t](**m["data"])
-                    abm.message.append(a)
+                    try:
+                        if t not in ComponentTypes:
+                            logger.warning(
+                                f"不支持的消息段类型，已忽略: {t}, data={m['data']}"
+                            )
+                            continue
+                        a = ComponentTypes[t](**m["data"])
+                        abm.message.append(a)
+                    except Exception as e:
+                        logger.exception(
+                            f"消息段解析失败: type={t}, data={m['data']}. {e}"
+                        )
+                        continue
 
         abm.timestamp = int(time.time())
         abm.message_str = message_str

astrbot/core/provider/entities.py

@@ -14,6 +14,7 @@ import astrbot.core.message.components as Comp
 from astrbot import logger
 from astrbot.core.agent.message import (
     AssistantMessageSegment,
+    ContentPart,
     ToolCall,
     ToolCallMessageSegment,
 )
@@ -92,6 +93,8 @@ class ProviderRequest:
     """会话 ID"""
     image_urls: list[str] = field(default_factory=list)
     """图片 URL 列表"""
+    extra_user_content_parts: list[ContentPart] = field(default_factory=list)
+    """额外的用户消息内容部分列表，用于在用户消息后添加额外的内容块（如系统提醒、指令等）。"""
     func_tool: ToolSet | None = None
     """可用的函数工具"""
     contexts: list[dict] = field(default_factory=list)
@@ -166,13 +169,23 @@ class ProviderRequest:
 
     async def assemble_context(self) -> dict:
         """将请求(prompt 和 image_urls)包装成 OpenAI 的消息格式。"""
+        # 构建内容块列表
+        content_blocks = []
+
+        # 1. 用户原始发言（OpenAI 建议：用户发言在前）
+        if self.prompt and self.prompt.strip():
+            content_blocks.append({"type": "text", "text": self.prompt})
+        elif self.image_urls:
+            # 如果没有文本但有图片，添加占位文本
+            content_blocks.append({"type": "text", "text": "[图片]"})
+
+        # 2. 额外的内容块（系统提醒、指令等）
+        if self.extra_user_content_parts:
+            for part in self.extra_user_content_parts:
+                content_blocks.append(part.model_dump())
+
+        # 3. 图片内容
         if self.image_urls:
-            user_content = {
-                "role": "user",
-                "content": [
-                    {"type": "text", "text": self.prompt if self.prompt else "[图片]"},
-                ],
-            }
             for image_url in self.image_urls:
                 if image_url.startswith("http"):
                     image_path = await download_image_by_url(image_url)
@@ -185,11 +198,21 @@ class ProviderRequest:
                 if not image_data:
                     logger.warning(f"图片 {image_url} 得到的结果为空，将忽略。")
                     continue
-                user_content["content"].append(
+                content_blocks.append(
                     {"type": "image_url", "image_url": {"url": image_data}},
                 )
-            return user_content
-        return {"role": "user", "content": self.prompt}
+
+        # 只有当只有一个来自 prompt 的文本块且没有额外内容块时，才降级为简单格式以保持向后兼容
+        if (
+            len(content_blocks) == 1
+            and content_blocks[0]["type"] == "text"
+            and not self.extra_user_content_parts
+            and not self.image_urls
+        ):
+            return {"role": "user", "content": content_blocks[0]["text"]}
+
+        # 否则返回多模态格式
+        return {"role": "user", "content": content_blocks}
 
     async def _encode_image_bs64(self, image_url: str) -> str:
         """将图片转换为 base64"""

astrbot/core/provider/provider.py

@@ -4,7 +4,7 @@ import os
 from collections.abc import AsyncGenerator
 from typing import TypeAlias, Union
 
-from astrbot.core.agent.message import Message
+from astrbot.core.agent.message import ContentPart, Message
 from astrbot.core.agent.tool import ToolSet
 from astrbot.core.provider.entities import (
     LLMResponse,
@@ -103,6 +103,7 @@ class Provider(AbstractProvider):
         system_prompt: str | None = None,
         tool_calls_result: ToolCallsResult | list[ToolCallsResult] | None = None,
         model: str | None = None,
+        extra_user_content_parts: list[ContentPart] | None = None,
         **kwargs,
     ) -> LLMResponse:
         """获得 LLM 的文本对话结果。会使用当前的模型进行对话。
@@ -114,6 +115,7 @@ class Provider(AbstractProvider):
             tools: tool set
             contexts: 上下文，和 prompt 二选一使用
             tool_calls_result: 回传给 LLM 的工具调用结果。参考: https://platform.openai.com/docs/guides/function-calling
+            extra_user_content_parts: 额外的用户内容块列表，用于在用户消息后添加额外的文本块（如系统提醒、指令等）
             kwargs: 其他参数
 
         Notes:
@@ -133,6 +135,7 @@ class Provider(AbstractProvider):
         system_prompt: str | None = None,
         tool_calls_result: ToolCallsResult | list[ToolCallsResult] | None = None,
         model: str | None = None,
+        extra_user_content_parts: list[ContentPart] | None = None,
         **kwargs,
     ) -> AsyncGenerator[LLMResponse, None]:
         """获得 LLM 的流式文本对话结果。会使用当前的模型进行对话。在生成的最后会返回一次完整的结果。
@@ -144,6 +147,7 @@ class Provider(AbstractProvider):
             tools: tool set
             contexts: 上下文，和 prompt 二选一使用
             tool_calls_result: 回传给 LLM 的工具调用结果。参考: https://platform.openai.com/docs/guides/function-calling
+            extra_user_content_parts: 额外的用户内容块列表，用于在用户消息后添加额外的文本块（如系统提醒、指令等）
             kwargs: 其他参数
 
         Notes:

astrbot/core/provider/sources/anthropic_source.py

@@ -11,6 +11,7 @@ from anthropic.types.usage import Usage
 
 from astrbot import logger
 from astrbot.api.provider import Provider
+from astrbot.core.agent.message import ContentPart
 from astrbot.core.provider.entities import LLMResponse, TokenUsage
 from astrbot.core.provider.func_tool_manager import ToolSet
 from astrbot.core.utils.io import download_image_by_url
@@ -296,13 +297,16 @@ class ProviderAnthropic(Provider):
         system_prompt=None,
         tool_calls_result=None,
         model=None,
+        extra_user_content_parts=None,
         **kwargs,
     ) -> LLMResponse:
         if contexts is None:
             contexts = []
         new_record = None
         if prompt is not None:
-            new_record = await self.assemble_context(prompt, image_urls)
+            new_record = await self.assemble_context(
+                prompt, image_urls, extra_user_content_parts
+            )
         context_query = self._ensure_message_to_dicts(contexts)
         if new_record:
             context_query.append(new_record)
@@ -350,13 +354,16 @@ class ProviderAnthropic(Provider):
         system_prompt=None,
         tool_calls_result=None,
         model=None,
+        extra_user_content_parts=None,
         **kwargs,
     ):
         if contexts is None:
             contexts = []
         new_record = None
         if prompt is not None:
-            new_record = await self.assemble_context(prompt, image_urls)
+            new_record = await self.assemble_context(
+                prompt, image_urls, extra_user_content_parts
+            )
         context_query = self._ensure_message_to_dicts(contexts)
         if new_record:
             context_query.append(new_record)
@@ -388,48 +395,116 @@ class ProviderAnthropic(Provider):
         async for llm_response in self._query_stream(payloads, func_tool):
             yield llm_response
 
-    async def assemble_context(self, text: str, image_urls: list[str] | None = None):
+    async def assemble_context(
+        self,
+        text: str,
+        image_urls: list[str] | None = None,
+        extra_user_content_parts: list[ContentPart] | None = None,
+    ):
         """组装上下文，支持文本和图片"""
-        if not image_urls:
-            return {"role": "user", "content": text}
-
         content = []
-        content.append({"type": "text", "text": text})
 
-        for image_url in image_urls:
-            if image_url.startswith("http"):
-                image_path = await download_image_by_url(image_url)
-                image_data = await self.encode_image_bs64(image_path)
-            elif image_url.startswith("file:///"):
-                image_path = image_url.replace("file:///", "")
-                image_data = await self.encode_image_bs64(image_path)
-            else:
-                image_data = await self.encode_image_bs64(image_url)
+        # 1. 用户原始发言（OpenAI 建议：用户发言在前）
+        if text:
+            content.append({"type": "text", "text": text})
+        elif image_urls:
+            # 如果没有文本但有图片，添加占位文本
+            content.append({"type": "text", "text": "[图片]"})
+        elif extra_user_content_parts:
+            # 如果只有额外内容块，也需要添加占位文本
+            content.append({"type": "text", "text": " "})
 
-            if not image_data:
-                logger.warning(f"图片 {image_url} 得到的结果为空，将忽略。")
-                continue
+        # 2. 额外的内容块（系统提醒、指令等）
+        if extra_user_content_parts:
+            for block in extra_user_content_parts:
+                block_type = block.get("type")
 
-            # Get mime type for the image
-            mime_type, _ = guess_type(image_url)
-            if not mime_type:
-                mime_type = "image/jpeg"  # Default to JPEG if can't determine
+                if block_type == "text":
+                    # 文本直接添加
+                    content.append(block)
 
-            content.append(
-                {
-                    "type": "image",
-                    "source": {
-                        "type": "base64",
-                        "media_type": mime_type,
-                        "data": (
-                            image_data.split("base64,")[1]
-                            if "base64," in image_data
-                            else image_data
-                        ),
+                elif block_type == "image_url":
+                    # 转换 OpenAI 格式的图片为 Anthropic 格式
+                    image_url_data = block.get("image_url", {})
+                    if isinstance(image_url_data, dict):
+                        url = image_url_data.get("url", "")
+                    else:
+                        # 兼容直接传 URL 字符串的情况
+                        url = str(image_url_data)
+
+                    if url and url.startswith("data:"):
+                        try:
+                            # 提取 MIME 类型和 base64 数据
+                            mime_type = url.split(":")[1].split(";")[0]
+                            base64_data = (
+                                url.split("base64,")[1] if "base64," in url else url
+                            )
+                            content.append(
+                                {
+                                    "type": "image",
+                                    "source": {
+                                        "type": "base64",
+                                        "media_type": mime_type,
+                                        "data": base64_data,
+                                    },
+                                }
+                            )
+                        except Exception as e:
+                            logger.warning(f"转换 image_url 到 Anthropic 格式失败: {e}")
+                    else:
+                        logger.warning(f"image_url 不是有效的 data URI: {url[:50]}...")
+
+                else:
+                    # 其他类型（如 audio_url）Anthropic 不支持，记录警告
+                    logger.debug(f"Anthropic 不支持的内容类型 '{block_type}'，已忽略")
+
+        # 3. 图片内容
+        if image_urls:
+            for image_url in image_urls:
+                if image_url.startswith("http"):
+                    image_path = await download_image_by_url(image_url)
+                    image_data = await self.encode_image_bs64(image_path)
+                elif image_url.startswith("file:///"):
+                    image_path = image_url.replace("file:///", "")
+                    image_data = await self.encode_image_bs64(image_path)
+                else:
+                    image_data = await self.encode_image_bs64(image_url)
+
+                if not image_data:
+                    logger.warning(f"图片 {image_url} 得到的结果为空，将忽略。")
+                    continue
+
+                # Get mime type for the image
+                mime_type, _ = guess_type(image_url)
+                if not mime_type:
+                    mime_type = "image/jpeg"  # Default to JPEG if can't determine
+
+                content.append(
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": mime_type,
+                            "data": (
+                                image_data.split("base64,")[1]
+                                if "base64," in image_data
+                                else image_data
+                            ),
+                        },
                     },
-                },
-            )
+                )
 
+        # 如果只有主文本且没有额外内容块和图片，返回简单格式以保持向后兼容
+        if (
+            text
+            and not extra_user_content_parts
+            and not image_urls
+            and len(content) == 1
+            and content[0]["type"] == "text"
+        ):
+            return {"role": "user", "content": content[0]["text"]}
+
+        # 否则返回多模态格式
         return {"role": "user", "content": content}
 
     async def encode_image_bs64(self, image_url: str) -> str:

astrbot/core/provider/sources/gemini_source.py

@@ -13,6 +13,7 @@ from google.genai.errors import APIError
 import astrbot.core.message.components as Comp
 from astrbot import logger
 from astrbot.api.provider import Provider
+from astrbot.core.agent.message import ContentPart
 from astrbot.core.message.message_event_result import MessageChain
 from astrbot.core.provider.entities import LLMResponse, TokenUsage
 from astrbot.core.provider.func_tool_manager import ToolSet
@@ -680,13 +681,16 @@ class ProviderGoogleGenAI(Provider):
         system_prompt=None,
         tool_calls_result=None,
         model=None,
+        extra_user_content_parts=None,
         **kwargs,
     ) -> LLMResponse:
         if contexts is None:
             contexts = []
         new_record = None
         if prompt is not None:
-            new_record = await self.assemble_context(prompt, image_urls)
+            new_record = await self.assemble_context(
+                prompt, image_urls, extra_user_content_parts
+            )
         context_query = self._ensure_message_to_dicts(contexts)
         if new_record:
             context_query.append(new_record)
@@ -732,13 +736,16 @@ class ProviderGoogleGenAI(Provider):
         system_prompt=None,
         tool_calls_result=None,
         model=None,
+        extra_user_content_parts=None,
         **kwargs,
     ) -> AsyncGenerator[LLMResponse, None]:
         if contexts is None:
             contexts = []
         new_record = None
         if prompt is not None:
-            new_record = await self.assemble_context(prompt, image_urls)
+            new_record = await self.assemble_context(
+                prompt, image_urls, extra_user_content_parts
+            )
         context_query = self._ensure_message_to_dicts(contexts)
         if new_record:
             context_query.append(new_record)
@@ -797,13 +804,33 @@ class ProviderGoogleGenAI(Provider):
         self.chosen_api_key = key
         self._init_client()
 
-    async def assemble_context(self, text: str, image_urls: list[str] | None = None):
+    async def assemble_context(
+        self,
+        text: str,
+        image_urls: list[str] | None = None,
+        extra_user_content_parts: list[ContentPart] | None = None,
+    ):
         """组装上下文。"""
+        # 构建内容块列表
+        content_blocks = []
+
+        # 1. 用户原始发言（OpenAI 建议：用户发言在前）
+        if text:
+            content_blocks.append({"type": "text", "text": text})
+        elif image_urls:
+            # 如果没有文本但有图片，添加占位文本
+            content_blocks.append({"type": "text", "text": "[图片]"})
+        elif extra_user_content_parts:
+            # 如果只有额外内容块，也需要添加占位文本
+            content_blocks.append({"type": "text", "text": " "})
+
+        # 2. 额外的内容块（系统提醒、指令等）
+        if extra_user_content_parts:
+            for part in extra_user_content_parts:
+                content_blocks.append(part.model_dump())
+
+        # 3. 图片内容
         if image_urls:
-            user_content = {
-                "role": "user",
-                "content": [{"type": "text", "text": text if text else "[图片]"}],
-            }
             for image_url in image_urls:
                 if image_url.startswith("http"):
                     image_path = await download_image_by_url(image_url)
@@ -816,14 +843,25 @@ class ProviderGoogleGenAI(Provider):
                 if not image_data:
                     logger.warning(f"图片 {image_url} 得到的结果为空，将忽略。")
                     continue
-                user_content["content"].append(
+                content_blocks.append(
                     {
                         "type": "image_url",
                         "image_url": {"url": image_data},
                     },
                 )
-            return user_content
-        return {"role": "user", "content": text}
+
+        # 如果只有主文本且没有额外内容块和图片，返回简单格式以保持向后兼容
+        if (
+            text
+            and not extra_user_content_parts
+            and not image_urls
+            and len(content_blocks) == 1
+            and content_blocks[0]["type"] == "text"
+        ):
+            return {"role": "user", "content": content_blocks[0]["text"]}
+
+        # 否则返回多模态格式
+        return {"role": "user", "content": content_blocks}
 
     async def encode_image_bs64(self, image_url: str) -> str:
         """将图片转换为 base64"""

astrbot/core/provider/sources/openai_source.py

@@ -17,7 +17,7 @@ from openai.types.completion_usage import CompletionUsage
 import astrbot.core.message.components as Comp
 from astrbot import logger
 from astrbot.api.provider import Provider
-from astrbot.core.agent.message import Message
+from astrbot.core.agent.message import ContentPart, Message
 from astrbot.core.agent.tool import ToolSet
 from astrbot.core.message.message_event_result import MessageChain
 from astrbot.core.provider.entities import LLMResponse, TokenUsage, ToolCallsResult
@@ -348,6 +348,7 @@ class ProviderOpenAIOfficial(Provider):
         system_prompt: str | None = None,
         tool_calls_result: ToolCallsResult | list[ToolCallsResult] | None = None,
         model: str | None = None,
+        extra_user_content_parts: list[ContentPart] | None = None,
         **kwargs,
     ) -> tuple:
         """准备聊天所需的有效载荷和上下文"""
@@ -355,7 +356,9 @@ class ProviderOpenAIOfficial(Provider):
             contexts = []
         new_record = None
         if prompt is not None:
-            new_record = await self.assemble_context(prompt, image_urls)
+            new_record = await self.assemble_context(
+                prompt, image_urls, extra_user_content_parts
+            )
         context_query = self._ensure_message_to_dicts(contexts)
         if new_record:
             context_query.append(new_record)
@@ -476,6 +479,7 @@ class ProviderOpenAIOfficial(Provider):
         system_prompt=None,
         tool_calls_result=None,
         model=None,
+        extra_user_content_parts=None,
         **kwargs,
     ) -> LLMResponse:
         payloads, context_query = await self._prepare_chat_payload(
@@ -485,6 +489,7 @@ class ProviderOpenAIOfficial(Provider):
             system_prompt,
             tool_calls_result,
             model=model,
+            extra_user_content_parts=extra_user_content_parts,
             **kwargs,
         )
 
@@ -539,6 +544,7 @@ class ProviderOpenAIOfficial(Provider):
         system_prompt=None,
         tool_calls_result=None,
         model=None,
+        extra_user_content_parts=None,
         **kwargs,
     ) -> AsyncGenerator[LLMResponse, None]:
         """流式对话，与服务商交互并逐步返回结果"""
@@ -549,6 +555,7 @@ class ProviderOpenAIOfficial(Provider):
             system_prompt,
             tool_calls_result,
             model=model,
+            extra_user_content_parts=extra_user_content_parts,
             **kwargs,
         )
 
@@ -624,13 +631,29 @@ class ProviderOpenAIOfficial(Provider):
         self,
         text: str,
         image_urls: list[str] | None = None,
+        extra_user_content_parts: list[ContentPart] | None = None,
     ) -> dict:
         """组装成符合 OpenAI 格式的 role 为 user 的消息段"""
+        # 构建内容块列表
+        content_blocks = []
+
+        # 1. 用户原始发言（OpenAI 建议：用户发言在前）
+        if text:
+            content_blocks.append({"type": "text", "text": text})
+        elif image_urls:
+            # 如果没有文本但有图片，添加占位文本
+            content_blocks.append({"type": "text", "text": "[图片]"})
+        elif extra_user_content_parts:
+            # 如果只有额外内容块，也需要添加占位文本
+            content_blocks.append({"type": "text", "text": " "})
+
+        # 2. 额外的内容块（系统提醒、指令等）
+        if extra_user_content_parts:
+            for part in extra_user_content_parts:
+                content_blocks.append(part.model_dump())
+
+        # 3. 图片内容
         if image_urls:
-            user_content = {
-                "role": "user",
-                "content": [{"type": "text", "text": text if text else "[图片]"}],
-            }
             for image_url in image_urls:
                 if image_url.startswith("http"):
                     image_path = await download_image_by_url(image_url)
@@ -643,14 +666,25 @@ class ProviderOpenAIOfficial(Provider):
                 if not image_data:
                     logger.warning(f"图片 {image_url} 得到的结果为空，将忽略。")
                     continue
-                user_content["content"].append(
+                content_blocks.append(
                     {
                         "type": "image_url",
                         "image_url": {"url": image_data},
                     },
                 )
-            return user_content
-        return {"role": "user", "content": text}
+
+        # 如果只有主文本且没有额外内容块和图片，返回简单格式以保持向后兼容
+        if (
+            text
+            and not extra_user_content_parts
+            and not image_urls
+            and len(content_blocks) == 1
+            and content_blocks[0]["type"] == "text"
+        ):
+            return {"role": "user", "content": content_blocks[0]["text"]}
+
+        # 否则返回多模态格式
+        return {"role": "user", "content": content_blocks}
 
     async def encode_image_bs64(self, image_url: str) -> str:
         """将图片转换为 base64"""

astrbot/core/star/command_management.py

@@ -4,7 +4,7 @@ from collections import defaultdict
 from dataclasses import dataclass, field
 from typing import Any
 
-from astrbot.core import db_helper
+from astrbot.core import db_helper, logger
 from astrbot.core.db.po import CommandConfig
 from astrbot.core.star.filter.command import CommandFilter
 from astrbot.core.star.filter.command_group import CommandGroupFilter
@@ -90,6 +90,7 @@ async def toggle_command(handler_full_name: str, enabled: bool) -> CommandDescri
 async def rename_command(
     handler_full_name: str,
     new_fragment: str,
+    aliases: list[str] | None = None,
 ) -> CommandDescriptor:
     descriptor = _build_descriptor_by_full_name(handler_full_name)
     if not descriptor:
@@ -99,9 +100,24 @@ async def rename_command(
     if not new_fragment:
         raise ValueError("指令名不能为空。")
 
+    # 校验主指令名
     candidate_full = _compose_command(descriptor.parent_signature, new_fragment)
     if _is_command_in_use(handler_full_name, candidate_full):
-        raise ValueError("新的指令名已被其他指令占用，请换一个名称。")
+        raise ValueError(f"指令名 '{candidate_full}' 已被其他指令占用。")
+
+    # 校验别名
+    if aliases:
+        for alias in aliases:
+            alias = alias.strip()
+            if not alias:
+                continue
+            alias_full = _compose_command(descriptor.parent_signature, alias)
+            if _is_command_in_use(handler_full_name, alias_full):
+                raise ValueError(f"别名 '{alias_full}' 已被其他指令占用。")
+
+    existing_cfg = await db_helper.get_command_config(handler_full_name)
+    merged_extra = dict(existing_cfg.extra_data or {}) if existing_cfg else {}
+    merged_extra["resolved_aliases"] = aliases or []
 
     config = await db_helper.upsert_command_config(
         handler_full_name=handler_full_name,
@@ -114,7 +130,7 @@ async def rename_command(
         conflict_key=descriptor.original_command,
         resolution_strategy="manual_rename",
         note=None,
-        extra_data=None,
+        extra_data=merged_extra,
         auto_managed=False,
     )
     _bind_descriptor_with_config(descriptor, config)
@@ -192,12 +208,18 @@ def _collect_descriptors(include_sub_commands: bool) -> list[CommandDescriptor]:
     """收集指令，按需包含子指令。"""
     descriptors: list[CommandDescriptor] = []
     for handler in star_handlers_registry:
-        desc = _build_descriptor(handler)
-        if not desc:
+        try:
+            desc = _build_descriptor(handler)
+            if not desc:
+                continue
+            if not include_sub_commands and desc.is_sub_command:
+                continue
+            descriptors.append(desc)
+        except Exception as e:
+            logger.warning(
+                f"解析指令处理函数 {handler.handler_full_name} 失败，跳过该指令。原因: {e!s}"
+            )
             continue
-        if not include_sub_commands and desc.is_sub_command:
-            continue
-        descriptors.append(desc)
     return descriptors
 
 
@@ -357,14 +379,27 @@ def _apply_config_to_descriptor(
         new_fragment,
     )
 
+    extra = config.extra_data or {}
+    resolved_aliases = extra.get("resolved_aliases")
+    if isinstance(resolved_aliases, list):
+        descriptor.aliases = [str(x) for x in resolved_aliases if str(x).strip()]
+
 
 def _apply_config_to_runtime(
     descriptor: CommandDescriptor,
     config: CommandConfig,
 ) -> None:
     descriptor.handler.enabled = config.enabled
-    if descriptor.filter_ref and descriptor.current_fragment:
-        _set_filter_fragment(descriptor.filter_ref, descriptor.current_fragment)
+    if descriptor.filter_ref:
+        if descriptor.current_fragment:
+            _set_filter_fragment(descriptor.filter_ref, descriptor.current_fragment)
+        extra = config.extra_data or {}
+        resolved_aliases = extra.get("resolved_aliases")
+        if isinstance(resolved_aliases, list):
+            _set_filter_aliases(
+                descriptor.filter_ref,
+                [str(x) for x in resolved_aliases if str(x).strip()],
+            )
 
 
 def _bind_configs_to_descriptors(
@@ -403,6 +438,18 @@ def _set_filter_fragment(
         filter_ref._cmpl_cmd_names = None
 
 
+def _set_filter_aliases(
+    filter_ref: CommandFilter | CommandGroupFilter,
+    aliases: list[str],
+) -> None:
+    current_aliases = getattr(filter_ref, "alias", set())
+    if set(aliases) == current_aliases:
+        return
+    setattr(filter_ref, "alias", set(aliases))
+    if hasattr(filter_ref, "_cmpl_cmd_names"):
+        filter_ref._cmpl_cmd_names = None
+
+
 def _is_command_in_use(
     target_handler_full_name: str,
     candidate_full_command: str,

astrbot/core/star/star_manager.py

@@ -631,7 +631,11 @@ class PluginManager:
         # 清除 pip.main 导致的多余的 logging handlers
         for handler in logging.root.handlers[:]:
             logging.root.removeHandler(handler)
-        await sync_command_configs()
+        try:
+            await sync_command_configs()
+        except Exception as e:
+            logger.error(f"同步指令配置失败: {e!s}")
+            logger.error(traceback.format_exc())
 
         if not fail_rec:
             return True, None

astrbot/dashboard/routes/command.py

@@ -61,12 +61,13 @@ class CommandRoute(Route):
         data = await request.get_json()
         handler_full_name = data.get("handler_full_name")
         new_name = data.get("new_name")
+        aliases = data.get("aliases")
 
         if not handler_full_name or not new_name:
             return Response().error("handler_full_name 与 new_name 均为必填。").__dict__
 
         try:
-            await rename_command_service(handler_full_name, new_name)
+            await rename_command_service(handler_full_name, new_name, aliases=aliases)
         except ValueError as exc:
             return Response().error(str(exc)).__dict__
 

astrbot/dashboard/routes/config.py

@@ -185,23 +185,30 @@ class ConfigRoute(Route):
             "/config/provider/list": ("GET", self.get_provider_config_list),
             "/config/provider/model_list": ("GET", self.get_provider_model_list),
             "/config/provider/get_embedding_dim": ("POST", self.get_embedding_dim),
-            "/config/provider_sources/<provider_source_id>/models": (
+            "/config/provider_sources/models": (
                 "GET",
                 self.get_provider_source_models,
             ),
-            "/config/provider_sources/<provider_source_id>/update": (
+            "/config/provider_sources/update": (
                 "POST",
                 self.update_provider_source,
             ),
-            "/config/provider_sources/<provider_source_id>/delete": (
+            "/config/provider_sources/delete": (
                 "POST",
                 self.delete_provider_source,
             ),
         }
         self.register_routes()
 
-    async def delete_provider_source(self, provider_source_id: str):
+    async def delete_provider_source(self):
         """删除 provider_source，并更新关联的 providers"""
+        post_data = await request.json
+        if not post_data:
+            return Response().error("缺少配置数据").__dict__
+
+        provider_source_id = post_data.get("id")
+        if not provider_source_id:
+            return Response().error("缺少 provider_source_id").__dict__
 
         provider_sources = self.config.get("provider_sources", [])
         target_idx = next(
@@ -235,15 +242,16 @@ class ConfigRoute(Route):
 
         return Response().ok(message="删除 provider source 成功").__dict__
 
-    async def update_provider_source(self, provider_source_id: str):
+    async def update_provider_source(self):
         """更新或新增 provider_source，并重载关联的 providers"""
-
         post_data = await request.json
         if not post_data:
             return Response().error("缺少配置数据").__dict__
 
         new_source_config = post_data.get("config") or post_data
-        original_id = provider_source_id
+        original_id = post_data.get("original_id")
+        if not original_id:
+            return Response().error("缺少 original_id").__dict__
 
         if not isinstance(new_source_config, dict):
             return Response().error("缺少或错误的配置数据").__dict__
@@ -684,11 +692,15 @@ class ConfigRoute(Route):
             logger.error(traceback.format_exc())
             return Response().error(f"获取嵌入维度失败: {e!s}").__dict__
 
-    async def get_provider_source_models(self, provider_source_id: str):
+    async def get_provider_source_models(self):
         """获取指定 provider_source 支持的模型列表
 
         本质上会临时初始化一个 Provider 实例，调用 get_models() 获取模型列表，然后销毁实例
         """
+        provider_source_id = request.args.get("source_id")
+        if not provider_source_id:
+            return Response().error("缺少参数 source_id").__dict__
+
         try:
             from astrbot.core.provider.register import provider_cls_map
 

changelogs/v4.10.1.md

@@ -0,0 +1,46 @@
+## What's Changed
+
+> 📢 在升级前，请**完整阅读**本次更新日志。
+> 
+> **特别提醒：**
+> 1. 本次升级**如果再降级**，会由于提供商配置的变更，导致提供商配置错乱，需要手动删除后重新添加。
+> 2. 此版本 WebUI 包体相较上一个版本增加约 **193%**，共约 **9.8 MB**，升级可能会需要一些时间。
+> 3. **升级后请务必确保 WebUI 和 AstrBot Core 版本一致**，否则会产生预期之外的情况。（判断方法：日志中出现 `WebUI 版本已是最新。` 即为一致的版本，`检测到 WebUI 版本 (xxx) 与当前 AstrBot 版本 (xxx) 不符。` 即为不一致的版本。此版本的判断方法也可通查看 WebUI 右上角是否出现 Bot / Chat 的切换按钮控件来判断是否是新版本的 WebUI）。
+> 4. 如果有任何问题请提交 [Issue](https://github.com/AstrBotDevs/AstrBot/issues) 并附带 `v4.10.0` tag。
+
+## 4.10.0 -> 4.10.1
+
+- fix(core): 修复极少数情况下由于指令管理导致的 AstrBot 启动失败的问题
+- fix(core): 修复当提供商源带有斜杠（“/”）时，无法删除 / 更新提供商源的问题（报错 405）
+- perf(core): 优化 OneBot 适配器的消息段解析逻辑，修复部分情况下无法正确解析消息段的问题
+
+### 重构与优化
+
+- 重构 Provider 页面和提供商的配置结构，将 Chat Provider 配置拆分为 Provider Source（提供商源）和 Provider（代表提供商源的各个模型），引入了提供商模型自动发现、模型元数据自动发现的功能，**提供更加便捷的模型添加体验**。
+- ⚠️ 将 “MCP” 页面移动到了 “插件” 页面中
+- ⚠️ 将 “MCP” 页面中的工具管理移动到了 “插件” -> “管理行为” 中。
+- ⚠️ 将 “QQ 个人号（OneBot v11）” 机器人适配器类型更名为 “OneBot v11”，并将其 Logo 更改为 OneBot 的 Logo。
+- ⚠️ AstrBot WebChat 升级为 **AstrBot ChatUI**，入口从边栏修改为顶部（右上角）切换按钮。
+- 优化引用消息的逻辑，减少对模型输入缓存的破坏。
+- 优化当 Agent 达到最大步数时的处理。在达到最大步数后，会移除所有请求中的 tools 并告知模型根据上下文进行最终总结。
+- 优化 LLM tools 执行的错误处理，减少工具调用无限循环的问题。
+
+
+### 修复
+
+- ‼️ 修复部分情况下，分段回复无法正常分段的问题。
+- 修复处理工具返回结果的过程中，导致一些直接发送图片的工具（如生图工具）无法正确发送到用户的问题。
+- 修复 WebChat 部分情况下，上一条消息文字内容增量到下一条消息的问题。
+
+### 新增
+
+- 支持**指令管理**，设置指令别名、解决指令冲突、查看指令详情等。入口：“插件” -> “管理行为”。
+- 支持 Google Gemini 3 系列引入的 [Thinking Level](https://ai.google.dev/gemini-api/docs/thinking#thinking-levels) 配置。
+- 支持记录每条 LLM 消息的耗时、Token 使用量、TTFT 数据，以及每次 Agent Loop 的各种统计数据。
+- AstrBot ChatUI 支持查看每条消息的 TTFT、Token 使用量数据。
+- AstrBot ChatUI 支持显示每次工具调用的耗时、参数和响应。
+- AstrBot ChatUI 支持渲染 Mermaid、LateX 内容，优化了 Code Block 的显示效果（使用 Monaco Editor），并减少 DOM 更新于内存占用。（Powered by [Simon-He95/markstream-vue](https://github.com/Simon-He95/markstream-vue)）
+- 支持查看 Changelog 历史版本更新日志。
+- 🎄
+
+Merry Christmas! 

changelogs/v4.10.2.md

@@ -0,0 +1,9 @@
+## What's Changed
+
+### 修复
+
+1. ‼️‼️ 修复了由 `psutil` 新版本导致的启动时报错的问题。
+
+### 新增
+
+1. 插件指令管理支持管理别名。

dashboard/src/components/extension/componentPanel/components/RenameDialog.vue

@@ -1,14 +1,16 @@
 <script setup lang="ts">
+import { computed, ref, watch } from 'vue';
 import { useModuleI18n } from '@/i18n/composables';
 import type { CommandItem } from '../types';
 
 const { tm } = useModuleI18n('features/command');
 
 // Props
-defineProps<{
+const props = defineProps<{
   show: boolean;
   command: CommandItem | null;
   newName: string;
+  aliases: string[];
   loading: boolean;
 }>();
 
@@ -16,8 +18,42 @@ defineProps<{
 const emit = defineEmits<{
   (e: 'update:show', value: boolean): void;
   (e: 'update:newName', value: string): void;
+  (e: 'update:aliases', value: string[]): void;
   (e: 'confirm'): void;
 }>();
+
+const addAlias = () => {
+  emit('update:aliases', [...props.aliases, '']);
+};
+
+const removeAlias = (index: number) => {
+  const newAliases = [...props.aliases];
+  newAliases.splice(index, 1);
+  emit('update:aliases', newAliases);
+};
+
+const updateAlias = (index: number, value: string) => {
+  const newAliases = [...props.aliases];
+  newAliases[index] = value;
+  emit('update:aliases', newAliases);
+};
+
+const hasAliases = computed(() => (props.aliases || []).some(a => (a ?? '').toString().trim()));
+const showAliasEditor = ref(false);
+const aliasEditorEverOpened = ref(false);
+
+watch(
+  () => props.show,
+  (open) => {
+    if (!open) return;
+    // 如果已有别名则默认展开，否则默认收起
+    showAliasEditor.value = hasAliases.value;
+  },
+);
+
+watch(showAliasEditor, (open) => {
+  if (open) aliasEditorEverOpened.value = true;
+});
 </script>
 
 <template>
@@ -32,7 +68,49 @@ const emit = defineEmits<{
           variant="outlined"
           density="compact"
           autofocus
+          class="mb-2"
         />
+
+        <v-card variant="outlined" class="mt-2" elevation="0">
+          <div
+            class="d-flex align-center justify-space-between px-4 py-3"
+            role="button"
+            tabindex="0"
+            @click="showAliasEditor = !showAliasEditor"
+            @keydown.enter.prevent="showAliasEditor = !showAliasEditor"
+            @keydown.space.prevent="showAliasEditor = !showAliasEditor"
+          >
+            <div class="text-subtitle-1">{{ tm('dialogs.rename.aliases') }}</div>
+            <v-icon size="20">{{ showAliasEditor ? 'mdi-chevron-up' : 'mdi-chevron-down' }}</v-icon>
+          </div>
+          <v-divider v-if="showAliasEditor" />
+          <v-slide-y-transition>
+            <div v-if="aliasEditorEverOpened" v-show="showAliasEditor" class="px-4 py-3">
+              <div v-for="(alias, index) in aliases" :key="index" class="d-flex align-center mb-2">
+                <v-text-field
+                  :model-value="alias"
+                  @update:model-value="updateAlias(index, $event)"
+                  variant="outlined"
+                  density="compact"
+                  hide-details
+                  class="flex-grow-1 mr-2"
+                />
+                <v-btn icon="mdi-delete" variant="text" color="error" density="compact" @click="removeAlias(index)" />
+              </div>
+              <v-btn
+                prepend-icon="mdi-plus"
+                variant="outlined"
+                color="primary"
+                block
+                size="small"
+                class="mt-2"
+                @click="addAlias"
+              >
+                {{ tm('dialogs.rename.addAlias') }}
+              </v-btn>
+            </div>
+          </v-slide-y-transition>
+        </v-card>
       </v-card-text>
       <v-card-actions>
         <v-spacer />

dashboard/src/components/extension/componentPanel/composables/useCommandActions.ts

@@ -14,6 +14,7 @@ export function useCommandActions(
     show: false,
     command: null,
     newName: '',
+    aliases: [],
     loading: false
   });
 
@@ -53,6 +54,7 @@ export function useCommandActions(
   const openRenameDialog = (cmd: CommandItem) => {
     renameDialog.command = cmd;
     renameDialog.newName = cmd.current_fragment || '';
+    renameDialog.aliases = [...(cmd.aliases || [])];
     renameDialog.show = true;
   };
 
@@ -66,7 +68,8 @@ export function useCommandActions(
     try {
       const res = await axios.post('/api/commands/rename', {
         handler_full_name: renameDialog.command.handler_full_name,
-        new_name: renameDialog.newName.trim()
+        new_name: renameDialog.newName.trim(),
+        aliases: renameDialog.aliases.filter(a => a.trim())
       });
       if (res.data.status === 'ok') {
         toast(successMessage, 'success');

dashboard/src/components/extension/componentPanel/index.vue

@@ -288,6 +288,8 @@ watch(viewMode, async (mode) => {
     @update:show="renameDialog.show = $event"
     :new-name="renameDialog.newName"
     @update:new-name="renameDialog.newName = $event"
+    :aliases="renameDialog.aliases"
+    @update:aliases="renameDialog.aliases = $event"
     :command="renameDialog.command"
     :loading="renameDialog.loading"
     @confirm="handleConfirmRename"

dashboard/src/components/extension/componentPanel/types.ts

@@ -52,6 +52,7 @@ export interface RenameDialogState {
   show: boolean;
   command: CommandItem | null;
   newName: string;
+  aliases: string[];
   loading: boolean;
 }
 

dashboard/src/composables/useProviderSources.ts

@@ -398,7 +398,7 @@ export function useProviderSources(options: UseProviderSourcesOptions) {
     if (!confirm(tm('providerSources.deleteConfirm', { id: source.id }))) return
 
     try {
-      await axios.post(`/api/config/provider_sources/${source.id}/delete`)
+      await axios.post('/api/config/provider_sources/delete', { id: source.id })
 
       providers.value = providers.value.filter((p) => p.provider_source_id !== source.id)
       providerSources.value = providerSources.value.filter((s) => s.id !== source.id)
@@ -423,7 +423,7 @@ export function useProviderSources(options: UseProviderSourcesOptions) {
     savingSource.value = true
     const originalId = selectedProviderSourceOriginalId.value || selectedProviderSource.value.id
     try {
-      const response = await axios.post(`/api/config/provider_sources/${originalId}/update`, {
+      const response = await axios.post('/api/config/provider_sources/update', {
         config: editableProviderSource.value,
         original_id: originalId
       })
@@ -478,7 +478,9 @@ export function useProviderSources(options: UseProviderSourcesOptions) {
     loadingModels.value = true
     try {
       const sourceId = editableProviderSource.value?.id || selectedProviderSource.value.id
-      const response = await axios.get(`/api/config/provider_sources/${sourceId}/models`)
+      const response = await axios.get('/api/config/provider_sources/models', {
+        params: { source_id: sourceId }
+      })
       if (response.data.status === 'ok') {
         const metadataMap = response.data.data.model_metadata || {}
         modelMetadata.value = metadataMap

dashboard/src/i18n/locales/en-US/features/command.json

@@ -45,6 +45,8 @@
     "rename": {
       "title": "Rename Command",
       "newName": "New command name",
+      "aliases": "Manage aliases",
+      "addAlias": "Add alias",
       "cancel": "Cancel",
       "confirm": "Confirm"
     },

dashboard/src/i18n/locales/zh-CN/features/command.json

@@ -45,6 +45,8 @@
     "rename": {
       "title": "重命名指令",
       "newName": "新指令名",
+      "aliases": "管理别名",
+      "addAlias": "添加别名",
       "cancel": "取消",
       "confirm": "确认"
     },

packages/astrbot/process_llm_request.py

@@ -7,6 +7,7 @@ from astrbot.api import logger, sp, star
 from astrbot.api.event import AstrMessageEvent
 from astrbot.api.message_components import Image, Reply
 from astrbot.api.provider import Provider, ProviderRequest
+from astrbot.core.agent.message import TextPart
 from astrbot.core.provider.func_tool_manager import ToolSet
 
 
@@ -85,7 +86,9 @@ class ProcessLLMRequest:
                 req.image_urls,
             )
             if caption:
-                req.prompt = f"(Image Caption: {caption})\n\n{req.prompt}"
+                req.extra_user_content_parts.append(
+                    TextPart(text=f"<image_caption>{caption}</image_caption>")
+                )
                 req.image_urls = []
         except Exception as e:
             logger.error(f"处理图片描述失败: {e}")
@@ -129,13 +132,14 @@ class ProcessLLMRequest:
             else:
                 req.prompt = prefix + req.prompt
 
+        # 收集系统提醒信息
+        system_parts = []
+
         # user identifier
         if cfg.get("identifier"):
             user_id = event.message_obj.sender.user_id
             user_nickname = event.message_obj.sender.nickname
-            req.prompt = (
-                f"\n[User ID: {user_id}, Nickname: {user_nickname}]\n{req.prompt}"
-            )
+            system_parts.append(f"User ID: {user_id}, Nickname: {user_nickname}")
 
         # group name identifier
         if cfg.get("group_name_display") and event.message_obj.group_id:
@@ -146,7 +150,7 @@ class ProcessLLMRequest:
                 return
             group_name = event.message_obj.group.group_name
             if group_name:
-                req.system_prompt += f"\nGroup name: {group_name}\n"
+                system_parts.append(f"Group name: {group_name}")
 
         # time info
         if cfg.get("datetime_system_prompt"):
@@ -162,7 +166,7 @@ class ProcessLLMRequest:
                 current_time = (
                     datetime.datetime.now().astimezone().strftime("%Y-%m-%d %H:%M (%Z)")
                 )
-            req.system_prompt += f"\nCurrent datetime: {current_time}\n"
+            system_parts.append(f"Current datetime: {current_time}")
 
         img_cap_prov_id: str = cfg.get("default_image_caption_provider_id") or ""
         if req.conversation:
@@ -225,10 +229,17 @@ class ProcessLLMRequest:
                 except BaseException as e:
                     logger.error(f"处理引用图片失败: {e}")
 
-            # 3. 将所有部分组合成文本并直接注入到当前消息中
+            # 3. 将所有部分组合成文本并添加到 extra_user_content_parts 中
             # 确保引用内容被正确的标签包裹
             quoted_content = "\n".join(content_parts)
             # 确保所有内容都在<Quoted Message>标签内
             quoted_text = f"<Quoted Message>\n{quoted_content}\n</Quoted Message>"
 
-            req.prompt = f"{quoted_text}\n\n{req.prompt}"
+            req.extra_user_content_parts.append(TextPart(text=quoted_text))
+
+        # 统一包裹所有系统提醒
+        if system_parts:
+            system_content = (
+                "<system_reminder>" + "\n".join(system_parts) + "</system_reminder>"
+            )
+            req.extra_user_content_parts.append(TextPart(text=system_content))

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "AstrBot"
-version = "4.10.0"
+version = "4.10.2"
 description = "Easy-to-use multi-platform LLM chatbot and development framework"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -34,7 +34,7 @@ dependencies = [
   "ormsgpack>=1.9.1",
   "pillow>=11.2.1",
   "pip>=25.1.1",
-  "psutil>=5.8.0",
+  "psutil>=5.8.0,<7.2.0",
   "py-cord>=2.6.1",
   "pydantic~=2.10.3",
   "pydub>=0.25.1",

requirements.txt

@@ -27,7 +27,7 @@ openai>=1.78.0
 ormsgpack>=1.9.1
 pillow>=11.2.1
 pip>=25.1.1
-psutil>=5.8.0
+psutil>=5.8.0,<7.2.0
 py-cord>=2.6.1
 pydantic~=2.10.3
 pydub>=0.25.1