@wenbin_wb/dsh-bridge 2.3.2 → 2.4.0

package/lib/feishu/node.js

@@ -2,6 +2,8 @@
 // 把飞书 OpenAPI / WebSocket 长连接入站事件解析后交给平台无关的
 // ConversationBridge 处理，出站通过 FeishuGateway 发送文本 / 卡片。
 
+import fs from 'node:fs'
+import path from 'node:path'
 import { ConversationBridge, conversationBridgeHelpers } from '../platform/conversation-bridge.js'
 
 function makePlatform(gateway) {
@@ -12,6 +14,9 @@ function makePlatform(gateway) {
     async sendText(peerId, text, opts = {}) {
       return gateway?.sendMarkdownCard(peerId, text, opts)
     },
+    async sendMediaFile(peerId, filePath, opts = {}) {
+      return gateway?.sendMediaFile(peerId, filePath, opts)
+    },
     async sendTyping() {},
     dispose() {},
   }
@@ -70,14 +75,10 @@ export class FeishuConversationNode extends ConversationBridge {
     this._inTurn = false
 
     // 订阅网关入站消息事件
-    this.ctx.on('feishu/message', (event) => {
-      void this._handleInbound(event)
-    })
+    this.ctx.on('feishu/message', (event) => this._handleInbound(event))
 
     // 订阅卡片交互事件（审批按钮点击）
-    this.ctx.on('feishu/action', (event) => {
-      void this._handleAction(event)
-    })
+    this.ctx.on('feishu/action', (event) => this._handleAction(event))
 
     // 监听轮次事件：turn/start 开启流式会话，turn/end 最终刷新并重置
     this.ctx.on('session/event', (session, event) => {
@@ -106,10 +107,26 @@ export class FeishuConversationNode extends ConversationBridge {
   }
 
   async _handleInbound(event) {
-    const { peerId, senderId, isGroup, text } = event
+    const { peerId, senderId, isGroup, text, messageId, messageType, contentObj } = event
     this._lastPeer = { peerId, senderId, isGroup }
 
-    this.logger.debug?.(`[dsh-bridge feishu] handling inbound message from ${peerId} (group=${isGroup}): ${text}`)
+    let mediaFiles = []
+    if (messageType && messageType !== 'text') {
+      mediaFiles = await this._processMedia(messageId, messageType, contentObj, this.config.cwd)
+    }
+
+    if (!text && mediaFiles.length === 0) {
+      this.logger.debug?.(`[dsh-bridge feishu] ignore empty message from ${peerId}`)
+      return
+    }
+
+    let fullText = text || ''
+    if (mediaFiles.length > 0) {
+      const mediaDesc = mediaFiles.map((f) => `[文件: ${f.path}]`).join('\n')
+      fullText = fullText ? `${fullText}\n\n${mediaDesc}` : mediaDesc
+    }
+
+    this.logger.debug?.(`[dsh-bridge feishu] handling inbound message from ${peerId} (group=${isGroup}): ${fullText}`)
 
     // 如果还没有活动会话，且是首条消息，自动尝试选择最新已有会话
     if (!this.activeSessionId) {
@@ -117,14 +134,42 @@ export class FeishuConversationNode extends ConversationBridge {
     }
 
     // 转交通用 ConversationBridge 路由
-    return super.handleInbound({
+    return this.handleInbound({
       senderId: isGroup ? peerId : senderId,
       peerId,
       isGroup,
-      text,
+      text: fullText,
     })
   }
 
+  async _processMedia(messageId, messageType, contentObj = {}, sessionCwd) {
+    if (!messageId || !messageType) return []
+    const mediaDir = path.join(sessionCwd || this.config.cwd || process.cwd(), '.feishu-media')
+    try { await fs.promises.mkdir(mediaDir, { recursive: true }) } catch {}
+
+    const downloaded = []
+    const fileKey = contentObj.image_key || contentObj.file_key
+    const fileName = contentObj.file_name
+
+    if (fileKey) {
+      try {
+        const type = messageType === 'image' ? 'image' : 'file'
+        const buf = await this.gateway.downloadMessageResource({ messageId, fileKey, type })
+        if (buf && buf.length > 0) {
+          const ext = fileName ? path.extname(fileName) : (type === 'image' ? '.png' : '.bin')
+          const safeName = fileName ? path.basename(fileName) : `feishu_${Date.now()}_${Math.random().toString(36).slice(2, 8)}${ext}`
+          const filePath = path.join(mediaDir, safeName)
+          await fs.promises.writeFile(filePath, buf)
+          downloaded.push({ filename: safeName, path: filePath, size: buf.length })
+          this.logger.info?.(`[dsh-bridge feishu] downloaded media ${safeName} (${buf.length} bytes)`)
+        }
+      } catch (err) {
+        this.logger.warn?.(`[dsh-bridge feishu] download media failed: ${err.message}`)
+      }
+    }
+    return downloaded
+  }
+
   async _handleAction(event) {
     const { operatorId, value } = event
     const approvalId = Number(value.approvalId)

package/lib/index.js

@@ -21,6 +21,7 @@ import { PlatformManager } from './platform/manager.js';
 import { WechatService } from './wechat/index.js';
 import { QqService } from './qq/index.js';
 import { FeishuService } from './feishu/index.js';
+import { TelegramService } from './telegram/index.js';
 
 const name = 'dsh-bridge';
 // 微信 Bot 会话桥依赖 DSH 提供的会话/agent/审批/工作区/持久化服务，需显式 inject
@@ -569,6 +570,19 @@ function apply(ctx, config = {}) {
   });
   platformManager.register(feishu);
 
+  // Telegram Bot（官方 Long Polling + 代理支持）—— 作为 Platform 子类注册进平台管理器
+  const telegram = new TelegramService({
+    ctx,
+    logger,
+    config: config.telegram ?? {},
+    onPersist: async (patch) => {
+      const stored = await loadConfig();
+      stored.telegram = { ...(stored.telegram ?? {}), ...patch };
+      await saveConfig(stored);
+    },
+  });
+  platformManager.register(telegram);
+
   // 启动时读取已保存的微信 Bot 配置（凭证 + 白名单 + 活动会话）
   loadConfig().then(async (stored) => {
     if (stored?.wechat) {
@@ -681,11 +695,50 @@ function apply(ctx, config = {}) {
     }
   }).catch(() => {});
 
+  // 启动时读取已保存的 Telegram Bot 配置（凭证 + 代理 + 白名单 + 活动会话）
+  loadConfig().then(async (stored) => {
+    if (stored?.telegram) {
+      const cfg = stored.telegram;
+      telegram.node.config.allowFrom = Array.isArray(cfg.allowFrom) ? cfg.allowFrom : [];
+      if (cfg.digestIntervalSec != null) telegram.node.config.digestIntervalSec = Number(cfg.digestIntervalSec);
+      if (cfg.approvalTimeoutSec != null) telegram.node.config.approvalTimeoutSec = Number(cfg.approvalTimeoutSec);
+      if (cfg.maxMessageChars != null) telegram.node.config.maxMessageChars = Number(cfg.maxMessageChars);
+      if (cfg.sendChunkDelayMs != null) telegram.node.config.sendChunkDelayMs = Number(cfg.sendChunkDelayMs);
+
+      telegram.node._restoringConfig = (async () => {
+        try {
+          if (cfg.activeSessionId) {
+            telegram.node.activeSessionId = cfg.activeSessionId;
+            logger.info('dsh-bridge: restored telegram active session: %s', cfg.activeSessionId);
+          } else {
+            await telegram.node._pickDefaultSession().catch(() => {});
+          }
+        } finally {
+          telegram.node._configRestored = true;
+        }
+      })();
+
+      await telegram.node._restoringConfig;
+
+      if (cfg.botToken) {
+        telegram.gateway.setCredentials({
+          botToken: cfg.botToken,
+          proxy: cfg.proxy || '',
+        });
+        logger.info('dsh-bridge: loaded saved telegram bot config, starting gateway');
+        await telegram.start().catch((err) => {
+          logger.error('dsh-bridge: telegram auto-start failed: %s', err?.message ?? err);
+        });
+      }
+    }
+  }).catch(() => {});
+
   const disposeRpc = installBridgeRpc(ctx, {
     service,
     wechat,
     qq,
     feishu,
+    telegram,
     platformManager,
     logger,
     saveCustomTunnelConfig: async (serverUrl, accessToken) => {
@@ -705,9 +758,11 @@ function apply(ctx, config = {}) {
     try { disposeRpc(); } catch {}
     await wechat.destroy();
     await qq.destroy();
+    await feishu.destroy();
+    await telegram.destroy();
     platformManager.dispose();
     await service.dispose();
-  }, 'dsh-bridge: stop wechat, qq, proxy and tunnels');
+  }, 'dsh-bridge: stop wechat, qq, feishu, telegram, proxy and tunnels');
 }
 
 export { name, inject, apply };

package/lib/platform/base.js

@@ -140,4 +140,17 @@ export class Platform {
       this.logger?.warn?.(`[dsh-bridge ${this.id}] persist failed: %s`, err?.message ?? err)
     }
   }
+
+  dispose() {
+    for (const d of this.disposers) {
+      try { d() } catch {}
+    }
+    this.disposers = []
+    this.bridge?.dispose?.()
+    this.bridge = null
+  }
+
+  async destroy() {
+    this.dispose()
+  }
 }

package/lib/platform/conversation-bridge.js

@@ -582,12 +582,13 @@ export class ConversationBridge {
     }
     const onEvent = (session, event) => {
       if (session.id !== this.activeSessionId) return
-      const state = digestState.get(session.id) ?? { startedTurns: new Set() }
+      const state = digestState.get(session.id) ?? { startedTurns: new Set(), createdFiles: new Set() }
       digestState.set(session.id, state)
 
       if (event.type === 'turn/start') {
-        const turn = event.data.turn
-        if (!state.startedTurns.has(turn)) {
+        const turn = event.data?.turn
+        state.createdFiles = new Set()
+        if (turn != null && !state.startedTurns.has(turn)) {
           state.startedTurns.add(turn)
           // 不发送"[OK] 收到，开始处理…"，改用 typing 指示 + 心跳进度。
           if (this.peerId) this.sendTyping(1).catch(() => {})
@@ -595,6 +596,14 @@ export class ConversationBridge {
         startHeartbeat(session, state)
         return
       }
+      if (event.type === 'tool/call') {
+        const args = event.data?.parameters || event.data?.args || {}
+        const target = args.TargetFile || args.targetFile || args.target_file || args.path || args.filePath
+        if (target && typeof target === 'string') {
+          state.createdFiles.add(target)
+        }
+        return
+      }
       if (event.type === 'assistant/message') {
         const text = textOfAssistantMessage(event.data.message)
         if (text.trim()) void this.sendText(text)
@@ -603,7 +612,7 @@ export class ConversationBridge {
       if (event.type === 'turn/end') {
         stopHeartbeat(state)
         if (this.peerId) this.sendTyping(2).catch(() => {})
-        const reason = event.data.reason
+        const reason = event.data?.reason || {}
         if (reason.kind === 'error') {
           void this.sendText(`❌ **处理出错**：${summarizeError(reason.error)}`)
         } else if (reason.kind === 'aborted') {
@@ -611,6 +620,25 @@ export class ConversationBridge {
         } else if (reason.kind === 'max-tokens') {
           void this.sendText(`⚠️ **达到模型单轮输出上限，本轮内容已截断**`)
         }
+        // 如果本轮生成/修改了产物文件，下发产物清单通知并尝试直接上传文件至聊天窗口
+        if (state.createdFiles && state.createdFiles.size > 0) {
+          const files = Array.from(state.createdFiles)
+          const fileLines = files.map((f) => `- \`${f}\``).join('\n')
+          void this.sendText(`📦 **本轮已生成产物文件**：\n${fileLines}`)
+
+          // 如果平台支持 sendMediaFile，自动尝试直接发送文件/图片到聊天窗口
+          if (typeof this.platform?.sendMediaFile === 'function' && this.peerId) {
+            for (const f of files) {
+              try {
+                if (statSync(f).isFile()) {
+                  void this.platform.sendMediaFile(this.peerId, f)
+                }
+              } catch {}
+            }
+          }
+
+          state.createdFiles.clear()
+        }
         return
       }
     }

package/lib/qq/gateway.js

@@ -1,6 +1,8 @@
 // QQ Bot OpenAPI v2 gateway
 // Official API: https://bot.q.qq.com/wiki/develop/api-v2/
 
+import fs from 'node:fs'
+import path from 'node:path'
 import { Service } from '@deepseek-ai/cordis'
 import WebSocket from 'ws'
 
@@ -66,6 +68,7 @@ function normalizeEvent(payload) {
       senderId: data.author?.user_openid || data.user_openid,
       peerId: data.author?.user_openid || data.user_openid,
       text: stringValue(data.content).trim(),
+      attachments: Array.isArray(data.attachments) ? data.attachments : [],
       message: data,
       messageReference: data.message_reference,
       msgSeq: data.msg_seq, // 用于避免去重
@@ -81,6 +84,7 @@ function normalizeEvent(payload) {
       peerId: data.group_openid || data.group_id,
       groupId: data.group_openid || data.group_id,
       text: stringValue(data.content).trim(),
+      attachments: Array.isArray(data.attachments) ? data.attachments : [],
       message: data,
       messageReference: data.message_reference,
       msgSeq: data.msg_seq, // 用于避免去重
@@ -137,6 +141,8 @@ export class QqGateway extends Service {
     this.heartbeatTimer = null
     this.heartbeatInterval = 30_000
     this.sequence = null
+    this.sessionId = null
+    this.unackedHeartbeats = 0
     this.tokenPromise = null
     this.dedup = new Map()
   }
@@ -213,6 +219,7 @@ export class QqGateway extends Service {
   }
 
   async runLoop() {
+    let backoffMs = this.config.reconnectDelayMs
     while (!this.stopRequested) {
       try {
         this.setStatus('starting')
@@ -223,11 +230,13 @@ export class QqGateway extends Service {
           || ((await requestJson(`${API_BASE}/gateway/bot`, { token, timeoutMs: this.config.apiTimeoutMs })).url)
           || DEFAULT_GATEWAY
         await this.connect(gateway, token)
+        backoffMs = this.config.reconnectDelayMs
       } catch (error) {
         if (this.stopRequested) break
         this.setStatus('reconnecting')
-        this.logger?.warn?.('[dsh-bridge qq] gateway disconnected: %s', error?.message ?? error)
-        await sleep(this.config.reconnectDelayMs)
+        this.logger?.warn?.('[dsh-bridge qq] gateway disconnected: %s, retrying in %dms...', error?.message ?? error, backoffMs)
+        await sleep(backoffMs)
+        backoffMs = Math.min(Math.round(backoffMs * 1.5), 30_000)
       }
     }
     this.setStatus('idle')
@@ -262,22 +271,48 @@ export class QqGateway extends Service {
     if (op === 10) {
       this.heartbeatInterval = Number(payload?.d?.heartbeat_interval || 30_000)
       this.startHeartbeat(ws)
-      ws.send(JSON.stringify({
-        op: 2,
-        d: {
-          token: `QQBot ${token}`,
-          intents: this.config.intents,
-          shard: [0, 1],
-          properties: { $os: process.platform, $browser: 'dsh-bridge', $device: 'dsh-bridge' },
-        },
-      }))
+      if (this.sessionId && this.sequence != null) {
+        // 快速恢复模式（Resume）：携带 sessionId 与 sequence 避免重新全量鉴权与丢失消息
+        this.logger?.info?.('[dsh-bridge qq] attempting session resume (sessionId=%s, seq=%s)', this.sessionId, this.sequence)
+        ws.send(JSON.stringify({
+          op: 6,
+          d: {
+            token: `QQBot ${token}`,
+            session_id: this.sessionId,
+            seq: this.sequence,
+          },
+        }))
+      } else {
+        // 全量鉴权模式（Identify）
+        ws.send(JSON.stringify({
+          op: 2,
+          d: {
+            token: `QQBot ${token}`,
+            intents: this.config.intents,
+            shard: [0, 1],
+            properties: { $os: process.platform, $browser: 'dsh-bridge', $device: 'dsh-bridge' },
+          },
+        }))
+      }
+      return
+    }
+    if (op === 11) {
+      // 心跳确认（Heartbeat ACK）：重置未确认计数器
+      this.unackedHeartbeats = 0
       return
     }
     if (op === 0) {
       if (payload.t === 'READY') {
+        this.sessionId = payload.d?.session_id || this.sessionId
         this.accountId = payload.d?.user?.id || payload.d?.user?.username || this.accountId
+        this.unackedHeartbeats = 0
         await this.persist({ accountId: this.accountId })
         this.setStatus('connected')
+        this.logger?.info?.('[dsh-bridge qq] gateway READY (session_id=%s)', this.sessionId)
+      } else if (payload.t === 'RESUMED') {
+        this.unackedHeartbeats = 0
+        this.setStatus('connected')
+        this.logger?.info?.('[dsh-bridge qq] gateway RESUMED successfully')
       }
       const event = normalizeEvent(payload)
       if (event.type === 'message' && event.id && !this.seen(event.id)) {
@@ -288,14 +323,31 @@ export class QqGateway extends Service {
       }
       return
     }
-    if (op === 7) { try { ws.close() } catch {}; return }
-    if (op === 9) throw new Error('QQ gateway invalid session')
+    if (op === 7) {
+      this.logger?.info?.('[dsh-bridge qq] gateway requested reconnect (OpCode 7)')
+      try { ws.close() } catch {}
+      return
+    }
+    if (op === 9) {
+      this.sessionId = null
+      this.sequence = null
+      throw new Error('QQ gateway invalid session (OpCode 9)')
+    }
   }
 
   startHeartbeat(ws) {
     this.clearHeartbeat()
+    this.unackedHeartbeats = 0
     const beat = () => {
-      if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify({ op: 1, d: this.sequence }))
+      if (ws.readyState === WebSocket.OPEN) {
+        if (this.unackedHeartbeats >= 2) {
+          this.logger?.warn?.('[dsh-bridge qq] heartbeat ACK missed (count=%d), dead link detected, reconnecting...', this.unackedHeartbeats)
+          try { ws.terminate() } catch {}
+          return
+        }
+        this.unackedHeartbeats += 1
+        ws.send(JSON.stringify({ op: 1, d: this.sequence }))
+      }
     }
     beat()
     this.heartbeatTimer = setInterval(beat, this.heartbeatInterval)
@@ -304,6 +356,7 @@ export class QqGateway extends Service {
   clearHeartbeat() {
     if (this.heartbeatTimer) clearInterval(this.heartbeatTimer)
     this.heartbeatTimer = null
+    this.unackedHeartbeats = 0
   }
 
   seen(id) {
@@ -485,6 +538,33 @@ export class QqGateway extends Service {
     return this.api(`/v2/panels/${encodeURIComponent(panelId)}/target`, { method: 'PUT', body })
   }
 
+  /**
+   * 上传并发送本地媒体文件（图片等）
+   */
+  async sendMediaFile(peerId, filePath, opts = {}) {
+    if (!fs.existsSync(filePath)) return null
+    const ext = path.extname(filePath).toLowerCase()
+    const isImage = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp'].includes(ext)
+    const fileType = isImage ? 1 : 1
+    try {
+      const buf = await fs.promises.readFile(filePath)
+      const base64Data = buf.toString('base64')
+      const ep = this.endpoint(peerId, opts.scope, 'files')
+      const res = await this.api(ep, {
+        method: 'POST',
+        body: {
+          file_type: fileType,
+          file_data: base64Data,
+          srv_send_msg: true,
+        },
+      })
+      return res
+    } catch (err) {
+      this.logger?.warn?.('[dsh-bridge qq] sendMediaFile error: %s', err?.message ?? err)
+      return null
+    }
+  }
+
   setCredentials(values = {}) {
     for (const key of ['appId', 'clientSecret', 'accessToken', 'accessTokenExpiresAt', 'gatewayUrl', 'intents']) {
       if (values[key] !== undefined) this.config[key] = values[key]

package/lib/qq/node.js

@@ -6,6 +6,8 @@
 //   - 出站：sendText 走 gateway.sendText；长文本用 Markdown 分块
 //   - 群聊：@提及消息仅在命中机器人才处理（GROUP_AT_MESSAGE_CREATE 已保证）
 
+import fs from 'node:fs'
+import path from 'node:path'
 import { ConversationBridge, conversationBridgeHelpers } from '../platform/conversation-bridge.js'
 import { gatewayConstants } from './gateway.js'
 
@@ -114,6 +116,7 @@ function makePlatform(gateway) {
     get capabilities() { return gateway.capabilities },
     // sendText / sendTyping 由 QqConversationNode 覆盖，这里仅提供兜底
     sendText: (peer, text) => gateway.sendText(peer, text, {}),
+    sendMediaFile: (peer, filePath, opts = {}) => gateway.sendMediaFile(peer, filePath, opts),
     sendTyping: () => Promise.resolve({ ok: true }),
     sendKeyboard: (peer, content, keyboard) => gateway.sendKeyboard(peer, content, keyboard, {}),
   }
@@ -144,12 +147,8 @@ export class QqConversationNode extends ConversationBridge {
     this._replyMsgId = null // 被动回复用的用户消息 ID（事件 d.id）
 
     // 订阅网关入站事件
-    this.ctx.on('qq/message', (event) => {
-      void this._handleInbound(event)
-    })
-    this.ctx.on('qq/interaction', (event) => {
-      void this._handleInteraction(event)
-    })
+    this.ctx.on('qq/message', (event) => this._handleInbound(event))
+    this.ctx.on('qq/interaction', (event) => this._handleInteraction(event))
   }
 
   // ---- 出站：覆盖 sendText / sendTyping，正确处理 scope 与被动回复 ----
@@ -373,7 +372,16 @@ export class QqConversationNode extends ConversationBridge {
     }
 
     const text = String(event.text ?? '').trim()
-    if (!text) {
+    const attachments = event.attachments || []
+
+    let mediaFiles = []
+    if (attachments.length > 0) {
+      this.logger?.info?.(`[dsh-bridge qq] processing ${attachments.length} attachment(s) from ${sender}...`)
+      mediaFiles = await this._processAttachments(attachments, this.config.cwd)
+      this.logger?.info?.(`[dsh-bridge qq] downloaded ${mediaFiles.length} file(s)`)
+    }
+
+    if (!text && mediaFiles.length === 0) {
       this.logger?.info?.(`[dsh-bridge qq] ignore empty message from ${sender}`)
       return
     }
@@ -384,10 +392,16 @@ export class QqConversationNode extends ConversationBridge {
       if (event.msgSeq !== undefined) this._msgSeq = event.msgSeq
     }
 
+    let fullText = text
+    if (mediaFiles.length > 0) {
+      const mediaDesc = mediaFiles.map((f) => `[文件: ${f.path}]`).join('\n')
+      fullText = fullText ? `${text}\n\n${mediaDesc}` : mediaDesc
+    }
+
     // 检测消息引用（文本交互）：如果用户回复了机器人的消息，且当前没有活动会话或消息以 /new 开头，
     // 则自动创建新会话并发送消息
     const messageReference = event.messageReference
-    if (messageReference && !this.activeSessionId && !text.startsWith('/')) {
+    if (messageReference && !this.activeSessionId && !fullText.startsWith('/')) {
       this.logger?.info?.(`[dsh-bridge qq] detected message reference from ${sender}, auto-starting conversation`)
       // 先创建新会话，再处理消息
       await this.handleInbound({ senderId: authId, text: '/new', isGroup })
@@ -396,7 +410,33 @@ export class QqConversationNode extends ConversationBridge {
     }
 
     // 交给平台无关核心：白名单/群消息/命令路由/agent 分发
-    await this.handleInbound({ senderId: authId, text, isGroup })
+    await this.handleInbound({ senderId: authId, text: fullText, isGroup })
+  }
+
+  /** 下载附件（图片/文件）并保存到本地工作目录 */
+  async _processAttachments(attachments, sessionCwd) {
+    if (!Array.isArray(attachments) || attachments.length === 0) return []
+    const mediaDir = path.join(sessionCwd || this.config.cwd || process.cwd(), '.qq-media')
+    try { await fs.promises.mkdir(mediaDir, { recursive: true }) } catch {}
+
+    const downloaded = []
+    for (const att of attachments) {
+      if (!att?.url) continue
+      try {
+        const rawUrl = att.url.startsWith('http') ? att.url : `https://${att.url}`
+        const res = await fetch(rawUrl, { signal: AbortSignal.timeout(15000) })
+        if (!res.ok) continue
+        const buf = Buffer.from(await res.arrayBuffer())
+        const ext = att.filename ? path.extname(att.filename) : (att.content_type?.includes('image') ? '.png' : '.bin')
+        const safeName = att.filename ? path.basename(att.filename) : `qq_${Date.now()}_${Math.random().toString(36).slice(2, 8)}${ext}`
+        const filePath = path.join(mediaDir, safeName)
+        await fs.promises.writeFile(filePath, buf)
+        downloaded.push({ filename: safeName, path: filePath, size: buf.length })
+      } catch (err) {
+        this.logger?.warn?.('[dsh-bridge qq] download attachment error: %s', err?.message ?? err)
+      }
+    }
+    return downloaded
   }
 
   // ---- 互动事件 ----