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
2026-08-09 12:40:59 +00:00 · 2026-07-13 00:42:46 +08:00
parent 3ddebd26ae
commit 0755beebcd
43 changed files with 12320 additions and 221 deletions
@@ -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
@@ -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'