@zhin.js/adapter-weixin-ilink 0.1.0

package/src/login.ts

@@ -0,0 +1,166 @@
+import type { Plugin } from "zhin.js";
+import { apiGetFetch, apiPostFetch } from "./ilink-api.js";
+import { buildBaseInfo, DEFAULT_API_BASE_URL } from "./ilink-meta.js";
+import { logger } from "./ilink-logger.js";
+import {
+  loadCredentials,
+  saveCredentials,
+  type WeixinIlinkCredentials,
+} from "./credentials.js";
+import type { WeixinIlinkBotConfig } from "./types.js";
+
+const DEFAULT_ILINK_BOT_TYPE = "3";
+const QR_LONG_POLL_TIMEOUT_MS = 35_000;
+const LOGIN_TIMEOUT_MS = 480_000;
+
+interface QRCodeResponse {
+  qrcode: string;
+  qrcode_img_content: string;
+}
+
+interface StatusResponse {
+  status:
+    | "wait"
+    | "scaned"
+    | "confirmed"
+    | "expired"
+    | "scaned_but_redirect"
+    | "need_verifycode"
+    | "verify_code_blocked"
+    | "binded_redirect";
+  bot_token?: string;
+  ilink_bot_id?: string;
+  baseurl?: string;
+  ilink_user_id?: string;
+  redirect_host?: string;
+}
+
+function getLocalBotTokenList(): string[] {
+  return [];
+}
+
+async function fetchQRCode(apiBaseUrl: string, botType: string): Promise<QRCodeResponse> {
+  const rawText = await apiPostFetch({
+    baseUrl: apiBaseUrl,
+    endpoint: `ilink/bot/get_bot_qrcode?bot_type=${encodeURIComponent(botType)}`,
+    body: JSON.stringify({ local_token_list: getLocalBotTokenList(), base_info: buildBaseInfo() }),
+    label: "fetchQRCode",
+  });
+  return JSON.parse(rawText) as QRCodeResponse;
+}
+
+async function pollQRStatus(
+  apiBaseUrl: string,
+  qrcode: string,
+): Promise<StatusResponse> {
+  try {
+    const endpoint = `ilink/bot/get_qrcode_status?qrcode=${encodeURIComponent(qrcode)}`;
+    const rawText = await apiGetFetch({
+      baseUrl: apiBaseUrl,
+      endpoint,
+      timeoutMs: QR_LONG_POLL_TIMEOUT_MS,
+      label: "pollQRStatus",
+    });
+    return JSON.parse(rawText) as StatusResponse;
+  } catch (err) {
+    if (err instanceof Error && err.name === "AbortError") {
+      return { status: "wait" };
+    }
+    logger.warn(`pollQRStatus error: ${String(err)}`);
+    return { status: "wait" };
+  }
+}
+
+export async function resolveCredentials(
+  plugin: Plugin,
+  config: WeixinIlinkBotConfig,
+): Promise<WeixinIlinkCredentials> {
+  const envToken = process.env.WEIXIN_ILINK_TOKEN?.trim() || config.botToken?.trim();
+  if (envToken) {
+    const stored = loadCredentials(config.name);
+    return {
+      botToken: envToken,
+      ilinkUserId: stored?.ilinkUserId,
+      ilinkBotId: stored?.ilinkBotId,
+      baseUrl: config.baseUrl ?? stored?.baseUrl ?? DEFAULT_API_BASE_URL,
+    };
+  }
+
+  const stored = loadCredentials(config.name);
+  if (stored?.botToken) {
+    return {
+      ...stored,
+      baseUrl: config.baseUrl ?? stored.baseUrl ?? DEFAULT_API_BASE_URL,
+    };
+  }
+
+  return loginWithQr(plugin, config);
+}
+
+export async function loginWithQr(
+  plugin: Plugin,
+  config: WeixinIlinkBotConfig,
+): Promise<WeixinIlinkCredentials> {
+  const apiBaseUrl = config.baseUrl ?? DEFAULT_API_BASE_URL;
+  const qr = await fetchQRCode(apiBaseUrl, DEFAULT_ILINK_BOT_TYPE);
+  const qrcodeUrl = qr.qrcode_img_content || qr.qrcode;
+
+  const loginAssist = plugin.inject("loginAssist");
+  if (!loginAssist) {
+    throw new Error("loginAssist 服务不可用，请确保已加载 zhin 核心服务");
+  }
+  void loginAssist.waitForInput("weixin-ilink", config.name, "qrcode", {
+    message: "请用微信扫描 ClawBot 二维码完成登录",
+    image: qrcodeUrl.startsWith("data:") ? qrcodeUrl : undefined,
+    url: qrcodeUrl.startsWith("http") ? qrcodeUrl : undefined,
+    qrcode: qr.qrcode,
+  });
+  const assistTask = loginAssist
+    .listPending()
+    .find((t) => t.adapter === "weixin-ilink" && t.botId === config.name);
+
+  const deadline = Date.now() + LOGIN_TIMEOUT_MS;
+  let currentBaseUrl = apiBaseUrl;
+
+  try {
+    while (Date.now() < deadline) {
+      const status = await pollQRStatus(currentBaseUrl, qr.qrcode);
+
+      if (status.status === "scaned_but_redirect" && status.redirect_host) {
+        currentBaseUrl = status.redirect_host.startsWith("http")
+          ? status.redirect_host
+          : `https://${status.redirect_host}`;
+      }
+
+      if (status.status === "confirmed" || status.status === "binded_redirect") {
+        if (!status.bot_token && status.status !== "binded_redirect") {
+          throw new Error("扫码成功但未返回 bot_token");
+        }
+        const creds: WeixinIlinkCredentials = {
+          botToken: status.bot_token ?? loadCredentials(config.name)?.botToken ?? "",
+          ilinkUserId: status.ilink_user_id,
+          ilinkBotId: status.ilink_bot_id,
+          baseUrl: status.baseurl ?? currentBaseUrl,
+        };
+        if (!creds.botToken) {
+          throw new Error("binded_redirect 但本地无有效 bot_token");
+        }
+        saveCredentials(config.name, creds);
+        if (assistTask) loginAssist.submit(assistTask.id, "confirmed");
+        return creds;
+      }
+
+      if (status.status === "expired") {
+        if (assistTask) loginAssist.cancel(assistTask.id, "expired");
+        throw new Error("二维码已过期，请重启 bot 重新登录");
+      }
+
+      await new Promise((r) => setTimeout(r, 500));
+    }
+    if (assistTask) loginAssist.cancel(assistTask.id, "timeout");
+    throw new Error("微信扫码登录超时");
+  } catch (err) {
+    if (assistTask) loginAssist.cancel(assistTask.id, String(err));
+    throw err;
+  }
+}

package/src/media-download.ts

@@ -0,0 +1,149 @@
+import type { WeixinInboundMediaOpts } from "./weixin-inbound.js";
+import { logger } from "./ilink-logger.js";
+import { getMimeFromFilename } from "./mime.js";
+import {
+  downloadAndDecryptBuffer,
+  downloadPlainCdnBuffer,
+} from "./pic-decrypt.js";
+import { silkToWav } from "./silk-transcode.js";
+import type { WeixinMessage } from "./ilink-types.js";
+import { MessageItemType } from "./ilink-types.js";
+
+const WEIXIN_MEDIA_MAX_BYTES = 100 * 1024 * 1024;
+
+/** Persist a buffer via the framework's unified media store. */
+type SaveMediaFn = (
+  buffer: Buffer,
+  contentType?: string,
+  subdir?: string,
+  maxBytes?: number,
+  originalFilename?: string,
+) => Promise<{ path: string }>;
+
+/**
+ * Download and decrypt media from a single MessageItem.
+ * Returns the populated WeixinInboundMediaOpts fields; empty object on unsupported type or failure.
+ */
+export async function downloadMediaFromItem(
+  item: WeixinMessage["item_list"] extends (infer T)[] | undefined ? T : never,
+  deps: {
+    cdnBaseUrl: string;
+    saveMedia: SaveMediaFn;
+    log: (msg: string) => void;
+    errLog: (msg: string) => void;
+    label: string;
+  },
+): Promise<WeixinInboundMediaOpts> {
+  const { cdnBaseUrl, saveMedia, log, errLog, label } = deps;
+  const result: WeixinInboundMediaOpts = {};
+
+  if (item.type === MessageItemType.IMAGE) {
+    const img = item.image_item;
+    if (!img?.media?.encrypt_query_param && !img?.media?.full_url) return result;
+    const aesKeyBase64 = img.aeskey
+      ? Buffer.from(img.aeskey, "hex").toString("base64")
+      : img.media.aes_key;
+    logger.debug(
+      `${label} image: encrypt_query_param=${(img.media.encrypt_query_param ?? "").slice(0, 40)}... hasAesKey=${Boolean(aesKeyBase64)} aeskeySource=${img.aeskey ? "image_item.aeskey" : "media.aes_key"} full_url=${Boolean(img.media.full_url)}`,
+    );
+    try {
+      const buf = aesKeyBase64
+        ? await downloadAndDecryptBuffer(
+            img.media.encrypt_query_param ?? "",
+            aesKeyBase64,
+            cdnBaseUrl,
+            `${label} image`,
+            img.media.full_url,
+          )
+        : await downloadPlainCdnBuffer(
+            img.media.encrypt_query_param ?? "",
+            cdnBaseUrl,
+            `${label} image-plain`,
+            img.media.full_url,
+          );
+      const saved = await saveMedia(buf, undefined, "inbound", WEIXIN_MEDIA_MAX_BYTES);
+      result.decryptedPicPath = saved.path;
+      logger.debug(`${label} image saved: ${saved.path}`);
+    } catch (err) {
+      logger.error(`${label} image download/decrypt failed: ${String(err)}`);
+      errLog(`weixin ${label} image download/decrypt failed: ${String(err)}`);
+    }
+  } else if (item.type === MessageItemType.VOICE) {
+    const voice = item.voice_item;
+    if ((!voice?.media?.encrypt_query_param && !voice?.media?.full_url) || !voice?.media?.aes_key)
+      return result;
+    try {
+      const silkBuf = await downloadAndDecryptBuffer(
+        voice.media.encrypt_query_param ?? "",
+        voice.media.aes_key,
+        cdnBaseUrl,
+        `${label} voice`,
+        voice.media.full_url,
+      );
+      logger.debug(`${label} voice: decrypted ${silkBuf.length} bytes, attempting silk transcode`);
+      const wavBuf = await silkToWav(silkBuf);
+      if (wavBuf) {
+        const saved = await saveMedia(wavBuf, "audio/wav", "inbound", WEIXIN_MEDIA_MAX_BYTES);
+        result.decryptedVoicePath = saved.path;
+        result.voiceMediaType = "audio/wav";
+        logger.debug(`${label} voice: saved WAV to ${saved.path}`);
+      } else {
+        const saved = await saveMedia(silkBuf, "audio/silk", "inbound", WEIXIN_MEDIA_MAX_BYTES);
+        result.decryptedVoicePath = saved.path;
+        result.voiceMediaType = "audio/silk";
+        logger.debug(`${label} voice: silk transcode unavailable, saved raw SILK to ${saved.path}`);
+      }
+    } catch (err) {
+      logger.error(`${label} voice download/transcode failed: ${String(err)}`);
+      errLog(`weixin ${label} voice download/transcode failed: ${String(err)}`);
+    }
+  } else if (item.type === MessageItemType.FILE) {
+    const fileItem = item.file_item;
+    if ((!fileItem?.media?.encrypt_query_param && !fileItem?.media?.full_url) || !fileItem?.media?.aes_key)
+      return result;
+    try {
+      const buf = await downloadAndDecryptBuffer(
+        fileItem.media.encrypt_query_param ?? "",
+        fileItem.media.aes_key,
+        cdnBaseUrl,
+        `${label} file`,
+        fileItem.media.full_url,
+      );
+      const mime = getMimeFromFilename(fileItem.file_name ?? "file.bin");
+      const saved = await saveMedia(
+        buf,
+        mime,
+        "inbound",
+        WEIXIN_MEDIA_MAX_BYTES,
+        fileItem.file_name ?? undefined,
+      );
+      result.decryptedFilePath = saved.path;
+      result.fileMediaType = mime;
+      logger.debug(`${label} file: saved to ${saved.path} mime=${mime}`);
+    } catch (err) {
+      logger.error(`${label} file download failed: ${String(err)}`);
+      errLog(`weixin ${label} file download failed: ${String(err)}`);
+    }
+  } else if (item.type === MessageItemType.VIDEO) {
+    const videoItem = item.video_item;
+    if ((!videoItem?.media?.encrypt_query_param && !videoItem?.media?.full_url) || !videoItem?.media?.aes_key)
+      return result;
+    try {
+      const buf = await downloadAndDecryptBuffer(
+        videoItem.media.encrypt_query_param ?? "",
+        videoItem.media.aes_key,
+        cdnBaseUrl,
+        `${label} video`,
+        videoItem.media.full_url,
+      );
+      const saved = await saveMedia(buf, "video/mp4", "inbound", WEIXIN_MEDIA_MAX_BYTES);
+      result.decryptedVideoPath = saved.path;
+      logger.debug(`${label} video: saved to ${saved.path}`);
+    } catch (err) {
+      logger.error(`${label} video download failed: ${String(err)}`);
+      errLog(`weixin ${label} video download failed: ${String(err)}`);
+    }
+  }
+
+  return result;
+}

package/src/mime.test.ts

@@ -0,0 +1,74 @@
+import { describe, it, expect } from "vitest";
+import { getMimeFromFilename, getExtensionFromMime, getExtensionFromContentTypeOrUrl } from "./mime.js";
+
+describe("getMimeFromFilename", () => {
+  it("returns correct MIME for known extensions", () => {
+    expect(getMimeFromFilename("photo.png")).toBe("image/png");
+    expect(getMimeFromFilename("doc.pdf")).toBe("application/pdf");
+    expect(getMimeFromFilename("video.mp4")).toBe("video/mp4");
+    expect(getMimeFromFilename("audio.mp3")).toBe("audio/mpeg");
+    expect(getMimeFromFilename("image.jpg")).toBe("image/jpeg");
+    expect(getMimeFromFilename("image.jpeg")).toBe("image/jpeg");
+    expect(getMimeFromFilename("data.csv")).toBe("text/csv");
+  });
+
+  it("is case-insensitive", () => {
+    expect(getMimeFromFilename("PHOTO.PNG")).toBe("image/png");
+    expect(getMimeFromFilename("file.PDF")).toBe("application/pdf");
+  });
+
+  it("returns application/octet-stream for unknown extensions", () => {
+    expect(getMimeFromFilename("file.xyz")).toBe("application/octet-stream");
+    expect(getMimeFromFilename("noext")).toBe("application/octet-stream");
+  });
+
+  it("handles paths with directories", () => {
+    expect(getMimeFromFilename("/path/to/photo.png")).toBe("image/png");
+  });
+});
+
+describe("getExtensionFromMime", () => {
+  it("returns correct extension for known MIME types", () => {
+    expect(getExtensionFromMime("image/jpeg")).toBe(".jpg");
+    expect(getExtensionFromMime("image/png")).toBe(".png");
+    expect(getExtensionFromMime("video/mp4")).toBe(".mp4");
+    expect(getExtensionFromMime("application/pdf")).toBe(".pdf");
+  });
+
+  it("handles MIME with parameters", () => {
+    expect(getExtensionFromMime("image/jpeg; charset=utf-8")).toBe(".jpg");
+    expect(getExtensionFromMime("text/plain; boundary=something")).toBe(".txt");
+  });
+
+  it("returns .bin for unknown MIME types", () => {
+    expect(getExtensionFromMime("application/unknown")).toBe(".bin");
+    expect(getExtensionFromMime("x-custom/type")).toBe(".bin");
+  });
+
+  it("handles image/jpg alias", () => {
+    expect(getExtensionFromMime("image/jpg")).toBe(".jpg");
+  });
+});
+
+describe("getExtensionFromContentTypeOrUrl", () => {
+  it("prefers Content-Type when it resolves to a known extension", () => {
+    expect(getExtensionFromContentTypeOrUrl("image/png", "https://example.com/file.jpg")).toBe(".png");
+  });
+
+  it("falls back to URL extension when Content-Type is unknown", () => {
+    expect(getExtensionFromContentTypeOrUrl("application/unknown", "https://example.com/file.jpg")).toBe(".jpg");
+  });
+
+  it("falls back to URL extension when Content-Type is null", () => {
+    expect(getExtensionFromContentTypeOrUrl(null, "https://example.com/file.mp4")).toBe(".mp4");
+  });
+
+  it("returns .bin when neither Content-Type nor URL has a known extension", () => {
+    expect(getExtensionFromContentTypeOrUrl(null, "https://example.com/file")).toBe(".bin");
+    expect(getExtensionFromContentTypeOrUrl("application/unknown", "https://example.com/file.xyz")).toBe(".bin");
+  });
+
+  it("handles URL with query parameters", () => {
+    expect(getExtensionFromContentTypeOrUrl(null, "https://example.com/file.png?token=abc")).toBe(".png");
+  });
+});

package/src/mime.ts

@@ -0,0 +1,105 @@
+import path from "node:path";
+
+const EXTENSION_TO_MIME: Record<string, string> = {
+  ".pdf": "application/pdf",
+  ".doc": "application/msword",
+  ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+  ".xls": "application/vnd.ms-excel",
+  ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+  ".ppt": "application/vnd.ms-powerpoint",
+  ".pptx": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
+  ".txt": "text/plain",
+  ".csv": "text/csv",
+  ".zip": "application/zip",
+  ".tar": "application/x-tar",
+  ".gz": "application/gzip",
+  ".mp3": "audio/mpeg",
+  ".ogg": "audio/ogg",
+  ".wav": "audio/wav",
+  ".mp4": "video/mp4",
+  ".mov": "video/quicktime",
+  ".webm": "video/webm",
+  ".mkv": "video/x-matroska",
+  ".avi": "video/x-msvideo",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".bmp": "image/bmp",
+};
+
+const MIME_TO_EXTENSION: Record<string, string> = {
+  "image/jpeg": ".jpg",
+  "image/jpg": ".jpg",
+  "image/png": ".png",
+  "image/gif": ".gif",
+  "image/webp": ".webp",
+  "image/bmp": ".bmp",
+  "video/mp4": ".mp4",
+  "video/quicktime": ".mov",
+  "video/webm": ".webm",
+  "video/x-matroska": ".mkv",
+  "video/x-msvideo": ".avi",
+  "audio/mpeg": ".mp3",
+  "audio/ogg": ".ogg",
+  "audio/wav": ".wav",
+  "application/pdf": ".pdf",
+  "application/zip": ".zip",
+  "application/x-tar": ".tar",
+  "application/gzip": ".gz",
+  "text/plain": ".txt",
+  "text/csv": ".csv",
+};
+
+/** Get MIME type from filename extension. Returns "application/octet-stream" for unknown extensions. */
+export function getMimeFromFilename(filename: string): string {
+  const ext = path.extname(filename).toLowerCase();
+  return EXTENSION_TO_MIME[ext] ?? "application/octet-stream";
+}
+
+/** Get file extension from MIME type. Returns ".bin" for unknown types. */
+export function getExtensionFromMime(mimeType: string): string {
+  const ct = mimeType.split(";")[0].trim().toLowerCase();
+  return MIME_TO_EXTENSION[ct] ?? ".bin";
+}
+
+/** Sniff common image/video MIME from magic bytes. */
+export function sniffMimeFromBuffer(buf: Buffer): string | undefined {
+  if (buf.length >= 3 && buf[0] === 0xff && buf[1] === 0xd8 && buf[2] === 0xff) {
+    return "image/jpeg";
+  }
+  if (
+    buf.length >= 8 &&
+    buf[0] === 0x89 &&
+    buf[1] === 0x50 &&
+    buf[2] === 0x4e &&
+    buf[3] === 0x47
+  ) {
+    return "image/png";
+  }
+  if (buf.length >= 6 && buf.slice(0, 6).toString("ascii") === "GIF87a") {
+    return "image/gif";
+  }
+  if (buf.length >= 6 && buf.slice(0, 6).toString("ascii") === "GIF89a") {
+    return "image/gif";
+  }
+  if (buf.length >= 12 && buf.slice(0, 4).toString("ascii") === "RIFF" && buf.slice(8, 12).toString("ascii") === "WEBP") {
+    return "image/webp";
+  }
+  if (buf.length >= 8 && buf.slice(4, 8).toString("ascii") === "ftyp") {
+    return "video/mp4";
+  }
+  return undefined;
+}
+
+/** Get file extension from Content-Type header or URL path. Returns ".bin" for unknown. */
+export function getExtensionFromContentTypeOrUrl(contentType: string | null, url: string): string {
+  if (contentType) {
+    const ext = getExtensionFromMime(contentType);
+    if (ext !== ".bin") return ext;
+  }
+  const ext = path.extname(new URL(url).pathname).toLowerCase();
+  const knownExts = new Set(Object.keys(EXTENSION_TO_MIME));
+  return knownExts.has(ext) ? ext : ".bin";
+}

package/src/outbound-media.ts

@@ -0,0 +1,141 @@
+/**
+ * 微信 iLink 出站媒体：base64 / 远程 URL 须落盘后再走 CDN 上传。
+ */
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import type { MessageSegment, SendContent } from "zhin.js";
+import { downloadRemoteImageToTemp } from "./upload.js";
+import { getExtensionFromMime } from "./mime.js";
+
+const MEDIA_TYPES = new Set(["image", "video", "file", "record", "audio"]);
+
+function isRemoteUrl(value: string): boolean {
+  return /^https?:\/\//i.test(value);
+}
+
+function isInlineMediaRef(value: string): boolean {
+  return value.startsWith("base64://") || /^data:[^/]+\/[^;]+;base64,/i.test(value);
+}
+
+function normalizeLocalPath(value: string): string {
+  return value.replace(/^file:\/\//, "");
+}
+
+export function segmentMediaRef(seg: MessageSegment): string | undefined {
+  const data = seg.data as Record<string, unknown>;
+  const candidates = [data.file, data.path, data.url].filter((v): v is string => typeof v === "string" && Boolean(v));
+  return candidates[0];
+}
+
+function extractBase64Buffer(data: Record<string, unknown>): Buffer | undefined {
+  const url = typeof data.url === "string" ? data.url : undefined;
+  const file = typeof data.file === "string" ? data.file : undefined;
+  const base64 = typeof data.base64 === "string" ? data.base64 : undefined;
+
+  if (url?.startsWith("base64://")) {
+    return Buffer.from(url.slice(9), "base64");
+  }
+  if (url && /^data:[^/]+\/[^;]+;base64,/i.test(url)) {
+    return Buffer.from(url.replace(/^data:[^/]+\/[^;]+;base64,/, ""), "base64");
+  }
+  if (file?.startsWith("base64://")) {
+    return Buffer.from(file.slice(9), "base64");
+  }
+  if (base64) {
+    const raw = base64.startsWith("base64://") ? base64.slice(9) : base64;
+    return Buffer.from(raw, "base64");
+  }
+  return undefined;
+}
+
+function resolveExt(seg: MessageSegment, mime?: string): string {
+  const data = seg.data as Record<string, unknown>;
+  const name = typeof data.name === "string" ? data.name : undefined;
+  if (name) {
+    const ext = path.extname(name);
+    if (ext) return ext;
+  }
+  const mimeHint = mime ?? (typeof data.mime === "string" ? data.mime : typeof data.mimeType === "string" ? data.mimeType : undefined);
+  if (mimeHint) {
+    return getExtensionFromMime(mimeHint) ?? ".bin";
+  }
+  if (seg.type === "image") return ".png";
+  if (seg.type === "video") return ".mp4";
+  if (seg.type === "record" || seg.type === "audio") return ".mp3";
+  return ".bin";
+}
+
+function withLocalFile(seg: MessageSegment, filePath: string): MessageSegment {
+  const data = { ...seg.data, file: filePath } as Record<string, unknown>;
+  delete data.base64;
+  return { type: seg.type, data } as MessageSegment;
+}
+
+function writeOutboundBuffer(buffer: Buffer, outboundDir: string, seg: MessageSegment): string {
+  fs.mkdirSync(outboundDir, { recursive: true });
+  const ext = resolveExt(seg);
+  const filePath = path.join(
+    outboundDir,
+    `out-${seg.type}-${Date.now()}-${crypto.randomBytes(4).toString("hex")}${ext}`,
+  );
+  fs.writeFileSync(filePath, buffer);
+  return filePath;
+}
+
+async function materializeSegment(
+  seg: MessageSegment,
+  outboundDir: string,
+): Promise<MessageSegment> {
+  if (!MEDIA_TYPES.has(seg.type)) return seg;
+
+  const ref = segmentMediaRef(seg);
+  if (ref && !isInlineMediaRef(ref)) {
+    const local = normalizeLocalPath(ref);
+    if (isRemoteUrl(local)) {
+      const downloaded = await downloadRemoteImageToTemp(local, outboundDir);
+      return withLocalFile(seg, downloaded);
+    }
+    if (fs.existsSync(local)) {
+      return withLocalFile(seg, local);
+    }
+  }
+
+  const buffer = extractBase64Buffer(seg.data as Record<string, unknown>);
+  if (buffer) {
+    return withLocalFile(seg, writeOutboundBuffer(buffer, outboundDir, seg));
+  }
+
+  return seg;
+}
+
+function asSegments(content: SendContent): MessageSegment[] {
+  if (typeof content === "string") {
+    return [{ type: "text", data: { text: content } }];
+  }
+  if (!Array.isArray(content)) {
+    return typeof content === "object" && content !== null && "type" in content
+      ? [content as MessageSegment]
+      : [];
+  }
+  return content.flatMap((item) => {
+    if (typeof item === "string") return [{ type: "text", data: { text: item } } as MessageSegment];
+    return typeof item === "object" && item !== null && "type" in item ? [item as MessageSegment] : [];
+  });
+}
+
+/** 将 base64 / 远程图落盘，供 sendWeixinMediaFile 上传 */
+export async function materializeOutboundMedia(
+  content: SendContent,
+  outboundDir: string,
+): Promise<SendContent> {
+  const segments = asSegments(content);
+  const out = await Promise.all(segments.map((seg) => materializeSegment(seg, outboundDir)));
+  if (typeof content === "string") {
+    return out[0]?.type === "text" ? (out[0].data as { text: string }).text : content;
+  }
+  if (!Array.isArray(content)) {
+    return out[0] ?? content;
+  }
+  return out;
+}