Add Telegram parse_mode support for send_message

app/agent/prompt/System Core Prompt.txt

@@ -87,6 +87,7 @@ You act as a proactive agent. Your goal is to fully resolve the user's media-rel
 {button_choice_spec}
 - Voice replies: {voice_reply_spec}
 - If the current channel supports image sending and an image would materially help, you may use the `send_message` tool with `image_url` to send it.
+{send_message_format_spec}
 - If the current channel supports file sending and you need to return a local image or file for the user to download, use `send_local_file`.
 </communication_runtime>
 

app/agent/prompt/__init__.py

@@ -141,6 +141,9 @@ class PromptManager:
             if caps:
                 markdown_spec = self._generate_formatting_instructions(caps)
         button_choice_spec = self._generate_button_choice_instructions(msg_channel)
+        send_message_format_spec = self._generate_send_message_format_instructions(
+            msg_channel
+        )
 
         # 啰嗦模式
         verbose_spec = ""
@@ -166,6 +169,7 @@ class PromptManager:
             moviepilot_info=moviepilot_info,
             voice_reply_spec=voice_reply_spec,
             button_choice_spec=button_choice_spec,
+            send_message_format_spec=send_message_format_spec,
         )
 
         return base_prompt
@@ -400,6 +404,27 @@ class PromptManager:
             "content as a text fallback and still completes the reply."
         )
 
+    @staticmethod
+    def _generate_send_message_format_instructions(
+        channel: MessageChannel = None,
+    ) -> str:
+        """
+        根据渠道生成 send_message 工具的格式参数提示。
+        """
+        if channel != MessageChannel.Telegram:
+            return ""
+        return (
+            "- Telegram message formatting: `send_message` supports an optional "
+            "`parse_mode` argument. Leave it empty for default MarkdownV2. When a "
+            "structured Telegram notice would be clearer in HTML, set "
+            "`parse_mode=\"HTML\"` and write the `message` using only Telegram-supported "
+            "HTML tags such as `<b>`, `<i>`, `<u>`, `<s>`, `<code>`, `<pre>`, "
+            "`<blockquote>`, and `<a href=\"...\">`. Keep `title` as plain text; "
+            "the Telegram module renders it as a bold heading automatically. Escape "
+            "user-provided or dynamic values before embedding them in HTML. Do "
+            "not mix Markdown syntax into an HTML-formatted message."
+        )
+
     @staticmethod
     def _generate_button_choice_instructions(
         channel: MessageChannel = None,

app/agent/tools/impl/send_message.py

@@ -10,12 +10,22 @@ from app.log import logger
 from app.schemas import Notification
 from app.schemas.types import NotificationType
 
+SEND_MESSAGE_PARSE_MODE_MARKDOWN = "MarkdownV2"
+SEND_MESSAGE_PARSE_MODE_HTML = "HTML"
+SEND_MESSAGE_PARSE_MODE_ALIASES = {
+    "markdownv2": SEND_MESSAGE_PARSE_MODE_MARKDOWN,
+    "mdv2": SEND_MESSAGE_PARSE_MODE_MARKDOWN,
+    "html": SEND_MESSAGE_PARSE_MODE_HTML,
+}
+
 
 class SendMessageInput(BaseModel):
     """发送消息工具的输入参数模型"""
 
-    explanation: Optional[str] = Field(None,
-        description="Clear explanation of why this tool is being used in the current context",)
+    explanation: Optional[str] = Field(
+        None,
+        description="Clear explanation of why this tool is being used in the current context",
+    )
     message: Optional[str] = Field(
         None,
         description="The message content to send to the user (should be clear and informative)",
@@ -28,15 +38,26 @@ class SendMessageInput(BaseModel):
         None,
         description="Optional image URL to send together with the message on channels that support images (such as Telegram and Slack)",
     )
+    parse_mode: Optional[str] = Field(
+        None,
+        description=(
+            "Optional Telegram message body format. Supported values: HTML or MarkdownV2. "
+            "Leave empty for default."
+        ),
+    )
 
     @model_validator(mode="after")
-    def validate_payload(self):
+    def validate_payload(self) -> "SendMessageInput":
+        """校验消息内容和可选格式参数。"""
         if not self.message and not self.title and not self.image_url:
             raise ValueError("message、title、image_url 至少需要提供一个")
+        self.parse_mode = SendMessageTool.normalize_parse_mode(self.parse_mode)
         return self
 
 
 class SendMessageTool(MoviePilotTool):
+    """发送普通通知消息给当前用户。"""
+
     name: str = "send_message"
     tags: list[str] = [
         ToolTag.Write,
@@ -44,10 +65,27 @@ class SendMessageTool(MoviePilotTool):
         ToolTag.Admin,
     ]
     sends_message: bool = True
-    description: str = "Send notification message to the user through configured notification channels (Telegram, Slack, WeChat, etc.). Supports optional image_url on channels that can send images. Used to inform users about operation results, errors, important updates, or proactively send a relevant image."
+    description: str = (
+        "Send notification message to the user through configured notification channels "
+        "(Telegram, Slack, WeChat, etc.). Supports optional image_url on channels that can "
+        "send images. For Telegram, the optional parse_mode parameter controls message body "
+        "rendering. Supported values are HTML and MarkdownV2; leave it empty for default."
+    )
     args_schema: Type[BaseModel] = SendMessageInput
     require_admin: bool = True
 
+    @staticmethod
+    def normalize_parse_mode(parse_mode: Optional[str]) -> Optional[str]:
+        """
+        规范化 send_message 支持的 Telegram 格式参数。
+        """
+        if not parse_mode:
+            return None
+        normalized = SEND_MESSAGE_PARSE_MODE_ALIASES.get(str(parse_mode).strip().lower())
+        if not normalized:
+            raise ValueError("parse_mode 仅支持 MarkdownV2 或 HTML")
+        return normalized
+
     def get_tool_message(self, **kwargs) -> Optional[str]:
         """根据消息参数生成友好的提示消息"""
         message = kwargs.get("message", "") or ""
@@ -71,12 +109,20 @@ class SendMessageTool(MoviePilotTool):
         message: Optional[str] = None,
         title: Optional[str] = None,
         image_url: Optional[str] = None,
+        parse_mode: Optional[str] = None,
         **kwargs,
     ) -> str:
+        """发送消息到当前会话渠道。"""
         title = title or ("图片" if image_url and not message else "")
         text = message or ""
+        try:
+            parse_mode = self.normalize_parse_mode(parse_mode)
+        except ValueError as e:
+            return str(e)
+
         logger.info(
-            f"执行工具: {self.name}, 参数: title={title}, message={text}, image_url={image_url}"
+            f"执行工具: {self.name}, 参数: title={title}, message={text}, "
+            f"image_url={image_url}, parse_mode={parse_mode}"
         )
         try:
             await self.send_notification_message(
@@ -89,6 +135,7 @@ class SendMessageTool(MoviePilotTool):
                     title=title,
                     text=text,
                     image=image_url,
+                    parse_mode=parse_mode,
                 )
             )
             return "消息已发送"

tests/test_agent_image_support.py

@@ -569,6 +569,15 @@ class AgentImageSupportTest(unittest.TestCase):
 
         self.assertEqual(payload.image_url, "https://example.com/poster.png")
 
+    def test_send_message_input_normalizes_html_parse_mode(self):
+        payload = SendMessageInput(
+            explanation="send html notice",
+            message="<b>处理完成</b>",
+            parse_mode="html",
+        )
+
+        self.assertEqual(payload.parse_mode, "HTML")
+
     def test_send_message_tool_uses_regular_notification_type(self):
         """发送消息工具应按普通通知消息登记。"""
 
@@ -588,6 +597,7 @@ class AgentImageSupportTest(unittest.TestCase):
                     message="处理完成",
                     title="智能体通知",
                     image_url="https://example.com/poster.png",
+                    parse_mode="HTML",
                 )
             return result, async_post_message
 
@@ -601,6 +611,33 @@ class AgentImageSupportTest(unittest.TestCase):
         self.assertEqual(notification.title, "智能体通知")
         self.assertEqual(notification.text, "处理完成")
         self.assertEqual(notification.image, "https://example.com/poster.png")
+        self.assertEqual(notification.parse_mode, "HTML")
+
+    def test_send_message_tool_rejects_invalid_parse_mode(self):
+        """发送消息工具应拒绝不支持的格式类型。"""
+
+        async def _run():
+            tool = SendMessageTool(session_id="session-1", user_id="10001")
+            tool.set_message_attr(
+                channel=MessageChannel.Telegram.value,
+                source="telegram-test",
+                username="tester",
+            )
+
+            with patch(
+                "app.agent.tools.base.ToolChain.async_post_message",
+                new_callable=AsyncMock,
+            ) as async_post_message:
+                result = await tool.run(
+                    message="处理完成",
+                    parse_mode="Markdown",
+                )
+            return result, async_post_message
+
+        result, async_post_message = asyncio.run(_run())
+
+        self.assertIn("parse_mode 仅支持 MarkdownV2 或 HTML", result)
+        async_post_message.assert_not_awaited()
 
     def test_send_local_file_input_accepts_file_payload(self):
         payload = SendLocalFileInput(

tests/test_agent_interaction.py

@@ -38,6 +38,19 @@ class TestAgentInteraction(unittest.TestCase):
         self.assertIn("do not write a final text reply after it", telegram_prompt)
         self.assertNotIn("ask_user_choice", wechat_prompt)
 
+    def test_prompt_injects_send_message_html_hint_only_for_telegram(self):
+        telegram_prompt = prompt_manager.get_agent_prompt(
+            channel=MessageChannel.Telegram.value
+        )
+        wechat_prompt = prompt_manager.get_agent_prompt(
+            channel=MessageChannel.Wechat.value
+        )
+
+        self.assertIn("parse_mode=\"HTML\"", telegram_prompt)
+        self.assertIn("Telegram-supported HTML tags", telegram_prompt)
+        self.assertIn("Do not mix Markdown syntax", telegram_prompt)
+        self.assertNotIn("parse_mode=\"HTML\"", wechat_prompt)
+
     def test_factory_injects_choice_tool_only_for_button_channels(self):
         with patch(
             "app.agent.tools.factory.PluginManager.get_plugin_agent_tools",