evolcore 0.0.2 → 0.0.3

package/dist/channels/dingtalk.js

@@ -1,11 +1,130 @@
-import { randomInt } from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import { createHash, randomInt } from 'crypto';
 import { logger } from '../utils/logger.js';
 import { requireOptional } from '../utils/npm-ops.js';
 import { middleOutputModePolicy, resolveShowActivities, showActivitiesPolicy } from '../core/channel-loader.js';
 import { formatItemsAsText } from '../core/message/items-formatter.js';
+import { sentReceipt, suppressedReceipt } from '../core/message/send-receipt.js';
 import { initWelcomeManager, sendWelcomeIfNeeded } from '../utils/welcome.js';
 import { isValidAid } from '../aun/aid/validation.js';
 import { bindContactAlias } from '../config/contact-book.js';
+import { resolvePaths } from '../paths.js';
+const DINGTALK_QUEUED_EMOTION = 'Pin';
+const DINGTALK_THINKING_EMOTION = 'BusinessTrip';
+const DINGTALK_DONE_EMOTION = 'Done';
+const DINGTALK_WRONG_EMOTION = 'Wrong';
+const DINGTALK_CARD_CALLBACK_TOPIC = '/v1.0/card/instances/callback';
+const DINGTALK_CARD_MAX_BUTTONS = 6;
+const DINGTALK_CARD_MAX_CHECKERS = 8;
+const DINGTALK_MAX_MESSAGE_CHARS = 18_000;
+const DINGTALK_CARD_PENDING_TTL_MS = 24 * 60 * 60 * 1000;
+const DINGTALK_CARD_SETTLED_RETENTION_MS = 24 * 60 * 60 * 1000;
+const DINGTALK_MEDIA_HOST_SUFFIXES = [
+    '.dingtalk.com',
+    '.aliyuncs.com',
+    '.alicdn.com',
+    '.aliyun.com',
+];
+function asRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    return value;
+}
+function parseJsonRecord(value) {
+    if (typeof value === 'string') {
+        try {
+            return asRecord(JSON.parse(value));
+        }
+        catch {
+            return {};
+        }
+    }
+    return asRecord(value);
+}
+function splitDingtalkMessage(content) {
+    const parts = [];
+    let remaining = content;
+    while (remaining.length > DINGTALK_MAX_MESSAGE_CHARS) {
+        let splitAt = remaining.lastIndexOf('\n\n', DINGTALK_MAX_MESSAGE_CHARS);
+        if (splitAt <= 0)
+            splitAt = remaining.lastIndexOf('\n', DINGTALK_MAX_MESSAGE_CHARS);
+        if (splitAt <= 0)
+            splitAt = DINGTALK_MAX_MESSAGE_CHARS;
+        parts.push(remaining.slice(0, splitAt).trimEnd());
+        remaining = remaining.slice(splitAt).trimStart();
+    }
+    if (remaining)
+        parts.push(remaining);
+    return parts;
+}
+function isTrustedDingtalkMediaUrl(value) {
+    try {
+        const url = new URL(value);
+        if (url.protocol !== 'https:' || url.username || url.password)
+            return false;
+        const host = url.hostname.toLowerCase();
+        return DINGTALK_MEDIA_HOST_SUFFIXES.some(suffix => (host === suffix.slice(1) || host.endsWith(suffix)));
+    }
+    catch {
+        return false;
+    }
+}
+export function dingtalkCardTrackId(channelName, interactionId) {
+    return `ec_${createHash('sha256').update(`${channelName || 'dingtalk'}:${interactionId}`).digest('base64url')}`;
+}
+export function buildDingtalkCardParamMap(interaction, state, status = '') {
+    const map = {
+        interactionId: interaction.id,
+        title: interaction.kind.title,
+        body: interaction.kind.body || '',
+        state,
+        status,
+        buttonCount: String(Math.min(interaction.kind.buttons.length, DINGTALK_CARD_MAX_BUTTONS)),
+        checkerCount: interaction.kind.kind === 'action'
+            ? String(Math.min(interaction.kind.checkers?.length || 0, DINGTALK_CARD_MAX_CHECKERS))
+            : '0',
+        allowCustomInput: interaction.kind.kind === 'action' && interaction.kind.allowCustomInput ? 'true' : 'false',
+    };
+    for (let i = 0; i < DINGTALK_CARD_MAX_BUTTONS; i++) {
+        const button = interaction.kind.buttons[i];
+        map[`button_${i}_text`] = button?.label || '';
+        map[`button_${i}_style`] = button?.style || 'default';
+        map[`button_${i}_visible`] = button ? 'true' : 'false';
+        map[`button_${i}_disabled`] = state !== 'pending' || !!(button && 'disabled' in button && button.disabled)
+            ? 'true'
+            : 'false';
+    }
+    const checkers = interaction.kind.kind === 'action' ? interaction.kind.checkers || [] : [];
+    for (let i = 0; i < DINGTALK_CARD_MAX_CHECKERS; i++) {
+        const checker = checkers[i];
+        map[`checker_${i}_label`] = checker?.label || '';
+        map[`checker_${i}_description`] = checker?.description || '';
+        map[`checker_${i}_visible`] = checker ? 'true' : 'false';
+    }
+    return map;
+}
+export function parseDingtalkCardCallback(data) {
+    const root = parseJsonRecord(data);
+    const content = parseJsonRecord(root.content);
+    const privateData = parseJsonRecord(content.cardPrivateData ?? root.cardPrivateData);
+    const actionIds = Array.isArray(privateData.actionIds)
+        ? privateData.actionIds
+        : Array.isArray(content.actionIds)
+            ? content.actionIds
+            : [];
+    const params = parseJsonRecord(privateData.params ?? content.params);
+    return {
+        outTrackId: root.outTrackId ?? content.outTrackId,
+        operatorId: root.userId ?? root.operatorId ?? content.userId,
+        actionId: typeof actionIds[0] === 'string'
+            ? actionIds[0]
+            : typeof root.actionId === 'string'
+                ? root.actionId
+                : undefined,
+        values: params,
+    };
+}
 export const DINGTALK_BIND_CODE_TTL_MS = 10 * 60 * 1000;
 export const DINGTALK_BIND_MAX_FAILED_ATTEMPTS = 5;
 const pendingContactBinds = new Map();
@@ -66,7 +185,7 @@ export function handlePendingDingtalkContactBindMessage(ctx) {
         return {
             handled: true,
             status: 'format',
-            reply: '请直接发送 6 位数字绑定码。格式错误不计入错误次数。',
+            reply: '请直接发送 6 位数字绑定码。',
             remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
         };
     }
@@ -79,14 +198,14 @@ export function handlePendingDingtalkContactBindMessage(ctx) {
                 handled: true,
                 status: 'failed',
                 remainingAttempts: 0,
-                reply: '绑定码错误次数已达上限，本次钉钉身份绑定失败。请重新执行 ec init dingtalk 并再次扫码绑定。',
+                reply: '绑定码无效，本次钉钉身份绑定失败。请重新执行 ec init dingtalk 并再次扫码绑定。',
             };
         }
         return {
             handled: true,
             status: 'wrong-code',
             remainingAttempts: remaining,
-            reply: `绑定码错误，请重新发送 6 位数字绑定码。剩余 ${remaining} 次机会。`,
+            reply: '绑定码错误，请重新发送 6 位数字绑定码。',
         };
     }
     const actorId = String(ctx.actorId || '').trim();
@@ -104,7 +223,7 @@ export function handlePendingDingtalkContactBindMessage(ctx) {
         return {
             handled: true,
             status: 'bound',
-            reply: `钉钉身份绑定成功：dingtalk:${actorId} -> ${item.primaryId}`,
+            reply: `钉钉身份绑定成功：${item.channelName}:${encodeURIComponent(actorId)} -> ${item.primaryId}`,
         };
     }
     catch (error) {
@@ -144,7 +263,19 @@ export class DingtalkChannel {
     webhookCache = new Map();
     conversationIdCache = new Map();
     senderStaffIdCache = new Map();
+    messageContextCache = new Map();
+    routes = new Map();
+    queuedReactions = new Map();
+    thinkingReactions = new Map();
+    taskReactionMessages = new Map();
     seenMessages = new Map();
+    interactionCallback;
+    interactionInvalidationCallback;
+    cardsByTrackId = new Map();
+    cardTrackIdByInteraction = new Map();
+    pendingCardsByChat = new Map();
+    cardActionsInFlight = new Set();
+    interactionSendTails = new Map();
     cleanupInterval = null;
     projectPathProvider = null;
     // Welcome message manager
@@ -164,12 +295,111 @@ export class DingtalkChannel {
             return false;
         return WEBHOOK_RE.test(url);
     }
-    isDuplicate(msgId) {
+    isDuplicate(msgId, chatId = '') {
         if (this.seenMessages.has(msgId))
             return true;
-        this.seenMessages.set(msgId, Date.now());
+        const ts = Date.now();
+        this.seenMessages.set(msgId, ts);
+        if (this.config.seenMsgFile) {
+            try {
+                fs.mkdirSync(path.dirname(this.config.seenMsgFile), { recursive: true });
+                fs.appendFileSync(this.config.seenMsgFile, JSON.stringify({ id: msgId, ts, chatId }) + '\n');
+            }
+            catch (error) {
+                logger.debug('[DingTalk] Failed to persist seen message:', error);
+            }
+        }
         return false;
     }
+    loadSeenMessages() {
+        const file = this.config.seenMsgFile;
+        if (!file)
+            return;
+        const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+        try {
+            for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+                if (!line)
+                    continue;
+                const record = JSON.parse(line);
+                if (typeof record.id === 'string' && typeof record.ts === 'number' && record.ts > cutoff) {
+                    this.seenMessages.set(record.id, record.ts);
+                }
+            }
+        }
+        catch (error) {
+            if (error?.code !== 'ENOENT')
+                logger.warn('[DingTalk] Failed to load seen messages:', error);
+        }
+    }
+    rewriteSeenMessages() {
+        const file = this.config.seenMsgFile;
+        if (!file)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            const records = [...this.seenMessages.entries()].map(([id, ts]) => JSON.stringify({ id, ts }));
+            if (records.length === 0)
+                fs.rmSync(file, { force: true });
+            else {
+                const tempFile = `${file}.${process.pid}.tmp`;
+                fs.writeFileSync(tempFile, records.join('\n') + '\n');
+                fs.renameSync(tempFile, file);
+            }
+        }
+        catch (error) {
+            logger.debug('[DingTalk] Failed to compact seen messages:', error);
+        }
+    }
+    rememberRoute(chatId, route) {
+        this.routes.set(chatId, route);
+        if (route.staffId)
+            this.senderStaffIdCache.set(chatId, route.staffId);
+        this.conversationIdCache.set(chatId, route.conversationId);
+        const file = this.config.routeFile;
+        if (!file)
+            return;
+        try {
+            fs.mkdirSync(path.dirname(file), { recursive: true });
+            const serializable = Object.fromEntries(this.routes);
+            const tempFile = `${file}.${process.pid}.tmp`;
+            fs.writeFileSync(tempFile, JSON.stringify(serializable, null, 2) + '\n');
+            fs.renameSync(tempFile, file);
+        }
+        catch (error) {
+            logger.debug('[DingTalk] Failed to persist routes:', error);
+        }
+    }
+    loadRoutes() {
+        const file = this.config.routeFile;
+        if (!file)
+            return;
+        try {
+            const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+            for (const [chatId, raw] of Object.entries(parseJsonRecord(parsed))) {
+                const route = raw;
+                if ((route.chatType === 'private' || route.chatType === 'group') && typeof route.conversationId === 'string') {
+                    this.routes.set(chatId, route);
+                    if (route.staffId)
+                        this.senderStaffIdCache.set(chatId, route.staffId);
+                    this.conversationIdCache.set(chatId, route.conversationId);
+                }
+            }
+        }
+        catch (error) {
+            if (error?.code !== 'ENOENT')
+                logger.warn('[DingTalk] Failed to load routes:', error);
+        }
+    }
+    acknowledgeStreamMessage(msg, response = { status: 'OK' }) {
+        if (!this.client || !msg?.headers?.messageId)
+            return;
+        try {
+            this.client.socketCallBackResponse(msg.headers.messageId, { response: JSON.stringify(response) });
+        }
+        catch (error) {
+            logger.warn('[DingTalk] Stream ACK failed:', error);
+        }
+    }
     resolveChatId(conversationType, conversationId, senderId) {
         return conversationType === '2' ? conversationId : senderId;
     }
@@ -196,11 +426,22 @@ export class DingtalkChannel {
         if (!clientId || !clientSecret || clientId.includes('your-') || clientSecret.includes('your-')) {
             throw new Error('DingTalk clientId/clientSecret not configured');
         }
-        const { DWClient, TOPIC_ROBOT } = await requireOptional('dingtalk-stream');
+        this.loadSeenMessages();
+        this.loadRoutes();
+        const { DWClient, TOPIC_ROBOT, TOPIC_CARD } = await requireOptional('dingtalk-stream');
         this.client = new DWClient({ clientId, clientSecret });
         this.client.registerCallbackListener(TOPIC_ROBOT, async (msg) => {
             await this.handleIncoming(msg);
         });
+        this.client.registerCallbackListener(TOPIC_CARD || DINGTALK_CARD_CALLBACK_TOPIC, async (msg) => {
+            await this.handleCardCallbackMessage(msg);
+        });
+        if (typeof this.client.registerAllEventListener === 'function') {
+            this.client.registerAllEventListener((event) => {
+                this.handlePlatformEvent(event);
+                return { status: 'SUCCESS' };
+            });
+        }
         await this.client.connect();
         this.connected = true;
         // Hourly cleanup of old dedup entries
@@ -210,6 +451,15 @@ export class DingtalkChannel {
                 if (ts < cutoff)
                     this.seenMessages.delete(id);
             }
+            this.rewriteSeenMessages();
+            for (const [id, context] of this.messageContextCache) {
+                if (context.createdAt < cutoff) {
+                    this.messageContextCache.delete(id);
+                    this.queuedReactions.delete(id);
+                    this.thinkingReactions.delete(id);
+                }
+            }
+            this.cleanupCardState();
         }, 60 * 60 * 1000);
         logger.info('[DingTalk] Connected via Stream Mode');
     }
@@ -228,14 +478,50 @@ export class DingtalkChannel {
         }
         logger.info('[DingTalk] Disconnected');
     }
+    getStatus() {
+        return { connected: this.connected };
+    }
+    async reconnect() {
+        if (this.connected)
+            await this.disconnect();
+        try {
+            await this.connect();
+            return '重连成功';
+        }
+        catch (error) {
+            return `重连失败: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
     onMessage(handler) {
         this.messageHandler = handler;
     }
     onRecall(handler) {
         this.recallHandler = handler;
     }
+    handlePlatformEvent(event) {
+        const data = parseJsonRecord(event?.data);
+        const bizData = parseJsonRecord(data.biz_data ?? data.bizData);
+        const eventType = String(data.biz_type ?? data.bizType ?? event?.headers?.eventType ?? '');
+        if (eventType === '260') {
+            logger.debug('[DingTalk] Robot message read event:', bizData);
+        }
+        else if (eventType === '261') {
+            // This event describes an outbound robot message being recalled. It is
+            // not the inbound user-message recall signal consumed by MessageBridge.
+            logger.debug('[DingTalk] Robot outbound message recalled:', bizData);
+        }
+        else if (eventType === '262') {
+            logger.debug('[DingTalk] Robot message reaction event:', bizData);
+        }
+        else {
+            logger.debug(`[DingTalk] Ignored platform event type=${eventType || 'unknown'}`);
+        }
+    }
     // ── Inbound message handling ───────────────────────────────────────────────
     async handleIncoming(msg) {
+        // Stream callbacks must be acknowledged even when the payload is a
+        // duplicate, stale, malformed, or intentionally ignored by mention policy.
+        this.acknowledgeStreamMessage(msg);
         try {
             const data = typeof msg.data === 'string' ? JSON.parse(msg.data) : msg.data;
             const msgId = data.msgId;
@@ -245,44 +531,65 @@ export class DingtalkChannel {
             const senderNick = data.senderNick;
             const sessionWebhook = data.sessionWebhook;
             const msgtype = data.msgtype;
-            // Dedup
-            if (msgId && this.isDuplicate(msgId)) {
+            const chatId = this.resolveChatId(conversationType, conversationId, senderId);
+            const chatType = conversationType === '2' ? 'group' : 'private';
+            // Dedup is persisted before any policy rejection so a restart cannot
+            // re-execute or repeatedly re-evaluate the same transport message.
+            if (msgId && this.isDuplicate(msgId, chatId)) {
                 logger.debug(`[DingTalk] Duplicate message skipped: ${msgId}`);
                 return;
             }
-            const chatId = this.resolveChatId(conversationType, conversationId, senderId);
-            const chatType = conversationType === '2' ? 'group' : 'private';
-            // Cache sender info for Open API sends
-            if (senderId)
-                this.senderStaffIdCache.set(chatId, senderId);
-            if (conversationId)
-                this.conversationIdCache.set(chatId, conversationId);
+            if (conversationId) {
+                this.rememberRoute(chatId, {
+                    chatType,
+                    conversationId,
+                    staffId: senderId || undefined,
+                    updatedAt: Date.now(),
+                });
+            }
+            const createdAt = Number(data.createAt ?? 0);
+            if (createdAt > 0 && Date.now() - createdAt > 5 * 60 * 1000) {
+                logger.warn(`[DingTalk] Dropping stale message: id=${msgId} age=${Math.round((Date.now() - createdAt) / 1000)}s`);
+                return;
+            }
+            const isMentioned = !!(data.isInAtList || (data.atUsers && data.atUsers.length > 0));
+            const mentions = Array.isArray(data.atUsers)
+                ? data.atUsers.map((item, index) => ({
+                    userId: item.staffId || item.dingtalkId || '',
+                    name: item.name,
+                    key: `at_${index}`,
+                })).filter((item) => item.userId)
+                : [];
+            const eventMetadata = {
+                mentions: mentions.length > 0 ? mentions : undefined,
+                isMentioned,
+                topicName: typeof data.conversationTitle === 'string' ? data.conversationTitle : undefined,
+            };
             // Group gate
             if (conversationType === '2') {
-                const isInAtList = !!(data.isInAtList || (data.atUsers && data.atUsers.length > 0));
-                if (!this.shouldProcessGroupMessage(conversationId, isInAtList)) {
+                if (!this.shouldProcessGroupMessage(conversationId, isMentioned)) {
                     logger.debug(`[DingTalk] Group message ignored (not mentioned): ${msgId}`);
                     return;
                 }
             }
+            // Emotion APIs require both the inbound message ID and openConversationId.
+            // Keep the association at the channel boundary so core only handles the
+            // channel-neutral messageId.
+            if (msgId && conversationId) {
+                this.messageContextCache.set(msgId, {
+                    openConversationId: conversationId,
+                    createdAt: Date.now(),
+                });
+            }
             // Webhook cache (SSRF validated)
             if (sessionWebhook && this.isValidWebhook(sessionWebhook)) {
                 this.webhookCache.set(chatId, sessionWebhook);
             }
-            // ACK to prevent 60s retry
-            if (this.client && msg.headers?.messageId) {
-                try {
-                    this.client.socketCallBackResponse(msg.headers.messageId, { response: JSON.stringify({ status: 'OK' }) });
-                }
-                catch (e) {
-                    logger.warn('[DingTalk] ACK failed:', e);
-                }
-            }
             // Dispatch by msgtype
             if (!this.messageHandler)
                 return;
             // 首次交互欢迎消息（使用共享帮助函数）
-            await sendWelcomeIfNeeded(this.welcomeManager, senderId, chatId, (id, text) => this.sendMessage(id, text), 'DingTalk');
+            await sendWelcomeIfNeeded(this.welcomeManager, senderId, chatId, async (id, text) => { await this.sendMessage(id, text); }, 'DingTalk');
             if (msgtype === 'text' || !msgtype) {
                 const text = this.extractText(data);
                 if (!text)
@@ -290,22 +597,40 @@ export class DingtalkChannel {
                 await this.messageHandler({
                     channelId: chatId, content: text, chatType,
                     peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                    ...eventMetadata,
                 });
             }
             else if (msgtype === 'picture' || msgtype === 'image') {
-                await this.handleImageMessage(data, chatId, chatType, senderId, senderNick, msgId);
+                await this.handleImageMessage(data, chatId, chatType, senderId, senderNick, msgId, eventMetadata);
             }
             else if (msgtype === 'file') {
-                await this.handleFileMessage(data, chatId, chatType, senderId, senderNick, msgId);
+                await this.handleFileMessage(data, chatId, chatType, senderId, senderNick, msgId, eventMetadata);
             }
             else if (msgtype === 'richText') {
-                await this.handleRichTextMessage(data, chatId, chatType, senderId, senderNick, msgId);
+                await this.handleRichTextMessage(data, chatId, chatType, senderId, senderNick, msgId, eventMetadata);
+            }
+            else if (msgtype === 'audio') {
+                const recognition = data.recognition || data.content?.recognition;
+                await this.messageHandler({
+                    channelId: chatId,
+                    content: recognition ? `用户发送了语音：${recognition}` : '[语音消息：未提供语音识别文本]',
+                    chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                    ...eventMetadata,
+                });
+            }
+            else if (msgtype === 'video') {
+                const videoContent = parseJsonRecord(data.content);
+                await this.handleFileMessage({
+                    ...data,
+                    content: { ...videoContent, fileName: videoContent.fileName || data.fileName || 'video.mp4' },
+                }, chatId, chatType, senderId, senderNick, msgId, eventMetadata);
             }
             else {
                 await this.messageHandler({
                     channelId: chatId,
                     content: `[不支持的消息类型: ${msgtype}]`,
                     chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                    ...eventMetadata,
                 });
             }
         }
@@ -314,20 +639,58 @@ export class DingtalkChannel {
         }
     }
     // ── Inbound media handling ─────────────────────────────────────────────────
-    async handleImageMessage(data, chatId, chatType, senderId, senderNick, msgId) {
+    async resolveMessageDownloadUrl(downloadUrlOrCode) {
+        if (/^https?:\/\//i.test(downloadUrlOrCode)) {
+            if (!isTrustedDingtalkMediaUrl(downloadUrlOrCode)) {
+                throw new Error('DingTalk media URL rejected: untrusted host');
+            }
+            return downloadUrlOrCode;
+        }
+        const token = await this.client?.getAccessToken();
+        if (!token)
+            throw new Error('DingTalk access token unavailable for media download');
+        const response = await fetch('https://api.dingtalk.com/v1.0/robot/messageFiles/download', {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-acs-dingtalk-access-token': token,
+            },
+            body: JSON.stringify({ downloadCode: downloadUrlOrCode, robotCode: this.config.clientId }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        const body = await response.json().catch(() => undefined);
+        if (!response.ok || !body?.downloadUrl) {
+            throw new Error(`DingTalk media URL resolution failed: ${response.status}${body ? ` ${JSON.stringify(body)}` : ''}`);
+        }
+        if (!isTrustedDingtalkMediaUrl(body.downloadUrl)) {
+            throw new Error('DingTalk media URL resolution returned an untrusted host');
+        }
+        return body.downloadUrl;
+    }
+    async downloadMessageMedia(downloadUrlOrCode) {
+        const { safeFetch } = await import('../utils/media-cache.js');
+        const downloadUrl = await this.resolveMessageDownloadUrl(downloadUrlOrCode);
+        const host = new URL(downloadUrl).hostname;
+        return safeFetch(downloadUrl, {
+            allowedHosts: new Set([host]),
+            rejectRedirects: true,
+        });
+    }
+    async handleImageMessage(data, chatId, chatType, senderId, senderNick, msgId, metadata = {}) {
         const content = typeof data.content === 'string' ? JSON.parse(data.content) : (data.content || {});
-        const downloadUrl = content.downloadUrl || content.downloadCode;
-        if (!downloadUrl) {
+        const downloadRef = content.downloadUrl || content.downloadCode || data.downloadUrl || data.downloadCode;
+        if (!downloadRef) {
             logger.warn('[DingTalk] Image message without downloadUrl');
             await this.messageHandler({
                 channelId: chatId, content: '[图片下载失败：缺少下载链接]',
                 chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                ...metadata,
             });
             return;
         }
         try {
-            const { safeFetch, validateImage } = await import('../utils/media-cache.js');
-            const buffer = await safeFetch(downloadUrl, { skipSsrfCheck: true });
+            const { validateImage } = await import('../utils/media-cache.js');
+            const buffer = await this.downloadMessageMedia(downloadRef);
             const result = await validateImage(buffer);
             if (result.mime) {
                 await this.messageHandler({
@@ -335,6 +698,7 @@ export class DingtalkChannel {
                     content: '用户发送了一张图片，请分析这张图片的内容。',
                     chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
                     images: [{ data: buffer.toString('base64'), mimeType: result.mime }],
+                    ...metadata,
                 });
             }
             else {
@@ -342,6 +706,7 @@ export class DingtalkChannel {
                 await this.messageHandler({
                     channelId: chatId, content: '[图片验证失败]',
                     chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                    ...metadata,
                 });
             }
         }
@@ -350,32 +715,35 @@ export class DingtalkChannel {
             await this.messageHandler({
                 channelId: chatId, content: '[图片下载失败]',
                 chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                ...metadata,
             });
         }
     }
-    async handleFileMessage(data, chatId, chatType, senderId, senderNick, msgId) {
+    async handleFileMessage(data, chatId, chatType, senderId, senderNick, msgId, metadata = {}) {
         const content = typeof data.content === 'string' ? JSON.parse(data.content) : (data.content || {});
-        const downloadUrl = content.downloadUrl || content.downloadCode;
-        const fileName = content.fileName || 'unknown';
-        if (!downloadUrl) {
+        const downloadRef = content.downloadUrl || content.downloadCode || data.downloadUrl || data.downloadCode;
+        const fileName = content.fileName || data.fileName || 'unknown';
+        if (!downloadRef) {
             logger.warn('[DingTalk] File message without downloadUrl');
             await this.messageHandler({
                 channelId: chatId, content: `[文件下载失败：缺少下载链接] ${fileName}`,
                 chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                ...metadata,
             });
             return;
         }
         try {
-            const { safeFetch, saveToUploads, sanitizeFileName } = await import('../utils/media-cache.js');
+            const { saveToUploads, sanitizeFileName } = await import('../utils/media-cache.js');
             const projectPath = this.projectPathProvider
                 ? await this.projectPathProvider(chatId)
                 : process.cwd();
-            const buffer = await safeFetch(downloadUrl, { skipSsrfCheck: true });
+            const buffer = await this.downloadMessageMedia(downloadRef);
             const { filePath } = saveToUploads(buffer, sanitizeFileName(fileName), projectPath);
             await this.messageHandler({
                 channelId: chatId,
                 content: `用户发送了文件：${fileName}\n文件已保存到：${filePath}\n请使用 Read 工具读取并分析文件内容。`,
                 chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                ...metadata,
             });
         }
         catch (error) {
@@ -383,16 +751,18 @@ export class DingtalkChannel {
             await this.messageHandler({
                 channelId: chatId, content: `[文件下载失败] ${fileName}`,
                 chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                ...metadata,
             });
         }
     }
-    async handleRichTextMessage(data, chatId, chatType, senderId, senderNick, msgId) {
+    async handleRichTextMessage(data, chatId, chatType, senderId, senderNick, msgId, metadata = {}) {
         const content = typeof data.content === 'string' ? JSON.parse(data.content) : (data.content || {});
         const richText = content.richText;
         if (!Array.isArray(richText)) {
             await this.messageHandler({
                 channelId: chatId, content: '[不支持的富文本格式]',
                 chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                ...metadata,
             });
             return;
         }
@@ -402,10 +772,10 @@ export class DingtalkChannel {
             if (item.type === 'text' && item.text) {
                 text += item.text;
             }
-            else if (item.type === 'picture' && item.downloadUrl) {
+            else if (item.type === 'picture' && (item.downloadUrl || item.downloadCode)) {
                 try {
-                    const { safeFetch, validateImage } = await import('../utils/media-cache.js');
-                    const buffer = await safeFetch(item.downloadUrl, { skipSsrfCheck: true });
+                    const { validateImage } = await import('../utils/media-cache.js');
+                    const buffer = await this.downloadMessageMedia(item.downloadUrl || item.downloadCode);
                     const result = await validateImage(buffer);
                     if (result.mime) {
                         images.push({ data: buffer.toString('base64'), mimeType: result.mime });
@@ -421,136 +791,566 @@ export class DingtalkChannel {
             channelId: chatId, content: prompt, chatType,
             peerId: senderId || '', peerName: senderNick, messageId: msgId,
             images: images.length > 0 ? images : undefined,
+            ...metadata,
         });
     }
-    // ── Outbound: text via sessionWebhook ──────────────────────────────────────
+    // ── Outbound: OpenAPI sends return processQueryKey message receipts ───────
     async sendMessage(chatId, content) {
-        const webhook = this.webhookCache.get(chatId);
-        if (!webhook) {
-            logger.warn(`[DingTalk] No webhook cached for chatId: ${chatId}, message dropped`);
+        if (!content.trim())
+            return [];
+        const token = await this.client?.getAccessToken();
+        if (!token)
+            throw new Error('DingTalk access token unavailable for sendMessage');
+        const messageIds = [];
+        for (const part of splitDingtalkMessage(content)) {
+            messageIds.push(await this.sendRobotMessage(chatId, token, 'sampleMarkdown', JSON.stringify({ title: 'EvolCore', text: part })));
+        }
+        return messageIds;
+    }
+    // ── Outbound: processing-state emoji reactions ────────────────────────────────
+    /** Mark a message as queued. Core only calls this while another task is running. */
+    async acknowledgeMessage(messageId) {
+        await this.ensureReaction(messageId, DINGTALK_QUEUED_EMOTION, this.queuedReactions);
+    }
+    /** Upgrade Queued to Thinking without leaving a visible state gap. */
+    async promoteAckReaction(messageId, taskId, sourceMessageIds) {
+        const messageIds = [...new Set([...(sourceMessageIds ?? []), messageId].filter(Boolean))];
+        if (taskId)
+            this.taskReactionMessages.set(taskId, messageIds);
+        // Register every in-flight reaction before yielding. A very short task may
+        // otherwise finalize while later messages in a merged batch are still
+        // untracked, leaving a late BusinessTrip behind.
+        const thinking = messageIds.map(id => (this.ensureReaction(id, DINGTALK_THINKING_EMOTION, this.thinkingReactions)));
+        await Promise.all(thinking);
+        await Promise.all(messageIds.map(id => (this.clearReaction(id, DINGTALK_QUEUED_EMOTION, this.queuedReactions))));
+    }
+    /** Clear processing reactions and replace them with Done or Wrong. */
+    async completeAckReaction(taskId, completed) {
+        const messageIds = this.taskReactionMessages.get(taskId);
+        if (!messageIds)
             return;
+        this.taskReactionMessages.delete(taskId);
+        for (const messageId of messageIds) {
+            // Add the terminal state first so users never see an empty reaction gap.
+            let terminalAdded = await this.sendEmotion(messageId, completed ? DINGTALK_DONE_EMOTION : DINGTALK_WRONG_EMOTION, false);
+            if (!terminalAdded) {
+                terminalAdded = await this.sendEmotion(messageId, completed ? DINGTALK_DONE_EMOTION : DINGTALK_WRONG_EMOTION, false);
+            }
+            if (!terminalAdded) {
+                logger.warn(`[DingTalk] Failed to add terminal reaction for ${messageId}; preserving processing reaction`);
+                continue;
+            }
+            await this.clearReaction(messageId, DINGTALK_QUEUED_EMOTION, this.queuedReactions);
+            await this.clearReaction(messageId, DINGTALK_THINKING_EMOTION, this.thinkingReactions);
+        }
+    }
+    async ensureReaction(messageId, emotionName, reactions) {
+        const existing = reactions.get(messageId);
+        if (existing)
+            return existing;
+        const pending = this.sendEmotion(messageId, emotionName, false)
+            .then((ok) => {
+            if (!ok)
+                reactions.delete(messageId);
+            return ok;
+        })
+            .catch(() => {
+            reactions.delete(messageId);
+            return false;
+        });
+        reactions.set(messageId, pending);
+        return pending;
+    }
+    async clearReaction(messageId, emotionName, reactions) {
+        const pending = reactions.get(messageId);
+        if (!pending)
+            return;
+        const added = await pending.catch(() => false);
+        if (added)
+            await this.sendEmotion(messageId, emotionName, true);
+        reactions.delete(messageId);
+    }
+    async sendEmotion(messageId, emotionName, recall) {
+        const context = this.messageContextCache.get(messageId);
+        if (!context) {
+            logger.debug(`[DingTalk] Cannot ${recall ? 'recall' : 'add'} emotion: no context for message ${messageId}`);
+            return false;
         }
         try {
             const token = await this.client?.getAccessToken();
-            const response = await fetch(webhook, {
+            if (!token) {
+                logger.debug('[DingTalk] Cannot send emotion: no access token');
+                return false;
+            }
+            const response = await fetch(`https://api.dingtalk.com/v1.0/robot/emotion/${recall ? 'recall' : 'reply'}`, {
                 method: 'POST',
                 headers: {
                     'Content-Type': 'application/json',
-                    'x-acs-dingtalk-access-token': token || '',
+                    'x-acs-dingtalk-access-token': token,
                 },
                 body: JSON.stringify({
-                    msgtype: 'markdown',
-                    markdown: { title: 'Bot', text: content },
+                    robotCode: this.config.clientId,
+                    openMsgId: messageId,
+                    openConversationId: context.openConversationId,
+                    // Pin / BusinessTrip / Done / Wrong are DingTalk built-in
+                    // reactions. emotionType=2 is for custom text reactions and
+                    // causes BusinessTrip to fail with system.error.
+                    emotionType: 1,
+                    emotionName,
                 }),
                 signal: AbortSignal.timeout(15_000),
             });
-            if (!response.ok) {
-                const body = await response.text().catch(() => '');
-                logger.error(`[DingTalk] sendMessage failed for ${chatId}: ${response.status} ${body}`);
+            const body = await response.json().catch(() => undefined);
+            if (!response.ok || body?.success === false) {
+                logger.warn(`[DingTalk] ${recall ? 'recall' : 'reply'} emotion ${emotionName} failed for ${messageId}: `
+                    + `${response.status}${body ? ` ${JSON.stringify(body)}` : ''}`);
+                return false;
             }
+            return true;
         }
         catch (error) {
-            logger.error(`[DingTalk] sendMessage failed for ${chatId}:`, error.message);
+            logger.debug(`[DingTalk] ${recall ? 'recall' : 'reply'} emotion ${emotionName} failed for ${messageId}: ${error?.message || error}`);
+            return false;
         }
     }
     // ── Outbound: image via Open API ───────────────────────────────────────────
-    async sendImage(chatId, png) {
-        try {
-            const token = await this.client?.getAccessToken();
-            if (!token) {
-                logger.warn('[DingTalk] No access token for sendImage');
-                return;
-            }
-            // Step 1: Upload media
-            const FormData = (await requireOptional('form-data')).default;
-            const form = new FormData();
-            form.append('type', 'image');
-            form.append('media', png, { filename: 'image.png', contentType: 'image/png' });
-            const uploadRes = await fetch(`https://oapi.dingtalk.com/media/upload?access_token=${token}`, { method: 'POST', body: form, signal: AbortSignal.timeout(30_000) });
-            const uploadData = await uploadRes.json();
-            const mediaId = uploadData?.media_id;
-            if (!mediaId) {
-                logger.error('[DingTalk] Media upload failed:', uploadData);
-                return;
-            }
-            // Step 2: Send via robot API
-            await this.sendRobotMessage(chatId, token, 'sampleImageMsg', JSON.stringify({ photoURL: `@${mediaId}` }));
+    async sendImage(chatId, image) {
+        const token = await this.client?.getAccessToken();
+        if (!token)
+            throw new Error('DingTalk access token unavailable for sendImage');
+        const { validateImage } = await import('../utils/media-cache.js');
+        const imageInfo = await validateImage(image);
+        if (!imageInfo.mime) {
+            const reason = 'reason' in imageInfo ? imageInfo.reason : 'unsupported image';
+            throw new Error(`DingTalk image validation failed: ${reason}`);
         }
-        catch (error) {
-            logger.error(`[DingTalk] sendImage failed for ${chatId}:`, error.message);
+        const extension = imageInfo.mime === 'image/jpeg' ? 'jpg' : imageInfo.mime.slice('image/'.length);
+        // Step 1: Upload media
+        const FormData = (await requireOptional('form-data')).default;
+        const form = new FormData();
+        form.append('type', 'image');
+        form.append('media', image, { filename: `image.${extension}`, contentType: imageInfo.mime });
+        const uploadRes = await fetch(`https://oapi.dingtalk.com/media/upload?access_token=${token}`, { method: 'POST', body: form, signal: AbortSignal.timeout(30_000) });
+        const uploadData = await uploadRes.json();
+        const mediaId = uploadData?.media_id;
+        if (!uploadRes.ok || uploadData?.errcode || !mediaId) {
+            throw new Error(`DingTalk media upload failed: ${uploadRes.status} ${JSON.stringify(uploadData)}`);
         }
+        // Step 2: Send via robot API
+        return [await this.sendRobotMessage(chatId, token, 'sampleImageMsg', JSON.stringify({ photoURL: `@${mediaId}` }))];
     }
     // ── Outbound: file via Open API ────────────────────────────────────────────
     async sendFile(chatId, filePath) {
+        // Detect image files → route to sendImage (same pattern as Feishu)
+        const header = Buffer.alloc(4_100);
+        const fd = fs.openSync(filePath, 'r');
+        let bytesRead = 0;
         try {
-            // Detect image files → route to sendImage (same pattern as Feishu)
-            const fs = await import('fs');
-            const path = await import('path');
-            const header = Buffer.alloc(12);
-            const fd = fs.openSync(filePath, 'r');
-            fs.readSync(fd, header, 0, 12, 0);
+            bytesRead = fs.readSync(fd, header, 0, header.length, 0);
+        }
+        finally {
             fs.closeSync(fd);
-            const { fileTypeFromBuffer } = await import('file-type');
-            const ftype = await fileTypeFromBuffer(header);
-            if (ftype && ftype.mime.startsWith('image/')) {
-                const buf = fs.readFileSync(filePath);
-                return this.sendImage(chatId, buf);
-            }
-            const token = await this.client?.getAccessToken();
-            if (!token) {
-                logger.warn('[DingTalk] No access token for sendFile');
-                return;
-            }
-            // Step 1: Upload media
-            const FormData = (await requireOptional('form-data')).default;
-            const form = new FormData();
-            form.append('type', 'file');
-            form.append('media', fs.createReadStream(filePath), { filename: path.basename(filePath) });
-            const uploadRes = await fetch(`https://oapi.dingtalk.com/media/upload?access_token=${token}`, { method: 'POST', body: form, signal: AbortSignal.timeout(60_000) });
-            const uploadData = await uploadRes.json();
-            const mediaId = uploadData?.media_id;
-            if (!mediaId) {
-                logger.error('[DingTalk] File upload failed:', uploadData);
-                return;
-            }
-            // Step 2: Send via robot API
-            const fileName = path.basename(filePath);
-            const fileType = path.extname(filePath).replace('.', '') || 'file';
-            await this.sendRobotMessage(chatId, token, 'sampleFile', JSON.stringify({ mediaId: `@${mediaId}`, fileName, fileType }));
         }
-        catch (error) {
-            logger.error(`[DingTalk] sendFile failed for ${chatId}:`, error.message);
+        const { default: imageType } = await import('image-type');
+        const ftype = await imageType(header.subarray(0, bytesRead)).catch(() => undefined);
+        if (ftype && ftype.mime.startsWith('image/')) {
+            const buf = fs.readFileSync(filePath);
+            return this.sendImage(chatId, buf);
         }
+        const token = await this.client?.getAccessToken();
+        if (!token)
+            throw new Error('DingTalk access token unavailable for sendFile');
+        // Step 1: Upload media
+        const FormData = (await requireOptional('form-data')).default;
+        const form = new FormData();
+        form.append('type', 'file');
+        form.append('media', fs.createReadStream(filePath), { filename: path.basename(filePath) });
+        const uploadRes = await fetch(`https://oapi.dingtalk.com/media/upload?access_token=${token}`, { method: 'POST', body: form, signal: AbortSignal.timeout(60_000) });
+        const uploadData = await uploadRes.json();
+        const mediaId = uploadData?.media_id;
+        if (!uploadRes.ok || uploadData?.errcode || !mediaId) {
+            throw new Error(`DingTalk file upload failed: ${uploadRes.status} ${JSON.stringify(uploadData)}`);
+        }
+        // Step 2: Send via robot API
+        const fileName = path.basename(filePath);
+        const fileType = path.extname(filePath).replace('.', '') || 'file';
+        return [await this.sendRobotMessage(chatId, token, 'sampleFile', JSON.stringify({ mediaId: `@${mediaId}`, fileName, fileType }))];
     }
     // ── Robot message send helper (group vs DM) ────────────────────────────────
     async sendRobotMessage(chatId, token, msgKey, msgParam) {
         const headers = { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' };
         const { clientId } = this.config;
         // Group chatId = conversationId, DM chatId = senderId
-        const cachedConvId = this.conversationIdCache.get(chatId);
-        const staffId = this.senderStaffIdCache.get(chatId);
-        if (cachedConvId === chatId) {
+        const route = this.routes.get(chatId);
+        const cachedConvId = route?.conversationId ?? this.conversationIdCache.get(chatId);
+        const staffId = route?.staffId ?? this.senderStaffIdCache.get(chatId) ?? (route?.chatType === 'private' ? chatId : undefined);
+        let res;
+        if (route?.chatType === 'group' || cachedConvId === chatId || (!route && chatId.startsWith('cid'))) {
             // Group: chatId is the conversationId
-            const res = await fetch('https://api.dingtalk.com/v1.0/robot/groupMessages/send', {
+            res = await fetch('https://api.dingtalk.com/v1.0/robot/groupMessages/send', {
                 method: 'POST', headers,
                 body: JSON.stringify({ msgKey, msgParam, openConversationId: chatId, robotCode: clientId }),
                 signal: AbortSignal.timeout(15_000),
             });
-            if (!res.ok)
-                logger.error(`[DingTalk] Group robot send failed: ${res.status}`);
         }
-        else if (staffId) {
+        else if (staffId || (!route && chatId)) {
             // DM: use senderStaffId
-            const res = await fetch('https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend', {
+            const targetStaffId = staffId || chatId;
+            res = await fetch('https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend', {
                 method: 'POST', headers,
-                body: JSON.stringify({ msgKey, msgParam, userIds: [staffId], robotCode: clientId }),
+                body: JSON.stringify({ msgKey, msgParam, userIds: [targetStaffId], robotCode: clientId }),
                 signal: AbortSignal.timeout(15_000),
             });
-            if (!res.ok)
-                logger.error(`[DingTalk] DM robot send failed: ${res.status}`);
         }
         else {
-            logger.warn(`[DingTalk] Cannot send robot message: no conversation/staff ID cached for ${chatId}`);
+            throw new Error(`DingTalk route unavailable for chatId=${chatId}`);
+        }
+        const body = await res.json().catch(() => undefined);
+        if (!res.ok || body?.success === false || body?.code || body?.errcode) {
+            throw new Error(`DingTalk robot send failed: ${res.status}${body ? ` ${JSON.stringify(body)}` : ''}`);
+        }
+        if (Array.isArray(body?.invalidStaffIdList) && body.invalidStaffIdList.length > 0) {
+            throw new Error(`DingTalk robot send rejected recipients: ${body.invalidStaffIdList.join(',')}`);
+        }
+        if (Array.isArray(body?.flowControlledStaffIdList) && body.flowControlledStaffIdList.length > 0) {
+            throw new Error(`DingTalk robot send rate limited recipients: ${body.flowControlledStaffIdList.join(',')}`);
+        }
+        const messageId = body?.processQueryKey ?? body?.result?.processQueryKey;
+        if (!messageId)
+            throw new Error(`DingTalk robot send succeeded without processQueryKey: ${JSON.stringify(body)}`);
+        return messageId;
+    }
+    onInteraction(callback) {
+        this.interactionCallback = callback;
+    }
+    onInteractionInvalidated(callback) {
+        this.interactionInvalidationCallback = callback;
+    }
+    async withInteractionSendLock(chatId, run) {
+        const previous = this.interactionSendTails.get(chatId) ?? Promise.resolve();
+        let release;
+        const current = new Promise(resolve => { release = resolve; });
+        this.interactionSendTails.set(chatId, current);
+        await previous.catch(() => undefined);
+        try {
+            return await run();
+        }
+        finally {
+            release();
+            if (this.interactionSendTails.get(chatId) === current)
+                this.interactionSendTails.delete(chatId);
+        }
+    }
+    cardActionMap(interaction) {
+        const result = new Map();
+        interaction.kind.buttons.slice(0, DINGTALK_CARD_MAX_BUTTONS).forEach((button, index) => {
+            const action = interaction.kind.kind === 'command-card'
+                ? button.command
+                : button.key;
+            result.set(`button_${index}`, action);
+            result.set(`btn_${index}`, action);
+        });
+        if (interaction.kind.kind === 'action' && interaction.kind.allowCustomInput) {
+            result.set('custom_submit', '_custom_input');
+            result.set('btn_submit_custom', '_custom_input');
+        }
+        return result;
+    }
+    trackPendingCard(entry) {
+        this.cardsByTrackId.set(entry.outTrackId, entry);
+        this.cardTrackIdByInteraction.set(entry.interaction.id, entry.outTrackId);
+        let pending = this.pendingCardsByChat.get(entry.chatId);
+        if (!pending) {
+            pending = new Set();
+            this.pendingCardsByChat.set(entry.chatId, pending);
+        }
+        pending.add(entry.outTrackId);
+    }
+    untrackPendingCard(entry) {
+        const pending = this.pendingCardsByChat.get(entry.chatId);
+        pending?.delete(entry.outTrackId);
+        if (pending?.size === 0)
+            this.pendingCardsByChat.delete(entry.chatId);
+    }
+    deleteCardEntry(entry) {
+        this.untrackPendingCard(entry);
+        this.cardsByTrackId.delete(entry.outTrackId);
+        if (this.cardTrackIdByInteraction.get(entry.interaction.id) === entry.outTrackId) {
+            this.cardTrackIdByInteraction.delete(entry.interaction.id);
+        }
+        this.cardActionsInFlight.delete(entry.outTrackId);
+    }
+    /** Bound in-memory card metadata even for interactions without expiresAt. */
+    cleanupCardState(now = Date.now()) {
+        for (const entry of [...this.cardsByTrackId.values()]) {
+            if (entry.settledAt) {
+                if (entry.settledAt <= now - DINGTALK_CARD_SETTLED_RETENTION_MS) {
+                    this.deleteCardEntry(entry);
+                }
+                continue;
+            }
+            const expired = (entry.interaction.expiresAt != null && entry.interaction.expiresAt <= now)
+                || entry.createdAt <= now - DINGTALK_CARD_PENDING_TTL_MS;
+            if (!expired)
+                continue;
+            entry.invalidated = true;
+            entry.invalidatedReason = 'expired';
+            entry.settledAt = now;
+            this.untrackPendingCard(entry);
+            if (!this.cardActionsInFlight.has(entry.outTrackId)) {
+                void this.updateCard(entry, 'invalid', '审批已超时').catch(error => {
+                    logger.warn(`[DingTalk] Failed to expire stale card ${entry.outTrackId}:`, error);
+                });
+            }
+        }
+    }
+    cardResponse(entry, state, status) {
+        return {
+            cardData: { cardParamMap: buildDingtalkCardParamMap(entry.interaction, state, status) },
+            cardUpdateOptions: { updateCardDataByKey: false, updatePrivateDataByKey: true },
+        };
+    }
+    privateCardFeedback(message) {
+        return {
+            userPrivateData: { cardParamMap: { feedback: message } },
+            cardUpdateOptions: { updatePrivateDataByKey: true },
+        };
+    }
+    async updateCard(entry, state, status) {
+        const token = await this.client?.getAccessToken();
+        if (!token)
+            throw new Error('DingTalk access token unavailable for card update');
+        const response = await fetch('https://api.dingtalk.com/v1.0/card/instances', {
+            method: 'PUT',
+            headers: {
+                'Content-Type': 'application/json',
+                'x-acs-dingtalk-access-token': token,
+            },
+            body: JSON.stringify({
+                outTrackId: entry.outTrackId,
+                cardData: { cardParamMap: buildDingtalkCardParamMap(entry.interaction, state, status) },
+                cardUpdateOptions: { updateCardDataByKey: false, updatePrivateDataByKey: false },
+            }),
+            signal: AbortSignal.timeout(15_000),
+        });
+        const body = await response.json().catch(() => undefined);
+        if (!response.ok || body?.success === false || body?.code || body?.errcode) {
+            throw new Error(`DingTalk card update failed: ${response.status}${body ? ` ${JSON.stringify(body)}` : ''}`);
+        }
+    }
+    async invalidateInteraction(interactionId, reason = 'cancelled') {
+        const trackId = this.cardTrackIdByInteraction.get(interactionId);
+        const entry = trackId ? this.cardsByTrackId.get(trackId) : undefined;
+        if (!entry || entry.resolved || entry.invalidated)
+            return;
+        entry.invalidated = true;
+        entry.invalidatedReason = reason;
+        entry.settledAt = Date.now();
+        this.untrackPendingCard(entry);
+        // Card callbacks must respond with cardData; DingTalk explicitly forbids
+        // calling the update API while the callback is still being handled.
+        if (this.cardActionsInFlight.has(entry.outTrackId))
+            return;
+        const status = reason === 'expired' ? '审批已超时' : reason === 'superseded' ? '已有新的交互请求' : '卡片已失效';
+        await this.updateCard(entry, 'invalid', status).catch(error => {
+            logger.warn(`[DingTalk] Failed to invalidate card ${entry.outTrackId}:`, error);
+        });
+    }
+    async invalidatePendingCards(chatId, trackIds) {
+        const pending = trackIds ?? [...(this.pendingCardsByChat.get(chatId) ?? [])];
+        for (const trackId of pending) {
+            const entry = this.cardsByTrackId.get(trackId);
+            if (!entry || entry.resolved || entry.invalidated)
+                continue;
+            if (this.interactionInvalidationCallback) {
+                try {
+                    await this.interactionInvalidationCallback(entry.interaction.id, 'superseded');
+                }
+                catch (error) {
+                    logger.warn('[DingTalk] Failed to cancel superseded interaction:', error);
+                }
+            }
+            await this.invalidateInteraction(entry.interaction.id, 'superseded');
+        }
+    }
+    async sendInteraction(chatId, interaction) {
+        return this.withInteractionSendLock(chatId, async () => {
+            if (!this.config.cardTemplateId)
+                return false;
+            if (interaction.kind.buttons.length > DINGTALK_CARD_MAX_BUTTONS) {
+                logger.warn(`[DingTalk] Interaction ${interaction.id} has too many buttons for the configured card template`);
+                return false;
+            }
+            if (interaction.kind.kind === 'action' && (interaction.kind.checkers?.length || 0) > DINGTALK_CARD_MAX_CHECKERS) {
+                logger.warn(`[DingTalk] Interaction ${interaction.id} has too many checkers for the configured card template`);
+                return false;
+            }
+            const previousPendingCards = [...(this.pendingCardsByChat.get(chatId) ?? [])];
+            const route = this.routes.get(chatId);
+            const isGroup = route?.chatType === 'group' || (!route && chatId.startsWith('cid'));
+            const staffId = route?.staffId || (!isGroup ? chatId : undefined);
+            if (!isGroup && !staffId)
+                return false;
+            const token = await this.client?.getAccessToken();
+            if (!token)
+                throw new Error('DingTalk access token unavailable for card send');
+            const outTrackId = dingtalkCardTrackId(this.channelName, interaction.id);
+            const conversationId = route?.conversationId || chatId;
+            const openSpaceId = isGroup
+                ? `dtv1.card//IM_GROUP.${conversationId}`
+                : `dtv1.card//IM_ROBOT.${staffId}`;
+            const payload = {
+                cardTemplateId: this.config.cardTemplateId,
+                outTrackId,
+                callbackType: 'STREAM',
+                openSpaceId,
+                cardData: { cardParamMap: buildDingtalkCardParamMap(interaction, 'pending') },
+            };
+            if (isGroup)
+                payload.imGroupOpenDeliverModel = { robotCode: this.config.clientId };
+            else
+                payload.imRobotOpenDeliverModel = { robotCode: this.config.clientId };
+            const response = await fetch('https://api.dingtalk.com/v1.0/card/instances/createAndDeliver', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-acs-dingtalk-access-token': token,
+                },
+                body: JSON.stringify(payload),
+                signal: AbortSignal.timeout(15_000),
+            });
+            const body = await response.json().catch(() => undefined);
+            if (!response.ok || body?.success === false || body?.code || body?.errcode) {
+                throw new Error(`DingTalk card send failed: ${response.status}${body ? ` ${JSON.stringify(body)}` : ''}`);
+            }
+            const failedDelivery = Array.isArray(body?.result?.deliverResults)
+                ? body.result.deliverResults.find((result) => result?.success === false)
+                : undefined;
+            if (failedDelivery) {
+                throw new Error(`DingTalk card delivery failed: ${failedDelivery.errorMsg || JSON.stringify(failedDelivery)}`);
+            }
+            const deliveredTrackId = body?.result?.outTrackId;
+            if (typeof deliveredTrackId !== 'string' || !deliveredTrackId) {
+                throw new Error(`DingTalk card send succeeded without result.outTrackId: ${JSON.stringify(body)}`);
+            }
+            if (deliveredTrackId !== outTrackId) {
+                throw new Error(`DingTalk card send returned an unexpected outTrackId: ${deliveredTrackId}`);
+            }
+            this.trackPendingCard({
+                interaction,
+                chatId,
+                outTrackId,
+                messageId: outTrackId,
+                actionMap: this.cardActionMap(interaction),
+                createdAt: Date.now(),
+            });
+            // Only supersede older cards after the replacement was delivered and
+            // tracked. A transient create failure must not destroy the last usable
+            // approval/menu card.
+            await this.invalidatePendingCards(chatId, previousPendingCards);
+            return outTrackId;
+        });
+    }
+    async processCardCallback(callback, streamMessageId) {
+        if (!callback.outTrackId)
+            return this.privateCardFeedback('无法识别卡片');
+        const entry = this.cardsByTrackId.get(callback.outTrackId);
+        if (!entry || entry.invalidated || entry.resolved)
+            return this.privateCardFeedback('卡片已失效，请重新发起');
+        if (entry.interaction.expiresAt && entry.interaction.expiresAt <= Date.now()) {
+            entry.invalidated = true;
+            entry.invalidatedReason = 'expired';
+            entry.settledAt = Date.now();
+            this.untrackPendingCard(entry);
+            return this.cardResponse(entry, 'invalid', '审批已超时');
+        }
+        if (entry.interaction.initiatorId && callback.operatorId !== entry.interaction.initiatorId) {
+            return this.privateCardFeedback('仅卡片发起者可操作');
+        }
+        if (this.cardActionsInFlight.has(callback.outTrackId))
+            return this.privateCardFeedback('操作正在处理中');
+        const action = callback.actionId ? entry.actionMap.get(callback.actionId) : undefined;
+        if (!action)
+            return this.privateCardFeedback('无法识别所选操作');
+        this.cardActionsInFlight.add(callback.outTrackId);
+        try {
+            if (entry.interaction.kind.kind === 'command-card') {
+                if (!this.messageHandler)
+                    return this.privateCardFeedback('处理器暂不可用');
+                const route = this.routes.get(entry.chatId);
+                await this.messageHandler({
+                    channelId: entry.chatId,
+                    content: action,
+                    chatType: route?.chatType || 'private',
+                    peerId: callback.operatorId || '',
+                    messageId: `card-trigger-${streamMessageId}`,
+                    source: 'card-trigger',
+                });
+            }
+            else {
+                if (!this.interactionCallback)
+                    return this.privateCardFeedback('处理器暂不可用');
+                const response = {
+                    type: 'interaction.response',
+                    id: entry.interaction.id,
+                    action,
+                    values: callback.values,
+                    operatorId: callback.operatorId,
+                };
+                const accepted = (await this.interactionCallback(response)) !== false;
+                if (!accepted || entry.invalidated) {
+                    entry.invalidated = true;
+                    entry.invalidatedReason ||= 'backend_rejected';
+                    entry.settledAt = Date.now();
+                    this.untrackPendingCard(entry);
+                    return this.cardResponse(entry, 'invalid', '操作未被接受');
+                }
+            }
+            entry.resolved = true;
+            entry.settledAt = Date.now();
+            this.untrackPendingCard(entry);
+            const selected = entry.interaction.kind.buttons.find(button => (entry.interaction.kind.kind === 'command-card' ? button.command : button.key) === action);
+            return this.cardResponse(entry, 'resolved', selected?.label || '已处理');
+        }
+        finally {
+            this.cardActionsInFlight.delete(callback.outTrackId);
+        }
+    }
+    async handleCardCallbackMessage(msg) {
+        const data = typeof msg.data === 'string' ? parseJsonRecord(msg.data) : parseJsonRecord(msg.data);
+        const callback = parseDingtalkCardCallback(data);
+        const streamMessageId = msg?.headers?.messageId || `unknown-${Date.now()}`;
+        const work = this.processCardCallback(callback, streamMessageId);
+        let timedOut = false;
+        let timeoutId;
+        const timeout = new Promise(resolve => {
+            timeoutId = setTimeout(() => {
+                timedOut = true;
+                resolve(this.privateCardFeedback('操作已提交，正在处理'));
+            }, 1_500);
+        });
+        try {
+            const response = await Promise.race([work, timeout]);
+            if (!timedOut && timeoutId)
+                clearTimeout(timeoutId);
+            this.acknowledgeStreamMessage(msg, response);
+            if (timedOut) {
+                void work.then(async (finalResponse) => {
+                    const entry = callback.outTrackId ? this.cardsByTrackId.get(callback.outTrackId) : undefined;
+                    const cardData = finalResponse?.cardData;
+                    if (entry && cardData) {
+                        const state = entry.invalidated ? 'invalid' : 'resolved';
+                        const status = cardData?.cardParamMap?.status || '已处理';
+                        await this.updateCard(entry, state, status).catch(error => logger.warn('[DingTalk] Delayed card update failed:', error));
+                    }
+                }).catch(error => logger.error('[DingTalk] Delayed card callback failed:', error));
+            }
+        }
+        catch (error) {
+            if (timeoutId)
+                clearTimeout(timeoutId);
+            logger.error('[DingTalk] Card callback failed:', error);
+            this.acknowledgeStreamMessage(msg, this.privateCardFeedback('操作失败，请重试'));
         }
     }
 }
@@ -565,17 +1365,25 @@ export class DingtalkChannelPlugin {
             return null;
         if (!isValidCredential(inst.clientId) || !isValidCredential(inst.clientSecret))
             return null;
+        const stateKey = createHash('sha256').update(`${ctx.agentName}:${inst.name}`).digest('hex').slice(0, 16);
+        const dataDir = resolvePaths().dataDir;
+        if (inst.cardCallbackRouteKey) {
+            logger.warn(`[DingTalk] cardCallbackRouteKey is ignored for ${inst.name}; interactive cards use Stream callbacks`);
+        }
         const channel = new DingtalkChannel({
             clientId: inst.clientId,
             clientSecret: inst.clientSecret,
             requireMention: inst.requireMention,
             freeResponseChats: inst.freeResponseChats,
+            cardTemplateId: inst.cardTemplateId,
+            seenMsgFile: path.join(dataDir, `dingtalk-seen-${stateKey}.jsonl`),
+            routeFile: path.join(dataDir, `dingtalk-routes-${stateKey}.json`),
         }, ctx.agentName, inst.name);
         const mode = resolveShowActivities(inst);
         const adapter = {
             channelName: inst.name,
             channelKey: inst.name,
-            capabilities: { file: true, image: true, interaction: false, markdown: true, thought: false, status: false, thread: false, authenticatedApproval: true },
+            capabilities: { file: true, image: true, interaction: !!inst.cardTemplateId, markdown: true, thought: false, status: true, thread: false, authenticatedApproval: true },
             send: async (envelope, payload) => {
                 const channelId = envelope.channelId;
                 switch (payload.kind) {
@@ -585,35 +1393,55 @@ export class DingtalkChannelPlugin {
                     case 'system.notice':
                     case 'system.error':
                     case 'result.error':
-                        await channel.sendMessage(channelId, payload.text);
-                        return;
-                    case 'result.file':
-                        await channel.sendFile(channelId, payload.filePath);
-                        return;
-                    case 'result.image':
-                        await channel.sendImage(channelId, payload.data);
-                        return;
+                        return sentReceipt(envelope, await channel.sendMessage(channelId, payload.text));
+                    case 'result.file': return sentReceipt(envelope, await channel.sendFile(channelId, payload.filePath));
+                    case 'result.image': return sentReceipt(envelope, await channel.sendImage(channelId, payload.data));
                     case 'activity.batch': {
                         const filtered = payload.items.filter((i) => !(i.kind === 'tool_result' && i.ok));
                         const text = formatItemsAsText(filtered);
                         if (text)
-                            await channel.sendMessage(channelId, text);
-                        return;
+                            return sentReceipt(envelope, await channel.sendMessage(channelId, text));
+                        return suppressedReceipt(envelope, 'empty_activity');
                     }
+                    case 'status.started':
+                    case 'status.queued':
+                    case 'status.progress':
+                        return suppressedReceipt(envelope, 'reaction_lifecycle');
+                    case 'status.completed':
+                        await channel.completeAckReaction(envelope.taskId, true);
+                        return suppressedReceipt(envelope, 'reaction_lifecycle');
+                    case 'status.interrupted':
+                    case 'status.timeout':
+                        await channel.completeAckReaction(envelope.taskId, false);
+                        return suppressedReceipt(envelope, 'reaction_lifecycle');
                     case 'status.requires_action':
-                        await channel.sendMessage(channelId, '等待 owner 审批');
-                        return;
+                        return sentReceipt(envelope, await channel.sendMessage(channelId, '等待 owner 审批'));
                     case 'status.error':
+                        await channel.completeAckReaction(envelope.taskId, false);
                         if (payload.metadata?.message)
-                            await channel.sendMessage(channelId, payload.metadata.message);
-                        return;
-                    case 'interaction':
+                            return sentReceipt(envelope, await channel.sendMessage(channelId, payload.metadata.message));
+                        return suppressedReceipt(envelope, 'reaction_lifecycle');
+                    case 'interaction': {
+                        try {
+                            const messageId = await channel.sendInteraction(channelId, payload.interaction);
+                            if (messageId)
+                                return sentReceipt(envelope, [messageId]);
+                        }
+                        catch (error) {
+                            logger.warn(`[DingTalk] Interactive card delivery failed, using text fallback: ${error instanceof Error ? error.message : String(error)}`);
+                        }
                         if (payload.fallbackText)
-                            await channel.sendMessage(channelId, payload.fallbackText);
-                        return;
-                    default: return;
+                            return sentReceipt(envelope, await channel.sendMessage(channelId, payload.fallbackText));
+                        throw new Error('DingTalk interaction delivery failed and no fallback text was provided');
+                    }
+                    default: return suppressedReceipt(envelope, 'unhandled_payload');
                 }
             },
+            acknowledge: (messageId) => channel.acknowledgeMessage(messageId),
+            promoteAck: (messageId, context) => (channel.promoteAckReaction(messageId, context?.taskId, context?.messageIds)),
+            onInteraction: (callback) => channel.onInteraction(callback),
+            onInteractionInvalidated: (callback) => channel.onInteractionInvalidated(callback),
+            invalidateInteraction: (interactionId, reason) => channel.invalidateInteraction(interactionId, reason),
         };
         const policy = {
             canSwitchProject: (_, identity) => identity === 'owner' || identity === 'admin',
@@ -641,8 +1469,10 @@ export class DingtalkChannelPlugin {
                         selfAID: ctx.agentName, content: event.content, images: event.images,
                         chatType: event.chatType || 'private', peerId: event.peerId || '',
                         peerName: event.peerName, messageId: event.messageId,
+                        mentions: event.mentions, isMentioned: event.isMentioned,
+                        topicName: event.topicName, source: event.source,
                     });
-                }), (channelId, text) => channel.sendMessage(channelId, text), adapter, channelType);
+                }), async (channelId, text) => { await channel.sendMessage(channelId, text); }, adapter, channelType);
             },
         };
     }