@wenbin_wb/dsh-bridge 2.3.3 → 2.5.0

package/lib/index.js

@@ -21,6 +21,9 @@ 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';
+import { AuthManager } from './auth/manager.js';
+import { renderLoginPage } from './auth/login-template.js';
 
 const name = 'dsh-bridge';
 // 微信 Bot 会话桥依赖 DSH 提供的会话/agent/审批/工作区/持久化服务，需显式 inject
@@ -126,14 +129,15 @@ function loopbackHeaders(headers, targetPort) {
 }
 
 /**
- * HTTP + WebSocket 代理服务器
+ * HTTP + WebSocket 代理服务器（带安全认证守门）
  * 关键：改写 Host + Origin，注入 crypto.randomUUID polyfill
- * 否则手机通过局域网访问时 DSH 会把它当未登录的外部请求处理
+ * 并在未授权时拦截并展示 DSH 风格登录页，阻止未授权 WebSocket 与 API 调用
  */
 class ProxyServer {
-  constructor({ localPort, targetPort, logger }) {
+  constructor({ localPort, targetPort, authManager, logger }) {
     this.localPort = localPort;
     this.targetPort = targetPort;
+    this.authManager = authManager;
     this.logger = logger;
     this.server = null;
     this.clientSockets = new Set();
@@ -144,6 +148,101 @@ class ProxyServer {
     if (this.server) return;
 
     this.server = createServer((req, res) => {
+      // 1. 处理登录 API: POST /__dsh_bridge__/login
+      if (req.url === '/__dsh_bridge__/login' && req.method === 'POST') {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+          try {
+            const body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
+            const clientIp = req.socket?.remoteAddress || '';
+            const verify = this.authManager?.verifyPassword(body.password, clientIp);
+            if (verify?.success) {
+              const sessionToken = this.authManager.createSession();
+              res.writeHead(200, {
+                'Content-Type': 'application/json; charset=utf-8',
+                'Set-Cookie': `dsh_bridge_auth=${sessionToken}; Path=/; HttpOnly; SameSite=Lax; Max-Age=2592000`,
+              });
+              res.end(JSON.stringify({ ok: true }));
+            } else {
+              res.writeHead(401, { 'Content-Type': 'application/json; charset=utf-8' });
+              res.end(JSON.stringify({ ok: false, error: verify?.error || '访问密码错误' }));
+            }
+          } catch (e) {
+            res.writeHead(400, { 'Content-Type': 'application/json; charset=utf-8' });
+            res.end(JSON.stringify({ ok: false, error: '无效请求' }));
+          }
+        });
+        return;
+      }
+
+      // 2. 处理登出 API: POST /__dsh_bridge__/logout
+      if (req.url === '/__dsh_bridge__/logout' && req.method === 'POST') {
+        res.writeHead(200, {
+          'Content-Type': 'application/json; charset=utf-8',
+          'Set-Cookie': 'dsh_bridge_auth=; Path=/; HttpOnly; Max-Age=0',
+        });
+        res.end(JSON.stringify({ ok: true }));
+        return;
+      }
+
+      // 3. 处理鉴权状态 API: GET /__dsh_bridge__/auth-status
+      if (req.url === '/__dsh_bridge__/auth-status' && req.method === 'GET') {
+        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify(this.authManager?.getStatus() ?? { enabled: false }));
+        return;
+      }
+
+      // 4. 核心鉴权拦截
+      const auth = this.authManager?.verifyRequest(req) ?? { authenticated: true };
+
+      // 4.1 若从 URL Token 认证通过：下发 Cookie 并 302 重定向到干净 URL (去掉 ?auth=)
+      if (auth.fromToken) {
+        const sessionToken = this.authManager.createSession();
+        try {
+          const urlObj = new URL(req.url, 'http://localhost');
+          urlObj.searchParams.delete('auth');
+          urlObj.searchParams.delete('token');
+          const cleanPath = (urlObj.pathname || '/') + (urlObj.search || '');
+          res.writeHead(302, {
+            'Location': cleanPath,
+            'Set-Cookie': `dsh_bridge_auth=${sessionToken}; Path=/; HttpOnly; SameSite=Lax; Max-Age=2592000`,
+          });
+          res.end();
+          return;
+        } catch {
+          res.writeHead(302, {
+            'Location': '/',
+            'Set-Cookie': `dsh_bridge_auth=${sessionToken}; Path=/; HttpOnly; SameSite=Lax; Max-Age=2592000`,
+          });
+          res.end();
+          return;
+        }
+      }
+
+      // 4.2 若未通过认证：根据请求类型渲染 DSH 登录页或返回 401 JSON
+      if (!auth.authenticated) {
+        const accept = String(req.headers['accept'] || '');
+        const isHtml = accept.includes('text/html') || (!req.url.startsWith('/api/') && !req.url.includes('.'));
+        if (isHtml) {
+          const clientIp = req.socket?.remoteAddress || '';
+          const isLocked = this.authManager?.isIpBlocked(clientIp);
+          const html = renderLoginPage({
+            hasPassword: this.authManager?.hasPassword,
+            locked: isLocked,
+            error: isLocked ? '尝试次数过多，请 60 秒后再试' : '',
+          });
+          res.writeHead(401, { 'Content-Type': 'text/html; charset=utf-8' });
+          res.end(html);
+          return;
+        } else {
+          res.writeHead(401, { 'Content-Type': 'application/json; charset=utf-8' });
+          res.end(JSON.stringify({ error: 'unauthorized', message: '需要访问认证，请先登录' }));
+          return;
+        }
+      }
+
+      // 5. 认证通过：正常执行反向代理转发
       const headers = loopbackHeaders(req.headers, this.targetPort);
       const proxyReq = httpRequest(
         { host: '127.0.0.1', port: this.targetPort, method: req.method, path: req.url, headers, agent: false },
@@ -184,8 +283,15 @@ class ProxyServer {
       req.pipe(proxyReq);
     });
 
-    // WebSocket upgrade（DSH 的 /api/events.mux 等流式通道）
+    // WebSocket upgrade 鉴权与代理
     this.server.on('upgrade', (req, socket, head) => {
+      const auth = this.authManager?.verifyRequest(req) ?? { authenticated: true };
+      if (!auth.authenticated) {
+        socket.write('HTTP/1.1 401 Unauthorized\r\nContent-Type: text/plain\r\n\r\nUnauthorized\r\n');
+        socket.destroy();
+        return;
+      }
+
       const headers = loopbackHeaders(req.headers, this.targetPort);
       const proxyReq = httpRequest({
         host: '127.0.0.1', port: this.targetPort, method: req.method, path: req.url, headers, agent: false,
@@ -258,11 +364,12 @@ class ProxyServer {
  * Bridge Service
  */
 class BridgeService {
-  constructor({ dshPort, proxyPort, home, customTunnelConfig, logger }) {
+  constructor({ dshPort, proxyPort, home, customTunnelConfig, authManager, logger }) {
     this.dshPort = dshPort;
     this.proxyPort = proxyPort;
     this.home = home;
     this.customTunnelConfig = customTunnelConfig ?? null;
+    this.authManager = authManager ?? null;
     this.logger = logger;
 
     this.qrCache = new QrCache();
@@ -281,6 +388,7 @@ class BridgeService {
     this.proxy = new ProxyServer({
       localPort: this.proxyPort,
       targetPort: this.dshPort,
+      authManager: this.authManager,
       logger: this.logger,
     });
 
@@ -290,11 +398,38 @@ class BridgeService {
 
   async getStatus() {
     const lanIp = selectLanIPv4();
-    const lanUrl = lanIp ? `http://${lanIp}:${this.proxyPort}` : null;
+    const token = this.authManager?.secretToken;
+    const isAuthEnabled = Boolean(this.authManager?.enabled && this.authManager?.mode !== 'password_only' && token);
+
+    const isLanProtected = isAuthEnabled && this.authManager?.scope !== 'public_only';
+    const isPublicProtected = isAuthEnabled && this.authManager?.scope !== 'lan_only';
+
+    const appendToken = (url, shouldAppend) => {
+      if (!url || !shouldAppend || !token) return url;
+      try {
+        const u = new URL(url);
+        u.searchParams.set('auth', token);
+        return u.toString();
+      } catch {
+        const sep = url.includes('?') ? '&' : '?';
+        return `${url}${sep}auth=${encodeURIComponent(token)}`;
+      }
+    };
+
+    const baseLanUrl = lanIp ? `http://${lanIp}:${this.proxyPort}` : null;
+    const lanUrl = appendToken(baseLanUrl, isLanProtected);
+
+    const baseCloudflaredUrl = this.cloudflared?.url || null;
+    const cloudflaredUrl = appendToken(baseCloudflaredUrl, isPublicProtected);
+
+    const baseCustomUrl = this.customTunnel?.publicUrl || null;
+    const customUrl = appendToken(baseCustomUrl, isPublicProtected);
 
     return {
       version: VERSION,
 
+      auth: this.authManager?.getStatus() ?? { enabled: false },
+
       proxy: {
         running: !!this.proxy,
         port: this.proxyPort,
@@ -304,14 +439,16 @@ class BridgeService {
       lan: {
         ip: lanIp,
         url: lanUrl,
+        rawUrl: baseLanUrl,
         qr: lanUrl ? await this.qrCache.get(lanUrl) : null,
       },
 
       cloudflared: {
         running: !!this.cloudflared,
-        url: this.cloudflared?.url || null,
-        qr: this.cloudflared?.url
-          ? await this.qrCache.get(this.cloudflared.url)
+        url: cloudflaredUrl,
+        rawUrl: baseCloudflaredUrl,
+        qr: cloudflaredUrl
+          ? await this.qrCache.get(cloudflaredUrl)
           : null,
         state: this.cloudflaredState,
       },
@@ -320,9 +457,10 @@ class BridgeService {
         configured: !!(this.customTunnelConfig?.serverUrl && this.customTunnelConfig?.accessToken),
         serverUrl: this.customTunnelConfig?.serverUrl ?? '',
         running: !!this.customTunnel?.connected,
-        url: this.customTunnel?.publicUrl || null,
-        qr: this.customTunnel?.publicUrl
-          ? await this.qrCache.get(this.customTunnel.publicUrl)
+        url: customUrl,
+        rawUrl: baseCustomUrl,
+        qr: customUrl
+          ? await this.qrCache.get(customUrl)
           : null,
         state: this.customTunnelState,
       },
@@ -494,6 +632,7 @@ function apply(ctx, config = {}) {
   const proxyPort = config.port ?? 3082;
   const dshHome = process.env.DSH_HOME ?? join(homedir(), '.dsh');
   const configFile = join(dshHome, 'dsh-bridge', 'config.json');
+  const emergencyResetFile = join(dshHome, 'dsh-bridge', 'reset-auth');
 
   // 从 JSON 文件读取持久化配置
   async function loadConfig() {
@@ -511,11 +650,60 @@ function apply(ctx, config = {}) {
     await writeFile(configFile, JSON.stringify(data, null, 2), 'utf8');
   }
 
+  // 访问安全认证管理器
+  const authManager = new AuthManager({
+    config: config.auth ?? {},
+    logger,
+    onPersist: async (patch) => {
+      const stored = await loadConfig();
+      stored.auth = { ...(stored.auth ?? {}), ...patch };
+      await saveConfig(stored);
+    },
+  });
+
+  // 保命救急检查：检测到 reset-auth 文件时自动重置全量密码与安全策略
+  async function checkEmergencyReset() {
+    try {
+      await unlink(emergencyResetFile);
+      authManager.enabled = false;
+      authManager.passwordHash = '';
+      authManager.passwordSalt = '';
+      authManager.adminPasswordHash = '';
+      authManager.adminPasswordSalt = '';
+      authManager.adminPolicy = 'password_unlock';
+      authManager.mode = 'token_and_password';
+      authManager.sessions.clear();
+      authManager.adminSessions.clear();
+      const stored = await loadConfig();
+      delete stored.auth;
+      await saveConfig(stored);
+      logger.warn('dsh-bridge: [保命救急] 检测到 reset-auth 标记文件，已成功重置所有访问密码与安全策略！');
+    } catch {}
+  }
+
+  // 启动时读取已保存的 auth 配置并执行保命标记检查
+  checkEmergencyReset().then(() => loadConfig()).then((stored) => {
+    if (stored?.auth) {
+      if (stored.auth.enabled != null) authManager.enabled = Boolean(stored.auth.enabled);
+      if (stored.auth.mode) authManager.mode = stored.auth.mode;
+      if (stored.auth.scope) authManager.scope = stored.auth.scope;
+      if (stored.auth.adminPolicy) authManager.adminPolicy = stored.auth.adminPolicy;
+      if (stored.auth.passwordHash) authManager.passwordHash = stored.auth.passwordHash;
+      if (stored.auth.passwordSalt) authManager.passwordSalt = stored.auth.passwordSalt;
+      if (stored.auth.adminPasswordHash) authManager.adminPasswordHash = stored.auth.adminPasswordHash;
+      if (stored.auth.adminPasswordSalt) authManager.adminPasswordSalt = stored.auth.adminPasswordSalt;
+      if (stored.auth.secretToken) authManager.secretToken = stored.auth.secretToken;
+      if (stored.auth.allowLoopback != null) authManager.allowLoopback = Boolean(stored.auth.allowLoopback);
+      logger.info('dsh-bridge: loaded saved auth config (enabled=%s, mode=%s, adminPolicy=%s)', authManager.enabled, authManager.mode, authManager.adminPolicy);
+    }
+  }).catch(() => {});
+
   const service = new BridgeService({
     dshPort,
     proxyPort,
     home: config.home,
     customTunnelConfig: config.customTunnel ?? null,
+    authManager,
     logger,
   });
 
@@ -569,6 +757,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 +882,51 @@ 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,
+    authManager,
     wechat,
     qq,
     feishu,
+    telegram,
     platformManager,
     logger,
     saveCustomTunnelConfig: async (serverUrl, accessToken) => {
@@ -705,9 +946,12 @@ function apply(ctx, config = {}) {
     try { disposeRpc(); } catch {}
     await wechat.destroy();
     await qq.destroy();
+    await feishu.destroy();
+    await telegram.destroy();
     platformManager.dispose();
+    authManager.dispose();
     await service.dispose();
-  }, 'dsh-bridge: stop wechat, qq, proxy and tunnels');
+  }, 'dsh-bridge: stop wechat, qq, feishu, telegram, proxy, auth and tunnels');
 }
 
-export { name, inject, apply };
+export { name, inject, apply, ProxyServer, BridgeService, selectLanIPv4 };

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]