@zhin.js/adapter-email 5.0.2 → 5.0.5

package/CHANGELOG.md

@@ -1,5 +1,47 @@
 # @zhin.js/adapter-email
 
+## 5.0.5
+
+### Patch Changes
+
+- @zhin.js/adapter@1.1.7
+- @zhin.js/core@1.5.5
+- zhin.js@6.0.5
+
+## 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

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 { 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,7 +88,7 @@ export class EmailEndpoint {
             }
             this.#smtp = null;
         }
-        logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
+        this.#logger.debug(formatCompact({ op: 'disconnect' }));
     }
     async send({ conversation, payload }) {
         if (!this.#smtp)
@@ -98,7 +99,7 @@ export class EmailEndpoint {
             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. */
@@ -106,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),
@@ -123,14 +124,14 @@ export class EmailEndpoint {
             ...(email.messageId ? { message: { conversation, id: email.messageId } } : {}),
             content,
             segments: formatInboundSegments(email, savedAttachments),
-            sender: senderDisplayName(sender),
+            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 } : {}),
             }),
         });
@@ -152,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 {
@@ -168,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),
@@ -182,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();
@@ -202,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(() => {
@@ -226,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),
             }));
@@ -280,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;
@@ -301,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/protocol.d.ts

@@ -34,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;
@@ -45,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?: {
@@ -106,7 +106,7 @@ export declare function formatInboundSegments(email: EmailMessage, savedAttachme
  * 入站归一化 → ConversationRef：Email 无群/频道概念，所有入站邮件都是
  * 与发件人地址的 private 会话（id = 发件人地址）。
  */
-export declare function emailInboundConversation(endpointId: string, email: EmailMessage): ConversationRef;
+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,
@@ -124,9 +124,9 @@ export function formatInboundSegments(email, savedAttachments = []) {
  * 入站归一化 → ConversationRef：Email 无群/频道概念，所有入站邮件都是
  * 与发件人地址的 private 会话（id = 发件人地址）。
  */
-export function emailInboundConversation(endpointId, email) {
+export function emailInboundConversation(endpointKey, email) {
     return {
-        endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+        endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
         kind: 'private',
         id: email.from,
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-email",
-  "version": "5.0.2",
+  "version": "5.0.5",
   "type": "module",
   "description": "Zhin.js Email adapter for Plugin Runtime (SMTP/IMAP)",
   "main": "./lib/index.js",
@@ -9,17 +9,17 @@
     "imap": "^0.8.19",
     "mailparser": "^3.9.14",
     "nodemailer": "^9.0.3",
-    "@zhin.js/adapter": "1.1.5",
-    "@zhin.js/core": "1.5.2",
-    "@zhin.js/im-contract": "1.0.1",
-    "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.1.3"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/core": "1.5.5",
+    "@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.5",
-    "@zhin.js/core": "1.5.2",
-    "@zhin.js/plugin-runtime": "1.1.3",
-    "zhin.js": "6.0.2"
+    "@zhin.js/adapter": "1.1.7",
+    "@zhin.js/core": "1.5.5",
+    "@zhin.js/plugin-runtime": "1.1.5",
+    "zhin.js": "6.0.5"
   },
   "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

@@ -6,7 +6,7 @@ import * as path from 'node:path';
 import { simpleParser } from 'mailparser';
 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,
@@ -27,8 +27,6 @@ import {
   type EmailSmtpTransport,
 } from './transport.js';
 
-const logger = getLogger('email');
-
 export interface EmailEndpointOptions {
   readonly id: CapabilityId;
   readonly gateway: MessageGateway;
@@ -42,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;
@@ -53,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);
@@ -72,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;
     }
   }
@@ -118,7 +119,7 @@ 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({ conversation, payload }: EndpointSendRequest): Promise<string> {
@@ -129,7 +130,7 @@ export class EmailEndpoint implements EndpointInstance {
       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 || '';
   }
 
@@ -137,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),
@@ -155,14 +156,14 @@ export class EmailEndpoint implements EndpointInstance {
       ...(email.messageId ? { message: { conversation, id: email.messageId } } : {}),
       content,
       segments: formatInboundSegments(email, savedAttachments),
-      sender: senderDisplayName(sender),
+      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 } : {}),
       }),
     });
@@ -186,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),
@@ -216,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();
@@ -236,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(() => {
@@ -260,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),
       }));
@@ -309,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;
     }
@@ -330,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/protocol.ts

@@ -43,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;
@@ -55,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?: {
@@ -94,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;
@@ -109,7 +109,7 @@ export function resolveEmailConfig(config: EmailAdapterConfig = {}): ResolvedEma
     : undefined;
   return {
     context: 'email',
-    name,
+    id,
     smtp,
     imap: {
       ...imap,
@@ -232,9 +232,9 @@ export function formatInboundSegments(
  * 入站归一化 → ConversationRef：Email 无群/频道概念，所有入站邮件都是
  * 与发件人地址的 private 会话（id = 发件人地址）。
  */
-export function emailInboundConversation(endpointId: string, email: EmailMessage): ConversationRef {
+export function emailInboundConversation(endpointKey: string, email: EmailMessage): ConversationRef {
   return {
-    endpoint: { id: endpointId, adapter: endpointId.split('\0')[0] ?? endpointId },
+    endpoint: { id: endpointKey, adapter: endpointKey.split('\0')[0] ?? endpointKey },
     kind: 'private',
     id: email.from,
   };