@zhin.js/adapter-email 5.0.1 → 5.0.4

package/CHANGELOG.md

@@ -1,5 +1,52 @@
 # @zhin.js/adapter-email
 
+## 5.0.4
+
+### Patch Changes
+
+- Updated dependencies [c106ecc]
+- Updated dependencies [b0f37ae]
+- Updated dependencies [ba08a2f]
+- Updated dependencies [daffd4c]
+- Updated dependencies [36c7400]
+- Updated dependencies [162fa34]
+- Updated dependencies [e40b048]
+- Updated dependencies [f1708c3]
+- Updated dependencies [e53444f]
+- Updated dependencies [92b0dd7]
+- Updated dependencies [a7df753]
+  - @zhin.js/im-contract@1.0.3
+  - @zhin.js/adapter@1.1.7
+  - @zhin.js/plugin-runtime@1.1.5
+  - @zhin.js/core@1.5.4
+  - zhin.js@6.0.4
+
+## 5.0.3
+
+### Patch Changes
+
+- f8c7a54: fix: im
+- Updated dependencies [f8c7a54]
+  - @zhin.js/logger@1.0.76
+  - @zhin.js/adapter@1.1.6
+  - @zhin.js/core@1.5.3
+  - @zhin.js/im-contract@1.0.2
+  - @zhin.js/plugin-runtime@1.1.4
+  - zhin.js@6.0.3
+
+## 5.0.2
+
+### Patch Changes
+
+- Updated dependencies [afc0e66]
+- Updated dependencies [2e41ad5]
+- Updated dependencies [9f57124]
+  - @zhin.js/core@1.5.2
+  - @zhin.js/adapter@1.1.5
+  - @zhin.js/im-contract@1.0.1
+  - @zhin.js/plugin-runtime@1.1.3
+  - zhin.js@6.0.2
+
 ## 5.0.1
 
 ### Patch Changes

package/README.md

@@ -23,8 +23,8 @@ pnpm add @zhin.js/adapter-email
 - `@zhin.js/plugin-runtime` — `plugin.ts`（`definePlugin`）
 - 配置经插件 `schema.json` 落到 `plugins.<instanceKey>`（`smtp` / `imap`）
 
-入站：`gateway.receive({ adapter, target: fromEmail, content: text, sender, metadata })`  
-出站：`send({ target, payload })` → nodemailer（payload 已由 gateway/core 渲染；无 segment-mapper）
+入站：`gateway.receive({ conversation, message, content: text, sender, metadata })`（`conversation` 为 kind=private、id=发件人地址的 ConversationRef）  
+出站：`send({ conversation, payload })` → nodemailer（收件人取 `conversation.id`；payload 已由 gateway/core 渲染；无 segment-mapper）
 
 ## 前置条件
 

package/lib/endpoint.d.ts

@@ -1,4 +1,4 @@
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import { type EmailMessage, type ResolvedEmailConfig } from './protocol.js';
@@ -21,10 +21,7 @@ export declare class EmailEndpoint implements EndpointInstance {
     open(): void;
     close(): void;
     stop(): Promise<void>;
-    send({ target, payload }: {
-        readonly target: string;
-        readonly payload: unknown;
-    }): Promise<string>;
+    send({ conversation, payload }: EndpointSendRequest): Promise<string>;
     /** Test / internal: admit a parsed mail when the endpoint is open. */
     admit(email: EmailMessage): void;
 }

package/lib/endpoint.js

@@ -4,15 +4,15 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import * as path from 'node:path';
 import { simpleParser } from 'mailparser';
-import { formatCompact, getLogger } from '@zhin.js/logger';
-import { formatInboundContent, formatInboundSegments, formatOutboundMail, parseEmailMessage, senderDisplayName, } from './protocol.js';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import { emailInboundConversation, formatInboundContent, formatInboundSegments, formatOutboundMail, parseEmailMessage, senderDisplayName, } from './protocol.js';
 import { defaultCreateImap, defaultCreateSmtp, } from './transport.js';
-const logger = getLogger('email');
 /**
  * Email（SMTP/IMAP）无好友/群/频道等社交图谱概念，
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
 export class EmailEndpoint {
+    #logger;
     #options;
     #smtp = null;
     #imap = null;
@@ -23,17 +23,18 @@ export class EmailEndpoint {
     #open = false;
     #started = false;
     constructor(options) {
+        this.#logger = getAdapterLogger('email', options.config.id);
         this.#options = options;
     }
     async start() {
         if (this.#started)
             return;
         this.#started = true;
-        const { smtp, imap, name } = this.#options.config;
+        const { smtp, imap, id } = this.#options.config;
         try {
             this.#smtp = await (this.#options.createSmtp?.(smtp) ?? defaultCreateSmtp(smtp));
             await this.#smtp.verify();
-            logger.debug(formatCompact({ endpoint: name, mode: 'smtp' }));
+            this.#logger.debug(formatCompact({ mode: 'smtp' }));
             this.#imap = this.#options.createImap?.(imap) ?? defaultCreateImap(imap);
             this.#setupImapListeners(this.#imap);
             await new Promise((resolve, reject) => {
@@ -41,13 +42,13 @@ export class EmailEndpoint {
                 this.#imap.once('error', (error) => reject(error));
                 this.#imap.connect();
             });
-            logger.debug(formatCompact({ endpoint: name, mode: 'imap' }));
+            this.#logger.debug(formatCompact({ mode: 'imap' }));
             this.#reconnectAttempts = 0;
             this.#startEmailCheck();
         }
         catch (error) {
             await this.stop();
-            logger.error('Failed to connect email services:', error);
+            this.#logger.error('Failed to connect email services:', error);
             throw error;
         }
     }
@@ -87,17 +88,18 @@ export class EmailEndpoint {
             }
             this.#smtp = null;
         }
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
-    async send({ target, payload }) {
+    async send({ conversation, payload }) {
         if (!this.#smtp)
             throw new Error('SMTP transporter not initialized');
+        const target = conversation.id;
         const mailOptions = formatOutboundMail(payload, {
             from: this.#options.config.smtp.auth.user,
             to: target,
         });
         const info = await this.#smtp.sendMail(mailOptions);
-        logger.debug(formatCompact({ op: 'email_send', target, messageId: info.messageId }));
+        this.#logger.debug(formatCompact({ op: 'email_send', target, messageId: info.messageId }));
         return info.messageId || '';
     }
     /** Test / internal: admit a parsed mail when the endpoint is open. */
@@ -105,7 +107,7 @@ export class EmailEndpoint {
         if (!this.#open)
             return;
         void this.#admitWithAttachments(email).catch((err) => {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'email_gateway_receive_failed',
                 target: email.from,
                 error: err instanceof Error ? err.message : String(err),
@@ -116,20 +118,20 @@ export class EmailEndpoint {
         const savedAttachments = await this.#downloadAttachments(email);
         const content = formatInboundContent(email);
         const sender = email.from;
+        const conversation = emailInboundConversation(String(this.#options.id), email);
         await this.#options.gateway.receive({
-            adapter: this.#options.id,
-            target: sender,
+            conversation,
+            ...(email.messageId ? { message: { conversation, id: email.messageId } } : {}),
             content,
             segments: formatInboundSegments(email, savedAttachments),
-            sender: senderDisplayName(sender),
-            id: email.messageId || undefined,
+            sender: { id: sender, name: senderDisplayName(sender) || undefined },
+            endpointId: this.#options.config.id,
             metadata: Object.freeze({
                 subject: email.subject,
                 to: email.to,
                 cc: email.cc,
                 uid: email.uid,
                 date: email.date.toISOString(),
-                endpoint: this.#options.config.name,
                 ...(savedAttachments.length ? { attachments: savedAttachments } : {}),
             }),
         });
@@ -151,15 +153,15 @@ export class EmailEndpoint {
             const filename = path.basename(rawName) || `attachment_${Date.now()}`;
             const filepath = path.resolve(downloadRoot, filename);
             if (filepath !== downloadRoot && !filepath.startsWith(downloadRoot + path.sep)) {
-                logger.warn(formatCompact({ op: 'email_attachment_skipped', filename: rawName, reason: 'path' }));
+                this.#logger.warn(formatCompact({ op: 'email_attachment_skipped', filename: rawName, reason: 'path' }));
                 continue;
             }
             if (config.allowedTypes?.length && !config.allowedTypes.includes(attachment.contentType ?? '')) {
-                logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'type' }));
+                this.#logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'type' }));
                 continue;
             }
             if (attachment.size != null && attachment.size > config.maxFileSize) {
-                logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'size' }));
+                this.#logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'size' }));
                 continue;
             }
             try {
@@ -167,7 +169,7 @@ export class EmailEndpoint {
                 saved.push({ filename, path: filepath, contentType: attachment.contentType, size: attachment.size });
             }
             catch (error) {
-                logger.warn(formatCompact({
+                this.#logger.warn(formatCompact({
                     op: 'email_attachment_download_failed',
                     filename,
                     error: error instanceof Error ? error.message : String(error),
@@ -181,14 +183,13 @@ export class EmailEndpoint {
             void this.#checkForNewEmails();
         });
         imap.on('error', (error) => {
-            logger.error('IMAP error:', error);
+            this.#logger.error('IMAP error:', error);
             // imap 通常在 error 后紧跟 end；两处都调度，靠已有定时器去重
             this.#scheduleImapReconnect();
         });
         imap.on('end', () => {
-            logger.debug(formatCompact({
+            this.#logger.debug(formatCompact({
                 op: 'disconnect',
-                endpoint: this.#options.config.name,
                 mode: 'imap',
             }));
             this.#scheduleImapReconnect();
@@ -201,9 +202,9 @@ export class EmailEndpoint {
         const base = this.#options.config.imap.reconnectInterval;
         const delay = Math.min(base * 2 ** this.#reconnectAttempts, 300_000);
         this.#reconnectAttempts += 1;
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
             op: 'imap_reconnect_scheduled',
-            endpoint: this.#options.config.name,
+            endpoint: this.#options.config.id,
             reconnect_ms: delay,
         }));
         this.#reconnectTimer = setTimeout(() => {
@@ -225,17 +226,17 @@ export class EmailEndpoint {
                 imap.connect();
             });
             this.#reconnectAttempts = 0;
-            logger.info(formatCompact({
+            this.#logger.info(formatCompact({
                 op: 'imap_reconnect',
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
                 ok: true,
             }));
             void this.#checkForNewEmails();
         }
         catch (error) {
-            logger.warn(formatCompact({
+            this.#logger.warn(formatCompact({
                 op: 'imap_reconnect',
-                endpoint: this.#options.config.name,
+                endpoint: this.#options.config.id,
                 ok: false,
                 error: error instanceof Error ? error.message : String(error),
             }));
@@ -279,7 +280,7 @@ export class EmailEndpoint {
             });
         }
         catch (error) {
-            logger.error('Error checking for new emails:', error);
+            this.#logger.error('Error checking for new emails:', error);
         }
         finally {
             this.#checking = false;
@@ -300,7 +301,7 @@ export class EmailEndpoint {
             void simpleParser(body).then((parsed) => {
                 this.admit(parseEmailMessage(parsed, uid));
             }).catch((error) => {
-                logger.error('Error parsing email:', error);
+                this.#logger.error('Error parsing email:', error);
             });
         });
     }

package/lib/index.d.ts

@@ -1,3 +1,3 @@
-export { addressListText, formatInboundContent, formatInboundSegments, formatOutboundMail, htmlToText, parseEmailMessage, resolveEmailConfig, senderDisplayName, type EmailAdapterConfig, type EmailAttachmentsConfig, type EmailMessage, type EmailWireSegment, type ImapConfig, type ResolvedEmailConfig, type SavedEmailAttachment, type SmtpConfig, } from './protocol.js';
+export { addressListText, emailInboundConversation, formatInboundContent, formatInboundSegments, formatOutboundMail, htmlToText, parseEmailMessage, resolveEmailConfig, senderDisplayName, type EmailAdapterConfig, type EmailAttachmentsConfig, type EmailMessage, type EmailWireSegment, type ImapConfig, type ResolvedEmailConfig, type SavedEmailAttachment, type SmtpConfig, } from './protocol.js';
 export { EmailEndpoint, type EmailEndpointOptions, } from './endpoint.js';
 export { defaultCreateImap, defaultCreateSmtp, type EmailImapFetchMessage, type EmailImapTransport, type EmailSmtpTransport, } from './transport.js';

package/lib/index.js

@@ -1,3 +1,3 @@
-export { addressListText, formatInboundContent, formatInboundSegments, formatOutboundMail, htmlToText, parseEmailMessage, resolveEmailConfig, senderDisplayName, } from './protocol.js';
+export { addressListText, emailInboundConversation, formatInboundContent, formatInboundSegments, formatOutboundMail, htmlToText, parseEmailMessage, resolveEmailConfig, senderDisplayName, } from './protocol.js';
 export { EmailEndpoint, } from './endpoint.js';
 export { defaultCreateImap, defaultCreateSmtp, } from './transport.js';

package/lib/protocol.d.ts

@@ -4,6 +4,7 @@
  */
 import type { Attachment } from 'mailparser';
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationRef } from '@zhin.js/im-contract';
 export interface SmtpConfig {
     readonly host: string;
     readonly port: number;
@@ -33,7 +34,7 @@ export interface EmailAttachmentsConfig {
 }
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface EmailAdapterConfig {
-    readonly name?: string;
+    readonly id?: string;
     readonly smtp?: SmtpConfig;
     readonly imap?: ImapConfig;
     readonly attachments?: EmailAttachmentsConfig;
@@ -44,7 +45,7 @@ export interface EmailAdapterConfig {
 }
 export interface ResolvedEmailConfig {
     readonly context: 'email';
-    readonly name: string;
+    readonly id: string;
     readonly smtp: SmtpConfig;
     readonly imap: Required<Pick<ImapConfig, 'checkInterval' | 'reconnectInterval' | 'mailbox' | 'markSeen'>> & ImapConfig;
     readonly attachments?: {
@@ -101,6 +102,11 @@ export interface SavedEmailAttachment {
  * 未下载的附件（disabled / 被过滤）只保留 content 里的占位文本。
  */
 export declare function formatInboundSegments(email: EmailMessage, savedAttachments?: readonly SavedEmailAttachment[]): Segment[];
+/**
+ * 入站归一化 → ConversationRef：Email 无群/频道概念，所有入站邮件都是
+ * 与发件人地址的 private 会话（id = 发件人地址）。
+ */
+export declare function emailInboundConversation(endpointKey: string, email: EmailMessage): ConversationRef;
 export declare function senderDisplayName(from: string): string;
 /**
  * nodemailer 附件的最小形状：url/path 走 `path`（URL 由 nodemailer 拉流、

package/lib/protocol.js

@@ -12,8 +12,8 @@ export function resolveEmailConfig(config = {}) {
     if (!smtp?.host || !smtp.auth?.user || !imap?.host || !imap.user) {
         throw new TypeError('Email adapter requires smtp + imap config (plugins.<key>.smtp/imap or endpoints with context: email)');
     }
-    const name = (typeof config.name === 'string' && config.name)
-        || (typeof entry?.name === 'string' && entry.name)
+    const id = (typeof config.id === 'string' && config.id)
+        || (typeof entry?.id === 'string' && entry.id)
         || process.env.EMAIL_BOT_NAME
         || 'email-bot';
     const attachmentsSource = config.attachments ?? entry?.attachments;
@@ -27,7 +27,7 @@ export function resolveEmailConfig(config = {}) {
         : undefined;
     return {
         context: 'email',
-        name,
+        id,
         smtp,
         imap: {
             ...imap,
@@ -120,6 +120,17 @@ export function formatInboundSegments(email, savedAttachments = []) {
     }
     return out;
 }
+/**
+ * 入站归一化 → ConversationRef：Email 无群/频道概念，所有入站邮件都是
+ * 与发件人地址的 private 会话（id = 发件人地址）。
+ */
+export function emailInboundConversation(endpointKey, email) {
+    return {
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+        kind: 'private',
+        id: email.from,
+    };
+}
 export function senderDisplayName(from) {
     const name = from.split('<')[0]?.trim();
     return name || from;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-email",
-  "version": "5.0.1",
+  "version": "5.0.4",
   "type": "module",
   "description": "Zhin.js Email adapter for Plugin Runtime (SMTP/IMAP)",
   "main": "./lib/index.js",
@@ -9,16 +9,17 @@
     "imap": "^0.8.19",
     "mailparser": "^3.9.14",
     "nodemailer": "^9.0.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.2"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/im-contract": "1.0.3",
+    "@zhin.js/logger": "1.0.76",
+    "@zhin.js/plugin-runtime": "1.1.5"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.1.4",
-    "@zhin.js/core": "1.5.1",
-    "@zhin.js/plugin-runtime": "1.1.2",
-    "zhin.js": "6.0.1"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/core": "1.5.4",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "zhin.js": "6.0.4"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/schema.json

@@ -3,16 +3,48 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
+    "master": {
+      "type": [
+        "string",
+        "number"
+      ],
+      "description": "框架 master（email address；AI/工具权限、endpoint 管理）。endpoints[i].master 可逐项覆盖"
+    },
+    "trusted": {
+      "type": "array",
+      "items": {
+        "type": [
+          "string",
+          "number"
+        ],
+        "description": "Trusted email address"
+      },
+      "description": "框架 trusted 用户列表（弱于 master）。endpoints[i].trusted 可逐项追加"
+    },
     "endpoints": {
       "type": "array",
-      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（id 必填，其余覆盖顶层）",
       "items": {
         "type": "object",
         "additionalProperties": true,
         "properties": {
-          "name": {
-            "type": "string",
-            "description": "Email bot name"
+          "master": {
+            "type": [
+              "string",
+              "number"
+            ],
+            "description": "本 endpoint 的框架 master（email address）；覆盖顶层 master"
+          },
+          "trusted": {
+            "type": "array",
+            "items": {
+              "type": [
+                "string",
+                "number"
+              ],
+              "description": "Trusted email address"
+            },
+            "description": "本 endpoint 的 trusted 列表"
           },
           "smtp": {
             "type": "object",
@@ -112,10 +144,14 @@
                 }
               }
             }
+          },
+          "id": {
+            "type": "string",
+            "description": "Email bot name"
           }
         },
         "required": [
-          "name",
+          "id",
           "smtp",
           "imap"
         ]

package/src/endpoint.ts

@@ -4,11 +4,12 @@
 import { mkdir, writeFile } from 'node:fs/promises';
 import * as path from 'node:path';
 import { simpleParser } from 'mailparser';
-import type { EndpointInstance } from '@zhin.js/adapter';
+import type { EndpointInstance, EndpointSendRequest } from '@zhin.js/adapter';
 import type { MessageGateway } from '@zhin.js/core/runtime';
-import { formatCompact, getLogger } from '@zhin.js/logger';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import {
+  emailInboundConversation,
   formatInboundContent,
   formatInboundSegments,
   formatOutboundMail,
@@ -26,8 +27,6 @@ import {
   type EmailSmtpTransport,
 } from './transport.js';
 
-const logger = getLogger('email');
-
 export interface EmailEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
@@ -41,6 +40,8 @@ export interface EmailEndpointOptions {
  * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
  */
 export class EmailEndpoint implements EndpointInstance {
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
   readonly #options: EmailEndpointOptions;
   #smtp: EmailSmtpTransport | null = null;
   #imap: EmailImapTransport | null = null;
@@ -52,17 +53,18 @@ export class EmailEndpoint implements EndpointInstance {
   #started = false;
 
   constructor(options: EmailEndpointOptions) {
+    this.#logger = getAdapterLogger('email', options.config.id);
     this.#options = options;
   }
 
   async start(): Promise<void> {
     if (this.#started) return;
     this.#started = true;
-    const { smtp, imap, name } = this.#options.config;
+    const { smtp, imap, id } = this.#options.config;
     try {
       this.#smtp = await (this.#options.createSmtp?.(smtp) ?? defaultCreateSmtp(smtp));
       await this.#smtp.verify();
-      logger.debug(formatCompact({ endpoint: name, mode: 'smtp' }));
+      this.#logger.debug(formatCompact({ mode: 'smtp' }));
 
       this.#imap = this.#options.createImap?.(imap) ?? defaultCreateImap(imap);
       this.#setupImapListeners(this.#imap);
@@ -71,12 +73,12 @@ export class EmailEndpoint implements EndpointInstance {
         this.#imap!.once('error', (error) => reject(error));
         this.#imap!.connect();
       });
-      logger.debug(formatCompact({ endpoint: name, mode: 'imap' }));
+      this.#logger.debug(formatCompact({ mode: 'imap' }));
       this.#reconnectAttempts = 0;
       this.#startEmailCheck();
     } catch (error) {
       await this.stop();
-      logger.error('Failed to connect email services:', error);
+      this.#logger.error('Failed to connect email services:', error);
       throw error;
     }
   }
@@ -117,17 +119,18 @@ export class EmailEndpoint implements EndpointInstance {
       }
       this.#smtp = null;
     }
-    logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
   }
 
-  async send({ target, payload }: { readonly target: string; readonly payload: unknown }): Promise<string> {
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
     if (!this.#smtp) throw new Error('SMTP transporter not initialized');
+    const target = conversation.id;
     const mailOptions = formatOutboundMail(payload, {
       from: this.#options.config.smtp.auth.user,
       to: target,
     });
     const info = await this.#smtp.sendMail(mailOptions);
-    logger.debug(formatCompact({ op: 'email_send', target, messageId: info.messageId }));
+    this.#logger.debug(formatCompact({ op: 'email_send', target, messageId: info.messageId }));
     return info.messageId || '';
   }
 
@@ -135,7 +138,7 @@ export class EmailEndpoint implements EndpointInstance {
   admit(email: EmailMessage): void {
     if (!this.#open) return;
     void this.#admitWithAttachments(email).catch((err) => {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'email_gateway_receive_failed',
         target: email.from,
         error: err instanceof Error ? err.message : String(err),
@@ -147,20 +150,20 @@ export class EmailEndpoint implements EndpointInstance {
     const savedAttachments = await this.#downloadAttachments(email);
     const content = formatInboundContent(email);
     const sender = email.from;
+    const conversation = emailInboundConversation(String(this.#options.id), email);
     await this.#options.gateway.receive({
-      adapter: this.#options.id,
-      target: sender,
+      conversation,
+      ...(email.messageId ? { message: { conversation, id: email.messageId } } : {}),
       content,
       segments: formatInboundSegments(email, savedAttachments),
-      sender: senderDisplayName(sender),
-      id: email.messageId || undefined,
+      sender: { id: sender, name: senderDisplayName(sender) || undefined },
+      endpointId: this.#options.config.id,
       metadata: Object.freeze({
         subject: email.subject,
         to: email.to,
         cc: email.cc,
         uid: email.uid,
         date: email.date.toISOString(),
-        endpoint: this.#options.config.name,
         ...(savedAttachments.length ? { attachments: savedAttachments } : {}),
       }),
     });
@@ -184,22 +187,22 @@ export class EmailEndpoint implements EndpointInstance {
       const filename = path.basename(rawName) || `attachment_${Date.now()}`;
       const filepath = path.resolve(downloadRoot, filename);
       if (filepath !== downloadRoot && !filepath.startsWith(downloadRoot + path.sep)) {
-        logger.warn(formatCompact({ op: 'email_attachment_skipped', filename: rawName, reason: 'path' }));
+        this.#logger.warn(formatCompact({ op: 'email_attachment_skipped', filename: rawName, reason: 'path' }));
         continue;
       }
       if (config.allowedTypes?.length && !config.allowedTypes.includes(attachment.contentType ?? '')) {
-        logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'type' }));
+        this.#logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'type' }));
         continue;
       }
       if (attachment.size != null && attachment.size > config.maxFileSize) {
-        logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'size' }));
+        this.#logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'size' }));
         continue;
       }
       try {
         await writeFile(filepath, attachment.content);
         saved.push({ filename, path: filepath, contentType: attachment.contentType, size: attachment.size });
       } catch (error) {
-        logger.warn(formatCompact({
+        this.#logger.warn(formatCompact({
           op: 'email_attachment_download_failed',
           filename,
           error: error instanceof Error ? error.message : String(error),
@@ -214,14 +217,13 @@ export class EmailEndpoint implements EndpointInstance {
       void this.#checkForNewEmails();
     });
     imap.on('error', (error) => {
-      logger.error('IMAP error:', error);
+      this.#logger.error('IMAP error:', error);
       // imap 通常在 error 后紧跟 end；两处都调度，靠已有定时器去重
       this.#scheduleImapReconnect();
     });
     imap.on('end', () => {
-      logger.debug(formatCompact({
-        op: 'disconnect',
-        endpoint: this.#options.config.name,
+      this.#logger.debug(formatCompact({
+          op: 'disconnect',
         mode: 'imap',
       }));
       this.#scheduleImapReconnect();
@@ -234,9 +236,9 @@ export class EmailEndpoint implements EndpointInstance {
     const base = this.#options.config.imap.reconnectInterval;
     const delay = Math.min(base * 2 ** this.#reconnectAttempts, 300_000);
     this.#reconnectAttempts += 1;
-    logger.warn(formatCompact({
+    this.#logger.warn(formatCompact({
       op: 'imap_reconnect_scheduled',
-      endpoint: this.#options.config.name,
+      endpoint: this.#options.config.id,
       reconnect_ms: delay,
     }));
     this.#reconnectTimer = setTimeout(() => {
@@ -258,16 +260,16 @@ export class EmailEndpoint implements EndpointInstance {
         imap.connect();
       });
       this.#reconnectAttempts = 0;
-      logger.info(formatCompact({
+      this.#logger.info(formatCompact({
         op: 'imap_reconnect',
-        endpoint: this.#options.config.name,
+        endpoint: this.#options.config.id,
         ok: true,
       }));
       void this.#checkForNewEmails();
     } catch (error) {
-      logger.warn(formatCompact({
+      this.#logger.warn(formatCompact({
         op: 'imap_reconnect',
-        endpoint: this.#options.config.name,
+        endpoint: this.#options.config.id,
         ok: false,
         error: error instanceof Error ? error.message : String(error),
       }));
@@ -307,7 +309,7 @@ export class EmailEndpoint implements EndpointInstance {
         });
       });
     } catch (error) {
-      logger.error('Error checking for new emails:', error);
+      this.#logger.error('Error checking for new emails:', error);
     } finally {
       this.#checking = false;
     }
@@ -328,7 +330,7 @@ export class EmailEndpoint implements EndpointInstance {
       void simpleParser(body).then((parsed) => {
         this.admit(parseEmailMessage(parsed, uid));
       }).catch((error) => {
-        logger.error('Error parsing email:', error);
+        this.#logger.error('Error parsing email:', error);
       });
     });
   }

package/src/index.ts

@@ -1,5 +1,6 @@
 export {
   addressListText,
+  emailInboundConversation,
   formatInboundContent,
   formatInboundSegments,
   formatOutboundMail,

package/src/protocol.ts

@@ -6,6 +6,7 @@
 import type { Attachment } from 'mailparser';
 import { htmlToPlainTextWithBlockBreaks, isMediaRef, type MediaRef } from '@zhin.js/core';
 import type { Segment } from '@zhin.js/core/runtime';
+import type { ConversationRef } from '@zhin.js/im-contract';
 import { formatCompact, getLogger } from '@zhin.js/logger';
 
 const logger = getLogger('email');
@@ -42,7 +43,7 @@ export interface EmailAttachmentsConfig {
 
 /** Plugin Runtime owner config (`plugins.<instanceKey>` / schema.json). */
 export interface EmailAdapterConfig {
-  readonly name?: string;
+  readonly id?: string;
   readonly smtp?: SmtpConfig;
   readonly imap?: ImapConfig;
   readonly attachments?: EmailAttachmentsConfig;
@@ -54,7 +55,7 @@ export interface EmailAdapterConfig {
 
 export interface ResolvedEmailConfig {
   readonly context: 'email';
-  readonly name: string;
+  readonly id: string;
   readonly smtp: SmtpConfig;
   readonly imap: Required<Pick<ImapConfig, 'checkInterval' | 'reconnectInterval' | 'mailbox' | 'markSeen'>> & ImapConfig;
   readonly attachments?: {
@@ -93,8 +94,8 @@ export function resolveEmailConfig(config: EmailAdapterConfig = {}): ResolvedEma
       'Email adapter requires smtp + imap config (plugins.<key>.smtp/imap or endpoints with context: email)',
     );
   }
-  const name = (typeof config.name === 'string' && config.name)
-    || (typeof entry?.name === 'string' && entry.name)
+  const id = (typeof config.id === 'string' && config.id)
+    || (typeof entry?.id === 'string' && entry.id)
     || process.env.EMAIL_BOT_NAME
     || 'email-bot';
   const attachmentsSource = config.attachments ?? entry?.attachments;
@@ -108,7 +109,7 @@ export function resolveEmailConfig(config: EmailAdapterConfig = {}): ResolvedEma
     : undefined;
   return {
     context: 'email',
-    name,
+    id,
     smtp,
     imap: {
       ...imap,
@@ -227,6 +228,18 @@ export function formatInboundSegments(
   return out;
 }
 
+/**
+ * 入站归一化 → ConversationRef：Email 无群/频道概念，所有入站邮件都是
+ * 与发件人地址的 private 会话（id = 发件人地址）。
+ */
+export function emailInboundConversation(endpointKey: string, email: EmailMessage): ConversationRef {
+  return {
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
+    kind: 'private',
+    id: email.from,
+  };
+}
+
 export function senderDisplayName(from: string): string {
   const name = from.split('<')[0]?.trim();
   return name || from;