@wenbin_wb/dsh-bridge 2.3.2 → 2.4.0

package/client/index.js

@@ -343,16 +343,18 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
       setCfgDraft({
         digestIntervalSec:  String(platform.config.digestIntervalSec  ?? 300),
         approvalTimeoutSec: String(platform.config.approvalTimeoutSec ?? 600),
-        maxMessageChars:    String(platform.config.maxMessageChars    ?? 2000),
+        maxMessageChars:    String(platform.config.maxMessageChars    ?? (platformId === 'telegram' ? 4096 : 2000)),
         sendChunkDelayMs:   String(platform.config.sendChunkDelayMs   ?? 1500),
         appId: platform.config.appId ?? '',
         // Secret 不由后端回传；空值表示沿用已保存密钥
         clientSecret: '',
         appSecret: '',
         domain: platform.config.domain ?? 'feishu',
+        botToken: '',
+        proxy: platform.config.proxy ?? '',
       });
     }
-  }, [platform?.config]);
+  }, [platform?.config, platformId]);
 
   // 向上传递连接状态（供平台列表卡片绿点使用）
   React.useEffect(() => {
@@ -424,10 +426,10 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
       ...d,
       digestIntervalSec: '300',
       approvalTimeoutSec: '600',
-      maxMessageChars: '2000',
+      maxMessageChars: platformId === 'telegram' ? '4096' : '2000',
       sendChunkDelayMs: '1500',
     }));
-  }, []);
+  }, [platformId]);
 
   // 高级设置保存
   const saveConfig = React.useCallback(async () => {
@@ -438,7 +440,7 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
       maxMessageChars:    Number(cfgDraft.maxMessageChars),
       sendChunkDelayMs:   Number(cfgDraft.sendChunkDelayMs),
     };
-    // QQ / 飞书 平台额外携带凭证
+    // QQ / 飞书 / Telegram 平台额外携带凭证
     if (platformId === 'qq') {
       payload.appId = cfgDraft.appId.trim();
       payload.clientSecret = cfgDraft.clientSecret.trim();
@@ -446,6 +448,9 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
       payload.appId = cfgDraft.appId.trim();
       payload.appSecret = cfgDraft.appSecret.trim();
       payload.domain = cfgDraft.domain || 'feishu';
+    } else if (platformId === 'telegram') {
+      payload.botToken = cfgDraft.botToken.trim();
+      payload.proxy = cfgDraft.proxy.trim();
     }
     await act(BRIDGE_ENDPOINTS.platformSetConfig, payload);
   }, [act, cfgDraft, platformId]);
@@ -461,6 +466,10 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
     (platformId === 'feishu' && (
       cfgDraft.appId !== (platform.config.appId ?? '') ||
       cfgDraft.appSecret !== (platform.config.appSecret ?? '')
+    )) ||
+    (platformId === 'telegram' && (
+      cfgDraft.botToken !== '' ||
+      cfgDraft.proxy !== (platform.config.proxy ?? '')
     ))
   );
 
@@ -523,6 +532,16 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
         target: '_blank', rel: 'noopener noreferrer',
         style: s.btnGhost,
       }, '🌐 飞书开放平台'),
+      platformId === 'telegram' && React.createElement('a', {
+        href: 'https://github.com/wenbin-wb/dsh-bridge/blob/main/docs/telegram-usage.md',
+        target: '_blank', rel: 'noopener noreferrer',
+        style: s.btnGhost,
+      }, '📖 Telegram 使用说明'),
+      platformId === 'telegram' && React.createElement('a', {
+        href: 'https://t.me/BotFather',
+        target: '_blank', rel: 'noopener noreferrer',
+        style: s.btnGhost,
+      }, '🌐 @BotFather 申请 Bot'),
       React.createElement('button', {
         style: s.btnGhost,
         onClick: () => setShowHelp(v => !v),
@@ -643,8 +662,8 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
           title: '清除登录凭证，下次需重新配置',
         }, '解绑账号'),
       ),
-      // 飞书专属：手机扫码直达 Bot 对话
-      platformId === 'feishu' && platform.botQr && React.createElement('div', {
+      // 飞书 / Telegram 扫码直达对话引导卡片
+      (platformId === 'feishu' || platformId === 'telegram') && platform.botQr && React.createElement('div', {
         style: {
           marginTop: 12,
           padding: 12,
@@ -657,11 +676,11 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
           flexWrap: 'wrap',
         },
       },
-        React.createElement('img', { src: platform.botQr, alt: 'Feishu Bot QR', style: { width: 110, height: 110, borderRadius: 8, border: '1px solid var(--dsw-alias-border-l2,#e5e7eb)', padding: 4, background: '#fff' } }),
+        React.createElement('img', { src: platform.botQr, alt: `${platformName} Bot QR`, style: { width: 110, height: 110, borderRadius: 8, border: '1px solid var(--dsw-alias-border-l2,#e5e7eb)', padding: 4, background: '#fff' } }),
         React.createElement('div', { style: { flex: 1, minWidth: 160 } },
-          React.createElement('div', { style: { ...s.label, fontSize: 13, fontWeight: 600 } }, '📱 手机飞书扫码直达对话'),
+          React.createElement('div', { style: { ...s.label, fontSize: 13, fontWeight: 600 } }, `📱 手机 ${platformName} 扫码直达对话`),
           React.createElement('div', { style: { ...s.muted, fontSize: 12, marginTop: 4, lineHeight: 1.5 } },
-            '用飞书手机 App 扫描左侧二维码，立即打开与 Bot 对话；发送首条消息自动完成白名单授权。'
+            `用 ${platformName} 扫描左侧二维码，立即打开与 Bot 对话；发送首条消息自动完成白名单授权。`
           ),
           platform.botLink && React.createElement('div', { style: { display: 'flex', gap: 8, marginTop: 8 } },
             React.createElement('a', {
@@ -669,13 +688,13 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
               target: '_blank',
               rel: 'noopener noreferrer',
               style: { ...s.btnGhost, textDecoration: 'none', display: 'inline-flex', alignItems: 'center', gap: 4, padding: '4px 10px', fontSize: 12 },
-            }, '在飞书客户端打开 ↗'),
+            }, `在 ${platformName} 客户端打开 ↗`),
           ),
         ),
       ),
     ),
 
-    // 未配置 / 登录中：表单（QQ / 飞书）或二维码（微信）
+    // 未配置 / 登录中：表单（QQ / 飞书 / Telegram）或二维码（微信）
     (!platform?.configured || showQr) && React.createElement('div', { style: s.block },
       showQr && login.qr
         ? React.createElement('div', null,
@@ -687,7 +706,7 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
             ),
             login.error && React.createElement('div', { style: { ...s.muted, marginTop: 4, color: 'var(--dsw-alias-state-warn-primary,#92400e)' } }, login.error),
           )
-        : (platformId === 'qq' || platformId === 'feishu')
+        : (platformId === 'qq' || platformId === 'feishu' || platformId === 'telegram')
           ? React.createElement('div', { style: { display: 'flex', flexDirection: 'column', gap: 10, marginTop: 4 } },
               platformId === 'feishu' && React.createElement('div', {
                 style: {
@@ -704,40 +723,76 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
                 React.createElement('code', { style: { ...s.code, fontSize: 11, background: 'var(--dsw-alias-bg-layer-2,#f3f4f6)', padding: '2px 4px', borderRadius: 4 } }, 'npx feishu-bot-bootstrap'),
                 React.createElement('span', { style: s.muted }, ' 手机扫码一键自动创建应用并输出凭证；或在下方手动填入凭证。')
               ),
-              React.createElement('div', null,
-                React.createElement('div', { style: { ...s.muted, marginBottom: 4 } },
-                  platformId === 'qq' ? 'AppID — QQ 开放平台机器人应用 ID' : 'App ID — 飞书开放平台自建应用 ID (cli_xxx)'
-                ),
-                React.createElement('input', {
-                  style: { ...s.input, width: '100%' },
-                  placeholder: platformId === 'qq' ? '请输入 AppID' : '请输入 App ID (如 cli_a1b2c3d4...)',
-                  value: cfgDraft?.appId ?? '',
-                  onChange: (e) => setCfgDraft(d => ({ ...d, appId: e.target.value })),
-                }),
-              ),
-              React.createElement('div', null,
-                React.createElement('div', { style: { ...s.muted, marginBottom: 4 } },
-                  platformId === 'qq' ? 'ClientSecret — QQ 开放平台机器人密钥' : 'App Secret — 飞书开放平台应用密钥'
-                ),
-                React.createElement('div', { style: { display: 'flex', gap: 6, alignItems: 'center' } },
-                  React.createElement('input', {
-                    style: { ...s.input, flex: 1 },
-                    type: showSecret ? 'text' : 'password',
-                    placeholder: platformId === 'qq' ? '请输入 ClientSecret' : '请输入 App Secret',
-                    value: platformId === 'qq' ? (cfgDraft?.clientSecret ?? '') : (cfgDraft?.appSecret ?? ''),
-                    onChange: (e) => setCfgDraft(d => platformId === 'qq' ? ({ ...d, clientSecret: e.target.value }) : ({ ...d, appSecret: e.target.value })),
-                  }),
-                  React.createElement('button', {
-                    style: { ...s.btnGhost, height: 32, padding: '0 10px', fontSize: 13, flexShrink: 0 },
-                    onClick: () => setShowSecret(v => !v),
-                    type: 'button',
-                    title: showSecret ? '隐藏密钥' : '显示明文',
-                  }, showSecret ? '🙈 隐藏' : '👁️ 显示'),
-                ),
-              ),
+              platformId === 'telegram'
+                ? React.createElement(React.Fragment, null,
+                    React.createElement('div', null,
+                      React.createElement('div', { style: { ...s.muted, marginBottom: 4 } }, 'Bot Token — Telegram @BotFather 下发的机器人 Token'),
+                      React.createElement('div', { style: { display: 'flex', gap: 6, alignItems: 'center' } },
+                        React.createElement('input', {
+                          style: { ...s.input, flex: 1 },
+                          type: showSecret ? 'text' : 'password',
+                          placeholder: '请输入 Telegram Bot Token (如 123456789:ABCdef...)',
+                          value: cfgDraft?.botToken ?? '',
+                          onChange: (e) => setCfgDraft(d => ({ ...d, botToken: e.target.value })),
+                        }),
+                        React.createElement('button', {
+                          style: { ...s.btnGhost, height: 32, padding: '0 10px', fontSize: 13, flexShrink: 0 },
+                          onClick: () => setShowSecret(v => !v),
+                          type: 'button',
+                          title: showSecret ? '隐藏密钥' : '显示明文',
+                        }, showSecret ? '🙈 隐藏' : '👁️ 显示'),
+                      ),
+                    ),
+                    React.createElement('div', null,
+                      React.createElement('div', { style: { ...s.muted, marginBottom: 4 } }, '网络代理 (可选) — 支持国内 HTTP / HTTPS 代理'),
+                      React.createElement('input', {
+                        style: { ...s.input, width: '100%' },
+                        placeholder: '可选，例如 http://127.0.0.1:7890（为空则直连或读取环境变量）',
+                        value: cfgDraft?.proxy ?? '',
+                        onChange: (e) => setCfgDraft(d => ({ ...d, proxy: e.target.value })),
+                      }),
+                    ),
+                  )
+                : React.createElement(React.Fragment, null,
+                    React.createElement('div', null,
+                      React.createElement('div', { style: { ...s.muted, marginBottom: 4 } },
+                        platformId === 'qq' ? 'AppID — QQ 开放平台机器人应用 ID' : 'App ID — 飞书开放平台自建应用 ID (cli_xxx)'
+                      ),
+                      React.createElement('input', {
+                        style: { ...s.input, width: '100%' },
+                        placeholder: platformId === 'qq' ? '请输入 AppID' : '请输入 App ID (如 cli_a1b2c3d4...)',
+                        value: cfgDraft?.appId ?? '',
+                        onChange: (e) => setCfgDraft(d => ({ ...d, appId: e.target.value })),
+                      }),
+                    ),
+                    React.createElement('div', null,
+                      React.createElement('div', { style: { ...s.muted, marginBottom: 4 } },
+                        platformId === 'qq' ? 'ClientSecret — QQ 开放平台机器人密钥' : 'App Secret — 飞书开放平台应用密钥'
+                      ),
+                      React.createElement('div', { style: { display: 'flex', gap: 6, alignItems: 'center' } },
+                        React.createElement('input', {
+                          style: { ...s.input, flex: 1 },
+                          type: showSecret ? 'text' : 'password',
+                          placeholder: platformId === 'qq' ? '请输入 ClientSecret' : '请输入 App Secret',
+                          value: platformId === 'qq' ? (cfgDraft?.clientSecret ?? '') : (cfgDraft?.appSecret ?? ''),
+                          onChange: (e) => setCfgDraft(d => platformId === 'qq' ? ({ ...d, clientSecret: e.target.value }) : ({ ...d, appSecret: e.target.value })),
+                        }),
+                        React.createElement('button', {
+                          style: { ...s.btnGhost, height: 32, padding: '0 10px', fontSize: 13, flexShrink: 0 },
+                          onClick: () => setShowSecret(v => !v),
+                          type: 'button',
+                          title: showSecret ? '隐藏密钥' : '显示明文',
+                        }, showSecret ? '🙈 隐藏' : '👁️ 显示'),
+                      ),
+                    ),
+                  ),
               React.createElement('div', null,
                 React.createElement('a', {
-                  href: platformId === 'qq' ? 'https://bot.q.qq.com/wiki/develop/api-v2/' : 'https://open.feishu.cn/app',
+                  href: platformId === 'qq'
+                    ? 'https://bot.q.qq.com/wiki/develop/api-v2/'
+                    : platformId === 'feishu'
+                      ? 'https://open.feishu.cn/app'
+                      : 'https://t.me/BotFather',
                   target: '_blank', rel: 'noopener noreferrer',
                   style: s.btnLink,
                 }, platformId === 'qq' ? '📖 前往 QQ 开放平台申请机器人' : '📖 前往飞书开放平台创建企业自建应用'),
@@ -746,7 +801,9 @@ function PlatformCard({ platformId, platformName, platformDesc, rpcCall, onStatu
                 React.createElement('button', {
                   style: { ...s.btnPri, opacity: busy ? 0.5 : 1 },
                   onClick: saveConfig,
-                  disabled: busy || !cfgDraft?.appId?.trim() || (platformId === 'qq' ? !cfgDraft?.clientSecret?.trim() : !cfgDraft?.appSecret?.trim()),
+                  disabled: busy || (platformId === 'telegram'
+                    ? !cfgDraft?.botToken?.trim()
+                    : (!cfgDraft?.appId?.trim() || (platformId === 'qq' ? !cfgDraft?.clientSecret?.trim() : !cfgDraft?.appSecret?.trim()))),
                 }, busy ? '保存中…' : '保存并连接'),
                 login.phase === 'error' && React.createElement('div', { style: { ...s.muted, fontSize: 12 } }, login.error ?? '连接失败'),
               ),

package/docs/telegram-usage.md

@@ -0,0 +1,89 @@
+# Telegram 机器人接入指南
+
+> 通过官方 Telegram Bot API，将本地 DeepSeek Harness 接入 Telegram，支持单聊与群聊、原生快捷指令菜单、交互卡片按键、增量打字机流式输出与权限审批。
+
+---
+
+## 🌟 核心优势
+
+- **100% 免公网 IP / 免 Webhook**：基于 Telegram 官方 Long Polling（长轮询）机制，本地电脑或内网服务器即可直连 Telegram Bot API。
+- **零依赖原生代理支持**：内置极简 HTTP/HTTPS CONNECT 隧道代理客户端，国内网络环境下仅需填入代理地址（如 `http://127.0.0.1:7890`）即可极速通信。
+- **增量打字机流式输出**：接入轮次实时生命周期，通过 `editMessageText` 实现平滑打字机流式输出，单条气泡原地更新，告别刷屏。
+- **原生快捷指令菜单 (`Menu` 按键)**：自动通过 `setMyCommands` 与 `setChatMenuButton` 注册全范围指令，输入 `/` 或点击左下角菜单即可一键直达。
+- **原生交互卡片与审批按键**：审批请求下发 Inline Keyboard 按键 `[✓ 批准执行]` / `[✕ 拒绝执行]`，一键点击即时响应。
+- **多工作区与会话持久化**：支持 `/sessions` 查看会话列表、`/use <序号>` 切换、`/workspaces` 调度工作区，重启 DSH 后白名单与会话不丢失。
+
+---
+
+## 🛠️ 第一步：在 Telegram 中创建机器人并获取 Token
+
+1. 打开 Telegram，搜索官方机器人管理号 [@BotFather](https://t.me/BotFather)；
+2. 点击底部 `Start` 或发送 `/newbot` 指令；
+3. 根据提示依次输入：
+   - **机器人昵称**（如 `My DSH Agent`）；
+   - **机器人用户名**（必须以 `bot` 结尾，如 `my_dsh_agent_bot`）；
+4. 创建成功后，@BotFather 会返回一行 **HTTP API Token**（格式如 `123456789:ABCdefGhIJKlmNoPQRsTUVwxyZ`）。
+
+> 💡 **（可选）在 BotFather 中固化快捷指令**：
+> 向 @BotFather 发送 `/setcommands`，选择你的机器人，直接复制并粘贴下方内容发送：
+> ```text
+> new - 新建会话并开始执行 (/new <提示词>)
+> sessions - 列出所有会话列表与切换
+> use - 切换活动会话 (/use <N>)
+> workspaces - 列出本地所有可用工作区
+> status - 查看 Agent 状态与会话摘要
+> stop - 停止当前正在运行的任务
+> end - 结束当前活动会话
+> help - 显示快捷按键与完整帮助
+> ```
+
+---
+
+## ⚙️ 第二步：在 DSH Bridge 中配置与连接
+
+1. 打开 DSH Web 设置页「**远程访问**」→「**IM 机器人**」；
+2. 在平台选择栏中点击「**Telegram**」卡片；
+3. 填入刚才获取的 **Bot Token**；
+4. **网络代理（可选）**：
+   - 若在中国大陆地区服务器或个人电脑上运行，填入本地代理地址，如 `http://127.0.0.1:7890`（支持 Clash / v2ray / Squid 等 HTTP/HTTPS 代理）；
+   - 亦可直接在系统环境变量中设置 `HTTPS_PROXY=http://127.0.0.1:7890`；
+5. 点击「**保存并连接**」。
+
+---
+
+## 📱 第三步：扫码与自动白名单授权
+
+1. 连接成功后，面板将展示当前机器人的二维码与 `https://t.me/<username>` 直达链接；
+2. 用手机 Telegram 扫描二维码或点击链接打开与机器人的对话；
+3. 发送第一条消息（如 `/help` 或 `你好`），系统将**自动将你的 Telegram 账号加入白名单**并持久化；
+4. 之后即可在 Telegram 里随时随地向 Agent 下达任务指令。
+
+---
+
+## 💬 常用指令与卡片交互
+
+| 指令 | 说明 | 交互支持 |
+| :--- | :--- | :--- |
+| *(普通文本)* | 发送给当前活动 Agent 执行任务 | 实时打字机流式输出 |
+| `/new <提示词>` | 在当前工作区新建会话并立即执行 | 启动全新轮次 |
+| `/new <提示词> @N` | 在指定工作区序号新建会话 | 多工作区调度 |
+| `/sessions`（或 `/list`） | 查看所有会话列表 | 附带一键切换按键 |
+| `/use N`（或 `/resume N`） | 切换活动会话至序号 N | 快速切换上下文 |
+| `/workspaces` | 列出本地所有可用项目工作区 | 查看工作区路径 |
+| `/status` | 查看当前 Agent 运行状态看板 | 附带刷新/停止/结束按键 |
+| `/stop` | 强制停止当前正在运行的 Agent 任务 | 即刻中断执行 |
+| `/end` | 结束当前活动会话 | 挂载快捷开始按键 |
+| `/yes` `/no`（或 `1`/`2`） | 响应权限审批请求 | 支持直接点击卡片按钮 |
+| `/help` | 查看快捷按键与完整使用帮助 | 挂载全套功能导航按键 |
+
+---
+
+## 🛡️ 多模态与安全说明
+
+1. **图片与文件双向传输**：
+   - 直接向 Telegram 机器人发送图片或文档，系统自动保存到本地并注入提示词供 Agent 解析；
+   - Agent 任务执行中生成的图片、文档等产物，在轮次结束时会自动推送回 Telegram 聊天。
+2. **安全白名单拦截**：
+   - 仅白名单内的用户消息会被放行给 Agent；非白名单用户发送的消息会被直接忽略，绝不消耗 Token 或喂给模型。
+3. **敏感操作审批**：
+   - 当 Agent 尝试执行系统命令或敏感文件读写时，Telegram 会自动下发 `[✓ 批准执行]` / `[✕ 拒绝执行]` 交互按键，10 分钟未处理自动超时拒绝。

package/lib/feishu/gateway.js

@@ -2,6 +2,8 @@
 // Official SDK: @larksuiteoapi/node-sdk
 // Reference: https://open.feishu.cn/document/home/event-subscription-via-websocket/overview
 
+import fs from 'node:fs'
+import path from 'node:path'
 import { Service } from '@deepseek-ai/cordis'
 import * as Lark from '@larksuiteoapi/node-sdk'
 
@@ -144,6 +146,7 @@ export class FeishuGateway extends Service {
         // 5. 启动 WebSocket 长连接
         await this.wsClient.start({ eventDispatcher: this.eventDispatcher })
         this.setStatus('online')
+        this._startWatchdog()
         this.logger.info?.('[dsh-bridge feishu] WebSocket connected to Feishu Open Platform')
         return true
       } catch (err) {
@@ -158,8 +161,28 @@ export class FeishuGateway extends Service {
     return this._startingPromise
   }
 
+  _startWatchdog() {
+    this._stopWatchdog()
+    this._watchdogTimer = setInterval(async () => {
+      if (this.status === 'online' && !this._closing && this.configured && this.client) {
+        try {
+          await this.client.bot.v3.bot.get({}).catch(() => null)
+        } catch (err) {
+          this.logger?.warn?.('[dsh-bridge feishu] liveness probe warning: %s', err?.message ?? err)
+        }
+      }
+    }, 60_000)
+    if (typeof this._watchdogTimer?.unref === 'function') this._watchdogTimer.unref()
+  }
+
+  _stopWatchdog() {
+    if (this._watchdogTimer) clearInterval(this._watchdogTimer)
+    this._watchdogTimer = null
+  }
+
   async stop() {
     this._closing = true
+    this._stopWatchdog()
     try {
       if (this.wsClient) {
         const wsInstance = this.wsClient.wsConfig?.getWSInstance?.()
@@ -199,15 +222,16 @@ export class FeishuGateway extends Service {
     const chatType = message.chat_type || 'p2p' // 'p2p' or 'group'
     const isGroup = chatType === 'group'
 
-    // 提取文本内容
+    // 解析消息体（文本 / 图片 / 文件 / 音频 / 视频）
     let text = ''
-    if (message.message_type === 'text') {
-      try {
-        const parsed = JSON.parse(message.content || '{}')
-        text = parsed.text || ''
-      } catch {
-        text = message.content || ''
+    let contentObj = {}
+    try {
+      contentObj = JSON.parse(message.content || '{}')
+      if (message.message_type === 'text') {
+        text = contentObj.text || ''
       }
+    } catch {
+      text = message.content || ''
     }
 
     // 群聊中剥离机器人 @ 占位符（例如 @_user_1 等）
@@ -226,12 +250,54 @@ export class FeishuGateway extends Service {
       isGroup,
       messageId,
       text,
+      contentObj,
       messageType: message.message_type,
       raw: data,
       createTime: Number(message.create_time || Date.now()),
     })
   }
 
+  /**
+   * 下载消息中的资源文件（图片/文件/音频/媒体）
+   * @param {object} opts
+   * @param {string} opts.messageId 消息 ID
+   * @param {string} opts.fileKey 资源 Key
+   * @param {string} [opts.type] 'file' | 'image'
+   * @returns {Promise<Buffer|null>}
+   */
+  async downloadMessageResource({ messageId, fileKey, type = 'file' }) {
+    if (!this.client) throw new Error('Feishu client not initialized')
+    try {
+      const resp = await this.client.im.messageResource.get({
+        path: {
+          message_id: messageId,
+          file_key: fileKey,
+        },
+        params: {
+          type: type === 'image' ? 'image' : 'file',
+        },
+      })
+      if (Buffer.isBuffer(resp)) return resp
+      if (resp && typeof resp.pipe === 'function') {
+        const chunks = []
+        for await (const chunk of resp) chunks.push(Buffer.from(chunk))
+        return Buffer.concat(chunks)
+      }
+      if (resp?.data) {
+        if (Buffer.isBuffer(resp.data)) return resp.data
+        if (resp.data.pipe) {
+          const chunks = []
+          for await (const chunk of resp.data) chunks.push(Buffer.from(chunk))
+          return Buffer.concat(chunks)
+        }
+      }
+      return null
+    } catch (err) {
+      this.logger?.warn?.('[dsh-bridge feishu] downloadMessageResource error: %s', err?.message ?? err)
+      return null
+    }
+  }
+
   async _handleCardActionTrigger(data) {
     const action = data?.action || {}
     const operator = data?.operator || {}
@@ -382,6 +448,99 @@ export class FeishuGateway extends Service {
     }
   }
 
+  /**
+   * 上传并发送本地图片
+   */
+  async sendLocalImage(receiveId, filePath, opts = {}) {
+    if (!this.client || !receiveId || !filePath) return null
+    let receiveIdType = opts.receiveIdType
+    if (!receiveIdType) {
+      if (receiveId.startsWith('ou_')) receiveIdType = 'open_id'
+      else if (receiveId.startsWith('oc_')) receiveIdType = 'chat_id'
+      else if (opts.isGroup) receiveIdType = 'chat_id'
+      else receiveIdType = 'open_id'
+    }
+
+    try {
+      const imageStream = fs.createReadStream(filePath)
+      const uploadRes = await this.client.im.v1.image.create({
+        data: {
+          image_type: 'message',
+          image: imageStream,
+        },
+      })
+      const imageKey = uploadRes?.image_key
+      if (!imageKey) throw new Error('Feishu image upload returned no image_key')
+
+      const res = await this.client.im.v1.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+          receive_id: receiveId,
+          msg_type: 'image',
+          content: JSON.stringify({ image_key: imageKey }),
+        },
+      })
+      return res?.data
+    } catch (err) {
+      this.logger.warn?.(`[dsh-bridge feishu] sendLocalImage error (${receiveId}, ${filePath}):`, err?.message ?? err)
+      return null
+    }
+  }
+
+  /**
+   * 上传并发送本地文件
+   */
+  async sendLocalFile(receiveId, filePath, opts = {}) {
+    if (!this.client || !receiveId || !filePath) return null
+    let receiveIdType = opts.receiveIdType
+    if (!receiveIdType) {
+      if (receiveId.startsWith('ou_')) receiveIdType = 'open_id'
+      else if (receiveId.startsWith('oc_')) receiveIdType = 'chat_id'
+      else if (opts.isGroup) receiveIdType = 'chat_id'
+      else receiveIdType = 'open_id'
+    }
+
+    try {
+      const fileName = path.basename(filePath)
+      const fileStream = fs.createReadStream(filePath)
+      const uploadRes = await this.client.im.v1.file.create({
+        data: {
+          file_type: 'stream',
+          file_name: fileName,
+          file: fileStream,
+        },
+      })
+      const fileKey = uploadRes?.file_key
+      if (!fileKey) throw new Error('Feishu file upload returned no file_key')
+
+      const res = await this.client.im.v1.message.create({
+        params: { receive_id_type: receiveIdType },
+        data: {
+          receive_id: receiveId,
+          msg_type: 'file',
+          content: JSON.stringify({ file_key: fileKey }),
+        },
+      })
+      return res?.data
+    } catch (err) {
+      this.logger.warn?.(`[dsh-bridge feishu] sendLocalFile error (${receiveId}, ${filePath}):`, err?.message ?? err)
+      return null
+    }
+  }
+
+  /**
+   * 发送本地媒体文件（自动识别图片/文档）
+   */
+  async sendMediaFile(receiveId, filePath, opts = {}) {
+    if (!fs.existsSync(filePath)) return null
+    const ext = path.extname(filePath).toLowerCase()
+    const isImage = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp'].includes(ext)
+    if (isImage) {
+      return this.sendLocalImage(receiveId, filePath, opts)
+    }
+    return this.sendLocalFile(receiveId, filePath, opts)
+  }
+
   // 释放资源
   dispose() {
     void this.stop()