skyloom 1.21.0 → 1.23.0

package/src/gateway/channels/feishu.ts

@@ -14,9 +14,10 @@
  */
 
 import * as crypto from 'crypto';
+import axios from 'axios';
 import { getLogger } from '../../core/logger';
-import { resolveSecret, postJson, TokenCache } from '../helpers';
-import type { ChannelAdapter, RawRequest, ReplyTarget, WebhookOutcome } from '../types';
+import { resolveSecret, postJson, postMultipart, loadMedia, TokenCache } from '../helpers';
+import type { ChannelAdapter, InboundMessage, MediaAttachment, OutboundMedia, RawRequest, ReplyTarget, WebhookOutcome } from '../types';
 
 const log = getLogger('channel-feishu');
 
@@ -43,6 +44,10 @@ export function createFeishuAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAd
   const encryptKey = resolveSecret(cfg.encryptKey, env, 'FEISHU_ENCRYPT_KEY');
   const verificationToken = resolveSecret(cfg.verificationToken, env, 'FEISHU_VERIFICATION_TOKEN');
   const base = cfg.domain === 'lark' ? 'https://open.larksuite.com' : 'https://open.feishu.cn';
+  // 'card' replies render as an interactive card (supports streaming patches);
+  // 'raw' forces plain text; 'auto' (default) uses a card so streaming works.
+  const renderMode: 'auto' | 'raw' | 'card' = cfg.renderMode || 'auto';
+  const useCard = renderMode === 'card' || renderMode === 'auto';
 
   const tokenCache = new TokenCache(async () => {
     const data = await postJson(`${base}/open-apis/auth/v3/tenant_access_token/internal`, {
@@ -52,6 +57,36 @@ export function createFeishuAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAd
     return { token: data.tenant_access_token, expiresInSec: data.expire ?? 7200 };
   });
 
+  const authHeader = async () => ({ Authorization: `Bearer ${await tokenCache.get()}` });
+  const onTokenError = (code: number) => { if (code === 99991663 || code === 99991661) tokenCache.invalidate(); };
+
+  /** A minimal interactive card carrying a single markdown body. */
+  const cardContent = (text: string): string => JSON.stringify({
+    config: { wide_screen_mode: true, update_multi: true },
+    elements: [{ tag: 'markdown', content: text || ' ' }],
+  });
+
+  /** Create a card message in a chat; returns its message_id for later patches. */
+  const createCard = async (chatId: string, text: string): Promise<string | null> => {
+    const data = await postJson(
+      `${base}/open-apis/im/v1/messages?receive_id_type=chat_id`,
+      { receive_id: chatId, msg_type: 'interactive', content: cardContent(text) },
+      { headers: await authHeader() },
+    );
+    if (data.code !== 0) { onTokenError(data.code); throw new Error(`feishu card create ${data.code}: ${data.msg}`); }
+    return data.data?.message_id || null;
+  };
+
+  /** Patch an existing card message with new content. */
+  const patchCard = async (messageId: string, text: string): Promise<void> => {
+    const data = await postJson(
+      `${base}/open-apis/im/v1/messages/${messageId}`,
+      { content: cardContent(text) },
+      { headers: await authHeader() },
+    ).catch((e) => ({ code: -1, msg: String(e) }));
+    if (data && data.code !== 0) onTokenError(data.code);
+  };
+
   // De-dupe redelivered events (Feishu retries on slow ack).
   const seen = new Set<string>();
   const remember = (id: string): boolean => {
@@ -103,12 +138,45 @@ export function createFeishuAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAd
       const chatId = message.chat_id as string;
       const msgType = message.message_type as string;
       let text = '';
-      if (msgType === 'text') {
-        try { text = JSON.parse(message.content || '{}').text || ''; } catch { text = ''; }
-        // Strip @mentions like "@_user_1 ".
-        text = text.replace(/@_user_\d+/g, '').trim();
-      } else {
-        text = `[${msgType} 消息]`;
+      const media: MediaAttachment[] = [];
+      let content: any = {};
+      try { content = JSON.parse(message.content || '{}'); } catch { /* ignore */ }
+      switch (msgType) {
+        case 'text':
+          text = (content.text || '').replace(/@_user_\d+/g, '').trim(); // strip @mentions
+          break;
+        case 'image':
+          media.push({ kind: 'image', ref: content.image_key });
+          break;
+        case 'audio':
+          media.push({ kind: 'audio', ref: content.file_key });
+          break;
+        case 'media': // short video
+          media.push({ kind: 'video', ref: content.file_key, filename: content.file_name });
+          break;
+        case 'file':
+          media.push({ kind: 'file', ref: content.file_key, filename: content.file_name });
+          break;
+        case 'sticker':
+          media.push({ kind: 'sticker', ref: content.file_key });
+          break;
+        case 'post': { // rich text: pull plain text + embedded images
+          const blocks = content?.content;
+          if (Array.isArray(blocks)) {
+            for (const row of blocks) {
+              for (const el of row || []) {
+                if (el?.tag === 'text' && el.text) text += el.text;
+                else if (el?.tag === 'a' && el.text) text += el.text;
+                else if (el?.tag === 'img' && el.image_key) media.push({ kind: 'image', ref: el.image_key });
+              }
+              text += '\n';
+            }
+          }
+          text = text.trim();
+          break;
+        }
+        default:
+          text = `[${msgType} 消息]`;
       }
       const senderId = payload.event?.sender?.sender_id?.open_id || payload.event?.sender?.sender_id?.user_id || 'unknown';
 
@@ -118,6 +186,7 @@ export function createFeishuAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAd
           conversationId: chatId || senderId,
           userId: senderId,
           text,
+          media: media.length ? media : undefined,
           replyTo: { channel: 'feishu', chatId },
           raw: payload,
         },
@@ -127,16 +196,94 @@ export function createFeishuAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAd
     async send(target: ReplyTarget, text: string): Promise<void> {
       const chatId = target.chatId as string;
       if (!chatId) return;
-      const token = await tokenCache.get();
+      if (useCard) { await createCard(chatId, text); return; }
       const data = await postJson(
         `${base}/open-apis/im/v1/messages?receive_id_type=chat_id`,
         { receive_id: chatId, msg_type: 'text', content: JSON.stringify({ text }) },
-        { headers: { Authorization: `Bearer ${token}` } },
+        { headers: await authHeader() },
       );
-      if (data.code !== 0) {
-        if (data.code === 99991663 || data.code === 99991661) tokenCache.invalidate(); // token expired
-        throw new Error(`feishu send error ${data.code}: ${data.msg}`);
+      if (data.code !== 0) { onTokenError(data.code); throw new Error(`feishu send error ${data.code}: ${data.msg}`); }
+    },
+
+    // Streaming reply: post a placeholder card, then patch it as text arrives —
+    // throttled (≥600ms apart) to stay well under Feishu's update rate limit.
+    async sendStreaming(target: ReplyTarget, chunks: AsyncIterable<string>): Promise<void> {
+      const chatId = target.chatId as string;
+      if (!chatId) return;
+      if (!useCard) { // plain-text mode can't patch; collect then send once
+        let all = '';
+        for await (const c of chunks) all += c;
+        await this.send(target, all.trim() || '(无回复)');
+        return;
       }
+      let messageId: string | null = null;
+      let acc = '';
+      let lastPatch = 0;
+      let dirty = false;
+      const MIN_INTERVAL = 600;
+      try {
+        messageId = await createCard(chatId, '思考中…');
+      } catch (e) { log.warn('feishu_card_create_failed', { error: String(e) }); return; }
+      if (!messageId) return;
+
+      for await (const chunk of chunks) {
+        acc += chunk;
+        dirty = true;
+        const now = Date.now();
+        if (now - lastPatch >= MIN_INTERVAL) {
+          lastPatch = now;
+          dirty = false;
+          await patchCard(messageId, acc);
+        }
+      }
+      // Final flush so the last tokens always land.
+      if (dirty || acc) await patchCard(messageId, acc.trim() || '(无回复)');
+    },
+
+    async sendMedia(target: ReplyTarget, item: OutboundMedia): Promise<void> {
+      const chatId = target.chatId as string;
+      if (!chatId) return;
+      const loaded = await loadMedia(item.src);
+      const headers = await authHeader();
+
+      if (item.kind === 'image') {
+        const up = await postMultipart(`${base}/open-apis/im/v1/images`, {
+          image_type: 'message',
+          image: { data: loaded.data, filename: loaded.filename || 'image', contentType: loaded.contentType || 'image/png' },
+        }, { headers });
+        if (up.code !== 0) { onTokenError(up.code); throw new Error(`feishu image upload ${up.code}: ${up.msg}`); }
+        const imageKey = up.data?.image_key;
+        const send = await postJson(`${base}/open-apis/im/v1/messages?receive_id_type=chat_id`,
+          { receive_id: chatId, msg_type: 'image', content: JSON.stringify({ image_key: imageKey }) },
+          { headers });
+        if (send.code !== 0) { onTokenError(send.code); throw new Error(`feishu image send ${send.code}: ${send.msg}`); }
+        return;
+      }
+
+      // file: upload to im/v1/files then send a file message
+      const up = await postMultipart(`${base}/open-apis/im/v1/files`, {
+        file_type: 'stream',
+        file_name: loaded.filename || 'file',
+        file: { data: loaded.data, filename: loaded.filename || 'file', contentType: loaded.contentType || 'application/octet-stream' },
+      }, { headers });
+      if (up.code !== 0) { onTokenError(up.code); throw new Error(`feishu file upload ${up.code}: ${up.msg}`); }
+      const fileKey = up.data?.file_key;
+      const send = await postJson(`${base}/open-apis/im/v1/messages?receive_id_type=chat_id`,
+        { receive_id: chatId, msg_type: 'file', content: JSON.stringify({ file_key: fileKey }) },
+        { headers });
+      if (send.code !== 0) { onTokenError(send.code); throw new Error(`feishu file send ${send.code}: ${send.msg}`); }
+    },
+
+    async fetchMedia(att: MediaAttachment, msg: InboundMessage): Promise<{ data: Buffer; contentType?: string } | null> {
+      const messageId = (msg.raw as any)?.event?.message?.message_id;
+      if (!messageId || !att.ref) return null;
+      const token = await tokenCache.get();
+      const res = await axios.get(
+        `${base}/open-apis/im/v1/messages/${messageId}/resources/${att.ref}?type=${att.kind === 'image' ? 'image' : 'file'}`,
+        { headers: { Authorization: `Bearer ${token}` }, responseType: 'arraybuffer', timeout: 30000, validateStatus: (s) => s >= 200 && s < 300 },
+      );
+      const ct = res.headers['content-type'];
+      return { data: Buffer.from(res.data), contentType: typeof ct === 'string' ? ct : undefined };
     },
   };
 }

package/src/gateway/channels/qq.ts

@@ -17,8 +17,8 @@
 
 import * as crypto from 'crypto';
 import { getLogger } from '../../core/logger';
-import { resolveSecret, postJson, TokenCache } from '../helpers';
-import type { ChannelAdapter, RawRequest, ReplyTarget, WebhookOutcome } from '../types';
+import { resolveSecret, postJson, loadMedia, TokenCache } from '../helpers';
+import type { ChannelAdapter, MediaAttachment, OutboundMedia, RawRequest, ReplyTarget, WebhookOutcome } from '../types';
 
 const log = getLogger('channel-qq');
 
@@ -102,7 +102,17 @@ export function createQQAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAdapte
       else if (t === 'C2C_MESSAGE_CREATE') replyTo = { channel: 'qq', kind: 'c2c', userOpenid: d.author?.user_openid, msgId };
       else if (t === 'AT_MESSAGE_CREATE' || t === 'MESSAGE_CREATE') replyTo = { channel: 'qq', kind: 'channel', channelId: d.channel_id, msgId };
 
-      if (!replyTo || !content) return { response: { status: 200, body: '' } };
+      // QQ delivers images/files as an attachments array on the event.
+      const media: MediaAttachment[] = [];
+      for (const att of (Array.isArray(d.attachments) ? d.attachments : [])) {
+        const ct = String(att?.content_type || '');
+        const kind: MediaAttachment['kind'] = ct.startsWith('image') ? 'image'
+          : ct.startsWith('audio') || ct.startsWith('voice') ? 'audio'
+          : ct.startsWith('video') ? 'video' : 'file';
+        media.push({ kind, ref: att?.id, filename: att?.filename, mimeType: att?.content_type, url: att?.url });
+      }
+
+      if (!replyTo || (!content && media.length === 0)) return { response: { status: 200, body: '' } };
 
       const userId = d.author?.user_openid || d.author?.id || d.author?.member_openid || 'unknown';
       return {
@@ -112,6 +122,7 @@ export function createQQAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAdapte
           conversationId: (replyTo.groupOpenid as string) || (replyTo.channelId as string) || (userId as string),
           userId,
           text: content,
+          media: media.length ? media : undefined,
           replyTo,
           raw: payload,
         },
@@ -136,5 +147,46 @@ export function createQQAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAdapte
         throw new Error(`qq send error: ${e?.response?.status || ''} ${String(e?.message || e).slice(0, 120)}`);
       }
     },
+
+    // QQ's v2 rich-media flow takes a URL (the platform fetches it): POST
+    // /files → file_info, then send msg_type:7 referencing that file_info.
+    // Group/C2C only; raw local bytes aren't supported, so the src must be a URL.
+    async sendMedia(target: ReplyTarget, item: OutboundMedia): Promise<void> {
+      if (!/^https?:\/\//i.test(item.src)) {
+        throw new Error('qq sendMedia requires an http(s) URL (platform fetches it)');
+      }
+      const base = target.kind === 'group'
+        ? `https://api.sgroup.qq.com/v2/groups/${target.groupOpenid}`
+        : target.kind === 'c2c'
+          ? `https://api.sgroup.qq.com/v2/users/${target.userOpenid}`
+          : null;
+      if (!base) throw new Error('qq sendMedia unsupported for channel target');
+      const headers = { ...(await authHeaders()), 'Content-Type': 'application/json' };
+      // file_type: 1=image 2=video 3=audio 4=file
+      const fileType = item.kind === 'image' ? 1 : 4;
+      let fileInfo: string;
+      try {
+        const up = await postJson(`${base}/files`, { file_type: fileType, url: item.src, srv_send_msg: false }, { headers });
+        fileInfo = up.file_info;
+      } catch (e: any) {
+        if (e?.response?.status === 401) tokenCache.invalidate();
+        throw new Error(`qq file upload error: ${e?.response?.status || ''} ${String(e?.message || e).slice(0, 120)}`);
+      }
+      const payload: any = { msg_type: 7, media: { file_info: fileInfo } };
+      if (target.msgId) payload.msg_id = target.msgId;
+      await postJson(`${base}/messages`, payload, { headers });
+    },
+
+    async fetchMedia(att: MediaAttachment): Promise<{ data: Buffer; contentType?: string } | null> {
+      // QQ delivers attachments with a direct URL — just download it.
+      if (!att.url) return null;
+      try {
+        const loaded = await loadMedia(att.url);
+        return { data: loaded.data, contentType: loaded.contentType || att.mimeType };
+      } catch (e) {
+        log.warn('qq_media_fetch_failed', { error: String(e) });
+        return null;
+      }
+    },
   };
 }

package/src/gateway/channels/wecom.ts

@@ -16,9 +16,10 @@
  */
 
 import * as crypto from 'crypto';
+import axios from 'axios';
 import { getLogger } from '../../core/logger';
-import { resolveSecret, postJson, getJson, TokenCache } from '../helpers';
-import type { ChannelAdapter, RawRequest, ReplyTarget, WebhookOutcome } from '../types';
+import { resolveSecret, postJson, getJson, postMultipart, loadMedia, TokenCache } from '../helpers';
+import type { ChannelAdapter, MediaAttachment, OutboundMedia, RawRequest, ReplyTarget, WebhookOutcome } from '../types';
 
 const log = getLogger('channel-wecom');
 
@@ -108,17 +109,26 @@ export function createWecomAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAda
       const msgType = xmlField(inner, 'MsgType');
       const fromUser = xmlField(inner, 'FromUserName');
       let text = '';
-      if (msgType === 'text') text = xmlField(inner, 'Content').trim();
-      else text = `[${msgType} 消息]`;
+      const media: MediaAttachment[] = [];
+      switch (msgType) {
+        case 'text': text = xmlField(inner, 'Content').trim(); break;
+        case 'image': media.push({ kind: 'image', ref: xmlField(inner, 'MediaId'), url: xmlField(inner, 'PicUrl') || undefined }); break;
+        case 'voice': media.push({ kind: 'audio', ref: xmlField(inner, 'MediaId'), filename: xmlField(inner, 'MediaId') + '.' + (xmlField(inner, 'Format') || 'amr') }); break;
+        case 'video': media.push({ kind: 'video', ref: xmlField(inner, 'MediaId') }); break;
+        case 'file': media.push({ kind: 'file', ref: xmlField(inner, 'MediaId'), filename: xmlField(inner, 'FileName') || undefined }); break;
+        case 'location': text = `[位置] ${xmlField(inner, 'Label')} (${xmlField(inner, 'Location_X')},${xmlField(inner, 'Location_Y')})`; break;
+        default: text = `[${msgType} 消息]`;
+      }
 
       // Ack the callback immediately (empty 200); reply is pushed via the API.
       return {
         response: { status: 200, body: '' },
-        message: text ? {
+        message: (text || media.length) ? {
           channel: 'wecom',
           conversationId: fromUser,
           userId: fromUser,
           text,
+          media: media.length ? media : undefined,
           replyTo: { channel: 'wecom', toUser: fromUser },
           raw: inner,
         } : undefined,
@@ -138,5 +148,49 @@ export function createWecomAdapter(cfg: any, env: NodeJS.ProcessEnv): ChannelAda
         throw new Error(`wecom send error ${data.errcode}: ${data.errmsg}`);
       }
     },
+
+    async sendMedia(target: ReplyTarget, item: OutboundMedia): Promise<void> {
+      const toUser = target.toUser as string;
+      if (!toUser || !agentId) return;
+      const loaded = await loadMedia(item.src);
+      const accessToken = await tokenCache.get();
+      const type = item.kind === 'image' ? 'image' : 'file';
+      // Upload to the temporary-media store (valid 3 days), then push by media_id.
+      const up = await postMultipart(
+        `https://qyapi.weixin.qq.com/cgi-bin/media/upload?access_token=${encodeURIComponent(accessToken)}&type=${type}`,
+        { media: { data: loaded.data, filename: loaded.filename || (type === 'image' ? 'image.png' : 'file'), contentType: loaded.contentType } },
+      );
+      if (up.errcode && up.errcode !== 0) {
+        if (up.errcode === 42001 || up.errcode === 40014) tokenCache.invalidate();
+        throw new Error(`wecom media upload ${up.errcode}: ${up.errmsg}`);
+      }
+      const mediaId = up.media_id;
+      const body: any = { touser: toUser, msgtype: type, agentid: Number(agentId) };
+      body[type] = { media_id: mediaId };
+      const send = await postJson(
+        `https://qyapi.weixin.qq.com/cgi-bin/message/send?access_token=${encodeURIComponent(accessToken)}`,
+        body,
+      );
+      if (send.errcode !== 0) {
+        if (send.errcode === 42001 || send.errcode === 40014) tokenCache.invalidate();
+        throw new Error(`wecom media send ${send.errcode}: ${send.errmsg}`);
+      }
+    },
+
+    async fetchMedia(att: MediaAttachment): Promise<{ data: Buffer; contentType?: string } | null> {
+      if (!att.ref) return null;
+      const accessToken = await tokenCache.get();
+      const res = await axios.get(
+        `https://qyapi.weixin.qq.com/cgi-bin/media/get?access_token=${encodeURIComponent(accessToken)}&media_id=${encodeURIComponent(att.ref)}`,
+        { responseType: 'arraybuffer', timeout: 30000, validateStatus: (s) => s >= 200 && s < 300 },
+      );
+      // An error comes back as JSON, not the binary — detect and bail.
+      const ct = res.headers['content-type'];
+      if (typeof ct === 'string' && ct.includes('application/json')) {
+        log.warn('wecom_media_get_failed', { body: Buffer.from(res.data).toString('utf8').slice(0, 120) });
+        return null;
+      }
+      return { data: Buffer.from(res.data), contentType: typeof ct === 'string' ? ct : undefined };
+    },
   };
 }

package/src/gateway/gateway.ts

@@ -16,7 +16,11 @@ import { createServer, IncomingMessage, ServerResponse } from 'http';
 import { getLogger } from '../core/logger';
 import { createSystemContext } from '../core/factory';
 import { buildAdapters } from './registry';
+import { describeMedia, parseReply } from './types';
+import { isSendableSrc } from './helpers';
+import { describeImages } from './vision';
 import type { ChannelAdapter, InboundMessage, RawRequest } from './types';
+import type { LoadedMedia } from './helpers';
 
 const log = getLogger('gateway');
 
@@ -28,27 +32,125 @@ async function readBody(req: IncomingMessage): Promise<Buffer> {
 }
 
 /** Run an agent turn for an inbound message and collect the final text reply. */
-async function runAgent(
+/** Build the agent prompt: text + media description + any vision result. */
+function buildPrompt(msg: InboundMessage, canSendMedia: boolean, visionText?: string | null): string {
+  const parts: string[] = [];
+  const mediaDesc = describeMedia(msg.media);
+  if (msg.text) parts.push(msg.text);
+  if (mediaDesc) parts.push(`(用户发送了媒体: ${mediaDesc})`);
+  if (visionText) parts.push(`(图片内容识别: ${visionText})`);
+  if (canSendMedia) {
+    parts.push('(若需回发图片或文件,在回复中用 Markdown 图片 ![说明](路径或URL) 或 [[file:路径或URL]] 表示,路径可为本地文件或 http(s) 链接。)');
+  }
+  return parts.join('\n\n') || msg.text;
+}
+
+/** Download inbound images and run vision over them. Returns null if disabled. */
+async function visionForMessage(
   ctx: ReturnType<typeof createSystemContext>,
   adapter: ChannelAdapter,
   msg: InboundMessage,
-): Promise<string> {
+): Promise<string | null> {
+  const chCfg = ((ctx.config as any).channels || {})[adapter.id] || {};
+  const llmCfg = (ctx.config as any).llm || {};
+  if (chCfg.vision === false) return null;
+  const model = chCfg.visionModel || llmCfg.vision_model || llmCfg.visionModel;
+  if (!model) return null; // vision is opt-in: requires a configured model
+  const images = (msg.media || []).filter((m) => m.kind === 'image');
+  if (!images.length || !adapter.fetchMedia) return null;
+
+  const loaded: LoadedMedia[] = [];
+  for (const att of images.slice(0, 4)) {
+    try {
+      const got = await adapter.fetchMedia(att, msg);
+      if (got) loaded.push({ data: got.data, filename: att.filename || 'image', contentType: got.contentType });
+    } catch (e) {
+      log.warn('vision_fetch_failed', { channel: adapter.id, error: String(e) });
+    }
+  }
+  if (!loaded.length) return null;
+  return describeImages(loaded, { model });
+}
+
+/** Resolve the agent for a channel message. */
+function resolveAgent(ctx: ReturnType<typeof createSystemContext>, adapter: ChannelAdapter) {
   const cfgChannels = (ctx.config as any).channels || {};
   const agentName = cfgChannels[adapter.id]?.agent || adapter.defaultAgent || 'fair';
-  const agent = ctx.agentMap.get(agentName) || ctx.agentMap.get('fair') || [...ctx.agentMap.values()][0];
-  if (!agent) throw new Error('no agent available');
+  return ctx.agentMap.get(agentName) || ctx.agentMap.get('fair') || [...ctx.agentMap.values()][0];
+}
 
+/** Dispatch one inbound message to its agent and deliver the reply. */
+async function dispatch(
+  ctx: ReturnType<typeof createSystemContext>,
+  adapter: ChannelAdapter,
+  msg: InboundMessage,
+): Promise<void> {
+  const agent = resolveAgent(ctx, adapter);
+  if (!agent) throw new Error('no agent available');
   await agent.init();
+  const visionText = await visionForMessage(ctx, adapter, msg);
+  const prompt = buildPrompt(msg, !!adapter.sendMedia, visionText);
+
+  // Streaming path: stream content chunks straight to the adapter (e.g. a Feishu
+  // card patched as text arrives). Falls back to collect-then-send otherwise.
+  const cfgStreaming = ((ctx.config as any).channels || {})[adapter.id]?.streaming !== false;
+  if (adapter.sendStreaming && cfgStreaming) {
+    let full = '';
+    async function* contentChunks(): AsyncGenerator<string> {
+      try {
+        for await (const ev of agent.chatStream(prompt)) {
+          if ((ev as any).type === 'content') { const t = (ev as any).text as string; full += t; yield t; }
+        }
+      } catch (e) {
+        log.warn('gateway_agent_failed', { channel: adapter.id, error: String(e) });
+        yield `\n[出错了] ${String(e)}`;
+      }
+    }
+    await adapter.sendStreaming(msg.replyTo, contentChunks());
+    // After streaming the text, deliver any media the agent referenced.
+    await deliverMedia(adapter, msg, full);
+    return;
+  }
+
   let text = '';
   try {
-    for await (const ev of agent.chatStream(msg.text)) {
+    for await (const ev of agent.chatStream(prompt)) {
       if ((ev as any).type === 'content') text += (ev as any).text;
     }
   } catch (e) {
     log.warn('gateway_agent_failed', { channel: adapter.id, error: String(e) });
-    return `[出错了] ${String(e)}`;
+    text = `[出错了] ${String(e)}`;
+  }
+  // Non-streaming: split out media so the text message is clean.
+  if (adapter.sendMedia) {
+    const parsed = parseReply(text);
+    await adapter.send(msg.replyTo, parsed.text || '(无回复)');
+    await deliverMedia(adapter, msg, text, parsed.media);
+  } else {
+    await adapter.send(msg.replyTo, text.trim() || '(无回复)');
+  }
+}
+
+/** Upload+send any media the agent referenced in its reply. Best-effort. */
+async function deliverMedia(
+  adapter: ChannelAdapter,
+  msg: InboundMessage,
+  fullText: string,
+  pre?: ReturnType<typeof parseReply>['media'],
+): Promise<void> {
+  if (!adapter.sendMedia) return;
+  const media = pre ?? parseReply(fullText).media;
+  for (const item of media) {
+    if (!isSendableSrc(item.src)) {
+      log.warn('gateway_media_unsendable', { channel: adapter.id, src: item.src });
+      continue;
+    }
+    try {
+      await adapter.sendMedia(msg.replyTo, item);
+    } catch (e) {
+      log.warn('gateway_send_media_failed', { channel: adapter.id, src: item.src, error: String(e) });
+    }
   }
-  return text.trim() || '(无回复)';
 }
 
 export interface GatewayOptions {
@@ -114,14 +216,8 @@ export async function startGateway(opts: GatewayOptions = {}): Promise<void> {
       // Route to an agent and deliver the reply asynchronously (after the ack).
       if (outcome.message) {
         const msg = outcome.message;
-        void (async () => {
-          try {
-            const reply = await runAgent(ctx, adapter, msg);
-            await adapter.send(msg.replyTo, reply);
-          } catch (e) {
-            log.warn('gateway_dispatch_failed', { channel: adapter.id, error: String(e) });
-          }
-        })();
+        void dispatch(ctx, adapter, msg).catch((e) =>
+          log.warn('gateway_dispatch_failed', { channel: adapter.id, error: String(e) }));
       }
     } catch (e) {
       log.warn('gateway_request_error', { error: String(e) });

package/src/gateway/helpers.ts

@@ -5,6 +5,8 @@
  */
 
 import axios from 'axios';
+import * as fs from 'fs';
+import * as path from 'path';
 
 /**
  * Resolve a secret/config value. Accepts a literal string, or an env-ref object
@@ -58,6 +60,64 @@ export async function getJson(
   return res.data;
 }
 
+/** A loaded binary plus its filename, ready to upload. */
+export interface LoadedMedia {
+  data: Buffer;
+  filename: string;
+  contentType?: string;
+}
+
+/**
+ * Load media bytes from a local filesystem path or an http(s) URL. Local paths
+ * are read directly; remote URLs are fetched (capped at 30 MiB to avoid
+ * pulling something huge into memory). Throws if the source can't be loaded.
+ */
+export async function loadMedia(src: string): Promise<LoadedMedia> {
+  if (/^https?:\/\//i.test(src)) {
+    const res = await axios.get(src, {
+      responseType: 'arraybuffer',
+      timeout: 30000,
+      maxContentLength: 30 * 1024 * 1024,
+      validateStatus: (s) => s >= 200 && s < 300,
+    });
+    const urlName = path.basename(new URL(src).pathname) || 'file';
+    const ct = res.headers['content-type'];
+    return {
+      data: Buffer.from(res.data),
+      filename: urlName,
+      contentType: typeof ct === 'string' ? ct : undefined,
+    };
+  }
+  const data = fs.readFileSync(src); // throws ENOENT if missing — caller handles
+  return { data, filename: path.basename(src) };
+}
+
+/** Is this a sendable media source (http(s) URL or an existing local file)? */
+export function isSendableSrc(src: string): boolean {
+  if (/^https?:\/\//i.test(src)) return true;
+  try { return fs.existsSync(src) && fs.statSync(src).isFile(); } catch { return false; }
+}
+
+/** POST multipart/form-data (Node 18+ FormData/Blob), return parsed JSON. */
+export async function postMultipart(
+  url: string,
+  fields: Record<string, string | { data: Buffer; filename: string; contentType?: string }>,
+  opts?: { headers?: Record<string, string>; timeoutMs?: number },
+): Promise<any> {
+  const form = new FormData();
+  for (const [k, v] of Object.entries(fields)) {
+    if (typeof v === 'string') form.append(k, v);
+    else form.append(k, new Blob([v.data], v.contentType ? { type: v.contentType } : undefined), v.filename);
+  }
+  const res = await axios.post(url, form, {
+    headers: { ...(opts?.headers || {}) },
+    timeout: opts?.timeoutMs ?? 30000,
+    maxBodyLength: Infinity,
+    validateStatus: (s) => s >= 200 && s < 300,
+  });
+  return res.data;
+}
+
 /**
  * A small token cache: fetch an access token via `fetcher`, cache it until it
  * is near expiry, and refresh transparently. Channels (Feishu/WeCom) all need