@zhin.js/adapter-wechat-mp 4.0.4 → 5.0.0

package/CHANGELOG.md

@@ -1,5 +1,29 @@
 # @zhin.js/adapter-wechat-mp
 
+## 5.0.0
+
+### Patch Changes
+
+- 4fbff5d: feat!: 多模态双向 Segment 一贯制（BREAKING，无兼容层）
+
+  全框架唯一媒体表达统一为 canonical `Segment` + `MediaRef{kind: url|path|base64|file, value, mime_type?, file_name?, size?}`，新增 audio/video/file 段类型；所有第二形状（legacy `data.url/file/base64` 字段、`mediaRefFromLegacyData`/`mediaRefToLegacyFields` 桥、双写）全部删除。
+
+  - **core**：`SendContent` 一等支持 `Segment[]`；endpoint 出站载荷只含 canonical 段；`resolveOutboundMediaPolicy` 改为纯声明驱动（adapter definition `segments.outboundMedia`），内置策略表删除，未声明回退 `url-or-text`；`ImageContent` 旧桥删除。
+  - **ai**：新增 `MediaContentBlock`/`MediaBlockRef`（Segment 同构）与 `UserMessage.media`（当前 turn 媒体，**不持久化**——存储层自动剥离）；`createUserMessage(text, media?)` 签名变更（`ImageContent` 删除）；provider 边界序列化器 `filterMediaBlocksForProvider` + 能力表（缺省 image-only，不支持类型降级占位文本）；ai-sdk 桥媒体块 → SDK image/file parts。
+  - **agent**：入站 turn 注入（`turn/inbound-media.ts`）——commMessage 媒体段 → 当前 turn `UserMessage.media`；图片 path 物化、音频默认 STT（`@zhin.js/speech` 可选，失败降级占位）、视频/文件占位；`publishOutboundElements` 产出 canonical Segment；`transcribeAudioPayload` 导出。
+  - **cli**：`bridgeRuntimeMessage` 回复链路媒体段透传，不再压平为文本（`$reply` 直达 normalize → adapter）。
+  - **全部 20 个平台适配器**：出站媒体只消费 `data.media`（url 直发 / base64 直发 / 平台上传 / 读盘），入站媒体产出 canonical `data.media`；`segments.outboundMedia` 声明与实际消费逐一核对修正；QQ 入站新增 canonical segments（image/audio/video/file/mention/face/reply），图片/语音/视频不再丢失。
+
+  迁移：适配器/插件产媒体一律用 `{ type, data: { media: MediaRef } }`；发送 legacy `data.url/file/base64` 形状的段会被 warn 丢弃。
+
+- Updated dependencies [7c1e63a]
+- Updated dependencies [4fbff5d]
+- Updated dependencies [5b94d9c]
+  - @zhin.js/command@1.0.5
+  - @zhin.js/adapter@1.1.3
+  - @zhin.js/core@1.5.0
+  - zhin.js@6.0.0
+
 ## 4.0.4
 
 ### Patch Changes

package/adapters/wechat-mp.js

@@ -11,15 +11,15 @@ import { wechatMpRuntimeStateToken } from "../lib/wechat-mp-runtime-state.js";
 export { WeChatMpEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    // 客服消息图片经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传）；
-    // 公众号无卡片交互面，交互段降级纯文本。
+    // 客服消息媒体统一经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传，
+    // kind=file 的 MediaRef 视为既有 media_id 直传）；公众号无卡片交互面，交互段降级纯文本。
     segments: {
-        outboundMedia: ['url', 'upload'],
+        outboundMedia: ['upload'],
         interactive: 'text',
     },
     create(context) {
         const config = resolveWeChatMpConfig(context.config);
-        // 注册到插件运行时状态（wechat-mp endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（wechat-mp.endpoint list 的"运行中"数据源）
         context.use(wechatMpRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: 'webhook',

package/adapters/wechat-mp.ts

@@ -16,15 +16,15 @@ export type { WeChatMpEndpointOptions, WeChatMpFetch } from '../src/endpoint.js'
 
 export default defineAdapter<WeChatMpAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  // 客服消息图片经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传）；
-  // 公众号无卡片交互面，交互段降级纯文本。
+  // 客服消息媒体统一经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传，
+  // kind=file 的 MediaRef 视为既有 media_id 直传）；公众号无卡片交互面，交互段降级纯文本。
   segments: {
-    outboundMedia: ['url', 'upload'],
+    outboundMedia: ['upload'],
     interactive: 'text',
   },
   create(context) {
     const config = resolveWeChatMpConfig(context.config);
-    // 注册到插件运行时状态（wechat-mp endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（wechat-mp.endpoint list 的"运行中"数据源）
     context.use(wechatMpRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: 'webhook',

package/lib/endpoint.js

@@ -4,12 +4,22 @@
 import axios from 'axios';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 import { extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, } from './protocol.js';
-import { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
+import { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, } from './media-upload.js';
 import { getPassiveReplyCapture, recordPassiveReplyText, } from './passive-reply.js';
 import { registerWeChatMpWebhookRoutes } from './webhook.js';
 const logger = getLogger('wechat-mp');
 /** token 失效类错误码：40001/40014 invalid access_token、42001 access_token expired。 */
 const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
+/**
+ * canonical 媒体段类型 → 微信 /cgi-bin/media/upload 的 type。
+ * 客服消息无 file 投递面，file 段不可投递。
+ */
+const WECHAT_UPLOAD_TYPE = {
+    image: 'image',
+    audio: 'voice',
+    voice: 'voice',
+    video: 'video',
+};
 function defaultFetch(url, init) {
     return axios({
         url,
@@ -165,25 +175,57 @@ export class WeChatMpEndpoint {
         return result.msgid?.toString() || `cs_${Date.now()}`;
     }
     /**
-     * 客服消息 image 段只接受 media_id：canonical MediaRef（base64/本地路径/URL）
-     * 先经 /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+     * 客服消息媒体段只接受 media_id：canonical MediaRef 是唯一来源。
+     * - kind=file（平台不透明引用，即既有 media_id）→ 直接透传；
+     * - kind=base64 / path / url → 经 /cgi-bin/media/upload 物化；
+     * - 无 MediaRef / 类型不可投递（file 段）→ warn + 丢弃；
+     * - 上传失败降级为文本（alt 优先），不阻断发送。
      */
     async #materializeOutboundMedia(payload) {
         if (!Array.isArray(payload))
             return payload;
-        return Promise.all(payload.map(async (item) => {
+        const materialized = await Promise.all(payload.map(async (item) => {
             if (typeof item === 'string' || !item || typeof item !== 'object')
                 return item;
             const seg = item;
-            if (seg.type !== 'image')
+            if (typeof seg.type !== 'string')
                 return item;
             const data = seg.data ?? {};
-            const media = readOutboundImageMedia(data);
-            if (!media)
+            const uploadType = WECHAT_UPLOAD_TYPE[seg.type];
+            const isMediaSegment = uploadType != null || seg.type === 'file';
+            if (!isMediaSegment)
                 return item;
+            const media = readOutboundMedia(data);
+            if (!media) {
+                // 已物化（mediaId/media_id）的段透传；其余无 canonical 媒体引用，丢弃留痕
+                if (typeof data.mediaId === 'string' && data.mediaId)
+                    return item;
+                if (typeof data.media_id === 'string' && data.media_id)
+                    return item;
+                logger.warn(formatCompact({
+                    op: 'wechat_mp_outbound_media_dropped',
+                    endpoint: this.#options.config.name,
+                    type: seg.type,
+                    reason: 'missing_media_ref',
+                }));
+                return null;
+            }
+            if (media.kind === 'file') {
+                // 平台不透明引用：value 即 media_id，直接透传不上传
+                return { type: seg.type, data: { mediaId: media.value } };
+            }
+            if (!uploadType) {
+                logger.warn(formatCompact({
+                    op: 'wechat_mp_outbound_media_dropped',
+                    endpoint: this.#options.config.name,
+                    type: seg.type,
+                    reason: 'unsupported_segment_type',
+                }));
+                return null;
+            }
             try {
-                const mediaId = await this.#uploadMedia('image', media);
-                return { type: 'image', data: { mediaId } };
+                const mediaId = await this.#uploadMedia(uploadType, media);
+                return { type: seg.type, data: { mediaId } };
             }
             catch (error) {
                 logger.warn(formatCompact({
@@ -191,10 +233,11 @@ export class WeChatMpEndpoint {
                     endpoint: this.#options.config.name,
                     error: error instanceof Error ? error.message : String(error),
                 }));
-                const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
+                const alt = typeof data.alt === 'string' && data.alt ? data.alt : `[${seg.type}]`;
                 return { type: 'text', data: { text: alt } };
             }
         }));
+        return materialized.filter((item) => item != null);
     }
     /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
     async #uploadMedia(type, media) {

package/lib/index.d.ts

@@ -1,5 +1,5 @@
 export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, type ResolvedWeChatMpConfig, type TokenResponse, type WeChatAPIResponse, type WeChatMessage, type WeChatMpAdapterConfig, type WeChatWireSegment, } from './protocol.js';
 export { getPassiveReplyCapture, recordPassiveReplyText, runWithPassiveReplyCapture, type PassiveReplyCapture, } from './passive-reply.js';
 export { WeChatMpEndpoint, type WeChatMpEndpointOptions, type WeChatMpFetch, } from './endpoint.js';
-export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, type MediaBinary, type WeChatMediaUploadResult, } from './media-upload.js';
+export { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, type MediaBinary, type WeChatMediaUploadResult, } from './media-upload.js';
 export { registerWeChatMpWebhookRoutes, handleWeChatMpVerification, handleWeChatMpMessage, collectPassiveReply, type WeChatMpWebhookHandler, } from './webhook.js';

package/lib/index.js

@@ -1,5 +1,5 @@
 export { buildTextReply, computeSignatureHash, decryptEchostr, decryptMessage, encryptMessage, extractOutboundText, formatCustomerServiceBody, formatInboundContent, formatInboundId, isEncryptedEchostr, normalizeEchostrParam, parseXMLMessage, queryParam, readTextBody, resolveEventPassiveReply, resolveWeChatMpConfig, verifySignature, } from './protocol.js';
 export { getPassiveReplyCapture, recordPassiveReplyText, runWithPassiveReplyCapture, } from './passive-reply.js';
 export { WeChatMpEndpoint, } from './endpoint.js';
-export { buildMediaUploadForm, readOutboundImageMedia, resolveMediaBinary, } from './media-upload.js';
+export { buildMediaUploadForm, readOutboundMedia, resolveMediaBinary, } from './media-upload.js';
 export { registerWeChatMpWebhookRoutes, handleWeChatMpVerification, handleWeChatMpMessage, collectPassiveReply, } from './webhook.js';

package/lib/media-upload.d.ts

@@ -16,7 +16,7 @@ export declare function resolveMediaBinary(media: MediaRef, download?: (url: str
 /** 临时素材上传的 multipart body（字段名固定为 `media`）。 */
 export declare function buildMediaUploadForm(binary: MediaBinary): FormData;
 /**
- * 出站 image 段的媒体引用：已有 media_id 的视为已物化；
- * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ * 出站媒体段的媒体引用：已有 media_id 的视为已物化（返回 undefined 透传）；
+ * 否则只读 canonical `data.media`（MediaRef-only，无 legacy 字段回退）。
  */
-export declare function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined;
+export declare function readOutboundMedia(data: Record<string, unknown>): MediaRef | undefined;

package/lib/media-upload.js

@@ -6,7 +6,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
-import { isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+import { isMediaRef } from '@zhin.js/core';
 const MIME_EXT = {
     'image/jpeg': 'jpg',
     'image/png': 'png',
@@ -28,6 +28,10 @@ export async function resolveMediaBinary(media, download = defaultDownload) {
         const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
         return { data: await readFile(path), mimeType, fileName: basename(path) };
     }
+    if (media.kind === 'file') {
+        // 平台不透明引用（media_id）：由调用方直接透传，不走上传。
+        throw new Error('MediaRef kind=file is a platform opaque reference; binary resolution not applicable');
+    }
     return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
 }
 async function defaultDownload(url) {
@@ -46,15 +50,15 @@ export function buildMediaUploadForm(binary) {
     return form;
 }
 /**
- * 出站 image 段的媒体引用：已有 media_id 的视为已物化；
- * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ * 出站媒体段的媒体引用：已有 media_id 的视为已物化（返回 undefined 透传）；
+ * 否则只读 canonical `data.media`（MediaRef-only，无 legacy 字段回退）。
  */
-export function readOutboundImageMedia(data) {
+export function readOutboundMedia(data) {
     if (typeof data.mediaId === 'string' && data.mediaId)
         return undefined;
     if (typeof data.media_id === 'string' && data.media_id)
         return undefined;
     if (isMediaRef(data.media))
         return data.media;
-    return mediaRefFromLegacyData(data);
+    return undefined;
 }

package/lib/protocol.js

@@ -237,9 +237,11 @@ export function formatCustomerServiceBody(target, payload) {
     if (segments.length === 0) {
         messageData.text.content = payload == null
             ? ''
-            : typeof payload === 'object'
-                ? JSON.stringify(payload)
-                : String(payload);
+            : Array.isArray(payload)
+                ? ''
+                : typeof payload === 'object'
+                    ? JSON.stringify(payload)
+                    : String(payload);
         return messageData;
     }
     const textParts = [];
@@ -263,6 +265,7 @@ export function formatCustomerServiceBody(target, payload) {
                 }
                 break;
             case 'voice':
+            case 'audio':
                 if (!hasMedia && data.mediaId) {
                     messageData.msgtype = 'voice';
                     messageData.voice = { media_id: data.mediaId };

package/lib/wechat-mp-endpoint-commands.js

@@ -1,5 +1,5 @@
 /**
- * `wechat-mp endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `wechat-mp.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';

package/lib/wechat-mp-runtime-state.js

@@ -1,6 +1,6 @@
 /**
  * WeChat MP 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `wechat-mp endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `wechat-mp.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';
 export const wechatMpRuntimeStateToken = defineEndpointRuntimeStateToken('wechat-mp');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wechat-mp",
-  "version": "4.0.4",
+  "version": "5.0.0",
   "type": "module",
   "description": "Zhin.js WeChat Official Account adapter for Plugin Runtime (HTTP webhook)",
   "main": "./lib/index.js",
@@ -8,19 +8,19 @@
   "dependencies": {
     "axios": "^1.19.0",
     "xml2js": "^0.6.2",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/command": "1.0.5",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/host-http": "1.0.4",
     "@zhin.js/logger": "1.0.75",
     "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/core": "1.5.0",
     "@zhin.js/host-http": "1.0.4",
     "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/plugin.js

@@ -8,7 +8,7 @@ export default definePlugin({
         displayName: 'WeChat Official Account Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（wechat-mp endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（wechat-mp.endpoint list 的"运行中"数据源）
         context.resources.provide(wechatMpRuntimeStateToken, createEndpointRuntimeState());
     },
 });

package/src/endpoint.ts

@@ -19,7 +19,7 @@ import {
 } from './protocol.js';
 import {
   buildMediaUploadForm,
-  readOutboundImageMedia,
+  readOutboundMedia,
   resolveMediaBinary,
   type WeChatMediaUploadResult,
 } from './media-upload.js';
@@ -34,6 +34,17 @@ const logger = getLogger('wechat-mp');
 /** token 失效类错误码：40001/40014 invalid access_token、42001 access_token expired。 */
 const TOKEN_INVALID_ERRCODES = new Set([40001, 40014, 42001]);
 
+/**
+ * canonical 媒体段类型 → 微信 /cgi-bin/media/upload 的 type。
+ * 客服消息无 file 投递面，file 段不可投递。
+ */
+const WECHAT_UPLOAD_TYPE: Readonly<Record<string, 'image' | 'voice' | 'video'>> = {
+  image: 'image',
+  audio: 'voice',
+  voice: 'voice',
+  video: 'video',
+};
+
 export type WeChatMpFetch = (
   url: string,
   init?: { readonly method?: string; readonly body?: unknown; readonly headers?: Record<string, string> },
@@ -217,35 +228,69 @@ export class WeChatMpEndpoint implements EndpointInstance {
   }
 
   /**
-   * 客服消息 image 段只接受 media_id：canonical MediaRef（base64/本地路径/URL）
-   * 先经 /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+   * 客服消息媒体段只接受 media_id：canonical MediaRef 是唯一来源。
+   * - kind=file（平台不透明引用，即既有 media_id）→ 直接透传；
+   * - kind=base64 / path / url → 经 /cgi-bin/media/upload 物化；
+   * - 无 MediaRef / 类型不可投递（file 段）→ warn + 丢弃；
+   * - 上传失败降级为文本（alt 优先），不阻断发送。
    */
   async #materializeOutboundMedia(payload: unknown): Promise<unknown> {
     if (!Array.isArray(payload)) return payload;
-    return Promise.all(payload.map(async (item) => {
+    const materialized = await Promise.all(payload.map(async (item) => {
       if (typeof item === 'string' || !item || typeof item !== 'object') return item;
       const seg = item as { type?: unknown; data?: Record<string, unknown> };
-      if (seg.type !== 'image') return item;
+      if (typeof seg.type !== 'string') return item;
       const data = seg.data ?? {};
-      const media = readOutboundImageMedia(data);
-      if (!media) return item;
+      const uploadType = WECHAT_UPLOAD_TYPE[seg.type];
+      const isMediaSegment = uploadType != null || seg.type === 'file';
+      if (!isMediaSegment) return item;
+      const media = readOutboundMedia(data);
+      if (!media) {
+        // 已物化（mediaId/media_id）的段透传；其余无 canonical 媒体引用，丢弃留痕
+        if (typeof data.mediaId === 'string' && data.mediaId) return item;
+        if (typeof data.media_id === 'string' && data.media_id) return item;
+        logger.warn(formatCompact({
+          op: 'wechat_mp_outbound_media_dropped',
+          endpoint: this.#options.config.name,
+          type: seg.type,
+          reason: 'missing_media_ref',
+        }));
+        return null;
+      }
+      if (media.kind === 'file') {
+        // 平台不透明引用：value 即 media_id，直接透传不上传
+        return { type: seg.type, data: { mediaId: media.value } };
+      }
+      if (!uploadType) {
+        logger.warn(formatCompact({
+          op: 'wechat_mp_outbound_media_dropped',
+          endpoint: this.#options.config.name,
+          type: seg.type,
+          reason: 'unsupported_segment_type',
+        }));
+        return null;
+      }
       try {
-        const mediaId = await this.#uploadMedia('image', media);
-        return { type: 'image', data: { mediaId } };
+        const mediaId = await this.#uploadMedia(uploadType, media);
+        return { type: seg.type, data: { mediaId } };
       } catch (error) {
         logger.warn(formatCompact({
           op: 'wechat_mp_media_upload_failed',
           endpoint: this.#options.config.name,
           error: error instanceof Error ? error.message : String(error),
         }));
-        const alt = typeof data.alt === 'string' && data.alt ? data.alt : '[image]';
+        const alt = typeof data.alt === 'string' && data.alt ? data.alt : `[${seg.type}]`;
         return { type: 'text', data: { text: alt } };
       }
     }));
+    return materialized.filter((item) => item != null);
   }
 
   /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
-  async #uploadMedia(type: 'image', media: Parameters<typeof resolveMediaBinary>[0]): Promise<string> {
+  async #uploadMedia(
+    type: 'image' | 'voice' | 'video',
+    media: Parameters<typeof resolveMediaBinary>[0],
+  ): Promise<string> {
     const binary = await resolveMediaBinary(media);
     const form = buildMediaUploadForm(binary);
     const url = `https://api.weixin.qq.com/cgi-bin/media/upload?access_token=${this.#accessToken}&type=${type}`;

package/src/index.ts

@@ -39,7 +39,7 @@ export {
 
 export {
   buildMediaUploadForm,
-  readOutboundImageMedia,
+  readOutboundMedia,
   resolveMediaBinary,
   type MediaBinary,
   type WeChatMediaUploadResult,

package/src/media-upload.ts

@@ -6,7 +6,7 @@
  */
 import { readFile } from 'node:fs/promises';
 import { basename } from 'node:path';
-import { isMediaRef, mediaRefFromLegacyData, type MediaRef } from '@zhin.js/core';
+import { isMediaRef, type MediaRef } from '@zhin.js/core';
 
 export interface MediaBinary {
   readonly data: Buffer;
@@ -47,6 +47,10 @@ export async function resolveMediaBinary(
     const path = media.value.startsWith('file://') ? media.value.slice('file://'.length) : media.value;
     return { data: await readFile(path), mimeType, fileName: basename(path) };
   }
+  if (media.kind === 'file') {
+    // 平台不透明引用（media_id）：由调用方直接透传，不走上传。
+    throw new Error('MediaRef kind=file is a platform opaque reference; binary resolution not applicable');
+  }
   return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
 }
 
@@ -67,12 +71,12 @@ export function buildMediaUploadForm(binary: MediaBinary): FormData {
 }
 
 /**
- * 出站 image 段的媒体引用：已有 media_id 的视为已物化；
- * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ * 出站媒体段的媒体引用：已有 media_id 的视为已物化（返回 undefined 透传）；
+ * 否则只读 canonical `data.media`（MediaRef-only，无 legacy 字段回退）。
  */
-export function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined {
+export function readOutboundMedia(data: Record<string, unknown>): MediaRef | undefined {
   if (typeof data.mediaId === 'string' && data.mediaId) return undefined;
   if (typeof data.media_id === 'string' && data.media_id) return undefined;
   if (isMediaRef(data.media)) return data.media;
-  return mediaRefFromLegacyData(data);
+  return undefined;
 }

package/src/protocol.ts

@@ -384,9 +384,11 @@ export function formatCustomerServiceBody(
   if (segments.length === 0) {
     (messageData.text as { content: string }).content = payload == null
       ? ''
-      : typeof payload === 'object'
-        ? JSON.stringify(payload)
-        : String(payload);
+      : Array.isArray(payload)
+        ? ''
+        : typeof payload === 'object'
+          ? JSON.stringify(payload)
+          : String(payload);
     return messageData;
   }
 
@@ -412,6 +414,7 @@ export function formatCustomerServiceBody(
         }
         break;
       case 'voice':
+      case 'audio':
         if (!hasMedia && data.mediaId) {
           messageData.msgtype = 'voice';
           messageData.voice = { media_id: data.mediaId };

package/src/wechat-mp-endpoint-commands.ts

@@ -1,5 +1,5 @@
 /**
- * `wechat-mp endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
+ * `wechat-mp.endpoint` 命令族：由 @zhin.js/adapter 的 createEndpointCommands 套件生成。
  * commands/endpoint/ 下的 list / add / remove 直接默认导出这三项。
  */
 import { createEndpointCommands } from '@zhin.js/adapter';

package/src/wechat-mp-runtime-state.ts

@@ -1,6 +1,6 @@
 /**
  * WeChat MP 插件实例的运行时状态：adapter create() 注册的 endpoint 列表。
- * 由 plugin.ts setup() provide，adapter create 与 `wechat-mp endpoint` 命令共享（同一 owner generation）。
+ * 由 plugin.ts setup() provide，adapter create 与 `wechat-mp.endpoint` 命令共享（同一 owner generation）。
  */
 import { defineEndpointRuntimeStateToken } from '@zhin.js/adapter';