@openclaw-channel/socket-chat 1.0.3 → 1.0.5

package/README.md

@@ -30,6 +30,16 @@ openclaw plugins install /path/to/socket-chat
 
 ---
 
+## 通过 CLI 添加账号
+
+apiKey 从微秘书平台[个人中心](https://wechat.aibotk.com/user/info)获取
+
+```bash
+openclaw channels add --channel socket-chat --token <apiKey>
+```
+
+---
+
 ## 配置
 
 在 `~/.openclaw/config.yaml` 中添加：
@@ -126,15 +136,7 @@ channels:
 
 ---
 
-## 通过 CLI 添加账号
-
-apiKey 从微秘书平台[个人中心](https://wechat.aibotk.com/user/info)获取
-
-```bash
-openclaw channels add socket-chat --token <apiKey>
-```
 
----
 
 ## 消息格式
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@openclaw-channel/socket-chat",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "description": "OpenClaw Socket Chat channel plugin — MQTT-based IM bridge",
   "type": "module",
   "publishConfig": {

package/src/__sdk-stub__.ts

@@ -7,6 +7,9 @@
  */
 export { resolveAllowlistMatchByCandidates } from "../../openclaw/src/channels/allowlist-match.js";
 export { createNormalizedOutboundDeliverer } from "../../openclaw/src/plugin-sdk/reply-payload.js";
+export { buildMediaPayload } from "../../openclaw/src/channels/plugins/media-payload.js";
+export { resolveChannelMediaMaxBytes } from "../../openclaw/src/channels/plugins/media-limits.js";
+export { detectMime } from "../../openclaw/src/media/mime.js";
 
 // ---- type-only re-exports (erased at runtime) ----
 export type { ChannelGatewayContext } from "../../openclaw/src/plugin-sdk/index.js";

package/src/channel.ts

@@ -242,7 +242,7 @@ export const socketChatPlugin: ChannelPlugin<ResolvedSocketChatAccount> = {
     normalizeTarget: normalizeSocketChatTarget,
     targetResolver: {
       looksLikeId: looksLikeSocketChatTargetId,
-      hint: "<contactId|group:groupId|group:groupId@wxid_mention1,wxid_mention2>",
+      hint: "<contactId|group:groupId|group:groupId@userId1,userId2>",
     },
   },
 
@@ -386,7 +386,7 @@ export const socketChatPlugin: ChannelPlugin<ResolvedSocketChatAccount> = {
       "- socket-chat: to send to a group, use target format `group:<groupId>`. " +
         "To @mention users in a group: `group:<groupId>@<userId1>,<userId2>`.",
       "- socket-chat: to send an image, provide a public HTTP URL as the media parameter.",
-      "- socket-chat: direct messages use the sender's contactId (e.g. `wxid_xxx`) as the target.",
+      "- socket-chat: direct messages use the sender's contactId as the target.",
     ],
   },
 };

package/src/config-schema.ts

@@ -56,6 +56,8 @@ export const SocketChatAccountConfigSchema = z.object({
    * 不配置或为空则允许群内所有成员触发（受 requireMention 约束）
    */
   groupAllowFrom: z.array(z.string()).optional(),
+  /** 媒体文件大小上限（MB）。未配置时使用框架全局默认值 */
+  mediaMaxMb: z.number().optional(),
   /** MQTT 连接配置缓存 TTL（秒），默认 300 */
   mqttConfigTtlSec: z.number().optional(),
   /** MQTT 重连最大次数，默认 10 */

package/src/inbound.test.ts

@@ -40,6 +40,16 @@ type MockChannelRuntime = {
   activity: {
     record: ReturnType<typeof vi.fn>;
   };
+  channel: {
+    media: {
+      fetchRemoteMedia: ReturnType<typeof vi.fn>;
+      saveMediaBuffer: ReturnType<typeof vi.fn>;
+    };
+  };
+  media: {
+    fetchRemoteMedia: ReturnType<typeof vi.fn>;
+    saveMediaBuffer: ReturnType<typeof vi.fn>;
+  };
 };
 
 function makeMockRuntime(overrides: Partial<MockChannelRuntime> = {}): MockChannelRuntime {
@@ -72,6 +82,30 @@ function makeMockRuntime(overrides: Partial<MockChannelRuntime> = {}): MockChann
       record: vi.fn(),
       ...overrides.activity,
     },
+    channel: {
+      media: {
+        fetchRemoteMedia: vi.fn(async () => ({
+          buffer: Buffer.from("fake-image-data"),
+          contentType: "image/jpeg",
+        })),
+        saveMediaBuffer: vi.fn(async () => ({
+          path: "/tmp/openclaw/inbound/saved-img.jpg",
+          contentType: "image/jpeg",
+        })),
+        ...overrides.channel?.media,
+      },
+    },
+    media: {
+      fetchRemoteMedia: vi.fn(async () => ({
+        buffer: Buffer.from("fake-image-data"),
+        contentType: "image/jpeg",
+      })),
+      saveMediaBuffer: vi.fn(async () => ({
+        path: "/tmp/openclaw/inbound/saved-img.jpg",
+        contentType: "image/jpeg",
+      })),
+      ...overrides.media,
+    },
   };
 }
 
@@ -508,8 +542,13 @@ describe("handleInboundMessage — group messages", () => {
 // ---------------------------------------------------------------------------
 
 describe("handleInboundMessage — media messages", () => {
-  it("passes MediaUrl fields when msg has an HTTP url (image)", async () => {
+  it("downloads image URL and passes local path as MediaPath/MediaUrl", async () => {
     const runtime = makeMockRuntime();
+    runtime.media.saveMediaBuffer.mockResolvedValue({
+      path: "/tmp/openclaw/inbound/img-001.jpg",
+      contentType: "image/jpeg",
+    });
+
     const ctx = makeCtx(runtime, {
       channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
     });
@@ -518,7 +557,7 @@ describe("handleInboundMessage — media messages", () => {
       msg: makeMsg({
         type: "图片",
         url: "https://oss.example.com/img.jpg",
-        content: "【图片消息】\n文件名：img.jpg\n下载链接：https://oss.example.com/img.jpg",
+        content: "【图片消息】\n文件名：img.jpg",
       }),
       accountId: "default",
       ctx: ctx as never,
@@ -526,19 +565,36 @@ describe("handleInboundMessage — media messages", () => {
       sendReply: vi.fn(async () => {}),
     });
 
+    // fetchRemoteMedia should have been called with the original URL
+    expect(runtime.media.fetchRemoteMedia).toHaveBeenCalledWith(
+      expect.objectContaining({ url: "https://oss.example.com/img.jpg" }),
+    );
+    // saveMediaBuffer should have been called
+    expect(runtime.media.saveMediaBuffer).toHaveBeenCalledOnce();
+    // ctxPayload should carry the saved local path, not the original URL
     expect(runtime.reply.finalizeInboundContext).toHaveBeenCalledWith(
       expect.objectContaining({
-        MediaUrl: "https://oss.example.com/img.jpg",
-        MediaUrls: ["https://oss.example.com/img.jpg"],
-        MediaPath: "https://oss.example.com/img.jpg",
+        MediaPath: "/tmp/openclaw/inbound/img-001.jpg",
+        MediaUrl: "/tmp/openclaw/inbound/img-001.jpg",
+        MediaPaths: ["/tmp/openclaw/inbound/img-001.jpg"],
+        MediaUrls: ["/tmp/openclaw/inbound/img-001.jpg"],
         MediaType: "image/jpeg",
       }),
     );
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
   });
 
-  it("passes MediaUrl fields when msg has an HTTP url (video)", async () => {
+  it("downloads video URL and detects correct content type", async () => {
     const runtime = makeMockRuntime();
+    runtime.media.fetchRemoteMedia.mockResolvedValue({
+      buffer: Buffer.from("fake-video-data"),
+      contentType: "video/mp4",
+    });
+    runtime.media.saveMediaBuffer.mockResolvedValue({
+      path: "/tmp/openclaw/inbound/video-001.mp4",
+      contentType: "video/mp4",
+    });
+
     const ctx = makeCtx(runtime, {
       channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
     });
@@ -547,7 +603,7 @@ describe("handleInboundMessage — media messages", () => {
       msg: makeMsg({
         type: "视频",
         url: "https://oss.example.com/video.mp4",
-        content: "【视频消息】\n文件名：video.mp4\n下载链接：https://oss.example.com/video.mp4",
+        content: "【视频消息】",
       }),
       accountId: "default",
       ctx: ctx as never,
@@ -557,23 +613,97 @@ describe("handleInboundMessage — media messages", () => {
 
     expect(runtime.reply.finalizeInboundContext).toHaveBeenCalledWith(
       expect.objectContaining({
-        MediaUrl: "https://oss.example.com/video.mp4",
+        MediaPath: "/tmp/openclaw/inbound/video-001.mp4",
         MediaType: "video/mp4",
       }),
     );
   });
 
-  it("does NOT pass MediaUrl for base64 url (no OSS configured)", async () => {
+  it("decodes base64 data URL and saves to local file", async () => {
+    const runtime = makeMockRuntime();
+    runtime.media.saveMediaBuffer.mockResolvedValue({
+      path: "/tmp/openclaw/inbound/b64-img.jpg",
+      contentType: "image/jpeg",
+    });
+
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
+    });
+
+    // minimal valid JPEG-ish base64
+    const fakeBase64 = Buffer.from("fake-jpeg-bytes").toString("base64");
+    await handleInboundMessage({
+      msg: makeMsg({
+        type: "图片",
+        url: `data:image/jpeg;base64,${fakeBase64}`,
+        content: "【图片消息】",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log: ctx.log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    // Should NOT call fetchRemoteMedia for data URLs
+    expect(runtime.media.fetchRemoteMedia).not.toHaveBeenCalled();
+    // Should call saveMediaBuffer with decoded buffer
+    expect(runtime.media.saveMediaBuffer).toHaveBeenCalledOnce();
+    const [savedBuf, savedMime] = runtime.media.saveMediaBuffer.mock.calls[0] as [Buffer, string];
+    expect(Buffer.isBuffer(savedBuf)).toBe(true);
+    expect(savedBuf.toString()).toBe("fake-jpeg-bytes");
+    expect(savedMime).toBe("image/jpeg");
+    // ctxPayload should carry the local path
+    expect(runtime.reply.finalizeInboundContext).toHaveBeenCalledWith(
+      expect.objectContaining({
+        MediaPath: "/tmp/openclaw/inbound/b64-img.jpg",
+        MediaUrl: "/tmp/openclaw/inbound/b64-img.jpg",
+      }),
+    );
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("skips base64 media that exceeds maxBytes and continues dispatch", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      // 1 MB limit
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open", mediaMaxMb: 1 } },
+    });
+    const log = { ...ctx.log, warn: vi.fn() };
+
+    // ~2 MB of base64 data (each char ≈ 0.75 bytes → need > 1.4M chars)
+    const bigBase64 = "A".repeat(1_500_000);
+    await handleInboundMessage({
+      msg: makeMsg({
+        type: "图片",
+        url: `data:image/jpeg;base64,${bigBase64}`,
+        content: "【图片消息】",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    expect(log.warn).toHaveBeenCalledWith(expect.stringContaining("media localization failed"));
+    expect(runtime.media.saveMediaBuffer).not.toHaveBeenCalled();
+    // Dispatch still proceeds without media fields
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+    const callArg = runtime.reply.finalizeInboundContext.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(callArg).not.toHaveProperty("MediaPath");
+  });
+
+  it("does not call fetchRemoteMedia for base64 data URLs (uses saveMediaBuffer directly)", async () => {
     const runtime = makeMockRuntime();
     const ctx = makeCtx(runtime, {
       channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
     });
 
+    const fakeBase64 = Buffer.from("img-bytes").toString("base64");
     await handleInboundMessage({
       msg: makeMsg({
         type: "图片",
-        url: "data:image/jpeg;base64,/9j/4AAQ...",
-        content: "【图片消息】\n文件名：img.jpg\n文件大小：12345 bytes",
+        url: `data:image/jpeg;base64,${fakeBase64}`,
+        content: "【图片消息】",
       }),
       accountId: "default",
       ctx: ctx as never,
@@ -581,9 +711,88 @@ describe("handleInboundMessage — media messages", () => {
       sendReply: vi.fn(async () => {}),
     });
 
+    expect(runtime.media.fetchRemoteMedia).not.toHaveBeenCalled();
+    expect(runtime.media.saveMediaBuffer).toHaveBeenCalledOnce();
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+  });
+
+  it("does not call fetchRemoteMedia when url is absent", async () => {
+    const runtime = makeMockRuntime();
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
+    });
+
+    await handleInboundMessage({
+      msg: makeMsg({ content: "plain text, no media" }),
+      accountId: "default",
+      ctx: ctx as never,
+      log: ctx.log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    expect(runtime.media.fetchRemoteMedia).not.toHaveBeenCalled();
+    expect(runtime.media.saveMediaBuffer).not.toHaveBeenCalled();
+    const callArg = runtime.reply.finalizeInboundContext.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(callArg).not.toHaveProperty("MediaPath");
+  });
+
+  it("continues dispatch and logs warning when media download fails", async () => {
+    const runtime = makeMockRuntime();
+    runtime.media.fetchRemoteMedia.mockRejectedValue(new Error("network timeout"));
+
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
+    });
+    const log = { ...ctx.log, warn: vi.fn() };
+
+    await handleInboundMessage({
+      msg: makeMsg({
+        type: "图片",
+        url: "https://oss.example.com/img.jpg",
+        content: "【图片消息】",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    // Warning logged
+    expect(log.warn).toHaveBeenCalledWith(
+      expect.stringContaining("media localization failed"),
+    );
+    // Dispatch still proceeds (text body)
+    expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
+    // No media fields in ctxPayload
     const callArg = runtime.reply.finalizeInboundContext.mock.calls[0]?.[0] as Record<string, unknown>;
+    expect(callArg).not.toHaveProperty("MediaPath");
     expect(callArg).not.toHaveProperty("MediaUrl");
-    expect(callArg).not.toHaveProperty("MediaUrls");
+  });
+
+  it("continues dispatch and logs warning when saveMediaBuffer fails", async () => {
+    const runtime = makeMockRuntime();
+    runtime.media.saveMediaBuffer.mockRejectedValue(new Error("disk full"));
+
+    const ctx = makeCtx(runtime, {
+      channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", dmPolicy: "open" } },
+    });
+    const log = { ...ctx.log, warn: vi.fn() };
+
+    await handleInboundMessage({
+      msg: makeMsg({
+        type: "图片",
+        url: "https://oss.example.com/img.jpg",
+        content: "【图片消息】",
+      }),
+      accountId: "default",
+      ctx: ctx as never,
+      log,
+      sendReply: vi.fn(async () => {}),
+    });
+
+    expect(log.warn).toHaveBeenCalledWith(
+      expect.stringContaining("media localization failed"),
+    );
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
   });
 
@@ -605,7 +814,6 @@ describe("handleInboundMessage — media messages", () => {
       sendReply: vi.fn(async () => {}),
     });
 
-    // Should not be skipped — dispatches even without text content
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
   });
 
@@ -666,6 +874,7 @@ describe("handleInboundMessage — media messages", () => {
     });
 
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
+    expect(runtime.media.fetchRemoteMedia).not.toHaveBeenCalled();
   });
 });
 
@@ -787,7 +996,7 @@ describe("handleInboundMessage — group access control (tier 1: groupId)", () =
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).toHaveBeenCalledOnce();
   });
 
-  it("blocks unlisted group and sends one-time notification", async () => {
+  it("blocks unlisted group without sending notification (notify branch commented out)", async () => {
     const runtime = makeMockRuntime();
     const ctx = makeCtx(runtime, {
       channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["R:allowed_group"] } },
@@ -798,12 +1007,11 @@ describe("handleInboundMessage — group access control (tier 1: groupId)", () =
       accountId: "default", ctx: ctx as never, log: ctx.log, sendReply,
     });
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
-    expect(sendReply).toHaveBeenCalledOnce();
-    expect(sendReply.mock.calls[0]?.[0]).toBe("group:R:other_group");
-    expect(sendReply.mock.calls[0]?.[1]).toContain("R:other_group");
+    // Notification is currently disabled (commented out in inbound.ts)
+    expect(sendReply).not.toHaveBeenCalled();
   });
 
-  it("does NOT send second notification for same blocked group", async () => {
+  it("silently blocks repeated messages from same unlisted group", async () => {
     const runtime = makeMockRuntime();
     const ctx = makeCtx(runtime, {
       channels: { "socket-chat": { apiKey: "k", apiBaseUrl: "https://x.com", groupPolicy: "allowlist", groups: ["R:allowed_group"] } },
@@ -812,7 +1020,7 @@ describe("handleInboundMessage — group access control (tier 1: groupId)", () =
     const msg = makeMsg({ isGroup: true, groupId: "R:notify_once_group", isGroupMention: true });
     await handleInboundMessage({ msg, accountId: "default", ctx: ctx as never, log: ctx.log, sendReply });
     await handleInboundMessage({ msg, accountId: "default", ctx: ctx as never, log: ctx.log, sendReply });
-    expect(sendReply).toHaveBeenCalledOnce();
+    expect(sendReply).not.toHaveBeenCalled();
     expect(runtime.reply.dispatchReplyWithBufferedBlockDispatcher).not.toHaveBeenCalled();
   });
 

package/src/inbound.ts

@@ -1,5 +1,11 @@
 import type { ChannelGatewayContext } from "openclaw/plugin-sdk";
-import { resolveAllowlistMatchByCandidates, createNormalizedOutboundDeliverer } from "openclaw/plugin-sdk";
+import {
+  resolveAllowlistMatchByCandidates,
+  createNormalizedOutboundDeliverer,
+  buildMediaPayload,
+  resolveChannelMediaMaxBytes,
+  detectMime,
+} from "openclaw/plugin-sdk";
 import { resolveSocketChatAccount, type CoreConfig } from "./config.js";
 import type { ResolvedSocketChatAccount } from "./config.js";
 import type { SocketChatInboundMessage } from "./types.js";
@@ -274,8 +280,9 @@ type LogSink = {
  * 处理 MQTT 入站消息：
  * 1. 安全策略检查（allowlist / pairing）
  * 2. 群组 @提及检查
- * 3. 路由 + 记录 session
- * 4. 派发 AI 回复
+ * 3. 媒体文件下载到本地
+ * 4. 路由 + 记录 session
+ * 5. 派发 AI 回复
  */
 export async function handleInboundMessage(params: {
   msg: SocketChatInboundMessage;
@@ -323,12 +330,12 @@ export async function handleInboundMessage(params: {
     // 第一层：groupId 是否在允许列表中
     const groupAccess = checkGroupAccess({ groupId, account, log, accountId });
     if (!groupAccess.allowed) {
-      if (groupAccess.notify) {
-        await sendReply(
-          `group:${groupId}`,
-          `此群（${msg.groupName ?? groupId}）未获授权使用 AI 服务。如需开启，请联系管理员将群 ID "${groupId}" 加入 groups 配置。`,
-        );
-      }
+      // if (groupAccess.notify) {
+      //   await sendReply(
+      //     `group:${groupId}`,
+      //     `此群（${msg.groupName ?? groupId}）未获授权使用 AI 服务。如需开启，请联系管理员将群 ID "${groupId}" 加入 groups 配置。`,
+      //   );
+      // }
       return;
     }
 
@@ -361,13 +368,78 @@ export async function handleInboundMessage(params: {
   const peerId = msg.isGroup ? (msg.groupId ?? msg.senderId) : msg.senderId;
 
   // 判断是否为媒体消息（图片/视频/文件等）
-  const mediaUrl = msg.url && !msg.url.startsWith("data:") ? msg.url : undefined;
-  // base64 内容不传给 agent（避免超长），仅标记 placeholder
   const isMediaMsg = !!msg.type && msg.type !== "文字";
   // BodyForAgent：媒体消息在 content 中已包含描述文字（如"【图片消息】\n下载链接：..."），直接使用
   const body = msg.content?.trim() || (isMediaMsg ? `<media:${msg.type}>` : "");
 
-  // ---- 3. 路由 ----
+  // ---- 3. 媒体文件本地化 ----
+  // 将媒体 URL 下载到本地，让 agent 能直接读取文件而不依赖外部 URL 的可用性。
+  // HTTP/HTTPS URL：通过 fetchRemoteMedia 下载；data: URL：直接解码 base64。
+  let resolvedMediaPayload = {};
+  const mediaUrl = msg.url?.trim();
+  if (mediaUrl) {
+    try {
+      const maxBytes = resolveChannelMediaMaxBytes({
+        cfg: ctx.cfg,
+        resolveChannelLimitMb: ({ cfg }) =>
+          (cfg as CoreConfig).channels?.["socket-chat"]?.mediaMaxMb,
+        accountId,
+      });
+
+      let buffer: Buffer;
+      let contentTypeHint: string | undefined;
+
+      if (mediaUrl.startsWith("data:")) {
+        // data URL：解析 MIME 和 base64 载荷
+        const commaIdx = mediaUrl.indexOf(",");
+        const meta = commaIdx > 0 ? mediaUrl.slice(5, commaIdx) : "";
+        const base64Data = commaIdx > 0 ? mediaUrl.slice(commaIdx + 1) : "";
+        contentTypeHint = meta.split(";")[0] || undefined;
+
+        // 大小预检（base64 字节数 × 0.75 ≈ 原始字节数）
+        const estimatedBytes = Math.ceil(base64Data.length * 0.75);
+        if (maxBytes && estimatedBytes > maxBytes) {
+          log.warn(
+            `[${accountId}] base64 media too large for ${msg.messageId} (est. ${estimatedBytes} bytes, limit ${maxBytes})`,
+          );
+          throw new Error("base64 media exceeds maxBytes limit");
+        }
+
+        buffer = Buffer.from(base64Data, "base64");
+      } else {
+        // HTTP/HTTPS URL：通过网络下载
+        const fetched = await channelRuntime.media.fetchRemoteMedia({
+          url: mediaUrl,
+          filePathHint: mediaUrl,
+          maxBytes,
+        });
+        buffer = fetched.buffer;
+        contentTypeHint = fetched.contentType;
+      }
+
+      const mime = await detectMime({
+        buffer,
+        headerMime: contentTypeHint,
+        filePath: mediaUrl,
+      });
+      const saved = await channelRuntime.media.saveMediaBuffer(
+        buffer,
+        mime ?? contentTypeHint,
+        "inbound",
+        maxBytes,
+      );
+      resolvedMediaPayload = buildMediaPayload([
+        { path: saved.path, contentType: saved.contentType },
+      ]);
+    } catch (err) {
+      // 下载/解码失败不阻断消息处理，仍正常派发文字部分
+      log.warn(
+        `[${accountId}] media localization failed for ${msg.messageId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  // ---- 4. 路由 ----
   const route = channelRuntime.routing.resolveAgentRoute({
     cfg: ctx.cfg,
     channel: "socket-chat",
@@ -382,7 +454,7 @@ export async function handleInboundMessage(params: {
     `[${accountId}] dispatch ${msg.messageId} from ${msg.senderId} → agent ${route.agentId}`,
   );
 
-  // ---- 4. 构建 MsgContext ----
+  // ---- 5. 构建 MsgContext ----
   const fromLabel = msg.isGroup
     ? `socket-chat:room:${peerId}`
     : `socket-chat:${msg.senderId}`;
@@ -396,15 +468,7 @@ export async function handleInboundMessage(params: {
     RawBody: msg.content || (msg.url ?? ""),
     BodyForAgent: body,
     CommandBody: body,
-    ...(mediaUrl
-      ? {
-          MediaUrl: mediaUrl,
-          MediaUrls: [mediaUrl],
-          MediaPath: mediaUrl,
-          // 尽量从 type 推断 MIME，否则留空由框架处理
-          MediaType: msg.type === "图片" ? "image/jpeg" : msg.type === "视频" ? "video/mp4" : undefined,
-        }
-      : {}),
+    ...resolvedMediaPayload,
     From: fromLabel,
     To: toLabel,
     SessionKey: route.sessionKey,
@@ -425,7 +489,7 @@ export async function handleInboundMessage(params: {
   });
 
   try {
-    // ---- 5. 记录 session 元数据 ----
+    // ---- 6. 记录 session 元数据 ----
     const storePath = channelRuntime.session.resolveStorePath(undefined, {
       agentId: route.agentId,
     });
@@ -445,7 +509,7 @@ export async function handleInboundMessage(params: {
       direction: "inbound",
     });
 
-    // ---- 6. 派发 AI 回复 ----
+    // ---- 7. 派发 AI 回复 ----
     // deliver 负责实际发送：框架当 originatingChannel === currentSurface 时
     // 不走 outbound adapter，直接调用此函数投递回复。
     const deliverReply = createNormalizedOutboundDeliverer(async (payload) => {

package/src/outbound.test.ts

@@ -81,25 +81,23 @@ describe("normalizeSocketChatTarget", () => {
 // ---------------------------------------------------------------------------
 
 describe("looksLikeSocketChatTargetId", () => {
-  it("recognizes wxid_ prefix", () => {
+  it("accepts any non-empty id", () => {
     expect(looksLikeSocketChatTargetId("wxid_abc123")).toBe(true);
-  });
-
-  it("recognizes roomid_ prefix", () => {
     expect(looksLikeSocketChatTargetId("roomid_xyz")).toBe(true);
-  });
-
-  it("recognizes group: prefix", () => {
     expect(looksLikeSocketChatTargetId("group:roomid_xxx")).toBe(true);
+    expect(looksLikeSocketChatTargetId("alice")).toBe(true);
+    expect(looksLikeSocketChatTargetId("user@example.com")).toBe(true);
   });
 
-  it("rejects arbitrary strings", () => {
-    expect(looksLikeSocketChatTargetId("alice")).toBe(false);
-    expect(looksLikeSocketChatTargetId("user@example.com")).toBe(false);
+  it("rejects empty string", () => {
     expect(looksLikeSocketChatTargetId("")).toBe(false);
   });
 
-  it("trims leading whitespace before checking", () => {
+  it("rejects whitespace-only string", () => {
+    expect(looksLikeSocketChatTargetId("   ")).toBe(false);
+  });
+
+  it("trims before checking", () => {
     expect(looksLikeSocketChatTargetId("  wxid_abc")).toBe(true);
   });
 });

package/src/outbound.ts

@@ -46,10 +46,10 @@ export function normalizeSocketChatTarget(raw: string): string | undefined {
 
 /**
  * 判断字符串是否像一个 socket-chat 原生 ID
- * wxid_xxx / roomid_xxx 格式，或带 group: 前缀
+ * socket-chat 的 chatId 格式不固定，任何非空字符串均视为原生 ID
  */
 export function looksLikeSocketChatTargetId(s: string): boolean {
-  return /^(wxid_|roomid_|group:)/.test(s.trim());
+  return s.trim().length > 0;
 }
 
 /**