@wu529778790/open-im 1.5.1 → 1.5.2-beta.0

package/README.md

@@ -185,18 +185,10 @@ Claude 默认使用 Agent SDK，不依赖本地 `claude` 可执行文件；通
 说明：钉钉当前采用“Stream Mode 收消息 + OpenAPI 发送消息”的混合模式。
 
 - 会话内普通文本回复默认走 `sessionWebhook`
-- 如果配置了 `cardTemplateId` / `DINGTALK_CARD_TEMPLATE_ID`，AI 回复会升级为单条 `ai_card` 流式更新（`prepare / update / finish`）
+- 若配置了 `cardTemplateId`，会尝试 AI 助理 `prepare/update/finish` 流式卡片；失败则 fallback 为普通文本（自定义机器人/普通群场景下互动卡片 API 报 param.error，暂不支持单条流式更新）
 - 启动/关闭通知会发给最近一次已互动的钉钉会话；如果服务冷启动后还没有任何钉钉会话互动过，则没有可用目标可发
 
-钉钉 AI 卡片模板需至少兼容以下字段，建议模板按这些 key 取值：
-
-- `title`
-- `content`
-- `note`
-- `toolName`
-- `status`
-- `flowStatus`
-- `displayText`
+钉钉 AI 卡片模板：已适配官方「搜索结果卡片」模板，使用变量 `lastMessage`、`content`、`resources`、`users`、`flowStatus`。若使用该模板，无需修改模板即可实现流式更新。
 
 ## IM 内命令
 
@@ -233,7 +225,7 @@ Claude 默认使用 Agent SDK，不依赖本地 `claude` 可执行文件；通
 
 **钉钉无法回复**：确认应用已启用机器人 Stream Mode，并检查 `DINGTALK_CLIENT_ID`、`DINGTALK_CLIENT_SECRET` 或 `platforms.dingtalk` 配置是否正确。
 
-**钉钉没有流式更新**：如果未配置 `DINGTALK_CARD_TEMPLATE_ID`（或 `platforms.dingtalk.cardTemplateId`），会自动退回普通文本回复；配置 AI 卡片模板后才会启用单条流式更新。
+**钉钉没有流式更新**：prepare 失败时 fallback 为普通文本回复。自定义机器人/普通群场景下，AI 助理和互动卡片 API 均不可用，仅支持单条文本回复。
 
 **Cursor 报 `Authentication required`**：先执行 `agent login`，或在 `env` 中设置 `CURSOR_API_KEY`。
 

package/dist/dingtalk/client.d.ts

@@ -1,6 +1,13 @@
 import { type DWClientDownStream } from 'dingtalk-stream';
 import type { Config } from '../config.js';
 import type { DingTalkActiveTarget } from '../shared/active-chats.js';
+export interface DingTalkStreamingTarget {
+    chatId: string;
+    conversationType?: string;
+    senderStaffId?: string;
+    senderId?: string;
+    robotCode?: string;
+}
 export declare function registerSessionWebhook(chatId: string, sessionWebhook: string): void;
 export declare function sendText(chatId: string, content: string): Promise<unknown>;
 export declare function sendMarkdown(chatId: string, title: string, text: string): Promise<unknown>;
@@ -8,6 +15,14 @@ export declare function ackMessage(messageId: string, result?: unknown): void;
 export declare function initDingTalk(cfg: Config, eventHandler: (data: DWClientDownStream) => Promise<void>): Promise<void>;
 export declare function stopDingTalk(): void;
 export declare function sendProactiveText(target: string | DingTalkActiveTarget, content: string): Promise<void>;
-export declare function prepareStreamingCard(chatId: string, templateId: string, cardData: Record<string, unknown>): Promise<string>;
+export declare function prepareStreamingCard(target: string | DingTalkStreamingTarget, templateId: string, cardData: Record<string, unknown>): Promise<string>;
 export declare function updateStreamingCard(conversationToken: string, templateId: string, cardData: Record<string, unknown>): Promise<void>;
 export declare function finishStreamingCard(conversationToken: string): Promise<void>;
+/** 创建并投放卡片（卡片平台 API，支持普通群流式更新） */
+export declare function createAndDeliverCard(target: DingTalkStreamingTarget, templateId: string, outTrackId: string, cardData: Record<string, unknown>): Promise<void>;
+/** 更新卡片实例（用于流式更新） */
+export declare function updateCardInstance(outTrackId: string, cardData: Record<string, unknown>): Promise<void>;
+/** 互动卡片普通版：发送（用于 prepare 失败时的 fallback 流式） */
+export declare function sendRobotInteractiveCard(target: DingTalkStreamingTarget, cardBizId: string, cardData: Record<string, unknown>): Promise<void>;
+/** 互动卡片普通版：更新（单条消息流式更新） */
+export declare function updateRobotInteractiveCard(cardBizId: string, cardData: Record<string, unknown>): Promise<void>;

package/dist/dingtalk/client.js

@@ -2,10 +2,12 @@ import { DWClient, TOPIC_ROBOT } from 'dingtalk-stream';
 import { createLogger } from '../logger.js';
 const log = createLogger('DingTalk');
 const DINGTALK_OPENAPI_BASE = 'https://api.dingtalk.com';
+const DINGTALK_OAPI_BASE = 'https://oapi.dingtalk.com';
 const TEXT_MSG_KEY = 'sampleText';
 let client = null;
 let messageHandler = null;
 const sessionWebhookByChat = new Map();
+const unionIdByUserId = new Map();
 function getClient() {
     if (!client) {
         throw new Error('DingTalk client not initialized');
@@ -115,9 +117,72 @@ async function callOpenApi(path, body) {
                 : text;
     throw new Error(`DingTalk OpenAPI business error: ${String(errorCode)} ${errorMessage}`);
 }
+async function callOapi(path, body) {
+    const accessToken = await getClient().getAccessToken();
+    const res = await fetch(`${DINGTALK_OAPI_BASE}${path}?access_token=${encodeURIComponent(String(accessToken))}`, {
+        method: 'POST',
+        headers: {
+            'content-type': 'application/json',
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(30000),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`DingTalk OAPI failed: ${res.status} ${text}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`DingTalk OAPI returned non-JSON response: ${text}`);
+    }
+    const errorCode = parsed.errcode;
+    if (errorCode === 0 || errorCode === '0' || errorCode === undefined) {
+        return parsed;
+    }
+    const errorMessage = typeof parsed.errmsg === 'string'
+        ? parsed.errmsg
+        : typeof parsed.message === 'string'
+            ? parsed.message
+            : text;
+    throw new Error(`DingTalk OAPI business error: ${String(errorCode)} ${errorMessage}`);
+}
 function normalizeConversationType(type) {
     return type?.trim().toLowerCase();
 }
+function isSingleConversation(type) {
+    const normalizedType = normalizeConversationType(type);
+    return (normalizedType === '0' ||
+        normalizedType === 'single' ||
+        normalizedType === 'singlechat' ||
+        normalizedType === 'oto');
+}
+function isGroupConversation(type) {
+    const normalizedType = normalizeConversationType(type);
+    return (normalizedType === '1' ||
+        normalizedType === '2' ||
+        normalizedType === 'group' ||
+        normalizedType === 'groupchat');
+}
+async function resolveUnionIdByUserId(userId) {
+    if (!userId)
+        return undefined;
+    const cached = unionIdByUserId.get(userId);
+    if (cached)
+        return cached;
+    const result = await callOapi('/topapi/v2/user/get', {
+        userid: userId,
+        language: 'zh_CN',
+    });
+    const unionId = result.result?.unionid;
+    if (typeof unionId === 'string' && unionId.length > 0) {
+        unionIdByUserId.set(userId, unionId);
+        return unionId;
+    }
+    return undefined;
+}
 function buildProactiveAttempts(target, content) {
     const robotCode = getRobotCode(target);
     const payload = buildTextPayload(content);
@@ -214,6 +279,7 @@ export function stopDingTalk() {
     }
     finally {
         sessionWebhookByChat.clear();
+        unionIdByUserId.clear();
         client = null;
         messageHandler = null;
         log.info('DingTalk client stopped');
@@ -236,19 +302,107 @@ export async function sendProactiveText(target, content) {
         }
         catch (err) {
             lastError = err;
-            log.warn(`DingTalk proactive ${attempt.label} send failed:`, err);
+            const msg = err instanceof Error ? err.message : String(err);
+            if (msg.includes('robot') || msg.includes('resource.not.found')) {
+                log.debug(`DingTalk proactive ${attempt.label} send failed:`, err);
+            }
+            else {
+                log.warn(`DingTalk proactive ${attempt.label} send failed:`, err);
+            }
         }
     }
     throw lastError instanceof Error
         ? lastError
         : new Error(`DingTalk proactive send failed for chat ${target.chatId}`);
 }
-export async function prepareStreamingCard(chatId, templateId, cardData) {
-    const result = await callOpenApi('/v1.0/aiInteraction/prepare', {
-        openConversationId: chatId,
-        contentType: 'ai_card',
-        content: buildAiCardContent(templateId, cardData),
-    });
+export async function prepareStreamingCard(target, templateId, cardData) {
+    const normalizedTarget = typeof target === 'string' ? { chatId: target } : target;
+    const contentType = 'ai_card';
+    const content = buildAiCardContent(templateId, cardData);
+    const attempts = [];
+    log.debug(`DingTalk prepare: conversationType=${normalizedTarget.conversationType ?? 'undefined'}, senderStaffId=${normalizedTarget.senderStaffId ?? 'undefined'}`);
+    if (isSingleConversation(normalizedTarget.conversationType)) {
+        let unionId;
+        try {
+            unionId = await resolveUnionIdByUserId(normalizedTarget.senderStaffId);
+        }
+        catch (err) {
+            log.debug('Failed to resolve DingTalk unionId from senderStaffId:', err);
+        }
+        if (unionId) {
+            attempts.push({
+                label: 'single-unionid',
+                body: { unionId, contentType, content },
+            });
+        }
+        if (normalizedTarget.chatId) {
+            attempts.push({
+                label: 'single-chatid',
+                body: { openConversationId: normalizedTarget.chatId, contentType, content },
+            });
+        }
+    }
+    else if (isGroupConversation(normalizedTarget.conversationType)) {
+        // 群聊时也优先尝试 unionId：部分场景下 conversationType 可能误报，或单聊被识别为群聊
+        let unionId;
+        try {
+            unionId = await resolveUnionIdByUserId(normalizedTarget.senderStaffId);
+        }
+        catch (err) {
+            log.debug('Failed to resolve DingTalk unionId for group (fallback):', err);
+        }
+        if (unionId) {
+            attempts.push({
+                label: 'group-unionid',
+                body: { unionId, contentType, content },
+            });
+        }
+        if (normalizedTarget.chatId) {
+            attempts.push({
+                label: 'group-chatid',
+                body: { openConversationId: normalizedTarget.chatId, contentType, content },
+            });
+        }
+    }
+    else {
+        let unionId;
+        try {
+            unionId = await resolveUnionIdByUserId(normalizedTarget.senderStaffId);
+        }
+        catch (err) {
+            log.debug('Failed to resolve DingTalk unionId for unknown conversation type:', err);
+        }
+        if (unionId) {
+            attempts.push({
+                label: 'unknown-unionid',
+                body: { unionId, contentType, content },
+            });
+        }
+        if (normalizedTarget.chatId) {
+            attempts.push({
+                label: 'unknown-chatid',
+                body: { openConversationId: normalizedTarget.chatId, contentType, content },
+            });
+        }
+    }
+    if (attempts.length === 0) {
+        throw new Error('DingTalk prepare target is incomplete');
+    }
+    let result;
+    let lastError;
+    for (const attempt of attempts) {
+        try {
+            result = await callOpenApi('/v1.0/aiInteraction/prepare', attempt.body);
+            break;
+        }
+        catch (err) {
+            lastError = err;
+            log.debug(`DingTalk prepare attempt failed (${attempt.label}):`, err);
+        }
+    }
+    if (!result) {
+        throw lastError instanceof Error ? lastError : new Error('DingTalk prepare failed');
+    }
     const token = result.result?.conversationToken;
     if (typeof token !== 'string' || token.length === 0) {
         throw new Error(`DingTalk prepare did not return conversationToken: ${JSON.stringify(result)}`);
@@ -275,3 +429,163 @@ export async function finishStreamingCard(conversationToken) {
         throw new Error(`DingTalk finish returned success=false: ${JSON.stringify(result)}`);
     }
 }
+/** 创建并投放卡片（卡片平台 API，支持普通群流式更新） */
+export async function createAndDeliverCard(target, templateId, outTrackId, cardData) {
+    const { chatId, robotCode, conversationType, senderStaffId } = target;
+    if (!robotCode) {
+        throw new Error('DingTalk robotCode required for createAndDeliver');
+    }
+    const isSingle = isSingleConversation(conversationType);
+    const cardParamMap = buildCardParamMap(cardData);
+    if (!cardParamMap.content && !cardParamMap.lastMessage)
+        cardParamMap.content = '...';
+    const lastMsg = String(cardData.lastMessage ?? cardData.displayText ?? cardData.content ?? cardData.title ?? 'AI').slice(0, 50);
+    const body = {
+        userId: senderStaffId ?? 'system',
+        cardTemplateId: templateId,
+        outTrackId,
+        cardData: { cardParamMap },
+    };
+    if (isSingle && senderStaffId) {
+        body.openSpaceId = `dtv1.card//im_robot.${senderStaffId}`;
+        body.imRobotOpenSpaceModel = {
+            lastMessageI18n: { zh_CN: lastMsg },
+            searchSupport: { searchIcon: '', searchTypeName: '消息', searchDesc: '' },
+            notification: { alertContent: lastMsg },
+        };
+        body.imRobotOpenDeliverModel = { spaceType: 'IM_ROBOT' };
+    }
+    else {
+        body.openSpaceId = `dtv1.card//im_group.${chatId}`;
+        body.imGroupOpenSpaceModel = {
+            lastMessageI18n: { zh_CN: lastMsg },
+            searchSupport: { searchIcon: '', searchTypeName: '消息', searchDesc: '' },
+            notification: { alertContent: lastMsg },
+        };
+        body.imGroupOpenDeliverModel = {
+            robotCode,
+            atUserIds: {},
+            recipients: [],
+        };
+    }
+    await callOpenApiWithMethod('POST', '/v1.0/card/instances/createAndDeliver', body);
+}
+/** 将 cardData 转为 cardParamMap（对象/数组需 JSON 序列化） */
+function buildCardParamMap(cardData) {
+    const cardParamMap = {};
+    for (const [k, v] of Object.entries(cardData)) {
+        if (v === undefined || v === null)
+            continue;
+        if (typeof v === 'object') {
+            cardParamMap[k] = JSON.stringify(v);
+        }
+        else {
+            cardParamMap[k] = String(v);
+        }
+    }
+    return cardParamMap;
+}
+/** 更新卡片实例（用于流式更新） */
+export async function updateCardInstance(outTrackId, cardData) {
+    const cardParamMap = buildCardParamMap(cardData);
+    await callOpenApiWithMethod('PUT', '/v1.0/card/instances', {
+        outTrackId,
+        cardData: { cardParamMap },
+    });
+}
+/** StandardCard 模板结构（与钉钉官方 Go 打字机示例完全一致：text=标题，markdown=内容） */
+function buildStandardCardData(cardData) {
+    const title = String(cardData.title ?? 'AI');
+    const content = String(cardData.content ?? cardData.displayText ?? '').trim() || '...';
+    const schema = {
+        config: { autoLayout: true, enableForward: true },
+        header: {
+            title: { type: 'text', text: title },
+            logo: '@lALPDfJ6V_FPDmvNAfTNAfQ',
+        },
+        contents: [
+            { type: 'text', text: title, id: 'text_1693929551595' },
+            { type: 'divider', id: 'divider_1693929551595' },
+            { type: 'markdown', text: content, id: 'markdown_1693929674245' },
+        ],
+    };
+    return JSON.stringify(schema);
+}
+/** 互动卡片普通版：发送（用于 prepare 失败时的 fallback 流式） */
+export async function sendRobotInteractiveCard(target, cardBizId, cardData) {
+    const { chatId, robotCode, conversationType } = target;
+    if (!robotCode) {
+        throw new Error('DingTalk robotCode required for interactive card');
+    }
+    const cardDataStr = buildStandardCardData(cardData);
+    const isSingle = isSingleConversation(conversationType);
+    const body = {
+        cardTemplateId: 'StandardCard',
+        cardBizId,
+        outTrackId: cardBizId,
+        robotCode,
+        cardData: cardDataStr,
+    };
+    if (isSingle && target.senderStaffId) {
+        body.singleChatReceiver = JSON.stringify({ userid: target.senderStaffId });
+    }
+    else {
+        body.openConversationId = chatId;
+    }
+    log.debug(`DingTalk sendRobotInteractiveCard: isSingle=${isSingle}, robotCode=${robotCode?.slice(0, 8)}..., chatIdLen=${chatId?.length}`);
+    try {
+        await callOpenApiWithMethod('POST', '/v1.0/im/v1.0/robot/interactiveCards/send', body);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes('param.error') || msg.includes('参数无效')) {
+            log.warn('DingTalk robot interactive card param.error - request body (no secrets):', JSON.stringify({ ...body, robotCode: body.robotCode ? '[REDACTED]' : undefined }, null, 2));
+        }
+        throw err;
+    }
+}
+/** 互动卡片普通版：更新（单条消息流式更新） */
+export async function updateRobotInteractiveCard(cardBizId, cardData) {
+    const cardDataStr = buildStandardCardData(cardData);
+    const body = { cardBizId, cardData: cardDataStr };
+    await callOpenApiWithMethod('PUT', '/v1.0/im/robots/interactiveCards', body);
+}
+async function callOpenApiWithMethod(method, path, body) {
+    const accessToken = await getClient().getAccessToken();
+    const res = await fetch(`${DINGTALK_OPENAPI_BASE}${path}`, {
+        method,
+        headers: {
+            'content-type': 'application/json',
+            'x-acs-dingtalk-access-token': String(accessToken),
+        },
+        body: JSON.stringify(body),
+        signal: AbortSignal.timeout(30000),
+    });
+    const text = await res.text();
+    if (!res.ok) {
+        throw new Error(`DingTalk OpenAPI failed: ${res.status} ${text}`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+    const errorCode = parsed.errorcode ?? parsed.errcode;
+    const success = parsed.success;
+    if (errorCode === 0 ||
+        errorCode === '0' ||
+        success === true ||
+        (errorCode === undefined && success === undefined)) {
+        return parsed;
+    }
+    const errorMessage = typeof parsed.errmsg === 'string'
+        ? parsed.errmsg
+        : typeof parsed.errormsg === 'string'
+            ? parsed.errormsg
+            : typeof parsed.message === 'string'
+                ? parsed.message
+                : text;
+    throw new Error(`DingTalk OpenAPI business error: ${String(errorCode)} ${errorMessage}`);
+}

package/dist/dingtalk/event-handler.js

@@ -24,6 +24,7 @@ function parseRobotMessage(data) {
 export function setupDingTalkHandlers(config, sessionManager) {
     configureDingTalkMessageSender({
         cardTemplateId: config.dingtalkCardTemplateId,
+        robotCodeFallback: config.dingtalkClientId,
     });
     if (config.dingtalkCardTemplateId) {
         log.info('DingTalk AI card streaming enabled');
@@ -43,7 +44,7 @@ export function setupDingTalkHandlers(config, sessionManager) {
         getRunningTasksSize: () => runningTasks.size,
     });
     registerPermissionSender('dingtalk', { sendTextReply, sendPermissionCard });
-    async function handleAIRequest(userId, chatId, prompt, workDir, convId, _threadCtx, replyToMessageId) {
+    async function handleAIRequest(userId, chatId, prompt, workDir, convId, _threadCtx, replyToMessageId, dingtalkTarget) {
         log.info(`[AI_REQUEST] userId=${userId}, chatId=${chatId}, promptLength=${prompt.length}`);
         const toolAdapter = getAdapter(config.aiCommand);
         if (!toolAdapter) {
@@ -55,7 +56,7 @@ export function setupDingTalkHandlers(config, sessionManager) {
             : undefined;
         log.info(`[AI_REQUEST] Running ${config.aiCommand} for user ${userId}, sessionId=${sessionId ?? 'new'}`);
         const toolId = config.aiCommand;
-        const msgId = await sendThinkingMessage(chatId, replyToMessageId, toolId);
+        const msgId = await sendThinkingMessage(chatId, replyToMessageId, toolId, dingtalkTarget);
         const stopTyping = startTypingLoop(chatId);
         const taskKey = `${userId}:${msgId}`;
         await runAITask({ config, sessionManager }, { userId, chatId, workDir, sessionId, convId, platform: 'dingtalk', taskKey }, prompt, toolAdapter, {
@@ -112,7 +113,7 @@ export function setupDingTalkHandlers(config, sessionManager) {
             chatId,
             userId,
             conversationType: robotMessage.conversationType,
-            robotCode: robotMessage.robotCode,
+            robotCode: robotMessage.robotCode || config.dingtalkClientId,
         });
         setChatUser(chatId, userId, 'dingtalk');
         try {
@@ -127,8 +128,15 @@ export function setupDingTalkHandlers(config, sessionManager) {
         }
         const workDir = sessionManager.getWorkDir(userId);
         const convId = sessionManager.getConvId(userId);
+        const dingtalkTarget = {
+            chatId,
+            conversationType: robotMessage.conversationType,
+            senderStaffId: robotMessage.senderStaffId,
+            senderId: robotMessage.senderId,
+            robotCode: robotMessage.robotCode || config.dingtalkClientId,
+        };
         const enqueueResult = requestQueue.enqueue(userId, convId, text, async (prompt) => {
-            await handleAIRequest(userId, chatId, prompt, workDir, convId);
+            await handleAIRequest(userId, chatId, prompt, workDir, convId, undefined, undefined, dingtalkTarget);
         });
         if (enqueueResult === 'rejected') {
             await sendTextReply(chatId, '请求队列已满，请稍后再试。');

package/dist/dingtalk/message-sender.d.ts

@@ -1,11 +1,13 @@
+import type { DingTalkStreamingTarget } from './client.js';
 import type { ThreadContext } from '../shared/types.js';
 import type { DingTalkActiveTarget } from '../shared/active-chats.js';
 export type MessageStatus = 'thinking' | 'streaming' | 'done' | 'error';
 interface SenderSettings {
     cardTemplateId?: string;
+    robotCodeFallback?: string;
 }
 export declare function configureDingTalkMessageSender(settings: SenderSettings): void;
-export declare function sendThinkingMessage(chatId: string, _replyToMessageId?: string, toolId?: string): Promise<string>;
+export declare function sendThinkingMessage(chatId: string, _replyToMessageId?: string, toolId?: string, target?: DingTalkStreamingTarget): Promise<string>;
 export declare function updateMessage(chatId: string, messageId: string, content: string, status: MessageStatus, note?: string, toolId?: string): Promise<void>;
 export declare function sendFinalMessages(chatId: string, messageId: string, fullContent: string, note: string, toolId?: string): Promise<void>;
 export declare function sendErrorMessage(chatId: string, messageId: string, error: string, toolId?: string): Promise<void>;

package/dist/dingtalk/message-sender.js

@@ -1,6 +1,6 @@
 import { randomBytes } from 'node:crypto';
 import { basename } from 'node:path';
-import { sendText, sendProactiveText, prepareStreamingCard, updateStreamingCard, finishStreamingCard, } from './client.js';
+import { sendText, sendProactiveText, prepareStreamingCard, updateStreamingCard, finishStreamingCard, createAndDeliverCard, updateCardInstance, sendRobotInteractiveCard, updateRobotInteractiveCard, } from './client.js';
 import { createLogger } from '../logger.js';
 import { splitLongContent, getAIToolDisplayName } from '../shared/utils.js';
 import { listDirectories, buildDirectoryKeyboard } from '../commands/handler.js';
@@ -26,6 +26,7 @@ function generateMessageId() {
 export function configureDingTalkMessageSender(settings) {
     senderSettings = {
         cardTemplateId: settings.cardTemplateId?.trim(),
+        robotCodeFallback: settings.robotCodeFallback?.trim(),
     };
 }
 function getCardTemplateId() {
@@ -56,20 +57,39 @@ function getToolTitle(toolId, status) {
         return `${toolName} - 执行中`;
     return `${toolName} - 错误`;
 }
+/**
+ * 适配钉钉官方「搜索结果卡片」模板变量结构
+ * 变量：lastMessage, content, resources, users, flowStatus
+ */
 function buildCardData(content, status, note, toolId = 'claude') {
     const toolName = getAIToolDisplayName(toolId);
     const safeContent = content.trim() || (status === 'thinking' ? '正在思考，请稍候...' : status === 'error' ? '执行失败' : '...');
     const safeNote = note?.trim() || '';
+    // lastMessage: 卡片摘要，用于会话列表预览
+    const lastMessage = safeContent.length > 50 ? `${safeContent.slice(0, 47)}...` : safeContent || getToolTitle(toolId, status);
+    // resources: 对象数组，note 作为来源列表（如 "1. xxx\n2. yyy" 按行解析）
+    const resources = [];
+    if (safeNote) {
+        for (const line of safeNote.split('\n')) {
+            const t = line.replace(/^\d+\.\s*/, '').trim();
+            if (t)
+                resources.push({ title: t });
+        }
+        if (resources.length === 0)
+            resources.push({ title: safeNote });
+    }
     return {
-        title: getToolTitle(toolId, status),
+        lastMessage,
         content: safeContent,
+        resources,
+        users: [],
+        flowStatus: FLOW_STATUS[status],
+        // 保留兼容字段
         note: safeNote,
-        toolName,
         status,
-        flowStatus: FLOW_STATUS[status],
-        icon: STATUS_ICONS[status],
+        toolName,
+        title: getToolTitle(toolId, status),
         displayText: formatMessage(safeContent, status, safeNote, toolId),
-        updatedAt: new Date().toISOString(),
     };
 }
 async function tryFinishCard(conversationToken) {
@@ -99,33 +119,99 @@ async function sendTextWithRetry(chatId, text, retries = 1) {
     }
     throw lastError;
 }
-export async function sendThinkingMessage(chatId, _replyToMessageId, toolId = 'claude') {
+export async function sendThinkingMessage(chatId, _replyToMessageId, toolId = 'claude', target) {
     const messageId = generateMessageId();
     const templateId = getCardTemplateId();
-    if (!templateId)
-        return messageId;
-    try {
-        const conversationToken = await prepareStreamingCard(chatId, templateId, buildCardData('', 'thinking', '请稍候', toolId));
-        streamStates.set(messageId, { chatId, mode: 'card', conversationToken, toolId });
+    const robotCode = target?.robotCode || senderSettings.robotCodeFallback;
+    // 1. 优先尝试互动卡片普通版（机器人适用，无需 AI 助理权限）
+    if (robotCode) {
+        try {
+            const effectiveTarget = target
+                ? { ...target, robotCode }
+                : { chatId, robotCode };
+            const cardBizId = messageId;
+            await sendRobotInteractiveCard(effectiveTarget, cardBizId, buildCardData('', 'thinking', '请稍候', toolId));
+            streamStates.set(messageId, {
+                chatId,
+                mode: 'interactiveCard',
+                cardBizId,
+                toolId,
+                target,
+            });
+            return messageId;
+        }
+        catch (err) {
+            log.debug('DingTalk 互动卡片普通版失败，尝试其他方式:', err);
+        }
     }
-    catch (err) {
-        log.warn('Failed to prepare DingTalk streaming card, falling back to text:', err);
-        streamStates.set(messageId, { chatId, mode: 'text', toolId });
+    // 2. 尝试 AI 助理 prepare（需 AI 助理会话）或 createAndDeliver（高级版）
+    if (templateId) {
+        try {
+            const conversationToken = await prepareStreamingCard(target ?? chatId, templateId, buildCardData('', 'thinking', '请稍候', toolId));
+            streamStates.set(messageId, { chatId, mode: 'card', conversationToken, toolId, target });
+            return messageId;
+        }
+        catch (prepareErr) {
+            log.debug('DingTalk prepare failed, trying createAndDeliver:', prepareErr);
+            if (robotCode) {
+                try {
+                    const effectiveTarget = target
+                        ? { ...target, robotCode }
+                        : { chatId, robotCode };
+                    await createAndDeliverCard(effectiveTarget, templateId, messageId, buildCardData('', 'thinking', '请稍候', toolId));
+                    streamStates.set(messageId, {
+                        chatId,
+                        mode: 'cardInstance',
+                        outTrackId: messageId,
+                        toolId,
+                        target,
+                    });
+                    return messageId;
+                }
+                catch (cardErr) {
+                    log.debug('DingTalk createAndDeliver failed:', cardErr);
+                }
+            }
+        }
     }
+    streamStates.set(messageId, { chatId, mode: 'text', toolId, target });
+    log.info('DingTalk 流式卡片不可用，将使用普通文本回复');
     return messageId;
 }
 export async function updateMessage(chatId, messageId, content, status, note, toolId = 'claude') {
     void chatId;
-    const templateId = getCardTemplateId();
     const state = streamStates.get(messageId);
-    if (!templateId || !state || state.mode !== 'card' || !state.conversationToken) {
+    if (!state)
+        return;
+    if (state.mode === 'card' && state.conversationToken) {
+        const templateId = getCardTemplateId();
+        if (!templateId)
+            return;
+        try {
+            await updateStreamingCard(state.conversationToken, templateId, buildCardData(content, status, note, toolId));
+        }
+        catch (err) {
+            log.warn('Failed to update DingTalk streaming card:', err);
+        }
         return;
     }
-    try {
-        await updateStreamingCard(state.conversationToken, templateId, buildCardData(content, status, note, toolId));
+    if (state.mode === 'cardInstance' && state.outTrackId) {
+        try {
+            await updateCardInstance(state.outTrackId, buildCardData(content, status, note, toolId));
+        }
+        catch (err) {
+            log.warn('Failed to update DingTalk card instance:', err);
+        }
+        return;
     }
-    catch (err) {
-        log.warn('Failed to update DingTalk streaming card:', err);
+    if (state.mode === 'interactiveCard' && state.cardBizId) {
+        try {
+            await updateRobotInteractiveCard(state.cardBizId, buildCardData(content, status, note, toolId));
+        }
+        catch (err) {
+            log.warn('Failed to update DingTalk interactive card:', err);
+        }
+        return;
     }
 }
 export async function sendFinalMessages(chatId, messageId, fullContent, note, toolId = 'claude') {
@@ -161,6 +247,36 @@ export async function sendFinalMessages(chatId, messageId, fullContent, note, to
             await tryFinishCard(state.conversationToken);
         }
     }
+    if (templateId && state?.mode === 'cardInstance' && state.outTrackId) {
+        try {
+            const cardNote = parts.length > 1 ? `内容较长，后续将继续发送 (${1}/${parts.length})` : note;
+            await updateCardInstance(state.outTrackId, buildCardData(parts[0], 'done', cardNote, toolId));
+            streamStates.delete(messageId);
+            for (let i = 1; i < parts.length; i++) {
+                const partNote = i === parts.length - 1 ? note : `继续输出 (${i + 1}/${parts.length})`;
+                await sendTextWithRetry(chatId, formatMessage(parts[i], 'done', partNote, toolId));
+            }
+            return;
+        }
+        catch (err) {
+            log.warn('Failed to finalize DingTalk card instance, falling back to text:', err);
+        }
+    }
+    if (state?.mode === 'interactiveCard' && state.cardBizId) {
+        try {
+            const cardNote = parts.length > 1 ? `内容较长，后续将继续发送 (${1}/${parts.length})` : note;
+            await updateRobotInteractiveCard(state.cardBizId, buildCardData(parts[0], 'done', cardNote, toolId));
+            streamStates.delete(messageId);
+            for (let i = 1; i < parts.length; i++) {
+                const partNote = i === parts.length - 1 ? note : `继续输出 (${i + 1}/${parts.length})`;
+                await sendTextWithRetry(chatId, formatMessage(parts[i], 'done', partNote, toolId));
+            }
+            return;
+        }
+        catch (err) {
+            log.warn('Failed to finalize DingTalk interactive card, falling back to text:', err);
+        }
+    }
     streamStates.delete(messageId);
     for (let i = 0; i < parts.length; i++) {
         const partNote = parts.length > 1
@@ -196,6 +312,26 @@ export async function sendErrorMessage(chatId, messageId, error, toolId = 'claud
             await tryFinishCard(state.conversationToken);
         }
     }
+    if (templateId && state?.mode === 'cardInstance' && state.outTrackId) {
+        try {
+            await updateCardInstance(state.outTrackId, buildCardData(`错误：${error}`, 'error', '执行失败', toolId));
+            streamStates.delete(messageId);
+            return;
+        }
+        catch (err) {
+            log.warn('Failed to update DingTalk error card instance, falling back to text:', err);
+        }
+    }
+    if (state?.mode === 'interactiveCard' && state.cardBizId) {
+        try {
+            await updateRobotInteractiveCard(state.cardBizId, buildCardData(`错误：${error}`, 'error', '执行失败', toolId));
+            streamStates.delete(messageId);
+            return;
+        }
+        catch (err) {
+            log.warn('Failed to update DingTalk error interactive card, falling back to text:', err);
+        }
+    }
     streamStates.delete(messageId);
     await sendTextWithRetry(chatId, formatMessage(`错误：${error}`, 'error', '执行失败', toolId));
 }

package/dist/dingtalk/message-sender.test.js

@@ -24,11 +24,21 @@ describe('DingTalk message sender', () => {
         prepareStreamingCardMock.mockResolvedValue('ctx-1');
         const sender = await import('./message-sender.js');
         sender.configureDingTalkMessageSender({ cardTemplateId: 'tpl-1' });
-        const messageId = await sender.sendThinkingMessage('cid-1', undefined, 'codex');
+        const messageId = await sender.sendThinkingMessage('cid-1', undefined, 'codex', {
+            chatId: 'cid-1',
+            conversationType: '0',
+            senderStaffId: 'staff-1',
+            senderId: 'sender-1',
+        });
         await sender.updateMessage('cid-1', messageId, '处理中', 'streaming', '执行中', 'codex');
         await sender.sendFinalMessages('cid-1', messageId, '最终结果', '耗时 1s', 'codex');
         expect(prepareStreamingCardMock).toHaveBeenCalledTimes(1);
-        expect(prepareStreamingCardMock).toHaveBeenCalledWith('cid-1', 'tpl-1', expect.objectContaining({
+        expect(prepareStreamingCardMock).toHaveBeenCalledWith({
+            chatId: 'cid-1',
+            conversationType: '0',
+            senderStaffId: 'staff-1',
+            senderId: 'sender-1',
+        }, 'tpl-1', expect.objectContaining({
             status: 'thinking',
             flowStatus: 1,
             toolName: 'Codex',
@@ -101,4 +111,21 @@ describe('DingTalk message sender', () => {
         expect(finishStreamingCardMock).toHaveBeenCalledWith('ctx-finish');
         expect(sendTextMock).not.toHaveBeenCalled();
     });
+    it('passes single chat metadata to prepare call', async () => {
+        prepareStreamingCardMock.mockResolvedValue('ctx-meta');
+        const sender = await import('./message-sender.js');
+        sender.configureDingTalkMessageSender({ cardTemplateId: 'tpl-meta' });
+        await sender.sendThinkingMessage('cid-meta', undefined, 'claude', {
+            chatId: 'cid-meta',
+            conversationType: '0',
+            senderStaffId: '015038621332843498',
+            senderId: '$:LWCP_v1:$abc',
+        });
+        expect(prepareStreamingCardMock).toHaveBeenCalledWith({
+            chatId: 'cid-meta',
+            conversationType: '0',
+            senderStaffId: '015038621332843498',
+            senderId: '$:LWCP_v1:$abc',
+        }, 'tpl-meta', expect.any(Object));
+    });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wu529778790/open-im",
-  "version": "1.5.1",
+  "version": "1.5.2-beta.0",
   "description": "Multi-platform IM bridge for AI CLI tools (Claude, Codex, Cursor)",
   "type": "module",
   "main": "dist/index.js",