@zhin.js/adapter-email 4.0.3 → 5.0.1

package/CHANGELOG.md

@@ -1,5 +1,38 @@
 # @zhin.js/adapter-email
 
+## 5.0.1
+
+### Patch Changes
+
+- Updated dependencies [c8f4d45]
+  - @zhin.js/plugin-runtime@1.1.2
+  - @zhin.js/adapter@1.1.4
+  - @zhin.js/core@1.5.1
+  - zhin.js@6.0.1
+
+## 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/adapter@1.1.3
+  - @zhin.js/core@1.5.0
+  - zhin.js@6.0.0
+
 ## 4.0.3
 
 ### Patch Changes

package/adapters/email.js

@@ -9,10 +9,12 @@ import { resolveEmailConfig, } from "../lib/protocol.js";
 export { EmailEndpoint } from "../lib/endpoint.js";
 export default defineAdapter({
     capabilities: ['inbound', 'outbound'],
-    // image/file 段映射为邮件附件：canonical MediaRef kind=url/path 均可作
-    // nodemailer attachment.path（URL 由 nodemailer 拉流）；邮件无交互面，交互段降级纯文本。
+    // image/audio/video/file 段映射为邮件附件：canonical MediaRef kind=url/path
+    // 作 nodemailer attachment.path（URL 由 nodemailer 拉流、path 读盘），
+    // kind=base64 直发（content + encoding）；kind=file 无邮件对应概念，丢弃留痕。
+    // 邮件无交互面，交互段降级纯文本。
     segments: {
-        outboundMedia: ['url', 'path'],
+        outboundMedia: ['url', 'path', 'base64'],
         interactive: 'text',
     },
     create(context) {

package/adapters/email.ts

@@ -19,10 +19,12 @@ export type {
 
 export default defineAdapter<EmailAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
-  // image/file 段映射为邮件附件：canonical MediaRef kind=url/path 均可作
-  // nodemailer attachment.path（URL 由 nodemailer 拉流）；邮件无交互面，交互段降级纯文本。
+  // image/audio/video/file 段映射为邮件附件：canonical MediaRef kind=url/path
+  // 作 nodemailer attachment.path（URL 由 nodemailer 拉流、path 读盘），
+  // kind=base64 直发（content + encoding）；kind=file 无邮件对应概念，丢弃留痕。
+  // 邮件无交互面，交互段降级纯文本。
   segments: {
-    outboundMedia: ['url', 'path'],
+    outboundMedia: ['url', 'path', 'base64'],
     interactive: 'text',
   },
   create(context) {

package/lib/protocol.d.ts

@@ -102,6 +102,18 @@ export interface SavedEmailAttachment {
  */
 export declare function formatInboundSegments(email: EmailMessage, savedAttachments?: readonly SavedEmailAttachment[]): Segment[];
 export declare function senderDisplayName(from: string): string;
+/**
+ * nodemailer 附件的最小形状：url/path 走 `path`（URL 由 nodemailer 拉流、
+ * 本地路径读盘），base64 走 `content` + `encoding: 'base64'` 直发。
+ */
+export type EmailOutboundAttachment = {
+    filename: string;
+    path: string;
+} | {
+    filename: string;
+    content: string;
+    encoding: 'base64';
+};
 /**
  * Wire-encode an already-rendered outbound payload into nodemailer options.
  * Segment canonicalization is intentionally not done here.
@@ -116,8 +128,5 @@ export declare function formatOutboundMail(payload: unknown, options: {
     subject: string;
     text?: string;
     html?: string;
-    attachments?: Array<{
-        filename: string;
-        path: string;
-    }>;
+    attachments?: EmailOutboundAttachment[];
 };

package/lib/protocol.js

@@ -2,7 +2,9 @@
  * Email SMTP/IMAP helpers (no legacy Adapter/Endpoint / segment-mapper).
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-import { htmlToPlainTextWithBlockBreaks, isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+import { htmlToPlainTextWithBlockBreaks, isMediaRef } from '@zhin.js/core';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+const logger = getLogger('email');
 export function resolveEmailConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'email');
     const smtp = config.smtp ?? entry?.smtp;
@@ -122,6 +124,50 @@ export function senderDisplayName(from) {
     const name = from.split('<')[0]?.trim();
     return name || from;
 }
+/**
+ * image/audio/video/file 段 → nodemailer 附件（canonical MediaRef 唯一来源）：
+ * - kind=url / path → attachment.path；
+ * - kind=base64 → attachment.content（data: URL 前缀剥离）；
+ * - kind=file（平台不透明引用）邮件无对应概念，丢弃留痕；
+ * - 缺 media 同样 warn + 丢弃。
+ */
+function mediaSegmentToAttachment(type, data) {
+    const media = data.media;
+    if (!isMediaRef(media)) {
+        logger.warn(formatCompact({
+            op: 'email_outbound_media_dropped',
+            type,
+            reason: 'missing_media_ref',
+        }));
+        return null;
+    }
+    if (media.kind === 'file') {
+        logger.warn(formatCompact({
+            op: 'email_outbound_media_dropped',
+            type,
+            reason: 'unsupported_kind',
+            kind: media.kind,
+        }));
+        return null;
+    }
+    const filename = attachmentFileName(type, data, media);
+    if (media.kind === 'base64') {
+        const value = media.value.startsWith('data:')
+            ? media.value.slice(media.value.indexOf(',') + 1)
+            : media.value;
+        return { filename, content: value, encoding: 'base64' };
+    }
+    return { filename, path: media.value };
+}
+function attachmentFileName(type, data, media) {
+    if (media.file_name)
+        return media.file_name;
+    if (typeof data.name === 'string' && data.name)
+        return data.name;
+    if (typeof data.alt === 'string' && data.alt)
+        return data.alt;
+    return type === 'image' ? 'image.png' : 'file';
+}
 /**
  * Wire-encode an already-rendered outbound payload into nodemailer options.
  * Segment canonicalization is intentionally not done here.
@@ -166,16 +212,12 @@ export function formatOutboundMail(payload, options) {
                 break;
             }
             case 'image':
+            case 'audio':
+            case 'video':
             case 'file': {
-                // canonical MediaRef 优先（kind url/path 均可作 nodemailer attachment.path），
-                // 旧 wire 字段 `{url,file,base64}` 经 mediaRefFromLegacyData 兼容。
-                const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
-                if (media && (media.kind === 'url' || media.kind === 'path')) {
-                    attachments.push({
-                        filename: String(data.filename || data.name || (item.type === 'image' ? 'image.png' : 'file')),
-                        path: media.value,
-                    });
-                }
+                const attachment = mediaSegmentToAttachment(item.type, data);
+                if (attachment)
+                    attachments.push(attachment);
                 break;
             }
             default:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-email",
-  "version": "4.0.3",
+  "version": "5.0.1",
   "type": "module",
   "description": "Zhin.js Email adapter for Plugin Runtime (SMTP/IMAP)",
   "main": "./lib/index.js",
@@ -9,16 +9,16 @@
     "imap": "^0.8.19",
     "mailparser": "^3.9.14",
     "nodemailer": "^9.0.3",
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/core": "1.4.3",
+    "@zhin.js/adapter": "1.1.4",
+    "@zhin.js/core": "1.5.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.1"
+    "@zhin.js/plugin-runtime": "1.1.2"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.2",
-    "@zhin.js/core": "1.4.3",
-    "@zhin.js/plugin-runtime": "1.1.1",
-    "zhin.js": "5.0.3"
+    "@zhin.js/adapter": "1.1.4",
+    "@zhin.js/core": "1.5.1",
+    "@zhin.js/plugin-runtime": "1.1.2",
+    "zhin.js": "6.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {
@@ -26,10 +26,10 @@
     }
   },
   "devDependencies": {
-    "@types/imap": "^0.8.40",
+    "@types/imap": "^0.8.43",
     "@types/mailparser": "^3.4.6",
-    "@types/node": "^26.1.0",
-    "@types/nodemailer": "^8.0.0",
+    "@types/node": "^26.1.2",
+    "@types/nodemailer": "^8.0.1",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10"
   },

package/src/protocol.ts

@@ -4,8 +4,11 @@
  */
 
 import type { Attachment } from 'mailparser';
-import { htmlToPlainTextWithBlockBreaks, isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+import { htmlToPlainTextWithBlockBreaks, isMediaRef, type MediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
+import { formatCompact, getLogger } from '@zhin.js/logger';
+
+const logger = getLogger('email');
 
 export interface SmtpConfig {
   readonly host: string;
@@ -229,6 +232,64 @@ export function senderDisplayName(from: string): string {
   return name || from;
 }
 
+/**
+ * nodemailer 附件的最小形状：url/path 走 `path`（URL 由 nodemailer 拉流、
+ * 本地路径读盘），base64 走 `content` + `encoding: 'base64'` 直发。
+ */
+export type EmailOutboundAttachment =
+  | { filename: string; path: string }
+  | { filename: string; content: string; encoding: 'base64' };
+
+/**
+ * image/audio/video/file 段 → nodemailer 附件（canonical MediaRef 唯一来源）：
+ * - kind=url / path → attachment.path；
+ * - kind=base64 → attachment.content（data: URL 前缀剥离）；
+ * - kind=file（平台不透明引用）邮件无对应概念，丢弃留痕；
+ * - 缺 media 同样 warn + 丢弃。
+ */
+function mediaSegmentToAttachment(
+  type: string,
+  data: Record<string, unknown>,
+): EmailOutboundAttachment | null {
+  const media = data.media;
+  if (!isMediaRef(media)) {
+    logger.warn(formatCompact({
+      op: 'email_outbound_media_dropped',
+      type,
+      reason: 'missing_media_ref',
+    }));
+    return null;
+  }
+  if (media.kind === 'file') {
+    logger.warn(formatCompact({
+      op: 'email_outbound_media_dropped',
+      type,
+      reason: 'unsupported_kind',
+      kind: media.kind,
+    }));
+    return null;
+  }
+  const filename = attachmentFileName(type, data, media);
+  if (media.kind === 'base64') {
+    const value = media.value.startsWith('data:')
+      ? media.value.slice(media.value.indexOf(',') + 1)
+      : media.value;
+    return { filename, content: value, encoding: 'base64' };
+  }
+  return { filename, path: media.value };
+}
+
+function attachmentFileName(
+  type: string,
+  data: Record<string, unknown>,
+  media: MediaRef,
+): string {
+  if (media.file_name) return media.file_name;
+  if (typeof data.name === 'string' && data.name) return data.name;
+  if (typeof data.alt === 'string' && data.alt) return data.alt;
+  return type === 'image' ? 'image.png' : 'file';
+}
+
 /**
  * Wire-encode an already-rendered outbound payload into nodemailer options.
  * Segment canonicalization is intentionally not done here.
@@ -242,7 +303,7 @@ export function formatOutboundMail(
   subject: string;
   text?: string;
   html?: string;
-  attachments?: Array<{ filename: string; path: string }>;
+  attachments?: EmailOutboundAttachment[];
 } {
   const mail = {
     from: options.from,
@@ -271,7 +332,7 @@ export function formatOutboundMail(
 
   const textParts: string[] = [];
   const htmlParts: string[] = [];
-  const attachments: Array<{ filename: string; path: string }> = [];
+  const attachments: EmailOutboundAttachment[] = [];
 
   for (const item of segments) {
     if (typeof item === 'string') {
@@ -288,18 +349,11 @@ export function formatOutboundMail(
         break;
       }
       case 'image':
+      case 'audio':
+      case 'video':
       case 'file': {
-        // canonical MediaRef 优先（kind url/path 均可作 nodemailer attachment.path），
-        // 旧 wire 字段 `{url,file,base64}` 经 mediaRefFromLegacyData 兼容。
-        const media = isMediaRef(data.media) ? data.media : mediaRefFromLegacyData(data);
-        if (media && (media.kind === 'url' || media.kind === 'path')) {
-          attachments.push({
-            filename: String(
-              data.filename || data.name || (item.type === 'image' ? 'image.png' : 'file'),
-            ),
-            path: media.value,
-          });
-        }
+        const attachment = mediaSegmentToAttachment(item.type, data);
+        if (attachment) attachments.push(attachment);
         break;
       }
       default: