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

[ydzat]

Overview

This PR adds native support for sending QQ merged forward cards (合并转发) through the aiocqhttp adapter, and fixes a bug in MessageChain deserialization that caused data loss for Forward messages.

Changes

1. aiocqhttp.py - Forward message sending

• Added _send_forward_message() method to handle Forward message components
• Uses NapCat's send_forward_msg API with fallback to standard send_group_forward_msg
• Supports display settings (title, brief, summary, source)

2. handler.py - MessageChain deserialization fix

• Added _deserialize_message_chain() function for proper Forward message handling
• Fixed bug where nested ForwardMessageNode.message_chain was not properly deserialized
• The default MessageChain.model_validate() lost data in nested MessageChain fields

Screenshots

Before: Forward messages were flattened into plain text concatenation (type='Plain'type='Plain'...)

After: Forward messages are sent as proper QQ merged forward cards

Checklist

For PR author

• Have you read the contribution guide?
• Have you communicated with the project maintainer?
• I have tested the changes and ensured they work as expected.

For project maintainer

• Have you linked the related issues?
• Have you written the configuration items? Have you written the migration? Has it taken effect? (N/A - no config changes)
• Have you added the dependencies to pyproject.toml and core/bootutils/deps.py? (N/A - no new deps)
• Have you written the documentation?

[Copilot]

Pull request overview

This PR adds native support for sending QQ merged forward cards through the aiocqhttp adapter and fixes a MessageChain deserialization bug affecting Forward messages.

Changes:

• Added _send_forward_message() method in aiocqhttp adapter to send Forward messages as proper QQ merged forward cards using NapCat's API with fallback support
• Fixed MessageChain deserialization in handler.py by introducing _deserialize_message_chain() function that properly handles nested MessageChain objects in Forward and Quote components

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 7 comments.

File	Description
src/langbot/pkg/plugin/handler.py	Adds custom deserialization function to properly handle nested MessageChain in Forward and Quote components, replacing default model_validate that caused data loss
src/langbot/pkg/platform/sources/aiocqhttp.py	Adds _send_forward_message method to send Forward messages as QQ merged forward cards with display settings, supporting Plain and Image components

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

The type checking pattern is inconsistent with the existing yiri2target method. In yiri2target (lines 29-71), Plain and Image components use 'type(component) is platform_message.Plain' and 'type(component) is platform_message.Image' for exact type matching. However, in _send_forward_message, lines 401 and 404 use 'isinstance(component, platform_message.Plain)' and 'isinstance(component, platform_message.Image)'. For consistency with the existing codebase pattern, these should use 'type(component) is' instead of 'isinstance'.

Suggested change

	if isinstance(component, platform_message.Plain):
	if component.text:
	content.append({'type': 'text', 'data': {'text': component.text}})
	elif isinstance(component, platform_message.Image):
	if type(component) is platform_message.Plain:
	if component.text:
	content.append({'type': 'text', 'data': {'text': component.text}})
	elif type(component) is platform_message.Image:

[Copilot]

When an item in the data list is not a dict or doesn't have a 'type' field (line 40-42), or when the type is unknown (line 45-47), the function creates an Unknown component with the issue description. However, this could lead to confusion if the original issue was a transient serialization problem, as the Unknown component will be permanently stored in the MessageChain. Consider logging these occurrences at a warning level to aid debugging, especially since this function is meant to fix a deserialization bug and should be robust against various input formats.

[Copilot]

Forward messages are only sent as proper merged forward cards when target_type is 'group' (line 380). If a Forward message is sent to a person (private chat), the code falls through to line 385 where it uses the standard yiri2target converter, which flattens Forward messages into plain text by concatenating nested message chains (see lines 60-62 in yiri2target). This behavioral difference between group and person messages might be intentional (due to API limitations), but it could be unexpected for users. Consider documenting this limitation or adding a warning log when a Forward message is sent to a person.

Suggested change

	return
	return
	elif forward_msg and target_type == 'person':
	# Forward messages in private chats are not sent as merged forward cards.
	# They will be flattened into plain text by the standard yiri2target converter.
	# This warning documents the limitation to avoid surprising users.
	if hasattr(self, "logger") and self.logger is not None:
	self.logger.warning(
	"Forward messages sent to private chats are delivered as plain text; "
	"merged forward cards are only supported in group messages."
	)

[Copilot]

The base64 handling at lines 408-409 has a logical issue. If a base64 string starts with 'data:' but doesn't contain a comma, line 409 evaluates to 'b64' (unchanged) due to the ternary operator. However, this means the string will still have the 'data:' prefix, which is then re-added at line 410 with 'base64://', resulting in 'base64://data:image/...'. The correct approach is to either strip 'data:' unconditionally after checking it exists, or handle the case where comma is missing differently. Consider: if b64.startswith('data:'): b64 = b64.split(',', 1)[1] if ',' in b64 else b64[5:] (to strip 'data:' prefix).

Suggested change

	b64 = b64.split(',', 1)[-1] if ',' in b64 else b64
	b64 = b64.split(',', 1)[1] if ',' in b64 else b64[5:]

[Copilot]

When the primary send_forward_msg API fails, the fallback at line 470 calls send_group_forward_msg with only group_id and messages parameters. However, the primary API call at line 463 uses additional parameters from the payload dict including user_id, and potentially news, prompt, summary, and source fields. The fallback doesn't include these display settings, which means if the primary API fails, the forward message will be sent without the custom display settings (title, brief, summary, source) that the user may have configured in forward.display. Consider including these parameters in the fallback call, or documenting that display settings are not supported in fallback mode.

Suggested change

	# Fallback: try standard OneBot API with integer group_id
	try:
	await self.logger.info('Trying fallback API send_group_forward_msg')
	# Fallback: try standard OneBot API with integer group_id.
	# Note: OneBot's send_group_forward_msg does not support the extended display
	# fields (news/prompt/summary/source) or the NapCat-specific user_id behavior,
	# so only group_id and messages are sent here and any forward.display settings
	# will not affect the fallback message rendering.
	try:
	await self.logger.info('Trying fallback API send_group_forward_msg without extended display settings')

[Copilot]

The _send_forward_message method only handles Plain and Image components in forward messages. However, the existing yiri2target converter in this file (lines 28-75) supports many more component types including At, AtAll, Voice, File, Face, and nested Forward messages. This creates an inconsistency where forward messages with these component types will be silently ignored rather than properly converted. Consider either supporting all component types that yiri2target supports, or at least handling unsupported types explicitly (e.g., converting them to text as done in yiri2target line 74).

Suggested change

	else:
	# Fallback: convert other component types to text, similar to yiri2target
	text = getattr(component, 'text', None)
	if not text:
	text = str(component)
	if text:
	content.append({'type': 'text', 'data': {'text': text}})

[Copilot]

When a forward message node has no valid content (empty content list), the node is skipped with 'continue' at line 420. If all nodes are skipped this way, the method returns early at line 436 without sending anything or notifying the caller. This could lead to silent failures where the user expects a forward message to be sent but nothing happens. Consider logging a warning when all nodes are empty, or throwing an exception to make the failure explicit.

Suggested change

	if not messages:
	if not messages:
	# No valid nodes produced any content; nothing will be sent.
	# Log this condition to avoid silent failures for callers.
	await self.logger.info(
	f'Forward message to group {group_id} not sent: all nodes had empty or invalid content.'
	)

[RockChinQ]

Hi @ydzat 👋

I reviewed this PR and noticed that the _deserialize_message_chain function in handler.py duplicates (and replaces) the existing MessageChain.model_validate logic, which has a large blast radius — all message deserialization goes through the new code path, not just Forward messages.

Root cause: The SDK's MessageChain.model_validate doesn't handle ForwardMessageNode.message_chain because its annotation is Optional[MessageChain] (not MessageChain), so the recursive field check doesn't match.

Fix: I've submitted a fix to the SDK directly: langbot-app/langbot-plugin-sdk#38

Once that SDK PR is merged, the custom _deserialize_message_chain function in handler.py can be removed entirely — just use the standard MessageChain.model_validate() and Forward will deserialize correctly.

Suggested changes for this PR:

1. Remove the _deserialize_message_chain function from handler.py
2. Revert the import change (List, Dict not needed)
3. Keep the send_message / _send_forward_message changes in aiocqhttp.py as-is (those are good 👍)

Other minor issues in aiocqhttp.py to consider:

• await self.logger.info(...) — is the logger async? If not, drop the await
• group_id is passed as str in the payload but standard OneBot expects int
• Forward + target_type == 'person' silently falls through to normal conversion (should at least log a warning)

Happy to help if you want to coordinate on timing with the SDK fix!

[RockChinQ]

Update: ignore my earlier note about await self.logger.info() — LangBot's logger methods are indeed async def, so await is correct. 👍

[codecov]

Codecov Report

❌ Patch coverage is 0% with 59 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/langbot/pkg/platform/sources/aiocqhttp.py	0.00%	59 Missing ⚠️

📢 Thoughts on this report? Let us know!