@workclaw/openclaw-workchat 1.0.5 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workclaw/openclaw-workchat",
-  "version": "1.0.5",
+  "version": "1.1.0",
   "type": "module",
   "description": "OpenClaw WorkChat channel plugin: QR binding + WebSocket messaging with the WorkChat open platform",
   "license": "MIT",

package/src/api/api.ts

@@ -1,5 +1,3 @@
-import { Agent, fetch as undiciFetch } from "undici";
-
 import { DEFAULT_BASE_URL, DEFAULT_WS_URL, RequestDefaults } from "./types.js";
 import { logger } from "../util/logger.js";
 import { redactBody, redactUrl } from "../util/redact.js";
@@ -23,10 +21,13 @@ async function fetchJson<T>(params: {
   allowInsecureTls?: boolean;
 }): Promise<T> {
   const { url, init, timeoutMs, allowInsecureTls } = params;
-  const dispatcher = allowInsecureTls
-    ? new Agent({ connect: { rejectUnauthorized: false } })
-    : undefined;
-  const fetcher = allowInsecureTls ? undiciFetch : globalThis.fetch;
+  void allowInsecureTls; // TLS verification always on (see fetcher note below)
+  // Native fetch only: undici's fetch serializes FormData file parts without
+  // the Blob's Content-Type (backend rejects with 4006 "不支持的媒体类型"),
+  // while Node's built-in fetch preserves it. allowInsecureTls is not used by
+  // any WorkChat deployment (workbrain.cn is public TLS), so dropping the
+  // undici path here is safe and keeps multipart uploads working.
+  const fetcher = globalThis.fetch;
   const controller = new AbortController();
   const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
 
@@ -36,7 +37,6 @@ async function fetchJson<T>(params: {
     response = await fetcher(url, {
       ...init,
       signal: controller.signal,
-      ...(dispatcher ? { dispatcher } : {}),
     } as any);
     text = await response.text().catch(() => "");
   } finally {
@@ -239,6 +239,73 @@ export async function sendWorkChatReplyMessage(params: {
   return { msgId: String(data.msgId) };
 }
 
+// ---------------------------------------------------------------------------
+// File upload (media send pipeline)
+// ---------------------------------------------------------------------------
+
+/** Response of POST /open-apis/v1/files/upload (backend FileUploadResp). */
+export interface WorkChatFileUploadResult {
+  url: string;
+  fileName?: string;
+  suffix?: string;
+  fileSize?: number;
+}
+
+/**
+ * POST {base}/open-apis/v1/files/upload — multipart single-file upload.
+ * Goes to the public bucket (SYSTEM_RESOURCE), so the returned URL is
+ * permanent and safe to embed in image/audio message content.
+ * Field name must be `file` (backend UploadFileReq).
+ */
+export async function uploadWorkChatFile(params: {
+  opts: WorkChatApiOptions;
+  filePath: string;
+  /** WorkChat user id — required by the backend as the login user (form field + x-user-id header). */
+  userId?: string | number;
+}): Promise<WorkChatFileUploadResult> {
+  const { opts, filePath, userId } = params;
+  const token = await getAccessToken(opts);
+  const { readFile } = await import("node:fs/promises");
+  const pathMod = await import("node:path");
+  const content = await readFile(filePath);
+  const fileName = pathMod.basename(filePath);
+  // The backend rejects non image/* or audio/* part content-types (4006), so
+  // the MIME must reflect the actual file — the send pipeline routes by
+  // extension already (audio: wav/m4a/mp3, else image).
+  const ext = pathMod.extname(fileName).replace(/^\./, "").toLowerCase();
+  const mime = ext === "mp3" || ext === "m4a" ? "audio/mpeg" : ext === "wav" ? "audio/wav" : `image/${ext === "jpg" ? "jpeg" : ext || "png"}`;
+  const form = new FormData();
+  form.set("file", new Blob([new Uint8Array(content)], { type: mime }), fileName);
+  // Backend UploadFileReq.userId: the file owner. The gateway normally injects
+  // x-user-id for user tokens; the plugin's app token does not carry it, so
+  // both the form field and the header are sent explicitly.
+  const ownerUserId = userId !== undefined && String(userId).trim() !== "" ? String(userId) : "0";
+  form.set("userId", ownerUserId);
+
+  const resp = await fetchJson<{ code?: number; message?: string; data?: { url?: string; fileName?: string; suffix?: string; fileSize?: number } }>({
+    url: `${normalizeBaseUrl(opts.baseUrl)}/open-apis/v1/files/upload`,
+    timeoutMs: opts.timeoutMs ?? RequestDefaults.TimeoutMs,
+    allowInsecureTls: opts.allowInsecureTls,
+    init: {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${token}`,
+        "x-user-id": ownerUserId,
+      },
+      body: form,
+    },
+  });
+  const data = unwrapEnvelope(resp);
+  const url = typeof data?.url === "string" ? data.url.trim() : "";
+  if (!url) throw new Error("workchat: url missing in file upload response");
+  return {
+    url,
+    fileName: typeof data?.fileName === "string" ? data.fileName : undefined,
+    suffix: typeof data?.suffix === "string" ? data.suffix : undefined,
+    fileSize: typeof data?.fileSize === "number" ? data.fileSize : undefined,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Agent lifecycle
 // ---------------------------------------------------------------------------

package/src/api/session-guard.ts

@@ -0,0 +1,84 @@
+import { logger } from "../util/logger.js";
+
+const SESSION_PAUSE_DURATION_MS = 60 * 60 * 1000;
+
+/**
+ * Backend error strings that indicate a permanent binding failure (agent
+ * deleted / not owned by this appKey). Retrying within the session cannot
+ * fix these — only a re-scan (new binding QR) can.
+ */
+const PERMANENT_ERROR_PATTERNS = [
+  "智能体不能为空",
+  "智能体不是接收人的智能体",
+  "设备链接异常",
+  "申请绑定的AppKey不存在",
+];
+
+const pauseUntilMap = new Map<string, number>();
+
+/** Pause all send attempts for `accountId` for one hour (permanent backend error). */
+export function pauseSession(accountId: string): void {
+  const until = Date.now() + SESSION_PAUSE_DURATION_MS;
+  pauseUntilMap.set(accountId, until);
+  logger.info(
+    `session-guard: paused accountId=${accountId} until=${new Date(until).toISOString()} (${SESSION_PAUSE_DURATION_MS / 1000}s)`,
+  );
+}
+
+/** Returns `true` when the account is still within its one-hour cooldown window. */
+export function isSessionPaused(accountId: string): boolean {
+  const until = pauseUntilMap.get(accountId);
+  if (until === undefined) return false;
+  if (Date.now() >= until) {
+    pauseUntilMap.delete(accountId);
+    return false;
+  }
+  return true;
+}
+
+/** Milliseconds remaining until the pause expires (0 when not paused). */
+export function getRemainingPauseMs(accountId: string): number {
+  const until = pauseUntilMap.get(accountId);
+  if (until === undefined) return 0;
+  const remaining = until - Date.now();
+  if (remaining <= 0) {
+    pauseUntilMap.delete(accountId);
+    return 0;
+  }
+  return remaining;
+}
+
+/** Throw if the session is currently paused. Call before any send request. */
+export function assertSessionActive(accountId: string): void {
+  if (isSessionPaused(accountId)) {
+    const remainingMin = Math.ceil(getRemainingPauseMs(accountId) / 60_000);
+    throw new Error(
+      `session paused for accountId=${accountId}, ${remainingMin} min remaining — the WorkChat binding is invalid, re-scan the QR code to fix`,
+    );
+  }
+}
+
+/** True when a backend error message indicates a permanent binding failure. */
+export function isPermanentBindingError(errMsg: string): boolean {
+  return PERMANENT_ERROR_PATTERNS.some((p) => errMsg.includes(p));
+}
+
+/**
+ * Auto-pause the account when the error looks like a permanent binding
+ * failure. Returns true when the pause was armed.
+ */
+export function pauseOnPermanentError(accountId: string, errMsg: string): boolean {
+  if (!isPermanentBindingError(errMsg)) return false;
+  if (!isSessionPaused(accountId)) {
+    pauseSession(accountId);
+    logger.warn(
+      `session-guard: permanent binding error, pausing accountId=${accountId} err="${errMsg.slice(0, 120)}" — re-scan required`,
+    );
+  }
+  return true;
+}
+
+/** Reset internal state — only for tests. @internal */
+export function _resetSessionGuardForTest(): void {
+  pauseUntilMap.clear();
+}

package/src/api/types.ts

@@ -13,10 +13,19 @@ export const DEFAULT_BASE_URL = "https://workbrain.cn/backend-api";
 /** WebSocket endpoint used when the open-connection API returns none. */
 export const DEFAULT_WS_URL = "wss://workbrain.cn/backend-api/open-apis/connect";
 
-/** msgType codes accepted by /open-apis/im/v1/messages. */
+/**
+ * msgType values accepted by /open-apis/im/v1/messages — the backend ChatType
+ * enum deserializes by NUMERIC CODE (verified live: name strings like "text"
+ * fail with 2001 请求体格式错误, while codes "1"/1/2/"2" pass through to the
+ * business layer). Codes from the backend ChatType enum: TEXT=1, IMAGE=2,
+ * Voice=110. Audio rides Voice(110) — the integration guide's "audio" name
+ * does not match the live deserializer.
+ * Media content is a JSON string: image {"url", width?, height?}, audio {"url", duration?}.
+ */
 export const WorkChatMsgType = {
   Text: "1",
-  Rich: "26",
+  Image: "2",
+  Audio: "110",
 } as const;
 
 export const RequestDefaults = {
@@ -39,7 +48,13 @@ export interface AgentMessagePayload {
   agentId?: string | number;
   conversationId?: string;
   msgId?: string | number;
-  message?: string | { content?: string };
+  message?: string | { content?: string; type?: string };
+  /** Backend ChatAgentMessageDTO: chatType mirrors message.type for media. */
+  chatType?: string | number;
+  /** Single file id (backend DTO fileId). */
+  fileId?: string | number;
+  /** File url list (backend DTO fileUrl) — populated for file/image/audio messages. */
+  fileUrl?: string[];
 }
 
 /** EVENT/AGENT_CREATED|INIT_AGENT payload. */

package/src/channel.ts

@@ -12,6 +12,12 @@ import {
 } from "./auth/login-qr.js";
 import type { WorkChatQrStartResult, WorkChatQrWaitResult } from "./auth/login-qr.js";
 import { pushWorkChatMessage, replyWorkChatMessage } from "./messaging/send.js";
+import {
+  downloadRemoteMediaToTemp,
+  isLocalMediaSource,
+  resolveLocalMediaPath,
+  sendWorkChatMediaFile,
+} from "./messaging/send-media.js";
 import { logger } from "./util/logger.js";
 
 /**
@@ -71,7 +77,8 @@ export const workchatPlugin: ChannelPlugin<ResolvedWorkChatAccount> = {
     messageToolHints: () => [
       "To send a message to the current WorkChat user, use the message tool with action='send'. You do not need to specify 'to' — the current conversation recipient is used automatically.",
       "IMPORTANT: When creating a cron job (scheduled task) for the current WorkChat user, you MUST set delivery.to to the user's WorkChat ID (the numeric ID from the current conversation) AND set delivery.accountId to the current AccountId. Without an explicit 'to', the cron delivery will fail with 'requires target'. Without an explicit 'accountId', the message may be sent from the wrong bot account. Example: delivery: { mode: 'announce', channel: 'openclaw-workchat', to: '<current_user_id>', accountId: '<current_AccountId>' }.",
-      "IMPORTANT: When sending media, set 'media' to a URL the WorkChat platform can fetch (an HTTPS URL). Local file paths are not supported by the WorkChat send API yet — include the link in the message text instead.",
+      "To send an image or audio file to the current user, use the message tool with action='send' and set 'media' to a local file path or a remote HTTPS URL. Supported audio formats: wav, m4a, mp3; supported image formats: bmp, gif, jpg, jpeg, png, webp. Remote URLs are downloaded and re-uploaded to WorkChat storage automatically — the client renders image/audio cards, never bare links.",
+      "IMPORTANT: When generating or saving a file to send, always use an absolute path (e.g. /tmp/photo.png or C:\\tmp\\photo.png on Windows), never a relative path like ./photo.png. Relative paths cannot be resolved and the file will not be delivered.",
     ],
   },
   reload: { configPrefixes: ["channels.openclaw-workchat"] },
@@ -107,16 +114,73 @@ export const workchatPlugin: ChannelPlugin<ResolvedWorkChatAccount> = {
       return { channel: "openclaw-workchat", messageId: result.messageId };
     },
     sendMedia: async (ctx) => {
-      // Media sends degrade to a text message carrying the media URL until the
-      // platform media-upload API is confirmed.
       const account = resolveOutboundAccount(ctx.cfg, ctx.accountId);
-      const text = ctx.text?.trim() ? ctx.text : ctx.mediaUrl ?? "";
-      const result = await pushWorkChatMessage({
-        account,
+      const aLog = logger.withAccount(account.accountId);
+      const mediaUrl = ctx.mediaUrl?.trim();
+      let text = ctx.text ?? "";
+
+      // message_sending hook (mirrors the deliver path; weixin parity): lets
+      // hosts observe/cancel outbound media too.
+      const { applyWorkChatMessageSendingHook, emitWorkChatMessageSent } =
+        await import("./messaging/outbound-hooks.js");
+      const sendingResult = await applyWorkChatMessageSendingHook({
         to: ctx.to,
         text,
+        accountId: account.accountId,
+        mediaUrl,
+      }).catch((err: unknown) => {
+        aLog.warn(`message_sending hook error, proceeding: ${String(err)}`);
+        return { cancelled: false, text };
       });
-      return { channel: "openclaw-workchat", messageId: result.messageId };
+      if (sendingResult.cancelled) {
+        aLog.info(`sendMedia: cancelled by message_sending hook to=${ctx.to}`);
+        return { channel: "openclaw-workchat", messageId: "" };
+      }
+      text = sendingResult.text;
+
+      if (!mediaUrl) {
+        // No media: degrade to a plain text send.
+        try {
+          const result = await pushWorkChatMessage({ account, to: ctx.to, text });
+          emitWorkChatMessageSent({ to: ctx.to, content: text, success: true, accountId: account.accountId });
+          return { channel: "openclaw-workchat", messageId: result.messageId };
+        } catch (err) {
+          emitWorkChatMessageSent({ to: ctx.to, content: text, success: false, error: String(err), accountId: account.accountId });
+          throw err;
+        }
+      }
+
+      // Local file → upload directly; remote URL → relay through local temp
+      // (the WorkChat client renders only WorkChat-hosted image/audio cards).
+      let filePath: string;
+      try {
+        if (isLocalMediaSource(mediaUrl)) {
+          filePath = resolveLocalMediaPath(mediaUrl);
+          aLog.debug(`sendMedia: uploading local file ${filePath}`);
+        } else {
+          aLog.debug(`sendMedia: downloading remote mediaUrl=${mediaUrl.slice(0, 80)}...`);
+          filePath = await downloadRemoteMediaToTemp(mediaUrl);
+          aLog.debug(`sendMedia: remote media downloaded to ${filePath}`);
+        }
+      } catch (err) {
+        emitWorkChatMessageSent({ to: ctx.to, content: text, success: false, error: String(err), accountId: account.accountId });
+        throw err;
+      }
+
+      try {
+        const result = await sendWorkChatMediaFile({
+          account,
+          to: ctx.to,
+          filePath,
+          text,
+          replyToMessageId: ctx.replyToId?.trim() || undefined,
+        });
+        emitWorkChatMessageSent({ to: ctx.to, content: text, success: true, accountId: account.accountId });
+        return { channel: "openclaw-workchat", messageId: result.messageId };
+      } catch (err) {
+        emitWorkChatMessageSent({ to: ctx.to, content: text, success: false, error: String(err), accountId: account.accountId });
+        throw err;
+      }
     },
   },
   status: {

package/src/messaging/inbound.ts

@@ -23,6 +23,10 @@ export type ParseWorkChatFrameResult = {
     openConversationId: string;
     messageId: string;
     agentId?: string;
+    /** "image"/"audio" for media messages (backend message.type / chatType). */
+    mediaType?: string;
+    /** Media URL from message.content JSON or the DTO fileUrl list. */
+    mediaUrl?: string;
   };
   pongData?: unknown;
   eventData?: AgentEventPayload;
@@ -83,11 +87,28 @@ export function parseWorkChatFrame(data: string): ParseWorkChatFrameResult | nul
   if (type === "CALLBACK" && String(envelope?.metadata?.topic || "").trim().toUpperCase() === "AGENT_MESSAGE") {
     const payload = (parseMaybeJson(envelope?.data) ?? {}) as AgentMessagePayload;
     const message = payload?.message;
-    const text = typeof message === "string"
+    const messageType = typeof message === "object" && message !== null
+      ? String((message as { type?: unknown }).type ?? "").trim().toLowerCase()
+      : "";
+    const rawContent = typeof message === "string"
       ? message
       : typeof message?.content === "string"
         ? message.content
         : "";
+
+    // Media messages: content is JSON {"url", ...} (image) or {"url","duration"} (audio);
+    // the backend DTO also carries a fileUrl list. Surface the URL for the AI
+    // pipeline while keeping a descriptive text body.
+    let mediaUrl: string | undefined;
+    let text = rawContent;
+    if (messageType === "image" || messageType === "audio") {
+      mediaUrl = extractMediaUrl(rawContent) ?? firstFileUrl(payload);
+      text = messageType === "image" ? "[用户发送了一张图片]" : "[用户发送了一条语音]";
+    } else if (!text.trim()) {
+      mediaUrl = firstFileUrl(payload);
+      if (mediaUrl) text = "[用户发送了一个文件]";
+    }
+
     return {
       type: "agent_message",
       message: {
@@ -96,6 +117,7 @@ export function parseWorkChatFrame(data: string): ParseWorkChatFrameResult | nul
         openConversationId: String(payload?.conversationId ?? ""),
         messageId: String(payload?.msgId ?? ""),
         ...(payload?.agentId !== undefined ? { agentId: String(payload.agentId) } : {}),
+        ...(mediaUrl ? { mediaUrl, mediaType: messageType || "file" } : {}),
       },
     };
   }
@@ -103,6 +125,23 @@ export function parseWorkChatFrame(data: string): ParseWorkChatFrameResult | nul
   return { type: "ignored", ignoredKind: `${type}/${topicLower || "(no topic)"}` };
 }
 
+/** Extract `url` from a media message content JSON string, if parseable. */
+function extractMediaUrl(content: string): string | undefined {
+  if (!content.trim()) return undefined;
+  try {
+    const parsed = JSON.parse(content) as { url?: unknown };
+    return typeof parsed?.url === "string" && parsed.url.trim() ? parsed.url.trim() : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/** First entry of the backend DTO fileUrl list, when present. */
+function firstFileUrl(payload: AgentMessagePayload): string | undefined {
+  const url = Array.isArray(payload?.fileUrl) ? payload.fileUrl[0] : undefined;
+  return typeof url === "string" && url.trim() ? url.trim() : undefined;
+}
+
 /** Build the pong response frame for a SYSTEM ping. */
 export function buildPongFrame(pongData: unknown): string {
   return JSON.stringify({
@@ -139,6 +178,12 @@ export type WorkChatMsgContext = {
   ConversationId?: string;
   /** Cloud agent id this message was addressed to. */
   AgentId?: string;
+  /** Media URL for inbound image/audio/file messages (WorkChat-hosted). */
+  MediaUrl?: string;
+  /** Media kind for inbound media messages ("image" | "audio" | "file"). */
+  MediaType?: string;
+  /** Local path after the media is persisted into the framework media store. */
+  MediaPath?: string;
 };
 
 function generateMessageSid(): string {
@@ -151,8 +196,13 @@ export function workChatMessageToMsgContext(
   accountId: string,
 ): WorkChatMsgContext {
   const fromUserId = message.userId ?? "";
+  // Media messages carry a placeholder body; append the URL so the model can
+  // see and describe the actual asset.
+  const body = message.mediaUrl
+    ? `${message.text ?? ""}\n[media] ${message.mediaUrl}`
+    : message.text ?? "";
   const ctx: WorkChatMsgContext = {
-    Body: message.text ?? "",
+    Body: body,
     From: fromUserId,
     To: fromUserId,
     AccountId: accountId,
@@ -170,5 +220,9 @@ export function workChatMessageToMsgContext(
   if (message.agentId) {
     ctx.AgentId = message.agentId;
   }
+  if (message.mediaUrl) {
+    ctx.MediaUrl = message.mediaUrl;
+    ctx.MediaType = message.mediaType ?? "file";
+  }
   return ctx;
 }

package/src/messaging/process-message.ts

@@ -33,10 +33,44 @@ function loadWorkChatOutboundHooks() {
   return workchatOutboundHooksPromise;
 }
 
+/** Max inbound media size persisted to the framework media store. */
+const WORKCHAT_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
+
+/**
+ * Download an inbound media URL. Prefers the framework's fetchRemoteMedia
+ * (SSRF guard + size limit); falls back to plain fetch.
+ */
+async function downloadInboundMedia(
+  url: string,
+  deps: ProcessFrameDeps,
+): Promise<{ buffer: Buffer; contentType?: string } | null> {
+  try {
+    if (deps.channelRuntime?.media?.fetchRemoteMedia) {
+      const fetched = await deps.channelRuntime.media.fetchRemoteMedia({
+        url,
+        maxBytes: WORKCHAT_MEDIA_MAX_BYTES,
+      });
+      return { buffer: fetched.buffer, contentType: fetched.contentType };
+    }
+  } catch (err) {
+    logger.warn(`fetchRemoteMedia failed, trying plain fetch: ${String(err)}`);
+  }
+  const res = await globalThis.fetch(url);
+  if (!res.ok) {
+    throw new Error(`inbound media download failed: HTTP ${res.status}`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  if (buffer.length > WORKCHAT_MEDIA_MAX_BYTES) {
+    throw new Error(`inbound media exceeds limit (${buffer.length} bytes)`);
+  }
+  return { buffer, contentType: res.headers.get("content-type") ?? undefined };
+}
+
 async function applyWorkChatMessageSendingHook(params: {
   to: string;
   text: string;
   accountId?: string;
+  mediaUrl?: string;
 }): Promise<{ cancelled: boolean; text: string }> {
   try {
     const hooks = await loadWorkChatOutboundHooks();
@@ -250,6 +284,17 @@ export async function processOneFrame(
     return;
   }
 
+  // --- Dedup: platform redelivery / monitor restart can replay frames; a
+  // known msgId is dropped before any dispatch side-effect.
+  if (message.messageId) {
+    const { isDuplicateMessage, recordMessageProcessed } = await import("../storage/seen-msgids.js");
+    if (isDuplicateMessage(deps.accountId, message.messageId)) {
+      logger.info(`inbound: duplicate msgId=${message.messageId}, dropping`);
+      return;
+    }
+    recordMessageProcessed(deps.accountId, message.messageId);
+  }
+
   const receivedAt = Date.now();
   const debug = isDebugMode(deps.accountId);
   const debugTrace: string[] = [];
@@ -257,7 +302,7 @@ export async function processOneFrame(
 
   const ctx = workChatMessageToMsgContext(message, deps.accountId);
   logger.info(
-    `inbound: from=${ctx.From} to=${ctx.To} bodyLen=${ctx.Body.length} conversationId=${ctx.ConversationId ?? "(none)"}`,
+    `inbound: from=${ctx.From} to=${ctx.To} bodyLen=${ctx.Body.length} conversationId=${ctx.ConversationId ?? "(none)"} hasMedia=${Boolean(ctx.MediaUrl)}`,
   );
   logger.debug(`inbound raw frame: ${rawFrame.slice(0, 200)}`);
 
@@ -275,6 +320,30 @@ export async function processOneFrame(
     }
   }
 
+  // --- Inbound media persistence: download the WorkChat-hosted file into the
+  // framework media store so the AI sees a local MediaPath (vision-capable
+  // models can actually read the image) instead of just a URL in the body.
+  // Runs after the slash gate so commands never trigger media downloads.
+  if (ctx.MediaUrl && deps.channelRuntime?.media?.saveMediaBuffer) {
+    try {
+      const media = await downloadInboundMedia(ctx.MediaUrl, deps);
+      if (media) {
+        const saved = await deps.channelRuntime.media.saveMediaBuffer(
+          media.buffer,
+          media.contentType,
+          "inbound",
+          WORKCHAT_MEDIA_MAX_BYTES,
+        );
+        ctx.MediaPath = saved.path;
+        ctx.MediaType = media.contentType ?? ctx.MediaType;
+        logger.info(`inbound media saved: path=${saved.path} type=${media.contentType}`);
+      }
+    } catch (err) {
+      // Non-fatal: the URL is already in Body; the AI can still reference it.
+      deps.errLog(`inbound media download failed url=${redactBody(ctx.MediaUrl)}: ${String(err)}`);
+    }
+  }
+
   // --- Framework command authorization ---
   const rawBody = ctx.Body?.trim() ?? "";
   ctx.CommandBody = rawBody;
@@ -395,8 +464,11 @@ export async function processOneFrame(
         const rawText = String(payload.text ?? "");
         const f = new StreamingMarkdownFilter();
         let text = f.feed(rawText) + f.flush();
+        const mediaUrl = payload.mediaUrl ?? payload.mediaUrls?.[0];
 
-        logger.info(`outbound: to=${ctx.To} textLen=${text.length}`);
+        logger.info(
+          `outbound: to=${ctx.To} textLen=${text.length} mediaUrl=${mediaUrl ? "present" : "none"}`,
+        );
 
         if (debug) {
           debugDeliveries.push({
@@ -410,6 +482,7 @@ export async function processOneFrame(
           to: ctx.To,
           text,
           accountId: deps.accountId,
+          mediaUrl,
         });
         if (sendingResult.cancelled) {
           logger.info(`outbound: cancelled by message_sending hook to=${ctx.To}`);
@@ -418,6 +491,43 @@ export async function processOneFrame(
         text = sendingResult.text;
 
         try {
+          // Media payloads ride the upload-then-card pipeline (same as the
+          // channel outbound sendMedia path); text-only payloads reply directly.
+          if (mediaUrl) {
+            const { isLocalMediaSource, resolveLocalMediaPath, downloadRemoteMediaToTemp, sendWorkChatMediaFile } =
+              await import("./send-media.js");
+            let filePath: string;
+            if (isLocalMediaSource(mediaUrl)) {
+              filePath = resolveLocalMediaPath(mediaUrl);
+              logger.debug(`outbound: local media resolved filePath=${filePath}`);
+            } else if (mediaUrl.startsWith("http://") || mediaUrl.startsWith("https://")) {
+              logger.debug(`outbound: downloading remote mediaUrl=${mediaUrl.slice(0, 80)}...`);
+              filePath = await downloadRemoteMediaToTemp(mediaUrl);
+            } else {
+              logger.warn(
+                `outbound: unrecognized mediaUrl scheme, sending text only mediaUrl=${mediaUrl.slice(0, 80)}`,
+              );
+              filePath = "";
+            }
+            if (filePath) {
+              await sendWorkChatMediaFile({
+                account: {
+                  ...deps.account,
+                  agentId: ctx.AgentId ?? deps.account.agentId,
+                  userId: ctx.From || deps.account.userId,
+                },
+                to: ctx.To,
+                filePath,
+                text,
+                replyToMessageId: ctx.MessageSid,
+                conversationId: ctx.ConversationId,
+                agentId: ctx.AgentId,
+              });
+              emitWorkChatMessageSent({ to: ctx.To, content: text, success: true, accountId: deps.accountId });
+              logger.info(`outbound: media reply sent OK to=${ctx.To}`);
+              return;
+            }
+          }
           const result = await replyWorkChatMessage({
             account: {
               ...deps.account,
@@ -442,7 +552,14 @@ export async function processOneFrame(
       onError: (err, info) => {
         deps.errLog(`workchat reply ${info.kind}: ${String(err)}`);
         const errMsg = err instanceof Error ? err.message : String(err);
-        const notice = `⚠️ 消息发送失败：${errMsg}`;
+        let notice: string;
+        if (errMsg.includes("remote media download failed")) {
+          notice = `⚠️ 媒体文件下载失败，请检查链接是否可访问。`;
+        } else if (errMsg.includes("file upload response") || errMsg.includes("upload failed")) {
+          notice = `⚠️ 媒体文件上传失败，请稍后重试。`;
+        } else {
+          notice = `⚠️ 消息发送失败：${errMsg}`;
+        }
         void sendWorkChatErrorNotice({
           account: deps.account,
           to: ctx.To,