evolcore 0.0.1 → 0.0.3

package/dist/channels/dingtalk.js

@@ -0,0 +1,1479 @@
+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();
+export function registerPendingDingtalkContactBind(req) {
+    const selfAid = String(req.selfAid || '').trim();
+    const channelName = String(req.channelName || '').trim();
+    const primaryId = String(req.primaryId || '').trim();
+    const now = req.now ?? Date.now();
+    const code = req.code ? String(req.code).trim() : generateDingtalkBindCode();
+    if (!isValidAid(selfAid))
+        return { ok: false, error: `invalid selfAid: ${req.selfAid}` };
+    if (!channelName)
+        return { ok: false, error: 'missing channelName' };
+    if (!isValidAid(primaryId))
+        return { ok: false, error: `invalid primaryId: ${req.primaryId}` };
+    if (!/^\d{6}$/.test(code))
+        return { ok: false, error: 'binding code must be 6 digits' };
+    const key = pendingBindKey(selfAid, channelName);
+    const replaced = pendingContactBinds.has(key);
+    const item = {
+        selfAid,
+        channelName,
+        primaryId,
+        code,
+        createdAt: now,
+        expiresAt: now + DINGTALK_BIND_CODE_TTL_MS,
+        failedAttempts: 0,
+        maxFailedAttempts: DINGTALK_BIND_MAX_FAILED_ATTEMPTS,
+    };
+    pendingContactBinds.set(key, item);
+    return { ok: true, code, expiresAt: item.expiresAt, replaced };
+}
+export function handlePendingDingtalkContactBindMessage(ctx) {
+    if (ctx.channelType !== 'dingtalk')
+        return { handled: false };
+    const selfAid = String(ctx.selfAid || '').trim();
+    const channelName = String(ctx.channelName || '').trim();
+    if (!selfAid || !channelName)
+        return { handled: false };
+    const key = pendingBindKey(selfAid, channelName);
+    const item = pendingContactBinds.get(key);
+    if (!item)
+        return { handled: false };
+    const now = ctx.now ?? Date.now();
+    if (now >= item.expiresAt) {
+        pendingContactBinds.delete(key);
+        return {
+            handled: true,
+            status: 'expired',
+            remainingAttempts: 0,
+            reply: '钉钉身份绑定码已超时，本次绑定失败。请重新执行 ec init dingtalk 并再次扫码绑定。',
+        };
+    }
+    if (ctx.chatType !== 'private')
+        return { handled: false };
+    const input = String(ctx.content ?? '').trim();
+    if (!/^\d+$/.test(input) || !/^\d{6}$/.test(input)) {
+        return {
+            handled: true,
+            status: 'format',
+            reply: '请直接发送 6 位数字绑定码。',
+            remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
+        };
+    }
+    if (input !== item.code) {
+        item.failedAttempts += 1;
+        const remaining = Math.max(0, item.maxFailedAttempts - item.failedAttempts);
+        if (remaining === 0) {
+            pendingContactBinds.delete(key);
+            return {
+                handled: true,
+                status: 'failed',
+                remainingAttempts: 0,
+                reply: '绑定码无效，本次钉钉身份绑定失败。请重新执行 ec init dingtalk 并再次扫码绑定。',
+            };
+        }
+        return {
+            handled: true,
+            status: 'wrong-code',
+            remainingAttempts: remaining,
+            reply: '绑定码错误，请重新发送 6 位数字绑定码。',
+        };
+    }
+    const actorId = String(ctx.actorId || '').trim();
+    if (!actorId) {
+        return {
+            handled: true,
+            status: 'missing-actor',
+            remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
+            reply: '无法识别当前钉钉发送者身份，未建立绑定。请重新发送绑定码或重新执行绑定流程。',
+        };
+    }
+    try {
+        bindContactAlias(item.selfAid, item.primaryId, 'dingtalk', actorId, item.channelName);
+        pendingContactBinds.delete(key);
+        return {
+            handled: true,
+            status: 'bound',
+            reply: `钉钉身份绑定成功：${item.channelName}:${encodeURIComponent(actorId)} -> ${item.primaryId}`,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            handled: true,
+            status: 'write-failed',
+            remainingAttempts: item.maxFailedAttempts - item.failedAttempts,
+            reply: `钉钉身份绑定写入失败：${message}`,
+        };
+    }
+}
+export function getPendingDingtalkContactBind(selfAid, channelName) {
+    const item = pendingContactBinds.get(pendingBindKey(selfAid, channelName));
+    return item ? { ...item } : null;
+}
+export function clearPendingDingtalkContactBinds() {
+    pendingContactBinds.clear();
+}
+function generateDingtalkBindCode() {
+    return String(randomInt(0, 1_000_000)).padStart(6, '0');
+}
+function pendingBindKey(selfAid, channelName) {
+    return `${String(selfAid || '').trim()}\u0000${String(channelName || '').trim()}`;
+}
+// ── Webhook SSRF validation ────────────────────────────────────────────────────
+const WEBHOOK_RE = /^https:\/\/(api|oapi)\.dingtalk\.com\//;
+// ── DingtalkChannel ────────────────────────────────────────────────────────────
+export class DingtalkChannel {
+    agentAid;
+    channelName;
+    config;
+    client = null;
+    connected = false;
+    messageHandler = null;
+    recallHandler;
+    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
+    welcomeManager;
+    constructor(config, agentAid, channelName) {
+        this.agentAid = agentAid;
+        this.channelName = channelName;
+        this.config = config;
+        // 初始化 welcomeManager（使用共享帮助函数）
+        if (agentAid && channelName) {
+            this.welcomeManager = initWelcomeManager('dingtalk', agentAid, channelName);
+        }
+    }
+    // ── Public helpers (testable) ──────────────────────────────────────────────
+    isValidWebhook(url) {
+        if (!url)
+            return false;
+        return WEBHOOK_RE.test(url);
+    }
+    isDuplicate(msgId, chatId = '') {
+        if (this.seenMessages.has(msgId))
+            return true;
+        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;
+    }
+    shouldProcessGroupMessage(conversationId, isInAtList) {
+        if (this.config.requireMention === false)
+            return true;
+        if (this.config.freeResponseChats?.includes(conversationId))
+            return true;
+        return isInAtList;
+    }
+    extractText(content) {
+        if (!content)
+            return '';
+        const text = content.text;
+        if (typeof text === 'string')
+            return text.trim();
+        if (text && typeof text === 'object' && typeof text.content === 'string')
+            return text.content.trim();
+        return '';
+    }
+    // ── Lifecycle ──────────────────────────────────────────────────────────────
+    async connect() {
+        const { clientId, clientSecret } = this.config;
+        if (!clientId || !clientSecret || clientId.includes('your-') || clientSecret.includes('your-')) {
+            throw new Error('DingTalk clientId/clientSecret not configured');
+        }
+        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
+        this.cleanupInterval = setInterval(() => {
+            const cutoff = Date.now() - 24 * 60 * 60 * 1000;
+            for (const [id, ts] of this.seenMessages) {
+                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');
+    }
+    async disconnect() {
+        this.connected = false;
+        if (this.cleanupInterval) {
+            clearInterval(this.cleanupInterval);
+            this.cleanupInterval = null;
+        }
+        if (this.client) {
+            try {
+                this.client.disconnect();
+            }
+            catch { /* ignore */ }
+            this.client = null;
+        }
+        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;
+            const conversationType = data.conversationType;
+            const conversationId = data.conversationId;
+            const senderId = data.senderStaffId || data.senderId;
+            const senderNick = data.senderNick;
+            const sessionWebhook = data.sessionWebhook;
+            const msgtype = data.msgtype;
+            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;
+            }
+            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') {
+                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);
+            }
+            // Dispatch by msgtype
+            if (!this.messageHandler)
+                return;
+            // 首次交互欢迎消息（使用共享帮助函数）
+            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)
+                    return;
+                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, eventMetadata);
+            }
+            else if (msgtype === 'file') {
+                await this.handleFileMessage(data, chatId, chatType, senderId, senderNick, msgId, eventMetadata);
+            }
+            else if (msgtype === 'richText') {
+                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,
+                });
+            }
+        }
+        catch (error) {
+            logger.error('[DingTalk] Failed to process incoming message:', error);
+        }
+    }
+    // ── Inbound media handling ─────────────────────────────────────────────────
+    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 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 { validateImage } = await import('../utils/media-cache.js');
+            const buffer = await this.downloadMessageMedia(downloadRef);
+            const result = await validateImage(buffer);
+            if (result.mime) {
+                await this.messageHandler({
+                    channelId: chatId,
+                    content: '用户发送了一张图片，请分析这张图片的内容。',
+                    chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                    images: [{ data: buffer.toString('base64'), mimeType: result.mime }],
+                    ...metadata,
+                });
+            }
+            else {
+                logger.warn(`[DingTalk] Image validation failed: ${!result.mime && 'reason' in result ? result.reason : 'unknown'}`);
+                await this.messageHandler({
+                    channelId: chatId, content: '[图片验证失败]',
+                    chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                    ...metadata,
+                });
+            }
+        }
+        catch (error) {
+            logger.error('[DingTalk] Failed to download image:', error);
+            await this.messageHandler({
+                channelId: chatId, content: '[图片下载失败]',
+                chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                ...metadata,
+            });
+        }
+    }
+    async handleFileMessage(data, chatId, chatType, senderId, senderNick, msgId, metadata = {}) {
+        const content = typeof data.content === 'string' ? JSON.parse(data.content) : (data.content || {});
+        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 { saveToUploads, sanitizeFileName } = await import('../utils/media-cache.js');
+            const projectPath = this.projectPathProvider
+                ? await this.projectPathProvider(chatId)
+                : process.cwd();
+            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) {
+            logger.error('[DingTalk] Failed to download file:', error);
+            await this.messageHandler({
+                channelId: chatId, content: `[文件下载失败] ${fileName}`,
+                chatType, peerId: senderId || '', peerName: senderNick, messageId: msgId,
+                ...metadata,
+            });
+        }
+    }
+    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;
+        }
+        let text = '';
+        const images = [];
+        for (const item of richText) {
+            if (item.type === 'text' && item.text) {
+                text += item.text;
+            }
+            else if (item.type === 'picture' && (item.downloadUrl || item.downloadCode)) {
+                try {
+                    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 });
+                    }
+                }
+                catch (error) {
+                    logger.warn('[DingTalk] Failed to download richText image:', error);
+                }
+            }
+        }
+        const prompt = text.trim() || (images.length > 0 ? '用户发送了一张图片，请分析这张图片的内容。' : '[空消息]');
+        await this.messageHandler({
+            channelId: chatId, content: prompt, chatType,
+            peerId: senderId || '', peerName: senderNick, messageId: msgId,
+            images: images.length > 0 ? images : undefined,
+            ...metadata,
+        });
+    }
+    // ── Outbound: OpenAPI sends return processQueryKey message receipts ───────
+    async sendMessage(chatId, content) {
+        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();
+            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,
+                },
+                body: JSON.stringify({
+                    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),
+            });
+            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.debug(`[DingTalk] ${recall ? 'recall' : 'reply'} emotion ${emotionName} failed for ${messageId}: ${error?.message || error}`);
+            return false;
+        }
+    }
+    // ── Outbound: image via Open API ───────────────────────────────────────────
+    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}`);
+        }
+        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 {
+            bytesRead = fs.readSync(fd, header, 0, header.length, 0);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        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 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
+            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),
+            });
+        }
+        else if (staffId || (!route && chatId)) {
+            // DM: use senderStaffId
+            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: [targetStaffId], robotCode: clientId }),
+                signal: AbortSignal.timeout(15_000),
+            });
+        }
+        else {
+            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('操作失败，请重试'));
+        }
+    }
+}
+// ── Plugin ─────────────────────────────────────────────────────────────────────
+function isValidCredential(value) {
+    return !!value && !value.includes('your-') && !value.includes('placeholder');
+}
+export class DingtalkChannelPlugin {
+    name = 'dingtalk';
+    async createInstance(inst, ctx) {
+        if (inst.enabled === false)
+            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: !!inst.cardTemplateId, markdown: true, thought: false, status: true, thread: false, authenticatedApproval: true },
+            send: async (envelope, payload) => {
+                const channelId = envelope.channelId;
+                switch (payload.kind) {
+                    case 'result.text':
+                    case 'command.result':
+                    case 'command.error':
+                    case 'system.notice':
+                    case 'system.error':
+                    case 'result.error':
+                        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)
+                            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':
+                        return sentReceipt(envelope, await channel.sendMessage(channelId, '等待 owner 审批'));
+                    case 'status.error':
+                        await channel.completeAckReaction(envelope.taskId, false);
+                        if (payload.metadata?.message)
+                            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)
+                            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',
+            canListProjects: (_, identity) => identity === 'owner' || identity === 'admin',
+            canCreateSession: () => true,
+            canDeleteSession: () => true,
+            canImportCliSession: (_, identity) => identity === 'owner' || identity === 'admin',
+            messagePrefix: (chatType, peerName) => (chatType === 'group' && peerName) ? `[${peerName}] ` : '',
+            showMiddleResult: (chatType, identity) => showActivitiesPolicy(mode, chatType, identity),
+            middleOutputMode: (chatType, identity) => middleOutputModePolicy(mode, chatType, identity),
+            showIdleMonitor: (chatType, identity) => showActivitiesPolicy(mode, chatType, identity),
+            accumulateErrors: () => true,
+        };
+        return {
+            channelType: 'dingtalk', adapter, channel,
+            policy,
+            options: { fileMarkerPattern: /\[SEND_FILE:(?:(\w+):)?([^\]]+)\]/g, supportsImages: true, flushDelay: inst.flushDelay },
+            connect: () => channel.connect(),
+            disconnect: () => channel.disconnect(),
+            onProjectPathRequest: () => Promise.resolve(ctx.defaultProjectPath),
+            registerBridge(bridge, channelType) {
+                bridge.register(adapter.channelName, (handler) => channel.onMessage(async (event) => {
+                    await handler({
+                        channel: adapter.channelName, channelType, channelId: event.channelId,
+                        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,
+                    });
+                }), async (channelId, text) => { await channel.sendMessage(channelId, text); }, adapter, channelType);
+            },
+        };
+    }
+}