@soimy/dingtalk 2.6.5

package/src/channel.ts

@@ -0,0 +1,1807 @@
+import { DWClient, TOPIC_ROBOT } from 'dingtalk-stream';
+import axios from 'axios';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import type { OpenClawConfig } from 'openclaw/plugin-sdk';
+import { buildChannelConfigSchema } from 'openclaw/plugin-sdk';
+import { maskSensitiveData, cleanupOrphanedTempFiles, retryWithBackoff } from './utils';
+import { getDingTalkRuntime } from './runtime';
+import { DingTalkConfigSchema } from './config-schema.js';
+import { registerPeerId, resolveOriginalPeerId } from './peer-id-registry';
+import { ConnectionManager } from './connection-manager';
+import { dingtalkOnboardingAdapter } from './onboarding.js';
+import type {
+  DingTalkConfig,
+  TokenInfo,
+  DingTalkInboundMessage,
+  MessageContent,
+  SendMessageOptions,
+  MediaFile,
+  HandleDingTalkMessageParams,
+  ProactiveMessagePayload,
+  SessionWebhookResponse,
+  AxiosResponse,
+  Logger,
+  ResolvedAccount,
+  GatewayStartContext,
+  GatewayStopResult,
+  AICardInstance,
+  AICardStreamingRequest,
+  ConnectionManagerConfig,
+  DingTalkChannelPlugin,
+} from './types';
+import { AICardStatus, ConnectionState } from './types';
+import { detectMediaTypeFromExtension, uploadMedia as uploadMediaUtil } from './media-utils';
+
+/**
+ * Get current timestamp in ISO 8601 format for status tracking
+ */
+function getCurrentTimestamp(): number {
+  return Date.now();
+}
+
+// Access Token cache - keyed by clientId for multi-account support
+interface TokenCache {
+  accessToken: string;
+  expiry: number;
+}
+const accessTokenCache = new Map<string, TokenCache>();
+
+// Global logger reference for use across module methods
+let currentLogger: Logger | undefined;
+
+// AI Card instance cache for streaming updates
+const aiCardInstances = new Map<string, AICardInstance>();
+
+// Target to active AI Card instance ID mapping (accountId:conversationId -> cardInstanceId)
+// Used to quickly lookup existing active cards for a target
+const activeCardsByTarget = new Map<string, string>();
+
+// Card cache TTL (1 hour)
+const CARD_CACHE_TTL = 60 * 60 * 1000; // 1 hour
+
+// DingTalk API base URL
+const DINGTALK_API = 'https://api.dingtalk.com';
+
+// ============ Message Deduplication ============
+// Prevents duplicate message processing when DingTalk retries delivery
+// Uses pure in-memory storage with short TTL and lazy cleanup during processing
+
+const processedMessages = new Map<string, number>(); // Map<dedupKey, expiresAt>
+const MESSAGE_DEDUP_TTL = 60000; // 60 seconds
+const MESSAGE_DEDUP_MAX_SIZE = 1000; // Hard cap to prevent memory pressure during bursts
+let messageCounter = 0; // Counter for deterministic cleanup triggering (safe due to Node.js single-threaded event loop)
+
+// Check if message was already processed (with lazy cleanup of expired entries)
+function isMessageProcessed(dedupKey: string): boolean {
+  const now = Date.now();
+  const expiresAt = processedMessages.get(dedupKey);
+
+  if (expiresAt === undefined) {
+    return false;
+  }
+
+  // Lazy cleanup: remove expired entry if found
+  if (now >= expiresAt) {
+    processedMessages.delete(dedupKey);
+    return false;
+  }
+
+  return true;
+}
+
+// Mark message as processed with bot-scoped key
+function markMessageProcessed(dedupKey: string): void {
+  const expiresAt = Date.now() + MESSAGE_DEDUP_TTL;
+  processedMessages.set(dedupKey, expiresAt);
+
+  // Hard cap: if Map exceeds max size, force immediate cleanup
+  if (processedMessages.size > MESSAGE_DEDUP_MAX_SIZE) {
+    const now = Date.now();
+    for (const [key, expiry] of processedMessages.entries()) {
+      if (now >= expiry) {
+        processedMessages.delete(key);
+      }
+    }
+    // If still over limit after cleanup, clear oldest entries (safety valve)
+    // Maps maintain insertion order, so we can delete early entries
+    if (processedMessages.size > MESSAGE_DEDUP_MAX_SIZE) {
+      const removeCount = processedMessages.size - MESSAGE_DEDUP_MAX_SIZE;
+      let removed = 0;
+      for (const key of processedMessages.keys()) {
+        processedMessages.delete(key);
+        if (++removed >= removeCount) break;
+      }
+    }
+    return; // Skip regular cleanup since we just did a full sweep
+  }
+
+  // Lazy cleanup: remove expired entries deterministically every 10 messages
+  // With 60s TTL, Map stays small under normal load, but we avoid cleanup on every message for performance
+  messageCounter++;
+  if (messageCounter >= 10) {
+    messageCounter = 0;
+    const now = Date.now();
+    for (const [key, expiry] of processedMessages.entries()) {
+      if (now >= expiry) {
+        processedMessages.delete(key);
+      }
+    }
+  }
+}
+
+// Authorization helpers
+type NormalizedAllowFrom = {
+  entries: string[];
+  entriesLower: string[];
+  hasWildcard: boolean;
+  hasEntries: boolean;
+};
+
+/**
+ * Normalize allowFrom list to standardized format
+ */
+function normalizeAllowFrom(list?: Array<string>): NormalizedAllowFrom {
+  const entries = (list ?? []).map((value) => String(value).trim()).filter(Boolean);
+  const hasWildcard = entries.includes('*');
+  const normalized = entries
+    .filter((value) => value !== '*')
+    .map((value) => value.replace(/^(dingtalk|dd|ding):/i, ''));
+  const normalizedLower = normalized.map((value) => value.toLowerCase());
+  return {
+    entries: normalized,
+    entriesLower: normalizedLower,
+    hasWildcard,
+    hasEntries: entries.length > 0,
+  };
+}
+
+/**
+ * Check if sender is allowed based on allowFrom list
+ */
+function isSenderAllowed(params: { allow: NormalizedAllowFrom; senderId?: string }): boolean {
+  const { allow, senderId } = params;
+  if (!allow.hasEntries) return true;
+  if (allow.hasWildcard) return true;
+  if (senderId && allow.entriesLower.includes(senderId.toLowerCase())) return true;
+  return false;
+}
+
+// 群组通道授权
+function isSenderGroupAllowed(params: { allow: NormalizedAllowFrom; groupId?: string }): boolean {
+  const { allow, groupId } = params;
+
+  if (groupId && allow.entriesLower.includes(groupId.toLowerCase())) return true;
+  return false;
+}
+
+// Helper function to check if a card is in a terminal state
+function isCardInTerminalState(state: string): boolean {
+  return state === AICardStatus.FINISHED || state === AICardStatus.FAILED;
+}
+
+// Clean up old AI card instances from cache
+function cleanupCardCache() {
+  const now = Date.now();
+
+  // Clean up AI card instances that are in FINISHED or FAILED state
+  // Active cards (PROCESSING, INPUTING) are not cleaned up even if they exceed TTL
+  for (const [cardInstanceId, instance] of aiCardInstances.entries()) {
+    if (isCardInTerminalState(instance.state) && now - instance.lastUpdated > CARD_CACHE_TTL) {
+      // Remove from aiCardInstances
+      aiCardInstances.delete(cardInstanceId);
+
+      // Remove from activeCardsByTarget mapping (break after first match for efficiency)
+      for (const [targetKey, mappedCardId] of activeCardsByTarget.entries()) {
+        if (mappedCardId === cardInstanceId) {
+          activeCardsByTarget.delete(targetKey);
+          break; // Each card should only have one target mapping
+        }
+      }
+    }
+  }
+}
+
+/**
+ * Get the current logger instance
+ * Useful for methods that don't receive log as a parameter
+ */
+function getLogger(): Logger | undefined {
+  return currentLogger;
+}
+
+// Helper function to detect markdown and extract title
+function detectMarkdownAndExtractTitle(
+  text: string,
+  options: SendMessageOptions,
+  defaultTitle: string
+): { useMarkdown: boolean; title: string } {
+  const hasMarkdown = /^[#*>-]|[*_`#[\]]/.test(text) || text.includes('\n');
+  const useMarkdown = options.useMarkdown !== false && (options.useMarkdown || hasMarkdown);
+
+  const title =
+    options.title ||
+    (useMarkdown
+      ? text
+          .split('\n')[0]
+          .replace(/^[#*\s\->]+/, '')
+          .slice(0, 20) || defaultTitle
+      : defaultTitle);
+
+  return { useMarkdown, title };
+}
+
+// ============ Group Members Persistence ============
+
+function groupMembersFilePath(storePath: string, groupId: string): string {
+  const dir = path.join(path.dirname(storePath), 'dingtalk-members');
+  const safeId = groupId.replace(/\+/g, '-').replace(/\//g, '_');
+  return path.join(dir, `${safeId}.json`);
+}
+
+function noteGroupMember(storePath: string, groupId: string, userId: string, name: string): void {
+  if (!userId || !name) return;
+  const filePath = groupMembersFilePath(storePath, groupId);
+  let roster: Record<string, string> = {};
+  try {
+    roster = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {}
+  if (roster[userId] === name) return;
+  roster[userId] = name;
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, JSON.stringify(roster, null, 2));
+}
+
+function formatGroupMembers(storePath: string, groupId: string): string | undefined {
+  const filePath = groupMembersFilePath(storePath, groupId);
+  let roster: Record<string, string> = {};
+  try {
+    roster = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+  } catch {
+    return undefined;
+  }
+  const entries = Object.entries(roster);
+  if (entries.length === 0) return undefined;
+  return entries.map(([id, name]) => `${name} (${id})`).join(', ');
+}
+
+// ============ Group Config Resolution ============
+
+function resolveGroupConfig(cfg: DingTalkConfig, groupId: string): { systemPrompt?: string } | undefined {
+  const groups = cfg.groups;
+  if (!groups) return undefined;
+  return groups[groupId] || groups['*'] || undefined;
+}
+
+// ============ Target Prefix Helpers ============
+
+/**
+ * Strip group: or user: prefix from target ID
+ * Returns the raw targetId and whether it was explicitly marked as a user
+ */
+function stripTargetPrefix(target: string): { targetId: string; isExplicitUser: boolean } {
+  if (target.startsWith('group:')) {
+    return { targetId: target.slice(6), isExplicitUser: false };
+  }
+  if (target.startsWith('user:')) {
+    return { targetId: target.slice(5), isExplicitUser: true };
+  }
+  return { targetId: target, isExplicitUser: false };
+}
+
+// ============ Config Helpers ============
+
+function getConfig(cfg: OpenClawConfig, accountId?: string): DingTalkConfig {
+  const dingtalkCfg = cfg?.channels?.dingtalk as DingTalkConfig | undefined;
+  if (!dingtalkCfg) return {} as DingTalkConfig;
+
+  if (accountId && dingtalkCfg.accounts?.[accountId]) {
+    return dingtalkCfg.accounts[accountId];
+  }
+
+  return dingtalkCfg;
+}
+
+function isConfigured(cfg: OpenClawConfig, accountId?: string): boolean {
+  const config = getConfig(cfg, accountId);
+  return Boolean(config.clientId && config.clientSecret);
+}
+
+const DEFAULT_AGENT_ID = 'main';
+const VALID_AGENT_ID_RE = /^[a-z0-9][a-z0-9_-]{0,63}$/i;
+const INVALID_AGENT_ID_CHARS_RE = /[^a-z0-9_-]+/g;
+const LEADING_DASH_RE = /^-+/;
+const TRAILING_DASH_RE = /-+$/;
+
+function normalizeAgentId(value: string | undefined | null): string {
+  const trimmed = (value ?? '').trim();
+  if (!trimmed) return DEFAULT_AGENT_ID;
+  if (VALID_AGENT_ID_RE.test(trimmed)) return trimmed.toLowerCase();
+  return (
+    trimmed
+      .toLowerCase()
+      .replace(INVALID_AGENT_ID_CHARS_RE, '-')
+      .replace(LEADING_DASH_RE, '')
+      .replace(TRAILING_DASH_RE, '')
+      .slice(0, 64) || DEFAULT_AGENT_ID
+  );
+}
+
+function resolveUserPath(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return trimmed;
+  if (trimmed.startsWith('~')) {
+    const expanded = trimmed.replace(/^~(?=$|[\\/])/, os.homedir());
+    return path.resolve(expanded);
+  }
+  return path.resolve(trimmed);
+}
+
+function resolveDefaultAgentWorkspaceDir(): string {
+  const profile = process.env.OPENCLAW_PROFILE?.trim();
+  if (profile && profile.toLowerCase() !== 'default') {
+    return path.join(os.homedir(), '.openclaw', `workspace-${profile}`);
+  }
+  return path.join(os.homedir(), '.openclaw', 'workspace');
+}
+
+interface AgentConfig {
+  id?: string;
+  default?: boolean;
+  workspace?: string;
+}
+
+function resolveDefaultAgentId(cfg: OpenClawConfig): string {
+  const agents: AgentConfig[] = cfg.agents?.list ?? [];
+  if (agents.length === 0) return DEFAULT_AGENT_ID;
+  const defaults = agents.filter((agent: AgentConfig) => agent?.default);
+  const chosen = (defaults[0] ?? agents[0])?.id?.trim();
+  return normalizeAgentId(chosen || DEFAULT_AGENT_ID);
+}
+
+function resolveAgentWorkspaceDir(cfg: OpenClawConfig, agentId: string): string {
+  const id = normalizeAgentId(agentId);
+  const agents: AgentConfig[] = cfg.agents?.list ?? [];
+  const agent = agents.find((entry: AgentConfig) => normalizeAgentId(entry?.id) === id);
+  const configured = agent?.workspace?.trim();
+  if (configured) return resolveUserPath(configured);
+  const defaultAgentId = resolveDefaultAgentId(cfg);
+  if (id === defaultAgentId) {
+    const fallback = cfg.agents?.defaults?.workspace?.trim();
+    if (fallback) return resolveUserPath(fallback);
+    return resolveDefaultAgentWorkspaceDir();
+  }
+  return path.join(os.homedir(), '.openclaw', `workspace-${id}`);
+}
+
+// Get Access Token with retry logic - uses clientId-based cache for multi-account support
+async function getAccessToken(config: DingTalkConfig, log?: Logger): Promise<string> {
+  const cacheKey = config.clientId;
+  const now = Date.now();
+  const cached = accessTokenCache.get(cacheKey);
+
+  if (cached && cached.expiry > now + 60000) {
+    return cached.accessToken;
+  }
+
+  const token = await retryWithBackoff(
+    async () => {
+      const response = await axios.post<TokenInfo>('https://api.dingtalk.com/v1.0/oauth2/accessToken', {
+        appKey: config.clientId,
+        appSecret: config.clientSecret,
+      });
+
+      // Store in cache with clientId as key
+      accessTokenCache.set(cacheKey, {
+        accessToken: response.data.accessToken,
+        expiry: now + response.data.expireIn * 1000,
+      });
+
+      return response.data.accessToken;
+    },
+    { maxRetries: 3, log }
+  );
+
+  return token;
+}
+
+// Wrapper function to upload media via uploadMediaUtil with getAccessToken bound
+async function uploadMedia(
+  config: DingTalkConfig,
+  mediaPath: string,
+  mediaType: 'image' | 'voice' | 'video' | 'file',
+  log?: Logger
+): Promise<string | null> {
+  return uploadMediaUtil(config, mediaPath, mediaType, getAccessToken, log);
+}
+
+// Send text/markdown proactive message via DingTalk OpenAPI
+async function sendProactiveTextOrMarkdown(
+  config: DingTalkConfig,
+  target: string,
+  text: string,
+  options: SendMessageOptions = {}
+): Promise<AxiosResponse> {
+  const token = await getAccessToken(config, options.log);
+  const log = options.log || getLogger();
+
+  // Support group: and user: prefixes, and resolve case-sensitive conversationId
+  const { targetId, isExplicitUser } = stripTargetPrefix(target);
+  const resolvedTarget = resolveOriginalPeerId(targetId);
+  const isGroup = !isExplicitUser && resolvedTarget.startsWith('cid');
+
+  const url = isGroup
+    ? 'https://api.dingtalk.com/v1.0/robot/groupMessages/send'
+    : 'https://api.dingtalk.com/v1.0/robot/oToMessages/batchSend';
+
+  // Use shared helper function for markdown detection and title extraction
+  const { useMarkdown, title } = detectMarkdownAndExtractTitle(text, options, 'OpenClaw 提醒');
+
+  log?.debug?.(
+    `[DingTalk] Sending proactive message to ${isGroup ? 'group' : 'user'} ${resolvedTarget} with title "${title}"`
+  );
+
+  // Choose msgKey based on whether we're sending markdown or plain text
+  // Note: DingTalk's proactive message API uses predefined message templates
+  // sampleMarkdown supports markdown formatting, sampleText for plain text
+  const msgKey = useMarkdown ? 'sampleMarkdown' : 'sampleText';
+  const msgParam = useMarkdown ? JSON.stringify({ title, text }) : JSON.stringify({ content: text });
+
+  const payload: ProactiveMessagePayload = {
+    robotCode: config.robotCode || config.clientId,
+    msgKey,
+    msgParam,
+  };
+
+  if (isGroup) {
+    payload.openConversationId = resolvedTarget;
+  } else {
+    payload.userIds = [resolvedTarget];
+  }
+
+  const result = await axios({
+    url,
+    method: 'POST',
+    data: payload,
+    headers: { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' },
+  });
+  return result.data;
+}
+
+// Send proactive media message via DingTalk OpenAPI
+async function sendProactiveMedia(
+  config: DingTalkConfig,
+  target: string,
+  mediaPath: string,
+  mediaType: 'image' | 'voice' | 'video' | 'file',
+  options: SendMessageOptions & { accountId?: string } = {}
+): Promise<{ ok: boolean; error?: string; data?: any; messageId?: string }> {
+  const log = options.log || getLogger();
+
+  try {
+    // Upload media first to get media_id
+    const mediaId = await uploadMedia(config, mediaPath, mediaType, log);
+    if (!mediaId) {
+      return { ok: false, error: 'Failed to upload media' };
+    }
+
+    const token = await getAccessToken(config, log);
+    const { targetId, isExplicitUser } = stripTargetPrefix(target);
+    const resolvedTarget = resolveOriginalPeerId(targetId);
+    const isGroup = !isExplicitUser && resolvedTarget.startsWith('cid');
+
+    const DINGTALK_API = 'https://api.dingtalk.com';
+    const url = isGroup
+      ? `${DINGTALK_API}/v1.0/robot/groupMessages/send`
+      : `${DINGTALK_API}/v1.0/robot/oToMessages/batchSend`;
+
+    // Build payload based on media type
+    // For personal messages (oToMessages), use native media message types
+    // For group messages (groupMessages), use sampleImageMsg/sampleAudio/etc.
+    let msgKey: string;
+    let msgParam: string;
+
+    if (mediaType === 'image') {
+      msgKey = 'sampleImageMsg';
+      msgParam = JSON.stringify({ photoURL: mediaId });
+    } else if (mediaType === 'voice') {
+      msgKey = 'sampleAudio';
+      msgParam = JSON.stringify({ mediaId, duration: '0' });
+    } else {
+      // File-like media (including video)
+      // Note: sampleVideo requires a cover image (picMediaId) which we don't have,
+      // so we fall back to sampleFile for video to avoid .octet-stream issues.
+      const filename = path.basename(mediaPath);
+      const defaultExt = mediaType === 'video' ? 'mp4' : 'file';
+      const ext = path.extname(mediaPath).slice(1) || defaultExt;
+      msgKey = 'sampleFile';
+      msgParam = JSON.stringify({ mediaId, fileName: filename, fileType: ext });
+    }
+
+    const payload: ProactiveMessagePayload = {
+      robotCode: config.robotCode || config.clientId,
+      msgKey,
+      msgParam,
+    };
+
+    if (isGroup) {
+      payload.openConversationId = resolvedTarget;
+    } else {
+      payload.userIds = [resolvedTarget];
+    }
+
+    log?.debug?.(
+      `[DingTalk] Sending proactive ${mediaType} message to ${isGroup ? 'group' : 'user'} ${resolvedTarget}`
+    );
+
+    const result = await axios({
+      url,
+      method: 'POST',
+      data: payload,
+      headers: { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' },
+    });
+
+    const messageId = result.data?.processQueryKey || result.data?.messageId;
+    return { ok: true, data: result.data, messageId };
+  } catch (err: any) {
+    log?.error?.(`[DingTalk] Failed to send proactive media: ${err.message}`);
+    if (axios.isAxiosError(err) && err.response) {
+      log?.error?.(`[DingTalk] Response: ${JSON.stringify(err.response.data)}`);
+    }
+    return { ok: false, error: err.message };
+  }
+}
+
+// Download media file to agent workspace (sandbox-compatible)
+// workspacePath: the agent's workspace directory (e.g., /home/node/.openclaw/workspace)
+async function downloadMedia(
+  config: DingTalkConfig,
+  downloadCode: string,
+  workspacePath: string,
+  log?: Logger
+): Promise<MediaFile | null> {
+  const formatAxiosErrorData = (value: unknown): string | undefined => {
+    if (value === null || value === undefined) return undefined;
+    if (Buffer.isBuffer(value)) return `<buffer ${value.length} bytes>`;
+    if (value instanceof ArrayBuffer) return `<arraybuffer ${value.byteLength} bytes>`;
+    if (typeof value === 'string') return value.length > 500 ? `${value.slice(0, 500)}…` : value;
+    try {
+      return JSON.stringify(maskSensitiveData(value));
+    } catch {
+      return String(value);
+    }
+  };
+
+  if (!downloadCode) {
+    log?.error?.('[DingTalk] downloadMedia requires downloadCode to be provided.');
+    return null;
+  }
+  if (!config.robotCode) {
+    if (log?.error) {
+      log.error('[DingTalk] downloadMedia requires robotCode to be configured.');
+    }
+    return null;
+  }
+  try {
+    const token = await getAccessToken(config, log);
+    const response = await axios.post(
+      'https://api.dingtalk.com/v1.0/robot/messageFiles/download',
+      { downloadCode, robotCode: config.robotCode },
+      { headers: { 'x-acs-dingtalk-access-token': token } }
+    );
+    const payload = response.data as Record<string, any>;
+    const downloadUrl = payload?.downloadUrl ?? payload?.data?.downloadUrl;
+    if (!downloadUrl) {
+      const payloadDetail = formatAxiosErrorData(payload);
+      log?.error?.(`[DingTalk] downloadMedia missing downloadUrl. payload=${payloadDetail ?? 'unknown'}`);
+      return null;
+    }
+    const mediaResponse = await axios.get(downloadUrl, { responseType: 'arraybuffer' });
+    const contentType = mediaResponse.headers['content-type'] || 'application/octet-stream';
+    const buffer = Buffer.from(mediaResponse.data as ArrayBuffer);
+
+    // Save to agent workspace's media/inbound/ directory (sandbox-compatible)
+    // This ensures the file is accessible within the sandbox
+    const mediaDir = path.join(workspacePath, 'media', 'inbound');
+    fs.mkdirSync(mediaDir, { recursive: true });
+
+    const ext = contentType.split('/')[1]?.split(';')[0] || 'bin';
+    const filename = `${Date.now()}_${Math.random().toString(36).slice(2, 8)}.${ext}`;
+    const mediaPath = path.join(mediaDir, filename);
+
+    fs.writeFileSync(mediaPath, buffer);
+    log?.debug?.(`[DingTalk] Media saved to workspace: ${mediaPath}`);
+    return { path: mediaPath, mimeType: contentType };
+  } catch (err: any) {
+    if (log?.error) {
+      if (axios.isAxiosError(err)) {
+        const status = err.response?.status;
+        const statusText = err.response?.statusText;
+        const dataDetail = formatAxiosErrorData(err.response?.data);
+        const code = err.code ? ` code=${err.code}` : '';
+        const statusLabel = status ? ` status=${status}${statusText ? ` ${statusText}` : ''}` : '';
+        log.error(`[DingTalk] Failed to download media:${statusLabel}${code} message=${err.message}`);
+        if (dataDetail) {
+          log.error(`[DingTalk] downloadMedia response data: ${dataDetail}`);
+        }
+      } else {
+        log.error(`[DingTalk] Failed to download media: ${err.message}`);
+      }
+    }
+    return null;
+  }
+}
+
+function extractMessageContent(data: DingTalkInboundMessage): MessageContent {
+  const msgtype = data.msgtype || 'text';
+
+  // Logic for different message types
+  if (msgtype === 'text') {
+    return { text: data.text?.content?.trim() || '', messageType: 'text' };
+  }
+
+  // Improved richText parsing: join all text/at components and extract first picture
+  if (msgtype === 'richText') {
+    const richTextParts = data.content?.richText || [];
+    let text = '';
+    let pictureDownloadCode: string | undefined;
+    for (const part of richTextParts) {
+      // Handle text content: include explicit text type or undefined type field (DingTalk may omit type)
+      if (part.text && (part.type === 'text' || part.type === undefined)) text += part.text;
+      if (part.type === 'at' && part.atName) text += `@${part.atName} `;
+      // Extract first picture's downloadCode from richText
+      if (part.type === 'picture' && part.downloadCode && !pictureDownloadCode) {
+        pictureDownloadCode = part.downloadCode;
+      }
+    }
+    return {
+      text: text.trim() || (pictureDownloadCode ? '<media:image>' : '[富文本消息]'),
+      mediaPath: pictureDownloadCode,
+      mediaType: pictureDownloadCode ? 'image' : undefined,
+      messageType: 'richText',
+    };
+  }
+
+  if (msgtype === 'picture') {
+    return { text: '<media:image>', mediaPath: data.content?.downloadCode, mediaType: 'image', messageType: 'picture' };
+  }
+
+  if (msgtype === 'audio') {
+    return {
+      text: data.content?.recognition || '<media:voice>',
+      mediaPath: data.content?.downloadCode,
+      mediaType: 'audio',
+      messageType: 'audio',
+    };
+  }
+
+  if (msgtype === 'video') {
+    return { text: '<media:video>', mediaPath: data.content?.downloadCode, mediaType: 'video', messageType: 'video' };
+  }
+
+  if (msgtype === 'file') {
+    return {
+      text: `<media:file> (${data.content?.fileName || '文件'})`,
+      mediaPath: data.content?.downloadCode,
+      mediaType: 'file',
+      messageType: 'file',
+    };
+  }
+
+  // Fallback
+  return { text: data.text?.content?.trim() || `[${msgtype}消息]`, messageType: msgtype };
+}
+
+// Send message via sessionWebhook
+async function sendBySession(
+  config: DingTalkConfig,
+  sessionWebhook: string,
+  text: string,
+  options: SendMessageOptions = {}
+): Promise<AxiosResponse> {
+  const token = await getAccessToken(config, options.log);
+  const log = options.log || getLogger();
+
+  // If mediaPath is provided, upload media and send as native media message
+  if (options.mediaPath && options.mediaType) {
+    const mediaId = await uploadMedia(config, options.mediaPath, options.mediaType, log);
+    if (mediaId) {
+      let body: any;
+
+      // Construct message body based on media type
+      if (options.mediaType === 'image') {
+        body = { msgtype: 'image', image: { media_id: mediaId } };
+      } else if (options.mediaType === 'voice') {
+        body = { msgtype: 'voice', voice: { media_id: mediaId } };
+      } else if (options.mediaType === 'video') {
+        body = { msgtype: 'video', video: { media_id: mediaId } };
+      } else if (options.mediaType === 'file') {
+        body = { msgtype: 'file', file: { media_id: mediaId } };
+      }
+
+      if (body) {
+        const result = await axios({
+          url: sessionWebhook,
+          method: 'POST',
+          data: body,
+          headers: { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' },
+        });
+        return result.data;
+      }
+    } else {
+      log?.warn?.('[DingTalk] Media upload failed, falling back to text description');
+    }
+  }
+
+  // Use shared helper function for markdown detection and title extraction
+  const { useMarkdown, title } = detectMarkdownAndExtractTitle(text, options, 'Clawdbot 消息');
+
+  let body: SessionWebhookResponse;
+  if (useMarkdown) {
+    let finalText = text;
+    if (options.atUserId) finalText = `${finalText} @${options.atUserId}`;
+    body = { msgtype: 'markdown', markdown: { title, text: finalText } };
+  } else {
+    body = { msgtype: 'text', text: { content: text } };
+  }
+
+  if (options.atUserId) body.at = { atUserIds: [options.atUserId], isAtAll: false };
+
+  const result = await axios({
+    url: sessionWebhook,
+    method: 'POST',
+    data: body,
+    headers: { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' },
+  });
+  return result.data;
+}
+
+// ============ AI Card API Functions ============
+
+/**
+ * Create and deliver an AI Card using the new DingTalk API (createAndDeliver)
+ * @param config DingTalk configuration
+ * @param conversationId Conversation ID (starts with 'cid' for groups, user ID for DM)
+ * @param data Original message data for context
+ * @param accountId Account ID for multi-account support
+ * @param log Logger instance
+ * @returns AI Card instance or null on failure
+ */
+async function createAICard(
+  config: DingTalkConfig,
+  conversationId: string,
+  data: DingTalkInboundMessage,
+  accountId: string,
+  log?: Logger
+): Promise<AICardInstance | null> {
+  try {
+    const token = await getAccessToken(config, log);
+    // Use crypto.randomUUID() for robust GUID generation instead of Date.now() + random
+    const cardInstanceId = `card_${randomUUID()}`;
+
+    log?.info?.(`[DingTalk][AICard] Creating and delivering card outTrackId=${cardInstanceId}`);
+    log?.debug?.(`[DingTalk][AICard] conversationType=${data.conversationType}, conversationId=${conversationId}`);
+
+    const isGroup = conversationId.startsWith('cid');
+
+    if (!config.cardTemplateId) {
+      throw new Error('DingTalk cardTemplateId is not configured.');
+    }
+
+    // Build the createAndDeliver request body
+    const createAndDeliverBody = {
+      cardTemplateId: config.cardTemplateId,
+      outTrackId: cardInstanceId,
+      cardData: {
+        cardParamMap: {},
+      },
+      callbackType: 'STREAM',
+      imGroupOpenSpaceModel: { supportForward: true },
+      imRobotOpenSpaceModel: { supportForward: true },
+      openSpaceId: isGroup ? `dtv1.card//IM_GROUP.${conversationId}` : `dtv1.card//IM_ROBOT.${conversationId}`,
+      userIdType: 1,
+      imGroupOpenDeliverModel: isGroup ? { robotCode: config.robotCode || config.clientId } : undefined,
+      imRobotOpenDeliverModel: !isGroup ? { spaceType: 'IM_ROBOT' } : undefined,
+    };
+
+    if (isGroup && !config.robotCode) {
+      log?.warn?.(
+        '[DingTalk][AICard] robotCode not configured, using clientId as fallback. ' +
+          'For best compatibility, set robotCode explicitly in config.'
+      );
+    }
+
+    log?.debug?.(
+      `[DingTalk][AICard] POST /v1.0/card/instances/createAndDeliver body=${JSON.stringify(createAndDeliverBody)}`
+    );
+    const resp = await axios.post(`${DINGTALK_API}/v1.0/card/instances/createAndDeliver`, createAndDeliverBody, {
+      headers: { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' },
+    });
+    log?.debug?.(
+      `[DingTalk][AICard] CreateAndDeliver response: status=${resp.status} data=${JSON.stringify(resp.data)}`
+    );
+
+    // Cache the AI card instance with config reference for token refresh
+    const aiCardInstance: AICardInstance = {
+      cardInstanceId,
+      accessToken: token,
+      conversationId,
+      createdAt: Date.now(),
+      lastUpdated: Date.now(),
+      state: AICardStatus.PROCESSING, // Initial state after creation
+      config, // Store config reference for token refresh
+    };
+    aiCardInstances.set(cardInstanceId, aiCardInstance);
+
+    // Add mapping from target to active card ID (accountId:conversationId -> cardInstanceId)
+    const targetKey = `${accountId}:${conversationId}`;
+    activeCardsByTarget.set(targetKey, cardInstanceId);
+    log?.debug?.(`[DingTalk][AICard] Registered active card mapping: ${targetKey} -> ${cardInstanceId}`);
+
+    return aiCardInstance;
+  } catch (err: any) {
+    log?.error?.(`[DingTalk][AICard] Create failed: ${err.message}`);
+    if (err.response) {
+      log?.error?.(
+        `[DingTalk][AICard] Error response: status=${err.response.status} data=${JSON.stringify(err.response.data)}`
+      );
+    }
+    return null;
+  }
+}
+
+/**
+ * Stream update AI Card content using the new DingTalk API
+ * Always use isFull=true to fully replace the Markdown content
+ * @param card AI Card instance
+ * @param content Content to stream
+ * @param finished Whether this is the final update (isFinalize=true)
+ * @param log Logger instance
+ */
+async function streamAICard(
+  card: AICardInstance,
+  content: string,
+  finished: boolean = false,
+  log?: Logger
+): Promise<void> {
+  // Refresh token if it's been more than 1.5 hours since card creation (tokens expire after 2 hours)
+  const tokenAge = Date.now() - card.createdAt;
+  const TOKEN_REFRESH_THRESHOLD = 90 * 60 * 1000; // 1.5 hours in milliseconds
+
+  if (tokenAge > TOKEN_REFRESH_THRESHOLD && card.config) {
+    log?.debug?.('[DingTalk][AICard] Token age exceeds threshold, refreshing...');
+    try {
+      card.accessToken = await getAccessToken(card.config, log);
+      log?.debug?.('[DingTalk][AICard] Token refreshed successfully');
+    } catch (err: any) {
+      log?.warn?.(`[DingTalk][AICard] Failed to refresh token: ${err.message}`);
+      // Continue with old token, let the API call fail if token is invalid
+    }
+  }
+
+  // Call streaming API to update content with full replacement
+  const streamBody: AICardStreamingRequest = {
+    outTrackId: card.cardInstanceId,
+    guid: randomUUID(), // Use crypto.randomUUID() for robust GUID generation
+    key: card.config?.cardTemplateKey || 'content',
+    content: content,
+    isFull: true, // Always full replacement for Markdown content
+    isFinalize: finished, // Set to true on final update to close the streaming channel
+    isError: false,
+  };
+
+  log?.debug?.(
+    `[DingTalk][AICard] PUT /v1.0/card/streaming contentLen=${content.length} isFull=true isFinalize=${finished} guid=${streamBody.guid} payload=${JSON.stringify(streamBody)}`
+  );
+
+  try {
+    const streamResp = await axios.put(`${DINGTALK_API}/v1.0/card/streaming`, streamBody, {
+      headers: { 'x-acs-dingtalk-access-token': card.accessToken, 'Content-Type': 'application/json' },
+    });
+    log?.debug?.(
+      `[DingTalk][AICard] Streaming response: status=${streamResp.status}, data=${JSON.stringify(streamResp.data)}`
+    );
+
+    // Update last updated time and state
+    card.lastUpdated = Date.now();
+    if (finished) {
+      card.state = AICardStatus.FINISHED;
+    } else if (card.state === AICardStatus.PROCESSING) {
+      card.state = AICardStatus.INPUTING;
+    }
+  } catch (err: any) {
+    // Handle 500 unknownError - likely cardTemplateKey mismatch with card template variables
+    if (err.response?.status === 500 && err.response?.data?.code === 'unknownError') {
+      const usedKey = streamBody.key;
+      const cardTemplateId = card.config?.cardTemplateId || '(unknown)';
+      const errorMsg =
+        `⚠️ **[DingTalk] AI Card 串流更新失败 (500 unknownError)**\n\n` +
+        `这通常是因为 \`cardTemplateKey\` (当前值: \`${usedKey}\`) 与钉钉卡片模板 \`${cardTemplateId}\` 中定义的正文变量名不匹配。\n\n` +
+        `**建议操作**：\n` +
+        `1. 前往钉钉开发者后台检查该模板的“变量管理”\n` +
+        `2. 确保配置中的 \`cardTemplateKey\` 与模板中用于显示内容的字段变量名完全一致\n\n` +
+        `*注意：当前及后续消息将自动转为 Markdown 发送，直到问题修复。*\n` +
+        `*参考文档: https://github.com/soimy/openclaw-channel-dingtalk/blob/main/README.md#3-%E5%BB%BA%E7%AB%8B%E5%8D%A1%E7%89%87%E6%A8%A1%E6%9D%BF%E5%8F%AF%E9%80%89`;
+
+      log?.error?.(
+        `[DingTalk][AICard] Streaming failed with 500 unknownError. Key: ${usedKey}, Template: ${cardTemplateId}. ` +
+          `Verify that "cardTemplateKey" matches the content field variable name in your card template.`
+      );
+
+      card.state = AICardStatus.FAILED;
+      card.lastUpdated = Date.now();
+
+      if (card.config) {
+        // Send notification directly to user via Markdown fallback
+        // We don't pass accountId here to ensure it doesn't try to use AI Card recursion
+        try {
+          await sendMessage(card.config, card.conversationId, errorMsg, { log });
+        } catch (sendErr: any) {
+          log?.warn?.(`[DingTalk][AICard] Failed to send error notification to user: ${sendErr.message}`);
+        }
+      }
+
+      throw err;
+    }
+
+    // Handle 401 errors specifically - try to refresh token once
+    if (err.response?.status === 401 && card.config) {
+      log?.warn?.('[DingTalk][AICard] Received 401 error, attempting token refresh and retry...');
+      try {
+        card.accessToken = await getAccessToken(card.config, log);
+        // Retry the streaming request with refreshed token
+        const retryResp = await axios.put(`${DINGTALK_API}/v1.0/card/streaming`, streamBody, {
+          headers: { 'x-acs-dingtalk-access-token': card.accessToken, 'Content-Type': 'application/json' },
+        });
+        log?.debug?.(`[DingTalk][AICard] Retry after token refresh succeeded: status=${retryResp.status}`);
+        // Update state on successful retry
+        card.lastUpdated = Date.now();
+        if (finished) {
+          card.state = AICardStatus.FINISHED;
+        } else if (card.state === AICardStatus.PROCESSING) {
+          card.state = AICardStatus.INPUTING;
+        }
+        return; // Success, exit function
+      } catch (retryErr: any) {
+        log?.error?.(`[DingTalk][AICard] Retry after token refresh failed: ${retryErr.message}`);
+        // Fall through to mark as failed and throw
+      }
+    }
+
+    // Ensure card state reflects the failure to prevent retry loops
+    card.state = AICardStatus.FAILED;
+    card.lastUpdated = Date.now();
+    log?.error?.(
+      `[DingTalk][AICard] Streaming update failed: ${err.message}, resp=${JSON.stringify(err.response?.data)}`
+    );
+    throw err;
+  }
+}
+
+/**
+ * Finalize AI Card: close streaming channel and update to FINISHED state
+ * @param card AI Card instance
+ * @param content Final content
+ * @param log Logger instance
+ */
+async function finishAICard(card: AICardInstance, content: string, log?: Logger): Promise<void> {
+  log?.debug?.(`[DingTalk][AICard] Starting finish, final content length=${content.length}`);
+
+  // Send final content with isFull=true and isFinalize=true to close streaming
+  // No separate state update needed - the streaming API handles everything
+  await streamAICard(card, content, true, log);
+}
+
+// ============ End of New AI Card API Functions ============
+
+// Send message with automatic mode selection (card/markdown)
+// Card mode: if an active AI Card exists for the target, stream updates; otherwise fall back to markdown.
+async function sendMessage(
+  config: DingTalkConfig,
+  conversationId: string,
+  text: string,
+  options: SendMessageOptions & { sessionWebhook?: string; accountId?: string } = {}
+): Promise<{ ok: boolean; error?: string; data?: AxiosResponse }> {
+  try {
+    const messageType = config.messageType || 'markdown';
+    const log = options.log || getLogger();
+
+    if (messageType === 'card' && options.accountId) {
+      const targetKey = `${options.accountId}:${conversationId}`;
+      const activeCardId = activeCardsByTarget.get(targetKey);
+      if (activeCardId) {
+        const activeCard = aiCardInstances.get(activeCardId);
+        if (activeCard && !isCardInTerminalState(activeCard.state)) {
+          try {
+            await streamAICard(activeCard, text, false, log);
+            return { ok: true };
+          } catch (err: any) {
+            log?.warn?.(`[DingTalk] AI Card streaming failed, fallback to markdown: ${err.message}`);
+            activeCard.state = AICardStatus.FAILED;
+            activeCard.lastUpdated = Date.now();
+          }
+        } else {
+          activeCardsByTarget.delete(targetKey);
+        }
+      }
+    }
+
+    // Fallback to markdown mode
+    if (options.sessionWebhook) {
+      await sendBySession(config, options.sessionWebhook, text, options);
+      return { ok: true };
+    }
+
+    const result = await sendProactiveTextOrMarkdown(config, conversationId, text, options);
+    return { ok: true, data: result };
+  } catch (err: any) {
+    options.log?.error?.(`[DingTalk] Send message failed: ${err.message}`);
+    return { ok: false, error: err.message };
+  }
+}
+
+// Message handler
+async function handleDingTalkMessage(params: HandleDingTalkMessageParams): Promise<void> {
+  const { cfg, accountId, data, sessionWebhook, log, dingtalkConfig } = params;
+  const rt = getDingTalkRuntime();
+
+  // Save logger reference globally for use by other methods
+  currentLogger = log;
+
+  log?.debug?.('[DingTalk] Full Inbound Data:', JSON.stringify(maskSensitiveData(data)));
+
+  // 0. 清理过期的卡片缓存
+  cleanupCardCache();
+
+  // 1. 过滤机器人自身消息
+  if (data.senderId === data.chatbotUserId || data.senderStaffId === data.chatbotUserId) {
+    log?.debug?.('[DingTalk] Ignoring robot self-message');
+    return;
+  }
+
+  const content = extractMessageContent(data);
+  if (!content.text) return;
+
+  const isDirect = data.conversationType === '1';
+  const senderId = data.senderStaffId || data.senderId;
+  const senderName = data.senderNick || 'Unknown';
+  const groupId = data.conversationId;
+  const groupName = data.conversationTitle || 'Group';
+
+  // Register original peer IDs to preserve case-sensitive conversationId (base64)
+  if (groupId) registerPeerId(groupId);
+  if (senderId) registerPeerId(senderId);
+
+  // 2. Check authorization for direct messages based on dmPolicy
+  let commandAuthorized = true;
+  if (isDirect) {
+    const dmPolicy = dingtalkConfig.dmPolicy || 'open';
+    const allowFrom = dingtalkConfig.allowFrom || [];
+
+    if (dmPolicy === 'allowlist') {
+      const normalizedAllowFrom = normalizeAllowFrom(allowFrom);
+      const isAllowed = isSenderAllowed({ allow: normalizedAllowFrom, senderId });
+
+      if (!isAllowed) {
+        log?.debug?.(`[DingTalk] DM blocked: senderId=${senderId} not in allowlist (dmPolicy=allowlist)`);
+
+        // Notify user with their sender ID so they can request access
+        try {
+          await sendBySession(
+            dingtalkConfig,
+            sessionWebhook,
+            `⛔ 访问受限\n\n您的用户ID：\`${senderId}\`\n\n请联系管理员将此ID添加到允许列表中。`,
+            { log }
+          );
+        } catch (err: any) {
+          log?.debug?.(`[DingTalk] Failed to send access denied message: ${err.message}`);
+        }
+
+        return;
+      }
+
+      log?.debug?.(`[DingTalk] DM authorized: senderId=${senderId} in allowlist`);
+    } else if (dmPolicy === 'pairing') {
+      // For pairing mode, SDK will handle the authorization
+      // Set commandAuthorized to true to let SDK check pairing status
+      commandAuthorized = true;
+    } else {
+      // 'open' policy - allow all
+      commandAuthorized = true;
+    }
+  } else {
+    // 群组通道授权
+    const groupPolicy = dingtalkConfig.groupPolicy || 'open';
+    const allowFrom = dingtalkConfig.allowFrom || [];
+
+    if (groupPolicy === 'allowlist') {
+      const normalizedAllowFrom = normalizeAllowFrom(allowFrom);
+      const isAllowed = isSenderGroupAllowed({ allow: normalizedAllowFrom, groupId });
+
+      if (!isAllowed) {
+        log?.debug?.(
+          `[DingTalk] Group blocked: conversationId=${groupId} senderId=${senderId} not in allowlist (groupPolicy=allowlist)`
+        );
+
+        try {
+          await sendBySession(
+            dingtalkConfig,
+            sessionWebhook,
+            `⛔ 访问受限\n\n您的群聊ID：\`${groupId}\`\n\n请联系管理员将此ID添加到允许列表中。`,
+            { log, atUserId: senderId }
+          );
+        } catch (err: any) {
+          log?.debug?.(`[DingTalk] Failed to send group access denied message: ${err.message}`);
+        }
+
+        return;
+      }
+
+      log?.debug?.(`[DingTalk] Group authorized: conversationId=${groupId} senderId=${senderId} in allowlist`);
+    }
+  }
+
+  const route = rt.channel.routing.resolveAgentRoute({
+    cfg,
+    channel: 'dingtalk',
+    accountId,
+    // agent权限和openclaw保持一致
+    peer: { kind: isDirect ? 'direct' : 'group', id: isDirect ? senderId : groupId },
+  });
+
+  const storePath = rt.channel.session.resolveStorePath(cfg.session?.store, { agentId: route.agentId });
+  const workspacePath = resolveAgentWorkspaceDir(cfg, route.agentId);
+
+  // Download media to agent workspace (must be after route is resolved for correct workspace)
+  let mediaPath: string | undefined;
+  let mediaType: string | undefined;
+  if (content.mediaPath && dingtalkConfig.robotCode) {
+    const media = await downloadMedia(dingtalkConfig, content.mediaPath, workspacePath, log);
+    if (media) {
+      mediaPath = media.path;
+      mediaType = media.mimeType;
+    }
+  }
+  const envelopeOptions = rt.channel.reply.resolveEnvelopeFormatOptions(cfg);
+  const previousTimestamp = rt.channel.session.readSessionUpdatedAt({ storePath, sessionKey: route.sessionKey });
+
+  // Group-specific: resolve config, track members, format member list
+  const groupConfig = !isDirect ? resolveGroupConfig(dingtalkConfig, groupId) : undefined;
+  // GroupSystemPrompt is injected into the system prompt on every turn (unlike
+  // group intro which only fires on the first turn). Embed DingTalk IDs here so
+  // the AI always has access to conversationId.
+  const groupSystemPrompt = !isDirect
+    ? [`DingTalk group context: conversationId=${groupId}`, groupConfig?.systemPrompt?.trim()]
+        .filter(Boolean)
+        .join('\n')
+    : undefined;
+
+  if (!isDirect) {
+    noteGroupMember(storePath, groupId, senderId, senderName);
+  }
+  const groupMembers = !isDirect ? formatGroupMembers(storePath, groupId) : undefined;
+
+  const fromLabel = isDirect ? `${senderName} (${senderId})` : `${groupName} - ${senderName}`;
+  const body = rt.channel.reply.formatInboundEnvelope({
+    channel: 'DingTalk',
+    from: fromLabel,
+    timestamp: data.createAt,
+    body: content.text,
+    chatType: isDirect ? 'direct' : 'group',
+    sender: { name: senderName, id: senderId },
+    previousTimestamp,
+    envelope: envelopeOptions,
+  });
+
+  const to = isDirect ? senderId : groupId;
+  const ctx = rt.channel.reply.finalizeInboundContext({
+    Body: body,
+    RawBody: content.text,
+    CommandBody: content.text,
+    From: to,
+    To: to,
+    SessionKey: route.sessionKey,
+    AccountId: accountId,
+    ChatType: isDirect ? 'direct' : 'group',
+    ConversationLabel: fromLabel,
+    GroupSubject: isDirect ? undefined : groupName,
+    SenderName: senderName,
+    SenderId: senderId,
+    Provider: 'dingtalk',
+    Surface: 'dingtalk',
+    MessageSid: data.msgId,
+    Timestamp: data.createAt,
+    MediaPath: mediaPath,
+    MediaType: mediaType,
+    MediaUrl: mediaPath,
+    GroupMembers: groupMembers,
+    GroupSystemPrompt: groupSystemPrompt,
+    GroupChannel: isDirect ? undefined : route.sessionKey,
+    CommandAuthorized: commandAuthorized,
+    OriginatingChannel: 'dingtalk',
+    OriginatingTo: to,
+  });
+
+  await rt.channel.session.recordInboundSession({
+    storePath,
+    sessionKey: ctx.SessionKey || route.sessionKey,
+    ctx,
+    updateLastRoute: { sessionKey: route.mainSessionKey, channel: 'dingtalk', to, accountId },
+    onRecordError: (err: unknown) => {
+      log?.error?.(`[DingTalk] Failed to record inbound session: ${String(err)}`);
+    },
+  });
+
+  log?.info?.(`[DingTalk] Inbound: from=${senderName} text="${content.text.slice(0, 50)}..."`);
+
+  // Determine if we are in card mode, if so, create or reuse card instance first
+  const useCardMode = dingtalkConfig.messageType === 'card';
+  let currentAICard: AICardInstance | undefined;
+  let lastCardContent = '';
+
+  if (useCardMode) {
+    // Try to reuse an existing active AI card for this target, if available
+    const targetKey = `${accountId}:${to}`;
+    const existingCardId = activeCardsByTarget.get(targetKey);
+    const existingCard = existingCardId ? aiCardInstances.get(existingCardId) : undefined;
+
+    // Only reuse cards that are not in terminal states
+    if (existingCard && !isCardInTerminalState(existingCard.state)) {
+      currentAICard = existingCard;
+      log?.debug?.('[DingTalk] Reusing existing active AI card for this conversation.');
+    } else {
+      // Create a new AI card
+      try {
+        const aiCard = await createAICard(dingtalkConfig, to, data, accountId, log);
+        if (aiCard) {
+          currentAICard = aiCard;
+        } else {
+          log?.warn?.('[DingTalk] Failed to create AI card (returned null), fallback to text/markdown.');
+        }
+      } catch (err: any) {
+        log?.warn?.(`[DingTalk] Failed to create AI card: ${err.message}, fallback to text/markdown.`);
+      }
+    }
+  }
+
+  // Feedback: Thinking...
+  if (dingtalkConfig.showThinking !== false) {
+    try {
+      const thinkingText = '🤔 思考中，请稍候...';
+      // AI card already has thinking state visually, so we only send thinking message for non-card modes
+      if (useCardMode && currentAICard) {
+        log?.debug?.('[DingTalk] AI Card in thinking state, skipping thinking message send.');
+      } else {
+        lastCardContent = thinkingText;
+        await sendMessage(dingtalkConfig, to, thinkingText, {
+          sessionWebhook,
+          atUserId: !isDirect ? senderId : null,
+          log,
+          accountId,
+        });
+      }
+    } catch (err: any) {
+      log?.debug?.(`[DingTalk] Thinking message failed: ${err.message}`);
+    }
+  }
+
+  const { queuedFinal } = await rt.channel.reply.dispatchReplyWithBufferedBlockDispatcher({
+    ctx,
+    cfg,
+    dispatcherOptions: {
+      responsePrefix: '',
+      deliver: async (payload: any) => {
+        try {
+          const textToSend = payload.markdown || payload.text;
+          if (!textToSend) return;
+
+          lastCardContent = textToSend;
+          await sendMessage(dingtalkConfig, to, textToSend, {
+            sessionWebhook,
+            atUserId: !isDirect ? senderId : null,
+            log,
+            accountId,
+          });
+        } catch (err: any) {
+          log?.error?.(`[DingTalk] Reply failed: ${err.message}`);
+          throw err;
+        }
+      },
+    },
+  });
+
+  // Finalize AI card
+  if (useCardMode && currentAICard) {
+    try {
+      // Helper function to check if a value is a non-empty string
+      const isNonEmptyString = (value: any): boolean => typeof value === 'string' && value.trim().length > 0;
+
+      // Validate that we have actual content before finalization
+      const hasLastCardContent = isNonEmptyString(lastCardContent);
+      const hasQueuedFinalString = isNonEmptyString(queuedFinal);
+
+      if (hasLastCardContent || hasQueuedFinalString) {
+        const finalContent =
+          hasLastCardContent && typeof lastCardContent === 'string'
+            ? lastCardContent
+            : typeof queuedFinal === 'string'
+              ? queuedFinal
+              : '';
+        await finishAICard(currentAICard, finalContent, log);
+      } else {
+        // No textual content was produced; skip finalization with empty content
+        log?.debug?.('[DingTalk] Skipping AI Card finalization because no textual content was produced.');
+        // Still mark the card as finished to allow cleanup
+        currentAICard.state = AICardStatus.FINISHED;
+        currentAICard.lastUpdated = Date.now();
+      }
+    } catch (err: any) {
+      log?.debug?.(`[DingTalk] AI Card finalization failed: ${err.message}`);
+      // Ensure the AI card transitions to a terminal error state
+      try {
+        if (currentAICard.state !== AICardStatus.FINISHED) {
+          currentAICard.state = AICardStatus.FAILED;
+          currentAICard.lastUpdated = Date.now();
+        }
+      } catch (stateErr: any) {
+        // Log state update failure at debug level to aid production debugging
+        log?.debug?.(`[DingTalk] Failed to update card state to FAILED: ${stateErr.message}`);
+      }
+    }
+  }
+  // Note: Media cleanup is handled by openclaw's media storage mechanism
+  // Files saved via rt.channel.media.saveMediaBuffer are managed automatically
+}
+
+// DingTalk Channel Definition
+export const dingtalkPlugin: DingTalkChannelPlugin = {
+  id: 'dingtalk',
+  meta: {
+    id: 'dingtalk',
+    label: 'DingTalk',
+    selectionLabel: 'DingTalk (钉钉)',
+    docsPath: '/channels/dingtalk',
+    blurb: '钉钉企业内部机器人，使用 Stream 模式，无需公网 IP。',
+    aliases: ['dd', 'ding'],
+  },
+  configSchema: buildChannelConfigSchema(DingTalkConfigSchema),
+  onboarding: dingtalkOnboardingAdapter,
+  capabilities: {
+    chatTypes: ['direct', 'group'] as Array<'direct' | 'group'>,
+    reactions: false,
+    threads: false,
+    media: true,
+    nativeCommands: false,
+    blockStreaming: false,
+  },
+  reload: { configPrefixes: ['channels.dingtalk'] },
+  config: {
+    listAccountIds: (cfg: OpenClawConfig): string[] => {
+      const config = getConfig(cfg);
+      return config.accounts && Object.keys(config.accounts).length > 0
+        ? Object.keys(config.accounts)
+        : isConfigured(cfg)
+          ? ['default']
+          : [];
+    },
+    resolveAccount: (cfg: OpenClawConfig, accountId?: string | null) => {
+      const config = getConfig(cfg);
+      const id = accountId || 'default';
+      const account = config.accounts?.[id];
+      const resolvedConfig = account || config;
+      const configured = Boolean(resolvedConfig.clientId && resolvedConfig.clientSecret);
+      return {
+        accountId: id,
+        config: resolvedConfig,
+        enabled: resolvedConfig.enabled !== false,
+        configured,
+        name: resolvedConfig.name || null,
+      };
+    },
+    defaultAccountId: (): string => 'default',
+    isConfigured: (account: ResolvedAccount): boolean => Boolean(account.config?.clientId && account.config?.clientSecret),
+    describeAccount: (account: ResolvedAccount) => ({
+      accountId: account.accountId,
+      name: account.config?.name || 'DingTalk',
+      enabled: account.enabled,
+      configured: Boolean(account.config?.clientId),
+    }),
+  },
+  security: {
+    resolveDmPolicy: ({ account }: any) => ({
+      policy: account.config?.dmPolicy || 'open',
+      allowFrom: account.config?.allowFrom || [],
+      policyPath: 'channels.dingtalk.dmPolicy',
+      allowFromPath: 'channels.dingtalk.allowFrom',
+      approveHint: '使用 /allow dingtalk:<userId> 批准用户',
+      normalizeEntry: (raw: string) => raw.replace(/^(dingtalk|dd|ding):/i, ''),
+    }),
+  },
+  groups: {
+    resolveRequireMention: ({ cfg }: any): boolean => getConfig(cfg).groupPolicy !== 'open',
+    resolveGroupIntroHint: ({ groupId, groupChannel }: any): string | undefined => {
+      const parts = [`conversationId=${groupId}`];
+      if (groupChannel) parts.push(`sessionKey=${groupChannel}`);
+      return `DingTalk IDs: ${parts.join(', ')}.`;
+    },
+  },
+  messaging: {
+    normalizeTarget: (raw: string) => (raw ? raw.replace(/^(dingtalk|dd|ding):/i, '') : undefined),
+    targetResolver: { looksLikeId: (id: string): boolean => /^[\w+\-/=]+$/.test(id), hint: '<conversationId>' },
+  },
+  outbound: {
+    deliveryMode: 'direct' as const,
+    resolveTarget: ({ to }: any) => {
+      const trimmed = to?.trim();
+      if (!trimmed) {
+        return {
+          ok: false as const,
+          error: new Error('DingTalk message requires --to <conversationId>'),
+        };
+      }
+      // Strip group: or user: prefix and resolve original case-sensitive conversationId
+      const { targetId } = stripTargetPrefix(trimmed);
+      const resolved = resolveOriginalPeerId(targetId);
+      return { ok: true as const, to: resolved };
+    },
+    sendText: async ({ cfg, to, text, accountId, log }: any) => {
+      const config = getConfig(cfg, accountId);
+      try {
+        const result = await sendMessage(config, to, text, { log, accountId });
+        getLogger()?.debug?.(`[DingTalk] sendText: "${text}" result: ${JSON.stringify(result)}`);
+        if (result.ok) {
+          const data = result.data as any;
+          const messageId = String(data?.processQueryKey || data?.messageId || randomUUID());
+          return {
+            channel: 'dingtalk',
+            messageId,
+            meta: result.data ? { data: result.data as unknown as Record<string, unknown> } : undefined,
+          };
+        }
+        throw new Error(typeof result.error === 'string' ? result.error : JSON.stringify(result.error));
+      } catch (err: any) {
+        throw new Error(typeof err?.response?.data === 'string' ? err.response.data : err?.message || 'sendText failed');
+      }
+    },
+    sendMedia: async ({
+      cfg,
+      to,
+      mediaPath,
+      filePath,
+      mediaUrl,
+      mediaType: providedMediaType,
+      accountId,
+      log,
+    }: any) => {
+      const config = getConfig(cfg, accountId);
+      if (!config.clientId) throw new Error('DingTalk not configured');
+
+      // Support mediaPath, filePath, and mediaUrl parameter names
+      const actualMediaPath = mediaPath || filePath || mediaUrl;
+
+      getLogger()?.debug?.(
+        `[DingTalk] sendMedia called: to=${to}, mediaPath=${mediaPath}, filePath=${filePath}, mediaUrl=${mediaUrl}, actualMediaPath=${actualMediaPath}`
+      );
+
+      if (!actualMediaPath) {
+        throw new Error(
+          `mediaPath, filePath, or mediaUrl is required. Received: ${JSON.stringify({
+            to,
+            mediaPath,
+            filePath,
+            mediaUrl,
+          })}`
+        );
+      }
+
+      try {
+        // Detect media type from file extension if not provided
+        const mediaType = providedMediaType || detectMediaTypeFromExtension(actualMediaPath);
+
+        // Send as native media via proactive API
+        const result = await sendProactiveMedia(config, to, actualMediaPath, mediaType, { log, accountId });
+        getLogger()?.debug?.(
+          `[DingTalk] sendMedia: ${mediaType} file=${actualMediaPath} result: ${JSON.stringify(result)}`
+        );
+
+        if (result.ok) {
+          // Extract messageId from DingTalk response for CLI display
+          const data = result.data;
+          const messageId = String(result.messageId || data?.processQueryKey || data?.messageId || randomUUID());
+          return {
+            channel: 'dingtalk',
+            messageId,
+            meta: result.data ? { data: result.data as unknown as Record<string, unknown> } : undefined,
+          };
+        }
+        throw new Error(typeof result.error === 'string' ? result.error : JSON.stringify(result.error));
+      } catch (err: any) {
+        throw new Error(typeof err?.response?.data === 'string' ? err.response.data : err?.message || 'sendMedia failed');
+      }
+    },
+  },
+  gateway: {
+    startAccount: async (ctx: GatewayStartContext): Promise<GatewayStopResult> => {
+      const { account, cfg, abortSignal } = ctx;
+      const config = account.config;
+      if (!config.clientId || !config.clientSecret) {
+        throw new Error('DingTalk clientId and clientSecret are required');
+      }
+
+      ctx.log?.info?.(`[${account.accountId}] Initializing DingTalk Stream client...`);
+
+      // Cleanup orphaned temp files from previous sessions
+      cleanupOrphanedTempFiles(ctx.log);
+
+      // Create DWClient with autoReconnect disabled (we'll manage reconnection ourselves)
+      const client = new DWClient({
+        clientId: config.clientId,
+        clientSecret: config.clientSecret,
+        debug: config.debug || false,
+        keepAlive: true,
+      });
+
+      // Disable DWClient's built-in autoReconnect to use our robust ConnectionManager
+      // Access private config to override autoReconnect
+      (client as any).config.autoReconnect = false;
+
+      // Register message callback listener
+      client.registerCallbackListener(TOPIC_ROBOT, async (res: any) => {
+        const messageId = res.headers?.messageId;
+        try {
+          if (messageId) {
+            client.socketCallBackResponse(messageId, { success: true });
+          }
+          const data = JSON.parse(res.data) as DingTalkInboundMessage;
+
+          // Message deduplication: use bot-scoped key (robotKey:msgId) to prevent cross-bot conflicts
+          // robotKey priority: robotCode (DingTalk's bot identifier) > clientId (app key) > accountId (local ID)
+          // This ensures consistent keys per bot instance (config values remain stable during runtime)
+          const robotKey = config.robotCode || config.clientId || account.accountId;
+          const msgId = data.msgId || messageId;
+
+          // Skip dedup if we don't have a message ID (extremely rare edge case)
+          if (!msgId) {
+            ctx.log?.warn?.(`[${account.accountId}] No message ID available for deduplication`);
+          } else {
+            const dedupKey = `${robotKey}:${msgId}`;
+            if (isMessageProcessed(dedupKey)) {
+              ctx.log?.debug?.(`[${account.accountId}] Skipping duplicate message: ${dedupKey}`);
+              return;
+            }
+            markMessageProcessed(dedupKey);
+          }
+
+          await handleDingTalkMessage({
+            cfg,
+            accountId: account.accountId,
+            data,
+            sessionWebhook: data.sessionWebhook,
+            log: ctx.log,
+            dingtalkConfig: config,
+          });
+        } catch (error: any) {
+          ctx.log?.error?.(`[${account.accountId}] Error processing message: ${error.message}`);
+        }
+      });
+
+      // Track stopped state to prevent duplicate stop operations
+      // The 'stopped' flag guards against multiple termination paths (abort signal, explicit stop)
+      // from executing concurrently and ensures each lifecycle transition updates snapshot only once
+      let stopped = false;
+
+      // Create connection manager configuration
+      const connectionConfig: ConnectionManagerConfig = {
+        maxAttempts: config.maxConnectionAttempts ?? 10,
+        initialDelay: config.initialReconnectDelay ?? 1000,
+        maxDelay: config.maxReconnectDelay ?? 60000,
+        jitter: config.reconnectJitter ?? 0.3,
+        onStateChange: (state: ConnectionState, error?: string) => {
+          if (stopped) return;
+          ctx.log?.debug?.(`[${account.accountId}] Connection state changed to: ${state}${error ? ` (${error})` : ''}`);
+          if (state === ConnectionState.CONNECTED) {
+            ctx.setStatus({
+              ...ctx.getStatus(),
+              running: true,
+              lastStartAt: getCurrentTimestamp(),
+              lastError: null,
+            });
+          } else if (state === ConnectionState.FAILED || state === ConnectionState.DISCONNECTED) {
+            ctx.setStatus({
+              ...ctx.getStatus(),
+              running: false,
+              lastError: error || `Connection ${state.toLowerCase()}`,
+            });
+          }
+        },
+      };
+
+      ctx.log?.debug?.(
+        `[${account.accountId}] Connection config: maxAttempts=${connectionConfig.maxAttempts}, ` +
+          `initialDelay=${connectionConfig.initialDelay}ms, maxDelay=${connectionConfig.maxDelay}ms, ` +
+          `jitter=${connectionConfig.jitter}`
+      );
+
+      // Create connection manager
+      const connectionManager = new ConnectionManager(client, account.accountId, connectionConfig, ctx.log);
+
+      // Setup abort signal handler BEFORE connecting
+      // This allows the abort signal to cancel in-flight connection attempts
+      if (abortSignal) {
+        // Check if already aborted before we even start
+        if (abortSignal.aborted) {
+          ctx.log?.warn?.(`[${account.accountId}] Abort signal already active, skipping connection`);
+
+          // Update snapshot: channel aborted before start
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: false,
+            lastStopAt: getCurrentTimestamp(),
+            lastError: 'Connection aborted before start',
+          });
+
+          throw new Error('Connection aborted before start');
+        }
+
+        abortSignal.addEventListener('abort', () => {
+          if (stopped) return;
+          stopped = true;
+          ctx.log?.info?.(`[${account.accountId}] Abort signal received, stopping DingTalk Stream client...`);
+          connectionManager.stop();
+
+          // Update snapshot: channel stopped by abort signal
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: false,
+            lastStopAt: getCurrentTimestamp(),
+          });
+        });
+      }
+
+      // Connect with robust retry logic
+      try {
+        await connectionManager.connect();
+
+        // Only mark as running if we weren't stopped and the connection is actually established
+        if (!stopped && connectionManager.isConnected()) {
+          // Update snapshot: connection successful, channel is now running
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: true,
+            lastStartAt: getCurrentTimestamp(),
+            lastError: null,
+          });
+          ctx.log?.info?.(`[${account.accountId}] DingTalk Stream client connected successfully`);
+        } else {
+          // Startup was cancelled or connection is not established; do not overwrite stopped snapshot.
+          ctx.log?.info?.(
+            `[${account.accountId}] DingTalk Stream client connect() completed but channel is ` +
+              `not running (stopped=${stopped}, connected=${connectionManager.isConnected()})`
+          );
+        }
+      } catch (err: any) {
+        ctx.log?.error?.(`[${account.accountId}] Failed to establish connection: ${err.message}`);
+
+        // Update snapshot: connection failed
+        ctx.setStatus({
+          ...ctx.getStatus(),
+          running: false,
+          lastError: err.message || 'Connection failed',
+        });
+        throw err;
+      }
+
+      // Return stop handler
+      return {
+        stop: () => {
+          if (stopped) return;
+          stopped = true;
+          ctx.log?.info?.(`[${account.accountId}] Stopping DingTalk Stream client...`);
+          connectionManager.stop();
+
+          // Update snapshot: channel stopped
+          ctx.setStatus({
+            ...ctx.getStatus(),
+            running: false,
+            lastStopAt: getCurrentTimestamp(),
+          });
+
+          ctx.log?.info?.(`[${account.accountId}] DingTalk Stream client stopped`);
+        },
+      };
+    },
+  },
+  status: {
+    defaultRuntime: { accountId: 'default', running: false, lastStartAt: null, lastStopAt: null, lastError: null },
+    collectStatusIssues: (accounts: any[]) => {
+      return accounts.flatMap((account) => {
+        if (!account.configured) {
+          return [
+            {
+              channel: 'dingtalk',
+              accountId: account.accountId,
+              kind: 'config' as const,
+              message: 'Account not configured (missing clientId or clientSecret)',
+            },
+          ];
+        }
+        return [];
+      });
+    },
+    buildChannelSummary: ({ snapshot }: any) => ({
+      configured: snapshot?.configured ?? false,
+      running: snapshot?.running ?? false,
+      lastStartAt: snapshot?.lastStartAt ?? null,
+      lastStopAt: snapshot?.lastStopAt ?? null,
+      lastError: snapshot?.lastError ?? null,
+    }),
+    probeAccount: async ({ account, timeoutMs }: any) => {
+      if (!account.configured || !account.config?.clientId || !account.config?.clientSecret) {
+        return { ok: false, error: 'Not configured' };
+      }
+      try {
+        const controller = new AbortController();
+        const timeoutId = timeoutMs ? setTimeout(() => controller.abort(), timeoutMs) : undefined;
+        try {
+          await getAccessToken(account.config);
+          return { ok: true, details: { clientId: account.config.clientId } };
+        } finally {
+          if (timeoutId) clearTimeout(timeoutId);
+        }
+      } catch (error: any) {
+        return { ok: false, error: error.message };
+      }
+    },
+    buildAccountSnapshot: ({ account, runtime, snapshot, probe }: any) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      clientId: account.config?.clientId ?? null,
+      running: runtime?.running ?? snapshot?.running ?? false,
+      lastStartAt: runtime?.lastStartAt ?? snapshot?.lastStartAt ?? null,
+      lastStopAt: runtime?.lastStopAt ?? snapshot?.lastStopAt ?? null,
+      lastError: runtime?.lastError ?? snapshot?.lastError ?? null,
+      probe,
+    }),
+  },
+};
+
+/**
+ * Public low-level API exports for the DingTalk channel plugin.
+ *
+ * - {@link sendBySession} sends a message to DingTalk using a session/webhook
+ *   (e.g. replies within an existing conversation).
+ * - {@link createAICard} creates and delivers an AI Card using the DingTalk API
+ *   (returns AICardInstance for streaming updates). Automatically registers the card
+ *   in activeCardsByTarget mapping (accountId:conversationId -> cardInstanceId).
+ * - {@link streamAICard} streams content updates to an AI Card
+ *   (for real-time streaming message updates).
+ * - {@link finishAICard} finalizes an AI Card and sets state to FINISHED
+ *   (closes streaming channel and updates card state).
+ * - {@link sendMessage} sends a message with automatic mode selection
+ *   (text/markdown/card based on config).
+ * - {@link uploadMedia} uploads a local media file to DingTalk media server
+ *   and returns the media_id for use in messages.
+ * - {@link getAccessToken} retrieves (and caches) the DingTalk access token
+ *   for the configured application/runtime.
+ * - {@link getLogger} retrieves the current global logger instance
+ *   (set by handleDingTalkMessage during inbound message processing).
+ *
+ * These exports are intended to be used by external integrations that need
+ * direct programmatic access to DingTalk messaging and authentication.
+ */
+export {
+  sendBySession,
+  createAICard,
+  streamAICard,
+  finishAICard,
+  sendMessage,
+  uploadMedia,
+  sendProactiveMedia,
+  getAccessToken,
+  getLogger,
+};
+export { detectMediaTypeFromExtension } from './media-utils';