feat: add supports for dify hitl (#2226)

* feat: Implement workflow form handling for paused workflows

- Added module-level storage for pending forms to manage state across sessions.
- Introduced functions to set, get, and clear pending forms with expiration handling.
- Enhanced DifyServiceAPIRunner to support resuming paused workflows via form actions.
- Implemented logic to yield human input requests and display appropriate messages.
- Updated workflow submission methods to handle paused states and resume actions.
- Ensured proper merging of pending form actions with user inputs for seamless interaction.

* feat: Add '_routed_by_rule' variable to form action in Lark and Telegram adapters

* feat: Enhance Lark and Telegram adapters with new form handling for paused workflows

* feat: Enhance TelegramAdapter to handle form action buttons and message threading

* feat: Improve TelegramAdapter message handling with enhanced error management and draft message support

* feat: Add the function for formatting human input text to support adapters without rich UI.

* feat(dingtalk): implement human input card support and card action handling

- Add a new module `card_callback.py` to handle card action button clicks from DingTalk.
- Introduce `DingTalkCardActionHandler` to process card action callbacks and extract parameters.
- Update `DingTalkAdapter` to manage card state and handle form input through a single card template.
- Add configuration for `human_input_card_template_id` in `dingtalk.yaml` to specify the template for human input.
- Create a new card template `dingtalk_human_input_card.json` for rendering human input prompts and buttons.

* feat(dingtalk): enhance human input card functionality with streaming support and active turn management

- Updated the DingTalk card template to enable streaming mode and multi-update configuration.
- Removed the obsolete delete_card method from DingTalkClient to streamline card management.
- Enhanced DingTalkAdapter to manage active turn cards and accumulated streaming text, ensuring a seamless user experience during human input prompts.
- Modified the create_message_card method to utilize existing active cards for resumed workflows, preventing duplication.
- Improved the _paint_form_on_card method to update existing cards with human input prompts and buttons dynamically.
- Updated the dingtalk_human_input_card.json template to reflect the new streaming capabilities and configuration options.

* feat(wecom): implement Dify human input pause handling with button interaction support

* feat(qqofficial): implement Dify human input button interaction handling and markdown keyboard support

* feat(qqofficial): implement one-click QR binding and enhance localization support

* feat(discord): implement Discord form view with button interactions for Dify actions

* fix(telegram): correct group chat type check and handle oversized callback data for Telegram actions
fix(difysvapi): ensure safe access to remove-think configuration in pipeline settings

* feat(dify): add support for chatflow app type and enhance human input handling

* feat(telegram): add action title feedback for user selections in Telegram messages

* feat(lark): enhance LarkAdapter to store form content for resume notices

* feat(dingtalk): update display formatting for card content with HTML line breaks

* feat(dingtalk): add feedback functionality to cards with 👍/👎 buttons

- Implemented feedback state management for cards, allowing users to provide feedback via thumbs up/down buttons.
- Enhanced card rendering to include feedback buttons when appropriate.
- Registered feedback listeners to handle feedback events and update card states accordingly.
- Updated the card template to support dynamic button rendering for feedback actions.
- Improved error handling and logging for feedback actions and card updates.

* fix: add Avatar component to dingtalk_human_input_card.json for enhanced user interaction

* feat(wecom): add optional source block to interactive template cards for enhanced branding

* feat(wecom): add functions for template card action extraction and update, enhance button interaction handling

* feat(qqofficial): synchronize passive-reply counter with inbound message sequence

* feat(qqofficial): add method to identify invisible form placeholder chunks in messages

* feat(dingtalk): add download link for human input card template and enhance dynamic form configuration

* feat(telegram): enhance message handling with group stream deletion and form placeholder detection

* Add unit tests for DingTalk, Lark, WeComBot, and Dify service API runners

- Implement tests for DingTalk adapter helper functions including form content cleaning, input extraction, and completed input lines.
- Create unit tests for Lark adapter helper functions focusing on input extraction and completed input lines.
- Add tests for WeComBot template card functionalities, including event extraction and payload building for human input.
- Enhance Dify service API runner tests to cover human input forms, including input collection, action handling, and form snapshot extraction.

* feat: Enhance Telegram and QQ Official adapters with select field handling and form action processing

- Added support for select fields in Telegram adapter, including option extraction and callback handling.
- Implemented form action processing for Telegram callbacks, improving user interaction feedback.
- Introduced new helper functions for building keyboards and resolving select button actions in QQ Official adapter.
- Enhanced DifyServiceAPIRunner to handle cumulative streaming responses and improve error handling during workflow resumes.
- Added unit tests for new functionalities in Telegram and QQ Official adapters, ensuring robust behavior for select fields and form actions.

* feat(lark): add functions for current input definitions and visible form content handling
feat(qqofficial): update fallback text handling for non-streaming scenarios
feat(difysvapi): enhance form content processing for interactive fields and actions
test: add unit tests for Lark and QQ Official adapter functionalities

* Add tests for DingTalk adapter content processing and markdown formatting

- Updated the assertion in `test_dingtalk_completed_input_lines_include_text_and_select_values` to remove unnecessary markdown formatting.
- Added new tests to verify that `_dingtalk_clean_form_content` maintains the order of prompts and completed values in various scenarios.
- Introduced `test_dingtalk_card_markdown_preserves_internal_line_breaks` to ensure internal line breaks are correctly converted to HTML line breaks.

* feat: Refactor input handling and feedback messages across multiple adapters

* feat: Update the human-computer interaction template cards, and optimize the prompt information and content display.

* feat: Refactor pending form handling to isolate by bot and pipeline

* feat: Enhance error handling and caching for Dify and WeCom interactions

* feat: Enhance select input handling and validation in Dify API runner and Telegram adapter

* feat: Add missing completed input lines handling in DingTalk adapter

* feat: Add pipeline_uuid handling across multiple adapters and update related tests

src/langbot/libs/dify_service_api/v1/client.py

@@ -109,6 +109,62 @@ class AsyncDifyServiceClient:
                     if chunk.startswith('data:'):
                         yield json.loads(chunk[5:])
 
+    async def workflow_submit(
+        self,
+        form_token: str,
+        workflow_run_id: str,
+        inputs: dict[str, typing.Any],
+        user: str,
+        action: str = '',
+        timeout: float = 120.0,
+    ) -> typing.AsyncGenerator[dict[str, typing.Any], None]:
+        """Submit human input to resume a paused workflow, then stream events.
+
+        1. POST /form/human_input/{form_token} to submit the form
+        2. GET /workflow/{task_id}/events to stream the resumed workflow events
+        """
+
+        headers = {
+            'Authorization': f'Bearer {self.api_key}',
+            'Content-Type': 'application/json',
+        }
+
+        async with httpx.AsyncClient(
+            base_url=self.base_url,
+            trust_env=True,
+            timeout=timeout,
+        ) as client:
+            # Step 1: Submit the form
+            payload: dict[str, typing.Any] = {
+                'inputs': inputs if isinstance(inputs, dict) else {},
+                'user': user,
+                'action': action,
+            }
+
+            submit_resp = await client.post(
+                f'/form/human_input/{form_token}',
+                headers=headers,
+                json=payload,
+            )
+            if submit_resp.status_code != 200:
+                raise DifyAPIError(f'{submit_resp.status_code} {submit_resp.text}')
+
+            # Step 2: Stream resumed workflow events
+            async with client.stream(
+                'GET',
+                f'/workflow/{workflow_run_id}/events',
+                headers={'Authorization': f'Bearer {self.api_key}'},
+                params={'user': user},
+            ) as r:
+                if r.status_code != 200:
+                    body = (await r.aread()).decode(errors='replace')
+                    raise DifyAPIError(f'{r.status_code} {body}')
+                async for chunk in r.aiter_lines():
+                    if chunk.strip() == '':
+                        continue
+                    if chunk.startswith('data:'):
+                        yield json.loads(chunk[5:])
+
     async def upload_file(
         self,
         file: httpx._types.FileTypes,

src/langbot/libs/dingtalk_api/api.py

@@ -1,17 +1,48 @@
 import asyncio
 import base64
 import json
+import logging
+import os
 import time
+import typing
+import uuid
 import urllib.parse
-from typing import Callable
+from typing import Awaitable, Callable, Optional
 import dingtalk_stream  # type: ignore
 import websockets
 from .EchoHandler import EchoTextHandler
+from .card_callback import DingTalkCardActionHandler
 from .dingtalkevent import DingTalkEvent
 import httpx
 import traceback
 
 
+_stdout_logger = logging.getLogger('langbot.dingtalk_api')
+
+
+DINGTALK_OPENAPI_BASE = 'https://api.dingtalk.com'
+
+
+def _stringify_card_param_map(card_param_map: Optional[dict]) -> dict:
+    """DingTalk cardParamMap only accepts string values.
+
+    Keep callers free to pass structured values for template variables such
+    as button groups or select options, then encode them once at the API
+    boundary.
+    """
+    if not card_param_map:
+        return {}
+    result = {}
+    for key, value in card_param_map.items():
+        if value is None:
+            result[key] = ''
+        elif isinstance(value, str):
+            result[key] = value
+        else:
+            result[key] = json.dumps(value, ensure_ascii=False)
+    return result
+
+
 class DingTalkClient:
     def __init__(
         self,
@@ -21,6 +52,7 @@ class DingTalkClient:
         robot_code: str,
         markdown_card: bool,
         logger: None,
+        card_action_callback: Optional[Callable[[dict], Awaitable[None]]] = None,
     ):
         """初始化 WebSocket 连接并自动启动"""
         self.credential = dingtalk_stream.Credential(client_id, client_secret)
@@ -30,6 +62,14 @@ class DingTalkClient:
         # 在 DingTalkClient 中传入自己作为参数，避免循环导入
         self.EchoTextHandler = EchoTextHandler(self)
         self.client.register_callback_handler(dingtalk_stream.chatbot.ChatbotMessage.TOPIC, self.EchoTextHandler)
+        # STREAM-mode card action button click handler. Forwards parsed payload
+        # to the adapter so it can resume paused Dify workflows.
+        self.card_action_callback = card_action_callback
+        self.card_action_handler = DingTalkCardActionHandler(self.client, self._on_card_action)
+        self.client.register_callback_handler(
+            dingtalk_stream.handlers.CallbackHandler.TOPIC_CARD_CALLBACK,
+            self.card_action_handler,
+        )
         self._message_handlers = {
             'example': [],
         }
@@ -39,8 +79,24 @@ class DingTalkClient:
         self.access_token_expiry_time = ''
         self.markdown_card = markdown_card
         self.logger = logger
+        # Legacy access_token used by the OLD oapi.dingtalk.com endpoints
+        # (e.g. /media/upload, which is the only documented way to get an
+        # `@xxx` media_id usable in card Avatar.imageUrl). The new v1.0
+        # token doesn't work there — different auth domain.
+        self.legacy_access_token = ''
+        self.legacy_access_token_expiry_time: typing.Optional[float] = None
         self._stopped = False  # Flag to control the event loop
 
+    async def _on_card_action(self, payload: dict) -> None:
+        """Dispatch a parsed card-action payload to the adapter callback."""
+        if self.card_action_callback is None:
+            return
+        try:
+            await self.card_action_callback(payload)
+        except Exception:
+            if self.logger:
+                await self.logger.error(f'DingTalk card action callback error: {traceback.format_exc()}')
+
     async def get_access_token(self):
         url = 'https://api.dingtalk.com/v1.0/oauth2/accessToken'
         headers = {'Content-Type': 'application/json'}
@@ -429,18 +485,35 @@ class DingTalkClient:
             'Content-Type': 'application/json',
         }
 
+        # For enterprise-internal robots, robotCode == AppKey (client_id).
+        # The dedicated robot_code field is only required for scenario-group
+        # robots or third-party robots; fall back to client_id when empty so
+        # the common single-bot setup keeps working without manual config.
+        robot_code = self.robot_code or self.key
         data = {
-            'robotCode': self.robot_code,
+            'robotCode': robot_code,
             'userIds': [target_id],
             'msgKey': 'sampleText',
             'msgParam': json.dumps({'content': content}),
         }
+        _stdout_logger.info(
+            'DingTalk send_proactive_message_to_one request: robotCode=%s target_id=%s content_len=%d',
+            robot_code,
+            target_id,
+            len(content),
+        )
         try:
             async with httpx.AsyncClient() as client:
                 response = await client.post(url, headers=headers, json=data)
+                _stdout_logger.info(
+                    'DingTalk send_proactive_message_to_one response: status=%d body=%s',
+                    response.status_code,
+                    response.text[:500],
+                )
                 if response.status_code == 200:
                     return
         except Exception:
+            _stdout_logger.exception('DingTalk send_proactive_message_to_one error')
             await self.logger.error(f'failed to send proactive massage to person: {traceback.format_exc()}')
             raise Exception(f'failed to send proactive massage to person: {traceback.format_exc()}')
 
@@ -456,7 +529,7 @@ class DingTalkClient:
         }
 
         data = {
-            'robotCode': self.robot_code,
+            'robotCode': self.robot_code or self.key,
             'openConversationId': target_id,
             'msgKey': 'sampleText',
             'msgParam': json.dumps({'content': content}),
@@ -477,47 +550,334 @@ class DingTalkClient:
         quote_origin: bool = False,
         card_auto_layout: bool = False,
     ):
-        card_data = {}
-        card_data['config'] = json.dumps({'autoLayout': card_auto_layout})
-        card_data['content'] = ''
+        """Create + deliver the streaming chat card for a chatbot reply.
 
-        # 将用户的消息内容作为卡片的查询参数，方便后续处理
-        if incoming_message.message_type == 'text':
-            card_data['query'] = incoming_message.get_text_list()[0]
+        Replaces the old `dingtalk_stream.AICardReplier`-based path. Returns
+        `(None, out_track_id)` to keep call sites compatible with the
+        previous `(card_instance, card_instance_id)` shape — the first slot
+        is unused now that everything is driven by out_track_id.
+        """
+        out_track_id = uuid.uuid4().hex
+        is_group = str(incoming_message.conversation_type) == '2'
+        if is_group:
+            open_space_id = f'dtv1.card//IM_GROUP.{incoming_message.conversation_id}'
         else:
-            card_data['query'] = '...'
+            open_space_id = f'dtv1.card//IM_ROBOT.{incoming_message.sender_staff_id}'
 
-        card_instance = dingtalk_stream.AICardReplier(self.client, incoming_message)
-        # print(card_instance)
-        # 先投放卡片: https://open.dingtalk.com/document/orgapp/create-and-deliver-cards
-        card_instance_id = await card_instance.async_create_and_deliver_card(
-            temp_card_id,
-            card_data,
+        card_param_map = {'content': ''}
+        if incoming_message.message_type == 'text':
+            card_param_map['query'] = incoming_message.get_text_list()[0]
+        else:
+            card_param_map['query'] = '...'
+
+        await self.create_and_deliver_card(
+            card_template_id=temp_card_id,
+            out_track_id=out_track_id,
+            open_space_id=open_space_id,
+            is_group=is_group,
+            card_param_map=card_param_map,
+            card_data_config={'autoLayout': card_auto_layout},
         )
-        return card_instance, card_instance_id
+        return None, out_track_id
 
     async def send_card_message(self, card_instance, card_instance_id: str, content: str, is_final: bool):
-        content_key = 'content'
+        """Stream a single chunk into an existing card's `content` field."""
         try:
-            await card_instance.async_streaming(
-                card_instance_id,
-                content_key=content_key,
+            await self.streaming_update_card(
+                out_track_id=card_instance_id,
+                content_key='content',
                 content_value=content,
                 append=False,
                 finished=is_final,
                 failed=False,
             )
         except Exception as e:
-            self.logger.exception(e)
-            await card_instance.async_streaming(
-                card_instance_id,
-                content_key=content_key,
+            if self.logger:
+                self.logger.exception(e)
+            await self.streaming_update_card(
+                out_track_id=card_instance_id,
+                content_key='content',
                 content_value='',
                 append=False,
                 finished=is_final,
                 failed=True,
             )
 
+    async def create_and_deliver_card(
+        self,
+        *,
+        card_template_id: str,
+        out_track_id: str,
+        open_space_id: str,
+        is_group: bool,
+        card_param_map: Optional[dict] = None,
+        callback_type: str = 'STREAM',
+        callback_route_key: Optional[str] = None,
+        support_forward: bool = True,
+        dynamic_data_source_configs: Optional[list] = None,
+        card_data_config: Optional[dict] = None,
+        at_user_ids: Optional[dict] = None,
+        recipients: Optional[list] = None,
+    ) -> bool:
+        """POST /v1.0/card/instances/createAndDeliver.
+
+        Mirrors the SDK's `async_create_and_deliver_card` shape but exposes
+        the dynamic-data-source config slot so we can register a pull URL
+        for variable-length button lists.
+        """
+        if not await self.check_access_token():
+            await self.get_access_token()
+
+        cardData: dict = {'cardParamMap': _stringify_card_param_map(card_param_map)}
+        if card_data_config is not None:
+            cardData['config'] = json.dumps(card_data_config)
+
+        body: dict = {
+            'cardTemplateId': card_template_id,
+            'outTrackId': out_track_id,
+            'cardData': cardData,
+            'callbackType': callback_type,
+            'openSpaceId': open_space_id,
+            'imGroupOpenSpaceModel': {'supportForward': support_forward},
+            'imRobotOpenSpaceModel': {'supportForward': support_forward},
+        }
+        if callback_type == 'HTTP' and callback_route_key:
+            body['callbackRouteKey'] = callback_route_key
+
+        if is_group:
+            deliver: dict = {'robotCode': self.robot_code or self.key}
+            if at_user_ids:
+                deliver['atUserIds'] = at_user_ids
+            if recipients is not None:
+                deliver['recipients'] = recipients
+            body['imGroupOpenDeliverModel'] = deliver
+        else:
+            body['imRobotOpenDeliverModel'] = {'spaceType': 'IM_ROBOT'}
+
+        if dynamic_data_source_configs:
+            body['openDynamicDataConfig'] = {'dynamicDataSourceConfigs': dynamic_data_source_configs}
+
+        url = f'{DINGTALK_OPENAPI_BASE}/v1.0/card/instances/createAndDeliver'
+        headers = {
+            'x-acs-dingtalk-access-token': self.access_token,
+            'Content-Type': 'application/json',
+        }
+        try:
+            _stdout_logger.info(
+                'DingTalk createAndDeliver request body: %s',
+                json.dumps(body, ensure_ascii=False)[:1500],
+            )
+            async with httpx.AsyncClient() as client:
+                response = await client.post(url, headers=headers, json=body, timeout=30.0)
+                if response.status_code == 200:
+                    _stdout_logger.info(
+                        'DingTalk createAndDeliver response: %s',
+                        response.text[:500],
+                    )
+                    return True
+                _stdout_logger.error(
+                    'DingTalk createAndDeliver failed: status=%s body=%s',
+                    response.status_code,
+                    response.text,
+                )
+                if self.logger:
+                    await self.logger.error(
+                        f'DingTalk createAndDeliver failed: status={response.status_code} body={response.text}'
+                    )
+                return False
+        except Exception:
+            _stdout_logger.exception('DingTalk createAndDeliver error')
+            if self.logger:
+                await self.logger.error(f'DingTalk createAndDeliver error: {traceback.format_exc()}')
+            return False
+
+    async def streaming_update_card(
+        self,
+        *,
+        out_track_id: str,
+        content_key: str,
+        content_value: str,
+        append: bool,
+        finished: bool,
+        failed: bool = False,
+    ) -> bool:
+        """PUT /v1.0/card/streaming.
+
+        Replaces `dingtalk_stream.AICardReplier.async_streaming` — same body
+        shape (outTrackId / guid / key / content / isFull / isFinalize /
+        isError) per the SDK source.
+        """
+        if not await self.check_access_token():
+            await self.get_access_token()
+
+        body = {
+            'outTrackId': out_track_id,
+            'guid': uuid.uuid4().hex,
+            'key': content_key,
+            'content': content_value,
+            'isFull': not append,
+            'isFinalize': finished,
+            'isError': failed,
+        }
+        url = f'{DINGTALK_OPENAPI_BASE}/v1.0/card/streaming'
+        headers = {
+            'x-acs-dingtalk-access-token': self.access_token,
+            'Content-Type': 'application/json',
+        }
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.put(url, headers=headers, json=body, timeout=30.0)
+                if response.status_code == 200:
+                    return True
+                if self.logger:
+                    await self.logger.error(
+                        f'DingTalk card streaming failed: status={response.status_code} body={response.text}'
+                    )
+                return False
+        except Exception:
+            if self.logger:
+                await self.logger.error(f'DingTalk card streaming error: {traceback.format_exc()}')
+            return False
+
+    async def update_card_data(
+        self,
+        *,
+        out_track_id: str,
+        card_param_map: Optional[dict] = None,
+        private_data: Optional[dict] = None,
+    ) -> bool:
+        """PUT /v1.0/card/instances — non-streaming card content update."""
+        if not await self.check_access_token():
+            await self.get_access_token()
+
+        body: dict = {
+            'outTrackId': out_track_id,
+            'cardData': {'cardParamMap': _stringify_card_param_map(card_param_map)},
+        }
+        if private_data:
+            body['privateData'] = private_data
+
+        url = f'{DINGTALK_OPENAPI_BASE}/v1.0/card/instances'
+        headers = {
+            'x-acs-dingtalk-access-token': self.access_token,
+            'Content-Type': 'application/json',
+        }
+        try:
+            _stdout_logger.info(
+                'DingTalk update_card_data request: out_track_id=%s body=%s',
+                out_track_id,
+                json.dumps(body, ensure_ascii=False)[:1500],
+            )
+            async with httpx.AsyncClient() as client:
+                response = await client.put(url, headers=headers, json=body, timeout=30.0)
+                _stdout_logger.info(
+                    'DingTalk update_card_data response: status=%d body=%s',
+                    response.status_code,
+                    response.text[:300],
+                )
+                if response.status_code == 200:
+                    return True
+                if self.logger:
+                    await self.logger.error(
+                        f'DingTalk update card failed: status={response.status_code} body={response.text}'
+                    )
+                return False
+        except Exception:
+            _stdout_logger.exception('DingTalk update_card_data error')
+            if self.logger:
+                await self.logger.error(f'DingTalk update card error: {traceback.format_exc()}')
+            return False
+
+    async def get_legacy_access_token(self) -> Optional[str]:
+        """Fetch the LEGACY (oapi.dingtalk.com) access_token. This is a
+        different auth domain from the v1.0 token cached in
+        ``self.access_token`` — only the legacy token authorises the
+        ``/media/upload`` endpoint that returns an ``@xxx`` media_id
+        consumable by card components like Avatar.imageUrl.
+
+        Returns the token string on success, None on failure. Caches
+        with a 60s safety margin before the documented 7200s expiry.
+        """
+        now = time.time()
+        if (
+            self.legacy_access_token
+            and self.legacy_access_token_expiry_time
+            and now < self.legacy_access_token_expiry_time
+        ):
+            return self.legacy_access_token
+
+        url = 'https://oapi.dingtalk.com/gettoken'
+        try:
+            async with httpx.AsyncClient() as client:
+                response = await client.get(url, params={'appkey': self.key, 'appsecret': self.secret}, timeout=15.0)
+            data = response.json() if response.status_code == 200 else {}
+            if data.get('errcode') == 0 and data.get('access_token'):
+                self.legacy_access_token = data['access_token']
+                expires_in = int(data.get('expires_in', 7200))
+                self.legacy_access_token_expiry_time = now + expires_in - 60
+                return self.legacy_access_token
+            if self.logger:
+                await self.logger.error(
+                    f'DingTalk legacy gettoken failed: status={response.status_code} body={response.text[:200]}'
+                )
+        except Exception:
+            _stdout_logger.exception('DingTalk legacy gettoken error')
+            if self.logger:
+                await self.logger.error(f'DingTalk legacy gettoken error: {traceback.format_exc()}')
+        return None
+
+    async def upload_image_media(self, file_path: str) -> Optional[str]:
+        """Upload an image file to DingTalk media storage and return the
+        ``@xxx`` media_id, which can be passed straight into card variables
+        like Avatar.imageUrl. Endpoint:
+
+            POST https://oapi.dingtalk.com/media/upload?access_token=…&type=image
+
+        Returns the media_id on success, None on any failure (caller
+        should handle a None gracefully — DingTalk falls back to a
+        default avatar when imageUrl is empty/unknown).
+        """
+        if not os.path.exists(file_path):
+            if self.logger:
+                await self.logger.error(f'DingTalk upload_image_media: file not found {file_path}')
+            return None
+
+        token = await self.get_legacy_access_token()
+        if not token:
+            return None
+
+        url = 'https://oapi.dingtalk.com/media/upload'
+        try:
+            with open(file_path, 'rb') as f:
+                file_bytes = f.read()
+            file_name = os.path.basename(file_path)
+            # Best-effort content-type guess; DingTalk accepts the major image
+            # mime types and otherwise infers from the bytes.
+            ext = os.path.splitext(file_name)[1].lower().lstrip('.')
+            mime = {'png': 'image/png', 'jpg': 'image/jpeg', 'jpeg': 'image/jpeg', 'gif': 'image/gif'}.get(
+                ext, 'application/octet-stream'
+            )
+            async with httpx.AsyncClient() as client:
+                response = await client.post(
+                    url,
+                    params={'access_token': token, 'type': 'image'},
+                    files={'media': (file_name, file_bytes, mime)},
+                    timeout=30.0,
+                )
+            data = response.json() if response.status_code == 200 else {}
+            if data.get('errcode') == 0 and data.get('media_id'):
+                _stdout_logger.info('DingTalk upload_image_media OK: media_id=%s', data['media_id'])
+                return data['media_id']
+            if self.logger:
+                await self.logger.error(
+                    f'DingTalk upload_image_media failed: status={response.status_code} body={response.text[:300]}'
+                )
+        except Exception:
+            _stdout_logger.exception('DingTalk upload_image_media error')
+            if self.logger:
+                await self.logger.error(f'DingTalk upload_image_media error: {traceback.format_exc()}')
+        return None
+
     async def start(self):
         """启动 WebSocket 连接，监听消息"""
         self._stopped = False

src/langbot/libs/dingtalk_api/card_callback.py

@@ -0,0 +1,106 @@
+"""STREAM-mode handler for DingTalk card action button clicks.
+
+DingTalk delivers card-action callbacks over the same WebSocket stream used
+for chatbot messages, under the topic `/v1.0/card/instances/callback`. This
+module subclasses `dingtalk_stream.CallbackHandler` and forwards the parsed
+payload to a coroutine the adapter registers, so the resume-paused-workflow
+logic stays in the platform adapter where it belongs.
+
+The `CardCallbackMessage` returned by `from_dict` exposes:
+
+* `card_instance_id` (from `outTrackId`) — the card whose button was clicked
+* `user_id`  — the clicker's userId
+* `content`  — parsed JSON; the click params live here. Where exactly inside
+               `content` they sit depends on the template binding. We probe
+               the common paths.
+* `extension` — parsed JSON; any extra data we set when delivering the card.
+"""
+
+from __future__ import annotations
+
+from typing import Awaitable, Callable, Optional
+
+import dingtalk_stream  # type: ignore
+from dingtalk_stream import AckMessage
+from dingtalk_stream.card_callback import CardCallbackMessage
+
+
+_PARAM_PATHS = (
+    ('params',),
+    ('cardPrivateData', 'params'),
+    ('userPrivateData', 'params'),
+    ('actionData', 'cardPrivateData', 'params'),
+)
+
+
+def _extract_params(content: dict) -> dict:
+    """Return the action params dict regardless of where the template put it."""
+    for path in _PARAM_PATHS:
+        node = content
+        for key in path:
+            if not isinstance(node, dict):
+                node = None
+                break
+            node = node.get(key)
+            if node is None:
+                break
+        if isinstance(node, dict) and node:
+            return node
+    return {}
+
+
+def _merge_params(*sources: dict) -> dict:
+    merged = {}
+    for source in sources:
+        if isinstance(source, dict):
+            merged.update(source)
+    return merged
+
+
+class DingTalkCardActionHandler(dingtalk_stream.CallbackHandler):
+    def __init__(
+        self,
+        dingtalk_stream_client,
+        on_action: Optional[Callable[[dict], Awaitable[None]]] = None,
+    ):
+        super().__init__()
+        self.dingtalk_client = dingtalk_stream_client
+        self.on_action = on_action
+
+    async def process(self, callback: dingtalk_stream.CallbackMessage):
+        try:
+            message = CardCallbackMessage.from_dict(callback.data)
+            content = message.content if isinstance(message.content, dict) else {}
+
+            # `CardCallbackMessage.from_dict` does not surface `actionId` (the
+            # top-level field that ButtonGroup's sendCardRequest event puts
+            # there). Pull it from the raw callback.data instead.
+            raw = callback.data if isinstance(callback.data, dict) else {}
+            params = _merge_params(_extract_params(content), _extract_params(raw))
+            action_id = raw.get('actionId') or ''
+            if not action_id:
+                # Some templates nest it under actionData / cardPrivateData.
+                action_data = raw.get('actionData') or {}
+                if isinstance(action_data, dict):
+                    action_id = action_data.get('actionId') or action_id
+                    if not action_id:
+                        cpd = action_data.get('cardPrivateData') or {}
+                        if isinstance(cpd, dict):
+                            ids = cpd.get('actionIds')
+                            if isinstance(ids, list) and ids:
+                                action_id = str(ids[0])
+
+            payload = {
+                'out_track_id': message.card_instance_id,
+                'user_id': message.user_id,
+                'corp_id': message.corp_id,
+                'action_id': action_id,
+                'params': params,
+                'raw_content': message.content,
+                'extension': message.extension if isinstance(message.extension, dict) else {},
+            }
+            if self.on_action is not None:
+                await self.on_action(payload)
+        except Exception as e:
+            self.logger.error(f'DingTalkCardActionHandler.process error: {e}')
+        return AckMessage.STATUS_OK, 'OK'

src/langbot/libs/qq_official_api/api.py

@@ -12,6 +12,142 @@ import traceback
 from cryptography.hazmat.primitives.asymmetric import ed25519
 
 
+QQ_SELECT_ACTION_PREFIX = '__langbot_select__:'
+
+
+def get_select_field_options(form_data: dict) -> tuple[str, list[str]]:
+    """Return the active select field name and its display/submission values."""
+    field_name = str(form_data.get('_current_input_field') or '').strip()
+    if not field_name:
+        return '', []
+
+    field = next(
+        (
+            item
+            for item in form_data.get('input_defs') or []
+            if str(item.get('output_variable_name') or '').strip() == field_name
+        ),
+        None,
+    )
+    if not field or str(field.get('type') or '').strip().lower() != 'select':
+        return '', []
+
+    source = field.get('option_source') or {}
+    source_value = source.get('value') if isinstance(source, dict) else None
+    if isinstance(source_value, list):
+        return field_name, [str(item) for item in source_value]
+    if isinstance(source_value, str):
+        return field_name, [part.strip() for part in source_value.splitlines() if part.strip()]
+
+    options = field.get('options')
+    if not isinstance(options, list):
+        return field_name, []
+    values = []
+    for item in options:
+        if isinstance(item, dict):
+            values.append(str(item.get('label') or item.get('value') or ''))
+        else:
+            values.append(str(item))
+    return field_name, [value for value in values if value]
+
+
+def build_keyboard_from_select_field(form_data: dict, *, buttons_per_row: int | None = None) -> dict:
+    """Build callback buttons for the currently active Dify select field."""
+    _, options = get_select_field_options(form_data)
+    visible_options = options[:25]
+    if buttons_per_row is None:
+        # Keep small choices readable while fitting up to QQ's 5x5 limit.
+        buttons_per_row = min(5, max(2, (len(visible_options) + 4) // 5))
+    selection_actions = [
+        {
+            'id': f'{QQ_SELECT_ACTION_PREFIX}{idx}',
+            'title': option,
+            'button_style': 'secondary',
+        }
+        for idx, option in enumerate(visible_options)
+    ]
+    return build_keyboard_from_form({'actions': selection_actions}, buttons_per_row=buttons_per_row)
+
+
+def resolve_select_button_action(form_data: dict, action_id: str) -> tuple[str, str] | None:
+    """Resolve a select-button callback to ``(field_name, option_value)``."""
+    if not action_id.startswith(QQ_SELECT_ACTION_PREFIX):
+        return None
+    try:
+        option_index = int(action_id[len(QQ_SELECT_ACTION_PREFIX) :])
+    except ValueError:
+        return None
+
+    field_name, options = get_select_field_options(form_data)
+    if not field_name or option_index < 0 or option_index >= len(options) or option_index >= 25:
+        return None
+    return field_name, options[option_index]
+
+
+def build_keyboard_from_form(form_data: dict, *, buttons_per_row: int = 2) -> dict:
+    """Build a QQ keyboard JSON payload from a Dify human-input form_data.
+
+    Each Dify ``action`` becomes a callback button (``action.type=1``)
+    whose ``data`` is set directly to the Dify ``action_id``. The
+    INTERACTION_CREATE event carries this back as
+    ``data.resolved.button_data`` so the adapter can match the click to
+    the originating form.
+
+    Layout limits per spec: max 5 rows, max 5 buttons per row. We default
+    to 2 buttons per row for legibility; oversized button lists wrap
+    onto additional rows and overflow gets dropped (max 25 visible).
+
+    Args:
+        form_data: Dify ``{"actions": [{"id", "title", "button_style"}, ...]}``.
+        buttons_per_row: 1..5. Mobile UI looks best at 2.
+
+    Returns:
+        ``{"content": {"rows": [{"buttons": [...]}]}}``.
+    """
+    actions = list(form_data.get('actions') or [])[:25]  # 5×5 hard cap
+    buttons_per_row = max(1, min(5, buttons_per_row))
+
+    def _button(idx: int, action: dict) -> dict:
+        action_id = str(action.get('id') or '')
+        label = str(action.get('title') or action_id or f'选项 {idx + 1}')
+        style_raw = (action.get('button_style') or '').lower()
+        # QQ: 0 灰色线框, 1 蓝色线框. Highlight the primary / first action.
+        if style_raw == 'primary' or (style_raw == '' and idx == 0):
+            style = 1
+        else:
+            style = 0
+        return {
+            'id': str(idx + 1),
+            'render_data': {
+                'label': label,
+                # Shown after the user clicks — gives local "已选择" feedback
+                # without a follow-up message. Style mimics DingTalk/Lark's
+                # in-card selection state.
+                'visited_label': f'✓ {label}',
+                'style': style,
+            },
+            'action': {
+                'type': 1,  # callback button
+                'permission': {'type': 2},  # everyone can click
+                'data': action_id,
+                'unsupport_tips': '当前客户端版本不支持此按钮，请升级 QQ',
+            },
+        }
+
+    rows = []
+    for row_start in range(0, len(actions), buttons_per_row):
+        row_actions = actions[row_start : row_start + buttons_per_row]
+        rows.append(
+            {
+                'buttons': [_button(row_start + j, a) for j, a in enumerate(row_actions)],
+            }
+        )
+        if len(rows) >= 5:
+            break
+
+    return {'content': {'rows': rows}}
+
+
 class QQOfficialClient:
     def __init__(self, secret: str, token: str, app_id: str, logger: None, unified_mode: bool = False):
         self.unified_mode = unified_mode
@@ -30,6 +166,10 @@ class QQOfficialClient:
         self.token = token
         self.app_id = app_id
         self._message_handlers = {}
+        # Single optional handler for INTERACTION_CREATE (button click). We
+        # don't multiplex like message handlers — only the adapter cares,
+        # and the click<->resume path needs a single source of truth.
+        self._interaction_handler: Optional[Callable[[Dict[str, Any], Optional[str]], Any]] = None
         self.base_url = 'https://api.sgroup.qq.com'
         self.access_token = ''
         self.access_token_expiry_time = None
@@ -107,6 +247,23 @@ class QQOfficialClient:
                 return response, 200
 
             if payload.get('op') == 0:
+                # INTERACTION_CREATE (button click) skips ``get_message`` —
+                # that helper only flattens message-event fields and would
+                # drop ``data.resolved.button_data`` / ``data.button_id``.
+                if payload.get('t') == 'INTERACTION_CREATE':
+                    if self._interaction_handler:
+                        try:
+                            d = payload.get('d') or {}
+                            # Top-level ``id`` is the ws/event id used as
+                            # ``event_id`` for passive replies. ``d.id``
+                            # is the interaction id used for ACK. Do not
+                            # confuse the two — QQ rejects misuse with
+                            # 40034025.
+                            ws_event_id = payload.get('id')
+                            await self._interaction_handler(d, ws_event_id)
+                        except Exception:
+                            await self.logger.error(f'Error in interaction handler: {traceback.format_exc()}')
+                    return {'code': 0, 'message': 'success'}
                 message_data = await self.get_message(payload)
                 if message_data:
                     event = QQOfficialEvent.from_payload(message_data)
@@ -133,6 +290,21 @@ class QQOfficialClient:
 
         return decorator
 
+    def on_interaction(self):
+        """Register a single handler for INTERACTION_CREATE events.
+
+        The handler receives ``(data_dict, interaction_id)`` — the raw
+        ``d`` payload plus the top-level ``id`` field (the interaction
+        id, needed for the PUT /interactions/{id} ack and for reuse as
+        an ``event_id`` on the resumed reply within 30 minutes).
+        """
+
+        def decorator(func: Callable[[Dict[str, Any], Optional[str]], Any]):
+            self._interaction_handler = func
+            return func
+
+        return decorator
+
     async def _handle_message(self, event: QQOfficialEvent):
         """处理消息事件"""
         msg_type = event.t
@@ -177,8 +349,20 @@ class QQOfficialClient:
         content_type = attachment.get('content_type', '')
         return content_type.startswith('image/')
 
-    async def send_private_text_msg(self, user_openid: str, content: str, msg_id: str):
-        """发送私聊消息"""
+    async def send_private_text_msg(
+        self,
+        user_openid: str,
+        content: str,
+        msg_id: Optional[str] = None,
+        event_id: Optional[str] = None,
+        msg_seq: int = 1,
+    ):
+        """Send a c2c text message.
+
+        Either ``msg_id`` (inbound user msg, free passive reply) or
+        ``event_id`` (e.g. INTERACTION_CREATE id, valid 30 min) is
+        required. Without either, the call costs the proactive-send quota.
+        """
         if not await self.check_access_token():
             await self.get_access_token()
 
@@ -188,11 +372,15 @@ class QQOfficialClient:
                 'Authorization': f'QQBot {self.access_token}',
                 'Content-Type': 'application/json',
             }
-            data = {
+            data: dict[str, Any] = {
                 'content': content,
                 'msg_type': 0,
-                'msg_id': msg_id,
+                'msg_seq': msg_seq,
             }
+            if msg_id:
+                data['msg_id'] = msg_id
+            if event_id:
+                data['event_id'] = event_id
             response = await client.post(url, headers=headers, json=data)
             response_data = response.json()
             if response.status_code == 200:
@@ -201,8 +389,19 @@ class QQOfficialClient:
                 await self.logger.error(f'Failed to send private message: {response_data}')
                 raise ValueError(response)
 
-    async def send_group_text_msg(self, group_openid: str, content: str, msg_id: str):
-        """发送群聊消息"""
+    async def send_group_text_msg(
+        self,
+        group_openid: str,
+        content: str,
+        msg_id: Optional[str] = None,
+        event_id: Optional[str] = None,
+        msg_seq: int = 1,
+    ):
+        """Send a group text message.
+
+        Either ``msg_id`` or ``event_id`` is required (see
+        :meth:`send_private_text_msg` for the distinction).
+        """
         if not await self.check_access_token():
             await self.get_access_token()
 
@@ -212,11 +411,15 @@ class QQOfficialClient:
                 'Authorization': f'QQBot {self.access_token}',
                 'Content-Type': 'application/json',
             }
-            data = {
+            data: dict[str, Any] = {
                 'content': content,
                 'msg_type': 0,
-                'msg_id': msg_id,
+                'msg_seq': msg_seq,
             }
+            if msg_id:
+                data['msg_id'] = msg_id
+            if event_id:
+                data['event_id'] = event_id
             response = await client.post(url, headers=headers, json=data)
             if response.status_code == 200:
                 return
@@ -485,6 +688,107 @@ class QQOfficialClient:
                 raise Exception(f'Failed to send stream message: HTTP {response.status_code} {response.text}')
             return response.json()
 
+    async def send_markdown_keyboard(
+        self,
+        target_type: str,
+        target_id: str,
+        markdown_content: str,
+        keyboard: Optional[dict] = None,
+        msg_id: Optional[str] = None,
+        event_id: Optional[str] = None,
+        msg_seq: int = 1,
+    ) -> dict:
+        """Send a ``msg_type=2`` (markdown) message carrying a keyboard.
+
+        The keyboard ride-along is the only documented way to attach
+        buttons in QQ official; pure keyboard-only messages are not
+        accepted by the server (markdown content is required).
+
+        Args:
+            target_type: 'c2c' (single chat), 'group', 'channel' (text
+                channel — uses POST /channels/{id}/messages instead of v2).
+            target_id: openid for c2c/group, channel_id for channel.
+            markdown_content: Plain markdown text shown above the buttons.
+            keyboard: ``{'content': {'rows': [{'buttons': [...]}]}}`` per
+                the official spec. Use :func:`build_keyboard_from_form`
+                to construct from Dify form_data.
+            msg_id: Inbound user message id; turns this into a passive
+                reply (preferred — no monthly quota cost).
+            event_id: Use ``INTERACTION_CREATE`` event id from a prior
+                button click to keep within the 30-minute passive window
+                without an inbound msg_id.
+            msg_seq: De-dup counter when reusing msg_id.
+        """
+        if not await self.check_access_token():
+            await self.get_access_token()
+
+        if target_type == 'c2c':
+            url = f'{self.base_url}/v2/users/{target_id}/messages'
+        elif target_type == 'group':
+            url = f'{self.base_url}/v2/groups/{target_id}/messages'
+        elif target_type == 'channel':
+            url = f'{self.base_url}/channels/{target_id}/messages'
+        else:
+            raise ValueError(f'Unsupported target_type for markdown+keyboard: {target_type}')
+
+        body: dict[str, Any] = {
+            'msg_type': 2,
+            'markdown': {'content': markdown_content},
+            'msg_seq': msg_seq,
+        }
+        if keyboard and keyboard.get('content', {}).get('rows'):
+            body['keyboard'] = keyboard
+        if msg_id:
+            body['msg_id'] = msg_id
+        if event_id:
+            body['event_id'] = event_id
+
+        async with httpx.AsyncClient(timeout=30) as client:
+            headers = {
+                'Authorization': f'QQBot {self.access_token}',
+                'Content-Type': 'application/json',
+            }
+            response = await client.post(url, headers=headers, json=body)
+            if response.status_code != 200:
+                await self.logger.error(
+                    f'Failed to send markdown+keyboard: HTTP {response.status_code} {response.text}'
+                )
+                raise Exception(f'Failed to send markdown+keyboard: HTTP {response.status_code} {response.text}')
+            return response.json()
+
+    async def ack_interaction(self, interaction_id: str, code: int = 0) -> None:
+        """Acknowledge a button-click INTERACTION_CREATE event.
+
+        QQ keeps the client in a loading spinner until this ack is
+        received. Should be called as soon as the click is parsed, before
+        any heavier downstream work (the actual workflow resume can run
+        async).
+
+        Args:
+            interaction_id: The ``id`` field from the INTERACTION_CREATE event.
+            code: 0=success, 1=fail, 2=rate-limited, 3=duplicate, 4=no
+                permission, 5=admin only. Default 0.
+        """
+        if not interaction_id:
+            return
+        if not await self.check_access_token():
+            await self.get_access_token()
+
+        url = f'{self.base_url}/interactions/{interaction_id}'
+        async with httpx.AsyncClient(timeout=10) as client:
+            headers = {
+                'Authorization': f'QQBot {self.access_token}',
+                'Content-Type': 'application/json',
+            }
+            try:
+                response = await client.put(url, headers=headers, json={'code': code})
+                if response.status_code >= 400:
+                    await self.logger.warning(
+                        f'ack_interaction non-success: HTTP {response.status_code} {response.text}'
+                    )
+            except Exception as e:
+                await self.logger.warning(f'ack_interaction error (non-fatal): {e}')
+
     async def is_token_expired(self):
         """检查token是否过期"""
         if self.access_token_expiry_time is None:
@@ -653,6 +957,12 @@ class QQOfficialClient:
                     d = payload.get('d', {})
                     s = payload.get('s')
                     t = payload.get('t')
+                    # Top-level event id, distinct from `d.id`. Per QQ
+                    # spec this is the only value accepted as ``event_id``
+                    # in subsequent passive-reply send-message calls
+                    # (``d.id`` for INTERACTION_CREATE is the interaction
+                    # id, used solely for PUT /interactions/{id} ack).
+                    ws_event_id = payload.get('id')
 
                     if not isinstance(d, dict):
                         d = {}
@@ -731,7 +1041,22 @@ class QQOfficialClient:
 
                         else:
                             await self.logger.debug(f'Received event: {t}, seq={s}')
-                            if on_event:
+                            # INTERACTION_CREATE bypasses the regular
+                            # on_event dispatcher so the adapter sees the
+                            # top-level ws_event_id (needed as event_id
+                            # for the resumed reply) — same shape as the
+                            # webhook handler.
+                            if t == 'INTERACTION_CREATE':
+                                if self._interaction_handler:
+                                    try:
+                                        result = self._interaction_handler(d, ws_event_id)
+                                        if asyncio.iscoroutine(result):
+                                            await result
+                                    except Exception:
+                                        await self.logger.error(
+                                            f'Error in interaction handler (ws): {traceback.format_exc()}'
+                                        )
+                            elif on_event:
                                 try:
                                     result = on_event(t, d)
                                     if asyncio.iscoroutine(result):

src/langbot/libs/wecom_ai_bot_api/ws_client.py

@@ -20,7 +20,19 @@ from typing import Any, Callable, Optional
 import aiohttp
 
 from langbot.libs.wecom_ai_bot_api import wecombotevent
-from langbot.libs.wecom_ai_bot_api.api import parse_wecom_bot_message, StreamSession
+from langbot.libs.wecom_ai_bot_api.api import (
+    parse_wecom_bot_message,
+    StreamSession,
+    build_human_input_template_card_payload,
+    build_human_input_text_prompt,
+    build_button_interaction_update_card,
+    build_multiple_interaction_update_card,
+    extract_template_card_action,
+    extract_template_card_event_payload,
+    extract_template_card_selections,
+    extract_wecom_event_type,
+    parse_select_button_action,
+)
 from langbot.pkg.platform.logger import EventLogger
 
 DEFAULT_WS_URL = 'wss://openws.work.weixin.qq.com'
@@ -43,6 +55,10 @@ def _generate_req_id(prefix: str) -> str:
     return f'{prefix}_{ts}_{rand}'
 
 
+def _frame_snippet(frame: dict, limit: int = 1000) -> str:
+    return json.dumps(frame, ensure_ascii=False, default=str)[:limit]
+
+
 class WecomBotWsClient:
     """WeChat Work AI Bot WebSocket long connection client.
 
@@ -103,6 +119,22 @@ class WecomBotWsClient:
         # msg_id -> feedback_id (for associating feedback with message)
         self._msg_feedback_ids: dict[str, str] = {}  # msg_id -> feedback_id
 
+        # Dify human-input pause state for ws mode. Keys are task_id (echoed
+        # back in template_card_event.TaskId so we can rebuild the session
+        # context on click).
+        # task_id -> {form_data, msg_id, user_id, chat_id, stream_id, req_id}
+        self._pending_forms_by_task: dict[str, dict] = {}
+        # Reverse: msg_id -> task_id (for cleanup when stream finishes).
+        self._task_id_by_msg: dict[str, str] = {}
+        # Optional card-action callback registered by the adapter.
+        # Signature mirrors the http-mode WecomBotClient:
+        #   async def callback(session, action_id, task_id, raw_event) -> None
+        self._card_action_callback: Optional[Callable] = None
+        # Optional `source` block injected into every interactive
+        # template_card the client builds via `push_form_pause`. Set via
+        # `set_card_source` from the adapter after reading config.
+        self.card_source: Optional[dict] = None
+
     # ── Public API ──────────────────────────────────────────────────
 
     async def connect(self):
@@ -236,6 +268,132 @@ class WecomBotWsClient:
         }
         return await self._send_reply(req_id, body)
 
+    async def reply_template_card(self, req_id: str, card_payload: dict[str, Any]) -> Optional[dict]:
+        """Send a template_card (button_interaction etc.) reply.
+
+        Args:
+            req_id: The req_id from the original message frame.
+            card_payload: Body produced by ``build_button_interaction_payload``;
+                must contain ``msgtype`` and ``template_card`` keys.
+
+        Returns:
+            ACK frame dict, or None on failure.
+        """
+        return await self._send_reply(req_id, card_payload)
+
+    async def update_template_card(
+        self,
+        req_id: str,
+        template_card: dict[str, Any],
+    ) -> Optional[dict]:
+        """Update an existing template_card via WebSocket.
+
+        Uses the ``aibot_respond_update_msg`` command.  Must be called
+        within 5 seconds of receiving the ``template_card_event`` callback,
+        using the **same req_id** from that callback.
+
+        The ``template_card`` dict should contain ``card_type`` and the
+        new content fields (e.g. ``main_title``, ``button_list`` with
+        disabled buttons and ``replace_text``).
+
+        Returns:
+            ACK frame dict, or None on failure.
+        """
+        body: dict[str, Any] = {
+            'response_type': 'update_template_card',
+            'template_card': template_card,
+        }
+        return await self._send_reply(req_id, body, cmd=CMD_RESPOND_UPDATE)
+
+    def set_card_action_callback(self, callback: Callable) -> None:
+        """Register the button-click handler.
+
+        ``async def callback(session, action_id, task_id, raw_event) -> None``
+        — same signature as the http-mode WecomBotClient version so the
+        adapter can hand both off to the same coroutine.
+        """
+        self._card_action_callback = callback
+
+    def set_card_source(self, source: Optional[dict]) -> None:
+        """Set the `source` block injected into every interactive
+        template_card pushed via `push_form_pause`. Pass None to clear."""
+        self.card_source = source
+
+    async def push_form_pause(
+        self, msg_id: str, form_data: dict, task_id: Optional[str] = None
+    ) -> tuple[bool, Optional[str], Optional[str]]:
+        """Attach a Dify human-input pause to the active stream and send
+        the button_interaction card immediately.
+
+        ws mode has no notion of polled "followup" responses — each reply
+        is a one-shot frame send. So unlike the http path (which defers
+        card delivery to the next followup), here we just craft the card
+        and reply with it on the original req_id. The corresponding stream
+        session is then torn down so subsequent chunks don't re-send.
+
+        Returns:
+            ``(ok, stream_id, task_id)``. ``ok=False`` if no active stream
+            for this msg_id (e.g. message arrived in non-stream mode).
+        """
+        key = self._stream_ids.get(msg_id)
+        if not key:
+            return False, None, None
+        req_id, stream_id = key.split('|', 1)
+
+        if not task_id:
+            task_id = f'dify-{secrets.token_hex(12)}'
+
+        session_info = self._stream_sessions.get(msg_id) or {}
+        text_prompt = build_human_input_text_prompt(form_data)
+        if text_prompt:
+            try:
+                ack = await self.reply_text(req_id, text_prompt)
+                if ack is None:
+                    return False, stream_id, None
+            except Exception:
+                await self.logger.error(f'Failed to send human-input text prompt: {traceback.format_exc()}')
+                return False, stream_id, None
+
+            self._stream_ids.pop(msg_id, None)
+            self._stream_last_content.pop(msg_id, None)
+            self._stream_sessions.pop(msg_id, None)
+            return True, stream_id, None
+
+        self._pending_forms_by_task[task_id] = {
+            'form_data': form_data,
+            'msg_id': msg_id,
+            'user_id': session_info.get('user_id', ''),
+            'chat_id': session_info.get('chat_id', ''),
+            'stream_id': stream_id,
+            'req_id': req_id,
+        }
+        self._task_id_by_msg[msg_id] = task_id
+
+        card_payload = build_human_input_template_card_payload(
+            form_data,
+            task_id,
+            source=self.card_source,
+            select_as_buttons=True,
+        )
+        try:
+            await self.reply_template_card(req_id, card_payload)
+        except Exception:
+            await self.logger.error(f'Failed to send button_interaction card: {traceback.format_exc()}')
+            # Roll back the bookkeeping so the next attempt isn't blocked.
+            self._pending_forms_by_task.pop(task_id, None)
+            self._task_id_by_msg.pop(msg_id, None)
+            return False, stream_id, None
+
+        # Tear down the stream — WeCom expects either stream chunks OR a
+        # template_card, not both on the same req_id. Subsequent
+        # push_stream_chunk calls for this msg_id become no-ops.
+        self._stream_ids.pop(msg_id, None)
+        self._stream_last_content.pop(msg_id, None)
+        # Keep _stream_sessions so the button callback can still resolve
+        # user/chat context; it gets cleaned up when the click fires.
+
+        return True, stream_id, task_id
+
     async def send_message(self, chat_id: str, content: str, msgtype: str = 'markdown') -> Optional[dict]:
         """Proactively send a message to a specified chat.
 
@@ -258,6 +416,23 @@ class WecomBotWsClient:
             body['text'] = {'content': content}
         return await self._send_reply(req_id, body, cmd=CMD_SEND_MSG)
 
+    async def send_template_card(self, chat_id: str, card_payload: dict[str, Any]) -> Optional[dict]:
+        """Proactively push a template_card to a chat.
+
+        Used for the resumed-workflow path (button click → new query):
+        synthetic events have no inbound req_id to reply against, so we
+        fall back to proactive ``aibot_send_msg`` instead of reply mode.
+
+        Args:
+            chat_id: userid (single chat) or chatid (group chat).
+            card_payload: ``{"msgtype": "template_card", "template_card": {...}}``
+                as produced by :func:`build_button_interaction_payload`.
+        """
+        req_id = _generate_req_id(CMD_SEND_MSG)
+        body = dict(card_payload)
+        body['chatid'] = chat_id
+        return await self._send_reply(req_id, body, cmd=CMD_SEND_MSG)
+
     async def push_stream_chunk(self, msg_id: str, content: str, is_final: bool = False) -> bool:
         """Push a streaming chunk for a given message ID.
 
@@ -276,10 +451,31 @@ class WecomBotWsClient:
             return False
         req_id, stream_id = key.split('|', 1)
         try:
+            previous_content = self._stream_last_content.get(msg_id, '')
+            if previous_content and content.startswith(previous_content):
+                next_content = content
+            elif previous_content and not content:
+                next_content = previous_content
+            else:
+                next_content = previous_content + content if previous_content else content
+
             # Skip sending if content hasn't changed (e.g. during tool call argument streaming)
-            if not is_final and content == self._stream_last_content.get(msg_id):
+            if not is_final and next_content == previous_content:
                 return True
 
+            # Skip empty/whitespace-only snapshots — the runner injects a
+            # zero-width space ('​') as a pass-through when workflow_paused
+            # fires without any preceding LLM output.  WeCom renders that
+            # as an empty bubble that sits before the form card; skip it.
+            # NOTE: Python str.strip() does NOT strip ​, so we use
+            # a regex that treats any character with Unicode category Zs
+            # (separator space) or Cf (format char like ZWS) as blank.
+            if not is_final:
+                import re as _re
+
+                if not _re.sub(r'[\s​‌‍]', '', next_content):
+                    return True
+
             # Generate feedback_id for final chunk
             feedback_id = ''
             if is_final:
@@ -290,8 +486,10 @@ class WecomBotWsClient:
                 if session_info:
                     self._feedback_sessions[feedback_id] = session_info
 
-            await self.reply_stream(req_id, stream_id, content, finish=is_final, feedback_id=feedback_id)
-            self._stream_last_content[msg_id] = content
+            # WeCom replaces the displayed stream content on each refresh, so
+            # every frame must contain the complete snapshot, not only a delta.
+            await self.reply_stream(req_id, stream_id, next_content, finish=is_final, feedback_id=feedback_id)
+            self._stream_last_content[msg_id] = next_content
             if is_final:
                 self._stream_ids.pop(msg_id, None)
                 self._stream_last_content.pop(msg_id, None)
@@ -465,7 +663,7 @@ class WecomBotWsClient:
             return
 
         # Unknown frame
-        await self.logger.warning(f'Unknown frame: {json.dumps(frame, ensure_ascii=False)[:200]}')
+        await self.logger.warning(f'Unknown frame: {_frame_snippet(frame)}')
 
     async def _handle_message_callback(self, frame: dict):
         """Handle an incoming message callback frame."""
@@ -473,6 +671,13 @@ class WecomBotWsClient:
             body = frame.get('body', {})
             req_id = frame.get('headers', {}).get('req_id', '')
 
+            event_type = extract_wecom_event_type(body)
+            if event_type == 'template_card_event':
+                await self._handle_template_card_event_frame(frame, body)
+                return
+            if event_type:
+                await self.logger.debug(f'Received msg_callback event_type={event_type}: {_frame_snippet(frame)}')
+
             # Parse message using shared logic
             message_data = await parse_wecom_bot_message(body, self.encoding_aes_key, self.logger)
             if not message_data:
@@ -506,8 +711,12 @@ class WecomBotWsClient:
             body = frame.get('body', {})
             req_id = frame.get('headers', {}).get('req_id', '')
 
-            event_info = body.get('event', {})
-            event_type = event_info.get('eventtype', '')
+            event_info = body.get('event', {}) if isinstance(body.get('event'), dict) else body
+            event_type = extract_wecom_event_type(body)
+            if not event_type:
+                await self.logger.warning(f'Received event_callback without event_type: {_frame_snippet(frame)}')
+            else:
+                await self.logger.debug(f'Received event_callback event_type={event_type}')
 
             message_data = {
                 'msgtype': 'event',
@@ -568,6 +777,10 @@ class WecomBotWsClient:
                         await self.logger.error(f'Error in feedback handler: {traceback.format_exc()}')
                 return
 
+            if event_type == 'template_card_event':
+                await self._handle_template_card_event_frame(frame, body)
+                return
+
             event = wecombotevent.WecomBotEvent(message_data)
 
             if event_type in self._message_handlers:
@@ -581,6 +794,72 @@ class WecomBotWsClient:
         except Exception:
             await self.logger.error(f'Error in event callback: {traceback.format_exc()}')
 
+    async def _handle_template_card_event_frame(self, frame: dict, body: dict):
+        """Handle template_card_event frames from event_callback or msg_callback."""
+        tce = extract_template_card_event_payload(body)
+        task_id, event_key, card_type = extract_template_card_action(tce)
+        await self.logger.info(
+            f'Received template_card_event (ws): task_id={task_id} event_key={event_key!r} card_type={card_type}'
+        )
+
+        pending = self._pending_forms_by_task.get(task_id)
+        if pending is None:
+            await self.logger.warning(f'No pending_form found for task_id={task_id} (ws); card event ignored')
+            return
+
+        req_id_for_update = frame.get('headers', {}).get('req_id', '')
+        form_data = pending.get('form_data', {}) or {}
+        selections = extract_template_card_selections(tce, form_data)
+        if not selections:
+            selections = parse_select_button_action(event_key, form_data)
+        if card_type == 'multiple_interaction' and not selections:
+            await self.logger.warning(
+                f'multiple_interaction callback has no parseable selections (ws): raw={str(tce)[:1000]}'
+            )
+            self._drop_pending_form_task(task_id, pending)
+            return
+
+        update_card = build_button_interaction_update_card(
+            form_data,
+            task_id,
+            event_key,
+            source=self.card_source,
+        )
+        if card_type == 'multiple_interaction' or selections:
+            update_card = build_multiple_interaction_update_card(
+                form_data,
+                task_id,
+                selections,
+                source=self.card_source,
+            )
+        try:
+            await self.update_template_card(req_id_for_update, update_card)
+        except Exception:
+            await self.logger.warning(f'Failed to update template card (ws): {traceback.format_exc()}')
+
+        if self._card_action_callback is not None:
+            try:
+                session = StreamSession(
+                    stream_id=pending.get('stream_id', ''),
+                    msg_id=pending.get('msg_id', ''),
+                    chat_id=pending.get('chat_id') or None,
+                    user_id=pending.get('user_id') or None,
+                )
+                session.pending_form = pending.get('form_data')
+                session.pending_form_task_id = task_id
+                await self._card_action_callback(session, event_key, task_id, body)
+            except Exception:
+                await self.logger.error(f'card action callback raised (ws): {traceback.format_exc()}')
+
+        self._drop_pending_form_task(task_id, pending)
+
+    def _drop_pending_form_task(self, task_id: str, pending: dict) -> None:
+        self._pending_forms_by_task.pop(task_id, None)
+        msg_id = pending.get('msg_id', '')
+        if msg_id:
+            self._task_id_by_msg.pop(msg_id, None)
+            self._stream_sessions.pop(msg_id, None)
+
     async def _dispatch_event(self, event: wecombotevent.WecomBotEvent):
         """Dispatch a message event to registered handlers with deduplication."""
         try:

src/langbot/pkg/api/http/controller/groups/platform/adapters.py

@@ -5,6 +5,29 @@ from ... import group
 from langbot.pkg.utils import importutil
 
 
+def _decrypt_qqofficial_secret(encrypted_b64: str, key: bytes) -> str:
+    """Decrypt the AppSecret returned by the QQ Official QR binding endpoint.
+
+    The base64 payload is laid out as `nonce (12 B) | ciphertext | tag (16 B)`.
+    `key` is the 32-byte AES-256 key locally generated when the bind task
+    was created and submitted as `key` to `q.qq.com/lite/create_bind_task`.
+    """
+    import base64
+    from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+
+    try:
+        raw = base64.b64decode(encrypted_b64)
+    except Exception as exc:
+        raise ValueError('Malformed encrypted credential') from exc
+    if len(key) != 32 or len(raw) <= 28:
+        raise ValueError('Invalid encrypted credential layout')
+    nonce, ciphertext, tag = raw[:12], raw[12:-16], raw[-16:]
+    try:
+        return AESGCM(key).decrypt(nonce, ciphertext + tag, None).decode('utf-8')
+    except Exception as exc:
+        raise ValueError('Failed to decrypt credential') from exc
+
+
 @group.group_class('adapters', '/api/v1/platform/adapters')
 class AdaptersRouterGroup(group.RouterGroup):
     async def initialize(self) -> None:
@@ -37,6 +60,15 @@ class AdaptersRouterGroup(group.RouterGroup):
                 importutil.read_resource_file_bytes(icon_path), mimetype=mimetypes.guess_type(icon_path)[0]
             )
 
+        @self.route('/dingtalk/human-input-card-template', methods=['GET'], auth_type=group.AuthType.NONE)
+        async def _() -> quart.Response:
+            filename = 'dingtalk_human_input_card.json'
+            response = quart.Response(
+                importutil.read_resource_file_bytes(f'templates/{filename}'), mimetype='application/json'
+            )
+            response.headers['Content-Disposition'] = f'attachment; filename={filename}'
+            return response
+
         # In-memory session store for active registrations
         _create_app_sessions: dict = {}
         _SESSION_TTL = 900  # 15 minutes
@@ -650,3 +682,220 @@ class AdaptersRouterGroup(group.RouterGroup):
             if session and session.get('task') and not session['task'].done():
                 session['task'].cancel()
             return self.success(data={})
+
+        # -----------------------------------------------------------------------
+        # QQ Official QR Binding
+        # -----------------------------------------------------------------------
+
+        _qqofficial_sessions: dict = {}
+        _QQOFFICIAL_SESSION_TTL = 300  # 5 minutes (QQ bind QR validity window)
+
+        def _cleanup_expired_qqofficial_sessions():
+            import time
+
+            now = time.time()
+            expired = [
+                sid for sid, s in _qqofficial_sessions.items() if now - s.get('created_at', 0) > _QQOFFICIAL_SESSION_TTL
+            ]
+            for sid in expired:
+                session = _qqofficial_sessions.pop(sid, None)
+                if session and session.get('task') and not session['task'].done():
+                    session['task'].cancel()
+
+        @self.route('/qqofficial/bind', methods=['POST'])
+        async def _() -> str:
+            """Start QQ Official QR binding. Returns session_id + QR URL.
+
+            Flow: generate a local AES-256 key, register it with
+            `q.qq.com/lite/create_bind_task`, then poll
+            `q.qq.com/lite/poll_bind_result` until the user authorizes the
+            bind inside the QQ Bot Assistant on mobile QQ. The encrypted
+            AppSecret returned by the poll endpoint is decrypted with the
+            same key. The key never leaves this process.
+            """
+            import uuid
+            import time
+            import secrets
+            import base64
+            import aiohttp
+
+            QQ_BIND_BASE = 'https://q.qq.com'
+            _cleanup_expired_qqofficial_sessions()
+
+            bind_key_bytes = secrets.token_bytes(32)
+            bind_key = base64.b64encode(bind_key_bytes).decode('ascii')
+
+            session_id = str(uuid.uuid4())
+            session = {
+                'status': 'pending',
+                'qr_url': None,
+                'expire_at': None,
+                'appid': None,
+                'secret': None,
+                'user_openid': None,
+                'error': None,
+                'created_at': time.time(),
+                'task_id': None,
+                'bind_key_bytes': bind_key_bytes,
+                'interval': 2,
+            }
+            _qqofficial_sessions[session_id] = session
+
+            async def run_qr_binding():
+                try:
+                    timeout = aiohttp.ClientTimeout(total=10)
+                    async with aiohttp.ClientSession(timeout=timeout) as http:
+                        # Step 1: create_bind_task — register our AES key, get task_id
+                        async with http.post(
+                            f'{QQ_BIND_BASE}/lite/create_bind_task',
+                            json={'key': bind_key},
+                            headers={'Accept': 'application/json'},
+                        ) as resp:
+                            try:
+                                data = await resp.json(content_type=None)
+                            except (aiohttp.ContentTypeError, ValueError):
+                                session['status'] = 'error'
+                                session['error'] = 'Invalid response from QQ bind service'
+                                return
+                            if int(data.get('retcode', -1)) != 0:
+                                session['status'] = 'error'
+                                session['error'] = (
+                                    data.get('msg') or data.get('message') or 'Failed to create bind task'
+                                )
+                                return
+                            task_id = str((data.get('data') or {}).get('task_id') or '').strip()
+                            if not task_id:
+                                session['status'] = 'error'
+                                session['error'] = 'Missing task_id in QQ response'
+                                return
+
+                        # The QR encodes a URL that mobile QQ opens inside the QQ Bot Assistant.
+                        # `source=langbot` is a courtesy attribution parameter so Tencent
+                        # can see LangBot adoption metrics, matching the convention used by
+                        # other third-party integrations (e.g. hermes-agent uses `source=hermes`).
+                        qr_url = f'{QQ_BIND_BASE}/qqbot/openclaw/connect.html?task_id={task_id}&_wv=2&source=langbot'
+                        session['task_id'] = task_id
+                        session['qr_url'] = qr_url
+                        session['expire_at'] = time.time() + _QQOFFICIAL_SESSION_TTL
+                        session['status'] = 'waiting'
+
+                        # Step 2: poll_bind_result until completed (status=2) or expired (3).
+                        deadline = time.time() + _QQOFFICIAL_SESSION_TTL
+                        while time.time() < deadline:
+                            await asyncio.sleep(session['interval'])
+
+                            async with http.post(
+                                f'{QQ_BIND_BASE}/lite/poll_bind_result',
+                                json={'task_id': task_id},
+                                headers={'Accept': 'application/json'},
+                            ) as poll_resp:
+                                try:
+                                    poll_data = await poll_resp.json(content_type=None)
+                                except (aiohttp.ContentTypeError, ValueError):
+                                    continue
+
+                            if int(poll_data.get('retcode', -1)) != 0:
+                                session['status'] = 'error'
+                                session['error'] = poll_data.get('msg') or poll_data.get('message') or 'Poll failed'
+                                return
+
+                            payload = poll_data.get('data') or {}
+                            try:
+                                raw_status = int(payload.get('status', 0))
+                            except (TypeError, ValueError):
+                                raw_status = 0
+
+                            if raw_status == 2:
+                                appid = str(payload.get('bot_appid') or '').strip()
+                                encrypted = str(payload.get('bot_encrypt_secret') or '').strip()
+                                if not appid or not encrypted:
+                                    session['status'] = 'error'
+                                    session['error'] = 'Incomplete credential payload'
+                                    return
+                                try:
+                                    session['secret'] = _decrypt_qqofficial_secret(
+                                        encrypted,
+                                        bind_key_bytes,
+                                    )
+                                except ValueError as exc:
+                                    session['status'] = 'error'
+                                    session['error'] = str(exc)
+                                    return
+                                session['appid'] = appid
+                                # The scanner's OpenID is returned alongside the credentials —
+                                # surfaced to the dashboard for audit / "bound by" display.
+                                session['user_openid'] = str(payload.get('user_openid') or '').strip() or None
+                                session['status'] = 'success'
+                                return
+
+                            if raw_status == 3:
+                                session['status'] = 'expired'
+                                session['error'] = 'QR code expired'
+                                return
+                            # status 0 / 1: still pending, continue polling
+
+                        session['status'] = 'expired'
+                        session['error'] = 'QR code expired'
+
+                except asyncio.CancelledError:
+                    return
+                except Exception as e:
+                    session['status'] = 'error'
+                    session['error'] = str(e)
+
+            task = asyncio.create_task(run_qr_binding())
+            session['task'] = task
+
+            # Wait up to 10s for the QR URL to be ready before responding.
+            for _ in range(20):
+                if session['qr_url'] or session['error']:
+                    break
+                await asyncio.sleep(0.5)
+
+            if session['error']:
+                task.cancel()
+                return self.http_status(502, -1, session['error'])
+
+            if not session['qr_url']:
+                task.cancel()
+                session['status'] = 'error'
+                session['error'] = 'Timeout waiting for QR code'
+                return self.http_status(504, -1, 'Timeout waiting for QR code')
+
+            return self.success(
+                data={
+                    'session_id': session_id,
+                    'qr_url': session['qr_url'],
+                    'expire_at': session['expire_at'],
+                }
+            )
+
+        @self.route('/qqofficial/bind/status/<session_id>', methods=['GET'])
+        async def _(session_id: str) -> str:
+            """Poll QQ Official QR binding status."""
+            _cleanup_expired_qqofficial_sessions()
+            session = _qqofficial_sessions.get(session_id)
+            if not session:
+                return self.http_status(404, -1, 'Session not found')
+
+            data = {'status': session['status']}
+
+            if session['status'] == 'success':
+                data['appid'] = session['appid']
+                data['secret'] = session['secret']
+                if session.get('user_openid'):
+                    data['user_openid'] = session['user_openid']
+                _qqofficial_sessions.pop(session_id, None)
+            elif session['status'] in ('error', 'expired'):
+                data['error'] = session['error']
+                _qqofficial_sessions.pop(session_id, None)
+
+            return self.success(data=data)
+
+        @self.route('/qqofficial/bind/<session_id>', methods=['DELETE'])
+        async def _(session_id: str) -> str:
+            """Cancel and clean up a QQ Official QR binding session."""
+            session = _qqofficial_sessions.pop(session_id, None)
+            if session and session.get('task') and not session['task'].done():
+                session['task'].cancel()
+            return self.success(data={})

src/langbot/pkg/pipeline/pipelinemgr.py

@@ -168,7 +168,7 @@ class RuntimePipeline:
                     bot_message=query.resp_messages[-1],
                     message=result.user_notice,
                     quote_origin=query.pipeline_config['output']['misc']['quote-origin'],
-                    is_final=[msg.is_final for msg in query.resp_messages][0],
+                    is_final=[msg.is_final for msg in query.resp_messages][-1],
                 )
             else:
                 await query.adapter.reply_message(

src/langbot/pkg/pipeline/pool.py

@@ -42,9 +42,13 @@ class QueryPool:
         adapter: abstract_platform_adapter.AbstractMessagePlatformAdapter,
         pipeline_uuid: typing.Optional[str] = None,
         routed_by_rule: bool = False,
+        variables: typing.Optional[dict[str, typing.Any]] = None,
     ) -> pipeline_query.Query:
         async with self.condition:
             query_id = self.query_id_counter
+            initial_variables: dict[str, typing.Any] = {'_routed_by_rule': routed_by_rule}
+            if variables:
+                initial_variables.update(variables)
             query = pipeline_query.Query(
                 bot_uuid=bot_uuid,
                 query_id=query_id,
@@ -53,7 +57,7 @@ class QueryPool:
                 sender_id=sender_id,
                 message_event=message_event,
                 message_chain=message_chain,
-                variables={'_routed_by_rule': routed_by_rule},
+                variables=initial_variables,
                 resp_messages=[],
                 resp_message_chain=[],
                 adapter=adapter,

src/langbot/pkg/pipeline/respback/respback.py

@@ -45,7 +45,7 @@ class SendResponseBackStage(stage.PipelineStage):
 
         try:
             if await query.adapter.is_stream_output_supported() and has_chunks:
-                is_final = [msg.is_final for msg in query.resp_messages][0]
+                is_final = [msg.is_final for msg in query.resp_messages][-1]
                 await query.adapter.reply_message_chunk(
                     message_source=query.message_event,
                     bot_message=query.resp_messages[-1],

src/langbot/pkg/platform/botmgr.py

@@ -501,6 +501,8 @@ class PlatformManager:
             bot_entity.adapter_config,
             logger,
         )
+        if hasattr(adapter_inst, 'ap'):
+            adapter_inst.ap = self.ap
 
         # 如果 adapter 支持 set_bot_uuid 方法，设置 bot_uuid（用于统一 webhook）
         if hasattr(adapter_inst, 'set_bot_uuid'):

src/langbot/pkg/platform/sources/dingtalk.yaml

@@ -103,6 +103,41 @@ spec:
       type: string
       required: true
       default: "填写你的卡片template_id"
+    - name: human_input_card_template_download
+      label:
+        en_US: Download Human Input Card Template
+        zh_Hans: 下载人工输入卡片模板
+        zh_Hant: 下載人工輸入卡片範本
+      description:
+        en_US: "Used as the only card template ID for the whole conversation turn. Download the built-in template, then import the JSON in DingTalk Open Platform > Card Platform / Card Template Management. After DingTalk creates the template, copy its template ID into the field below. The template already wires `content` (MarkdownBlock) and `btns` (ButtonGroup). Leave empty to fall back to the legacy two-card behavior."
+        zh_Hans: "用作整个对话回合唯一卡片的模板 ID。先下载内置模板，再到钉钉开放平台 > 卡片平台 / 卡片模板管理中导入该 JSON；钉钉生成模板后，将模板 ID 填到这里。模板已预先连好 `content` (MarkdownBlock) 与 `btns` (ButtonGroup)。留空则降级为旧的双卡行为。"
+        zh_Hant: "用作整個對話回合唯一卡片的範本 ID。先下載內建範本，再到釘釘開放平台 > 卡片平台 / 卡片範本管理中匯入該 JSON；釘釘產生範本後，將範本 ID 填到這裡。範本已預先連好 `content` (MarkdownBlock) 與 `btns` (ButtonGroup)。留空則降級為舊的雙卡行為。"
+      type: download-link
+      required: false
+      default: ""
+      url: /api/v1/platform/adapters/dingtalk/human-input-card-template
+      download_filename: dingtalk_human_input_card.json
+      help_links:
+        zh: https://open-dev.dingtalk.com/fe/card
+        en: https://open-dev.dingtalk.com/fe/card
+        ja: https://open-dev.dingtalk.com/fe/card
+      help_label:
+        en_US: Import Guide
+        zh_Hans: 导入指引
+        zh_Hant: 匯入指引
+        ja_JP: インポート手順
+    - name: human_input_card_template_id
+      label:
+        en_US: Human Input Card Template ID
+        zh_Hans: 人工输入卡片模板ID
+        zh_Hant: 人工輸入卡片範本ID
+      description:
+        en_US: "Paste the template ID generated after importing the human input card template."
+        zh_Hans: "填写导入人工输入卡片模板后生成的模板 ID。"
+        zh_Hant: "填寫匯入人工輸入卡片範本後產生的範本 ID。"
+      type: string
+      required: false
+      default: ""
 execution:
   python:
     path: ./dingtalk.py

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

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import discord
+from discord import ui as discord_ui
 
 import typing
 import re
@@ -8,6 +9,8 @@ import base64
 import uuid
 import os
 import datetime
+import time
+import traceback
 
 # 使用BytesIO创建文件对象，避免路径问题
 import io
@@ -824,6 +827,69 @@ class DiscordEventConverter(abstract_platform_adapter.AbstractEventConverter):
             )
 
 
+class DiscordFormView(discord_ui.View):
+    """Discord ``ui.View`` that renders one button per Dify form action.
+
+    Each button's click triggers ``adapter._on_form_button_click`` which
+    acks the interaction, locks the buttons in place, and enqueues a
+    synthetic ``_dify_form_action`` query so the runner resumes the
+    workflow.
+    """
+
+    # Discord button style mapping for Dify ``button_style`` values.
+    _STYLE_MAP: typing.ClassVar[dict] = {
+        'primary': discord.ButtonStyle.primary,
+        'danger': discord.ButtonStyle.danger,
+        'warning': discord.ButtonStyle.danger,
+        'success': discord.ButtonStyle.success,
+        'default': discord.ButtonStyle.secondary,
+        '': discord.ButtonStyle.secondary,
+    }
+
+    def __init__(
+        self,
+        adapter: 'DiscordAdapter',
+        session_key: str,
+        actions: list,
+        timeout: float = 1800,
+    ):
+        super().__init__(timeout=timeout)
+        self._adapter = adapter
+        self._session_key = session_key
+        # Discord caps a view at 25 children (5 rows × 5 buttons). Trim
+        # silently — most Dify forms have ≤10 actions in practice.
+        for idx, action in enumerate(actions[:25]):
+            action_id = str(action.get('id') or '')
+            label = str(action.get('title') or action_id or f'Option {idx + 1}')
+            style = self._STYLE_MAP.get(
+                str(action.get('button_style') or '').lower(),
+                discord.ButtonStyle.secondary,
+            )
+            # custom_id must be unique within the view and ≤100 chars.
+            # Encode (session, idx) so we can recover the action even
+            # if Dify ids contain unsafe characters.
+            custom_id = f'lb_form:{idx}:{action_id[:80]}'[:100]
+            button = discord_ui.Button(
+                label=label[:80],  # Discord label limit
+                style=style,
+                custom_id=custom_id,
+            )
+            button.callback = self._make_callback(action_id, label)
+            self.add_item(button)
+
+    def _make_callback(self, action_id: str, action_title: str):
+        async def _cb(interaction: discord.Interaction):
+            await self._adapter._on_form_button_click(
+                interaction=interaction,
+                session_key=self._session_key,
+                action_id=action_id,
+                action_title=action_title,
+                view=self,
+            )
+
+        return _cb
+
+
 class DiscordAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
     bot: discord.Client = pydantic.Field(exclude=True)
 
@@ -837,6 +903,10 @@ class DiscordAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
 
     voice_manager: VoiceConnectionManager | None = pydantic.Field(exclude=True, default=None)
 
+    # Injected by botmgr at construction so the form-button callback can
+    # enqueue a synthetic resume query (`_dify_form_action`) on the pool.
+    ap: typing.Any = pydantic.Field(exclude=True, default=None)
+
     def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger, **kwargs):
         bot_account_id = config['client_id']
 
@@ -860,8 +930,18 @@ class DiscordAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
 
         args = {}
 
-        if os.getenv('http_proxy'):
-            args['proxy'] = os.getenv('http_proxy')
+        # Proxy: config > env var > auto-detect.
+        # discord.py uses aiohttp which does NOT respect http_proxy env
+        # vars by default — we must pass proxy= explicitly.
+        proxy = (
+            config.get('proxy')
+            or os.getenv('http_proxy')
+            or os.getenv('HTTP_PROXY')
+            or os.getenv('https_proxy')
+            or os.getenv('HTTPS_PROXY')
+        )
+        if proxy:
+            args['proxy'] = proxy
 
         bot = MyClient(intents=intents, **args)
 
@@ -875,6 +955,19 @@ class DiscordAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
             **kwargs,
         )
 
+        # Per-resp-message-id buffer for the accumulated text yielded by
+        # the runner. Discord's edit-message ratelimit (5/5s) makes true
+        # progressive streaming impractical, so we collect chunks and
+        # render once on is_final. ``_form_data`` on the final chunk
+        # diverts to the button-view path.
+        self._stream_buffer: dict[str, str] = {}
+        # session_key -> {form_data, channel_id, thread_id, sender_id,
+        #                 posted_at, view_message_id}
+        # Populated when we send a form view; consumed when the user
+        # clicks a button so we know which workflow_run / form_token to
+        # resume.
+        self._pending_forms: dict[str, dict] = {}
+
     # Voice functionality methods
     async def join_voice_channel(self, guild_id: int, channel_id: int, user_id: int = None) -> discord.VoiceClient:
         """
@@ -1068,7 +1161,12 @@ class DiscordAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
     ):
         msg_to_send, files = await self.message_converter.yiri2target(message)
 
-        assert isinstance(message_source.source_platform_object, discord.Message)
+        # Synthetic events (button-click resume) have no inbound discord
+        # Message. Route via the channel we cached when the user clicked.
+        source = message_source.source_platform_object
+        if not isinstance(source, discord.Message):
+            await self._reply_synthetic(message_source, msg_to_send, files)
+            return
 
         args = {
             'content': msg_to_send,
@@ -1078,7 +1176,7 @@ class DiscordAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
             args['files'] = files
 
         if quote_origin:
-            args['reference'] = message_source.source_platform_object
+            args['reference'] = source
 
         has_at = False
 
@@ -1090,7 +1188,422 @@ class DiscordAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
         if has_at:
             args['mention_author'] = True
 
-        await message_source.source_platform_object.channel.send(**args)
+        await source.channel.send(**args)
+
+    async def _reply_synthetic(
+        self,
+        message_source: platform_events.MessageEvent,
+        msg_to_send: str,
+        files: list,
+    ) -> None:
+        """Deliver a reply for a button-click-resumed (synthetic) event.
+
+        We don't have an inbound discord.Message to anchor to; instead
+        look up the channel cached in ``_pending_forms[session_key +
+        '__last_channel']`` from the most recent button click.
+        """
+        if isinstance(message_source, platform_events.GroupMessage):
+            # _handle_form_chunk uses channel_id alone as the session
+            # scope, and launcher_id was set to channel_id when
+            # synthesizing the event.
+            session_key = f'c:{message_source.group.id}'
+        else:
+            session_key = f'p:{message_source.sender.id}'
+
+        cached = self._pending_forms.get(session_key + '__last_channel') or {}
+        channel = cached.get('channel')
+        if channel is None:
+            if self.ap is not None:
+                self.ap.logger.warning(
+                    f'Discord: synthetic reply has no cached channel for '
+                    f'{session_key}; dropping content (len={len(msg_to_send)})'
+                )
+            return
+
+        args: dict[str, typing.Any] = {'content': msg_to_send}
+        if files:
+            args['files'] = files
+        try:
+            await channel.send(**args)
+        except Exception:
+            if self.ap is not None:
+                self.ap.logger.error(f'Discord: synthetic reply send failed: {traceback.format_exc()}')
+
+    # Discord allows 5 edits per 5 seconds per message. We throttle
+    # to one edit per 8 runner-chunks (runner already yields every 8
+    # text_chunks internally), which stays comfortably within limits.
+    _STREAM_EDIT_INTERVAL = 8
+
+    async def is_stream_output_supported(self) -> bool:
+        return True
+
+    async def create_message_card(self, message_id: str, event: platform_events.MessageEvent) -> bool:
+        """Set up a stream context for progressive editing.
+
+        The first non-empty reply_message_chunk will send the initial
+        message; subsequent chunks edit it in place.
+        """
+        source = event.source_platform_object
+        if not isinstance(source, discord.Message):
+            return False
+        self._stream_buffer[message_id] = {
+            'channel': source.channel,
+            'sent_message': None,  # discord.Message set on first send
+            'last_content': '',
+            'chunk_count': 0,
+        }
+        return True
+
+    async def reply_message_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message: typing.Any,
+        message: platform_message.MessageChain,
+        quote_origin: bool = False,
+        is_final: bool = False,
+    ):
+        msg_id = (
+            bot_message.get('resp_message_id')
+            if isinstance(bot_message, dict)
+            else getattr(bot_message, 'resp_message_id', None)
+        )
+
+        text_parts = [m.text for m in message if isinstance(m, platform_message.Plain)]
+        chunk_text = '\n\n'.join(t for t in text_parts if t)
+
+        form_data = getattr(bot_message, '_form_data', None) if not isinstance(bot_message, dict) else None
+
+        ctx = self._stream_buffer.get(msg_id) if msg_id else None
+
+        # If the stream ctx was not set up (create_message_card wasn't
+        # called, e.g. synthetic event), or the final chunk carries a
+        # form, skip progressive editing entirely.
+        if ctx is None or form_data:
+            try:
+                if form_data and is_final:
+                    await self._handle_form_chunk(message_source, form_data)
+                elif is_final and chunk_text:
+                    await self.reply_message(
+                        message_source,
+                        platform_message.MessageChain([platform_message.Plain(text=chunk_text)]),
+                        quote_origin,
+                    )
+            finally:
+                self._stream_buffer.pop(msg_id, None)
+            return
+
+        # Progressive streaming path: send first chunk, edit subsequent.
+        ctx['chunk_count'] += 1
+
+        # Runner yields the full accumulated text on each chunk, so we
+        # always replace (not append).
+        if chunk_text:
+            ctx['last_content'] = chunk_text
+
+        sent = ctx['sent_message']
+
+        if sent is None:
+            # First non-empty chunk — send the initial message.
+            if not ctx['last_content']:
+                return  # No content yet, wait for next chunk.
+            try:
+                sent = await ctx['channel'].send(ctx['last_content'])
+                ctx['sent_message'] = sent
+            except Exception:
+                if self.ap is not None:
+                    self.ap.logger.error(f'Discord stream send failed: {traceback.format_exc()}')
+                self._stream_buffer.pop(msg_id, None)
+                return
+
+        if is_final:
+            # Final chunk — edit to the full content, then clean up.
+            if ctx['last_content'] and ctx['last_content'] != sent.content:
+                try:
+                    await sent.edit(content=ctx['last_content'][:2000])
+                except Exception:
+                    pass  # Best-effort
+            self._stream_buffer.pop(msg_id, None)
+        elif (ctx['chunk_count'] % self._STREAM_EDIT_INTERVAL) == 0:
+            # Intermediate edit — throttle to avoid rate limits.
+            if ctx['last_content'] and ctx['last_content'] != sent.content:
+                try:
+                    await sent.edit(content=ctx['last_content'][:2000])
+                except Exception:
+                    pass  # Rate-limited or deleted — ignore.
+
+    async def _handle_form_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        form_data: dict,
+    ) -> None:
+        """Render a Dify form pause as a Discord embed + button View.
+
+        Mirrors the QQ / Telegram / Lark form path: the button's click
+        callback synthesizes a ``_dify_form_action`` query so the runner's
+        ``_merge_pending_form_action`` resumes the workflow.
+        """
+        source = message_source.source_platform_object
+
+        actions = form_data.get('actions') or []
+        if not actions:
+            # Nothing clickable — fall back to plain text.
+            if source is not None:
+                await self.reply_message(
+                    message_source,
+                    platform_message.MessageChain(
+                        [platform_message.Plain(text=str(form_data.get('node_title') or ''))]
+                    ),
+                )
+            return
+
+        node_title = str(form_data.get('node_title') or 'Confirmation needed')
+        form_content = str(form_data.get('form_content') or '').strip()
+
+        # Two paths:
+        #   (a) Real message — extract channel from source.
+        #   (b) Synthetic event (button-click resume) — no
+        #       source_platform_object; recover the channel we cached
+        #       when the user clicked.
+        if isinstance(source, discord.Message):
+            channel = source.channel
+            guild_id = str(source.guild.id) if source.guild else ''
+            sender_id = str(source.author.id)
+            channel_id = str(source.channel.id)
+            session_key = f'c:{channel_id}' if guild_id else f'p:{sender_id}'
+        else:
+            # Synthetic event — resolve session_key from event shape,
+            # then look up the cached channel from the click.
+            if isinstance(message_source, platform_events.GroupMessage):
+                # launcher_id was set to channel_id when we synthesized.
+                channel_id = str(message_source.group.id)
+                session_key = f'c:{channel_id}'
+            else:
+                session_key = f'p:{message_source.sender.id}'
+                channel_id = ''
+
+            cached = self._pending_forms.get(session_key + '__last_channel')
+            channel = cached.get('channel') if cached else None
+            guild_id = (cached or {}).get('guild_id', '')
+            sender_id = str(message_source.sender.id) if message_source.sender else ''
+            if channel is None:
+                if self.ap is not None:
+                    self.ap.logger.warning(
+                        f'Discord: synthetic form chunk has no cached channel for '
+                        f'{session_key}; cannot render form buttons'
+                    )
+                return
+
+        body_parts: list[str] = []
+        if form_content:
+            body_parts.append(form_content)
+        embed_body = '\n\n'.join(body_parts)
+        # Discord embed.description has a 4096 char limit — defensive trim.
+        if len(embed_body) > 4000:
+            embed_body = embed_body[:3990] + '\n\n…(truncated)'
+
+        embed = discord.Embed(
+            title=node_title[:256],
+            description=embed_body,
+            color=discord.Color.blurple(),
+        )
+
+        view = DiscordFormView(
+            adapter=self,
+            session_key=session_key,
+            actions=actions,
+            timeout=1800,  # 30 min — matches Dify form_token TTL
+        )
+
+        try:
+            sent_msg = await channel.send(embed=embed, view=view)
+        except Exception:
+            if self.ap is not None:
+                self.ap.logger.error(f'Discord: form view send failed: {traceback.format_exc()}')
+            return
+
+        self._pending_forms[session_key] = {
+            'form_data': form_data,
+            'channel_id': channel_id,
+            'guild_id': guild_id,
+            'sender_id': sender_id,
+            'view_message_id': str(sent_msg.id),
+            'posted_at': time.time(),
+        }
+
+        if self.ap is not None:
+            self.ap.logger.info(f'Discord: form view posted session={session_key} actions={len(actions)}')
+
+    async def _on_form_button_click(
+        self,
+        interaction: discord.Interaction,
+        session_key: str,
+        action_id: str,
+        action_title: str,
+        view: DiscordFormView,
+    ) -> None:
+        """Handle a click on a form button — ack, resume the workflow,
+        and disable the View buttons so the choice is visually locked in."""
+        import langbot_plugin.api.entities.builtin.provider.session as provider_session
+
+        # ACK first (3-second deadline before Discord shows "interaction failed").
+        try:
+            await interaction.response.defer()
+        except discord.HTTPException:
+            # Already responded somehow — proceed regardless.
+            pass
+
+        pending = self._pending_forms.get(session_key)
+        if not pending:
+            if self.ap is not None:
+                self.ap.logger.warning(
+                    f'Discord: button click on stale session {session_key}; ignoring (action_id={action_id!r})'
+                )
+            await self._lock_view_message(interaction, view, action_title, stale=True)
+            return
+
+        form_data: dict = pending.get('form_data') or {}
+        guild_id = pending.get('guild_id', '')
+        channel_id = pending.get('channel_id', '')
+        initiator_id = str(pending.get('sender_id', '') or '')
+        actor_id = str(interaction.user.id) if interaction.user is not None else initiator_id
+        if not guild_id and initiator_id and actor_id != initiator_id:
+            if self.ap is not None:
+                self.ap.logger.warning(
+                    f'Discord: user {actor_id} cannot act on private form created for {initiator_id}'
+                )
+            await self._lock_view_message(interaction, view, action_title, stale=True)
+            return
+
+        self._pending_forms.pop(session_key, None)
+
+        # Lock the buttons in place: disable everything, mark chosen one.
+        await self._lock_view_message(interaction, view, action_title)
+
+        # In group context the launcher remains the channel so Dify resumes
+        # the original group session. The synthetic sender is still the real
+        # clicker, preserving actor identity for auditing and routing rules.
+        if guild_id:
+            launcher_type = provider_session.LauncherTypes.GROUP
+            launcher_id = channel_id
+        else:
+            launcher_type = provider_session.LauncherTypes.PERSON
+            launcher_id = initiator_id or actor_id
+
+        form_action_data = {
+            'form_token': form_data.get('form_token', ''),
+            'workflow_run_id': form_data.get('workflow_run_id', ''),
+            'action_id': action_id,
+            'action_title': action_title,
+            'node_title': form_data.get('node_title', ''),
+            'user': f'{launcher_type.value}_{launcher_id}',
+            'inputs': {},
+        }
+
+        message_chain = platform_message.MessageChain([platform_message.Plain(text=f'[Form Action: {action_title}]')])
+
+        # Synthesize a platform event so the pipeline can run the resume
+        # query. source_platform_object=None signals "no inbound discord
+        # message" — reply_message must tolerate this (it falls through
+        # to channel.send via the cached interaction.channel below).
+        if launcher_type == provider_session.LauncherTypes.GROUP:
+            synthetic_event: platform_events.MessageEvent = platform_events.GroupMessage(
+                sender=platform_entities.GroupMember(
+                    id=actor_id,
+                    member_name=interaction.user.display_name if interaction.user else '',
+                    permission='MEMBER',
+                    group=platform_entities.Group(
+                        id=launcher_id,
+                        name=channel_id,
+                        permission=platform_entities.Permission.Member,
+                    ),
+                    special_title='',
+                ),
+                message_chain=message_chain,
+                time=int(time.time()),
+                source_platform_object=None,
+            )
+        else:
+            synthetic_event = platform_events.FriendMessage(
+                sender=platform_entities.Friend(
+                    id=actor_id,
+                    nickname=interaction.user.display_name if interaction.user else '',
+                    remark='',
+                ),
+                message_chain=message_chain,
+                time=int(time.time()),
+                source_platform_object=None,
+            )
+
+        if self.ap is None:
+            if self.logger:
+                await self.logger.error('Discord: ap not injected; cannot enqueue button-click query')
+            return
+
+        bot_uuid = ''
+        pipeline_uuid = form_data.get('pipeline_uuid') or None
+        for bot in self.ap.platform_mgr.bots:
+            if bot.adapter is self:
+                bot_uuid = bot.bot_entity.uuid
+                pipeline_uuid = pipeline_uuid or bot.bot_entity.use_pipeline_uuid
+                break
+
+        # Remember the channel so _reply_synthetic and _handle_form_chunk
+        # (synthetic-event path) can find a target. guild_id is needed
+        # to reconstruct the launcher_type on subsequent form pauses.
+        self._pending_forms[session_key + '__last_channel'] = {
+            'channel': interaction.channel,
+            'guild_id': guild_id,
+            'posted_at': time.time(),
+        }
+
+        try:
+            await self.ap.query_pool.add_query(
+                bot_uuid=bot_uuid,
+                launcher_type=launcher_type,
+                launcher_id=launcher_id,
+                sender_id=actor_id,
+                message_event=synthetic_event,
+                message_chain=message_chain,
+                adapter=self,
+                pipeline_uuid=pipeline_uuid,
+                variables={
+                    '_dify_form_action': form_action_data,
+                    '_routed_by_rule': True,
+                },
+            )
+            if self.ap is not None:
+                self.ap.logger.info(
+                    f'Discord: button-click query enqueued action_id={action_id!r} '
+                    f'session={session_key} actor_id={actor_id}'
+                )
+        except Exception:
+            if self.ap is not None:
+                self.ap.logger.error(f'Discord: enqueue button-click query failed: {traceback.format_exc()}')
+
+    async def _lock_view_message(
+        self,
+        interaction: discord.Interaction,
+        view: DiscordFormView,
+        chosen_title: str,
+        stale: bool = False,
+    ) -> None:
+        """Disable all buttons on the form view and annotate the chosen
+        one — mirrors DingTalk/Lark's in-card selection feedback."""
+        try:
+            for child in view.children:
+                if not isinstance(child, discord_ui.Button):
+                    continue
+                child.disabled = True
+                if not stale and child.label == chosen_title:
+                    child.style = discord.ButtonStyle.success
+                    if not (child.label or '').startswith('✓ '):
+                        child.label = f'✓ {child.label}'
+            view.stop()
+            if interaction.message is not None:
+                await interaction.message.edit(view=view)
+        except Exception:
+            if self.ap is not None:
+                self.ap.logger.warning(f'Discord: lock-view-message failed (non-fatal): {traceback.format_exc()}')
 
     async def is_muted(self, group_id: int) -> bool:
         return False

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

@@ -11,7 +11,13 @@ import langbot_plugin.api.definition.abstract.platform.adapter as abstract_platf
 import langbot_plugin.api.entities.builtin.platform.message as platform_message
 import langbot_plugin.api.entities.builtin.platform.events as platform_events
 import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
-from langbot.libs.qq_official_api.api import QQOfficialClient
+from langbot.libs.qq_official_api.api import (
+    QQ_SELECT_ACTION_PREFIX,
+    QQOfficialClient,
+    build_keyboard_from_form,
+    build_keyboard_from_select_field,
+    resolve_select_button_action,
+)
 from langbot.libs.qq_official_api.qqofficialevent import QQOfficialEvent
 from ...utils import image
 from ..logger import EventLogger
@@ -191,6 +197,7 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
     enable_webhook: bool = False
     message_converter: QQOfficialMessageConverter = QQOfficialMessageConverter()
     event_converter: QQOfficialEventConverter = QQOfficialEventConverter()
+    ap: typing.Any = None
 
     def __init__(self, config: dict, logger: EventLogger):
         enable_webhook = config.get('enable-webhook', False)
@@ -216,6 +223,31 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
         self._stream_ctx_ts: dict[str, float] = {}
         self._fallback_text: dict[str, str] = {}
         self._fallback_text_ts: dict[str, float] = {}
+        # Dify form-action bookkeeping for the human-input button flow.
+        # session_key = "<scene>_<id>" where scene is c2c/group/channel and
+        #   id is user_openid / group_openid / channel_id.
+        # session_key -> {form_data, msg_id, event_id, scene, target_id,
+        #                 sender_id, posted_at}
+        # Set when we send a markdown+keyboard card and consulted when:
+        #   (a) INTERACTION_CREATE fires — we look up the form by
+        #       session_key (button's `data` carries the action_id),
+        #   (b) the resumed-workflow query needs to find a passive-reply
+        #       event_id (INTERACTION_CREATE id, 30-min validity).
+        self._pending_forms: dict[str, dict] = {}
+        # session_key -> most recent ``INTERACTION_CREATE`` event_id, used
+        # as the passive event_id for the resumed query's LLM output.
+        self._session_event_ids: dict[str, dict] = {}
+        # Per-anchor msg_seq counter. QQ accepts up to 5 passive replies
+        # per (msg_id|event_id) within 60 min, but each reuse needs a
+        # fresh ``msg_seq`` — re-sending with msg_seq=1 is silently dedup'd.
+        self._anchor_msg_seq: dict[str, int] = {}
+
+        # Wire button-click handler so webhook mode catches INTERACTION_CREATE.
+        # (ws mode is wired separately via on_event in _run_websocket so the
+        # raw payload bypasses get_message's message-only flattening.)
+        @self.bot.on_interaction()
+        async def _on_interaction(event_data: dict, interaction_id: typing.Optional[str]):
+            await self._handle_interaction_create(event_data, interaction_id)
 
     async def reply_message(
         self,
@@ -227,6 +259,13 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
             message_source,
         )
 
+        # Synthetic event (button-click resume): no inbound platform
+        # object → no msg_id. Route via the cached INTERACTION_CREATE
+        # event_id (valid 30 min, no quota cost).
+        if qq_official_event is None:
+            await self._reply_synthetic(message_source, message)
+            return
+
         content_list = await QQOfficialMessageConverter.yiri2target(message)
 
         # 确定 target_type 和 target_id
@@ -376,6 +415,9 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
             await self.logger.info('QQ Official WebSocket connected and ready')
 
         async def on_event(event_type: str, event_data: dict):
+            # INTERACTION_CREATE is dispatched via bot.on_interaction()
+            # (registered in __init__) so we get the top-level ws_event_id
+            # — needed as the passive-reply event_id. It never reaches here.
             # 只处理消息事件，忽略 READY/RESUMED 等系统事件
             message_event_types = {
                 'C2C_MESSAGE_CREATE',
@@ -437,12 +479,36 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
     async def is_stream_output_supported(self) -> bool:
         return self.config.get('enable-stream-reply', False)
 
+    @staticmethod
+    def _is_form_placeholder_chunk(text: str) -> bool:
+        """Return True for invisible placeholder chunks used to carry forms."""
+
+        if not text:
+            return False
+
+        cleaned = text.replace('\u200b', '').replace('\u200c', '').replace('\u200d', '').replace('\ufeff', '').strip()
+        # Some Windows consoles/logs display the zero-width placeholder as
+        # mojibake. Treat those variants as the same non-user-facing marker.
+        return cleaned in {'', '鈥?', '​'}
+
     async def create_message_card(self, message_id: str, event: platform_events.MessageEvent) -> bool:
         source = event.source_platform_object
+        # Synthetic events (button-click resume) have no source object —
+        # they ride a cached INTERACTION_CREATE event_id, not a streamable
+        # msg_id. Skip stream setup; reply_message handles the one-shot
+        # send at is_final.
+        if source is None:
+            return False
         # Streaming API only supports C2C private chat
         if source.t != 'C2C_MESSAGE_CREATE':
             return False
 
+        # The stream endpoint still consumes msg_seq for this inbound msg_id.
+        # Keep the passive-reply counter in sync so a follow-up form card uses
+        # msg_seq=2 instead of being deduplicated by QQ as another seq=1 send.
+        if source.d_id:
+            self._anchor_msg_seq[source.d_id] = max(self._anchor_msg_seq.get(source.d_id, 0), 1)
+
         ctx = {
             'user_openid': source.user_openid,
             'msg_id': source.d_id,
@@ -469,12 +535,38 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
     ):
         # Periodically clean up stale stream contexts
         await self._cleanup_stale_streams()
+
+        # Dify human-input pause: when the runner attaches `_form_data` to
+        # the final chunk, finalize any in-flight stream session and send
+        # a markdown + keyboard message instead. Plain-text content from
+        # earlier chunks is already on the stream; we close it cleanly
+        # and the buttons land as a separate reply.
+        form_data = getattr(bot_message, '_form_data', None) if not isinstance(bot_message, dict) else None
+        if is_final:
+            _resume = getattr(bot_message, '_resume_from_form', None) if not isinstance(bot_message, dict) else None
+            _open_new = getattr(bot_message, '_open_new_card', None) if not isinstance(bot_message, dict) else None
+            if self.ap is not None:
+                self.ap.logger.info(
+                    f'QQ Official reply_message_chunk final: '
+                    f'type={type(bot_message).__name__} '
+                    f'is_final={is_final} '
+                    f'form_data_present={form_data is not None} '
+                    f'resume_from_form={_resume} open_new_card={_open_new} '
+                    f'content_len={len(getattr(bot_message, "content", "") or "")}'
+                )
+        if form_data and is_final:
+            await self._handle_form_chunk(message_source, message, form_data)
+            return
+
         # 提取纯文本内容（当前 chunk 的文本）
         text_parts = []
         for msg in message:
             if type(msg) is platform_message.Plain:
                 text_parts.append(msg.text)
         chunk_text = '\n\n'.join(text_parts)
+        if self._is_form_placeholder_chunk(chunk_text):
+            await self.logger.debug('QQ Official: skipped invisible form placeholder chunk')
+            return
 
         message_id = (
             bot_message.get('resp_message_id')
@@ -484,7 +576,8 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
         if not message_id or message_id not in self._stream_ctx:
             # 非流式场景（如群聊不支持流式），累积文本后一次性回复
             if chunk_text:
-                self._fallback_text[message_id] = self._fallback_text.get(message_id, '') + chunk_text
+                # Chunks carry the latest full snapshot, not a text delta.
+                self._fallback_text[message_id] = chunk_text
                 self._fallback_text_ts[message_id] = time.time()
             if is_final:
                 full_text = self._fallback_text.pop(message_id, '')
@@ -497,7 +590,7 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
 
         # 累积文本
         if chunk_text:
-            ctx['accumulated_text'] += chunk_text
+            ctx['accumulated_text'] = chunk_text
 
         # 未启动会话时，等第一个有内容的 chunk 来建立会话
         if not ctx['session_started']:
@@ -557,3 +650,489 @@ class QQOfficialAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter
         ],
     ):
         return super().unregister_listener(event_type, callback)
+
+    # ------------------------------------------------------------------
+    # Dify human-input button-interaction support
+    # ------------------------------------------------------------------
+
+    _PENDING_FORM_TTL = 1800  # 30 min — matches QQ passive-reply window.
+    _MAX_REPLIES_PER_ANCHOR = 5  # QQ hard limit per msg_id / event_id.
+
+    def _next_msg_seq(self, anchor: str) -> typing.Optional[int]:
+        """Return the next msg_seq for an anchor, or ``None`` if the
+        anchor has already been used 5 times (further sends would be
+        silently dropped by QQ)."""
+        if not anchor:
+            return 1
+        used = self._anchor_msg_seq.get(anchor, 0)
+        if used >= self._MAX_REPLIES_PER_ANCHOR:
+            return None
+        self._anchor_msg_seq[anchor] = used + 1
+        return used + 1
+
+    async def _reply_synthetic(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+    ) -> None:
+        """Deliver a reply for a synthetic (button-click-resume) event.
+
+        Synthetic events have ``source_platform_object=None`` and no
+        fresh inbound msg_id. The previous INTERACTION_CREATE id we
+        cached in :attr:`_session_event_ids` is a valid passive-reply
+        anchor (``event_id``) for up to 30 minutes — use it.
+        """
+        if isinstance(message_source, platform_events.GroupMessage):
+            target_type = 'group'
+            group = getattr(message_source, 'group', None) or (
+                message_source.sender.group if hasattr(message_source.sender, 'group') else None
+            )
+            target_id = str(group.id) if group else None
+        else:
+            target_type = 'c2c'
+            target_id = str(message_source.sender.id) if message_source.sender else None
+
+        if not target_id:
+            await self.logger.warning('QQ Official: synthetic reply has no target_id; dropping')
+            return
+
+        session_key = f'{target_type}_{target_id}'
+        cached = self._session_event_ids.get(session_key)
+        event_id = cached.get('event_id') if cached else None
+        if cached and (time.time() - cached.get('posted_at', 0)) > self._PENDING_FORM_TTL:
+            event_id = None
+
+        if not event_id:
+            await self.logger.warning(
+                f'QQ Official: no cached event_id for {session_key}; '
+                f'cannot deliver synthetic reply within passive-reply window'
+            )
+            return
+
+        content_list = await QQOfficialMessageConverter.yiri2target(message)
+        text_parts = [c['content'] for c in content_list if c.get('type') == 'text' and c.get('content')]
+        if not text_parts:
+            await self.logger.info('QQ Official: synthetic reply has no text content; skipping')
+            return
+        text = '\n\n'.join(text_parts)
+
+        msg_seq = self._next_msg_seq(event_id)
+        if msg_seq is None:
+            await self.logger.warning(
+                f'QQ Official: anchor {event_id!r} exhausted (>5 passive replies); '
+                f'cannot deliver synthetic reply for {session_key}'
+            )
+            return
+
+        try:
+            if target_type == 'c2c':
+                await self.bot.send_private_text_msg(
+                    user_openid=target_id,
+                    content=text,
+                    event_id=event_id,
+                    msg_seq=msg_seq,
+                )
+            elif target_type == 'group':
+                await self.bot.send_group_text_msg(
+                    group_openid=target_id,
+                    content=text,
+                    event_id=event_id,
+                    msg_seq=msg_seq,
+                )
+        except Exception:
+            await self.logger.error(f'QQ Official: synthetic reply delivery failed: {traceback.format_exc()}')
+
+    def _resolve_target_from_source(self, source: QQOfficialEvent) -> typing.Optional[tuple[str, str]]:
+        """Return ``(target_type, target_id)`` for sending a reply, or
+        ``None`` if the scene cannot host a markdown+keyboard message."""
+        if source is None:
+            return None
+        if source.t == 'C2C_MESSAGE_CREATE':
+            return 'c2c', source.user_openid
+        if source.t == 'GROUP_AT_MESSAGE_CREATE':
+            return 'group', source.group_openid
+        if source.t == 'AT_MESSAGE_CREATE':
+            return 'channel', source.channel_id
+        # DIRECT_MESSAGE_CREATE uses the guild DM API which does not accept
+        # markdown+keyboard at the time of writing — caller falls back to text.
+        return None
+
+    def _resolve_target_from_event(
+        self, message_source: platform_events.MessageEvent
+    ) -> typing.Optional[tuple[str, str]]:
+        """Resolve ``(target_type, target_id)`` from the public event.
+
+        Prefers the platform-native source when present; falls back to
+        the synthesized event's sender/group fields so button-click
+        resume queries can still find a destination.
+        """
+        source = message_source.source_platform_object
+        if source is not None:
+            return self._resolve_target_from_source(source)
+        if isinstance(message_source, platform_events.GroupMessage):
+            group = getattr(message_source, 'group', None) or (
+                message_source.sender.group
+                if message_source.sender and hasattr(message_source.sender, 'group')
+                else None
+            )
+            if group and getattr(group, 'id', None):
+                return 'group', str(group.id)
+        if isinstance(message_source, platform_events.FriendMessage):
+            if message_source.sender and getattr(message_source.sender, 'id', None):
+                return 'c2c', str(message_source.sender.id)
+        return None
+
+    def _prune_pending_forms(self) -> None:
+        now = time.time()
+        stale = [k for k, v in self._pending_forms.items() if now - v.get('posted_at', 0) > self._PENDING_FORM_TTL]
+        for k in stale:
+            self._pending_forms.pop(k, None)
+        stale_e = [
+            k for k, v in self._session_event_ids.items() if now - v.get('posted_at', 0) > self._PENDING_FORM_TTL
+        ]
+        for k in stale_e:
+            self._session_event_ids.pop(k, None)
+
+    async def _handle_form_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        message: platform_message.MessageChain,
+        form_data: dict,
+    ) -> None:
+        """Send the markdown + keyboard form prompt for a Dify pause.
+
+        Called from ``reply_message_chunk`` when the runner attaches
+        ``_form_data`` to the final chunk. Replaces what would otherwise
+        be a plain-text numbered-list fallback.
+        """
+        if self.ap is not None:
+            self.ap.logger.info(
+                f'QQ Official _handle_form_chunk entered; '
+                f'source_present={message_source.source_platform_object is not None} '
+                f'form_actions={len(form_data.get("actions") or [])}'
+            )
+        self._prune_pending_forms()
+
+        source = message_source.source_platform_object
+        scene_target = self._resolve_target_from_event(message_source)
+        if scene_target is None:
+            # No rich-UI fit — fall through to existing text path.
+            await self.logger.info('QQ Official: form chunk on unsupported scene; falling back to text')
+            text_parts = [m.text for m in message if type(m) is platform_message.Plain]
+            fallback_msg = platform_message.MessageChain([platform_message.Plain(text='\n\n'.join(text_parts))])
+            try:
+                await self.reply_message(message_source, fallback_msg)
+            except Exception:
+                await self.logger.error(f'QQ Official: form fallback text send failed: {traceback.format_exc()}')
+            return
+
+        target_type, target_id = scene_target
+        session_key = f'{target_type}_{target_id}'
+
+        # Cancel any in-flight stream / fallback ctx so plain-text prefix
+        # doesn't continue alongside the keyboard message.
+        msg_id = getattr(source, 'd_id', '') or '' if source is not None else ''
+        if msg_id:
+            self._stream_ctx.pop(msg_id, None)
+            self._stream_ctx_ts.pop(msg_id, None)
+            self._fallback_text.pop(msg_id, None)
+            self._fallback_text_ts.pop(msg_id, None)
+
+        node_title = form_data.get('node_title') or 'Confirmation needed'
+        form_content = form_data.get('form_content') or ''
+        is_field_step = bool(form_data.get('_current_input_field')) and not form_data.get('_action_select_only')
+        parts = [f'### {node_title}']
+        plain_parts = [node_title]
+        if form_content.strip():
+            parts.append(form_content.strip())
+            plain_parts.append(form_content.strip())
+        markdown_content = '\n\n'.join(parts)
+        plain_content = '\n\n'.join(plain_parts)
+
+        keyboard = build_keyboard_from_select_field(form_data) if is_field_step else None
+        is_text_field_step = is_field_step and not keyboard.get('content', {}).get('rows')
+        if is_text_field_step:
+            keyboard = None
+        if keyboard is None and not is_text_field_step:
+            keyboard = build_keyboard_from_form(form_data, buttons_per_row=2)
+        if keyboard is not None and not keyboard.get('content', {}).get('rows') and not is_text_field_step:
+            # No actions to render — fall back to plain text.
+            text_msg = platform_message.MessageChain([platform_message.Plain(text=plain_content)])
+            try:
+                await self.reply_message(message_source, text_msg)
+            except Exception:
+                await self.logger.error(f'QQ Official: empty-keyboard fallback send failed: {traceback.format_exc()}')
+            return
+
+        # Prefer the inbound msg_id (no quota cost). If the source is a
+        # synthetic event from a prior click, the cached interaction id
+        # serves as event_id for up to 30 min.
+        event_id = None
+        if not msg_id:
+            cached = self._session_event_ids.get(session_key)
+            if cached and (time.time() - cached.get('posted_at', 0)) < self._PENDING_FORM_TTL:
+                event_id = cached.get('event_id')
+
+        anchor = msg_id or event_id or ''
+        msg_seq = self._next_msg_seq(anchor)
+        if msg_seq is None:
+            await self.logger.warning(
+                f'QQ Official: anchor {anchor!r} exhausted (>5 passive replies); '
+                f'cannot deliver form card for session={session_key}'
+            )
+            return
+
+        try:
+            await self.bot.send_markdown_keyboard(
+                target_type=target_type,
+                target_id=target_id,
+                markdown_content=markdown_content,
+                keyboard=keyboard,
+                msg_id=msg_id if (msg_id and not event_id) else None,
+                event_id=event_id,
+                msg_seq=msg_seq,
+            )
+            if self.ap is not None:
+                self.ap.logger.info(
+                    f'QQ Official: form card sent '
+                    f'target={target_type}/{target_id} '
+                    f'msg_id={msg_id!r} event_id={event_id!r} msg_seq={msg_seq}'
+                )
+        except Exception:
+            if self.ap is not None:
+                self.ap.logger.error(
+                    f'QQ Official: send_markdown_keyboard failed, falling back to text: {traceback.format_exc()}'
+                )
+            await self.logger.error(
+                f'QQ Official: send_markdown_keyboard failed, falling back to text: {traceback.format_exc()}'
+            )
+            text_msg = platform_message.MessageChain([platform_message.Plain(text=plain_content)])
+            try:
+                await self.reply_message(message_source, text_msg)
+            except Exception:
+                pass
+            return
+
+        sender_id = ''
+        if source is not None:
+            sender_id = (
+                getattr(source, 'user_openid', None)
+                or getattr(source, 'member_openid', None)
+                or getattr(source, 'd_author_id', None)
+                or ''
+            )
+        if not sender_id and message_source.sender is not None:
+            sender_id = str(getattr(message_source.sender, 'id', '') or '')
+        self._pending_forms[session_key] = {
+            'form_data': form_data,
+            'msg_id': msg_id,
+            'sender_id': sender_id,
+            'target_type': target_type,
+            'target_id': target_id,
+            'source_event_t': source.t if source is not None else None,
+            'posted_at': time.time(),
+        }
+        await self.logger.info(
+            f'QQ Official: form posted session={session_key} actions={len(form_data.get("actions") or [])}'
+        )
+
+    async def _handle_interaction_create(
+        self,
+        event_data: dict,
+        ws_event_id: typing.Optional[str] = None,
+    ) -> None:
+        """Handle a button-click INTERACTION_CREATE event.
+
+        Two IDs at play (QQ keeps them separate):
+            ws_event_id   top-level payload ``id`` (or webhook ``X-Bot-
+                          Event-Id``). The ONLY value accepted as
+                          ``event_id`` for subsequent passive replies.
+            d['id']       the interaction id — used for PUT
+                          /interactions/{id} ack. Cannot be reused as
+                          event_id (QQ returns 40034025 if you try).
+
+        Layout (https://bot.q.qq.com/.../msg-btn.html):
+            chat_type     0 channel / 1 group / 2 c2c
+            data.resolved.button_data  what we set as ``action.data``
+            data.resolved.button_id    ``id`` field on the button row
+        """
+        import langbot_plugin.api.entities.builtin.provider.session as provider_session
+
+        if self.ap is not None:
+            self.ap.logger.info(
+                f'QQ Official _handle_interaction_create entered; '
+                f'ws_event_id={ws_event_id!r} '
+                f'interaction_id={(event_data.get("id") if isinstance(event_data, dict) else None)!r} '
+                f'chat_type={event_data.get("chat_type") if isinstance(event_data, dict) else None}'
+            )
+
+        if not isinstance(event_data, dict):
+            await self.logger.warning(f'QQ Official: INTERACTION_CREATE event_data is not dict: {type(event_data)}')
+            return
+
+        # ACK uses the interaction id, NOT the ws event id.
+        interaction_id = event_data.get('id') or ''
+        if interaction_id:
+            asyncio.create_task(self.bot.ack_interaction(interaction_id, code=0))
+
+        resolved = (event_data.get('data') or {}).get('resolved') or {}
+        action_id = str(resolved.get('button_data') or resolved.get('button_id') or '').strip()
+        if not action_id:
+            await self.logger.warning('QQ Official: INTERACTION_CREATE missing button_data/button_id; ignoring')
+            return
+
+        chat_type = event_data.get('chat_type')
+        scene_target: typing.Optional[tuple[str, str]] = None
+        if chat_type == 2 or event_data.get('user_openid'):
+            scene_target = ('c2c', event_data.get('user_openid') or '')
+        elif chat_type == 1 or event_data.get('group_openid'):
+            scene_target = ('group', event_data.get('group_openid') or '')
+        elif chat_type == 0 or event_data.get('channel_id'):
+            scene_target = ('channel', event_data.get('channel_id') or '')
+
+        if not scene_target or not scene_target[1]:
+            await self.logger.warning(f'QQ Official: INTERACTION_CREATE missing scene/target; raw={event_data}')
+            return
+
+        target_type, target_id = scene_target
+        session_key = f'{target_type}_{target_id}'
+
+        self._prune_pending_forms()
+        pending = self._pending_forms.get(session_key)
+        if not pending:
+            await self.logger.warning(
+                f'QQ Official: no pending form for session {session_key}; click ignored (action_id={action_id!r})'
+            )
+            return
+
+        # Cache ws_event_id so a follow-up pause / text reply can use it
+        # as event_id for passive delivery (30-min window). Falls back to
+        # the interaction_id only if no ws_event_id was provided (e.g.
+        # tests / older payload shape) — QQ will reject that value but
+        # we log so the mismatch is debuggable.
+        cached_event_id = ws_event_id or interaction_id
+        if cached_event_id:
+            self._session_event_ids[session_key] = {
+                'event_id': cached_event_id,
+                'posted_at': time.time(),
+            }
+            # New anchor → fresh 5-reply budget.
+            self._anchor_msg_seq[cached_event_id] = 0
+            if self.ap is not None and not ws_event_id:
+                self.ap.logger.warning(
+                    'QQ Official: INTERACTION_CREATE lacked ws_event_id; '
+                    'falling back to interaction_id (passive reply may be rejected)'
+                )
+
+        form_data: dict = pending.get('form_data') or {}
+        actions = form_data.get('actions') or []
+        select_choice = resolve_select_button_action(form_data, action_id)
+        if action_id.startswith(QQ_SELECT_ACTION_PREFIX) and select_choice is None:
+            await self.logger.warning(f'QQ Official: invalid select action_id={action_id!r} for {session_key}')
+            return
+
+        matched = None
+        if select_choice is None:
+            matched = next(
+                (a for a in actions if str(a.get('id', '')) == action_id),
+                None,
+            )
+            if matched is None:
+                await self.logger.warning(
+                    f'QQ Official: action_id={action_id!r} is not present on pending form for {session_key}'
+                )
+                return
+        self._pending_forms.pop(session_key, None)
+        action_title = select_choice[1] if select_choice else matched.get('title') or action_id
+
+        initiator_id = str(pending.get('sender_id') or '')
+        actor_id = str(event_data.get('member_openid') or event_data.get('user_openid') or initiator_id)
+
+        # Build resume payload matching the shape every other adapter uses
+        # (DingTalk / Lark / Telegram / WeCom). The runner's
+        # _merge_pending_form_action consumes this verbatim.
+        if target_type == 'group' or target_type == 'channel':
+            launcher_type = provider_session.LauncherTypes.GROUP
+            launcher_id = target_id
+        else:
+            launcher_type = provider_session.LauncherTypes.PERSON
+            launcher_id = target_id
+
+        form_action_data = {
+            'form_token': form_data.get('form_token', ''),
+            'workflow_run_id': form_data.get('workflow_run_id', ''),
+            'action_id': '' if select_choice else action_id,
+            'action_title': action_title,
+            'node_title': form_data.get('node_title', ''),
+            'user': f'{launcher_type.value}_{launcher_id}',
+            'inputs': {'select': select_choice[1]} if select_choice else {},
+        }
+        if select_choice:
+            form_action_data['_current_input_field'] = select_choice[0]
+            form_action_data['_input_progress'] = True
+
+        event_label = 'Form Select' if select_choice else 'Form Action'
+        message_chain = platform_message.MessageChain([platform_message.Plain(text=f'[{event_label}: {action_title}]')])
+
+        if launcher_type == provider_session.LauncherTypes.GROUP:
+            synthetic_event: platform_events.MessageEvent = platform_events.GroupMessage(
+                sender=platform_entities.GroupMember(
+                    id=actor_id or launcher_id,
+                    member_name='',
+                    permission='MEMBER',
+                    group=platform_entities.Group(
+                        id=launcher_id,
+                        name='',
+                        permission=platform_entities.Permission.Member,
+                    ),
+                    special_title='',
+                ),
+                message_chain=message_chain,
+                time=int(time.time()),
+                source_platform_object=None,
+            )
+        else:
+            synthetic_event = platform_events.FriendMessage(
+                sender=platform_entities.Friend(
+                    id=actor_id or launcher_id,
+                    nickname='',
+                    remark='',
+                ),
+                message_chain=message_chain,
+                time=int(time.time()),
+                source_platform_object=None,
+            )
+
+        if self.ap is None:
+            await self.logger.error('QQ Official: ap not injected; cannot enqueue button-click query')
+            return
+
+        bot_uuid = ''
+        pipeline_uuid = form_data.get('pipeline_uuid') or None
+        for bot in self.ap.platform_mgr.bots:
+            if bot.adapter is self:
+                bot_uuid = bot.bot_entity.uuid
+                pipeline_uuid = pipeline_uuid or bot.bot_entity.use_pipeline_uuid
+                break
+
+        try:
+            await self.ap.query_pool.add_query(
+                bot_uuid=bot_uuid,
+                launcher_type=launcher_type,
+                launcher_id=launcher_id,
+                sender_id=actor_id or launcher_id,
+                message_event=synthetic_event,
+                message_chain=message_chain,
+                adapter=self,
+                pipeline_uuid=pipeline_uuid,
+                variables={
+                    '_dify_form_action': form_action_data,
+                    '_routed_by_rule': True,
+                },
+            )
+            await self.logger.info(
+                f'QQ Official: button-click query enqueued action_id={action_id!r} '
+                f'session={session_key} actor_id={actor_id}'
+            )
+        except Exception:
+            await self.logger.error(f'QQ Official: enqueue button-click query failed: {traceback.format_exc()}')

src/langbot/pkg/platform/sources/qqofficial.yaml

@@ -31,6 +31,18 @@ spec:
       type: array[string]
       required: false
       default: []
+    - name: one-click-bind
+      label:
+        en_US: One-Click QR Binding
+        zh_Hans: 一键扫码绑定
+        zh_Hant: 一鍵掃碼綁定
+      description:
+        en_US: Scan QR code with mobile QQ to auto-fill AppID and Secret (Token is not used and can be left blank)
+        zh_Hans: 使用手机 QQ 扫码绑定，自动填写 AppID 和密钥（当前未使用 Token，可留空）
+        zh_Hant: 使用手機 QQ 掃碼綁定，自動填寫 AppID 和密鑰（目前未使用 Token，可留空）
+      type: qr-code-login
+      login_platform: qqofficial
+      required: false
     - name: appid
       label:
         en_US: App ID
@@ -52,8 +64,12 @@ spec:
         en_US: Token
         zh_Hans: 令牌
         zh_Hant: 令牌
+      description:
+        en_US: Optional. The QR binding cannot return this value; the current adapter implementation does not use it either, so it can be safely left blank.
+        zh_Hans: 可选。扫码绑定无法获取该字段，当前适配器实现也未使用该字段，留空即可。
+        zh_Hant: 可選。掃碼綁定無法取得此欄位，目前介面卡實作亦未使用，留空即可。
       type: string
-      required: true
+      required: false
       default: ""
     - name: enable-webhook
       label:

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

@@ -1,15 +1,17 @@
 from __future__ import annotations
-import time
 
 
 import telegram
 import telegram.ext
-from telegram import Update
-from telegram.ext import ApplicationBuilder, ContextTypes, MessageHandler, filters
+from telegram import ForceReply, InlineKeyboardButton, InlineKeyboardMarkup, Update
+from telegram.ext import ApplicationBuilder, ContextTypes, MessageHandler, CallbackQueryHandler, filters
 import telegramify_markdown
 import typing
 import traceback
+import json
 import base64
+import time
+import uuid
 import pydantic
 
 from langbot.pkg.utils import httpclient
@@ -20,6 +22,61 @@ import langbot_plugin.api.entities.builtin.platform.entities as platform_entitie
 import langbot_plugin.api.definition.abstract.platform.event_logger as abstract_platform_logger
 
 
+def _telegram_select_field_options(form_data: dict) -> tuple[str, list[str]]:
+    """Return the active select field and its option values."""
+    field_name = str(form_data.get('_current_input_field') or '').strip()
+    if not field_name:
+        return '', []
+    field = next(
+        (
+            item
+            for item in form_data.get('input_defs') or []
+            if str(item.get('output_variable_name') or '').strip() == field_name
+        ),
+        None,
+    )
+    if not field or str(field.get('type') or '').strip().lower() != 'select':
+        return '', []
+
+    source = field.get('option_source') or {}
+    source_value = source.get('value') if isinstance(source, dict) else None
+    if isinstance(source_value, list):
+        return field_name, [str(item) for item in source_value]
+    if isinstance(source_value, str):
+        return field_name, [part.strip() for part in source_value.splitlines() if part.strip()]
+
+    options = field.get('options')
+    if not isinstance(options, list):
+        return field_name, []
+    values = []
+    for item in options:
+        if isinstance(item, dict):
+            values.append(str(item.get('label') or item.get('value') or ''))
+        else:
+            values.append(str(item))
+    return field_name, [value for value in values if value]
+
+
+def _telegram_form_action_from_callback(data: dict) -> dict | None:
+    """Translate compact Telegram callback data into a runner form action."""
+    if 'x' not in data:
+        return {
+            'action_id': str(data.get('action_id') or data.get('a') or ''),
+            'inputs': {},
+        }
+    try:
+        option_index = int(data['x'])
+    except (TypeError, ValueError):
+        return None
+    if option_index < 0:
+        return None
+    return {
+        'action_id': '',
+        'inputs': {'select': {'index': option_index}},
+        '_input_progress': True,
+    }
+
+
 class TelegramMessageConverter(abstract_platform_adapter.AbstractMessageConverter):
     @staticmethod
     async def yiri2target(message_chain: platform_message.MessageChain, bot: telegram.Bot) -> list[dict]:
@@ -167,7 +224,7 @@ class TelegramEventConverter(abstract_platform_adapter.AbstractEventConverter):
                 time=event.message.date.timestamp(),
                 source_platform_object=event,
             )
-        elif event.effective_chat.type == 'group' or 'supergroup':
+        elif event.effective_chat.type in ('group', 'supergroup'):
             return platform_events.GroupMessage(
                 sender=platform_entities.GroupMember(
                     id=event.effective_chat.id,
@@ -189,6 +246,7 @@ class TelegramEventConverter(abstract_platform_adapter.AbstractEventConverter):
 class TelegramAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
     bot: telegram.Bot = pydantic.Field(exclude=True)
     application: telegram.ext.Application = pydantic.Field(exclude=True)
+    ap: typing.Any = pydantic.Field(exclude=True, default=None)
 
     message_converter: TelegramMessageConverter = TelegramMessageConverter()
     event_converter: TelegramEventConverter = TelegramEventConverter()
@@ -204,6 +262,48 @@ class TelegramAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
         typing.Callable[[platform_events.Event, abstract_platform_adapter.AbstractMessagePlatformAdapter], None],
     ] = {}
 
+    _FORM_ACTION_CACHE_TTL = 30 * 60
+    # callback_data -> (display title, pipeline UUID, expiration time, form group id)
+    _form_action_titles: typing.Dict[str, tuple[str, str, float, str]] = {}
+
+    def _prune_form_action_titles(self, now: float | None = None) -> None:
+        now = time.monotonic() if now is None else now
+        expired = [key for key, (_, _, expires_at, _) in self._form_action_titles.items() if expires_at <= now]
+        for key in expired:
+            self._form_action_titles.pop(key, None)
+
+    def _cache_form_action_titles(
+        self,
+        mappings: dict[str, str],
+        pipeline_uuid: str = '',
+        now: float | None = None,
+    ) -> None:
+        now = time.monotonic() if now is None else now
+        self._prune_form_action_titles(now)
+        group_id = uuid.uuid4().hex
+        expires_at = now + self._FORM_ACTION_CACHE_TTL
+        self._form_action_titles.update(
+            {callback_data: (title, pipeline_uuid, expires_at, group_id) for callback_data, title in mappings.items()}
+        )
+
+    def _take_form_action_context(self, callback_data: str, now: float | None = None) -> tuple[str, str] | None:
+        """Consume a callback and invalidate every button from the same form."""
+        self._prune_form_action_titles(now)
+        entry = self._form_action_titles.get(callback_data)
+        if entry is None:
+            return None
+        title, pipeline_uuid, _, group_id = entry
+        group_keys = [
+            key for key, (_, _, _, cached_group_id) in self._form_action_titles.items() if cached_group_id == group_id
+        ]
+        for key in group_keys:
+            self._form_action_titles.pop(key, None)
+        return title, pipeline_uuid
+
+    def _take_form_action_title(self, callback_data: str, now: float | None = None) -> str | None:
+        context = self._take_form_action_context(callback_data, now)
+        return context[0] if context else None
+
     def __init__(self, config: dict, logger: abstract_platform_logger.AbstractEventLogger):
         async def telegram_callback(update: Update, context: ContextTypes.DEFAULT_TYPE):
             if update.message.from_user.is_bot:
@@ -224,6 +324,117 @@ class TelegramAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
                 telegram_callback,
             )
         )
+
+        async def callback_query_handler(update: Update, context: ContextTypes.DEFAULT_TYPE):
+            query = update.callback_query
+            await query.answer()
+            try:
+                data = json.loads(query.data)
+                if data.get('form_action') or data.get('f'):
+                    import langbot_plugin.api.entities.builtin.provider.session as provider_session
+
+                    # workflow_run_id is not in the callback payload (too large
+                    # for Telegram's 64-byte limit). Only w_suffix is sent;
+                    # the runner resolves the full run id from _PENDING_FORMS.
+                    w_suffix = data.get('w', '')
+                    session_key = data.get('session_key') or data.get('s', '')
+                    callback_action = _telegram_form_action_from_callback(data)
+                    action_context = self._take_form_action_context(query.data) if callback_action is not None else None
+                    if callback_action is None or action_context is None:
+                        await self.logger.warning(f'Invalid or stale Telegram form callback: {query.data!r}')
+                        return
+                    action_title, pipeline_uuid = action_context
+                    # Show selected action feedback by editing the original message
+                    try:
+                        original_text = query.message.text or ''
+                        selected_text = f'{original_text}\n\n✅ {action_title}'
+                        await query.edit_message_text(text=selected_text, reply_markup=None)
+                    except Exception:
+                        # If edit fails (e.g. message too long), just pass
+                        pass
+
+                    if session_key.startswith('group_') or session_key.startswith('g:'):
+                        launcher_type = provider_session.LauncherTypes.GROUP
+                        launcher_id = (
+                            session_key.split(':', 1)[1]
+                            if session_key.startswith('g:')
+                            else session_key[len('group_') :]
+                        )
+                    else:
+                        launcher_type = provider_session.LauncherTypes.PERSON
+                        launcher_id = (
+                            session_key.split(':', 1)[1]
+                            if session_key.startswith('p:')
+                            else session_key[len('person_') :]
+                        )
+
+                    user_id = str(query.from_user.id)
+
+                    # Find bot_uuid and pipeline_uuid
+                    bot_uuid = ''
+                    for b in self.ap.platform_mgr.bots:
+                        if b.adapter is self:
+                            bot_uuid = b.bot_entity.uuid
+                            pipeline_uuid = pipeline_uuid or b.bot_entity.use_pipeline_uuid
+                            break
+
+                    form_action_data = {
+                        # workflow_run_id is intentionally omitted; the runner
+                        # resolves it from w_suffix via _PENDING_FORMS.
+                        'w_suffix': w_suffix,
+                        'user': f'{launcher_type.value}_{launcher_id}',
+                        **callback_action,
+                    }
+
+                    event_label = 'Form Select' if callback_action.get('_input_progress') else 'Form Action'
+                    message_chain = platform_message.MessageChain(
+                        [platform_message.Plain(text=f'[{event_label}: {action_title}]')]
+                    )
+
+                    if launcher_type == provider_session.LauncherTypes.GROUP:
+                        synthetic_event = platform_events.GroupMessage(
+                            sender=platform_entities.GroupMember(
+                                id=user_id,
+                                member_name='',
+                                permission=platform_entities.Permission.Member,
+                                group=platform_entities.Group(
+                                    id=launcher_id,
+                                    name='',
+                                    permission=platform_entities.Permission.Member,
+                                ),
+                            ),
+                            message_chain=message_chain,
+                            source_platform_object=update,
+                        )
+                    else:
+                        synthetic_event = platform_events.FriendMessage(
+                            sender=platform_entities.Friend(
+                                id=user_id,
+                                nickname='',
+                                remark='',
+                            ),
+                            message_chain=message_chain,
+                            source_platform_object=update,
+                        )
+
+                    await self.ap.query_pool.add_query(
+                        bot_uuid=bot_uuid,
+                        launcher_type=launcher_type,
+                        launcher_id=launcher_id,
+                        sender_id=user_id,
+                        message_event=synthetic_event,
+                        message_chain=message_chain,
+                        adapter=self,
+                        pipeline_uuid=pipeline_uuid,
+                        variables={
+                            '_dify_form_action': form_action_data,
+                            '_routed_by_rule': True,
+                        },
+                    )
+            except Exception:
+                await self.logger.error(f'Error in telegram callback query: {traceback.format_exc()}')
+
+        application.add_handler(CallbackQueryHandler(callback_query_handler))
         super().__init__(
             config=config,
             logger=logger,
@@ -314,23 +525,34 @@ class TelegramAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
             args['parse_mode'] = 'MarkdownV2'
         return args
 
+    async def _delete_group_stream_message(self, chat_mode: str, chat_id: int, stream_id: int | None):
+        if chat_mode != 'group' or stream_id is None:
+            return
+        try:
+            await self.bot.delete_message(chat_id=chat_id, message_id=stream_id)
+        except telegram.error.TelegramError:
+            pass
+
+    @staticmethod
+    def _is_form_placeholder_chunk(text: str) -> bool:
+        """Return True for invisible placeholder chunks used to carry forms."""
+
+        if not text:
+            return True
+
+        cleaned = text.replace('\u200b', '').replace('\u200c', '').replace('\u200d', '').replace('\ufeff', '').strip()
+        return cleaned == ''
+
     async def create_message_card(self, message_id, event):
         assert isinstance(event.source_platform_object, Update)
         update = event.source_platform_object
         chat_id = update.effective_chat.id
-        chat_type = update.effective_chat.type
-        message_thread_id = update.message.message_thread_id
+        effective_message = update.effective_message
+        message_thread_id = getattr(effective_message, 'message_thread_id', None) if effective_message else None
 
-        if chat_type == 'private':
-            draft_id = int(time.time() * 1000)
-            self.msg_stream_id[message_id] = ('private', draft_id)
-
-            args = self._build_message_args(chat_id, 'Thinking...', message_thread_id, draft_id=draft_id)
-            await self.bot.send_message_draft(**args)
-        else:
-            args = self._build_message_args(chat_id, 'Thinking...', message_thread_id)
-            send_msg = await self.bot.send_message(**args)
-            self.msg_stream_id[message_id] = ('group', send_msg.message_id)
+        args = self._build_message_args(chat_id, 'Thinking...', message_thread_id)
+        send_msg = await self.bot.send_message(**args)
+        self.msg_stream_id[message_id] = ('message', send_msg.message_id, False)
 
         return True
 
@@ -347,12 +569,15 @@ class TelegramAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
         assert isinstance(message_source.source_platform_object, Update)
         update = message_source.source_platform_object
         chat_id = update.effective_chat.id
-        message_thread_id = update.message.message_thread_id
+        effective_message = update.effective_message
+        message_thread_id = getattr(effective_message, 'message_thread_id', None) if effective_message else None
 
         if message_id not in self.msg_stream_id:
             return
 
-        chat_mode, draft_id = self.msg_stream_id[message_id]
+        stream_state = self.msg_stream_id[message_id]
+        chat_mode, stream_id = stream_state[:2]
+        has_visible_content = len(stream_state) > 2 and stream_state[2]
         components = await TelegramMessageConverter.yiri2target(message, self.bot)
 
         if not components or components[0]['type'] != 'text':
@@ -361,17 +586,68 @@ class TelegramAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
             return
 
         content = components[0]['text']
+        form_data = getattr(bot_message, '_form_data', None)
+
+        if form_data and is_final:
+            if not has_visible_content:
+                await self._send_form_action_buttons(message_source, form_data, edit_message_id=stream_id)
+            else:
+                await self._send_form_action_buttons(message_source, form_data)
+            self.msg_stream_id.pop(message_id, None)
+            return
+
+        if self._is_form_placeholder_chunk(content):
+            if is_final and bot_message.tool_calls is None and not has_visible_content:
+                await self._delete_group_stream_message(chat_mode, chat_id, stream_id)
+                self.msg_stream_id.pop(message_id, None)
+            return
 
         if chat_mode == 'private':
-            args = self._build_message_args(chat_id, content, message_thread_id, draft_id=draft_id)
-            await self.bot.send_message_draft(**args)
+            # Streaming via draft (ephemeral preview in the chat input area)
+            if (msg_seq - 1) % 8 == 0 or is_final:
+                args = self._build_message_args(chat_id, content, message_thread_id, draft_id=stream_id)
+                try:
+                    await self.bot.send_message_draft(**args)
+                except telegram.error.BadRequest as exc:
+                    if 'Message_too_long' in str(exc):
+                        args['text'] = content[:4000] + '\n\n… (truncated)'
+                        try:
+                            await self.bot.send_message_draft(**args)
+                        except telegram.error.RetryAfter:
+                            pass
+                    else:
+                        pass  # Ignore other draft errors (cosmetic)
+                self.msg_stream_id[message_id] = (chat_mode, stream_id, True)
             if is_final and bot_message.tool_calls is None:
-                del args['draft_id']
-                await self.bot.send_message(**args)
+                # Finalise: send the real message, discard the draft
+                args = self._build_message_args(chat_id, content, message_thread_id)
+                try:
+                    await self.bot.send_message(**args)
+                except telegram.error.BadRequest as exc:
+                    if 'Message_too_long' in str(exc):
+                        args['text'] = content[:4000] + '\n\n… (truncated)'
+                        await self.bot.send_message(**args)
+                    else:
+                        raise
                 self.msg_stream_id.pop(message_id)
         else:
-            stream_id = draft_id
-            if (msg_seq - 1) % 8 == 0 or is_final:
+            # Streaming via edit_message_text (persistent message)
+            if stream_id is None:
+                args = self._build_message_args(chat_id, content, message_thread_id)
+                try:
+                    send_msg = await self.bot.send_message(**args)
+                except telegram.error.BadRequest as exc:
+                    if 'Message_too_long' in str(exc):
+                        args['text'] = self._process_markdown(content[:4000] + '\n\n鈥?(truncated)')
+                        send_msg = await self.bot.send_message(**args)
+                    else:
+                        raise
+                self.msg_stream_id[message_id] = (chat_mode, send_msg.message_id, True)
+                if is_final and bot_message.tool_calls is None:
+                    self.msg_stream_id.pop(message_id, None)
+                return
+
+            if not has_visible_content or (msg_seq - 1) % 8 == 0 or is_final:
                 args = {
                     'message_id': stream_id,
                     'chat_id': chat_id,
@@ -379,11 +655,137 @@ class TelegramAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
                 }
                 if self.config.get('markdown_card', False):
                     args['parse_mode'] = 'MarkdownV2'
-                await self.bot.edit_message_text(**args)
+                try:
+                    await self.bot.edit_message_text(**args)
+                except telegram.error.BadRequest as exc:
+                    if 'Message_too_long' in str(exc):
+                        args['text'] = self._process_markdown(content[:4000] + '\n\n… (truncated)')
+                        await self.bot.edit_message_text(**args)
+                    else:
+                        raise
+                self.msg_stream_id[message_id] = (chat_mode, stream_id, True)
 
             if is_final and bot_message.tool_calls is None:
                 self.msg_stream_id.pop(message_id)
 
+    async def _send_form_action_buttons(
+        self,
+        message_source: platform_events.MessageEvent,
+        form_data: dict,
+        edit_message_id: int | None = None,
+    ):
+        """Send inline keyboard buttons for Dify form fields or actions."""
+        actions = form_data.get('actions', [])
+        node_title = form_data.get('node_title', '')
+        form_content = form_data.get('form_content', '')
+        workflow_run_id = form_data.get('workflow_run_id', '')
+        # Telegram callback_data is capped at 64 bytes, so we identify the
+        # paused workflow by the last 8 chars of workflow_run_id (unique
+        # within a session with overwhelming probability).
+        w_suffix = workflow_run_id[-8:] if workflow_run_id else ''
+
+        if isinstance(message_source, platform_events.GroupMessage):
+            session_key = f'g:{message_source.group.id}'
+        else:
+            session_key = f'p:{message_source.sender.id}'
+
+        current_field = str(form_data.get('_current_input_field') or '').strip()
+        is_field_step = bool(current_field) and not form_data.get('_action_select_only')
+        select_field, select_options = _telegram_select_field_options(form_data)
+        is_select_field = bool(select_field and select_options)
+        if is_select_field:
+            choices = [(option, {'x': idx}) for idx, option in enumerate(select_options)]
+        elif is_field_step:
+            choices = []
+        else:
+            choices = [(action.get('title', action.get('id', '')), {'a': action.get('id', '')}) for action in actions]
+
+        keyboard = []
+        pending_title_mappings: dict[str, str] = {}
+        oversized = False
+        buttons_per_row = 2 if is_select_field else 1
+        current_row = []
+        for title, choice_data in choices:
+            callback_payload = {'f': 1, **choice_data, 's': session_key}
+            if w_suffix:
+                callback_payload['w'] = w_suffix
+            callback_data = json.dumps(callback_payload, separators=(',', ':'))
+            if len(callback_data.encode('utf-8')) > 64:
+                oversized = True
+                break
+            pending_title_mappings[callback_data] = str(title)
+            current_row.append(InlineKeyboardButton(str(title), callback_data=callback_data))
+            if len(current_row) == buttons_per_row:
+                keyboard.append(current_row)
+                current_row = []
+        if current_row and not oversized:
+            keyboard.append(current_row)
+
+        update = message_source.source_platform_object
+        chat_id = update.effective_chat.id
+        effective_message = update.effective_message
+        message_thread_id = getattr(effective_message, 'message_thread_id', None) if effective_message else None
+
+        heading = f'[{node_title}]'
+        text_lines = [heading]
+        if form_content:
+            text_lines.append(form_content)
+
+        if oversized:
+            # callback_data exceeds Telegram's 64-byte limit — fall back to
+            # a plain-text numbered list so the user can reply by number.
+            for idx, (title, _) in enumerate(choices, start=1):
+                text_lines.append(f'  {idx}. {title}')
+            args = {
+                'chat_id': chat_id,
+                'text': '\n\n'.join(text_lines),
+            }
+        elif keyboard:
+            self._cache_form_action_titles(
+                pending_title_mappings,
+                str(form_data.get('pipeline_uuid') or ''),
+            )
+            reply_markup = InlineKeyboardMarkup(keyboard)
+            args = {
+                'chat_id': chat_id,
+                'text': '\n\n'.join(text_lines),
+                'reply_markup': reply_markup,
+            }
+        elif is_field_step:
+            args = {
+                'chat_id': chat_id,
+                'text': '\n\n'.join(text_lines),
+                # Telegram privacy-mode bots receive replies to ForceReply
+                # prompts even when they cannot read ordinary group messages.
+                'reply_markup': ForceReply(
+                    selective=False,
+                    input_field_placeholder=current_field,
+                ),
+            }
+        else:
+            args = {
+                'chat_id': chat_id,
+                'text': '\n\n'.join(text_lines),
+            }
+
+        if message_thread_id:
+            args['message_thread_id'] = message_thread_id
+
+        if edit_message_id is not None:
+            edit_args = {
+                'chat_id': chat_id,
+                'message_id': edit_message_id,
+                'text': args['text'],
+            }
+            edit_args['reply_markup'] = args.get('reply_markup')
+            try:
+                await self.bot.edit_message_text(**edit_args)
+                return
+            except telegram.error.TelegramError:
+                await self._delete_group_stream_message('group', chat_id, edit_message_id)
+
+        await self.bot.send_message(**args)
+
     def get_launcher_id(self, event: platform_events.MessageEvent) -> str | None:
         if not isinstance(event.source_platform_object, Update):
             return None

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

@@ -11,7 +11,13 @@ import langbot_plugin.api.entities.builtin.platform.events as platform_events
 import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
 from ..logger import EventLogger
 from langbot.libs.wecom_ai_bot_api.wecombotevent import WecomBotEvent
-from langbot.libs.wecom_ai_bot_api.api import WecomBotClient
+from langbot.libs.wecom_ai_bot_api.api import (
+    WecomBotClient,
+    extract_template_card_action,
+    extract_template_card_event_payload,
+    extract_template_card_selections,
+    parse_select_button_action,
+)
 from langbot.libs.wecom_ai_bot_api.ws_client import WecomBotWsClient
 
 
@@ -296,6 +302,7 @@ class WecomBotAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
     listeners: dict = {}
     _stream_to_monitoring_msg: dict = {}  # Maps stream_id to (monitoring_message_id, timestamp)
     _STREAM_MAPPING_TTL = 600  # 10 minutes
+    ap: typing.Any = None
 
     def __init__(self, config: dict, logger: EventLogger):
         enable_webhook = config.get('enable-webhook', False)
@@ -336,6 +343,25 @@ class WecomBotAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
             _stream_to_monitoring_msg={},
         )
 
+        # Both WecomBotClient (webhook) and WecomBotWsClient (ws long-conn)
+        # expose ``set_card_action_callback``. Wire the click handler so
+        # Dify human-input button taps resume the workflow on either mode.
+        if hasattr(self.bot, 'set_card_action_callback'):
+            self.bot.set_card_action_callback(self._on_card_action)
+
+        # Hand the client a `source` block so every interactive
+        # template_card it emits carries the LangBot logo + name at the
+        # top — the WeCom analogue of DingTalk's Avatar header.
+        # Always on; icon_url accepts plain HTTPS URLs (no upload needed).
+        if hasattr(self.bot, 'set_card_source'):
+            self.bot.set_card_source(
+                {
+                    'icon_url': 'https://raw.githubusercontent.com/RockChinQ/LangBot/master/res/logo-blue.png',
+                    'desc': 'LangBot',
+                    'desc_color': 0,
+                }
+            )
+
     async def reply_message(
         self,
         message_source: platform_events.MessageEvent,
@@ -345,15 +371,37 @@ class WecomBotAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
         content = await self.message_converter.yiri2target(message)
         _ws_mode = not self.config.get('enable-webhook', False)
 
+        event = message_source.source_platform_object
+        # Synthetic events (button-click resume queries) have no inbound
+        # platform object. Fall back to a proactive send so error
+        # messages and one-shot replies still reach the user.
+        if event is None:
+            if _ws_mode:
+                if isinstance(message_source, platform_events.GroupMessage):
+                    chat_id = str(message_source.group.id)
+                else:
+                    chat_id = str(message_source.sender.id)
+                try:
+                    await self.bot.send_message(chat_id, content)
+                except Exception:
+                    await self.logger.error(
+                        f'WeComBot: proactive reply for synthetic event failed: {traceback.format_exc()}'
+                    )
+            else:
+                await self.logger.warning(
+                    'WeComBot webhook mode cannot reply to a synthetic event '
+                    '(no req_id and no proactive-send credentials); dropping.'
+                )
+            return
+
         if _ws_mode:
-            event = message_source.source_platform_object
-            req_id = event.get('req_id', '')
+            req_id = event.get('req_id', '') if isinstance(event, dict) else getattr(event, 'req_id', '')
             if req_id:
                 await self.bot.reply_text(req_id, content)
             else:
                 await self.bot.set_message(event.message_id, content)
         else:
-            await self.bot.set_message(message_source.source_platform_object.message_id, content)
+            await self.bot.set_message(event.message_id, content)
 
     async def reply_message_chunk(
         self,
@@ -364,9 +412,56 @@ class WecomBotAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
         is_final: bool = False,
     ):
         content = await self.message_converter.yiri2target(message)
-        msg_id = message_source.source_platform_object.message_id
         _ws_mode = not self.config.get('enable-webhook', False)
 
+        # Synthetic events (e.g. button-click triggered form resume) have
+        # no inbound platform message — no msg_id, no req_id, no stream
+        # session. The output must go via the proactive-send path instead
+        # of the stream/reply path.
+        spo = message_source.source_platform_object
+        if spo is None:
+            return await self._handle_synthetic_chunk(message_source, bot_message, content, is_final, _ws_mode)
+
+        msg_id = spo.message_id
+
+        # Dify human-input pause: when the runner attaches `_form_data` to
+        # the final chunk, hand the button_interaction card off to the
+        # underlying client. In webhook mode the card is queued for the
+        # next followup poll; in ws mode it's sent as a reply frame
+        # immediately. Falls back to plain text when the bot has no active
+        # stream session for this msg_id (rare).
+        form_data = getattr(bot_message, '_form_data', None)
+        if form_data and is_final:
+            if hasattr(self.bot, 'push_form_pause'):
+                ok, stream_id, task_id = await self.bot.push_form_pause(msg_id, form_data)
+                if ok:
+                    await self.logger.info(
+                        f'WeComBot: pending button_interaction registered '
+                        f'stream_id={stream_id} task_id={task_id} ws_mode={_ws_mode}'
+                    )
+                    return {'stream': True, 'form': True, 'task_id': task_id}
+            await self.logger.warning(
+                'WeComBot: cannot register form pause (no active stream session); falling back to plain text'
+            )
+            try:
+                from langbot.pkg.provider.runners.difysvapi import _format_human_input_text
+
+                fallback = _format_human_input_text(
+                    form_data.get('node_title', ''),
+                    form_data.get('form_content', ''),
+                    form_data.get('actions', []) or [],
+                )
+            except Exception:
+                fallback = content or '（人工输入）'
+            if _ws_mode:
+                event = message_source.source_platform_object
+                req_id = event.get('req_id', '') if isinstance(event, dict) else getattr(event, 'req_id', '')
+                if req_id:
+                    await self.bot.reply_text(req_id, fallback)
+            else:
+                await self.bot.set_message(msg_id, fallback)
+            return {'stream': False, 'form': True, 'fallback': True}
+
         if _ws_mode:
             success = await self.bot.push_stream_chunk(msg_id, content, is_final=is_final)
             if not success and is_final:
@@ -385,6 +480,142 @@ class WecomBotAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
         """Whether streaming output is enabled for this bot instance."""
         return self.config.get('enable-stream-reply', True)
 
+    async def _handle_synthetic_chunk(
+        self,
+        message_source: platform_events.MessageEvent,
+        bot_message,
+        content: str,
+        is_final: bool,
+        ws_mode: bool,
+    ) -> dict:
+        """Handle reply_message_chunk for synthetic events (button clicks).
+
+        Synthetic events have no inbound message → no msg_id, no req_id,
+        no stream session. We can't do incremental streaming, so we
+        buffer chunks per-conversation and flush on ``is_final`` via the
+        proactive send path.
+
+        Buffer keyed by ``(launcher_type, launcher_id)`` from the
+        synthetic event itself. Only ws mode has a usable proactive-send
+        path right now (``ws_client.send_message`` /
+        ``ws_client.send_template_card``); webhook mode requires a
+        corpid/secret we don't have, so it logs and drops.
+        """
+        if isinstance(message_source, platform_events.GroupMessage):
+            chat_id = str(message_source.group.id)
+        else:
+            chat_id = str(message_source.sender.id)
+
+        form_data = getattr(bot_message, '_form_data', None)
+
+        # Buffer streaming content until is_final.
+        buf_key = chat_id
+        if not hasattr(self, '_synthetic_buffers'):
+            # Attribute-not-declared trick: pydantic forbids dynamic attrs
+            # on the model, but plain instance dicts via object.__setattr__
+            # do work. Lazy-create on first call.
+            object.__setattr__(self, '_synthetic_buffers', {})
+        buffers: dict[str, str] = self._synthetic_buffers
+        if content and not form_data:
+            previous = buffers.get(buf_key, '')
+            if previous and content.startswith(previous):
+                buffers[buf_key] = content
+            elif previous and previous.endswith(content):
+                buffers[buf_key] = previous
+            else:
+                buffers[buf_key] = previous + content
+
+        if not is_final:
+            return {'stream': True, 'synthetic': True, 'buffered': True}
+
+        final_content = buffers.pop(buf_key, '')
+        if content:
+            if final_content and content.startswith(final_content):
+                final_content = content
+            elif final_content and final_content.endswith(content):
+                pass
+            else:
+                final_content = final_content + content
+
+        if not ws_mode:
+            await self.logger.warning(
+                'WeComBot webhook mode cannot proactively push synthetic-event '
+                'output (no corpid/secret); the resume reply is dropped. '
+                f'content_len={len(final_content)} form_data_present={form_data is not None}'
+            )
+            return {'stream': False, 'synthetic': True, 'dropped': True}
+
+        # ws mode: proactive send.
+        try:
+            if form_data:
+                # Determine user_id / chat_id for the routing context of any
+                # subsequent click on this card.
+                if isinstance(message_source, platform_events.GroupMessage):
+                    routing_chat_id = str(message_source.group.id)
+                    routing_user_id = str(message_source.sender.id)
+                else:
+                    routing_chat_id = ''
+                    routing_user_id = str(message_source.sender.id)
+                payload = self._build_button_interaction_payload_from_form(
+                    form_data,
+                    user_id=routing_user_id,
+                    chat_id=routing_chat_id,
+                )
+                await self.bot.send_template_card(chat_id, payload)
+                await self.logger.info(
+                    f'WeComBot ws: proactively sent template_card for synthetic event '
+                    f'chat_id={chat_id} form_token={form_data.get("form_token")!r} '
+                    f'workflow_run_id={form_data.get("workflow_run_id")!r}'
+                )
+            elif final_content:
+                await self.bot.send_message(chat_id, final_content)
+                await self.logger.info(
+                    f'WeComBot ws: proactively sent text for synthetic event chat_id={chat_id} len={len(final_content)}'
+                )
+        except Exception:
+            await self.logger.error(f'WeComBot: synthetic event proactive send failed: {traceback.format_exc()}')
+            return {'stream': False, 'synthetic': True, 'error': True}
+
+        return {'stream': True, 'synthetic': True}
+
+    def _build_button_interaction_payload_from_form(
+        self, form_data: dict, *, user_id: str = '', chat_id: str = ''
+    ) -> dict:
+        """Build a button_interaction payload + track task_id for click resolution.
+
+        Unlike the inbound-event path (where push_form_pause registers the
+        task_id with the active stream session), proactive sends still
+        need the task_id registered so button clicks find pending_form.
+        For ws mode we stash it directly on the ws_client's pending dict.
+        """
+        from langbot.libs.wecom_ai_bot_api.api import build_human_input_template_card_payload
+        import secrets as _secrets
+
+        task_id = f'dify-{_secrets.token_hex(12)}'
+        source = getattr(self.bot, 'card_source', None)
+        payload = build_human_input_template_card_payload(
+            form_data,
+            task_id,
+            source=source,
+            select_as_buttons=not self.config.get('enable-webhook', False),
+        )
+
+        # Register task_id → form_data so the click callback can find it.
+        # user_id / chat_id are required so _on_card_action can route the
+        # resulting synthetic query back to the right user. msg_id / req_id
+        # / stream_id are intentionally empty — synthetic cards have no
+        # inbound message to anchor on.
+        if hasattr(self.bot, '_pending_forms_by_task'):
+            self.bot._pending_forms_by_task[task_id] = {
+                'form_data': form_data,
+                'msg_id': '',
+                'user_id': user_id,
+                'chat_id': chat_id,
+                'stream_id': '',
+                'req_id': '',
+            }
+        return payload
+
     async def send_message(self, target_type, target_id, message):
         _ws_mode = not self.config.get('enable-webhook', False)
         if _ws_mode:
@@ -531,3 +762,191 @@ class WecomBotAdapter(abstract_platform_adapter.AbstractMessagePlatformAdapter):
 
     async def is_muted(self, group_id: int) -> bool:
         pass
+
+    # ------------------------------------------------------------------
+    # Dify human-input button-interaction click handling
+    # ------------------------------------------------------------------
+
+    async def _on_card_action(self, session, action_id: str, task_id: str, raw_event: dict) -> None:
+        """Translate a button click on a button_interaction card into a
+        synthetic ``_dify_form_action`` query enqueued on the pool.
+
+        Pattern mirrors DingTalk / Lark / Telegram so the runner's
+        ``_merge_pending_form_action`` path resumes the workflow.
+        """
+        import langbot_plugin.api.entities.builtin.provider.session as provider_session
+
+        form = session.pending_form or {}
+        await self.logger.info(
+            f'WeComBot _on_card_action: task_id={task_id} action_id={action_id!r} '
+            f'form_token={form.get("form_token")!r} workflow_run_id={form.get("workflow_run_id")!r} '
+            f'session.user_id={session.user_id!r} session.chat_id={session.chat_id!r}'
+        )
+
+        actions = form.get('actions') or []
+        tce = extract_template_card_event_payload(raw_event) if isinstance(raw_event, dict) else {}
+        _, _, card_type = extract_template_card_action(tce)
+        selections = extract_template_card_selections(tce, form)
+        if not selections:
+            selections = parse_select_button_action(action_id, form)
+        await self.logger.info(
+            f'WeComBot template_card selections: task_id={task_id} card_type={card_type} selections={selections}'
+        )
+        if card_type == 'multiple_interaction' and not selections:
+            await self.logger.warning(
+                f'WeComBot: multiple_interaction callback has no parseable selections; raw={str(tce)[:1000]}'
+            )
+            return
+        is_select_submit = card_type == 'multiple_interaction' or bool(selections)
+
+        clean_action_id = '' if is_select_submit else (action_id or '').strip()
+        action_title = clean_action_id
+        for a in actions:
+            if str(a.get('id', '')) == clean_action_id:
+                action_title = a.get('title') or clean_action_id
+                break
+
+        inputs = dict(form.get('inputs') or {})
+        inputs.update(selections)
+
+        def _missing_fields_after_select() -> list[str]:
+            missing: list[str] = []
+            for field in form.get('input_defs') or form.get('all_input_defs') or []:
+                field_name = str(field.get('output_variable_name') or '').strip()
+                if not field_name:
+                    continue
+                if inputs.get(field_name) in (None, '', []):
+                    missing.append(field_name)
+            return missing
+
+        input_progress = False
+        if is_select_submit:
+            missing_fields = _missing_fields_after_select()
+            if not missing_fields and len(actions) == 1:
+                action = actions[0]
+                clean_action_id = str(action.get('id') or '').strip()
+                action_title = action.get('title') or clean_action_id
+            elif not missing_fields and len(actions) > 1:
+                if not self.config.get('enable-webhook', False):
+                    action_form_data = {
+                        'form_content': form.get('raw_form_content') or form.get('form_content') or '',
+                        'raw_form_content': form.get('raw_form_content') or form.get('form_content') or '',
+                        'input_defs': [],
+                        'all_input_defs': form.get('all_input_defs') or form.get('input_defs') or [],
+                        'inputs': inputs,
+                        'actions': actions,
+                        'node_title': form.get('node_title', ''),
+                        'workflow_run_id': form.get('workflow_run_id', ''),
+                        'form_token': form.get('form_token', ''),
+                        'pipeline_uuid': form.get('pipeline_uuid', ''),
+                        '_action_select_only': True,
+                    }
+                    target_chat_id = session.chat_id or session.user_id or ''
+                    try:
+                        payload = self._build_button_interaction_payload_from_form(
+                            action_form_data,
+                            user_id=session.user_id or '',
+                            chat_id=session.chat_id or '',
+                        )
+                        await self.bot.send_template_card(target_chat_id, payload)
+                        await self.logger.info(
+                            f'WeComBot: sent action-select button card after select submit '
+                            f'task_id={task_id} action_count={len(actions)}'
+                        )
+                    except Exception:
+                        await self.logger.error(
+                            f'WeComBot: failed to send action-select button card: {traceback.format_exc()}'
+                        )
+                    return
+                await self.logger.warning(
+                    'WeComBot webhook mode cannot proactively send action-select button card after select submit'
+                )
+                return
+            else:
+                input_progress = True
+                action_title = 'Submit'
+
+        launcher_id = session.user_id or session.chat_id or ''
+        sender_user_id = session.user_id or launcher_id
+        # WeCom AI bot has both single-chat and group-chat; chat_id present
+        # indicates group context.
+        if session.chat_id:
+            launcher_type = provider_session.LauncherTypes.GROUP
+            launcher_id = session.chat_id
+        else:
+            launcher_type = provider_session.LauncherTypes.PERSON
+            launcher_id = session.user_id or ''
+
+        form_action_data = {
+            'form_token': form.get('form_token', ''),
+            'workflow_run_id': form.get('workflow_run_id', ''),
+            'action_id': clean_action_id,
+            'action_title': action_title,
+            'node_title': form.get('node_title', ''),
+            'user': f'{launcher_type.value}_{launcher_id}',
+            'inputs': inputs,
+        }
+        if input_progress:
+            form_action_data['_input_progress'] = True
+
+        message_chain = platform_message.MessageChain([platform_message.Plain(text=f'[Form Action: {action_title}]')])
+
+        if launcher_type == provider_session.LauncherTypes.GROUP:
+            synthetic_event = platform_events.GroupMessage(
+                sender=platform_entities.GroupMember(
+                    id=sender_user_id,
+                    member_name='',
+                    permission=platform_entities.Permission.Member,
+                    group=platform_entities.Group(
+                        id=launcher_id,
+                        name='',
+                        permission=platform_entities.Permission.Member,
+                    ),
+                    special_title='',
+                ),
+                message_chain=message_chain,
+                time=int(time.time()),
+                source_platform_object=None,
+            )
+        else:
+            synthetic_event = platform_events.FriendMessage(
+                sender=platform_entities.Friend(
+                    id=sender_user_id,
+                    nickname='',
+                    remark='',
+                ),
+                message_chain=message_chain,
+                time=int(time.time()),
+                source_platform_object=None,
+            )
+
+        if self.ap is None:
+            await self.logger.error('WeComBot: ap not injected; cannot enqueue button-click query')
+            return
+
+        bot_uuid = ''
+        pipeline_uuid = form.get('pipeline_uuid') or None
+        for bot in self.ap.platform_mgr.bots:
+            if bot.adapter is self:
+                bot_uuid = bot.bot_entity.uuid
+                pipeline_uuid = pipeline_uuid or bot.bot_entity.use_pipeline_uuid
+                break
+
+        try:
+            await self.ap.query_pool.add_query(
+                bot_uuid=bot_uuid,
+                launcher_type=launcher_type,
+                launcher_id=launcher_id,
+                sender_id=sender_user_id,
+                message_event=synthetic_event,
+                message_chain=message_chain,
+                adapter=self,
+                pipeline_uuid=pipeline_uuid,
+                variables={
+                    '_dify_form_action': form_action_data,
+                    '_routed_by_rule': True,
+                },
+            )
+            await self.logger.info(f'WeComBot: button-click query enqueued action_id={clean_action_id!r}')
+        except Exception:
+            await self.logger.error(f'WeComBot: enqueue button-click query failed: {traceback.format_exc()}')

tests/unit_tests/platform/test_dingtalk_adapter.py

@@ -0,0 +1,254 @@
+"""Tests for DingTalk adapter helper behavior."""
+
+import asyncio
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from langbot.pkg.platform.sources.dingtalk import (
+    DingTalkAdapter,
+    _dingtalk_card_markdown,
+    _dingtalk_clean_form_content,
+    _dingtalk_completed_input_lines,
+    _dingtalk_extract_component_inputs,
+    _dingtalk_form_component_params,
+    _dingtalk_missing_completed_input_lines,
+    _dingtalk_pending_input_defs,
+)
+
+
+def test_dingtalk_select_component_params_expose_options():
+    params = _dingtalk_form_component_params(
+        {
+            '_current_input_field': 'choice',
+            'input_defs': [
+                {
+                    'output_variable_name': 'choice',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['A', 'B']},
+                }
+            ],
+            'inputs': {},
+        }
+    )
+
+    assert params['select_visible'] == 'true'
+    assert params['select_placeholder'] == 'choice'
+    assert params['select_options'] == ['A', 'B']
+    assert [option['value'] for option in params['index_o']] == ['A', 'B']
+    assert [option['value'] for option in params['test_index']] == ['A', 'B']
+    assert params['index_o'][0]['text']['zh_CN'] == 'A'
+    assert params['index_o'][0]['text']['en_US'] == 'A'
+    assert params['select_index'] == -1
+
+
+def test_dingtalk_extract_select_from_builtin_result_dict():
+    inputs = _dingtalk_extract_component_inputs({'selectResult': {'index': 1, 'value': 'B'}})
+
+    assert inputs == {'select': 'B'}
+
+
+def test_dingtalk_extract_select_from_template_param_string():
+    inputs = _dingtalk_extract_component_inputs({'select': '{"index": 1, "value": "B"}'})
+
+    assert inputs == {'select': '{"index": 1, "value": "B"}'}
+
+
+def test_dingtalk_extract_input_and_select_together():
+    inputs = _dingtalk_extract_component_inputs(
+        {
+            'inputResult': {'value': 'looks good'},
+            '__built_in_selectResult__': {'index': 0, 'value': 'A'},
+        }
+    )
+
+    assert inputs == {'input': 'looks good', 'select': 'A'}
+
+
+def test_dingtalk_extract_component_inputs_strips_card_line_endings():
+    inputs = _dingtalk_extract_component_inputs(
+        {
+            'inputResult': {'value': '回复我测试\r\n'},
+            'selectResult': {'value': '1\r'},
+        }
+    )
+
+    assert inputs == {'input': '回复我测试', 'select': '1'}
+
+
+def test_dingtalk_pending_input_defs_includes_file_fields():
+    pending = _dingtalk_pending_input_defs(
+        {
+            'input_defs': [
+                {'output_variable_name': 'comment', 'type': 'paragraph'},
+                {'output_variable_name': 'files', 'type': 'file-list'},
+            ],
+            'inputs': {'comment': 'ready'},
+        }
+    )
+
+    assert [field['output_variable_name'] for field in pending] == ['files']
+
+
+def test_dingtalk_completed_input_lines_include_text_and_select_values():
+    lines = _dingtalk_completed_input_lines(
+        {
+            'all_input_defs': [
+                {'output_variable_name': 'comment', 'type': 'paragraph'},
+                {
+                    'output_variable_name': 'choice',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['A', 'B']},
+                },
+            ],
+            'inputs': {'comment': 'looks good', 'choice': 'B'},
+        }
+    )
+
+    assert lines == ['✅ comment：looks good', '✅ choice：B']
+
+
+def test_dingtalk_completed_inputs_are_not_repeated_when_already_interleaved():
+    form_data = {
+        'all_input_defs': [
+            {'output_variable_name': 'us_input', 'type': 'paragraph'},
+            {'output_variable_name': 'xiala', 'type': 'select'},
+        ],
+        'inputs': {'us_input': '回复我测试\r', 'xiala': '1'},
+    }
+    form_content = '你好\n请输入你的问题\n✅ us_input：回复我测试\n请选择你的答案\n✅ xiala：1'
+
+    assert _dingtalk_missing_completed_input_lines(form_data, form_content) == []
+
+
+def test_dingtalk_completed_inputs_are_appended_when_template_does_not_render_them():
+    form_data = {
+        'all_input_defs': [{'output_variable_name': 'comment', 'type': 'paragraph'}],
+        'inputs': {'comment': 'ready'},
+    }
+
+    assert _dingtalk_missing_completed_input_lines(form_data, 'Please review') == ['✅ comment：ready']
+
+
+def test_dingtalk_clean_form_content_uses_all_input_defs():
+    content = _dingtalk_clean_form_content(
+        {
+            'raw_form_content': 'Hello\n\n{{#$output.comment#}}\n\n{{#$output.choice#}}\n',
+            'input_defs': [],
+            'all_input_defs': [
+                {'output_variable_name': 'comment', 'type': 'paragraph'},
+                {'output_variable_name': 'choice', 'type': 'select'},
+            ],
+        }
+    )
+
+    assert content == 'Hello'
+
+
+def test_dingtalk_field_stage_keeps_prior_prompts_and_completed_values():
+    content = _dingtalk_clean_form_content(
+        {
+            '_current_input_field': 'choice',
+            'raw_form_content': ('Question\n{{#$output.comment#}}\nChoose an answer\n{{#$output.choice#}}'),
+            'form_content': 'Choose an answer',
+            'input_defs': [
+                {'output_variable_name': 'comment', 'type': 'paragraph'},
+                {'output_variable_name': 'choice', 'type': 'select'},
+            ],
+            'inputs': {'comment': 'hello'},
+        }
+    )
+
+    assert '{{#$output.' not in content
+    assert content.index('Question') < content.index('comment')
+    assert content.index('comment') < content.index('Choose an answer')
+
+
+def test_dingtalk_final_action_stage_interleaves_prompts_and_completed_values():
+    content = _dingtalk_clean_form_content(
+        {
+            '_action_select_only': True,
+            'raw_form_content': ('11\nQuestion\n{{#$output.comment#}}\nChoose an answer\n{{#$output.choice#}}'),
+            'all_input_defs': [
+                {'output_variable_name': 'comment', 'type': 'paragraph'},
+                {'output_variable_name': 'choice', 'type': 'select'},
+            ],
+            'inputs': {'comment': 'hello', 'choice': 'B'},
+        }
+    )
+
+    assert '{{#$output.' not in content
+    assert content.startswith('11\nQuestion')
+    assert content.index('Question') < content.index('comment')
+    assert content.index('comment') < content.index('Choose an answer')
+    assert content.index('Choose an answer') < content.index('choice')
+
+
+def test_dingtalk_card_markdown_preserves_internal_line_breaks():
+    assert _dingtalk_card_markdown('11\nQuestion\nCompleted') == '11<br>Question<br>Completed'
+
+
+def _build_card_action_adapter() -> DingTalkAdapter:
+    adapter = DingTalkAdapter.model_construct(
+        card_state={
+            'card-1': {
+                'session_key': 'group_group-1',
+                'launcher_type': 'group',
+                'launcher_id': 'group-1',
+                'sender_user_id': 'initiator-1',
+                'form_token': 'token-1',
+                'workflow_run_id': 'run-1',
+                'actions': [{'id': 'approve', 'title': 'Approve'}],
+                'node_title': 'Review',
+                'form_content': 'Please review',
+                'input_defs': [],
+                'inputs': {},
+            }
+        },
+        active_turn_card={},
+        active_turn_text={},
+    )
+    adapter.logger = AsyncMock()
+    adapter.ap = MagicMock()
+    adapter.ap.platform_mgr.bots = []
+    adapter.ap.query_pool.add_query = AsyncMock()
+    return adapter
+
+
+@pytest.mark.asyncio
+async def test_dingtalk_group_card_action_uses_clicker_as_sender():
+    adapter = _build_card_action_adapter()
+
+    with patch.object(DingTalkAdapter, '_mark_card_resolved', new=AsyncMock()) as mark_resolved:
+        await adapter._on_card_action(
+            {
+                'out_track_id': 'card-1',
+                'user_id': 'reviewer-2',
+                'action_id': 'approve',
+                'params': {},
+            }
+        )
+        await asyncio.sleep(0)
+
+    call = adapter.ap.query_pool.add_query.await_args
+    assert call.kwargs['launcher_id'] == 'group-1'
+    assert call.kwargs['sender_id'] == 'reviewer-2'
+    assert call.kwargs['message_event'].sender.id == 'reviewer-2'
+    mark_resolved.assert_awaited_once()
+
+
+@pytest.mark.asyncio
+async def test_dingtalk_unknown_card_action_is_rejected():
+    adapter = _build_card_action_adapter()
+
+    await adapter._on_card_action(
+        {
+            'out_track_id': 'card-1',
+            'user_id': 'reviewer-2',
+            'action_id': 'not-on-card',
+            'params': {},
+        }
+    )
+
+    adapter.ap.query_pool.add_query.assert_not_awaited()
+    adapter.logger.warning.assert_awaited_once()

tests/unit_tests/platform/test_dingtalk_api.py

@@ -0,0 +1,42 @@
+"""Tests for DingTalk API payload helpers."""
+
+import json
+
+from langbot.libs.dingtalk_api.api import _stringify_card_param_map
+
+
+def test_dingtalk_card_param_map_stringifies_select_component_arrays():
+    params = _stringify_card_param_map(
+        {
+            'content': 'Pick one',
+            'btns': json.dumps([{'text': 'OK'}], ensure_ascii=False),
+            'select_options': ['A', 'B'],
+            'index_o': [
+                {
+                    'value': 'A',
+                    'text': {'zh_CN': 'A', 'en_US': 'A'},
+                }
+            ],
+            'test_index': [
+                {
+                    'value': 'A',
+                    'text': {'zh_CN': 'A', 'en_US': 'A'},
+                }
+            ],
+            'select_index': -1,
+        }
+    )
+
+    assert params['content'] == 'Pick one'
+    assert params['btns'] == '[{"text": "OK"}]'
+    assert params['select_options'] == '["A", "B"]'
+    assert json.loads(params['index_o'])[0]['value'] == 'A'
+    assert json.loads(params['test_index'])[0]['value'] == 'A'
+    assert params['select_index'] == '-1'
+
+
+def test_dingtalk_card_param_map_stringifies_unregistered_structures():
+    params = _stringify_card_param_map({'other': ['A'], 'empty': None})
+
+    assert params['other'] == '["A"]'
+    assert params['empty'] == ''

tests/unit_tests/platform/test_lark_adapter.py

@@ -0,0 +1,196 @@
+"""Tests for Lark adapter helper behavior."""
+
+from langbot.pkg.platform.sources.lark import (
+    LarkAdapter,
+    _lark_clean_form_content,
+    _lark_completed_input_lines,
+    _lark_current_input_defs,
+    _lark_extract_action_form_inputs,
+    _lark_should_update_stream_element,
+    _lark_visible_form_content,
+)
+
+
+def test_lark_current_input_defs_only_returns_active_stage():
+    input_defs = [
+        {'output_variable_name': 'us_input', 'type': 'paragraph'},
+        {'output_variable_name': 'xiala', 'type': 'select'},
+    ]
+
+    assert _lark_current_input_defs(
+        {
+            '_current_input_field': 'xiala',
+            'input_defs': input_defs,
+        }
+    ) == [input_defs[1]]
+    assert (
+        _lark_current_input_defs(
+            {
+                '_action_select_only': True,
+                'input_defs': input_defs,
+            }
+        )
+        == []
+    )
+
+
+def test_lark_form_field_elements_only_render_active_stage():
+    adapter = LarkAdapter.model_construct()
+    form_data = {
+        '_current_input_field': 'xiala',
+        'input_defs': [
+            {'output_variable_name': 'us_input', 'type': 'paragraph'},
+            {
+                'output_variable_name': 'xiala',
+                'type': 'select',
+                'option_source': {'type': 'constant', 'value': ['1', '2']},
+            },
+        ],
+    }
+
+    elements, input_name_map, file_help_lines = adapter._build_lark_form_field_elements(form_data)
+
+    assert len(elements) == 1
+    assert elements[0]['tag'] == 'select_static'
+    assert elements[0]['label']['content'] == 'xiala'
+    assert list(input_name_map.values()) == ['xiala']
+    assert file_help_lines == []
+
+
+def test_lark_form_stage_skips_closed_streaming_element_update():
+    assert not _lark_should_update_stream_element(
+        resume_from=False,
+        form_data={'_current_input_field': 'xiala'},
+        msg_seq=1,
+        is_final=True,
+    )
+    assert _lark_should_update_stream_element(
+        resume_from=False,
+        form_data=None,
+        msg_seq=1,
+        is_final=True,
+    )
+
+
+def test_lark_final_action_stage_interleaves_prompts_and_completed_values():
+    form_content = _lark_visible_form_content(
+        {
+            '_action_select_only': True,
+            'raw_form_content': ('11\nQuestion\n{{#$output.us_input#}}\nChoose an answer\n{{#$output.xiala#}}\n'),
+            'all_input_defs': [
+                {'output_variable_name': 'us_input', 'type': 'paragraph'},
+                {'output_variable_name': 'xiala', 'type': 'select'},
+            ],
+            'inputs': {'us_input': 'hello', 'xiala': '2'},
+        }
+    )
+
+    assert '{{#$output.' not in form_content
+    assert form_content.startswith('11\nQuestion')
+    assert form_content.index('Question') < form_content.index('us_input')
+    assert form_content.index('us_input') < form_content.index('Choose an answer')
+    assert form_content.index('Choose an answer') < form_content.index('xiala')
+
+
+def test_lark_completed_input_lines_include_text_select_and_files():
+    lines = _lark_completed_input_lines(
+        {
+            'all_input_defs': [
+                {'output_variable_name': 'us_input', 'type': 'paragraph'},
+                {'output_variable_name': 'xiala', 'type': 'select'},
+                {'output_variable_name': 'files', 'type': 'file-list'},
+            ],
+            'inputs': {
+                'us_input': '你好',
+                'xiala': 'or',
+                'files': [{'upload_file_id': 'file-1'}, {'upload_file_id': 'file-2'}],
+            },
+        }
+    )
+
+    assert lines == [
+        '✅ us_input：你好',
+        '✅ xiala：or',
+        '✅ files：2 file(s)',
+    ]
+
+
+def test_lark_clean_form_content_removes_all_input_placeholders():
+    content = _lark_clean_form_content(
+        '人工介入\n\n{{#$output.us_input#}}\n\n{{#$output.xiala#}}\n',
+        [
+            {'output_variable_name': 'us_input', 'type': 'paragraph'},
+            {'output_variable_name': 'xiala', 'type': 'select'},
+        ],
+    )
+
+    assert content == '人工介入'
+
+
+def test_lark_extract_action_form_inputs_from_json_form_value():
+    class Action:
+        form_value = '{"Input_1_us_input_abcd12": "hello", "Select_2_xiala_abcd12": "B"}'
+        input_value = None
+        option = None
+        name = None
+
+    inputs = _lark_extract_action_form_inputs(
+        Action(),
+        {
+            'input_name_map': {
+                'Input_1_us_input_abcd12': 'us_input',
+                'Select_2_xiala_abcd12': 'xiala',
+            }
+        },
+    )
+
+    assert inputs == {'us_input': 'hello', 'xiala': 'B'}
+
+
+def test_lark_extract_action_form_inputs_from_webhook_dict_action():
+    inputs = _lark_extract_action_form_inputs(
+        {
+            'form_value': {
+                'Input_1_us_input_abcd12': 'hello',
+                'Select_2_xiala_abcd12': {'value': 'B', 'text': {'content': 'Option B'}},
+            }
+        },
+        {
+            'input_name_map': {
+                'Input_1_us_input_abcd12': 'us_input',
+                'Select_2_xiala_abcd12': 'xiala',
+            }
+        },
+    )
+
+    assert inputs == {'us_input': 'hello', 'xiala': {'value': 'B', 'text': {'content': 'Option B'}}}
+
+
+def test_lark_extract_action_form_inputs_maps_dotted_component_names():
+    inputs = _lark_extract_action_form_inputs(
+        {
+            'form_value': {
+                'Form_1_token_abcd12.Input_1_us_input_abcd12': 'hello',
+            }
+        },
+        {
+            'input_name_map': {
+                'Input_1_us_input_abcd12': 'us_input',
+            }
+        },
+    )
+
+    assert inputs == {'us_input': 'hello'}
+
+
+def test_lark_completed_input_lines_display_select_value_from_object():
+    lines = _lark_completed_input_lines(
+        {
+            'all_input_defs': [
+                {'output_variable_name': 'xiala', 'type': 'select'},
+            ],
+            'inputs': {'xiala': {'value': 'B', 'text': {'content': 'Option B'}}},
+        }
+    )
+
+    assert lines == ['✅ xiala：B']

tests/unit_tests/platform/test_qqofficial_api.py

@@ -0,0 +1,224 @@
+"""Tests for QQ Official keyboard payload helpers."""
+
+import asyncio
+import time
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+
+from langbot.libs.qq_official_api.api import (
+    QQ_SELECT_ACTION_PREFIX,
+    build_keyboard_from_select_field,
+    get_select_field_options,
+    resolve_select_button_action,
+)
+
+
+def _select_form_data() -> dict:
+    return {
+        '_current_input_field': 'choice',
+        'input_defs': [
+            {
+                'output_variable_name': 'choice',
+                'type': 'select',
+                'option_source': {'type': 'constant', 'value': ['A', 'B', 'C']},
+            }
+        ],
+    }
+
+
+def test_qq_select_field_builds_callback_buttons():
+    keyboard = build_keyboard_from_select_field(_select_form_data(), buttons_per_row=2)
+
+    rows = keyboard['content']['rows']
+    assert [[button['render_data']['label'] for button in row['buttons']] for row in rows] == [
+        ['A', 'B'],
+        ['C'],
+    ]
+    assert rows[0]['buttons'][0]['action']['data'] == f'{QQ_SELECT_ACTION_PREFIX}0'
+    assert rows[0]['buttons'][1]['action']['data'] == f'{QQ_SELECT_ACTION_PREFIX}1'
+
+
+def test_qq_select_button_resolves_field_and_value():
+    form_data = _select_form_data()
+
+    assert get_select_field_options(form_data) == ('choice', ['A', 'B', 'C'])
+    assert resolve_select_button_action(form_data, f'{QQ_SELECT_ACTION_PREFIX}1') == ('choice', 'B')
+    assert resolve_select_button_action(form_data, f'{QQ_SELECT_ACTION_PREFIX}99') is None
+
+
+def test_qq_select_keyboard_fits_twenty_five_options():
+    form_data = _select_form_data()
+    form_data['input_defs'][0]['option_source']['value'] = [f'Option {idx}' for idx in range(25)]
+
+    rows = build_keyboard_from_select_field(form_data)['content']['rows']
+
+    assert len(rows) == 5
+    assert all(len(row['buttons']) == 5 for row in rows)
+
+
+def test_qq_non_select_field_does_not_build_keyboard():
+    form_data = {
+        '_current_input_field': 'comment',
+        'input_defs': [{'output_variable_name': 'comment', 'type': 'paragraph'}],
+    }
+
+    assert build_keyboard_from_select_field(form_data)['content']['rows'] == []
+
+
+def _stream_test_adapter():
+    from langbot.pkg.platform.sources.qqofficial import QQOfficialAdapter
+
+    adapter = QQOfficialAdapter.model_construct()
+    adapter.logger = AsyncMock()
+    adapter.bot = MagicMock()
+    adapter.bot.send_stream_msg = AsyncMock(return_value={'id': 'stream-1'})
+    adapter.bot.send_markdown_keyboard = AsyncMock(return_value={'id': 'message-1'})
+    adapter.ap = None
+    adapter._stream_ctx = {}
+    adapter._stream_ctx_ts = {}
+    adapter._fallback_text = {}
+    adapter._fallback_text_ts = {}
+    return adapter
+
+
+@pytest.mark.asyncio
+async def test_qq_stream_uses_cumulative_chunks_as_snapshots():
+    adapter = _stream_test_adapter()
+    adapter._stream_ctx['message-1'] = {
+        'user_openid': 'user-1',
+        'msg_id': 'source-1',
+        'stream_msg_id': None,
+        'msg_seq': 1,
+        'index': 0,
+        'last_update_ts': 0,
+        'accumulated_text': '',
+        'sent_length': 0,
+        'session_started': False,
+    }
+    adapter._stream_ctx_ts['message-1'] = time.time()
+    source = MagicMock()
+
+    await adapter.reply_message_chunk(
+        source,
+        {'resp_message_id': 'message-1'},
+        platform_message.MessageChain([platform_message.Plain(text='<think>one')]),
+    )
+    await adapter.reply_message_chunk(
+        source,
+        {'resp_message_id': 'message-1'},
+        platform_message.MessageChain([platform_message.Plain(text='<think>one two')]),
+        is_final=True,
+    )
+
+    assert [call.kwargs['content'] for call in adapter.bot.send_stream_msg.await_args_list] == [
+        '<think>one',
+        ' two',
+    ]
+
+
+@pytest.mark.asyncio
+async def test_qq_non_streaming_fallback_keeps_latest_snapshot_only():
+    from langbot.pkg.platform.sources.qqofficial import QQOfficialAdapter
+
+    adapter = _stream_test_adapter()
+    source = MagicMock()
+
+    with patch.object(QQOfficialAdapter, 'reply_message', new=AsyncMock()) as reply_message:
+        await adapter.reply_message_chunk(
+            source,
+            {'resp_message_id': 'message-1'},
+            platform_message.MessageChain([platform_message.Plain(text='Hel')]),
+        )
+        await adapter.reply_message_chunk(
+            source,
+            {'resp_message_id': 'message-1'},
+            platform_message.MessageChain([platform_message.Plain(text='Hello')]),
+            is_final=True,
+        )
+
+    sent_chain = reply_message.await_args.args[1]
+    assert str(sent_chain) == 'Hello'
+
+
+@pytest.mark.asyncio
+async def test_qq_text_field_prompt_keeps_form_content():
+    from langbot.pkg.platform.sources.qqofficial import QQOfficialAdapter
+
+    adapter = _stream_test_adapter()
+    adapter._pending_forms = {}
+    adapter._session_event_ids = {}
+    adapter._anchor_msg_seq = {}
+    source = MagicMock()
+    source.d_id = 'source-1'
+    source.t = 'C2C_MESSAGE_CREATE'
+    event = MagicMock()
+    event.source_platform_object = source
+    event.sender.id = 'user-1'
+    form_data = {
+        '_current_input_field': 'us_input',
+        'node_title': 'Manual input',
+        'form_content': '1234\nEnter your question',
+        'input_defs': [{'output_variable_name': 'us_input', 'type': 'paragraph'}],
+        'actions': [{'id': 'yes', 'title': 'yes'}],
+    }
+
+    with patch.object(QQOfficialAdapter, '_resolve_target_from_event', return_value=('c2c', 'user-1')):
+        await adapter._handle_form_chunk(event, platform_message.MessageChain([]), form_data)
+
+    send_call = adapter.bot.send_markdown_keyboard.await_args.kwargs
+    assert send_call['markdown_content'] == '### Manual input\n\n1234\nEnter your question'
+    assert send_call['keyboard'] is None
+
+
+@pytest.mark.asyncio
+async def test_qq_select_click_enqueues_input_progress_query():
+    import langbot.pkg.core.app  # noqa: F401
+    from langbot.pkg.platform.sources.qqofficial import QQOfficialAdapter
+
+    adapter = QQOfficialAdapter.model_construct()
+    adapter.logger = AsyncMock()
+    adapter.bot = MagicMock()
+    adapter.bot.ack_interaction = AsyncMock()
+    adapter.ap = MagicMock()
+    adapter.ap.platform_mgr.bots = []
+    adapter.ap.query_pool.add_query = AsyncMock()
+    adapter._pending_forms = {
+        'group_group-1': {
+            'form_data': {
+                **_select_form_data(),
+                'form_token': 'token-1',
+                'workflow_run_id': 'run-1',
+                'node_title': 'Review',
+                'actions': [{'id': 'approve', 'title': 'Approve'}],
+            },
+            'sender_id': 'initiator-1',
+            'posted_at': time.time(),
+        }
+    }
+    adapter._session_event_ids = {}
+    adapter._anchor_msg_seq = {}
+
+    await adapter._handle_interaction_create(
+        {
+            'id': 'interaction-1',
+            'chat_type': 1,
+            'group_openid': 'group-1',
+            'member_openid': 'reviewer-2',
+            'data': {'resolved': {'button_data': f'{QQ_SELECT_ACTION_PREFIX}1'}},
+        },
+        ws_event_id='event-1',
+    )
+    await asyncio.sleep(0)
+
+    call = adapter.ap.query_pool.add_query.await_args
+    form_action = call.kwargs['variables']['_dify_form_action']
+    assert call.kwargs['launcher_id'] == 'group-1'
+    assert call.kwargs['sender_id'] == 'reviewer-2'
+    assert form_action['action_id'] == ''
+    assert form_action['inputs'] == {'select': 'B'}
+    assert form_action['_current_input_field'] == 'choice'
+    assert form_action['_input_progress'] is True
+    adapter.bot.ack_interaction.assert_awaited_once_with('interaction-1', code=0)

tests/unit_tests/platform/test_telegram_adapter.py

@@ -0,0 +1,158 @@
+"""Tests for Telegram Dify form callback helpers."""
+
+import json
+from unittest.mock import AsyncMock, MagicMock
+
+import pytest
+from telegram import ForceReply
+
+import langbot_plugin.api.entities.builtin.platform.entities as platform_entities
+import langbot_plugin.api.entities.builtin.platform.events as platform_events
+import langbot_plugin.api.entities.builtin.platform.message as platform_message
+from langbot.pkg.platform.sources.telegram import (
+    TelegramAdapter,
+    _telegram_form_action_from_callback,
+    _telegram_select_field_options,
+)
+
+
+def _select_form_data() -> dict:
+    return {
+        '_current_input_field': 'choice',
+        'input_defs': [
+            {
+                'output_variable_name': 'choice',
+                'type': 'select',
+                'option_source': {'type': 'constant', 'value': ['A', 'B', 'C']},
+            }
+        ],
+    }
+
+
+def test_telegram_select_field_options_are_extracted():
+    assert _telegram_select_field_options(_select_form_data()) == ('choice', ['A', 'B', 'C'])
+
+
+def test_telegram_select_callback_becomes_input_progress():
+    assert _telegram_form_action_from_callback({'f': 1, 'x': 1}) == {
+        'action_id': '',
+        'inputs': {'select': {'index': 1}},
+        '_input_progress': True,
+    }
+
+
+def test_telegram_action_callback_remains_final_action():
+    assert _telegram_form_action_from_callback({'f': 1, 'a': 'approve'}) == {
+        'action_id': 'approve',
+        'inputs': {},
+    }
+
+
+def test_telegram_invalid_select_callback_is_rejected():
+    assert _telegram_form_action_from_callback({'f': 1, 'x': -1}) is None
+    assert _telegram_form_action_from_callback({'f': 1, 'x': 'invalid'}) is None
+
+
+def test_telegram_form_callback_cache_consumes_the_whole_form_group():
+    adapter = TelegramAdapter.model_construct()
+    adapter._form_action_titles = {}
+    adapter._cache_form_action_titles({'callback-a': 'A', 'callback-b': 'B'}, now=100.0)
+
+    assert adapter._take_form_action_title('callback-a', now=101.0) == 'A'
+    assert adapter._take_form_action_title('callback-a', now=101.0) is None
+    assert adapter._take_form_action_title('callback-b', now=101.0) is None
+    assert adapter._form_action_titles == {}
+
+
+def test_telegram_form_callback_cache_prunes_expired_entries():
+    adapter = TelegramAdapter.model_construct()
+    adapter._form_action_titles = {}
+    adapter._cache_form_action_titles({'callback-a': 'A'}, now=100.0)
+
+    assert adapter._take_form_action_title('callback-a', now=100.0 + adapter._FORM_ACTION_CACHE_TTL) is None
+    assert adapter._form_action_titles == {}
+
+
+def test_telegram_form_callback_cache_preserves_pipeline_uuid():
+    adapter = TelegramAdapter.model_construct()
+    adapter._form_action_titles = {}
+    adapter._cache_form_action_titles(
+        {'callback-a': 'Approve'},
+        pipeline_uuid='pipeline-routed',
+        now=100.0,
+    )
+
+    assert adapter._take_form_action_context('callback-a', now=101.0) == (
+        'Approve',
+        'pipeline-routed',
+    )
+
+
+@pytest.mark.asyncio
+async def test_telegram_select_field_sends_two_column_inline_keyboard():
+    bot = MagicMock()
+    bot.send_message = AsyncMock()
+    adapter = TelegramAdapter.model_construct(bot=bot, config={}, msg_stream_id={}, seq=1, listeners={})
+    adapter._form_action_titles = {}
+
+    update = MagicMock()
+    update.effective_chat.id = 123
+    update.effective_message.message_thread_id = None
+    event = platform_events.FriendMessage(
+        sender=platform_entities.Friend(id='user-1', nickname='', remark=''),
+        message_chain=platform_message.MessageChain([]),
+        source_platform_object=update,
+    )
+    form_data = {
+        **_select_form_data(),
+        'node_title': 'Review',
+        'form_content': 'Choose one',
+        'workflow_run_id': 'workflow-run-12345678',
+        'actions': [{'id': 'approve', 'title': 'Approve'}],
+    }
+
+    await adapter._send_form_action_buttons(event, form_data)
+
+    args = bot.send_message.await_args.kwargs
+    rows = args['reply_markup'].inline_keyboard
+    assert [[button.text for button in row] for row in rows] == [['A', 'B'], ['C']]
+    callback_data = rows[0][1].callback_data
+    assert len(callback_data.encode('utf-8')) <= 64
+    assert json.loads(callback_data)['x'] == 1
+    assert callback_data in adapter._form_action_titles
+
+
+@pytest.mark.asyncio
+async def test_telegram_text_field_does_not_show_action_buttons():
+    bot = MagicMock()
+    bot.send_message = AsyncMock()
+    adapter = TelegramAdapter.model_construct(bot=bot, config={}, msg_stream_id={}, seq=1, listeners={})
+    adapter._form_action_titles = {}
+
+    update = MagicMock()
+    update.effective_chat.id = 123
+    update.effective_message.message_thread_id = None
+    event = platform_events.FriendMessage(
+        sender=platform_entities.Friend(id='user-1', nickname='', remark=''),
+        message_chain=platform_message.MessageChain([]),
+        source_platform_object=update,
+    )
+    form_data = {
+        '_current_input_field': 'us_input',
+        'input_defs': [{'output_variable_name': 'us_input', 'type': 'paragraph'}],
+        'node_title': '人工介入',
+        'form_content': 'us_input (paragraph): reply "us_input: <value>"',
+        'workflow_run_id': 'workflow-run-12345678',
+        'actions': [{'id': 'yes', 'title': 'yes'}, {'id': 'no', 'title': 'no'}],
+    }
+
+    await adapter._send_form_action_buttons(event, form_data)
+
+    args = bot.send_message.await_args.kwargs
+    assert isinstance(args['reply_markup'], ForceReply)
+    assert args['reply_markup'].selective is False
+    assert args['reply_markup'].input_field_placeholder == 'us_input'
+    assert 'Please reply' not in args['text']
+    assert args['text'].startswith('[人工介入]')
+    assert 'us_input (paragraph)' in args['text']
+    assert adapter._form_action_titles == {}

tests/unit_tests/platform/test_wecombot_template_card.py

@@ -0,0 +1,475 @@
+import sys
+import types
+
+import pytest
+
+
+logger_module = types.ModuleType('langbot.pkg.platform.logger')
+logger_module.EventLogger = object
+sys.modules.setdefault('langbot.pkg.platform.logger', logger_module)
+
+from langbot.libs.wecom_ai_bot_api.api import (  # noqa: E402
+    WecomBotClient,
+    build_button_interaction_payload,
+    build_human_input_template_card_payload,
+    build_button_interaction_update_card,
+    build_multiple_interaction_update_card,
+    extract_template_card_event_payload,
+    extract_template_card_selections,
+    extract_wecom_event_type,
+    extract_template_card_action,
+    build_human_input_text_prompt,
+    parse_select_button_action,
+)
+from langbot.libs.wecom_ai_bot_api.ws_client import WecomBotWsClient  # noqa: E402
+
+
+def test_extract_template_card_action_supports_nested_button_key():
+    task_id, event_key, card_type = extract_template_card_action(
+        {
+            'taskId': 'task-1',
+            'cardType': 'button_interaction',
+            'button': {'key': 'approve'},
+        }
+    )
+
+    assert task_id == 'task-1'
+    assert event_key == 'approve'
+    assert card_type == 'button_interaction'
+
+
+def test_extract_wecom_event_type_supports_top_level_template_card_event():
+    payload = {
+        'eventtype': 'template_card_event',
+        'template_card_event': {
+            'TaskId': 'task-1',
+            'CardType': 'multiple_interaction',
+            'ResponseData': '{"select_list":[{"question_key":"choice","option_id":"opt_2"}]}',
+        },
+    }
+
+    assert extract_wecom_event_type(payload) == 'template_card_event'
+    assert extract_template_card_event_payload(payload)['TaskId'] == 'task-1'
+
+
+def test_extract_wecom_event_type_infers_template_card_event_from_top_level_card_fields():
+    payload = {
+        'TaskId': 'task-1',
+        'CardType': 'button_interaction',
+        'EventKey': 'approve',
+    }
+
+    assert extract_wecom_event_type(payload) == 'template_card_event'
+    assert extract_template_card_event_payload(payload)['EventKey'] == 'approve'
+
+
+def test_build_button_interaction_update_card_marks_clicked_button():
+    card = build_button_interaction_update_card(
+        {
+            'node_title': 'Manual Review',
+            'form_content': 'Please choose one action.',
+            'actions': [
+                {'id': 'approve', 'title': 'Approve', 'button_style': 'primary'},
+                {'id': 'reject', 'title': 'Reject', 'button_style': 'danger'},
+            ],
+        },
+        task_id='task-1',
+        action_id='reject',
+        source={'desc': 'LangBot'},
+    )
+
+    assert card['main_title'] == {'title': 'Manual Review'}
+    assert card['sub_title_text'] == 'Please choose one action.'
+    assert card['button_list'][0] == {'text': 'Approve', 'style': 2, 'key': 'approve'}
+    assert card['button_list'][1] == {
+        'text': '✅ Reject',
+        'style': 1,
+        'key': 'reject',
+        'replace_text': '✅ Reject',
+    }
+    assert card['source'] == {'desc': 'LangBot'}
+
+
+def test_build_button_interaction_payload_uses_preselected_button_styles_before_click():
+    payload = build_button_interaction_payload(
+        {
+            'node_title': 'Manual Review',
+            'actions': [
+                {'id': 'approve', 'title': 'Approve', 'button_style': 'primary'},
+                {'id': 'reject', 'title': 'Reject', 'button_style': 'danger'},
+            ],
+        },
+        task_id='task-1',
+    )
+
+    assert payload['template_card']['button_list'] == [
+        {'text': 'Approve', 'style': 2, 'key': 'approve'},
+        {'text': 'Reject', 'style': 2, 'key': 'reject'},
+    ]
+
+
+def test_build_payload_uses_multiple_interaction_for_pending_select_field():
+    payload = build_human_input_template_card_payload(
+        {
+            'node_title': 'Manual Review',
+            'form_content': 'Choose a label\n\n{{#$output.choice#}}',
+            'input_defs': [
+                {
+                    'output_variable_name': 'choice',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['A', 'B']},
+                }
+            ],
+            'inputs': {},
+            'actions': [{'id': 'yes', 'title': 'Yes'}],
+        },
+        task_id='task-1',
+        source={'desc': 'LangBot'},
+    )
+
+    card = payload['template_card']
+    assert card['card_type'] == 'multiple_interaction'
+    assert card['source'] == {'desc': 'LangBot'}
+    assert card['select_list'] == [
+        {
+            'question_key': 'choice',
+            'title': 'choice',
+            'selected_id': 'opt_1',
+            'option_list': [
+                {'id': 'opt_1', 'text': 'A'},
+                {'id': 'opt_2', 'text': 'B'},
+            ],
+        }
+    ]
+    assert card['submit_button'] == {'text': 'Submit', 'key': 'submit_human_input'}
+
+
+def test_build_payload_can_emulate_select_as_buttons_for_wecombot_ws():
+    form_data = {
+        'node_title': 'Manual Review',
+        'form_content': 'Choose a label\n\n{{#$output.choice#}}',
+        'input_defs': [
+            {
+                'output_variable_name': 'choice',
+                'type': 'select',
+                'option_source': {'type': 'constant', 'value': ['A', 'B']},
+            }
+        ],
+        'inputs': {},
+        'actions': [{'id': 'yes', 'title': 'Yes'}],
+    }
+    payload = build_human_input_template_card_payload(
+        form_data,
+        task_id='task-1',
+        select_as_buttons=True,
+    )
+
+    card = payload['template_card']
+    assert card['card_type'] == 'button_interaction'
+    assert card['button_list'][0]['text'] == 'A'
+    assert parse_select_button_action(card['button_list'][1]['key'], form_data) == {'choice': 'B'}
+
+
+def test_text_input_card_uses_current_stage_content_without_direct_reply_prompt():
+    payload = build_human_input_template_card_payload(
+        {
+            'node_title': '人工介入',
+            'form_content': '11\n请输入你的问题\n\n{{#$output.us_input#}}',
+            'raw_form_content': ('11\n请输入你的问题\n{{#$output.us_input#}}\n请选择你的答案\n{{#$output.xiala#}}'),
+            'input_defs': [
+                {
+                    'output_variable_name': 'us_input',
+                    'type': 'paragraph',
+                    'label': '请输入你的问题',
+                }
+            ],
+            'inputs': {},
+            'actions': [{'id': 'yes', 'title': 'yes'}],
+            '_current_input_field': 'us_input',
+        },
+        task_id='task-1',
+    )
+
+    card = payload['template_card']
+    assert 'desc' not in card['main_title']
+    assert card['sub_title_text'] == '11\n请输入你的问题'
+    assert card['button_list'] == []
+
+
+def test_build_human_input_text_prompt_for_current_text_field():
+    prompt = build_human_input_text_prompt(
+        {
+            'node_title': '人工介入',
+            'form_content': '11\n请输入你的问题\n{{#$output.us_input#}}',
+            'raw_form_content': ('11\n请输入你的问题\n{{#$output.us_input#}}\n请选择你的答案\n{{#$output.xiala#}}'),
+            'input_defs': [
+                {
+                    'output_variable_name': 'us_input',
+                    'type': 'paragraph',
+                    'label': '请输入你的问题',
+                }
+            ],
+            '_current_input_field': 'us_input',
+        }
+    )
+
+    assert prompt == '人工介入\n\n11\n请输入你的问题'
+
+
+@pytest.mark.asyncio
+async def test_ws_push_form_pause_sends_text_prompt_without_empty_card():
+    client = WecomBotWsClient('bot-id', 'secret', object())
+    client._stream_ids['msg-1'] = 'req-1|stream-1'
+    client._stream_sessions['msg-1'] = {'user_id': 'user-1'}
+    sent = []
+
+    async def fake_reply_text(req_id, content):
+        sent.append((req_id, content))
+        return {}
+
+    client.reply_text = fake_reply_text
+
+    ok, stream_id, task_id = await client.push_form_pause(
+        'msg-1',
+        {
+            'node_title': '人工介入',
+            'form_content': '11\n请输入你的问题\n{{#$output.us_input#}}',
+            'raw_form_content': ('11\n请输入你的问题\n{{#$output.us_input#}}\n请选择你的答案\n{{#$output.xiala#}}'),
+            'input_defs': [
+                {
+                    'output_variable_name': 'us_input',
+                    'type': 'paragraph',
+                    'label': '请输入你的问题',
+                }
+            ],
+            '_current_input_field': 'us_input',
+        },
+    )
+
+    assert ok is True
+    assert stream_id == 'stream-1'
+    assert task_id is None
+    assert sent == [('req-1', '人工介入\n\n11\n请输入你的问题')]
+    assert client._pending_forms_by_task == {}
+    assert 'msg-1' not in client._stream_ids
+
+
+@pytest.mark.asyncio
+async def test_ws_stream_sends_cumulative_snapshots_to_wecom():
+    client = WecomBotWsClient('bot-id', 'secret', object())
+    client._stream_ids['msg-1'] = 'req-1|stream-1'
+    client._stream_sessions['msg-1'] = {}
+    sent = []
+
+    async def fake_reply_stream(req_id, stream_id, content, finish=False, feedback_id=''):
+        sent.append((req_id, stream_id, content, finish))
+        return {}
+
+    client.reply_stream = fake_reply_stream
+
+    assert await client.push_stream_chunk('msg-1', '你', is_final=False)
+    assert await client.push_stream_chunk('msg-1', '你好', is_final=False)
+    assert await client.push_stream_chunk('msg-1', '你好', is_final=True)
+
+    assert sent == [
+        ('req-1', 'stream-1', '你', False),
+        ('req-1', 'stream-1', '你好', False),
+        ('req-1', 'stream-1', '你好', True),
+    ]
+
+
+@pytest.mark.asyncio
+async def test_webhook_stream_queues_cumulative_snapshots_for_followups():
+    client = WecomBotClient('', '', '', object(), unified_mode=True)
+    session, _ = client.stream_sessions.create_or_get({'msgid': 'msg-1', 'chatid': '', 'from': {'userid': 'user-1'}})
+
+    assert await client.push_stream_chunk('msg-1', '你', is_final=False)
+    assert await client.push_stream_chunk('msg-1', '你好', is_final=False)
+    assert await client.push_stream_chunk('msg-1', '你好', is_final=True)
+
+    chunks = [
+        await client.stream_sessions.consume(session.stream_id),
+        await client.stream_sessions.consume(session.stream_id),
+        await client.stream_sessions.consume(session.stream_id),
+    ]
+    assert [(chunk.content, chunk.is_final) for chunk in chunks] == [
+        ('你', False),
+        ('你好', False),
+        ('你好', True),
+    ]
+
+
+def test_human_input_payload_keeps_action_select_stage_as_buttons():
+    payload = build_human_input_template_card_payload(
+        {
+            'node_title': 'Manual Review',
+            'input_defs': [
+                {
+                    'output_variable_name': 'choice',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['A', 'B']},
+                }
+            ],
+            'inputs': {'choice': 'B'},
+            'actions': [
+                {'id': 'approve', 'title': 'Approve'},
+                {'id': 'reject', 'title': 'Reject'},
+            ],
+            '_action_select_only': True,
+        },
+        task_id='task-1',
+    )
+
+    card = payload['template_card']
+    assert card['card_type'] == 'button_interaction'
+    assert card['button_list'] == [
+        {'text': 'Approve', 'style': 2, 'key': 'approve'},
+        {'text': 'Reject', 'style': 2, 'key': 'reject'},
+    ]
+
+
+def test_extract_template_card_selections_maps_selected_id_to_option_text():
+    selections = extract_template_card_selections(
+        {
+            'SelectedItems': [
+                {'QuestionKey': 'choice', 'SelectedId': 'opt_2'},
+            ],
+        },
+        {
+            'input_defs': [
+                {
+                    'output_variable_name': 'choice',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['A', 'B']},
+                }
+            ],
+        },
+    )
+
+    assert selections == {'choice': 'B'}
+
+
+def test_extract_template_card_selections_reads_nested_response_data_json():
+    selections = extract_template_card_selections(
+        {
+            'CardType': 'multiple_interaction',
+            'ResponseData': '{"select_list":[{"question_key":"choice","option_id":"opt_2"}]}',
+        },
+        {
+            'input_defs': [
+                {
+                    'output_variable_name': 'choice',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['A', 'B']},
+                }
+            ],
+        },
+    )
+
+    assert selections == {'choice': 'B'}
+
+
+def test_extract_template_card_selections_reads_response_data_direct_mapping():
+    selections = extract_template_card_selections(
+        {
+            'CardType': 'multiple_interaction',
+            'EventKey': 'submit_human_input',
+            'ResponseData': '{"choice":"opt_2"}',
+        },
+        {
+            'input_defs': [
+                {
+                    'output_variable_name': 'choice',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['A', 'B']},
+                }
+            ],
+        },
+    )
+
+    assert selections == {'choice': 'B'}
+
+
+def test_build_multiple_interaction_update_card_disables_selected_value_without_submitted_text():
+    card = build_multiple_interaction_update_card(
+        {
+            'node_title': 'Manual Review',
+            'form_content': 'Choose a label\n{{#$output.choice#}}',
+            'raw_form_content': 'Choose a label\n{{#$output.choice#}}',
+            'input_defs': [
+                {
+                    'output_variable_name': 'choice',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['A', 'B']},
+                }
+            ],
+            '_current_input_field': 'choice',
+        },
+        task_id='task-1',
+        selections={'choice': 'B'},
+    )
+
+    assert card['card_type'] == 'multiple_interaction'
+    assert card['main_title']['desc'] == 'Choose a label\n✅ choice：B'
+    assert card['submit_button']['text'] == '✅'
+    assert card['select_list'][0]['disable'] is True
+    assert card['select_list'][0]['selected_id'] == 'opt_2'
+
+
+def test_select_stage_only_shows_current_prompt_in_a_separate_message():
+    raw_content = '11\n请输入你的问题\n{{#$output.us_input#}}\n请选择你的答案\n{{#$output.xiala#}}'
+    payload = build_human_input_template_card_payload(
+        {
+            'node_title': '人工介入',
+            'form_content': '请选择你的答案\n{{#$output.xiala#}}',
+            'raw_form_content': raw_content,
+            'input_defs': [
+                {
+                    'output_variable_name': 'xiala',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['1', '2']},
+                }
+            ],
+            'all_input_defs': [
+                {'output_variable_name': 'us_input', 'type': 'paragraph'},
+                {
+                    'output_variable_name': 'xiala',
+                    'type': 'select',
+                    'option_source': {'type': 'constant', 'value': ['1', '2']},
+                },
+            ],
+            'inputs': {'us_input': '你叫啥'},
+            '_current_input_field': 'xiala',
+        },
+        task_id='task-1',
+    )
+
+    assert payload['template_card']['main_title']['desc'] == '请选择你的答案'
+
+
+def test_action_stage_only_shows_content_after_fields_without_placeholders():
+    raw_content = '11\n请输入你的问题\n{{#$output.us_input#}}\n请选择你的答案\n{{#$output.xiala#}}\n请选择操作'
+    payload = build_human_input_template_card_payload(
+        {
+            'node_title': '人工介入',
+            'form_content': raw_content,
+            'raw_form_content': raw_content,
+            'input_defs': [],
+            'all_input_defs': [
+                {'output_variable_name': 'us_input', 'type': 'paragraph'},
+                {'output_variable_name': 'xiala', 'type': 'select'},
+            ],
+            'inputs': {'us_input': '你叫啥', 'xiala': '2'},
+            'actions': [
+                {'id': 'yes', 'title': 'yes'},
+                {'id': 'no', 'title': 'no'},
+            ],
+            '_action_select_only': True,
+        },
+        task_id='task-1',
+    )
+
+    card = payload['template_card']
+    assert card['sub_title_text'] == '请选择操作'
+    assert '{{#$output.' not in card['sub_title_text']
+    assert [button['text'] for button in card['button_list']] == ['yes', 'no']

web/src/app/home/bots/components/bot-form/BotForm.tsx

@@ -269,6 +269,10 @@ export default function BotForm({
               options: item.options,
               show_if: item.show_if,
               login_platform: item.login_platform,
+              url: item.url,
+              download_filename: item.download_filename,
+              help_links: item.help_links,
+              help_label: item.help_label,
             }),
         ),
       );

web/src/app/home/components/dynamic-form/DynamicFormComponent.tsx

@@ -24,7 +24,15 @@ import { useTranslation } from 'react-i18next';
 import { cn } from '@/lib/utils';
 import { Input } from '@/components/ui/input';
 import { Button } from '@/components/ui/button';
-import { Copy, Check, Globe, Info, QrCode } from 'lucide-react';
+import {
+  Copy,
+  Check,
+  Globe,
+  Info,
+  QrCode,
+  Download,
+  ExternalLink,
+} from 'lucide-react';
 import { copyToClipboard } from '@/app/utils/clipboard';
 import {
   Tooltip,
@@ -33,6 +41,7 @@ import {
   TooltipTrigger,
 } from '@/components/ui/tooltip';
 import { systemInfo } from '@/app/infra/http';
+import { getAdapterDocUrl } from '@/app/infra/entities/adapter-docs';
 
 /**
  * Resolve the value referenced by a `show_if.field` string.
@@ -291,6 +300,52 @@ function WebhookUrlField({
   );
 }
 
+function DownloadLinkField({
+  label,
+  description,
+  url,
+  filename,
+  helpUrl,
+  helpLabel,
+}: {
+  label: string;
+  description?: string;
+  url: string;
+  filename?: string;
+  helpUrl?: string | null;
+  helpLabel: string;
+}) {
+  const baseUrl = import.meta.env.VITE_API_BASE_URL || window.location.origin;
+  const downloadUrl = url.startsWith('http') ? url : `${baseUrl}${url}`;
+
+  return (
+    <FormItem className="min-w-0">
+      <FormLabel className="break-words">{label}</FormLabel>
+      <div className="flex min-w-0 flex-wrap items-center gap-2">
+        <Button asChild variant="outline" size="sm">
+          <a href={downloadUrl} download={filename}>
+            <Download className="h-4 w-4" />
+            {label}
+          </a>
+        </Button>
+        {helpUrl && (
+          <Button asChild variant="ghost" size="sm">
+            <a href={helpUrl} target="_blank" rel="noopener noreferrer">
+              <ExternalLink className="h-4 w-4" />
+              {helpLabel}
+            </a>
+          </Button>
+        )}
+      </div>
+      {description && (
+        <p className="max-w-2xl text-sm break-words text-muted-foreground">
+          {description}
+        </p>
+      )}
+    </FormItem>
+  );
+}
+
 /**
  * Display-only component for `__system.*` fields (e.g. the deployment's
  * outbound IPs that the operator must add to a platform's trusted-IP list).
@@ -405,7 +460,7 @@ export default function DynamicFormComponent({
 }) {
   const isInitialMount = useRef(true);
   const previousInitialValues = useRef(initialValues);
-  const { t } = useTranslation();
+  const { t, i18n } = useTranslation();
 
   // Normalize a form value according to its field type.
   // This ensures legacy/malformed data (e.g. a plain string for
@@ -460,6 +515,7 @@ export default function DynamicFormComponent({
           item.type !== 'webhook-url' &&
           item.type !== 'embed-code' &&
           item.type !== 'qr-code-login' &&
+          item.type !== 'download-link' &&
           !item.name.startsWith(SYSTEM_FIELD_PREFIX),
       ),
     [itemConfigList],
@@ -777,6 +833,30 @@ export default function DynamicFormComponent({
             );
           }
 
+          if (config.type === 'download-link') {
+            if (!config.url) return null;
+
+            return (
+              <DownloadLinkField
+                key={config.id}
+                label={extractI18nObject(config.label)}
+                description={
+                  config.description
+                    ? extractI18nObject(config.description)
+                    : undefined
+                }
+                url={config.url}
+                filename={config.download_filename}
+                helpUrl={getAdapterDocUrl(config.help_links, i18n.language)}
+                helpLabel={
+                  config.help_label
+                    ? extractI18nObject(config.help_label)
+                    : t('bots.viewAdapterDocs')
+                }
+              />
+            );
+          }
+
           // QR code login button (e.g. Feishu one-click create, WeChat scan login)
           if (config.type === 'qr-code-login') {
             return (

web/src/app/home/components/dynamic-form/DynamicFormItemConfig.ts

@@ -18,6 +18,10 @@ export class DynamicFormItemConfig implements IDynamicFormItemSchema {
   options?: IDynamicFormItemOption[];
   show_if?: IShowIfCondition;
   login_platform?: string;
+  url?: string;
+  download_filename?: string;
+  help_links?: Record<string, string>;
+  help_label?: I18nObject;
 
   constructor(params: IDynamicFormItemSchema) {
     this.id = params.id;
@@ -30,6 +34,10 @@ export class DynamicFormItemConfig implements IDynamicFormItemSchema {
     this.options = params.options;
     this.show_if = params.show_if;
     this.login_platform = params.login_platform;
+    this.url = params.url;
+    this.download_filename = params.download_filename;
+    this.help_links = params.help_links;
+    this.help_label = params.help_label;
   }
 }
 

web/src/app/home/components/qrcode-login/QrCodeLoginDialog.tsx

@@ -16,7 +16,12 @@ import {
 } from 'lucide-react';
 import QRCode from 'qrcode';
 
-export type QrLoginPlatform = 'feishu' | 'weixin' | 'dingtalk' | 'wecombot';
+export type QrLoginPlatform =
+  | 'feishu'
+  | 'weixin'
+  | 'dingtalk'
+  | 'wecombot'
+  | 'qqofficial';
 
 interface PlatformConfig {
   titleKey: string;
@@ -29,6 +34,7 @@ interface PlatformConfig {
   apiBase: string;
   extractSuccess: (data: Record<string, string>) => Record<string, string>;
   successNoteKey?: string;
+  boundByKey?: string;
 }
 
 const PLATFORM_CONFIGS: Record<QrLoginPlatform, PlatformConfig> = {
@@ -92,6 +98,22 @@ const PLATFORM_CONFIGS: Record<QrLoginPlatform, PlatformConfig> = {
     }),
     successNoteKey: 'wecombot.robotNameNote',
   },
+  qqofficial: {
+    titleKey: 'qqofficial.createBinding',
+    connectingKey: 'qqofficial.connecting',
+    scanQRCodeKey: 'qqofficial.scanQRCode',
+    waitingKey: 'qqofficial.waitingForScan',
+    successKey: 'qqofficial.bindSuccess',
+    failedKey: 'qqofficial.bindFailed',
+    retryKey: 'qqofficial.retry',
+    apiBase: '/api/v1/platform/adapters/qqofficial/bind',
+    extractSuccess: (data) => ({
+      appid: data.appid,
+      secret: data.secret,
+    }),
+    successNoteKey: 'qqofficial.tokenNote',
+    boundByKey: 'qqofficial.boundBy',
+  },
 };
 
 interface QrCodeLoginDialogProps {
@@ -118,6 +140,7 @@ export default function QrCodeLoginDialog({
   const [qrDataUrl, setQrDataUrl] = useState('');
   const [expireIn, setExpireIn] = useState(0);
   const [errorMessage, setErrorMessage] = useState('');
+  const [successMeta, setSuccessMeta] = useState('');
   const pollTimerRef = useRef<ReturnType<typeof setInterval> | null>(null);
   const countdownRef = useRef<ReturnType<typeof setInterval> | null>(null);
   const checkExpiredRef = useRef<ReturnType<typeof setInterval> | null>(null);
@@ -178,6 +201,7 @@ export default function QrCodeLoginDialog({
     setQrDataUrl('');
     setExpireIn(0);
     setErrorMessage('');
+    setSuccessMeta('');
 
     const token = localStorage.getItem('token');
     const baseUrl = import.meta.env.VITE_API_BASE_URL || window.location.origin;
@@ -275,6 +299,13 @@ export default function QrCodeLoginDialog({
             sessionIdRef.current = null;
             cleanup();
             setState('success');
+            // Platform may return extra audit metadata (e.g. QQ Official returns
+            // the scanner's user_openid) — surface it briefly before the dialog closes.
+            if (rest.user_openid && cfg.boundByKey) {
+              setSuccessMeta(
+                tRef.current(cfg.boundByKey, { openid: rest.user_openid }),
+              );
+            }
             setTimeout(() => {
               onSuccessRef.current(cfg.extractSuccess(rest));
               onOpenChangeRef.current(false);
@@ -395,6 +426,11 @@ export default function QrCodeLoginDialog({
               <p className="text-sm text-green-600 font-medium">
                 {t(platformConfig.successKey)}
               </p>
+              {successMeta && (
+                <p className="text-xs text-muted-foreground text-center max-w-xs break-all">
+                  {successMeta}
+                </p>
+              )}
               {platformConfig.successNoteKey && (
                 <p className="text-xs text-muted-foreground text-center max-w-xs">
                   {t(platformConfig.successNoteKey)}

web/src/app/infra/entities/form/dynamic.ts

@@ -44,6 +44,10 @@ export interface IDynamicFormItemSchema {
   scopes?: string[];
   accept?: string; // For file type: accepted MIME types
   login_platform?: string; // For qr-code-login type: platform identifier (e.g. 'feishu', 'weixin')
+  url?: string; // For download-link type: relative or absolute download URL
+  download_filename?: string; // Optional filename for download-link type
+  help_links?: Record<string, string>; // Optional docs links for display-only fields
+  help_label?: I18nObject; // Optional label for help_links
 }
 
 export enum DynamicFormItemType {
@@ -72,6 +76,7 @@ export enum DynamicFormItemType {
   WEBHOOK_URL = 'webhook-url',
   EMBED_CODE = 'embed-code',
   QR_CODE_LOGIN = 'qr-code-login',
+  DOWNLOAD_LINK = 'download-link',
 }
 
 export interface IFileConfig {

web/src/app/wizard/page.tsx

@@ -229,6 +229,10 @@ export default function WizardPage() {
           options: item.options,
           show_if: item.show_if,
           login_platform: item.login_platform,
+          url: item.url,
+          download_filename: item.download_filename,
+          help_links: item.help_links,
+          help_label: item.help_label,
         }),
     );
   }, [adapters, selectedAdapter]);
@@ -249,6 +253,10 @@ export default function WizardPage() {
           options: item.options,
           show_if: item.show_if,
           login_platform: item.login_platform,
+          url: item.url,
+          download_filename: item.download_filename,
+          help_links: item.help_links,
+          help_label: item.help_label,
         }),
     );
   }, [selectedRunnerConfigStage]);

web/src/i18n/locales/en-US.ts

@@ -1822,6 +1822,19 @@ const enUS = {
     robotNameNote:
       'Robot Name cannot be obtained automatically. Please fill it in manually.',
   },
+  qqofficial: {
+    createBinding: 'One-Click QR Binding for QQ Official Bot',
+    scanQRCode:
+      'Scan the QR code below with mobile QQ and authorize the binding in QQ Bot Assistant',
+    waitingForScan: 'Waiting for scan',
+    bindSuccess: 'Bound successfully! AppID and Secret have been filled in',
+    bindFailed: 'Binding failed',
+    connecting: 'Connecting to QQ service...',
+    retry: 'Retry',
+    tokenNote:
+      'The Token field is not used by the current adapter — you can leave it blank.',
+    boundBy: 'Bound by QQ user {{openid}}',
+  },
   pluginPages: {
     selectFromSidebar: 'Select a plugin page from the sidebar',
     invalidPage: 'Invalid plugin page',

web/src/i18n/locales/es-ES.ts

@@ -1740,6 +1740,20 @@ const esES = {
     robotNameNote:
       'El nombre del robot no puede obtenerse automáticamente. Introdúcelo manualmente.',
   },
+  qqofficial: {
+    createBinding: 'Vinculación QR con un clic para el bot oficial de QQ',
+    scanQRCode:
+      'Escanea el código QR siguiente con QQ móvil y autoriza la vinculación en «QQ Bot Assistant»',
+    waitingForScan: 'Esperando escaneo',
+    bindSuccess:
+      '¡Vinculación correcta! AppID y Secret se han rellenado automáticamente',
+    bindFailed: 'Error en la vinculación',
+    connecting: 'Conectando con el servicio de QQ...',
+    retry: 'Reintentar',
+    tokenNote:
+      'El campo Token no es utilizado por el adaptador actual; puedes dejarlo vacío.',
+    boundBy: 'Vinculado por el usuario QQ {{openid}}',
+  },
   pluginPages: {
     selectFromSidebar: 'Selecciona una página de plugin en la barra lateral',
     invalidPage: 'Página de plugin no válida',

web/src/i18n/locales/ja-JP.ts

@@ -1733,6 +1733,19 @@ const jaJP = {
     retry: '再試行',
     robotNameNote: 'ロボット名は自動取得できません。手動で入力してください。',
   },
+  qqofficial: {
+    createBinding: 'ワンクリックで QQ 公式ボットを QR バインド',
+    scanQRCode:
+      '以下の QR コードをモバイル QQ でスキャンし、「QQ ボットアシスタント」でバインドを承認してください',
+    waitingForScan: 'スキャン待ち',
+    bindSuccess: 'バインド成功！AppID と Secret が自動入力されました',
+    bindFailed: 'バインド失敗',
+    connecting: 'QQ サービスに接続中...',
+    retry: '再試行',
+    tokenNote:
+      'Token フィールドは現行アダプターでは使用しません。空欄のままで構いません。',
+    boundBy: 'QQ ユーザー {{openid}} によりバインドされました',
+  },
   pluginPages: {
     selectFromSidebar: 'サイドバーからプラグインページを選択してください',
     invalidPage: '無効なプラグインページ',

web/src/i18n/locales/ru-RU.ts

@@ -1711,6 +1711,19 @@ const ruRU = {
     robotNameNote:
       'Имя бота нельзя получить автоматически. Пожалуйста, введите его вручную.',
   },
+  qqofficial: {
+    createBinding: 'Привязка официального бота QQ по QR-коду',
+    scanQRCode:
+      'Отсканируйте QR-код ниже мобильным QQ и подтвердите привязку в «QQ Bot Assistant»',
+    waitingForScan: 'Ожидание сканирования',
+    bindSuccess: 'Привязка успешна! AppID и Secret заполнены автоматически',
+    bindFailed: 'Не удалось выполнить привязку',
+    connecting: 'Подключение к сервису QQ...',
+    retry: 'Повторить',
+    tokenNote:
+      'Поле Token не используется текущим адаптером — его можно оставить пустым.',
+    boundBy: 'Привязано пользователем QQ {{openid}}',
+  },
   pluginPages: {
     selectFromSidebar: 'Выберите страницу плагина на боковой панели',
     invalidPage: 'Недопустимая страница плагина',

web/src/i18n/locales/th-TH.ts

@@ -1672,6 +1672,18 @@ const thTH = {
     retry: 'ลองใหม่',
     robotNameNote: 'ไม่สามารถดึงชื่อบอตได้โดยอัตโนมัติ กรุณากรอกด้วยตนเอง',
   },
+  qqofficial: {
+    createBinding: 'ผูกบอต QQ Official ด้วย QR คลิกเดียว',
+    scanQRCode:
+      'สแกนคิวอาร์โค้ดด้านล่างด้วย QQ มือถือ แล้วอนุญาตการผูกใน «QQ Bot Assistant»',
+    waitingForScan: 'กำลังรอสแกน',
+    bindSuccess: 'ผูกสำเร็จ! AppID และ Secret ถูกกรอกอัตโนมัติแล้ว',
+    bindFailed: 'การผูกล้มเหลว',
+    connecting: 'กำลังเชื่อมต่อบริการ QQ...',
+    retry: 'ลองใหม่',
+    tokenNote: 'อะแดปเตอร์ปัจจุบันไม่ได้ใช้ฟิลด์ Token จึงเว้นว่างไว้ได้',
+    boundBy: 'ผูกโดยผู้ใช้ QQ {{openid}}',
+  },
   pluginPages: {
     selectFromSidebar: 'เลือกหน้าปลั๊กอินจากแถบด้านข้าง',
     invalidPage: 'หน้าปลั๊กอินไม่ถูกต้อง',

web/src/i18n/locales/vi-VN.ts

@@ -1701,6 +1701,19 @@ const viVN = {
     retry: 'Thử lại',
     robotNameNote: 'Không thể tự động lấy tên bot. Vui lòng điền thủ công.',
   },
+  qqofficial: {
+    createBinding: 'Liên kết bot QQ Official bằng QR một chạm',
+    scanQRCode:
+      'Quét mã QR bên dưới bằng QQ trên di động và xác nhận liên kết trong «QQ Bot Assistant»',
+    waitingForScan: 'Đang chờ quét',
+    bindSuccess: 'Liên kết thành công! AppID và Secret đã được điền tự động',
+    bindFailed: 'Liên kết thất bại',
+    connecting: 'Đang kết nối tới dịch vụ QQ...',
+    retry: 'Thử lại',
+    tokenNote:
+      'Bộ chuyển đổi hiện tại không dùng trường Token; có thể để trống.',
+    boundBy: 'Được liên kết bởi người dùng QQ {{openid}}',
+  },
   pluginPages: {
     selectFromSidebar: 'Chọn một trang plugin từ thanh bên',
     invalidPage: 'Trang plugin không hợp lệ',

web/src/i18n/locales/zh-Hans.ts

@@ -1741,6 +1741,17 @@ const zhHans = {
     retry: '重试',
     robotNameNote: '机器人名称无法自动获取，请手动填写。',
   },
+  qqofficial: {
+    createBinding: '一键扫码绑定 QQ 机器人',
+    scanQRCode: '请使用手机 QQ 扫描以下二维码，在「QQ 机器人助手」中授权绑定',
+    waitingForScan: '等待扫码中',
+    bindSuccess: '绑定成功！AppID 与密钥已自动填入',
+    bindFailed: '绑定失败',
+    connecting: '正在连接 QQ 服务...',
+    retry: '重试',
+    tokenNote: 'Token 字段当前适配器未使用，留空即可。',
+    boundBy: '由 QQ 用户 {{openid}} 扫码绑定',
+  },
   pluginPages: {
     selectFromSidebar: '从侧边栏选择一个插件页面',
     invalidPage: '无效的插件页面',

web/src/i18n/locales/zh-Hant.ts

@@ -1650,6 +1650,17 @@ const zhHant = {
     retry: '重試',
     robotNameNote: '機器人名稱無法自動取得，請手動填寫。',
   },
+  qqofficial: {
+    createBinding: '一鍵掃碼綁定 QQ 機器人',
+    scanQRCode: '請使用手機 QQ 掃描以下 QR Code，在「QQ 機器人助手」中授權綁定',
+    waitingForScan: '等待掃碼中',
+    bindSuccess: '綁定成功！AppID 與密鑰已自動填入',
+    bindFailed: '綁定失敗',
+    connecting: '正在連線 QQ 服務...',
+    retry: '重試',
+    tokenNote: 'Token 欄位目前介面卡未使用，留空即可。',
+    boundBy: '由 QQ 用戶 {{openid}} 掃碼綁定',
+  },
   pluginPages: {
     selectFromSidebar: '從側邊欄選擇一個插件頁面',
     invalidPage: '無效的插件頁面',