@dingtalk-real-ai/dingtalk-connector 0.8.12 → 0.8.13

package/docs/RELEASE_NOTES_V0.8.9.md

@@ -0,0 +1,81 @@
+# Release Notes - v0.8.9
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新带来**引用消息完整解析**、**macOS LaunchAgent 兼容性修复**和**多项稳定性改进**。消息处理层新增对引用消息（reply）的递归解析，支持提取引用中的文本、媒体附件和链接；修复了 macOS LaunchAgent 环境下因无效文件描述符导致 WebSocket 连接失败的问题；同时修复了 AI Card 流式关闭的竞争条件、FormData CJS 互操作问题，并锁定 axios 版本以提升依赖稳定性。
+
+This release introduces **quoted message parsing**, **macOS LaunchAgent compatibility**, and **multiple stability improvements**. The message handler now recursively parses quoted (reply) messages, extracting text, media attachments, and URLs. A fix for invalid file descriptors (EBADF) on macOS LaunchAgent environments prevents WebSocket connection failures. Additionally, the AI Card streaming close race condition is fixed, FormData CJS interop issues are resolved, and axios is pinned to v1.6.0 for dependency stability.
+
+## ✨ 功能与体验改进 / Features & Improvements
+
+- **引用消息完整解析 / Quoted message full parsing**  
+  新增 `extractQuotedMsgText` 递归解析引用消息（最多 3 层嵌套），支持 text、richText、picture、video、audio、file、markdown、interactiveCard 等消息类型。引用消息中的媒体附件（图片/视频/音频/文件）会被自动提取并传递给下游处理。引用了含链接的文本消息时，链接会被提取用于 URL 路由（如 alidocs 文档链接）。  
+  Added `extractQuotedMsgText` for recursive quoted message parsing (up to 3 levels), supporting text, richText, picture, video, audio, file, markdown, and interactiveCard message types. Media attachments in quoted messages are automatically extracted and passed downstream. URLs from quoted text messages are extracted for URL routing (e.g., alidocs document links).
+
+- **新增配置项 / New configuration options**  
+  `configSchema` 新增 `asyncMode`、`ackText`、`endpoint`、`debug` 四个配置字段，为异步消息处理和自定义端点提供灵活配置能力。  
+  Added `asyncMode`, `ackText`, `endpoint`, `debug` to `configSchema`, enabling flexible configuration for async message processing and custom endpoints.
+
+- **普通消息本地图片后处理 / Local image post-processing for normal messages**  
+  `sendNormalToUser` 和 `sendNormalToGroup` 新增本地图片上传后处理，发送普通消息时自动将 Markdown 中的本地图片路径上传到钉钉并替换为 media_id，与 AI Card 消息行为保持一致。  
+  Added local image upload post-processing to `sendNormalToUser` and `sendNormalToGroup`, automatically uploading local image paths in Markdown to DingTalk and replacing them with media_id, consistent with AI Card message behavior.
+
+## 🐛 修复 / Fixes
+
+- **macOS LaunchAgent 环境 WebSocket 连接失败 / WebSocket connection failure on macOS LaunchAgent**  
+  修复 macOS LaunchAgent/daemon 环境下，进程启动时 stdin/stdout/stderr（fd 0/1/2）无效（EBADF），导致 Node.js 创建 TCP 连接时出现 EBADF 错误。启动前检测并将无效 fd 重定向到 `/dev/null`。  
+  Fixed EBADF errors when creating TCP connections on macOS LaunchAgent/daemon environments where stdin/stdout/stderr (fd 0/1/2) are invalid at process startup. Invalid file descriptors are now detected and redirected to `/dev/null`.
+
+- **AI Card 流式关闭竞争条件 / AI Card streaming close race condition**  
+  修复 `closeStreaming` 可能被 `onIdle` 和 `onError` 同时触发时的竞争条件。现在在函数开头立即捕获并清空 `currentCardTarget`（snapshot 模式），防止并发调用导致 `finishAICard` 收到 null 参数而崩溃。  
+  Fixed a race condition where `closeStreaming` could be triggered simultaneously by `onIdle` and `onError`. Now captures and clears `currentCardTarget` at function entry (snapshot pattern), preventing concurrent calls from passing null to `finishAICard`.
+
+- **FormData CJS 互操作问题 / FormData CJS interop issue**  
+  将 `form-data` 从动态 `import()` 改为静态 `import`，修复 jiti/ESM 环境下动态导入 CJS 模块时 `.default` 偶发为 `undefined` 导致 `Cannot read properties of undefined (reading 'registry')` 错误的问题。  
+  Changed `form-data` from dynamic `import()` to static `import`, fixing intermittent `Cannot read properties of undefined (reading 'registry')` errors caused by `.default` being `undefined` when dynamically importing CJS modules in jiti/ESM environments.
+
+- **纯文本图片路径误转换 / Bare image path false conversion**  
+  禁用纯文本中本地图片路径的自动转换为图片语法的行为。此前纯文本中出现的本地路径（如 `/path/to/image.png`）会被自动包裹为 `![](mediaId)`，影响用户只想展示路径文本的场景。  
+  Disabled automatic conversion of bare local image paths in plain text to image syntax. Previously, local paths like `/path/to/image.png` in plain text were automatically wrapped as `![](mediaId)`, which was undesirable when users intended to display the path as text.
+
+## 🔧 内部改进 / Internal Improvements
+
+- **Zod Schema 拆分兼容 Web UI / Zod Schema split for Web UI compatibility**  
+  将 `DingtalkConfigSchema` 拆分为 `DingtalkConfigBaseSchema`（纯 ZodObject）和带 `superRefine` 的完整 Schema，解决 `superRefine` 将 Schema 转为 `ZodEffects` 后无法用于 `buildChannelConfigSchema` 生成 JSON Schema 的问题。  
+  Split `DingtalkConfigSchema` into `DingtalkConfigBaseSchema` (pure ZodObject) and the full schema with `superRefine`, fixing incompatibility with `buildChannelConfigSchema` JSON Schema generation.
+
+- **configSchema 类型简化 / configSchema type simplification**  
+  将 `clientId`、`clientSecret`、`allowFrom`、`groupAllowFrom` 等字段的 JSON Schema 从 `oneOf` 联合类型简化为单一 `string` 类型，移除不再需要的 `secretInputJsonSchema`，降低配置复杂度。  
+  Simplified JSON Schema for `clientId`, `clientSecret`, `allowFrom`, `groupAllowFrom` from `oneOf` union types to single `string` type, removing the no-longer-needed `secretInputJsonSchema`.
+
+- **reply-dispatcher logger 统一 / reply-dispatcher logger unification**  
+  将 `reply-dispatcher.ts` 中手动构建的 log 对象替换为 `createLoggerFromConfig`，与项目其他模块的日志规范保持一致。  
+  Replaced manually constructed log object in `reply-dispatcher.ts` with `createLoggerFromConfig`, aligning with the project's logging conventions.
+
+- **锁定 axios 版本 / Pin axios version**  
+  将 `axios` 依赖从 `^1.6.0` 锁定为 `1.6.0`，避免自动升级引入不兼容变更。  
+  Pinned `axios` dependency from `^1.6.0` to `1.6.0` to prevent automatic upgrades from introducing incompatible changes.
+
+## 📥 安装升级 / 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
+```
+
+## 🔗 相关链接 / 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-03-31  
+**版本号 / Version**：v0.8.9  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_v0.7.0.md

@@ -0,0 +1,142 @@
+# Release Notes - v0.7.0
+
+## 🎉 新版本亮点 / Highlights
+
+本次更新带来了丰富的富媒体和文档处理能力，让 AI 助手能够更好地理解和处理各种类型的内容。新增了图片识别、文件解析、钉钉文档操作和多 Agent 路由等核心功能。
+
+This update brings rich media and document processing capabilities, enabling AI assistants to better understand and process various types of content. New core features include image recognition, file parsing, DingTalk document operations, and multi-Agent routing.
+
+## ✨ 新增功能 / Added Features
+
+### 富媒体接收支持 / Rich Media Reception Support
+- ✅ **JPEG 图片消息** - 支持接收钉钉中直接发送的 JPEG 图片，自动下载到 `~/.openclaw/workspace/media/inbound/` 目录  
+  **JPEG Image Messages** - Support receiving JPEG images sent directly in DingTalk, automatically downloaded to `~/.openclaw/workspace/media/inbound/` directory
+- ✅ **PNG 图片（富文本）** - 支持接收富文本消息中包含的 PNG 图片，自动提取 URL 和 downloadCode 并下载  
+  **PNG Images (Rich Text)** - Support receiving PNG images contained in rich text messages, automatically extract URL and downloadCode and download
+- ✅ **视觉模型集成** - 下载的图片自动传递给视觉模型，AI 可以识别和分析图片内容  
+  **Vision Model Integration** - Downloaded images are automatically passed to vision models, AI can recognize and analyze image content
+- ✅ **媒体文件管理** - 统一的文件命名格式 `openclaw-media-{timestamp}.{ext}`，便于管理和追踪  
+  **Media File Management** - Unified file naming format `openclaw-media-{timestamp}.{ext}` for easy management and tracking
+
+### 文件附件提取 / File Attachment Extraction
+- ✅ **Word 文档解析** - 支持解析 `.docx` 文件，通过 `mammoth` 库提取文本内容并注入到 AI 上下文  
+  **Word Document Parsing** - Support parsing `.docx` files, extract text content via `mammoth` library and inject into AI context
+- ✅ **PDF 文档解析** - 支持解析 `.pdf` 文件，通过 `pdf-parse` 库提取文本内容并注入到 AI 上下文  
+  **PDF Document Parsing** - Support parsing `.pdf` files, extract text content via `pdf-parse` library and inject into AI context
+- ✅ **纯文本文件** - 支持读取 `.txt`、`.md`、`.json` 等纯文本文件，内容直接注入到消息中  
+  **Plain Text Files** - Support reading plain text files (`.txt`, `.md`, `.json`, etc.), content directly injected into messages
+- ✅ **二进制文件处理** - 支持处理 `.xlsx`、`.pptx`、`.zip` 等二进制文件，文件保存到磁盘并在消息中报告路径  
+  **Binary File Processing** - Support processing binary files (`.xlsx`, `.pptx`, `.zip`, etc.), files saved to disk and paths reported in messages
+
+### 钉钉文档 API / DingTalk Document API
+- ✅ **创建文档** - `docs.create()` - 在指定空间中创建新的钉钉文档  
+  **Create Document** - `docs.create()` - Create new DingTalk documents in specified spaces
+- ✅ **追加内容** - `docs.append()` - 在现有文档上追加 Markdown 内容  
+  **Append Content** - `docs.append()` - Append Markdown content to existing documents
+- ✅ **搜索文档** - `docs.search()` - 根据关键词搜索钉钉文档  
+  **Search Documents** - `docs.search()` - Search DingTalk documents by keywords
+- ✅ **列举文档** - `docs.list()` - 列举指定空间下的所有文档  
+  **List Documents** - `docs.list()` - List all documents under specified spaces
+- ⚠️ **读取文档** - `docs.read()` - 当前不可用（见已知问题）  
+  **Read Document** - `docs.read()` - Currently unavailable (see Known Issues)
+
+### 多 Agent 路由支持 / Multi-Agent Routing Support
+- ✅ **多 Agent 会话隔离** - 支持一个连接器实例同时连接多个 Agent  
+  **Multi-Agent Session Isolation** - Support one connector instance connecting to multiple Agents simultaneously
+- ✅ **多机器人绑定** - 支持多个钉钉机器人分别绑定到不同的 Agent，实现角色分工和专业化服务  
+  **Multi-Bot Binding** - Support multiple DingTalk bots binding to different Agents, enabling role division and specialized services
+- ✅ **独立会话空间** - 每个 Agent 拥有独立的会话上下文，互不干扰  
+  **Independent Session Space** - Each Agent has an independent session context without interference
+- ✅ **灵活配置** - 通过 `accounts` 和 `bindings` 配置多个机器人，提供详细的配置示例和说明  
+  **Flexible Configuration** - Configure multiple bots via `accounts` and `bindings`, with detailed configuration examples and instructions
+- ✅ **向后兼容** - 单 Agent 场景下功能完全兼容，无需额外配置  
+  **Backward Compatible** - Fully compatible with single Agent scenarios, no additional configuration required
+
+## 🐛 修复 / Fixes
+
+- **语音消息播放异常修复** - 修复机器人发送语音消息播放异常问题，音频进度和播放功能现已正常工作  
+  **Voice Message Playback Fix** - Fixed bot voice message playback issues, audio progress and playback functionality now work correctly
+
+## 🔧 改进 / Improvements
+
+- **媒体文件处理优化** - 优化了媒体文件下载和存储机制，提升处理效率  
+  **Media File Processing Optimization** - Optimized media file download and storage mechanism, improved processing efficiency
+- **文件附件流程改进** - 改进了文件附件处理流程，支持更多文件类型，错误处理更完善  
+  **File Attachment Process Improvement** - Improved file attachment processing flow, supporting more file types with better error handling
+- **Markdown 表格转换** - 自动将 Markdown 表格转换为钉钉支持的文本格式，提升消息可读性  
+  **Markdown Table Conversion** - Automatically convert Markdown tables to DingTalk-supported text format for better message readability
+- **日志增强** - 增强了错误处理和日志输出，便于问题排查和调试  
+  **Log Enhancement** - Enhanced error handling and log output for easier troubleshooting and debugging
+
+## 📦 依赖更新 / Dependency Updates
+
+- 新增 `mammoth@^1.8.0` - Word 文档（.docx）解析库  
+  Added `mammoth@^1.8.0` - Word document (.docx) parsing library
+- 新增 `pdf-parse@^1.1.1` - PDF 文档解析库  
+  Added `pdf-parse@^1.1.1` - PDF document parsing library
+
+## ⚠️ 已知问题 / Known Issues
+
+### 1. 钉钉文档读取功能不可用 / DingTalk Document Reading Unavailable
+
+**问题描述 / Issue Description**：`docs.read()` API 当前无法正常工作  
+`docs.read()` API is currently not working properly
+
+**原因 / Cause**：MCP（Model Context Protocol）中未提供读取文档的 tool，虽然代码层面实现正常，但缺少底层支持  
+MCP (Model Context Protocol) does not provide the tool for reading documents. While the implementation is correct at the code level, underlying support is missing
+
+**影响范围 / Impact**：仅影响文档读取功能，其他文档操作（创建、追加、搜索、列举）均正常  
+Only affects document reading functionality, other document operations (create, append, search, list) work normally
+
+**解决方案 / Solution**：等待 MCP 提供相应的 tool 支持，或使用其他文档操作 API 作为替代方案  
+Wait for MCP to provide corresponding tool support, or use other document operation APIs as alternatives
+
+**状态 / Status**：已记录，等待上游支持  
+Recorded, waiting for upstream support
+
+## 📚 文档更新 / Documentation Updates
+
+- ✅ 更新 README.md，添加新功能使用说明  
+  Updated README.md, added usage instructions for new features
+- ✅ 新增"富媒体接收"章节，说明图片消息处理方式  
+  Added "Rich Media Reception" section, explaining image message processing
+- ✅ 新增"文件附件提取"章节，列出支持的文件类型和处理方式  
+  Added "File Attachment Extraction" section, listing supported file types and processing methods
+- ✅ 新增"钉钉文档 API"章节，提供 API 使用示例  
+  Added "DingTalk Document API" section, providing API usage examples
+- ✅ 新增"多 Agent 路由支持"章节，说明多 Agent 会话隔离功能  
+  Added "Multi-Agent Routing Support" section, explaining multi-Agent session isolation functionality
+- ✅ 新增"多 Agent 配置"章节，提供详细的配置示例和说明（`accounts` 和 `bindings` 配置）  
+  Added "Multi-Agent Configuration" section with detailed configuration examples and instructions (`accounts` and `bindings` configuration)
+- ✅ 补充常见问题解答，包括新功能的故障排查  
+  Added FAQ section, including troubleshooting for new features
+
+## 🔗 相关链接 / 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)
+
+## 📥 安装升级 / 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
+```
+
+## 🙏 致谢 / Acknowledgments
+
+感谢所有贡献者和用户的支持与反馈！  
+Thanks to all contributors and users for their support and feedback!
+
+---
+
+**发布日期 / Release Date**：2026-03-05  
+**版本号 / Version**：v0.7.0  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/docs/RELEASE_NOTES_v0.7.1.md

@@ -0,0 +1,74 @@
+# Release Notes - v0.7.1
+
+## 🐛 修复版本 / Bug Fix Release
+
+本次更新修复了 stream 模式下的关键问题，确保 Agent 路由功能正常工作。
+
+This update fixes critical issues in stream mode to ensure Agent routing functionality works correctly.
+
+## 🐛 修复 / Fixes
+
+### 1. Stream 模式 Session 路由失败问题 / Stream Mode Session Routing Failure
+
+**问题描述 / Issue Description**：stream 模式下 model 参数错误导致 session 路由失败  
+Incorrect model parameter in stream mode caused session routing failures
+
+**修复内容 / Fix**：
+- 将 Gateway 请求中的 `model` 参数从 `'default'` 更正为 `'main'`  
+  Corrected `model` parameter in Gateway requests from `'default'` to `'main'`
+- 确保正确的 Agent 路由和会话管理  
+  Ensures proper Agent routing and session management
+
+**影响范围 / Impact**：影响所有使用 stream 模式的用户，修复后 Agent 路由将正常工作  
+Affects all users using stream mode. After the fix, Agent routing will work correctly.
+
+### 2. 多 Agent 路由问题修复 / Multi-Agent Routing Fix
+
+**问题描述 / Issue Description**：多个钉钉机器人绑定到不同 Agent 时路由异常
+Multiple DingTalk bots binding to different Agents failed to route correctly
+
+**修复内容 / Fix**：
+- 修复多 Agent 路由机制，确保多个钉钉机器人可以正确绑定到不同的 Agent  
+  Fixed multi-Agent routing mechanism, ensuring multiple DingTalk bots can correctly bind to different Agents
+- 改进会话隔离和路由逻辑  
+  Improved session isolation and routing logic
+
+**影响范围 / Impact**：影响使用多 Agent 配置的用户，修复后多机器人多 Agent 场景将正常工作  
+Affects users with multi-Agent configurations. After the fix, multi-bot multi-Agent scenarios will work correctly.
+
+## 🔧 改进 / Improvements
+
+- **异步模式优化** - 优化异步模式处理流程，改进错误处理和日志输出  
+  **Async Mode Optimization** - Optimized async mode processing flow, improved error handling and log output
+- **DM Policy 增强** - 增强 DM Policy 检查机制，支持白名单配置  
+  **DM Policy Enhancement** - Enhanced DM Policy check mechanism, supporting allowlist configuration
+
+## 📥 安装升级 / 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
+```
+
+## 🔗 相关链接 / 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)
+
+## 🙏 致谢 / Acknowledgments
+
+感谢所有贡献者和用户的支持与反馈！  
+Thanks to all contributors and users for their support and feedback!
+
+---
+
+**发布日期 / Release Date**：2026-03-05  
+**版本号 / Version**：v0.7.1  
+**兼容性 / Compatibility**：OpenClaw Gateway 0.4.0+

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "dingtalk-connector",
   "name": "DingTalk Channel",
-  "version": "0.8.12",
+  "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.12",
+  "version": "0.8.13",
   "description": "DingTalk (钉钉) channel connector — Stream mode with AI Card streaming",
   "main": "index.ts",
   "type": "module",
@@ -40,11 +40,22 @@
   },
   "homepage": "https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector#readme",
   "bugs": "https://github.com/DingTalk-Real-AI/dingtalk-openclaw-connector/issues",
+  "files": [
+    "index.ts",
+    "src/",
+    "docs/*.md",
+    "openclaw.plugin.json",
+    "tsconfig.json",
+    "LICENSE",
+    "README.md",
+    "README.en.md",
+    "CHANGELOG.md"
+  ],
   "publishConfig": {
     "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/channel.ts

@@ -162,10 +162,10 @@ export const dingtalkPlugin: ChannelPlugin<ResolvedDingtalkAccount> = {
       name: account.name,
       clientId: account.clientId,
     }),
-    resolveAllowFrom: ({ cfg, accountId }) => {
-      const account = resolveDingtalkAccount({ cfg, accountId });
-      return (account.config?.allowFrom ?? []).map((entry) => String(entry));
-    },
+    // 返回空列表，禁止框架层对发送者做全局过滤。
+    // 连接器内部（message-handler.ts）已按 dmPolicy/groupPolicy 各自独立检查，
+    // allowFrom 仅用于私聊，groupAllowFrom 仅用于群聊，不应被框架层全局应用。
+    resolveAllowFrom: () => [],
     formatAllowFrom: ({ allowFrom }) =>
       allowFrom
         .map((entry) => String(entry).trim())
@@ -289,8 +289,14 @@ export const dingtalkPlugin: ChannelPlugin<ResolvedDingtalkAccount> = {
     textChunkLimit: 2000,
     sendText: async ({ cfg, to, text, accountId, replyToId, threadId }) => {
       const account = resolveDingtalkAccount({ cfg, accountId });
+      // 使用已解析的凭据覆盖原始 config，防止 clientId/clientSecret 为 SecretInput 对象或 undefined
+      const resolvedConfig: DingtalkConfig = {
+        ...account.config,
+        ...(account.clientId != null ? { clientId: account.clientId } : {}),
+        ...(account.clientSecret != null ? { clientSecret: account.clientSecret } : {}),
+      };
       const result = await sendTextToDingTalk({
-        config: account.config,
+        config: resolvedConfig,
         target: to,
         text,
         replyToId,
@@ -303,6 +309,12 @@ export const dingtalkPlugin: ChannelPlugin<ResolvedDingtalkAccount> = {
     },
     sendMedia: async ({ cfg, to, text, mediaUrl, accountId, mediaLocalRoots, replyToId, threadId }) => {
       const account = resolveDingtalkAccount({ cfg, accountId });
+      // 使用已解析的凭据覆盖原始 config，防止 clientId/clientSecret 为 SecretInput 对象或 undefined
+      const resolvedConfig: DingtalkConfig = {
+        ...account.config,
+        ...(account.clientId != null ? { clientId: account.clientId } : {}),
+        ...(account.clientSecret != null ? { clientSecret: account.clientSecret } : {}),
+      };
       const logger = createLogger(account.config?.debug ?? false, 'DingTalk:SendMedia');
       
       logger.info('开始处理，参数:', JSON.stringify({
@@ -326,7 +338,7 @@ export const dingtalkPlugin: ChannelPlugin<ResolvedDingtalkAccount> = {
       }
 
       const result = await sendMediaToDingTalk({
-        config: account.config,
+        config: resolvedConfig,
         target: to,
         text,
         mediaUrl,

package/src/config/schema.ts

@@ -66,6 +66,8 @@ const DingtalkSharedConfigShape = {
   ackText: z.string().optional(),
   endpoint: z.string().optional(), // DWClient gateway endpoint
   debug: z.boolean().optional(), // DWClient debug mode
+  enableMediaUpload: z.boolean().optional(),
+  systemPrompt: z.string().optional(),
 };
 
 /**
@@ -93,8 +95,6 @@ export const DingtalkConfigBaseSchema = z
     // Top-level credentials (backward compatible for single-account mode)
     clientId: z.union([z.string(), z.number()]).optional(),
     clientSecret: buildSecretInputSchema().optional(),
-    enableMediaUpload: z.boolean().optional(),
-    systemPrompt: z.string().optional(),
     ...DingtalkSharedConfigShape,
     dmPolicy: DmPolicySchema.optional().default("open"),
     groupPolicy: GroupPolicySchema.optional().default("open"),

package/src/core/connection.ts

@@ -664,7 +664,7 @@ export async function monitorSingleAccount(
 
       // 处理 400 错误（请求参数错误）
       if (error.response?.status === 400 || error.message?.includes("status code 400") || error.message?.includes("400")) {
-        throw new Error(
+        reject(new Error(
           `[DingTalk][${accountId}] Bad Request (400):\n` +
             `  - clientId or clientSecret format is invalid\n` +
             `  - clientId: ${clientIdStr} (type: ${typeof account.clientId}, length: ${clientIdStr.length})\n` +
@@ -676,24 +676,27 @@ export async function monitorSingleAccount(
             `    4. Check if clientId starts with 'ding' prefix\n` +
             `  - Error details: ${error.message}\n` +
             `  - Response data: ${JSON.stringify(error.response?.data || {})}`,
-        );
+        ));
+        return;
       }
 
       // 处理 401 认证错误
       if (error.response?.status === 401 || error.message?.includes("401")) {
-        throw new Error(
+        reject(new Error(
           `[DingTalk][${accountId}] Authentication failed (401 Unauthorized):\n` +
             `  - Your clientId or clientSecret is invalid, expired, or revoked\n` +
             `  - clientId: ${clientIdStr.substring(0, 8)}...\n` +
             `  - Please verify your credentials at DingTalk Developer Console\n` +
             `  - Error details: ${error.message}`,
-        );
+        ));
+        return;
       }
 
       // 处理其他连接错误
-      throw new Error(
+      reject(new Error(
         `[DingTalk][${accountId}] Failed to connect to DingTalk Stream: ${error.message}`,
-      );
+      ));
+      return;
     }
 
     // Handle disconnection（已被自定义 close 监听器替代）

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,
@@ -857,20 +857,40 @@ async function parsePdfFile(filePath: string, log?: any): Promise<string | null>
   try {
     log?.info?.(`开始解析 PDF 文档: ${filePath}`);
 
-    let pdfParse: any;
+    let pdfParseV1: any;
+    let pdfParseV2: any;
     try {
-      pdfParse = (await import('pdf-parse')).default;
+      const mod = await import('pdf-parse');
+      if (mod.PDFParse) {
+        pdfParseV2 = mod.PDFParse; // v2.x API
+      } else if (mod.default) {
+        pdfParseV1 = mod.default; // v1.x API
+      } else {
+        throw new Error('pdf-parse module format not recognized');
+      }
     } catch {
       log?.warn?.('pdf-parse 库未安装，无法解析 .pdf 文件。请运行: npm install pdf-parse');
       return null;
     }
 
     const buffer = fs.readFileSync(filePath);
-    const data = await pdfParse(buffer);
-    const text = data.text.trim();
-    
+    let text: string;
+    let numPages: number | undefined;
+
+    if (pdfParseV2) {
+      const parser = new pdfParseV2({ data: buffer });
+      const result = await parser.getText();
+      text = (result.text ?? '').trim();
+      numPages = result.total;
+      parser.destroy?.();
+    } else {
+      const data = await pdfParseV1(buffer);
+      text = (data.text ?? '').trim();
+      numPages = data.numpages;
+    }
+
     if (text) {
-      log?.info?.(`PDF 文档解析成功: ${filePath}, 文本长度=${text.length}, 页数=${data.numpages}`);
+      log?.info?.(`PDF 文档解析成功: ${filePath}, 文本长度=${text.length}, 页数=${numPages}`);
       return text;
     } else {
       log?.warn?.(`PDF 文档解析结果为空: ${filePath}`);
@@ -1493,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,
@@ -607,7 +607,8 @@ export function createDingtalkReplyDispatcher(params: CreateDingtalkReplyDispatc
               // 安全检查：确保 code 存在且为字符串
               const errorCode = err.response?.data?.code;
               if (err.response?.status === 403 && typeof errorCode === 'string' && errorCode.includes('QpsLimit')) {
-                // QPS 限流，跳过本次更新
+                // QPS 限流，跳过本次更新；同步更新节流时间，防止立即重试再次触发限流
+                lastUpdateTime = now;
                 log.warn(`[DingTalk][AICard] QPS 限流，跳过本次更新`);
               } else {
                 log.error(`[DingTalk][onPartialReply] ❌ AI Card 更新失败：${err.message}`);

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,