@dingtalk-real-ai/dingtalk-connector 0.7.7 → 0.7.8

package/CHANGELOG.md

@@ -6,6 +6,22 @@
 This document records all significant changes. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and version numbers follow [Semantic Versioning](https://semver.org/).
 
+## [0.7.8] - 2026-03-13
+
+### 修复 / Fixes
+- 🐛 **AI 卡片模版与渲染优化** - 更新 AI 卡片模版 ID，使卡片样式与最新官方规范保持一致，并提升多终端展示效果  
+  **AI card template & rendering optimization** - Updated the AI card template ID to match the latest official standard and improved rendering across clients
+- 🐛 **Markdown 表格渲染修复** - 在发送到钉钉前自动为 Markdown 表格头部补充必要空行，避免因缺少空行导致表格被当作普通文本渲染  
+  **Markdown table rendering fix** - Automatically inserts required blank lines before Markdown table headers to prevent DingTalk from rendering tables as plain text
+- 🐛 **消息去重逻辑优化** - 将消息去重维度从「账号 + 消息 ID」简化为单一「消息 ID」，避免多账号场景下的重复处理或误判  
+  **Message de-duplication optimization** - Simplified de-duplication from `(accountId, messageId)` to `messageId` only, preventing duplicate handling or misjudgment in multi-account scenarios
+
+### 改进 / Improvements
+- ✅ **统一 Markdown 修正管道** - 对 AI 卡片流式内容、最终内容、普通 Markdown 消息及 `sampleMarkdown` 卡片文本统一应用 Markdown 修正规则，确保表格等格式在各入口行为一致  
+  **Unified Markdown normalization pipeline** - Applies the same Markdown normalization to streaming AI card content, final content, regular Markdown messages, and `sampleMarkdown` card text for consistent behavior
+- ✅ **AI 卡片状态内容一致性** - 在完成 AI 卡片时，对展示内容和写入 `cardParamMap.msgContent` 的内容使用同一份 Markdown 修正结果，确保用户看到的内容与内部状态一致  
+  **Consistent AI card status content** - Ensures the same normalized Markdown is used both for the visible content and `cardParamMap.msgContent` when finishing AI cards
+
 ## [0.7.7] - 2026-03-13
 
 ### 新增 / Added

package/docs/RELEASE_NOTES_V0.7.8.md

@@ -0,0 +1,101 @@
+# Release Notes - v0.7.8
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **AI 卡片模版更新与展示效果优化 / AI Card Template & Rendering Improvements**  
+  升级钉钉 AI 卡片模版 ID，使卡片样式与最新官方规范保持一致，并优化多终端的展示效果与兼容性。  
+  Updated the DingTalk AI card template ID to align with the latest official template standard, improving visual consistency and compatibility across different clients.
+
+- **Markdown 表格渲染修复与自动优化 / Markdown Table Rendering Fix & Auto-Adjustment**  
+  新增 Markdown 预处理逻辑，在发送到钉钉前自动为表格头部补充必要的空行，避免因缺少空行导致的表格无法正确渲染问题；支持缩进表格场景。  
+  Added a Markdown preprocessing step that automatically inserts a blank line before table headers when needed, ensuring DingTalk renders tables correctly, including indented table cases.
+
+- **统一的 Markdown 修正管道 / Unified Markdown Normalization Pipeline**  
+  对 AI 卡片流式更新、AI 卡片最终内容提交、普通 Markdown 消息发送以及卡片 `sampleMarkdown` 内容，统一通过同一套 Markdown 修正函数进行处理，确保所有下发到钉钉的文本在表格渲染等细节上行为一致。  
+  Unified the Markdown normalization logic used for streaming AI card updates, final AI card content, regular Markdown messages, and `sampleMarkdown` card payloads, ensuring consistent behavior of table rendering and formatting in DingTalk.
+
+- **AI 卡片状态信息更准确 / More Accurate AI Card Status Content**  
+  在完成 AI 卡片时，对用于展示的内容与写入 `cardParamMap` 中的 `msgContent` 同步应用 Markdown 修正逻辑，保证用户看到的内容与卡片内部状态字段保持完全一致。  
+  When finalizing AI cards, the same Markdown fixes are now applied both to the displayed content and the `msgContent` stored in `cardParamMap`, keeping the visible card and its internal state in sync.
+
+## 🐛 修复 / Fixes
+
+- **Markdown 表格无法正确显示的问题 / Incorrect Markdown Table Rendering**  
+  修复了部分场景下 Markdown 表格前缺少空行，导致钉钉不将其识别为表格而当作普通文本渲染的问题；现在会自动检测表头与分隔行模式并在需要时插入空行。  
+  Fixed an issue where missing blank lines before Markdown tables caused DingTalk to render them as plain text; the connector now detects table headers and divider lines and inserts a blank line when necessary.
+
+- **消息去重维度优化 / Message De-duplication Scope Optimization**  
+  优化消息去重逻辑，从「按账号+消息 ID」改为仅基于「消息 ID」维度标记与判断，避免在多账号场景中出现某些重复消息未被正确拦截或误判的情况。  
+  Improved the message de-duplication mechanism by switching from an account-scoped `(accountId, messageId)` key to a global `messageId` key, preventing edge cases where duplicate messages across accounts might not be handled correctly.
+
+## 📋 技术细节 / Technical Details
+
+### AI 卡片模版 & 内容处理 / AI Card Template & Content Handling
+
+- 更新 `AI_CARD_TEMPLATE_ID` 为新的模版 ID，以匹配最新的钉钉 AI 卡片样式规范。  
+- 新增 `ensureTableBlankLines(text: string)` 工具函数：  
+  - 将文本按行拆分，识别包含竖线的表格行与 `---` 分隔行。  
+  - 当前行看起来像表头、下一行是分隔行、且前一行既不是空行也不是表格行时，会在表头前插入一个空行。  
+  - 支持带缩进的表格写法，保持原有内容顺序与缩进风格不变。  
+- 在以下路径中统一使用 `ensureTableBlankLines`：  
+  - AI 卡片流式内容更新（`streamAICard`）中的 `content` 字段。  
+  - AI 卡片结束时（`finishAICard`）的最终内容与日志长度统计。  
+  - 普通 Markdown 消息发送（`sendMarkdownMessage`），在追加 `@user` 之前先做表格修正。  
+  - `buildMsgPayload` 中 `sampleMarkdown` 类型的 `text` 字段。  
+- 为单元测试导出 `__testables.ensureTableBlankLines`，便于在不依赖具体业务逻辑的情况下验证 Markdown 修正规则。
+
+### 消息去重逻辑 / Message De-duplication Logic
+
+- 去重检查由 `isMessageProcessed(accountId, messageId)` 简化为 `isMessageProcessed(messageId)`，对同一消息 ID 统一判重。  
+- 标记逻辑由 `markMessageProcessed(accountId, messageId)` 更新为 `markMessageProcessed(messageId)`，减少多账号场景下可能出现的重复处理路径。  
+- 保持原有日志信息与跳过处理分支不变，仅调整内部去重键值结构。
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+# 通过 npm 安装最新版本 / Install latest version via npm
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+
+# 或升级现有版本 / Or upgrade existing version
+openclaw plugins update dingtalk-connector
+
+# 通过 Git 安装 / Install via Git
+openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+```
+
+## ⚠️ 升级注意事项 / Upgrade Notes
+
+### 兼容性说明 / Compatibility Notes
+
+- **向下兼容 / Backward Compatible**：本次为小版本修复和体验优化更新，在保留 v0.7.x 既有行为的前提下增强了 Markdown 表格渲染与消息去重逻辑，对现有配置完全兼容。  
+- **Markdown 表格渲染更稳定 / More Robust Markdown Tables**：即便原始内容中未严格遵守表格前空行的写法，Connector 也会自动做最小化修正，以提高在钉钉中的可读性。  
+- **消息去重语义更清晰 / Clearer De-duplication Semantics**：以 `messageId` 为唯一维度进行去重，更贴合钉钉消息唯一标识的语义。
+
+### 验证步骤 / Verification Steps
+
+升级到此版本后，建议进行以下验证：
+
+1. **AI 卡片模版与渲染验证 / AI Card Template & Rendering Verification**  
+   - 触发一次典型的 AI 卡片对话，观察新模版下的卡片布局与字段展示是否符合预期。  
+   - 在含有多段文字与表格的回复中，确认卡片内 Markdown 表格渲染正常。  
+
+2. **Markdown 表格兼容性验证 / Markdown Table Compatibility Verification**  
+   - 通过机器人发送包含 Markdown 表格的消息（包含表头、分隔行与多列数据），且故意在表格前省略空行。  
+   - 在移动端及 PC 端查看，确认钉钉能够正确以表格形式渲染内容。  
+
+3. **消息去重行为验证 / Message De-duplication Behavior Verification**  
+   - 在相同会话中模拟重复推送同一个 `messageId` 的回调（或快速重复发送同一条消息）。  
+   - 确认日志中出现去重命中提示，并且业务处理逻辑只执行一次。
+
+## 🔗 相关链接 / Related Links
+
+- [完整变更日志 / Full Changelog](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/CHANGELOG.md)
+- [使用文档 / Documentation](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/blob/main/README.md)
+- [问题反馈 / Issue Feedback](https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues)
+
+---
+
+**发布日期 / Release Date**：2026-03-13  
+**版本号 / Version**：v0.7.8  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+
+

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.7.7",
+  "version": "0.7.8",
   "description": "DingTalk (钉钉) messaging channel via Stream mode with AI Card streaming",
   "author": "DingTalk Real Team",
   "channels": ["dingtalk-connector"],

package/package.json

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

package/plugin.ts

@@ -1103,7 +1103,7 @@ async function processFileMarkers(
 
 const DINGTALK_API = 'https://api.dingtalk.com';
 const DINGTALK_OAPI = 'https://oapi.dingtalk.com';
-const AI_CARD_TEMPLATE_ID = '382e4302-551d-4880-bf29-a30acfab2e71.schema';
+const AI_CARD_TEMPLATE_ID = '02fcf2f4-5e02-4a85-b672-46d1f715543e.schema';
 
 // flowStatus 值与 Python SDK AICardStatus 一致（cardParamMap 的值必须是字符串）
 const AICardStatus = {
@@ -1141,6 +1141,45 @@ async function createAICard(
   return createAICardForTarget(config, target, log);
 }
 
+/**
+ * 确保 Markdown 表格前有空行，否则钉钉无法正确渲染表格。
+ *
+ * 逐行向前看：当前行像表头（含 `|`）且下一行是分隔行时，
+ * 若前一行非空且非表格行，则在表头前插入空行。
+ * 支持缩进表格（行首有空白字符）。
+ */
+function ensureTableBlankLines(text: string): string {
+  const lines = text.split('\n');
+  const result: string[] = [];
+
+  // 匹配表格分隔行 (例如 | --- | --- | 或 --- | ---)
+  const tableDividerRegex = /^\s*\|?\s*:?-+:?\s*(\|?\s*:?-+:?\s*)+\|?\s*$/;
+  // 匹配包含竖线的表格行
+  const tableRowRegex = /^\s*\|?.*\|.*\|?\s*$/;
+
+  const isDivider = (line: string) => line.includes('|') && tableDividerRegex.test(line);
+
+  for (let i = 0; i < lines.length; i++) {
+    const currentLine = lines[i];
+    const nextLine = lines[i + 1] ?? '';
+
+    // 逻辑：
+    // 1. 当前行看起来像表头（包含 |）
+    // 2. 下一行是分隔行（---）
+    // 3. 前一行不是空行且不是表格行
+    if (
+      tableRowRegex.test(currentLine) &&
+      isDivider(nextLine) &&
+      i > 0 && lines[i - 1].trim() !== '' && !tableRowRegex.test(lines[i - 1])
+    ) {
+      result.push('');
+    }
+
+    result.push(currentLine);
+  }
+  return result.join('\n');
+}
+
 // 流式更新 AI Card 内容
 async function streamAICard(
   card: AICardInstance,
@@ -1177,11 +1216,12 @@ async function streamAICard(
   }
 
   // 调用 streaming API 更新内容
+  const fixedContent = ensureTableBlankLines(content);
   const body = {
     outTrackId: card.cardInstanceId,
     guid: `${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
     key: 'msgContent',
-    content: content,
+    content: fixedContent,
     isFull: true,  // 全量替换
     isFinalize: finished,
     isError: false,
@@ -1205,10 +1245,11 @@ async function finishAICard(
   content: string,
   log?: any,
 ): Promise<void> {
-  log?.info?.(`[DingTalk][AICard] 开始 finish，最终内容长度=${content.length}`);
+  const fixedContent = ensureTableBlankLines(content);
+  log?.info?.(`[DingTalk][AICard] 开始 finish，最终内容长度=${fixedContent.length}`);
 
   // 1. 先用最终内容关闭流式通道（isFinalize=true），确保卡片显示替换后的内容
-  await streamAICard(card, content, true, log);
+  await streamAICard(card, fixedContent, true, log);
 
   // 2. 更新卡片状态为 FINISHED
   const body = {
@@ -1216,7 +1257,7 @@ async function finishAICard(
     cardData: {
       cardParamMap: {
         flowStatus: AICardStatus.FINISHED,
-        msgContent: content,
+        msgContent: fixedContent,
         staticMsgContent: '',
         sys_full_json_obj: JSON.stringify({
           order: ['msgContent'],  // 只声明实际使用的字段，避免部分客户端显示空占位
@@ -1698,7 +1739,7 @@ async function sendMarkdownMessage(
   options: any = {},
 ): Promise<any> {
   const token = await getAccessToken(config);
-  let text = markdown;
+  let text = ensureTableBlankLines(markdown);
   if (options.atUserId) text = `${text} @${options.atUserId}`;
 
   const body: any = {
@@ -2235,7 +2276,7 @@ function buildMsgPayload(
         msgKey: 'sampleMarkdown',
         msgParam: {
           title: title || content.split('\n')[0].replace(/^[#*\s\->]+/, '').slice(0, 20) || 'Message',
-          text: content,
+          text: ensureTableBlankLines(content),
         },
       };
     case 'link':
@@ -3532,15 +3573,15 @@ const dingtalkPlugin = {
           ctx.log?.info?.(`[DingTalk] 已立即确认回调: messageId=${messageId}`);
         }
 
-        // 【消息去重】检查是否已处理过该消息（按账号维度隔离）
-        if (messageId && isMessageProcessed(account.accountId, messageId)) {
+        // 【消息去重】检查是否已处理过该消息
+        if (messageId && isMessageProcessed(messageId)) {
           ctx.log?.warn?.(`[DingTalk][${account.accountId}] 检测到重复消息，跳过处理: messageId=${messageId}`);
           return;
         }
 
-        // 标记消息为已处理（按账号维度隔离）
+        // 标记消息为已处理
         if (messageId) {
-          markMessageProcessed(account.accountId, messageId);
+          markMessageProcessed(messageId);
         }
 
         // 异步处理消息（不阻塞回调确认）
@@ -3939,6 +3980,8 @@ export {
 // ============ 测试辅助导出 ============
 // 仅用于单元测试，避免在业务代码中直接依赖内部实现细节
 export const __testables = {
+  // Markdown 修正
+  ensureTableBlankLines,
   // 会话 & 去重
   normalizeSlashCommand,
   buildSessionContext,