@dingtalk-real-ai/dingtalk-connector 0.8.0-beta.2 → 0.8.1

package/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.1] - 2026-03-20
+
+### 修复 / Fixes
+- 🐛 **文件和图片下载 OSS 签名验证失败** - 修复默认 `Content-Type` 请求头导致 OSS 签名验证失败的问题，确保文件和图片能够正常下载  
+  **File and image download OSS signature verification failure** - Fixed OSS signature verification failure caused by default `Content-Type` header, ensuring files and images download correctly
+
+## [0.8.0] - 2026-03-20
+
+### 重构 / Refactoring
+- ✅ **业务逻辑分层重构** - 对项目结构进行重构，采用业务逻辑分层设计，明确职责边界，降低模块耦合并提升可维护性  
+  **Business-logic layered refactor** - Reworked project architecture with layered business logic design, clarifying responsibilities, reducing coupling, and improving maintainability
+- ✅ **OpenClaw 对接方式升级** - 从 OpenClaw HTTP 对接迁移为 OpenClaw SDK，统一调用链路并增强集成稳定性  
+  **OpenClaw integration upgrade** - Migrated from OpenClaw HTTP integration to OpenClaw SDK for a unified invocation flow and better integration stability
+
+### 改进 / Improvements
+- ✅ **IM 交互体验优化** - 优化 IM 场景下的部分交互细节，提升消息处理与反馈体验  
+  **IM interaction optimization** - Improved several interaction details in IM scenarios to provide smoother message handling and feedback
+- ✅ **README 重写与配置简化** - 重写 README 文档，简化配置教程，降低接入门槛并提升上手效率  
+  **README rewrite & simpler setup** - Rewrote README and simplified setup guidance to reduce onboarding complexity and speed up adoption
+
+### 修复 / Fixes
+- 🐛 **dingtalk-stream 断连问题修复** - 修复 dingtalk-stream 相关的部分断连场景，增强长连接稳定性与恢复能力  
+  **dingtalk-stream disconnect fixes** - Fixed several dingtalk-stream related disconnection scenarios, improving long-connection stability and recovery
+
 ## [0.7.10] - 2026-03-16
 
 ### 新增 / Added

package/README.en.md

@@ -268,20 +268,26 @@ Configure multiple bots connected to different agents:
   "agents": {
     "list": [
       {
-        "agentId": "ding-bot1",
+        "id": "ding-bot1",
+        "name": "Customer Service Bot",
         "model": "your-model-config",
-        "persona": {
-          "name": "Customer Service Bot",
-          "systemPrompt": "You are a professional customer service assistant..."
+        "workspace": "~/.openclaw/workspace-bot1",
+        "identity": {
+          "name": "Service Assistant",
+          "theme": "customer service",
+          "emoji": "🤝"
         }
         // Other agent configurations...
       },
       {
-        "agentId": "ding-bot2",
+        "id": "ding-bot2",
+        "name": "Technical Support Bot",
         "model": "your-model-config",
-        "persona": {
-          "name": "Technical Support Bot",
-          "systemPrompt": "You are a technical support expert..."
+        "workspace": "~/.openclaw/workspace-bot2",
+        "identity": {
+          "name": "Tech Expert",
+          "theme": "technical support",
+          "emoji": "🔧"
         }
         // Other agent configurations...
       }

package/README.md

@@ -279,20 +279,26 @@ openclaw logs --follow
   "agents": {
     "list": [
       {
-        "agentId": "ding-bot1",
+        "id": "ding-bot1",
+        "name": "钉钉客服机器人",
         "model": "your-model-config",
-        "persona": {
-          "name": "钉钉客服机器人",
-          "systemPrompt": "你是一个专业的客服助手..."
+        "workspace": "~/.openclaw/workspace-bot1",
+        "identity": {
+          "name": "客服小助手",
+          "theme": "专业客服",
+          "emoji": "🤝"
         }
         // 其他 agent 配置...
       },
       {
-        "agentId": "ding-bot2",
+        "id": "ding-bot2",
+        "name": "钉钉技术支持机器人",
         "model": "your-model-config",
-        "persona": {
-          "name": "钉钉技术支持机器人",
-          "systemPrompt": "你是一个技术支持专家..."
+        "workspace": "~/.openclaw/workspace-bot2",
+        "identity": {
+          "name": "技术专家",
+          "theme": "技术支持",
+          "emoji": "🔧"
         }
         // 其他 agent 配置...
       }

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.8.0-beta.2",
+  "version": "0.8.1",
   "description": "DingTalk (钉钉) messaging channel via Stream mode with AI Card streaming",
   "author": "DingTalk Real Team",
   "main": "index.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dingtalk-real-ai/dingtalk-connector",
-  "version": "0.8.0-beta.2",
+  "version": "0.8.1",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "index.ts",
   "type": "module",

package/src/core/connection.ts

@@ -138,6 +138,7 @@ export async function monitorSingleAccount(
   // ============ 连接状态管理 ============
 
   let lastSocketAvailableTime = Date.now();
+  let connectionEstablishedTime = Date.now(); // 记录连接建立时间
   let isReconnecting = false;
   let reconnectAttempts = 0;
   let keepAliveTimer: NodeJS.Timeout | null = null;
@@ -226,18 +227,49 @@ export async function monitorSingleAccount(
       // 2. 重新建立连接
       await client.connect();
 
-      // 3. 验证连接是否真正建立（必须检查 socket 状态）
-      const socketState = client.socket?.readyState;
-      if (socketState !== 1) {
-        // socket 状态不是 OPEN (1)，说明连接未真正建立
-        throw new Error(`连接未建立，socket 状态=${socketState} (期望=1)`);
+      // 3. 等待连接真正建立（监听 open 事件，最多等待 10 秒）
+      const connectionEstablished = await new Promise<boolean>((resolve) => {
+        const timeout = setTimeout(() => {
+          resolve(false);
+        }, 10_000); // 10 秒超时
+
+        // 如果已经是 OPEN 状态，直接返回
+        if (client.socket?.readyState === 1) {
+          clearTimeout(timeout);
+          resolve(true);
+          return;
+        }
+
+        // 否则监听 open 事件
+        const onOpen = () => {
+          clearTimeout(timeout);
+          client.socket?.removeListener('open', onOpen);
+          client.socket?.removeListener('error', onError);
+          resolve(true);
+        };
+
+        const onError = (err: any) => {
+          clearTimeout(timeout);
+          client.socket?.removeListener('open', onOpen);
+          client.socket?.removeListener('error', onError);
+          logger.warn(`连接建立失败: ${err.message}`);
+          resolve(false);
+        };
+
+        client.socket?.once('open', onOpen);
+        client.socket?.once('error', onError);
+      });
+
+      if (!connectionEstablished) {
+        throw new Error(`连接建立超时或失败`);
       }
 
-      // 4. 重置 socket 可用时间和重连计数
+      // 4. 重置 socket 可用时间、连接建立时间和重连计数
       lastSocketAvailableTime = Date.now();
+      connectionEstablishedTime = Date.now(); // 重置连接建立时间
       reconnectAttempts = 0; // 重连成功，重置计数
 
-      logger.info(`✅ 重连成功 (socket 状态=${socketState})`);
+      logger.info(`✅ 重连成功 (socket 状态=${client.socket?.readyState})`);
     } catch (err: any) {
       reconnectAttempts++;
       log?.error?.(
@@ -329,11 +361,20 @@ export async function monitorSingleAccount(
 
         // 【心跳检测】检查 socket 状态
         const socketState = client.socket?.readyState;
+        const timeSinceConnection = Date.now() - connectionEstablishedTime;
         logger.debug(
-          `🔍 心跳检测：socket 状态=${socketState}, elapsed=${Math.round(elapsed / 1000)}s`,
+          `🔍 心跳检测：socket 状态=${socketState}, elapsed=${Math.round(elapsed / 1000)}s, 连接已建立=${Math.round(timeSinceConnection / 1000)}s`,
         );
 
+        // 给新建立的连接 15 秒宽限期，避免在连接建立初期就触发重连
         if (socketState !== 1) {
+          if (timeSinceConnection < 15_000) {
+            logger.debug(
+              `⏳ 连接建立中（已 ${Math.round(timeSinceConnection / 1000)}s），跳过状态检查`,
+            );
+            return;
+          }
+          
           logger.info(
             `⚠️ 心跳检测：socket 状态=${socketState}，触发重连...`,
           );
@@ -519,8 +560,6 @@ export async function monitorSingleAccount(
 
         // ===== 第三步：开始处理消息 =====
         logger.info(`🚀 开始处理消息...`);
-        logger.info(`AccountId: ${accountId}`);
-        logger.info(`HasConfig: ${!!account.config}`);
 
         await messageHandler({
           accountId,

package/src/core/message-handler.ts

@@ -266,6 +266,11 @@ export async function downloadImageToFile(
   try {
     log?.info?.(`开始下载图片: ${downloadUrl.slice(0, 100)}...`);
     const resp = await dingtalkHttp.get(downloadUrl, {
+      proxy: false, // 禁用代理，避免 PAC 文件影响
+
+      headers: {
+        'Content-Type': undefined, // 删除默认的 Content-Type 请求头，让 OSS 签名验证通过
+      },
       responseType: 'arraybuffer',
       timeout: 30_000,
     });
@@ -366,6 +371,10 @@ export async function downloadFileToLocal(
   try {
     log?.info?.(`开始下载文件: ${fileName}`);
     const resp = await dingtalkHttp.get(downloadUrl, {
+      proxy: false, // 禁用代理，避免 PAC 文件影响
+      headers: {
+        'Content-Type': undefined, // 删除默认的 Content-Type 请求头，让 OSS 签名验证通过
+      },
       responseType: 'arraybuffer',
       timeout: 60_000, // 文件可能较大，增加超时时间
     });
@@ -407,7 +416,8 @@ export async function downloadFileToLocal(
     log?.info?.(`文件下载成功: ${fileName}, size=${buffer.length} bytes, path=${localPath}`);
     return localPath;
   } catch (err: any) {
-    log?.error?.(`文件下载失败: ${fileName}, error=${err.message}`);
+    console.error(`[ERROR] downloadFileToLocal 异常: ${err.message}`);
+    console.error(`[ERROR] 异常堆栈:\n${err.stack}`);
     return null;
   }
 }
@@ -526,7 +536,7 @@ interface HandleMessageParams {
 /**
  * 内部消息处理函数（实际执行消息处理逻辑）
  */
-async function handleDingTalkMessageInternal(params: HandleMessageParams): Promise<void> {
+export async function handleDingTalkMessageInternal(params: HandleMessageParams): Promise<void> {
   const { accountId, config, data, sessionWebhook, runtime, log, cfg } = params;
 
   const content = extractMessageContent(data);
@@ -825,7 +835,7 @@ async function handleDingTalkMessageInternal(params: HandleMessageParams): Promi
       const parseResult = await parseFileContent(localPath, fileName, log);
       
       if (parseResult.type === 'text' && parseResult.content) {
-        // 文本类文件：将内容注入到上下文
+        // 文本类文件：将内容注入到上下文（即使解析成功也给出文件路径）
         const contentPreview = parseResult.content.length > 200 
           ? parseResult.content.slice(0, 200) + '...' 
           : parseResult.content;
@@ -833,6 +843,7 @@ async function handleDingTalkMessageInternal(params: HandleMessageParams): Promi
         fileContentParts.push(
           `📄 **${fileType}**: ${fileName}\n` +
           `✅ 已解析文件内容（${parseResult.content.length} 字符）\n` +
+          `💾 已保存到本地: ${localPath}\n` +
           `📝 内容预览:\n\`\`\`\n${contentPreview}\n\`\`\`\n\n` +
           `📋 完整内容:\n${parseResult.content}`
         );
@@ -1191,13 +1202,13 @@ async function handleDingTalkMessageInternal(params: HandleMessageParams): Promi
  */
 export async function handleDingTalkMessage(params: HandleMessageParams): Promise<void> {
   const { accountId, data, log, cfg } = params;
-  
+
   // 构建会话标识（与会话上下文保持一致）
   const isDirect = data.conversationType === '1';
   const senderId = data.senderStaffId || data.senderId;
   const conversationId = data.conversationId;
   const baseSessionId = isDirect ? senderId : conversationId;
-  
+
   if (!baseSessionId) {
     log?.warn?.('无法构建会话标识，跳过队列管理');
     return handleDingTalkMessageInternal(params);
@@ -1206,7 +1217,7 @@ export async function handleDingTalkMessage(params: HandleMessageParams): Promis
   // 解析 agentId（与消息处理逻辑保持一致）
   const chatType = isDirect ? "direct" : "group";
   const peerId = isDirect ? senderId : conversationId;
-  
+
   let matchedAgentId: string | null = null;
   if (cfg.bindings && cfg.bindings.length > 0) {
     for (const binding of cfg.bindings) {
@@ -1228,38 +1239,46 @@ export async function handleDingTalkMessage(params: HandleMessageParams): Promis
   // 构建队列标识：会话 + agentId
   // 这样不同 agent 可以并发处理，同一 agent 的同一会话串行处理
   const queueKey = `${baseSessionId}:${matchedAgentId}`;
-  
-  // 更新会话活跃时间
-  sessionLastActivity.set(queueKey, Date.now());
-  
-  // 获取该会话+agent的上一个处理任务
-  const previousTask = sessionQueues.get(queueKey) || Promise.resolve();
-  
-  // 创建当前消息的处理任务
-  const currentTask = previousTask
-    .then(async () => {
-      log?.info?.(`[队列] 开始处理消息，queueKey=${queueKey}`);
-      await handleDingTalkMessageInternal(params);
-      log?.info?.(`[队列] 消息处理完成，queueKey=${queueKey}`);
-    })
-    .catch((err: any) => {
-      log?.error?.(`[队列] 消息处理异常，queueKey=${queueKey}, error=${err.message}`);
-      // 不抛出错误，避免阻塞后续消息
-    })
-    .finally(() => {
-      // 如果当前任务是队列中的最后一个任务，清理队列
-      if (sessionQueues.get(queueKey) === currentTask) {
-        sessionQueues.delete(queueKey);
-        log?.info?.(`[队列] 队列已清空，queueKey=${queueKey}`);
-      }
-    });
-  
-  // 更新队列
-  sessionQueues.set(queueKey, currentTask);
-  log?.info?.(`[队列] 消息已加入队列，queueKey=${queueKey}, 队列大小=${sessionQueues.size}`);
-  
-  // 不等待任务完成，让消息异步处理
-  // 这样可以立即返回，不阻塞 WebSocket 消息接收
+
+  try {
+
+    // 更新会话活跃时间
+    sessionLastActivity.set(queueKey, Date.now());
+
+    // 获取该会话+agent的上一个处理任务
+    const previousTask = sessionQueues.get(queueKey) || Promise.resolve();
+
+    // 创建当前消息的处理任务
+    const currentTask = previousTask
+      .then(async () => {
+        log?.info?.(`[队列] 开始处理消息，queueKey=${queueKey}`);
+        await handleDingTalkMessageInternal(params);
+        log?.info?.(`[队列] 消息处理完成，queueKey=${queueKey}`);
+      })
+      .catch((err: any) => {
+        log?.error?.(`[队列] 消息处理异常，queueKey=${queueKey}, error=${err.message}`);
+        // 不抛出错误，避免阻塞后续消息
+      })
+      .finally(() => {
+        // 如果当前任务是队列中的最后一个任务，清理队列
+        if (sessionQueues.get(queueKey) === currentTask) {
+          sessionQueues.delete(queueKey);
+          log?.info?.(`[队列] 队列已清空，queueKey=${queueKey}`);
+        }
+      });
+    
+    // 更新队列
+    sessionQueues.set(queueKey, currentTask);
+
+    // 等待当前任务完成
+    await currentTask;
+    console.log(`[DEBUG] 任务执行完成`);
+  } catch (err: any) {
+    console.error(`[DEBUG] 队列管理异常: ${err.message}`);
+    console.error(`[DEBUG] 队列管理异常堆栈: ${err.stack}`);
+    // 如果队列管理失败，直接调用内部处理函数
+    return handleDingTalkMessageInternal(params);
+  }
 }
 
 // handleDingTalkMessage 已在函数定义处直接导出

package/src/reply-dispatcher.ts

@@ -276,6 +276,12 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
       // 处理媒体标记
       let finalText = accumulatedText;
       
+      // ✅ 如果累积的文本为空，使用默认提示文案
+      if (!finalText.trim()) {
+        finalText = '✅ 任务执行完成（无文本输出）';
+        log.info(`[DingTalk][closeStreaming] 累积文本为空，使用默认提示文案`);
+      }
+      
       // 获取 oapiToken 用于媒体处理
       const oapiToken = await getOapiAccessToken(account.config as DingtalkConfig);
       
@@ -420,7 +426,14 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
         const hasText = Boolean(text.trim());
         const skipTextForDuplicateFinal =
           info?.kind === "final" && hasText && deliveredFinalTexts.has(text);
-        const shouldDeliverText = hasText && !skipTextForDuplicateFinal;
+        
+        // ✅ 如果是 final 响应且没有文本，使用默认提示文案
+        if (info?.kind === "final" && !hasText) {
+          text = '✅ 任务执行完成（无文本输出）';
+          log.info(`[DingTalk][deliver] final 响应无文本，使用默认提示文案`);
+        }
+        
+        const shouldDeliverText = Boolean(text.trim()) && !skipTextForDuplicateFinal;
 
         if (!shouldDeliverText) {
           log.info(`[DingTalk][deliver] 跳过发送：hasText=${hasText}, skipTextForDuplicateFinal=${skipTextForDuplicateFinal}`);

package/src/services/media.ts

@@ -7,7 +7,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import type { DingtalkConfig } from '../types/index.ts';
 import { DINGTALK_OAPI, getOapiAccessToken } from '../utils/index.ts';
-import { dingtalkOapiHttp } from '../utils/http-client.ts';
+import { dingtalkHttp, dingtalkOapiHttp } from '../utils/http-client.ts';
 
 // ============ 常量 ============
 

package/src/services/messaging.ts

@@ -591,9 +591,10 @@ export async function sendMediaToDingTalk(params: {
     });
   }
 
-  // 1. 先发送文本消息（如果有）
-  if (text?.trim()) {
-    log.info("先发送文本消息");
+  // 1. 先发送文本消息（如果有且不为空）
+  // 注意：只有在 text 有实际内容时才发送，避免发送空消息
+  if (text && text.trim().length > 0) {
+    log.info("先发送文本消息:", text);
     await sendProactive(config, targetParam, text, {
       msgType: "text",
       replyToId,
@@ -726,33 +727,28 @@ export async function sendMediaToDingTalk(params: {
       };
     }
 
-    // 对于音频、文件，发送包含下载链接的文本消息
+    // 对于音频、文件，发送真正的文件消息
     const fs = await import("fs");
     const stats = fs.statSync(mediaUrl);
-    const fileSizeMB = (stats.size / (1024 * 1024)).toFixed(2);
-
-    // 使用上传结果中的下载链接
-    const downloadUrl = uploadResult.downloadUrl;
-
-    // 根据媒体类型选择图标和描述
-    let icon = "📄";
-    let typeLabel = "文件";
-    if (mediaType === "voice") {
-      icon = "🎵";
-      typeLabel = "音频";
-    }
-
-    const message = `${icon} ${typeLabel}文件已上传\n\n文件: ${fileName}\n大小: ${fileSizeMB} MB\n\n下载链接: ${downloadUrl}`;
+    
+    // 获取文件扩展名作为 fileType
+    const fileType = ext || "file";
+    
+    // 构建文件信息
+    const fileInfo = {
+      fileName: fileName,
+      fileType: fileType,
+    };
 
-    const result = await sendProactive(config, targetParam, message, {
-      msgType: "text",
-      replyToId,
-    });
+    // 使用 sendFileProactive 发送文件消息
+    const { sendFileProactive } = await import("./media.ts");
+    await sendFileProactive(config, targetParam, fileInfo, uploadResult.mediaId, log);
 
-    // 确保返回值中有 processQueryKey，告诉 SDK 消息已发送成功
+    // 返回成功结果
     return {
-      ...result,
-      processQueryKey: result.processQueryKey || "media-message-sent",
+      ok: true,
+      usedAICard: false,
+      processQueryKey: "file-message-sent",
     };
   } catch (err: any) {
     log.error("发送媒体消息失败:", err.message);
@@ -916,21 +912,19 @@ async function sendProactiveInternal(
       ? `${DINGTALK_API}/v1.0/robot/oToMessages/batchSend`
       : `${DINGTALK_API}/v1.0/robot/groupMessages/send`;
 
-    // 构建消息体
+    // 使用 buildMsgPayload 构建消息体（支持所有消息类型）
+    const payload = buildMsgPayload(msgType, content, options.title);
+    if ("error" in payload) {
+      log.error("构建消息失败:", payload.error);
+      return { ok: false, error: payload.error, usedAICard: false };
+    }
+
     const body: any = {
       robotCode: config.clientId,
-      msgKey: msgType === "markdown" ? "sampleMarkdown" : "sampleText",
+      msgKey: payload.msgKey,
+      msgParam: JSON.stringify(payload.msgParam),
     };
 
-    if (msgType === "markdown") {
-      body.msgParam = JSON.stringify({
-        title: options.title || "Message",
-        text: content,
-      });
-    } else {
-      body.msgParam = JSON.stringify({ content });
-    }
-
     // ✅ 根据目标类型设置不同的参数
     if (isUser) {
       body.userIds = [targetId];