@xmanrui/dsh-im 0.9.0 → 0.10.0

package/src/channels/shared/image-prompt.mjs

@@ -0,0 +1,268 @@
+const DEFAULT_MAX_IMAGE_BYTES = 5 * 1024 * 1024;
+const DEFAULT_MAX_IMAGES = 20;
+const DEFAULT_MAX_TOTAL_IMAGE_BYTES = 20 * 1024 * 1024;
+
+export const DEFAULT_IMAGE_PROMPT = '请分析这张图片。';
+
+export class ImagePromptError extends Error {
+  constructor(code, message, userMessage, options = {}) {
+    super(message, options);
+    this.name = 'ImagePromptError';
+    this.code = code;
+    this.userMessage = userMessage;
+  }
+}
+
+function requestSignal(signal, timeoutMs) {
+  const timeout = AbortSignal.timeout(timeoutMs);
+  return signal ? AbortSignal.any([signal, timeout]) : timeout;
+}
+
+async function cancelResponseBody(response) {
+  try {
+    await response?.body?.cancel?.();
+  } catch {
+    // The original download error is more useful than a best-effort cleanup failure.
+  }
+}
+
+export async function fetchImageBuffer(url, {
+  fetchImpl = fetch,
+  headers,
+  signal,
+  maxBytes = DEFAULT_MAX_IMAGE_BYTES,
+  timeoutMs = 15_000,
+  allowedHosts,
+} = {}) {
+  const target = new URL(url);
+  if (target.protocol !== 'https:') throw new Error('Image download URL must use HTTPS');
+  if (Array.isArray(allowedHosts) && !allowedHosts.some((rule) => (
+    typeof rule === 'string'
+    && (target.hostname === rule
+      || (rule.startsWith('.')
+        && (target.hostname === rule.slice(1) || target.hostname.endsWith(rule))))
+  ))) {
+    throw new Error('Image download URL is not hosted by the messaging platform');
+  }
+  const response = await fetchImpl(target, {
+    method: 'GET',
+    headers,
+    signal: requestSignal(signal, timeoutMs),
+    redirect: 'manual',
+  });
+  if (Number.isInteger(response?.status) && response.status >= 300 && response.status < 400) {
+    await cancelResponseBody(response);
+    throw new ImagePromptError(
+      'image-redirect-blocked',
+      `Image download redirect was blocked (HTTP ${response.status})`,
+      '图片下载地址发生了重定向，暂时无法读取。',
+    );
+  }
+  if (!response?.ok) {
+    await cancelResponseBody(response);
+    throw new ImagePromptError(
+      'image-http-error',
+      `Image download failed with HTTP ${response?.status ?? 'unknown'}`,
+      `图片下载失败（HTTP ${response?.status ?? 'unknown'}），请重新发送后再试。`,
+    );
+  }
+  const declaredLength = Number(response.headers?.get?.('content-length'));
+  if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+    await cancelResponseBody(response);
+    throw new ImagePromptError(
+      'image-too-large',
+      `Image response declares ${declaredLength} bytes; the limit is ${maxBytes}`,
+      '图片超过 5 MB，请压缩后重试。',
+    );
+  }
+
+  if (response.body?.[Symbol.asyncIterator]) {
+    const chunks = [];
+    let size = 0;
+    for await (const chunk of response.body) {
+      const data = Buffer.from(chunk);
+      size += data.length;
+      if (size > maxBytes) {
+        await response.body.cancel?.().catch?.(() => undefined);
+        throw new ImagePromptError(
+          'image-too-large',
+          `Image response exceeded ${maxBytes} bytes`,
+          '图片超过 5 MB，请压缩后重试。',
+        );
+      }
+      chunks.push(data);
+    }
+    return Buffer.concat(chunks, size);
+  }
+
+  const data = Buffer.from(await response.arrayBuffer());
+  if (data.length > maxBytes) {
+    throw new ImagePromptError(
+      'image-too-large',
+      `Image response contains ${data.length} bytes; the limit is ${maxBytes}`,
+      '图片超过 5 MB，请压缩后重试。',
+    );
+  }
+  return data;
+}
+
+function cleanText(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function imageSources(message) {
+  return Array.isArray(message?.images) ? message.images.filter(Boolean) : [];
+}
+
+function safeName(value) {
+  if (typeof value !== 'string') return undefined;
+  const name = value
+    .replaceAll('\\', '/')
+    .split('/')
+    .at(-1)
+    ?.replace(/[\u0000-\u001f\u007f]/g, '')
+    .trim()
+    .slice(0, 255);
+  return name || undefined;
+}
+
+function detectedImageMediaType(data) {
+  if (data.length >= 8
+    && data[0] === 0x89 && data[1] === 0x50 && data[2] === 0x4e && data[3] === 0x47
+    && data[4] === 0x0d && data[5] === 0x0a && data[6] === 0x1a && data[7] === 0x0a) {
+    return 'image/png';
+  }
+  if (data.length >= 3 && data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff) {
+    return 'image/jpeg';
+  }
+  if (data.length >= 6) {
+    const signature = data.subarray(0, 6).toString('ascii');
+    if (signature === 'GIF87a' || signature === 'GIF89a') return 'image/gif';
+  }
+  if (data.length >= 12
+    && data.subarray(0, 4).toString('ascii') === 'RIFF'
+    && data.subarray(8, 12).toString('ascii') === 'WEBP') {
+    return 'image/webp';
+  }
+  return null;
+}
+
+function loadedImage(value) {
+  if (Buffer.isBuffer(value) || value instanceof Uint8Array) {
+    return { data: Buffer.from(value) };
+  }
+  const raw = value?.data ?? value?.buffer;
+  if (Buffer.isBuffer(raw) || raw instanceof Uint8Array) {
+    return {
+      data: Buffer.from(raw),
+      name: value?.name ?? value?.filename,
+    };
+  }
+  return null;
+}
+
+export function hasInboundImages(message) {
+  return imageSources(message).length > 0;
+}
+
+export function hasInboundPrompt(message) {
+  return Boolean(cleanText(message?.content)) || hasInboundImages(message);
+}
+
+export async function promptContentForMessage(message, {
+  signal,
+  maxImageBytes = DEFAULT_MAX_IMAGE_BYTES,
+  maxImages = DEFAULT_MAX_IMAGES,
+  maxTotalImageBytes = DEFAULT_MAX_TOTAL_IMAGE_BYTES,
+} = {}) {
+  const sources = imageSources(message);
+  if (sources.length > maxImages) {
+    throw new ImagePromptError(
+      'too-many-images',
+      `Image message contains ${sources.length} images; the limit is ${maxImages}`,
+      `一次最多只能处理 ${maxImages} 张图片。`,
+    );
+  }
+
+  const text = cleanText(message?.content);
+  const content = [];
+  let totalImageBytes = 0;
+  if (text) content.push({ type: 'text', text });
+  else if (sources.length > 0) content.push({ type: 'text', text: DEFAULT_IMAGE_PROMPT });
+
+  for (const [index, source] of sources.entries()) {
+    signal?.throwIfAborted();
+    if (Number.isFinite(source?.size) && source.size > maxImageBytes) {
+      throw new ImagePromptError(
+        'image-too-large',
+        `Image ${index + 1} declares ${source.size} bytes; the limit is ${maxImageBytes}`,
+        '图片超过 5 MB，请压缩后重试。',
+      );
+    }
+    if (Number.isFinite(source?.size) && totalImageBytes + source.size > maxTotalImageBytes) {
+      throw new ImagePromptError(
+        'images-too-large',
+        `Images declare more than ${maxTotalImageBytes} bytes in total`,
+        '一次发送的图片总大小过大，请减少图片数量或压缩后重试。',
+      );
+    }
+
+    let result;
+    try {
+      result = source?.data === undefined
+        ? await source?.load?.({ signal, maxBytes: maxImageBytes })
+        : source.data;
+    } catch (error) {
+      if (signal?.aborted || error?.name === 'AbortError' || error?.name === 'TimeoutError') throw error;
+      if (error instanceof ImagePromptError) throw error;
+      throw new ImagePromptError(
+        'image-download-failed',
+        `Unable to download image ${index + 1}: ${error?.message ?? String(error)}`,
+        '图片下载失败，请重新发送后再试。',
+        { cause: error },
+      );
+    }
+    const loaded = loadedImage(result);
+    if (!loaded?.data.length) {
+      throw new ImagePromptError(
+        'invalid-image-data',
+        `Image ${index + 1} returned no data`,
+        '未能读取图片内容，请重新发送。',
+      );
+    }
+    if (loaded.data.length > maxImageBytes) {
+      throw new ImagePromptError(
+        'image-too-large',
+        `Image ${index + 1} contains ${loaded.data.length} bytes; the limit is ${maxImageBytes}`,
+        '图片超过 5 MB，请压缩后重试。',
+      );
+    }
+    if (totalImageBytes + loaded.data.length > maxTotalImageBytes) {
+      throw new ImagePromptError(
+        'images-too-large',
+        `Images contain more than ${maxTotalImageBytes} bytes in total`,
+        '一次发送的图片总大小过大，请减少图片数量或压缩后重试。',
+      );
+    }
+    totalImageBytes += loaded.data.length;
+    const mediaType = detectedImageMediaType(loaded.data);
+    if (!mediaType) {
+      throw new ImagePromptError(
+        'unsupported-image-type',
+        `Image ${index + 1} is not JPEG, PNG, GIF, or WebP`,
+        '暂不支持该图片格式，请发送 JPEG、PNG、WebP 或 GIF 图片。',
+      );
+    }
+    content.push({
+      type: 'image',
+      mediaType,
+      data: loaded.data.toString('base64'),
+      ...(safeName(loaded.name ?? source?.name) ? { name: safeName(loaded.name ?? source?.name) } : {}),
+    });
+  }
+  return content;
+}
+
+export function imagePromptUserMessage(error) {
+  return error instanceof ImagePromptError ? error.userMessage : null;
+}

package/src/channels/shared/text-harness-bridge.mjs

@@ -2,6 +2,11 @@ import { runWorkspaceCommand } from './workspace-command.mjs';
 import { runCompactCommand } from './compact-command.mjs';
 import { askInWorkspaceSession } from './workspace-session.mjs';
 import { HarnessApprovalQueue } from './harness-approval.mjs';
+import {
+  hasInboundImages,
+  imagePromptUserMessage,
+  promptContentForMessage,
+} from './image-prompt.mjs';
 import {
   harnessAnswerForQuestion,
   harnessQuestionText,
@@ -17,6 +22,7 @@ function cleanText(value) {
 function canClaimInteractionReply(message, pending, senderId) {
   return pending.actor === senderId
     && (message.kind !== 'group' || message.addressed === true)
+    && !hasInboundImages(message)
     && Boolean(cleanText(message.content));
 }
 
@@ -98,7 +104,7 @@ export class TextHarnessBridge {
       key,
       actor: senderId,
       messageId,
-      text: normalized.content,
+      text: hasInboundImages(normalized) ? '' : normalized.content,
       addressed: normalized.kind !== 'group' || normalized.addressed === true,
       hasPendingQuestion: Boolean(pending),
       questionCompletion: pending?.submitting || pending?.claimedReplyMessageId
@@ -208,16 +214,17 @@ export class TextHarnessBridge {
         this.#status.lastRejectedAt = new Date().toISOString();
         return;
       }
-      if (!text) {
-        await this.#bot.sendText(target, '目前仅支持文字消息。');
+      const hasImages = hasInboundImages(message);
+      if (!text && !hasImages) {
+        await this.#bot.sendText(target, '目前支持文字和图片消息。');
         return;
       }
       const command = text.toLowerCase();
-      if (command === '/help') {
+      if (!hasImages && command === '/help') {
         await this.#bot.sendText(target, [
           `${this.#descriptor.label}机器人已连接 DeepSeek Harness。`,
           '',
-          '直接发送文字即可继续当前会话。',
+          '直接发送文字或图片即可继续当前会话。',
           '/new  开启一个全新会话',
           '/compact  压缩当前会话的较早上下文',
           '/workspace 工作区绝对路径  切换工作区',
@@ -229,30 +236,34 @@ export class TextHarnessBridge {
         ].join('\n'));
         return;
       }
-      if (command === '/status') {
+      if (!hasImages && command === '/status') {
         await this.#harness.ensureRunning({ signal: this.#signal });
         await this.#bot.sendText(target, `${this.#descriptor.label}机器人与 DeepSeek Harness 连接正常。`);
         return;
       }
-      const workspaceCommand = await runWorkspaceCommand(text, this.#harness, conversationKey);
+      const workspaceCommand = !hasImages
+        ? await runWorkspaceCommand(text, this.#harness, conversationKey)
+        : null;
       if (workspaceCommand) {
         for (const reply of workspaceCommand.messages ?? [workspaceCommand.message]) {
           await this.#bot.sendText(target, reply);
         }
         return;
       }
-      if (command === '/new') {
+      if (!hasImages && command === '/new') {
         await this.#state.clearSession(conversationKey);
         await this.#bot.sendText(target, '已开启新会话。请发送你的问题。');
         return;
       }
-      const compactCommand = await runCompactCommand(
-        text,
-        this.#harness,
-        this.#state,
-        conversationKey,
-        { signal: this.#signal },
-      );
+      const compactCommand = !hasImages
+        ? await runCompactCommand(
+            text,
+            this.#harness,
+            this.#state,
+            conversationKey,
+            { signal: this.#signal },
+          )
+        : null;
       if (compactCommand) {
         await this.#bot.sendText(target, compactCommand.message);
         return;
@@ -272,11 +283,15 @@ export class TextHarnessBridge {
           );
         }
       }
+      const content = hasImages
+        ? await promptContentForMessage(message, { signal: this.#signal })
+        : undefined;
       const { answer } = await askInWorkspaceSession({
         harness: this.#harness,
         state: this.#state,
         key: conversationKey,
         text,
+        content,
         createOptions: this.#signal ? { signal: this.#signal } : undefined,
         existsOptions: this.#signal ? { signal: this.#signal } : undefined,
         askOptions: {
@@ -316,6 +331,18 @@ export class TextHarnessBridge {
       stream?.cancel?.();
       if (this.#signal?.aborted) return;
       this.#status.lastError = error?.message ?? String(error);
+      const imageErrorMessage = imagePromptUserMessage(error);
+      if (imageErrorMessage) {
+        try {
+          await this.#bot.sendText(target, imageErrorMessage);
+        } catch (sendError) {
+          this.#logger.error?.(
+            `[dsh-im:${this.#descriptor.key}] failed to send the image error reply:`,
+            sendError,
+          );
+        }
+        return;
+      }
       this.#logger.error?.(`[dsh-im:${this.#descriptor.key}] failed to process a message:`, error);
       try {
         await this.#bot.sendText(target, '消息处理失败，请稍后重试。');
@@ -358,7 +385,7 @@ export class TextHarnessBridge {
 
     const target = message.replyTarget;
     const text = cleanText(message.content);
-    if (!text) {
+    if (!text || hasInboundImages(message)) {
       try {
         await this.#bot.sendText(target, '请用文字回答当前问题。');
       } catch (error) {

package/src/channels/shared/workspace-session.mjs

@@ -33,6 +33,7 @@ export async function askInWorkspaceSession({
   state,
   key,
   text,
+  content,
   createOptions,
   existsOptions,
   askOptions,
@@ -48,7 +49,7 @@ export async function askInWorkspaceSession({
       }
       return {
         sessionId,
-        answer: await session.ask(text, askOptions),
+        answer: await session.ask(content ?? text, askOptions),
       };
     } catch (error) {
       if (error?.code !== WORKSPACE_SESSION_STALE) throw error;

package/src/channels/slack/manifest.mjs

@@ -17,6 +17,7 @@ oauth_config:
     bot:
       - app_mentions:read
       - chat:write
+      - files:read
       - im:history
 settings:
   event_subscriptions:

package/src/channels/slack/slack-api.mjs

@@ -1,4 +1,10 @@
+import { fetchImageBuffer, ImagePromptError } from '../shared/image-prompt.mjs';
+
 const DEFAULT_BASE_URL = 'https://slack.com/api/';
+const SLACK_FILE_HOST = 'files.slack.com';
+const LEGACY_SLACK_FILE_HOST = 'slack.com';
+const SLACK_FILE_PATH_PREFIX = '/files-pri/';
+const SLACK_FILE_HOSTS = Object.freeze([SLACK_FILE_HOST]);
 
 function cleanString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
@@ -9,6 +15,61 @@ function requestSignal(signal, timeoutMs) {
   return signal ? AbortSignal.any([signal, timeout]) : timeout;
 }
 
+function isRedirectStatus(status) {
+  return Number.isInteger(status) && status >= 300 && status < 400;
+}
+
+async function cancelResponseBody(response) {
+  try {
+    await response?.body?.cancel?.();
+  } catch {
+    // Preserve the download failure when response cleanup also fails.
+  }
+}
+
+function secureSlackFileUrl(value) {
+  const url = new URL(value);
+  if (url.protocol !== 'https:') throw new Error('Image download URL must use HTTPS');
+  if (url.username || url.password || (url.port && url.port !== '443')) {
+    throw new Error('Image download URL is not hosted by the messaging platform');
+  }
+  if (url.hostname === LEGACY_SLACK_FILE_HOST && url.pathname.startsWith(SLACK_FILE_PATH_PREFIX)) {
+    url.hostname = SLACK_FILE_HOST;
+  }
+  if (url.hostname !== SLACK_FILE_HOST || !url.pathname.startsWith(SLACK_FILE_PATH_PREFIX)) {
+    throw new Error('Image download URL is not hosted by the messaging platform');
+  }
+  url.hash = '';
+  return url;
+}
+
+function redirectUrl(response, source) {
+  const location = response?.headers?.get?.('location');
+  if (!location) return null;
+  try {
+    return new URL(location, source);
+  } catch {
+    return null;
+  }
+}
+
+function responseOAuthScopes(response) {
+  const raw = response?.headers?.get?.('x-oauth-scopes');
+  if (raw === null || raw === undefined) return null;
+  return new Set(raw.split(',').map((scope) => scope.trim()).filter(Boolean));
+}
+
+function isSlackWorkspaceRedirect(target) {
+  return target?.protocol === 'https:'
+    && !target.username
+    && !target.password
+    && (!target.port || target.port === '443')
+    && target.hostname.endsWith('.slack.com')
+    && target.hostname !== SLACK_FILE_HOST
+    && target.pathname === '/'
+    && target.searchParams.has('redir');
+}
+
 function delay(ms, signal) {
   return new Promise((resolve, reject) => {
     if (signal?.aborted) {
@@ -79,6 +140,7 @@ export class SlackApi {
   #appToken;
   #fetch;
   #baseUrl;
+  #botScopes = null;
 
   constructor({ botToken, appToken, fetchImpl = fetch, baseUrl = DEFAULT_BASE_URL }) {
     if (botToken !== undefined && !validSlackBotToken(botToken)) {
@@ -177,6 +239,34 @@ export class SlackApi {
     });
   }
 
+  async downloadFile({ url, signal, maxBytes }) {
+    if (!this.#botToken) throw new TypeError('Slack bot token is required for file download');
+    const target = secureSlackFileUrl(url);
+    const fetchSlackFile = async (requestUrl, options) => {
+      const response = await this.#fetch(requestUrl, options);
+      if (!isRedirectStatus(response?.status)) return response;
+
+      const next = redirectUrl(response, requestUrl);
+      if ((this.#botScopes && !this.#botScopes.has('files:read'))
+        || isSlackWorkspaceRedirect(next)) {
+        await cancelResponseBody(response);
+        throw new ImagePromptError(
+          'slack-file-access-required',
+          'Slack redirected a private file request to the workspace because file access was not granted',
+          'Slack 未授权机器人读取该文件。请为应用添加 files:read 后重新安装，再重新发送图片。',
+        );
+      }
+      return response;
+    };
+    return fetchImageBuffer(target, {
+      fetchImpl: fetchSlackFile,
+      headers: { authorization: `Bearer ${this.#botToken}` },
+      signal,
+      maxBytes,
+      allowedHosts: SLACK_FILE_HOSTS,
+    });
+  }
+
   async #request(method, {
     tokenKind,
     body,
@@ -206,6 +296,11 @@ export class SlackApi {
       throw new Error(`Slack ${method} transport failed`);
     }
 
+    if (tokenKind === 'bot') {
+      const scopes = responseOAuthScopes(response);
+      if (scopes) this.#botScopes = scopes;
+    }
+
     let payload;
     try {
       payload = await response.json();

package/src/channels/slack/slack-runtime.mjs

@@ -5,6 +5,7 @@ import { createSlackBridgeStatus, SlackHarnessBridge } from './slack-bridge.mjs'
 const RECONNECT_DELAYS_MS = Object.freeze([1_000, 3_000, 5_000, 10_000, 30_000]);
 const SLACK_MESSAGE_LIMIT = 38_000;
 const SLACK_STREAM_CHUNK_LIMIT = 11_000;
+const IMAGE_MEDIA_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp', 'image/gif']);
 
 function addSocketListener(socket, event, listener) {
   if (typeof socket.addEventListener === 'function') socket.addEventListener(event, listener);
@@ -42,13 +43,28 @@ function stripBotMention(value, botUserId) {
     .trim();
 }
 
-export function normalizeSlackEvent(payload, botUserId) {
+function slackImageSource(file, loadFile) {
+  const mediaType = typeof file?.mimetype === 'string' ? file.mimetype.toLowerCase() : '';
+  const url = typeof file?.url_private_download === 'string' && file.url_private_download
+    ? file.url_private_download : file?.url_private;
+  if (!IMAGE_MEDIA_TYPES.has(mediaType) || typeof url !== 'string' || !url) return null;
+  return {
+    name: typeof file.name === 'string' ? file.name : undefined,
+    mediaType,
+    size: Number.isSafeInteger(file.size) && file.size >= 0 ? file.size : undefined,
+    load: (options) => loadFile(url, options),
+  };
+}
+
+export function normalizeSlackEvent(payload, botUserId, { loadFile = async () => {
+  throw new Error('Slack file downloader is unavailable');
+} } = {}) {
   const event = payload?.event;
   if (!event || !payload?.event_id || !event.channel || !event.user || !event.ts) return null;
   const direct = event.type === 'message' && event.channel_type === 'im';
   const mentioned = event.type === 'app_mention';
   if (!direct && !mentioned) return null;
-  if (event.subtype || event.bot_id || event.app_id) return null;
+  if ((event.subtype && event.subtype !== 'file_share') || event.bot_id || event.app_id) return null;
   const threadTs = String(event.thread_ts ?? event.ts);
   return {
     messageId: String(payload.event_id),
@@ -57,6 +73,9 @@ export function normalizeSlackEvent(payload, botUserId) {
     kind: direct ? 'direct' : 'group',
     conversationId: direct ? String(event.channel) : `${event.channel}:${threadTs}`,
     content: stripBotMention(event.text ?? '', botUserId),
+    images: Array.isArray(event.files)
+      ? event.files.map((file) => slackImageSource(file, loadFile)).filter(Boolean)
+      : [],
     addressed: direct || mentioned,
     replyTarget: {
       channelId: String(event.channel),
@@ -389,7 +408,9 @@ export class SlackRuntime {
         if (packet.type !== 'events_api' || packet.payload?.type !== 'event_callback') return;
         if (this.#appId && packet.payload.api_app_id
           && packet.payload.api_app_id !== this.#appId) return;
-        const message = normalizeSlackEvent(packet.payload, this.#config.platformId.split(':')[1]);
+        const message = normalizeSlackEvent(packet.payload, this.#config.platformId.split(':')[1], {
+          loadFile: (url, options) => this.#api.downloadFile({ url, ...options }),
+        });
         const bridge = this.#bridge;
         if (message && bridge) {
           void bridge.accept(message).catch((error) => {

package/src/channels/telegram/telegram-api.mjs

@@ -1,4 +1,7 @@
+import { fetchImageBuffer } from '../shared/image-prompt.mjs';
+
 const DEFAULT_BASE_URL = 'https://api.telegram.org/';
+const TELEGRAM_FILE_HOSTS = Object.freeze(['api.telegram.org']);
 
 function cleanString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
@@ -47,6 +50,40 @@ export class TelegramApi {
     });
   }
 
+  async getFile({ fileId, signal } = {}) {
+    const id = cleanString(fileId);
+    if (!id || !/^[A-Za-z0-9_-]{1,512}$/.test(id)) {
+      throw new TypeError('Telegram file id is invalid');
+    }
+    return this.#call('getFile', { file_id: id }, { signal });
+  }
+
+  async downloadFile({ fileId, signal, maxBytes } = {}) {
+    const file = await this.getFile({ fileId, signal });
+    const filePath = cleanString(file?.file_path);
+    if (!filePath || filePath.startsWith('/') || filePath.includes('\\')
+      || filePath.includes('?') || filePath.includes('#')) {
+      throw new Error('Telegram returned an invalid file path');
+    }
+    let decodedSegments;
+    try {
+      decodedSegments = filePath.split('/').map((segment) => decodeURIComponent(segment));
+    } catch {
+      throw new Error('Telegram returned an invalid file path');
+    }
+    if (decodedSegments.some((segment) => !segment || segment === '.' || segment === '..')) {
+      throw new Error('Telegram returned an invalid file path');
+    }
+    const url = new URL(this.#baseUrl);
+    url.pathname = `/file/bot${this.#token}/${filePath}`;
+    return fetchImageBuffer(url, {
+      fetchImpl: this.#fetch,
+      signal,
+      maxBytes,
+      allowedHosts: TELEGRAM_FILE_HOSTS,
+    });
+  }
+
   async sendMessage({ chatId, text, replyToMessageId, messageThreadId, signal }) {
     return this.#call('sendMessage', {
       chat_id: chatId,