feat(platform): add Forward message support for aiocqhttp adapter

- Add _send_forward_message method to send merged forward cards via OneBot API
- Support NapCat's send_forward_msg API with fallback to send_group_forward_msg
- Fix MessageChain deserialization for Forward messages in handler.py
- Properly deserialize nested ForwardMessageNode.message_chain to preserve data

This enables plugins to send QQ merged forward cards through the standard
LangBot send_message API using the Forward message component.

Author: ydzat

src/langbot/pkg/platform/sources/aiocqhttp.py

@@ -375,13 +375,112 @@ async def shutdown_trigger_placeholder():
             self.bot = aiocqhttp.CQHttp()
 
     async def send_message(self, target_type: str, target_id: str, message: platform_message.MessageChain):
+        # Check if message contains a Forward component
+        forward_msg = message.get_first(platform_message.Forward)
+        if forward_msg and target_type == 'group':
+            # Send as merged forward message via OneBot API
+            await self._send_forward_message(int(target_id), forward_msg)
+            return
+
         aiocq_msg = (await AiocqhttpMessageConverter.yiri2target(message))[0]
 
         if target_type == 'group':
             await self.bot.send_group_msg(group_id=int(target_id), message=aiocq_msg)
         elif target_type == 'person':
             await self.bot.send_private_msg(user_id=int(target_id), message=aiocq_msg)
 
+    async def _send_forward_message(self, group_id: int, forward: platform_message.Forward):
+        """Send a merged forward message to a group using NapCat extended API."""
+        messages = []
+
+        for node in forward.node_list:
+            # Build content for each node
+            content = []
+            if node.message_chain:
+                for component in node.message_chain:
+                    if isinstance(component, platform_message.Plain):
+                        if component.text:
+                            content.append({
+                                "type": "text",
+                                "data": {"text": component.text}
+                            })
+                    elif isinstance(component, platform_message.Image):
+                        img_data = {}
+                        if component.base64:
+                            b64 = component.base64
+                            if b64.startswith('data:'):
+                                b64 = b64.split(',', 1)[-1] if ',' in b64 else b64
+                            img_data["file"] = f"base64://{b64}"
+                        elif component.url:
+                            img_data["file"] = component.url
+                        elif component.path:
+                            img_data["file"] = str(component.path)
+
+                        if img_data:
+                            content.append({
+                                "type": "image",
+                                "data": img_data
+                            })
+
+            if not content:
+                continue
+
+            # Build node data - use user_id and nickname format for NapCat
+            user_id = str(node.sender_id) if node.sender_id else str(self.bot_account_id or "10000")
+            node_data = {
+                "type": "node",
+                "data": {
+                    "user_id": user_id,
+                    "nickname": node.sender_name or "未知",
+                    "content": content,
+                }
+            }
+
+            messages.append(node_data)
+
+        if not messages:
+            return
+
+        # Build the full message payload for NapCat's send_forward_msg API
+        # This matches the format used by GiveMeSetuPlugin
+        bot_id = str(self.bot_account_id) if self.bot_account_id else "10000"
+        payload = {
+            "group_id": str(group_id),
+            "user_id": bot_id,  # Required by NapCat for display
+            "messages": messages,
+        }
+
+        # Add display settings if available
+        if forward.display:
+            if forward.display.title:
+                payload["news"] = [{"text": forward.display.title}]
+            if forward.display.brief:
+                payload["prompt"] = forward.display.brief
+            if forward.display.summary:
+                payload["summary"] = forward.display.summary
+            if forward.display.source:
+                payload["source"] = forward.display.source
+
+        try:
+            # Use send_forward_msg (NapCat extended API) instead of send_group_forward_msg
+            await self.logger.info(f"Sending forward message to group {group_id} with {len(messages)} nodes, payload keys: {list(payload.keys())}")
+            result = await self.bot.call_action("send_forward_msg", **payload)
+            await self.logger.info(f"Forward message sent to group {group_id}, result: {result}")
+        except Exception as e:
+            await self.logger.error(f"Failed to send forward message to group {group_id}: {e}")
+            # Fallback: try standard OneBot API with integer group_id
+            try:
+                await self.logger.info(f"Trying fallback API send_group_forward_msg")
+                await self.bot.call_action(
+                    "send_group_forward_msg",
+                    group_id=group_id,
+                    messages=messages
+                )
+                await self.logger.info(f"Forward message sent via fallback API to group {group_id}")
+            except Exception as e2:
+                await self.logger.error(f"Fallback also failed: {e2}")
+                raise
+
     async def reply_message(
         self,
         message_source: platform_events.MessageEvent,

src/langbot/pkg/plugin/handler.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 import typing
-from typing import Any
+from typing import Any, List, Dict
 import base64
 import traceback
 
@@ -26,6 +26,76 @@
 from ..utils import constants
 
 
+def _deserialize_message_chain(data: List[Dict[str, Any]]) -> platform_message.MessageChain:
+    """Deserialize message chain with proper handling of Forward messages.
+
+    The default MessageChain.model_validate doesn't properly deserialize nested
+    MessageChain in ForwardMessageNode, causing data loss. This function handles
+    that case explicitly.
+    """
+    components = []
+    component_types = platform_message.MessageChain._get_component_types()
+
+    for item in data:
+        if not isinstance(item, dict) or 'type' not in item:
+            components.append(platform_message.Unknown(text=f"Invalid component: {item}"))
+            continue
+
+        comp_type = item['type']
+        if comp_type not in component_types:
+            components.append(platform_message.Unknown(text=f"Unknown type: {comp_type}"))
+            continue
+
+        comp_class = component_types[comp_type]
+
+        # Special handling for Forward messages
+        if comp_type == 'Forward':
+            node_list = []
+            for node_data in item.get('node_list', []):
+                # Recursively deserialize message_chain in each node
+                mc_data = node_data.get('message_chain', [])
+                if isinstance(mc_data, list):
+                    mc = _deserialize_message_chain(mc_data)
+                elif isinstance(mc_data, platform_message.MessageChain):
+                    mc = mc_data
+                else:
+                    mc = platform_message.MessageChain([])
+
+                node = platform_message.ForwardMessageNode(
+                    sender_id=node_data.get('sender_id', ''),
+                    sender_name=node_data.get('sender_name', ''),
+                    message_chain=mc,
+                    message_id=node_data.get('message_id', 0),
+                )
+                node_list.append(node)
+
+            display_data = item.get('display', {})
+            display = platform_message.ForwardMessageDiaplay(
+                title=display_data.get('title', 'Chat history'),
+                brief=display_data.get('brief', '[Chat history]'),
+                source=display_data.get('source', 'Chat history'),
+                preview=display_data.get('preview', []),
+                summary=display_data.get('summary', 'View forwarded messages'),
+            )
+
+            forward = platform_message.Forward(
+                display=display,
+                node_list=node_list,
+            )
+            components.append(forward)
+        else:
+            # For other component types, use default validation
+            # but handle Quote's nested MessageChain
+            if comp_type == 'Quote' and 'origin' in item:
+                origin_data = item['origin']
+                if isinstance(origin_data, list):
+                    item['origin'] = _deserialize_message_chain(origin_data)
+
+            components.append(comp_class.model_validate(item))
+
+    return platform_message.MessageChain(root=components)
+
+
 class RuntimeConnectionHandler(handler.Handler):
     """Runtime connection handler"""
 
@@ -279,7 +349,8 @@ async def send_message(data: dict[str, Any]) -> handler.ActionResponse:
             target_id = data['target_id']
             message_chain = data['message_chain']
 
-            message_chain_obj = platform_message.MessageChain.model_validate(message_chain)
+            # Use custom deserializer that properly handles Forward messages
+            message_chain_obj = _deserialize_message_chain(message_chain)
 
             bot = await self.ap.platform_mgr.get_bot_by_uuid(bot_uuid)
             if bot is None: