feat: support persona custom error reply message with fallback (#5547)

* feat: support persona custom error reply message with fallback

* refactor: centralize persona custom error message helpers

Author: zouyonghe

astrbot/core/agent/runners/tool_loop_agent_runner.py

@@ -23,6 +23,9 @@
 from astrbot.core.message.message_event_result import (
     MessageChain,
 )
+from astrbot.core.persona_error_reply import (
+    extract_persona_custom_error_message_from_event,
+)
 from astrbot.core.provider.entities import (
     LLMResponse,
     ProviderRequest,
@@ -78,6 +81,11 @@ class FollowUpTicket:
 
 
 class ToolLoopAgentRunner(BaseAgentRunner[TContext]):
+    def _get_persona_custom_error_message(self) -> str | None:
+        """Read persona-level custom error message from event extras when available."""
+        event = getattr(self.run_context.context, "event", None)
+        return extract_persona_custom_error_message_from_event(event)
+
     @override
     async def reset(
         self,
@@ -463,12 +471,14 @@ async def step(self):
             self.stats.end_time = time.time()
             self._transition_state(AgentState.ERROR)
             self._resolve_unconsumed_follow_ups()
+            custom_error_message = self._get_persona_custom_error_message()
+            error_text = custom_error_message or (
+                f"LLM 响应错误: {llm_resp.completion_text or '未知错误'}"
+            )
             yield AgentResponse(
                 type="err",
                 data=AgentResponseData(
-                    chain=MessageChain().message(
-                        f"LLM 响应错误: {llm_resp.completion_text or '未知错误'}",
-                    ),
+                    chain=MessageChain().message(error_text),
                 ),
             )
             return

astrbot/core/astr_agent_run_util.py

@@ -14,6 +14,9 @@
     MessageEventResult,
     ResultContentType,
 )
+from astrbot.core.persona_error_reply import (
+    extract_persona_custom_error_message_from_event,
+)
 from astrbot.core.provider.entities import LLMResponse
 from astrbot.core.provider.provider import TTSProvider
 
@@ -235,7 +238,16 @@ async def run_agent(
                     pass
             logger.error(traceback.format_exc())
 
-            err_msg = f"\n\nAstrBot 请求失败。\n错误类型: {type(e).__name__}\n错误信息: {e!s}\n\n请在平台日志查看和分享错误详情。\n"
+            custom_error_message = extract_persona_custom_error_message_from_event(
+                astr_event
+            )
+            if custom_error_message:
+                err_msg = custom_error_message
+            else:
+                err_msg = (
+                    f"\n\nAstrBot 请求失败。\n错误类型: {type(e).__name__}\n错误信息: "
+                    f"{e!s}\n\n请在平台日志查看和分享错误详情。\n"
+                )
 
             error_llm_response = LLMResponse(
                 role="err",

astrbot/core/astr_main_agent.py

@@ -37,6 +37,10 @@
 )
 from astrbot.core.conversation_mgr import Conversation
 from astrbot.core.message.components import File, Image, Reply
+from astrbot.core.persona_error_reply import (
+    extract_persona_custom_error_message_from_persona,
+    set_persona_custom_error_message_on_event,
+)
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
 from astrbot.core.provider import Provider
 from astrbot.core.provider.entities import ProviderRequest
@@ -285,6 +289,10 @@ async def _ensure_persona_and_skills(
         provider_settings=cfg,
     )
 
+    set_persona_custom_error_message_on_event(
+        event, extract_persona_custom_error_message_from_persona(persona)
+    )
+
     if persona:
         # Inject persona system prompt
         if prompt := persona["prompt"]:

astrbot/core/db/__init__.py

@@ -306,6 +306,7 @@ async def insert_persona(
         begin_dialogs: list[str] | None = None,
         tools: list[str] | None = None,
         skills: list[str] | None = None,
+        custom_error_message: str | None = None,
         folder_id: str | None = None,
         sort_order: int = 0,
     ) -> Persona:
@@ -317,6 +318,7 @@ async def insert_persona(
             begin_dialogs: Optional list of initial dialog strings
             tools: Optional list of tool names (None means all tools, [] means no tools)
             skills: Optional list of skill names (None means all skills, [] means no skills)
+            custom_error_message: Optional persona-level fallback error message
             folder_id: Optional folder ID to place the persona in (None means root)
             sort_order: Sort order within the folder (default 0)
         """
@@ -340,6 +342,7 @@ async def update_persona(
         begin_dialogs: list[str] | None = None,
         tools: list[str] | None = None,
         skills: list[str] | None = None,
+        custom_error_message: str | None = None,
     ) -> Persona | None:
         """Update a persona's system prompt or begin dialogs."""
         ...

astrbot/core/db/po.py

@@ -126,6 +126,8 @@ class Persona(TimestampMixin, SQLModel, table=True):
     """None means use ALL tools for default, empty list means no tools, otherwise a list of tool names."""
     skills: list | None = Field(default=None, sa_type=JSON)
     """None means use ALL skills for default, empty list means no skills, otherwise a list of skill names."""
+    custom_error_message: str | None = Field(default=None, sa_type=Text)
+    """Optional custom error message sent to end users when the agent request fails."""
     folder_id: str | None = Field(default=None, max_length=36)
     """所属文件夹ID，NULL 表示在根目录"""
     sort_order: int = Field(default=0)
@@ -472,6 +474,8 @@ class Personality(TypedDict):
     """工具列表。None 表示使用所有工具，空列表表示不使用任何工具"""
     skills: list[str] | None
     """Skills 列表。None 表示使用所有 Skills，空列表表示不使用任何 Skills"""
+    custom_error_message: str | None
+    """可选的人格自定义报错回复信息。配置后将优先发送给最终用户。"""
 
     # cache
     _begin_dialogs_processed: list[dict]

astrbot/core/db/sqlite.py

@@ -32,8 +32,8 @@
 from astrbot.core.db.po import (
     Stats as DeprecatedStats,
 )
+from astrbot.core.sentinels import NOT_GIVEN
 
-NOT_GIVEN = T.TypeVar("NOT_GIVEN")
 TxResult = T.TypeVar("TxResult")
 CRON_FIELD_NOT_SET = object()
 
@@ -58,6 +58,7 @@ async def initialize(self) -> None:
             # 确保 personas 表有 folder_id、sort_order、skills 列（前向兼容）
             await self._ensure_persona_folder_columns(conn)
             await self._ensure_persona_skills_column(conn)
+            await self._ensure_persona_custom_error_message_column(conn)
             await conn.commit()
 
     async def _ensure_persona_folder_columns(self, conn) -> None:
@@ -92,6 +93,16 @@ async def _ensure_persona_skills_column(self, conn) -> None:
         if "skills" not in columns:
             await conn.execute(text("ALTER TABLE personas ADD COLUMN skills JSON"))
 
+    async def _ensure_persona_custom_error_message_column(self, conn) -> None:
+        """确保 personas 表有 custom_error_message 列。"""
+        result = await conn.execute(text("PRAGMA table_info(personas)"))
+        columns = {row[1] for row in result.fetchall()}
+
+        if "custom_error_message" not in columns:
+            await conn.execute(
+                text("ALTER TABLE personas ADD COLUMN custom_error_message TEXT")
+            )
+
     # ====
     # Platform Statistics
     # ====
@@ -675,6 +686,7 @@ async def insert_persona(
         begin_dialogs=None,
         tools=None,
         skills=None,
+        custom_error_message=None,
         folder_id=None,
         sort_order=0,
     ):
@@ -688,6 +700,7 @@ async def insert_persona(
                     begin_dialogs=begin_dialogs or [],
                     tools=tools,
                     skills=skills,
+                    custom_error_message=custom_error_message,
                     folder_id=folder_id,
                     sort_order=sort_order,
                 )
@@ -719,6 +732,7 @@ async def update_persona(
         begin_dialogs=None,
         tools=NOT_GIVEN,
         skills=NOT_GIVEN,
+        custom_error_message=NOT_GIVEN,
     ):
         """Update a persona's system prompt or begin dialogs."""
         async with self.get_db() as session:
@@ -734,6 +748,8 @@ async def update_persona(
                     values["tools"] = tools
                 if skills is not NOT_GIVEN:
                     values["skills"] = skills
+                if custom_error_message is not NOT_GIVEN:
+                    values["custom_error_message"] = custom_error_message
                 if not values:
                     return None
                 query = query.values(**values)

astrbot/core/persona_error_reply.py

@@ -0,0 +1,86 @@
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+PERSONA_CUSTOM_ERROR_MESSAGE_EXTRA_KEY = "persona_custom_error_message"
+
+
+def normalize_persona_custom_error_message(value: object) -> str | None:
+    """Normalize persona custom error reply text."""
+    if not isinstance(value, str):
+        return None
+    message = value.strip()
+    return message or None
+
+
+def extract_persona_custom_error_message_from_persona(
+    persona: Mapping[str, Any] | None,
+) -> str | None:
+    """Extract normalized custom error reply text from persona mapping."""
+    if persona is None:
+        return None
+    return normalize_persona_custom_error_message(persona.get("custom_error_message"))
+
+
+def extract_persona_custom_error_message_from_event(event: Any) -> str | None:
+    """Extract normalized custom error reply text from event extras."""
+    try:
+        if event is None or not hasattr(event, "get_extra"):
+            return None
+        raw_message = event.get_extra(PERSONA_CUSTOM_ERROR_MESSAGE_EXTRA_KEY)
+        return normalize_persona_custom_error_message(raw_message)
+    except Exception:
+        return None
+
+
+def set_persona_custom_error_message_on_event(
+    event: Any, message: object
+) -> str | None:
+    """Normalize and store persona custom error reply text into event extras."""
+    normalized = normalize_persona_custom_error_message(message)
+    try:
+        if event is not None and hasattr(event, "set_extra"):
+            event.set_extra(PERSONA_CUSTOM_ERROR_MESSAGE_EXTRA_KEY, normalized)
+    except Exception:
+        pass
+    return normalized
+
+
+async def resolve_persona_custom_error_message(
+    *,
+    event: Any,
+    persona_manager: Any,
+    provider_settings: dict | None = None,
+    conversation_persona_id: str | None = None,
+) -> str | None:
+    """Resolve normalized custom error reply text for the selected persona."""
+    (
+        _persona_id,
+        persona,
+        _force_applied_persona_id,
+        _use_webchat_special_default,
+    ) = await persona_manager.resolve_selected_persona(
+        umo=event.unified_msg_origin,
+        conversation_persona_id=conversation_persona_id,
+        platform_name=event.get_platform_name(),
+        provider_settings=provider_settings,
+    )
+    return extract_persona_custom_error_message_from_persona(persona)
+
+
+async def resolve_event_conversation_persona_id(
+    event: Any, conversation_manager: Any
+) -> str | None:
+    """Resolve current conversation persona_id from event and conversation manager."""
+    curr_cid = await conversation_manager.get_curr_conversation_id(
+        event.unified_msg_origin
+    )
+    if not curr_cid:
+        return None
+    conversation = await conversation_manager.get_conversation(
+        event.unified_msg_origin, curr_cid
+    )
+    if not conversation:
+        return None
+    return conversation.persona_id

astrbot/core/persona_mgr.py

@@ -4,6 +4,7 @@
 from astrbot.core.db import BaseDatabase
 from astrbot.core.db.po import Persona, PersonaFolder, Personality
 from astrbot.core.platform.message_session import MessageSession
+from astrbot.core.sentinels import NOT_GIVEN
 
 DEFAULT_PERSONALITY = Personality(
     prompt="You are a helpful and friendly assistant.",
@@ -12,6 +13,7 @@
     mood_imitation_dialogs=[],
     tools=None,
     skills=None,
+    custom_error_message=None,
     _begin_dialogs_processed=[],
     _mood_imitation_dialogs_processed="",
 )
@@ -126,19 +128,27 @@ async def update_persona(
         persona_id: str,
         system_prompt: str | None = None,
         begin_dialogs: list[str] | None = None,
-        tools: list[str] | None = None,
-        skills: list[str] | None = None,
+        tools: list[str] | None | object = NOT_GIVEN,
+        skills: list[str] | None | object = NOT_GIVEN,
+        custom_error_message: str | None | object = NOT_GIVEN,
     ):
         """更新指定 persona 的信息。tools 参数为 None 时表示使用所有工具，空列表表示不使用任何工具"""
         existing_persona = await self.db.get_persona_by_id(persona_id)
         if not existing_persona:
             raise ValueError(f"Persona with ID {persona_id} does not exist.")
+        update_kwargs = {}
+        if tools is not NOT_GIVEN:
+            update_kwargs["tools"] = tools
+        if skills is not NOT_GIVEN:
+            update_kwargs["skills"] = skills
+        if custom_error_message is not NOT_GIVEN:
+            update_kwargs["custom_error_message"] = custom_error_message
+
         persona = await self.db.update_persona(
             persona_id,
             system_prompt,
             begin_dialogs,
-            tools=tools,
-            skills=skills,
+            **update_kwargs,
         )
         if persona:
             for i, p in enumerate(self.personas):
@@ -298,6 +308,7 @@ async def create_persona(
         begin_dialogs: list[str] | None = None,
         tools: list[str] | None = None,
         skills: list[str] | None = None,
+        custom_error_message: str | None = None,
         folder_id: str | None = None,
         sort_order: int = 0,
     ) -> Persona:
@@ -320,6 +331,7 @@ async def create_persona(
             begin_dialogs,
             tools=tools,
             skills=skills,
+            custom_error_message=custom_error_message,
             folder_id=folder_id,
             sort_order=sort_order,
         )
@@ -346,6 +358,7 @@ def get_v3_persona_data(
                 "mood_imitation_dialogs": [],  # deprecated
                 "tools": persona.tools,
                 "skills": persona.skills,
+                "custom_error_message": persona.custom_error_message,
             }
             for persona in self.personas
         ]
@@ -402,6 +415,7 @@ def get_v3_persona_data(
             begin_dialogs=selected_default_persona["begin_dialogs"],
             tools=selected_default_persona["tools"] or None,
             skills=selected_default_persona["skills"] or None,
+            custom_error_message=selected_default_persona["custom_error_message"],
         )
 
         return v3_persona_config, personas_v3, selected_default_persona

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

@@ -19,6 +19,9 @@
     MessageEventResult,
     ResultContentType,
 )
+from astrbot.core.persona_error_reply import (
+    extract_persona_custom_error_message_from_event,
+)
 from astrbot.core.pipeline.stage import Stage
 from astrbot.core.platform.astr_message_event import AstrMessageEvent
 from astrbot.core.provider.entities import (
@@ -366,11 +369,13 @@ async def process(
 
         except Exception as e:
             logger.error(f"Error occurred while processing agent: {e}")
-            await event.send(
-                MessageChain().message(
-                    f"Error occurred while processing agent request: {e}"
-                )
+            custom_error_message = extract_persona_custom_error_message_from_event(
+                event
+            )
+            error_text = custom_error_message or (
+                f"Error occurred while processing agent request: {e}"
             )
+            await event.send(MessageChain().message(error_text))
         finally:
             if follow_up_capture:
                 await finalize_follow_up_capture(