@marshulll/openclaw-wecom 0.1.15 → 0.1.17

package/docs/wecom.config.full.example.json

@@ -8,7 +8,17 @@
         "tempDir": "/tmp/openclaw-wecom",
         "retentionHours": 72,
         "cleanupOnStart": true,
-        "maxBytes": 10485760
+        "maxBytes": 10485760,
+        "vision": {
+          "enabled": true,
+          "baseUrl": "https://newapi.looksunlight.com/v1",
+          "apiKey": "YOUR_API_KEY",
+          "model": "gpt-4o-mini",
+          "prompt": "请描述图片内容并尽量提取可见文字。",
+          "maxTokens": 400,
+          "timeoutMs": 15000,
+          "maxBytes": 5242880
+        }
       },
       "botMediaBridge": true,
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@marshulll/openclaw-wecom",
-  "version": "0.1.15",
+  "version": "0.1.17",
   "type": "module",
   "description": "OpenClaw WeCom channel plugin (intelligent bot + internal app)",
   "author": "OpenClaw",

package/wecom/src/config-schema.ts

@@ -47,6 +47,16 @@ const accountSchema = z.object({
     retentionHours: z.number().optional(),
     cleanupOnStart: z.boolean().optional(),
     maxBytes: z.number().optional(),
+    vision: z.object({
+      enabled: z.boolean().optional(),
+      baseUrl: z.string().optional(),
+      apiKey: z.string().optional(),
+      model: z.string().optional(),
+      prompt: z.string().optional(),
+      maxTokens: z.number().optional(),
+      timeoutMs: z.number().optional(),
+      maxBytes: z.number().optional(),
+    }).optional(),
   }).optional(),
 
   network: z.object({
@@ -81,6 +91,16 @@ export const WecomConfigSchema = ensureJsonSchema(z.object({
     retentionHours: z.number().optional(),
     cleanupOnStart: z.boolean().optional(),
     maxBytes: z.number().optional(),
+    vision: z.object({
+      enabled: z.boolean().optional(),
+      baseUrl: z.string().optional(),
+      apiKey: z.string().optional(),
+      model: z.string().optional(),
+      prompt: z.string().optional(),
+      maxTokens: z.number().optional(),
+      timeoutMs: z.number().optional(),
+      maxBytes: z.number().optional(),
+    }).optional(),
   }).optional(),
 
   network: z.object({

package/wecom/src/media-vision.ts

@@ -0,0 +1,98 @@
+import type { WecomAccountConfig } from "./types.js";
+
+export type VisionConfig = {
+  enabled?: boolean;
+  baseUrl?: string;
+  apiKey?: string;
+  model?: string;
+  prompt?: string;
+  maxTokens?: number;
+  timeoutMs?: number;
+  maxBytes?: number;
+};
+
+function resolveBaseUrl(raw?: string): string | null {
+  const value = raw?.trim();
+  if (!value) return null;
+  if (value.endsWith("/v1")) return value;
+  return `${value.replace(/\/+$/, "")}/v1`;
+}
+
+export function resolveVisionConfig(accountConfig: WecomAccountConfig): VisionConfig | null {
+  const vision = accountConfig.media?.vision;
+  if (!vision?.enabled) return null;
+
+  const baseUrl = resolveBaseUrl(
+    vision.baseUrl
+      || process.env.OPENAI_BASE_URL
+      || process.env.OPENAI_API_BASE
+      || process.env.OPENAI_ENDPOINT,
+  );
+  const apiKey = vision.apiKey || process.env.OPENAI_API_KEY || process.env.OPENAI_KEY;
+  if (!baseUrl || !apiKey) return null;
+
+  return {
+    enabled: true,
+    baseUrl,
+    apiKey,
+    model: vision.model || process.env.OPENAI_MODEL || "gpt-4o-mini",
+    prompt: vision.prompt
+      || "请描述图片内容并尽量提取可见文字。输出简洁中文要点。",
+    maxTokens: typeof vision.maxTokens === "number" ? vision.maxTokens : 400,
+    timeoutMs: typeof vision.timeoutMs === "number" ? vision.timeoutMs : 15000,
+    maxBytes: typeof vision.maxBytes === "number" ? vision.maxBytes : undefined,
+  };
+}
+
+export async function describeImageWithVision(params: {
+  config: VisionConfig;
+  buffer: Buffer;
+  mimeType: string;
+}): Promise<string | null> {
+  const { config, buffer, mimeType } = params;
+  if (!config.enabled || !config.baseUrl || !config.apiKey) return null;
+
+  if (config.maxBytes && buffer.length > config.maxBytes) {
+    return null;
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), config.timeoutMs ?? 15000);
+
+  try {
+    const imageBase64 = buffer.toString("base64");
+    const payload = {
+      model: config.model,
+      messages: [
+        {
+          role: "user",
+          content: [
+            { type: "text", text: config.prompt },
+            { type: "image_url", image_url: { url: `data:${mimeType};base64,${imageBase64}` } },
+          ],
+        },
+      ],
+      max_tokens: config.maxTokens ?? 400,
+    };
+
+    const res = await fetch(`${config.baseUrl}/chat/completions`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        Authorization: `Bearer ${config.apiKey}`,
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+
+    if (!res.ok) return null;
+    const data = await res.json() as any;
+    const content = data?.choices?.[0]?.message?.content;
+    if (typeof content !== "string") return null;
+    return content.trim() || null;
+  } catch {
+    return null;
+  } finally {
+    clearTimeout(timeout);
+  }
+}

package/wecom/src/types.ts

@@ -47,6 +47,16 @@ export type WecomAccountConfig = {
     retentionHours?: number;
     cleanupOnStart?: boolean;
     maxBytes?: number;
+    vision?: {
+      enabled?: boolean;
+      baseUrl?: string;
+      apiKey?: string;
+      model?: string;
+      prompt?: string;
+      maxTokens?: number;
+      timeoutMs?: number;
+      maxBytes?: number;
+    };
   };
 
   // Network behavior

package/wecom/src/wecom-app.ts

@@ -1,15 +1,16 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import crypto from "node:crypto";
 import { XMLParser } from "fast-xml-parser";
-import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, extname, join } from "node:path";
 
 import type { WecomWebhookTarget } from "./monitor.js";
 import { decryptWecomEncrypted, verifyWecomSignature } from "./crypto.js";
 import { getWecomRuntime } from "./runtime.js";
 import { handleCommand } from "./commands.js";
 import { markdownToWecomText } from "./format.js";
+import { describeImageWithVision, resolveVisionConfig } from "./media-vision.js";
 import { downloadWecomMedia, fetchMediaFromUrl, sendWecomFile, sendWecomImage, sendWecomText, sendWecomVideo, sendWecomVoice, uploadWecomMedia } from "./wecom-api.js";
 
 const xmlParser = new XMLParser({
@@ -26,6 +27,7 @@ type MediaCacheEntry = {
   type: "image" | "voice" | "video" | "file";
   mimeType?: string;
   url?: string;
+  summary?: string;
   createdAt: number;
   size: number;
 };
@@ -171,6 +173,139 @@ function normalizeMediaType(raw?: string): "image" | "voice" | "video" | "file"
   return null;
 }
 
+function pickString(...values: unknown[]): string {
+  for (const value of values) {
+    if (typeof value === "string" && value.trim()) return value.trim();
+  }
+  return "";
+}
+
+function resolveContentTypeFromExt(ext: string): string {
+  const value = ext.toLowerCase();
+  if (value === "png") return "image/png";
+  if (value === "gif") return "image/gif";
+  if (value === "jpg" || value === "jpeg") return "image/jpeg";
+  if (value === "webp") return "image/webp";
+  if (value === "bmp") return "image/bmp";
+  if (value === "amr") return "audio/amr";
+  if (value === "wav") return "audio/wav";
+  if (value === "mp3") return "audio/mpeg";
+  if (value === "m4a") return "audio/mp4";
+  if (value === "mp4") return "video/mp4";
+  if (value === "mov") return "video/quicktime";
+  if (value === "avi") return "video/x-msvideo";
+  if (value === "pdf") return "application/pdf";
+  if (value === "txt") return "text/plain";
+  if (value === "csv") return "text/csv";
+  if (value === "json") return "application/json";
+  if (value === "doc") return "application/msword";
+  if (value === "docx") return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+  if (value === "xls") return "application/vnd.ms-excel";
+  if (value === "xlsx") return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+  if (value === "ppt") return "application/vnd.ms-powerpoint";
+  if (value === "pptx") return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+  if (value === "zip") return "application/zip";
+  return "application/octet-stream";
+}
+
+function resolveMediaTypeFromContentType(contentType: string): "image" | "voice" | "video" | "file" {
+  const value = contentType.toLowerCase();
+  if (value.startsWith("image/")) return "image";
+  if (value.startsWith("audio/")) return "voice";
+  if (value.startsWith("video/")) return "video";
+  return "file";
+}
+
+function stripFileProtocol(rawPath: string): string {
+  return rawPath.startsWith("file://") ? rawPath.replace(/^file:\/\//, "") : rawPath;
+}
+
+function parseBase64Input(input: string): { data: string; mimeType?: string } {
+  const match = input.match(/^data:([^;]+);base64,(.*)$/i);
+  if (match) {
+    return { data: match[2], mimeType: match[1] };
+  }
+  return { data: input };
+}
+
+function resolveOutboundMediaSpec(payload: any): {
+  type?: string;
+  url?: string;
+  path?: string;
+  base64?: string;
+  filename?: string;
+  mimeType?: string;
+} | null {
+  if (!payload || typeof payload !== "object") return null;
+  const mediaBlockRaw = payload.media ?? payload.attachment ?? payload.file ?? payload.files;
+  const mediaBlock = Array.isArray(mediaBlockRaw) ? mediaBlockRaw[0] : mediaBlockRaw;
+  const url = pickString(
+    payload.mediaUrl,
+    mediaBlock?.url,
+    mediaBlock?.mediaUrl,
+    mediaBlock?.fileUrl,
+    mediaBlock?.file_url,
+  );
+  const path = pickString(
+    payload.mediaPath,
+    payload.filePath,
+    mediaBlock?.path,
+    mediaBlock?.filePath,
+    mediaBlock?.localPath,
+  );
+  const base64 = pickString(
+    payload.mediaBase64,
+    payload.base64,
+    mediaBlock?.base64,
+    mediaBlock?.data,
+  );
+  const type = pickString(payload.mediaType, mediaBlock?.type, mediaBlock?.mediaType);
+  const filename = pickString(payload.filename, payload.fileName, mediaBlock?.filename, mediaBlock?.fileName, mediaBlock?.name);
+  const mimeType = pickString(payload.mimeType, payload.mediaMimeType, mediaBlock?.mimeType, mediaBlock?.contentType);
+  if (!url && !path && !base64) return null;
+  return { type, url, path, base64, filename, mimeType };
+}
+
+async function loadOutboundMedia(params: {
+  payload: any;
+  account: WecomWebhookTarget["account"];
+  maxBytes: number | undefined;
+}): Promise<{ buffer: Buffer; contentType: string; type: "image" | "voice" | "video" | "file"; filename: string } | null> {
+  const spec = resolveOutboundMediaSpec(params.payload);
+  if (!spec) return null;
+
+  let buffer: Buffer | null = null;
+  let contentType = spec.mimeType ?? "";
+  let filename = spec.filename ?? "";
+
+  if (spec.base64) {
+    const parsed = parseBase64Input(spec.base64);
+    buffer = Buffer.from(parsed.data, "base64");
+    if (!contentType && parsed.mimeType) contentType = parsed.mimeType;
+  } else if (spec.path) {
+    const resolvedPath = stripFileProtocol(spec.path);
+    buffer = await readFile(resolvedPath);
+    if (!filename) filename = basename(resolvedPath);
+    if (!contentType) {
+      const ext = extname(resolvedPath).replace(".", "");
+      contentType = resolveContentTypeFromExt(ext);
+    }
+  } else if (spec.url) {
+    const media = await fetchMediaFromUrl(spec.url, params.account);
+    buffer = media.buffer;
+    if (!contentType) contentType = media.contentType;
+  }
+
+  if (!buffer) return null;
+  if (params.maxBytes && buffer.length > params.maxBytes) return null;
+
+  const type = normalizeMediaType(spec.type) ?? resolveMediaTypeFromContentType(contentType || "application/octet-stream");
+  const ext = resolveExtFromContentType(contentType || "application/octet-stream", type);
+  const safeName = sanitizeFilename(filename, `${type}.${ext}`);
+
+  return { buffer, contentType: contentType || resolveContentTypeFromExt(ext), type, filename: safeName };
+}
+
 function sanitizeFilename(name: string, fallback: string): string {
   const base = name.split(/[/\\\\]/).pop() ?? "";
   const trimmed = base.trim();
@@ -327,38 +462,35 @@ async function startAgentForApp(params: {
     cfg: config,
     dispatcherOptions: {
       deliver: async (payload, info) => {
-        const maybeMediaUrl = (payload as any).mediaUrl as string | undefined;
-        const maybeMediaType = (payload as any).mediaType as string | undefined;
-        if (maybeMediaUrl) {
-          try {
-            const media = await fetchMediaFromUrl(maybeMediaUrl, account);
-            const type = normalizeMediaType(maybeMediaType) ?? "file";
-            const ext = resolveExtFromContentType(media.contentType, type);
+        const maxBytes = resolveMediaMaxBytes(target);
+        try {
+          const outbound = await loadOutboundMedia({ payload, account, maxBytes });
+          if (outbound) {
             const mediaId = await uploadWecomMedia({
               account,
-              type: type as "image" | "voice" | "video" | "file",
-              buffer: media.buffer,
-              filename: `${type}.${ext}`,
+              type: outbound.type,
+              buffer: outbound.buffer,
+              filename: outbound.filename,
             });
-            if (type === "image") {
+            if (outbound.type === "image") {
               await sendWecomImage({ account, toUser: fromUser, chatId: isGroup ? chatId : undefined, mediaId });
               logVerbose(target, `app image reply delivered (${info.kind}) to ${fromUser}`);
-            } else if (type === "voice") {
+            } else if (outbound.type === "voice") {
               await sendWecomVoice({ account, toUser: fromUser, chatId: isGroup ? chatId : undefined, mediaId });
               logVerbose(target, `app voice reply delivered (${info.kind}) to ${fromUser}`);
-            } else if (type === "video") {
+            } else if (outbound.type === "video") {
               const title = (payload as any).title as string | undefined;
               const description = (payload as any).description as string | undefined;
               await sendWecomVideo({ account, toUser: fromUser, chatId: isGroup ? chatId : undefined, mediaId, title, description });
               logVerbose(target, `app video reply delivered (${info.kind}) to ${fromUser}`);
-            } else if (type === "file") {
+            } else if (outbound.type === "file") {
               await sendWecomFile({ account, toUser: fromUser, chatId: isGroup ? chatId : undefined, mediaId });
               logVerbose(target, `app file reply delivered (${info.kind}) to ${fromUser}`);
             }
             target.statusSink?.({ lastOutboundAt: Date.now() });
-          } catch (err) {
-            target.runtime.error?.(`wecom app media reply failed: ${String(err)}`);
           }
+        } catch (err) {
+          target.runtime.error?.(`wecom app media reply failed: ${String(err)}`);
         }
 
         const text = markdownToWecomText(core.channel.text.convertMarkdownTables(payload.text ?? "", tableMode));
@@ -467,7 +599,11 @@ async function processAppMessage(params: {
       if (cached) {
         mediaContext = { type: cached.type, path: cached.path, mimeType: cached.mimeType, url: cached.url };
         logVerbose(target, `app image cache hit: ${cached.path}`);
-        messageText = "[用户发送了一张图片]\n\n请根据图片内容回复用户。";
+        if (cached.summary) {
+          messageText = `[用户发送了一张图片]\n\n[图片识别结果]\n${cached.summary}\n\n请根据识别结果回复用户。`;
+        } else {
+          messageText = "[用户发送了一张图片]\n\n请根据图片内容回复用户。";
+        }
       } else {
         let buffer: Buffer | null = null;
         let contentType = "";
@@ -498,16 +634,27 @@ async function processAppMessage(params: {
             await writeFile(tempImagePath, buffer);
             const mimeType = contentType || "image/jpeg";
             mediaContext = { type: "image", path: tempImagePath, mimeType, url: picUrl || undefined };
+
+            const visionConfig = resolveVisionConfig(target.account.config);
+            const summary = visionConfig
+              ? await describeImageWithVision({ config: visionConfig, buffer, mimeType })
+              : null;
+
             storeCachedMedia(cacheKey, {
               path: tempImagePath,
               type: "image",
               mimeType,
               url: picUrl || undefined,
+              summary: summary ?? undefined,
               createdAt: Date.now(),
               size: buffer.length,
             });
             logVerbose(target, `app image saved (${buffer.length} bytes): ${tempImagePath}`);
-            messageText = "[用户发送了一张图片]\n\n请根据图片内容回复用户。";
+            if (summary) {
+              messageText = `[用户发送了一张图片]\n\n[图片识别结果]\n${summary}\n\n请根据识别结果回复用户。`;
+            } else {
+              messageText = "[用户发送了一张图片]\n\n请根据图片内容回复用户。";
+            }
           }
         } else {
           messageText = "[用户发送了一张图片，但下载失败]\n\n请告诉用户图片处理暂时不可用。";
@@ -582,7 +729,8 @@ async function processAppMessage(params: {
         if (cached) {
           mediaContext = { type: cached.type, path: cached.path, mimeType: cached.mimeType, url: cached.url };
           logVerbose(target, `app file cache hit: ${cached.path}`);
-          messageText = `[用户发送了一个文件: ${fileName || "未知文件"}]\n\n请根据文件内容回复用户。`;
+          const cachedName = fileName || basename(cached.path) || "未知文件";
+          messageText = `[用户发送了一个文件: ${cachedName}，已保存到: ${cached.path}]\n\n请使用 Read 工具查看这个文件的内容并回复用户。`;
         } else {
           const media = await downloadWecomMedia({ account: target.account, mediaId });
         const maxBytes = resolveMediaMaxBytes(target);
@@ -610,7 +758,7 @@ async function processAppMessage(params: {
             size: media.buffer.length,
           });
           logVerbose(target, `app file saved (${media.buffer.length} bytes): ${tempFilePath}`);
-          messageText = `[用户发送了一个文件: ${safeName}]\n\n请根据文件内容回复用户。`;
+          messageText = `[用户发送了一个文件: ${safeName}，已保存到: ${tempFilePath}]\n\n请使用 Read 工具查看这个文件的内容并回复用户。`;
         }
         }
       } catch (err) {

package/wecom/src/wecom-bot.ts

@@ -1,8 +1,8 @@
 import type { IncomingMessage, ServerResponse } from "node:http";
 import crypto from "node:crypto";
-import { mkdir, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, extname, join } from "node:path";
 
 import type { PluginRuntime } from "openclaw/plugin-sdk";
 
@@ -11,6 +11,7 @@ import type { ResolvedWecomAccount, WecomInboundMessage } from "./types.js";
 import { computeWecomMsgSignature, decryptWecomEncrypted, encryptWecomPlaintext, verifyWecomSignature } from "./crypto.js";
 import { fetchMediaFromUrl, sendWecomFile, sendWecomImage, sendWecomVideo, sendWecomVoice, uploadWecomMedia } from "./wecom-api.js";
 import { getWecomRuntime } from "./runtime.js";
+import { describeImageWithVision, resolveVisionConfig } from "./media-vision.js";
 
 const STREAM_TTL_MS = 10 * 60 * 1000;
 const STREAM_MAX_BYTES = 20_480;
@@ -20,7 +21,7 @@ const DEDUPE_MAX_ENTRIES = 2_000;
 const MEDIA_CACHE_MAX_ENTRIES = 200;
 
 const cleanupExecuted = new Set<string>();
-const mediaCache = new Map<string, { entry: InboundMedia; createdAt: number; size: number }>();
+const mediaCache = new Map<string, { entry: InboundMedia; createdAt: number; size: number; summary?: string }>();
 
 type StreamState = {
   streamId: string;
@@ -413,49 +414,44 @@ async function startAgentForStream(params: {
     cfg: config,
     dispatcherOptions: {
       deliver: async (payload) => {
-        const maybeMediaUrl = (payload as any).mediaUrl as string | undefined;
-        const maybeMediaType = (payload as any).mediaType as string | undefined;
         const canBridgeMedia = account.config.botMediaBridge !== false
           && Boolean(account.corpId && account.corpSecret && account.agentId);
         const toChatId = chatType === "group" ? chatId : undefined;
 
-        if (maybeMediaUrl && canBridgeMedia) {
+        if (canBridgeMedia) {
           try {
-            const media = await fetchMediaFromUrl(maybeMediaUrl, account);
-            const type = normalizeMediaType(maybeMediaType) ?? "file";
-            const ext = media.contentType.includes("png") ? "png"
-              : media.contentType.includes("gif") ? "gif"
-              : media.contentType.includes("jpeg") || media.contentType.includes("jpg") ? "jpg"
-              : media.contentType.includes("mp4") ? "mp4"
-              : media.contentType.includes("amr") ? "amr"
-              : media.contentType.includes("wav") ? "wav"
-              : media.contentType.includes("mp3") ? "mp3"
-              : "bin";
+            const outbound = await loadOutboundMedia({
+              payload,
+              account,
+              maxBytes: resolveMediaMaxBytes(target),
+            });
+            if (outbound) {
             const mediaId = await uploadWecomMedia({
               account,
-              type: type as "image" | "voice" | "video" | "file",
-              buffer: media.buffer,
-              filename: `${type}.${ext}`,
+              type: outbound.type,
+              buffer: outbound.buffer,
+              filename: outbound.filename,
             });
-            if (type === "image") {
+            if (outbound.type === "image") {
               await sendWecomImage({ account, toUser: userid, chatId: toChatId, mediaId });
-            } else if (type === "voice") {
+            } else if (outbound.type === "voice") {
               await sendWecomVoice({ account, toUser: userid, chatId: toChatId, mediaId });
-            } else if (type === "video") {
+            } else if (outbound.type === "video") {
               const title = (payload as any).title as string | undefined;
               const description = (payload as any).description as string | undefined;
               await sendWecomVideo({ account, toUser: userid, chatId: toChatId, mediaId, title, description });
-            } else if (type === "file") {
+            } else if (outbound.type === "file") {
               await sendWecomFile({ account, toUser: userid, chatId: toChatId, mediaId });
             }
             const current = streams.get(streamId);
             if (current) {
-              const note = mediaSentLabel(type);
+              const note = mediaSentLabel(outbound.type);
               const nextText = current.content ? `${current.content}\n\n${note}` : note;
               current.content = truncateUtf8Bytes(nextText.trim(), STREAM_MAX_BYTES);
               current.updatedAt = Date.now();
             }
             target.statusSink?.({ lastOutboundAt: Date.now() });
+            }
           } catch (err) {
             target.runtime.error?.(`[${account.accountId}] wecom bot media bridge failed: ${String(err)}`);
           }
@@ -593,9 +589,22 @@ async function buildBotMediaMessage(params: {
     const cacheKey = buildMediaCacheKey({ url, base64 });
     const cached = await getCachedMedia(cacheKey, resolveMediaRetentionMs(target));
     if (cached) {
+      if (msgtype === "image" && cached.summary) {
+        return {
+          text: `[用户发送了一张图片]\n\n[图片识别结果]\n${cached.summary}\n\n请根据识别结果回复用户。`,
+          media: cached.media,
+        };
+      }
+      if (msgtype === "file") {
+        const safeName = sanitizeFilename(filename || basename(cached.media.path), "file");
+        return {
+          text: `[用户发送了一个文件: ${safeName}，已保存到: ${cached.media.path}]\n\n请使用 Read 工具查看这个文件的内容并回复用户。`,
+          media: cached.media,
+        };
+      }
       return {
         text: buildInboundMediaPrompt(msgtype, filename),
-        media: cached,
+        media: cached.media,
       };
     }
 
@@ -652,7 +661,7 @@ async function buildBotMediaMessage(params: {
       };
       storeCachedMedia(cacheKey, media, buffer.length);
       return {
-        text: buildInboundMediaPrompt("file", safeName),
+        text: `[用户发送了一个文件: ${safeName}，已保存到: ${tempFilePath}]\n\n请使用 Read 工具查看这个文件的内容并回复用户。`,
         media,
       };
     }
@@ -670,9 +679,19 @@ async function buildBotMediaMessage(params: {
         mimeType: contentType || "image/jpeg",
         url,
       };
-      storeCachedMedia(cacheKey, media, buffer.length);
+      const visionConfig = resolveVisionConfig(target.account.config);
+      const summary = visionConfig
+        ? await describeImageWithVision({
+          config: visionConfig,
+          buffer,
+          mimeType: media.mimeType || "image/jpeg",
+        })
+        : null;
+      storeCachedMedia(cacheKey, media, buffer.length, summary ?? undefined);
       return {
-        text: buildInboundMediaPrompt("image"),
+        text: summary
+          ? `[用户发送了一张图片]\n\n[图片识别结果]\n${summary}\n\n请根据识别结果回复用户。`
+          : buildInboundMediaPrompt("image"),
         media,
       };
     }
@@ -776,6 +795,132 @@ function normalizeMediaType(raw?: string): "image" | "voice" | "video" | "file"
   return null;
 }
 
+function resolveContentTypeFromExt(ext: string): string {
+  const value = ext.toLowerCase();
+  if (value === "png") return "image/png";
+  if (value === "gif") return "image/gif";
+  if (value === "jpg" || value === "jpeg") return "image/jpeg";
+  if (value === "webp") return "image/webp";
+  if (value === "bmp") return "image/bmp";
+  if (value === "amr") return "audio/amr";
+  if (value === "wav") return "audio/wav";
+  if (value === "mp3") return "audio/mpeg";
+  if (value === "m4a") return "audio/mp4";
+  if (value === "mp4") return "video/mp4";
+  if (value === "mov") return "video/quicktime";
+  if (value === "avi") return "video/x-msvideo";
+  if (value === "pdf") return "application/pdf";
+  if (value === "txt") return "text/plain";
+  if (value === "csv") return "text/csv";
+  if (value === "json") return "application/json";
+  if (value === "doc") return "application/msword";
+  if (value === "docx") return "application/vnd.openxmlformats-officedocument.wordprocessingml.document";
+  if (value === "xls") return "application/vnd.ms-excel";
+  if (value === "xlsx") return "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet";
+  if (value === "ppt") return "application/vnd.ms-powerpoint";
+  if (value === "pptx") return "application/vnd.openxmlformats-officedocument.presentationml.presentation";
+  if (value === "zip") return "application/zip";
+  return "application/octet-stream";
+}
+
+function resolveMediaTypeFromContentType(contentType: string): "image" | "voice" | "video" | "file" {
+  const value = contentType.toLowerCase();
+  if (value.startsWith("image/")) return "image";
+  if (value.startsWith("audio/")) return "voice";
+  if (value.startsWith("video/")) return "video";
+  return "file";
+}
+
+function stripFileProtocol(rawPath: string): string {
+  return rawPath.startsWith("file://") ? rawPath.replace(/^file:\/\//, "") : rawPath;
+}
+
+function parseBase64Input(input: string): { data: string; mimeType?: string } {
+  const match = input.match(/^data:([^;]+);base64,(.*)$/i);
+  if (match) {
+    return { data: match[2], mimeType: match[1] };
+  }
+  return { data: input };
+}
+
+function resolveOutboundMediaSpec(payload: any): {
+  type?: string;
+  url?: string;
+  path?: string;
+  base64?: string;
+  filename?: string;
+  mimeType?: string;
+} | null {
+  if (!payload || typeof payload !== "object") return null;
+  const mediaBlockRaw = payload.media ?? payload.attachment ?? payload.file ?? payload.files;
+  const mediaBlock = Array.isArray(mediaBlockRaw) ? mediaBlockRaw[0] : mediaBlockRaw;
+  const url = pickString(
+    payload.mediaUrl,
+    mediaBlock?.url,
+    mediaBlock?.mediaUrl,
+    mediaBlock?.fileUrl,
+    mediaBlock?.file_url,
+  );
+  const path = pickString(
+    payload.mediaPath,
+    payload.filePath,
+    mediaBlock?.path,
+    mediaBlock?.filePath,
+    mediaBlock?.localPath,
+  );
+  const base64 = pickString(
+    payload.mediaBase64,
+    payload.base64,
+    mediaBlock?.base64,
+    mediaBlock?.data,
+  );
+  const type = pickString(payload.mediaType, mediaBlock?.type, mediaBlock?.mediaType);
+  const filename = pickString(payload.filename, payload.fileName, mediaBlock?.filename, mediaBlock?.fileName, mediaBlock?.name);
+  const mimeType = pickString(payload.mimeType, payload.mediaMimeType, mediaBlock?.mimeType, mediaBlock?.contentType);
+  if (!url && !path && !base64) return null;
+  return { type, url, path, base64, filename, mimeType };
+}
+
+async function loadOutboundMedia(params: {
+  payload: any;
+  account: ResolvedWecomAccount;
+  maxBytes: number | undefined;
+}): Promise<{ buffer: Buffer; contentType: string; type: "image" | "voice" | "video" | "file"; filename: string } | null> {
+  const spec = resolveOutboundMediaSpec(params.payload);
+  if (!spec) return null;
+
+  let buffer: Buffer | null = null;
+  let contentType = spec.mimeType ?? "";
+  let filename = spec.filename ?? "";
+
+  if (spec.base64) {
+    const parsed = parseBase64Input(spec.base64);
+    buffer = Buffer.from(parsed.data, "base64");
+    if (!contentType && parsed.mimeType) contentType = parsed.mimeType;
+  } else if (spec.path) {
+    const resolvedPath = stripFileProtocol(spec.path);
+    buffer = await readFile(resolvedPath);
+    if (!filename) filename = basename(resolvedPath);
+    if (!contentType) {
+      const ext = extname(resolvedPath).replace(".", "");
+      contentType = resolveContentTypeFromExt(ext);
+    }
+  } else if (spec.url) {
+    const media = await fetchMediaFromUrl(spec.url, params.account);
+    buffer = media.buffer;
+    if (!contentType) contentType = media.contentType;
+  }
+
+  if (!buffer) return null;
+  if (params.maxBytes && buffer.length > params.maxBytes) return null;
+
+  const type = normalizeMediaType(spec.type) ?? resolveMediaTypeFromContentType(contentType || "application/octet-stream");
+  const ext = resolveExtFromContentType(contentType || "application/octet-stream", type);
+  const safeName = sanitizeFilename(filename, `${type}.${ext}`);
+
+  return { buffer, contentType: contentType || resolveContentTypeFromExt(ext), type, filename: safeName };
+}
+
 function mediaSentLabel(type: string): string {
   if (type === "image") return "[已发送图片]";
   if (type === "voice") return "[已发送语音]";
@@ -812,7 +957,7 @@ function pruneMediaCache(): void {
 async function getCachedMedia(
   key: string | null,
   retentionMs?: number,
-): Promise<InboundMedia | null> {
+): Promise<{ media: InboundMedia; summary?: string } | null> {
   if (!key) return null;
   const cached = mediaCache.get(key);
   if (!cached) return null;
@@ -826,12 +971,12 @@ async function getCachedMedia(
     mediaCache.delete(key);
     return null;
   }
-  return cached.entry;
+  return { media: cached.entry, summary: cached.summary };
 }
 
-function storeCachedMedia(key: string | null, entry: InboundMedia, size: number): void {
+function storeCachedMedia(key: string | null, entry: InboundMedia, size: number, summary?: string): void {
   if (!key) return;
-  mediaCache.set(key, { entry, createdAt: Date.now(), size });
+  mediaCache.set(key, { entry, createdAt: Date.now(), size, summary });
   pruneMediaCache();
 }