@zhin.js/adapter-wecom 3.0.6 → 4.0.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @zhin.js/adapter-wecom
 
+## 4.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/agent@1.1.0
+  - zhin.js@6.0.0
+
 ## 3.0.6
 
 ### Patch Changes

package/adapters/wecom.js

@@ -12,15 +12,15 @@ import { wecomRuntimeStateToken } from "../lib/wecom-runtime-state.js";
 export { WecomEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    // image 段经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传）；
-    // 无卡片交互面，交互段降级纯文本。
+    // image 段全部经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传、
+    // base64/path 直接上传、file 引用直用 media_id）；无卡片交互面，交互段降级纯文本。
     segments: {
-        outboundMedia: ['url', 'upload'],
+        outboundMedia: ['upload'],
         interactive: 'text',
     },
     create(context) {
         const config = resolveWecomConfig(context.config);
-        // 注册到插件运行时状态（wecom endpoint list 的"运行中"数据源）
+        // 注册到插件运行时状态（wecom.endpoint list 的"运行中"数据源）
         context.use(wecomRuntimeStateToken).endpoints.set(config.name, {
             name: config.name,
             mode: 'webhook',

package/adapters/wecom.ts

@@ -17,15 +17,15 @@ export type { WecomEndpointOptions, WecomFetch } from '../src/endpoint.js';
 
 export default defineAdapter<WecomAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  // image 段经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传）；
-  // 无卡片交互面，交互段降级纯文本。
+  // image 段全部经 /cgi-bin/media/upload 物化为 media_id（url 下载后上传、
+  // base64/path 直接上传、file 引用直用 media_id）；无卡片交互面，交互段降级纯文本。
   segments: {
-    outboundMedia: ['url', 'upload'],
+    outboundMedia: ['upload'],
     interactive: 'text',
   },
   create(context) {
     const config = resolveWecomConfig(context.config);
-    // 注册到插件运行时状态（wecom endpoint list 的"运行中"数据源）
+    // 注册到插件运行时状态（wecom.endpoint list 的"运行中"数据源）
     context.use(wecomRuntimeStateToken).endpoints.set(config.name, {
       name: config.name,
       mode: 'webhook',

package/lib/endpoint.js

@@ -89,13 +89,15 @@ export class WecomEndpoint {
         });
     }
     /**
-     * message/send 的 image 段只接受 media_id：canonical MediaRef（base64/本地路径/URL）
-     * 先经 /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+     * message/send 的 image 段只接受 media_id：canonical MediaRef 按 kind 投递——
+     * file（平台不透明引用）直用为 media_id；base64/本地路径/URL 先经
+     * /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+     * 无 canonical MediaRef 的媒体段 warn + 丢弃。
      */
     async #materializeOutboundMedia(payload) {
         if (!Array.isArray(payload))
             return payload;
-        return Promise.all(payload.map(async (item) => {
+        const items = await Promise.all(payload.map(async (item) => {
             if (typeof item === 'string' || !item || typeof item !== 'object')
                 return item;
             const seg = item;
@@ -103,8 +105,18 @@ export class WecomEndpoint {
                 return item;
             const data = seg.data ?? {};
             const media = readOutboundImageMedia(data);
-            if (!media)
-                return item;
+            if (!media) {
+                logger.warn(formatCompact({
+                    op: 'wecom_outbound_media_dropped',
+                    endpoint: this.#options.config.name,
+                    type: 'image',
+                    reason: 'missing_media_ref',
+                }));
+                return null;
+            }
+            if (media.kind === 'file') {
+                return { type: 'image', data: { media_id: media.value } };
+            }
             try {
                 const mediaId = await this.#uploadMedia('image', media);
                 return { type: 'image', data: { media_id: mediaId } };
@@ -119,6 +131,7 @@ export class WecomEndpoint {
                 return { type: 'text', data: { text: alt } };
             }
         }));
+        return items.filter((item) => item !== null);
     }
     /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */
     async #uploadMedia(type, media) {

package/lib/media-upload.d.ts

@@ -16,7 +16,8 @@ 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}` 字段。
+ * 出站 image 段的媒体引用：只读 canonical `data.media`（MediaRef）。
+ * 中央 normalizeOutboundPayload 已保证到达 endpoint 的载荷为 canonical；
+ * 无 MediaRef 时返回 undefined，由调用方 warn + 丢弃。
  */
 export declare function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined;

package/lib/media-upload.js

@@ -5,7 +5,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',
@@ -27,7 +27,11 @@ 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) };
     }
-    return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+    if (media.kind === 'url') {
+        return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+    }
+    // kind=file 为平台不透明引用（media_id），无二进制可解，调用方应直用 value
+    throw new Error(`cannot resolve binary from media kind: ${media.kind}`);
 }
 async function defaultDownload(url) {
     const response = await fetch(url, { signal: AbortSignal.timeout(30_000) });
@@ -45,15 +49,10 @@ export function buildMediaUploadForm(binary) {
     return form;
 }
 /**
- * 出站 image 段的媒体引用：已有 media_id 的视为已物化；
- * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ * 出站 image 段的媒体引用：只读 canonical `data.media`（MediaRef）。
+ * 中央 normalizeOutboundPayload 已保证到达 endpoint 的载荷为 canonical；
+ * 无 MediaRef 时返回 undefined，由调用方 warn + 丢弃。
  */
 export function readOutboundImageMedia(data) {
-    if (typeof data.media_id === 'string' && data.media_id)
-        return undefined;
-    if (typeof data.mediaId === 'string' && data.mediaId)
-        return undefined;
-    if (isMediaRef(data.media))
-        return data.media;
-    return mediaRefFromLegacyData(data);
+    return isMediaRef(data.media) ? data.media : undefined;
 }

package/lib/protocol.js

@@ -192,8 +192,8 @@ export function formatOutboundBody(payload) {
                 if (!hasMedia) {
                     hasMedia = true;
                     mediaType = 'image';
-                    // media_id 由 endpoint 上传物化写入；file/url 为旧调用方直传 media_id 的兼容入口。
-                    mediaData = { media_id: data.media_id ?? data.mediaId ?? data.file ?? data.url };
+                    // media_id 由 endpoint 的 #materializeOutboundMedia 物化写入（内部 wire）。
+                    mediaData = { media_id: data.media_id };
                 }
                 break;
             case 'markdown':

package/lib/wecom-endpoint-commands.js

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

package/lib/wecom-runtime-state.js

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-wecom",
-  "version": "3.0.6",
+  "version": "4.0.0",
   "description": "Zhin.js WeCom (企业微信) adapter for Plugin Runtime (HTTP webhook)",
   "type": "module",
   "main": "./lib/index.js",
@@ -34,21 +34,21 @@
     "directory": "plugins/adapters/wecom"
   },
   "dependencies": {
-    "@zhin.js/command": "1.0.4",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/command": "1.0.5",
+    "@zhin.js/adapter": "1.1.3",
+    "@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": {
     "zod": "^4.0.0",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/agent": "1.0.10",
-    "@zhin.js/core": "1.4.3",
-    "@zhin.js/plugin-runtime": "1.1.1",
+    "@zhin.js/adapter": "1.1.3",
+    "@zhin.js/agent": "1.1.0",
     "@zhin.js/host-http": "1.0.4",
-    "zhin.js": "5.0.3"
+    "@zhin.js/core": "1.5.0",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "6.0.0"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -66,8 +66,8 @@
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "zod": "^4.4.3",
-    "@zhin.js/agent": "1.0.10",
-    "zhin.js": "5.0.3"
+    "zhin.js": "6.0.0",
+    "@zhin.js/agent": "1.1.0"
   },
   "files": [
     "adapters",

package/plugin.js

@@ -9,7 +9,7 @@ export default definePlugin({
         displayName: 'WeCom (企业微信) Adapter',
     },
     setup(context) {
-        // 运行中 endpoint 注册表（wecom endpoint list 的"运行中"数据源）
+        // 运行中 endpoint 注册表（wecom.endpoint list 的"运行中"数据源）
         context.resources.provide(wecomRuntimeStateToken, createEndpointRuntimeState());
         return registerWecomPlatformPermitChecker();
     },

package/src/endpoint.ts

@@ -143,18 +143,31 @@ export class WecomEndpoint implements EndpointInstance {
   }
 
   /**
-   * message/send 的 image 段只接受 media_id：canonical MediaRef（base64/本地路径/URL）
-   * 先经 /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+   * message/send 的 image 段只接受 media_id：canonical MediaRef 按 kind 投递——
+   * file（平台不透明引用）直用为 media_id；base64/本地路径/URL 先经
+   * /cgi-bin/media/upload 物化；上传失败降级为文本（alt 优先），不阻断发送。
+   * 无 canonical MediaRef 的媒体段 warn + 丢弃。
    */
   async #materializeOutboundMedia(payload: unknown): Promise<unknown> {
     if (!Array.isArray(payload)) return payload;
-    return Promise.all(payload.map(async (item) => {
+    const items = 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;
       const data = seg.data ?? {};
       const media = readOutboundImageMedia(data);
-      if (!media) return item;
+      if (!media) {
+        logger.warn(formatCompact({
+          op: 'wecom_outbound_media_dropped',
+          endpoint: this.#options.config.name,
+          type: 'image',
+          reason: 'missing_media_ref',
+        }));
+        return null;
+      }
+      if (media.kind === 'file') {
+        return { type: 'image', data: { media_id: media.value } };
+      }
       try {
         const mediaId = await this.#uploadMedia('image', media);
         return { type: 'image', data: { media_id: mediaId } };
@@ -168,6 +181,7 @@ export class WecomEndpoint implements EndpointInstance {
         return { type: 'text', data: { text: alt } };
       }
     }));
+    return items.filter((item) => item !== null);
   }
 
   /** POST /cgi-bin/media/upload（临时素材，3 天有效），返回 media_id。 */

package/src/media-upload.ts

@@ -5,7 +5,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;
@@ -46,7 +46,11 @@ 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) };
   }
-  return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+  if (media.kind === 'url') {
+    return { data: await download(media.value), mimeType, fileName: `image.${ext}` };
+  }
+  // kind=file 为平台不透明引用（media_id），无二进制可解，调用方应直用 value
+  throw new Error(`cannot resolve binary from media kind: ${media.kind}`);
 }
 
 async function defaultDownload(url: string): Promise<Buffer> {
@@ -66,12 +70,10 @@ export function buildMediaUploadForm(binary: MediaBinary): FormData {
 }
 
 /**
- * 出站 image 段的媒体引用：已有 media_id 的视为已物化；
- * 否则读 canonical `data.media`，兼容旧 wire `{url,file,base64}` 字段。
+ * 出站 image 段的媒体引用：只读 canonical `data.media`（MediaRef）。
+ * 中央 normalizeOutboundPayload 已保证到达 endpoint 的载荷为 canonical；
+ * 无 MediaRef 时返回 undefined，由调用方 warn + 丢弃。
  */
 export function readOutboundImageMedia(data: Record<string, unknown>): MediaRef | undefined {
-  if (typeof data.media_id === 'string' && data.media_id) return undefined;
-  if (typeof data.mediaId === 'string' && data.mediaId) return undefined;
-  if (isMediaRef(data.media)) return data.media;
-  return mediaRefFromLegacyData(data);
+  return isMediaRef(data.media) ? data.media : undefined;
 }

package/src/protocol.ts

@@ -292,8 +292,8 @@ export function formatOutboundBody(payload: unknown): WecomSendBody {
         if (!hasMedia) {
           hasMedia = true;
           mediaType = 'image';
-          // media_id 由 endpoint 上传物化写入；file/url 为旧调用方直传 media_id 的兼容入口。
-          mediaData = { media_id: data.media_id ?? data.mediaId ?? data.file ?? data.url };
+          // media_id 由 endpoint 的 #materializeOutboundMedia 物化写入（内部 wire）。
+          mediaData = { media_id: data.media_id };
         }
         break;
       case 'markdown':

package/src/wecom-endpoint-commands.ts

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

package/src/wecom-runtime-state.ts

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