@dingtalk-real-ai/dingtalk-connector 0.8.13-beta.0 → 0.8.13

package/CHANGELOG.md

@@ -5,35 +5,41 @@ 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.13-beta.0] - 2026-04-06
+## [0.8.13] - 2026-04-08
 
 ### 修复 / Fixes
-- 🐛 **修复多账号场景下凭据未解析** - `sendText`/`sendMedia` 在多账号模式下 `clientId`/`clientSecret` 可能为 `SecretInput` 对象，导致 API 请求携带无效凭据。现已用 `resolveDingtalkAccount` 返回的已解析值覆盖原始 config  
-  **Fix unresolved credentials in sendText/sendMedia** - In multi-account mode, credentials could be `SecretInput` objects; now resolved values are used
+- 🐛 **修复文件发送 mediaId 格式不一致导致静默失败** - `sendFileProactive` 在不同调用点传入 `cleanMediaId`（不带 `@`）和 `mediaId`（带 `@`），经实测钉钉 API 统一要求带 `@` 前缀。同时修复 catch 块吞掉异常导致外层误报成功  
+  **Fix inconsistent mediaId format causing silent file send failure** - Unified to `@`-prefixed `mediaId`; fixed catch blocks swallowing errors
 
-- 🐛 **修复连接错误在 async 回调中无法传播** - `connection.ts` 错误处理使用 `throw` 抛出，但在 async 回调内无法被外层 Promise 捕获。改为 `reject(new Error(...))` 确保 400/401 等错误正确传播  
-  **Fix connection errors not propagating in async callback** - Changed `throw` to `reject()` inside async error handlers
+- 🐛 **修复多账号场景下凭据未解析** - `sendText`/`sendMedia` 在多账号模式下 `clientId`/`clientSecret` 可能为 `SecretInput` 对象，现已用已解析值覆盖  
+  **Fix unresolved credentials in multi-account mode** - Resolved values now override raw config
 
-- 🐛 **修复 QPS 限流后立即重试触发再次限流** - 收到 403 QpsLimit 后未更新 `lastUpdateTime`，导致节流检查立即放行。现已同步更新节流时间  
-  **Fix QPS rate limit immediate retry** - `lastUpdateTime` is now synced when skipping a QPS-limited update
+- 🐛 **修复连接错误在 async 回调中无法传播** - 改为 `reject(new Error(...))` 确保 400/401 等错误正确传播  
+  **Fix connection errors not propagating** - Changed `throw` to `reject()` inside async error handlers
 
-- 🐛 **修复 `resolveAllowFrom` 全局过滤误拦截群消息** - `allowFrom` 仅用于私聊白名单，群消息由 `groupAllowFrom` 在内部处理。将 `resolveAllowFrom` 改为返回空列表，禁用框架层全局过滤  
-  **Fix resolveAllowFrom global filter blocking group messages** - Returns `[]` to disable framework-level filtering; internal policy checks handle DM and group separately
+- 🐛 **修复 QPS 限流后立即重试** - 收到 403 QpsLimit 后同步更新 `lastUpdateTime`  
+  **Fix QPS rate limit immediate retry** - `lastUpdateTime` is now synced when skipping
+
+- 🐛 **修复 `resolveAllowFrom` 全局过滤误拦截群消息** - 返回空列表禁用框架层全局过滤，群消息由内部 `groupAllowFrom` 处理  
+  **Fix resolveAllowFrom blocking group messages** - Returns `[]` to disable framework-level filtering
 
 ### 新增 / Added
-- ✨ **消息路由支持 `group:`/`user:` 前缀** - `sendTextToDingTalk` 和 `sendMediaToDingTalk` 新增 `group:<id>` 和 `user:<id>` 格式解析，与 `gateway-methods.ts` 保持一致，兼容旧版裸 `cid` 前缀  
-  **Message routing supports `group:`/`user:` prefix targets** - Consistent with `gateway-methods.ts`, backward compatible with bare `cid` prefix
+- ✨ **消息路由支持 `group:`/`user:` 前缀** - `sendTextToDingTalk` 和 `sendMediaToDingTalk` 新增前缀格式解析，兼容旧版裸 `cid` 前缀  
+  **Message routing supports `group:`/`user:` prefix targets** - Backward compatible with bare `cid` prefix
 
 ### 改进 / Improvements
-- ✅ **兼容 pdf-parse v1 和 v2 API** - `parsePdfFile` 自动检测 pdf-parse 导出格式，v2.x 使用 `PDFParse` 类，v1.x 使用 `default` 函数  
-  **Support both pdf-parse v1 and v2 API** - Auto-detects export format: v2.x class API or v1.x function API
+- ✅ **兼容 pdf-parse v1/v2 API** - 自动检测导出格式，v2.x 使用 class API，v1.x 使用函数 API  
+  **Support both pdf-parse v1 and v2 API** - Auto-detects export format
+
+- ✅ **`enableMediaUpload`/`systemPrompt` 移至共享配置** - 支持多账号独立配置  
+  **Move `enableMediaUpload`/`systemPrompt` to shared config** - Per-account configurable
 
-- ✅ **`enableMediaUpload`/`systemPrompt` 移至共享配置** - 这两个字段现在支持多账号模式下每个账号独立配置  
-  **Move `enableMediaUpload`/`systemPrompt` to shared config** - Now configurable per-account in multi-account mode
+- ✅ **新增出站路由测试** - 覆盖 `group:`/`user:` 前缀解析和消息路由场景  
+  **Add outbound routing tests** - Covers prefix parsing and routing scenarios
 
 ### 文档 / Documentation
 - 📝 **优化 README 安装验证说明** - 移除版本号硬编码，新增插件未加载时的警示提示  
-  **Improve README plugin verification instructions** - Removed hardcoded version, added warning when plugin is not loaded
+  **Improve README plugin verification instructions** - Removed hardcoded version, added warning
 
 ## [0.8.12] - 2026-04-01
 

package/README.en.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img alt="DingTalk" src="docs/images/dingtalk.svg" width="72" height="72" />
+  <img alt="DingTalk" src="https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/dingtalk.svg" width="72" height="72" />
   <h1>Official DingTalk OpenClaw Connector</h1>
   <p>Connect DingTalk bots to OpenClaw Gateway with AI Card streaming and session management</p>
   
@@ -135,13 +135,13 @@ You should see output similar to `✓ DingTalk Channel (vX.X.X) - loaded`.
 1. Go to [DingTalk Open Platform](https://open-dev.dingtalk.com/)
 2. Click **"Application Development"**
 
-![Create Application](docs/images/image-1.png)
+![Create Application](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-1.png)
 
 #### 2.2 Add Bot Capability
 
 1. On the application details page, use the “one-click OpenClaw bot app” flow
 
-![Create OpenClaw bot app](docs/images/image-2.png)
+![Create OpenClaw bot app](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-2.png)
 
 #### 2.3 Get Credentials
 
@@ -149,9 +149,9 @@ You should see output similar to `✓ DingTalk Channel (vX.X.X) - loaded`.
 2. Copy your **AppKey** (Client ID)
 3. Copy your **AppSecret** (Client Secret)
 
-![Finish creation](docs/images/image-3.png)
+![Finish creation](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-3.png)
 
-![Get credentials](docs/images/image-4.png)
+![Get credentials](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-4.png)
 
 > ⚠️ **Important**: Client ID and Client Secret are your bot’s unique credentials. Store them safely.
 
@@ -281,6 +281,29 @@ Both session routing/message policy options (including `pmpolicy` and `groupPoli
 
 ---
 
+### Invalid Config: additional properties
+
+**Symptoms**:
+
+```
+Problem:
+  - channels.dingtalk-connector: invalid config: must NOT have additional properties
+```
+
+**Cause**: Your config file contains deprecated or renamed fields that are no longer recognized.
+
+**Solution**: Open `openclaw.config.yaml` and remove any unsupported fields under `channels.dingtalk-connector`. Known fields to remove:
+
+| Old Field | Notes |
+|-----------|-------|
+| `gatewayPassword` | Deprecated legacy field |
+| `gatewayToken` | Deprecated legacy field |
+| `dmHistoryLimit` | Removed in v0.8.9 (never implemented) |
+
+The error message will indicate the exact field name. Remove it and restart.
+
+---
+
 ### HTTP 401 Error
 
 **Symptoms**: Error message shows "401 Unauthorized"

package/README.md

@@ -1,5 +1,5 @@
 <div align="center">
-  <img alt="DingTalk" src="docs/images/dingtalk.svg" width="72" height="72" />
+  <img alt="DingTalk" src="https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/dingtalk.svg" width="72" height="72" />
   <h1>钉钉 OpenClaw 官方连接器</h1>
   <p>将钉钉机器人连接到 OpenClaw Gateway，支持 AI Card 流式响应和会话管理</p>
   
@@ -167,13 +167,13 @@ openclaw plugins list
 1. 访问 [钉钉开放平台](https://open-dev.dingtalk.com/)
 2. 点击 **"应用开发"**
 
-![创建应用](docs/images/image-1.png)
+![创建应用](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-1.png)
 
 #### 3.2 添加机器人能力
 
 1. 在应用详情页，点击 一键创建OpenClaw机器人应用
 
-![创建OpenClaw机器人应用](docs/images/image-2.png)
+![创建OpenClaw机器人应用](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-2.png)
 
 #### 3.3 获取凭证
 
@@ -181,9 +181,9 @@ openclaw plugins list
 2. 复制你的 **AppKey**（Client ID）
 3. 复制你的 **AppSecret**（Client Secret）
 
-![完成创建](docs/images/image-3.png)
+![完成创建](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-3.png)
 
-![获取凭证](docs/images/image-4.png)
+![获取凭证](https://raw.githubusercontent.com/DingTalk-Real-AI/dingtalk-openclaw-connector/main/docs/images/image-4.png)
 
 > ⚠️ **重要**：Client ID和 Client Secret是机器人的唯一凭证。请合理保存。
 
@@ -314,6 +314,29 @@ openclaw logs --follow
 
 ---
 
+### 配置字段不合法（additional properties）
+
+**症状**：
+
+```
+Problem:
+  - channels.dingtalk-connector: invalid config: must NOT have additional properties
+```
+
+**原因**：配置文件中包含已废弃或已重命名的字段，连接器不再识别。
+
+**解决方案**：打开 `openclaw.config.yaml`，删除 `channels.dingtalk-connector` 下不再支持的字段。已知需要删除的旧字段：
+
+| 旧字段 | 说明 |
+|--------|------|
+| `gatewayPassword` | 早期版本字段，已废弃 |
+| `gatewayToken` | 早期版本字段，已废弃 |
+| `dmHistoryLimit` | v0.8.9 移除（未实现） |
+
+错误信息会指出具体的字段名，删除后重启即可。
+
+---
+
 ### HTTP 401 错误
 
 **症状**：错误信息显示 "401 Unauthorized"

package/docs/RELEASE_NOTES_V0.8.13.md

@@ -0,0 +1,62 @@
+# Release Notes - v0.8.13
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新聚焦**媒体发送可靠性**和**多账号稳定性**：修复了文件发送时 mediaId 格式不一致导致静默失败的问题，修复了多账号凭据解析错误、连接错误无法传播、QPS 限流重试等多个关键 Bug，同时新增 `group:`/`user:` 前缀路由支持。
+
+This release focuses on **media sending reliability** and **multi-account stability**: fixes silent file sending failures caused by inconsistent mediaId format, resolves multi-account credential resolution errors, connection error propagation, QPS throttle retry issues, and adds `group:`/`user:` prefix routing support.
+
+## 🐛 修复 / Fixes
+
+- **修复文件发送时 mediaId 格式不一致导致静默失败 / Fix inconsistent mediaId format causing silent file send failure**  
+  `sendFileProactive` 在不同调用点传入了 `cleanMediaId`（不带 `@`）和 `mediaId`（带 `@`），经实测钉钉 API 统一要求带 `@` 前缀的 `mediaId`。同时修复了 `sendFileMessage`/`sendFileProactive` 的 catch 块吞掉异常导致外层误报成功的问题。  
+  `sendFileProactive` was called with `cleanMediaId` (without `@`) in some places and `mediaId` (with `@`) in others. Testing confirmed DingTalk API requires the `@`-prefixed `mediaId`. Also fixed catch blocks swallowing errors, causing false success reports.
+
+- **修复多账号场景下凭据未解析 / Fix unresolved credentials in multi-account mode**  
+  `sendText`/`sendMedia` 在多账号模式下 `clientId`/`clientSecret` 可能为 `SecretInput` 对象，导致 API 请求携带无效凭据。现已用 `resolveDingtalkAccount` 返回的已解析值覆盖。  
+  In multi-account mode, credentials could be `SecretInput` objects; now resolved values are used.
+
+- **修复连接错误在 async 回调中无法传播 / Fix connection errors not propagating**  
+  `connection.ts` 错误处理使用 `throw` 抛出，但在 async 回调内无法被外层 Promise 捕获。改为 `reject(new Error(...))` 确保 400/401 等错误正确传播。  
+  Changed `throw` to `reject()` inside async error handlers for proper error propagation.
+
+- **修复 QPS 限流后立即重试 / Fix QPS rate limit immediate retry**  
+  收到 403 QpsLimit 后未更新 `lastUpdateTime`，导致节流检查立即放行。现已同步更新。  
+  `lastUpdateTime` is now synced when skipping a QPS-limited update.
+
+- **修复 `resolveAllowFrom` 全局过滤误拦截群消息 / Fix resolveAllowFrom blocking group messages**  
+  `allowFrom` 仅用于私聊白名单，群消息由 `groupAllowFrom` 在内部处理。将 `resolveAllowFrom` 改为返回空列表，禁用框架层全局过滤。  
+  Returns `[]` to disable framework-level filtering; internal policy checks handle DM and group separately.
+
+## ✨ 功能改进 / Improvements
+
+- **消息路由支持 `group:`/`user:` 前缀 / Message routing supports `group:`/`user:` prefix targets**  
+  `sendTextToDingTalk` 和 `sendMediaToDingTalk` 新增 `group:<id>` 和 `user:<id>` 格式解析，兼容旧版裸 `cid` 前缀。  
+  Now supports `group:<id>` and `user:<id>` prefixed targets, backward compatible with bare `cid` prefix.
+
+- **兼容 pdf-parse v1/v2 API、共享配置字段扩展 / pdf-parse v1/v2 compatibility & shared config fields**  
+  `parsePdfFile` 自动检测 pdf-parse 导出格式；`enableMediaUpload`/`systemPrompt` 移至共享配置，支持多账号独立配置。  
+  Auto-detects pdf-parse export format; `enableMediaUpload`/`systemPrompt` now configurable per-account.
+
+- **新增出站路由测试 / Add outbound routing tests**  
+  新增 `outbound-routing.test.ts`，覆盖 `group:`/`user:` 前缀解析和消息路由场景。  
+  Added `outbound-routing.test.ts` covering prefix parsing and message routing scenarios.
+
+## 📥 安装升级 / Installation & Upgrade
+
+```bash
+openclaw plugins install @dingtalk-real-ai/dingtalk-connector
+openclaw plugins update dingtalk-connector
+openclaw plugins install https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector.git
+```
+
+## 🔗 相关链接 / 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)
+
+---
+
+**发布日期 / Release Date**：2026-04-08  
+**版本号 / Version**：v0.8.13  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.8.13-beta.0",
+  "version": "0.8.13",
   "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.13-beta.0",
+  "version": "0.8.13",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "index.ts",
   "type": "module",
@@ -55,7 +55,7 @@
     "access": "public"
   },
   "dependencies": {
-    "axios": "1.6.0",
+    "axios": "1.14.0",
     "dingtalk-stream": "2.1.4",
     "form-data": "^4.0.0",
     "zod": "^4.3.6"

package/src/core/message-handler.ts

@@ -49,7 +49,7 @@ import {
   processLocalImages, 
   processVideoMarkers, 
   processAudioMarkers, 
-  processFileMarkers
+  uploadAndReplaceFileMarkers
 } from "../services/media/index.ts";
 import { sendProactive, type AICardTarget } from "../services/messaging/index.ts";
 import { createAICardForTarget, streamAICard, type AICardInstance } from "../services/messaging/card.ts";
@@ -701,7 +701,7 @@ export async function downloadMediaByCode(
 
     const resp = await dingtalkHttp.post(
       `${DINGTALK_API}/v1.0/robot/messageFiles/download`,
-      { downloadCode, robotCode: config.clientId },
+      { downloadCode, robotCode: String(config.clientId) },
       {
         headers: { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' },
         timeout: 30_000,
@@ -733,7 +733,7 @@ export async function getFileDownloadUrl(
 
     const resp = await dingtalkHttp.post(
       `${DINGTALK_API}/v1.0/robot/messageFiles/download`,
-      { downloadCode, robotCode: config.clientId },
+      { downloadCode, robotCode: String(config.clientId) },
       {
         headers: { 'x-acs-dingtalk-access-token': token, 'Content-Type': 'application/json' },
         timeout: 30_000,
@@ -1513,7 +1513,7 @@ export async function handleDingTalkMessageInternal(params: HandleMessageParams)
             true,  // ✅ 使用主动 API 模式
             mediaTarget
           );
-          finalText = await processFileMarkers(
+          finalText = await uploadAndReplaceFileMarkers(
             finalText,
             '',
             config,

package/src/reply-dispatcher.ts

@@ -43,7 +43,7 @@ import {
   processLocalImages,
   processVideoMarkers,
   processAudioMarkers,
-  processFileMarkers,
+  uploadAndReplaceFileMarkers,
 } from "./services/media/index.ts";
 
 
@@ -314,7 +314,7 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
           true,  // ✅ 使用主动 API 模式
           target
         );
-        finalText = await processFileMarkers(
+        finalText = await uploadAndReplaceFileMarkers(
           finalText,
           '',
           account.config as DingtalkConfig,

package/src/services/media/file.ts

@@ -29,9 +29,14 @@ export async function parseDocumentFile(filePath: string, log?: any): Promise<st
 }
 
 /**
- * 提取文件标记并发送文件消息
+ * 提取文件标记，上传文件到钉钉，并用文本替换标记。
+ * 
+ * 注意：此函数只做「上传 + 文本替换」，不会发送独立的文件消息。
+ * 如果需要上传后再发送独立文件消息，请使用 media.ts 中的 processFileMarkers。
+ * 
+ * 调用方：reply-dispatcher.ts、message-handler.ts（通过 media/index.ts 导入）
  */
-export async function processFileMarkers(
+export async function uploadAndReplaceFileMarkers(
   content: string,
   sessionWebhook: string,
   config: DingtalkConfig,

package/src/services/media.ts

@@ -607,7 +607,12 @@ export interface FileInfo {
 }
 
 /**
- * 提取文件标记并发送文件消息
+ * 提取文件标记，上传文件到钉钉，并发送独立的文件消息（webhook 或 proactive API）。
+ * 
+ * 注意：此函数既做「上传」也做「发送」，是完整版的文件处理流程。
+ * 与 media/file.ts 中的 uploadAndReplaceFileMarkers 不同，后者只做上传+文本替换。
+ * 
+ * 调用方：messaging.ts（直接 import media.ts）
  */
 export async function processFileMarkers(
   content: string,
@@ -672,11 +677,11 @@ export async function processFileMarkers(
         continue;
       }
 
-      // 发送文件消息
+      // 发送文件消息（钉钉 API 统一要求带 @ 前缀的 mediaId）
       if (useProactiveApi && target) {
-        await sendFileProactive(config, target, fileInfo, uploadResult.cleanMediaId, log);
+        await sendFileProactive(config, target, fileInfo, uploadResult.mediaId, log);
       } else {
-        await sendFileMessage(config, sessionWebhook, fileInfo, uploadResult.downloadUrl, log);
+        await sendFileMessage(config, sessionWebhook, fileInfo, uploadResult.mediaId, log);
       }
       statusMessages.push(`✅ 文件已发送: ${fileName}`);
       log?.info?.(`${logPrefix} 文件处理完成: ${fileName}`);
@@ -771,7 +776,7 @@ export async function sendVideoProactive(
     };
 
     const body: any = {
-      robotCode: config.clientId,
+      robotCode: String(config.clientId),
       msgKey: 'sampleVideo',
       msgParam: JSON.stringify(msgParam),
     };
@@ -873,7 +878,7 @@ export async function sendAudioProactive(
     };
 
     const body: any = {
-      robotCode: config.clientId,
+      robotCode: String(config.clientId),
       msgKey: 'sampleAudio',
       msgParam: JSON.stringify(msgParam),
     };
@@ -942,6 +947,7 @@ async function sendFileMessage(
     }
   } catch (err: any) {
     log?.error?.(`发送文件消息异常: ${fileInfo.fileName}, 错误: ${err.message}`);
+    throw err;
   }
 }
 
@@ -960,14 +966,16 @@ export async function sendFileProactive(
     const { DINGTALK_API } = await import('../utils/index.ts');
 
     // 钉钉普通消息 API 的文件消息格式
+    const resolvedFileName = fileInfo.fileName || path.basename(fileInfo.path);
+    const resolvedFileType = fileInfo.fileType || resolvedFileName.split('.').pop() || 'file';
     const msgParam = {
       mediaId: mediaId,
-      fileName: fileInfo.fileName,
-      fileType: fileInfo.fileType,
+      fileName: resolvedFileName,
+      fileType: resolvedFileType,
     };
 
     const body: any = {
-      robotCode: config.clientId,
+      robotCode: String(config.clientId),
       msgKey: 'sampleFile',
       msgParam: JSON.stringify(msgParam),
     };
@@ -994,6 +1002,7 @@ export async function sendFileProactive(
     }
   } catch (err: any) {
     log?.error?.(`File[Proactive] 发送文件消息失败: ${fileInfo.fileName}, 错误: ${err.message}`);
+    throw err;
   }
 }
 
@@ -1109,9 +1118,7 @@ export async function processRawMediaPaths(
         };
         
         if (target) {
-          // 文件消息使用下载链接
-          // 文件消息使用媒体文件ID（cleanMediaId）通过主动API发送
-          await sendFileProactive(config, target, fileInfo, uploadResult.cleanMediaId, log);
+          await sendFileProactive(config, target, fileInfo, uploadResult.mediaId, log);
         }
         statusMessages.push(`✅ 文件已发送: ${fileName}`);
       }

package/src/services/messaging/card.ts

@@ -303,7 +303,7 @@ export async function finishAICard(
     `[DingTalk][AICard] 开始 finish，最终内容长度=${fixedContent.length}`,
   );
 
-  await streamAICard(card, fixedContent, true, log);
+  await streamAICard(card, fixedContent, true, config, log);
 
   const body = {
     outTrackId: card.cardInstanceId,

package/src/services/messaging.ts

@@ -229,7 +229,7 @@ export async function sendNormalToUser(
   try {
     const token = await getAccessToken(config);
     const body = {
-      robotCode: config.clientId,
+      robotCode: String(config.clientId),
       userIds: userIdArray,
       msgKey: payload.msgKey,
       msgParam: JSON.stringify(payload.msgParam),
@@ -306,7 +306,7 @@ export async function sendNormalToGroup(
   try {
     const token = await getAccessToken(config);
     const body = {
-      robotCode: config.clientId,
+      robotCode: String(config.clientId),
       openConversationId,
       msgKey: payload.msgKey,
       msgParam: JSON.stringify(payload.msgParam),
@@ -439,7 +439,7 @@ export async function sendAICardInternal(
     }
 
     // 7. 使用 finishAICard 设置内容
-    await finishAICard(card, processedContent, log);
+    await finishAICard(card, processedContent, config, log);
 
     log?.info?.(
       `AI Card 发送成功: ${targetDesc}, cardInstanceId=${card.cardInstanceId}`,
@@ -767,8 +767,9 @@ export async function sendMediaToDingTalk(params: {
     // 获取文件扩展名作为 fileType
     const fileType = ext || "file";
     
-    // 构建文件信息
+    // 构建文件信息（path 字段用于 sendFileProactive 中 fileName 的 fallback）
     const fileInfo = {
+      path: mediaUrl,
       fileName: fileName,
       fileType: fileType,
     };
@@ -904,7 +905,7 @@ async function sendProactiveInternal(
     try {
       const card = await createAICardForTarget(config, target, externalLog);
       if (card) {
-        await finishAICard(card, content, externalLog);
+        await finishAICard(card, content, config, externalLog);
         return {
           ok: true,
           cardInstanceId: card.cardInstanceId,
@@ -956,7 +957,7 @@ async function sendProactiveInternal(
     }
 
     const body: any = {
-      robotCode: config.clientId,
+      robotCode: String(config.clientId),
       msgKey: payload.msgKey,
       msgParam: JSON.stringify(payload.msgParam),
     };

package/src/utils/http-client.ts

@@ -2,6 +2,7 @@
  * HTTP 客户端配置模块
  * 
  * 提供统一的 axios 实例，用于钉钉 API 请求。
+ * 所有钉钉 API 调用必须使用此模块导出的实例，禁止直接使用 axios 或 fetch。
  * 
  * 使用方式：
  * ```typescript
@@ -13,7 +14,7 @@
 
 import axios, { type AxiosInstance } from 'axios';
 
-/** 钉钉专用 HTTP 客户端（30 秒超时） */
+/** 钉钉新版 API 专用 HTTP 客户端（30 秒超时，用于 api.dingtalk.com） */
 export const dingtalkHttp: AxiosInstance = axios.create({
   timeout: 30000,
   headers: {