@zhin.js/adapter-email 1.0.1 → 1.1.0

package/src/endpoint.ts

@@ -1,420 +1,364 @@
+import { Endpoint } from 'zhin.js/adapter';
 /**
- * Email Endpoint 实现
+ * EmailEndpoint — lifecycle, SMTP outbound, IMAP inbound polling.
  */
-import nodemailer from "nodemailer";
-import Imap from "imap";
-import { simpleParser, type ParsedMail, type Attachment } from "mailparser";
-import { formatCompact, Endpoint, Message, MessageSegment, segment, SendContent, SendOptions, htmlToPlainTextWithBlockBreaks } from 'zhin.js';
-import { EventEmitter } from "events";
-import { createWriteStream, promises as fs } from "fs";
-import path from "path";
-import type { EmailEndpointConfig, EmailMessage } from "./types.js";
-import type { EmailAdapter } from "./adapter.js";
-
-export class EmailEndpoint extends EventEmitter implements Endpoint<EmailEndpointConfig, EmailMessage> {
-    $config: EmailEndpointConfig;
-    $connected: boolean = false;
-    private smtpTransporter: nodemailer.Transporter | null = null;
-    private imapConnection: Imap | null = null;
-    private checkTimer: NodeJS.Timeout | null = null;
+import { mkdir, writeFile } from 'node:fs/promises';
+import * as path from 'node:path';
+import { simpleParser } from 'mailparser';
+import { type EndpointSendRequest } from 'zhin.js/adapter';
+import { formatCompact, getAdapterLogger } from '@zhin.js/logger';
+import type { CapabilityId } from 'zhin.js';
+import {
+  emailInboundConversation,
+  formatInboundContent,
+  formatInboundSegments,
+  formatOutboundMail,
+  parseEmailMessage,
+  senderDisplayName,
+  type EmailMessage,
+  type ResolvedEmailConfig,
+  type SavedEmailAttachment,
+} from './protocol.js';
+import {
+  defaultCreateImap,
+  defaultCreateSmtp,
+  type EmailImapFetchMessage,
+  type EmailImapTransport,
+  type EmailSmtpTransport,
+} from './transport.js';
+import { EmailClient } from './client.js';
+
+export interface EmailEndpointOptions {
+  readonly id: CapabilityId;
+  readonly config: ResolvedEmailConfig;
+  readonly createSmtp?: (config: ResolvedEmailConfig['smtp']) => EmailSmtpTransport | Promise<EmailSmtpTransport>;
+  readonly createImap?: (config: ResolvedEmailConfig['imap']) => EmailImapTransport;
+}
 
-    get logger() {
-    return this.adapter.plugin.logger;
+/**
+ * Email（SMTP/IMAP）无好友/群/频道等社交图谱概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
+export class EmailEndpoint extends Endpoint<EmailClient> {
+  readonly client: EmailClient;
+  readonly #logger!: ReturnType<typeof getAdapterLogger>;
+
+  readonly #options: EmailEndpointOptions;
+  #smtp: EmailSmtpTransport | null = null;
+  #imap: EmailImapTransport | null = null;
+  #checkTimer: NodeJS.Timeout | null = null;
+  #reconnectTimer: NodeJS.Timeout | null = null;
+  #reconnectAttempts = 0;
+  #checking = false;
+  #open = false;
+  #started = false;
+
+  constructor(options: EmailEndpointOptions) {
+    super();
+    this.#logger = getAdapterLogger('email', options.config.id);
+    this.#options = options;
+    this.client = new EmailClient(() => this.#smtp, () => this.#imap);
   }
 
-  get $id() {
-        return this.$config.name;
-    }
-
-    constructor(public adapter: EmailAdapter, config: EmailEndpointConfig) {
-        super();
-        this.$config = config;
-
-        // 设置默认值
-        this.$config.imap.checkInterval = this.$config.imap.checkInterval || 60000; // 1分钟
-        this.$config.imap.mailbox = this.$config.imap.mailbox || 'INBOX';
-        this.$config.imap.markSeen = this.$config.imap.markSeen !== false;
-
-        if (this.$config.attachments?.enabled) {
-            this.$config.attachments.downloadPath = this.$config.attachments.downloadPath || './downloads/email';
-            this.$config.attachments.maxFileSize = this.$config.attachments.maxFileSize || 10 * 1024 * 1024; // 10MB
-        }
-    }
-
-    async $connect(): Promise<void> {
-        try {
-            // 初始化 SMTP 传输器
-            this.smtpTransporter = nodemailer.createTransport({
-                host: this.$config.smtp.host,
-                port: this.$config.smtp.port,
-                secure: this.$config.smtp.secure,
-                auth: this.$config.smtp.auth
-            });
-
-            // 验证 SMTP 连接
-            await this.smtpTransporter!.verify();
-            this.logger.info(formatCompact({ endpoint: this.$id, mode: "smtp" }));
-
-            // 初始化 IMAP 连接
-            this.imapConnection = new Imap({
-                user: this.$config.imap.user,
-                password: this.$config.imap.password,
-                host: this.$config.imap.host,
-                port: this.$config.imap.port,
-                tls: this.$config.imap.tls
-            });
-
-            // 设置 IMAP 事件监听
-            this.setupImapListeners();
-
-            // 连接 IMAP
-            await new Promise<void>((resolve, reject) => {
-                this.imapConnection!.once('ready', resolve);
-                this.imapConnection!.once('error', reject);
-                this.imapConnection!.connect();
-            });
-
-            this.logger.info(formatCompact({ endpoint: this.$id, mode: "imap" }));
-
-            // 开始检查邮件
-            this.startEmailCheck();
-            this.$connected = true;
-
-        } catch (error) {
-            this.logger.error('Failed to connect email services:', error);
-            throw error;
-        }
-    }
-
-    async $disconnect(): Promise<void> {
-        this.$connected = false;
-
-        // 停止定时检查
-        if (this.checkTimer) {
-            clearInterval(this.checkTimer);
-            this.checkTimer = null;
-        }
-
-        // 关闭 IMAP 连接
-        if (this.imapConnection) {
-            this.imapConnection.end();
-            this.imapConnection = null;
-        }
-
-        // 关闭 SMTP 连接
-        if (this.smtpTransporter) {
-            this.smtpTransporter.close();
-            this.smtpTransporter = null;
-        }
-
-        this.logger.info(formatCompact( { op: "disconnect", endpoint: this.$id }));
-    }
-
-    private setupImapListeners(): void {
-        if (!this.imapConnection) return;
-
-        this.imapConnection.on('mail', (numNewMsgs: number) => {
-            this.logger.debug(`Received ${numNewMsgs} new emails`);
-            this.checkForNewEmails();
+  async start(): Promise<void> {
+    if (this.#started) return;
+    this.#started = true;
+    const { smtp, imap, id } = this.#options.config;
+    try {
+      this.#smtp = await (this.#options.createSmtp?.(smtp) ?? defaultCreateSmtp(smtp));
+      await this.#smtp.verify();
+      this.#logger.debug(formatCompact({ mode: 'smtp' }));
+
+      this.#imap = this.#options.createImap?.(imap) ?? defaultCreateImap(imap);
+      this.#setupImapListeners(this.#imap);
+      await new Promise<void>((resolve, reject) => {
+        this.#imap!.once('ready', () => {
+          void this.#emitPlatformEvent('imap.ready', Object.freeze({}));
+          resolve();
         });
-
-        this.imapConnection.on('error', (error: any) => {
-            this.logger.error('IMAP error:', error);
-        });
-
-        this.imapConnection.on('end', () => {
-            this.logger.info(formatCompact( { op: "disconnect", endpoint: this.$id, mode: "imap" }));
-        });
-    }
-
-    private startEmailCheck(): void {
-        if (this.checkTimer) return;
-
-        this.checkTimer = setInterval(() => {
-            this.checkForNewEmails();
-        }, this.$config.imap.checkInterval!);
-
-        // 立即检查一次
-        this.checkForNewEmails();
+        this.#imap!.once('error', (error) => reject(error));
+        this.#imap!.connect();
+      });
+      this.#logger.debug(formatCompact({ mode: 'imap' }));
+      this.#reconnectAttempts = 0;
+      this.#startEmailCheck();
+    } catch (error) {
+      await this.stop();
+      this.#logger.error('Failed to connect email services:', error);
+      throw error;
     }
+  }
 
-    private async checkForNewEmails(): Promise<void> {
-        if (!this.imapConnection || !this.$connected) return;
-
-        try {
-            await new Promise<void>((resolve, reject) => {
-                this.imapConnection!.openBox(this.$config.imap.mailbox!, false, (error, box) => {
-                    if (error) return reject(error);
-
-                    // 搜索未读邮件
-                    this.imapConnection!.search(['UNSEEN'], (error, results) => {
-                        if (error) return reject(error);
-
-                        if (results.length === 0) {
-                            return resolve();
-                        }
-
-                        // 获取邮件
-                        const fetch = this.imapConnection!.fetch(results, {
-                            bodies: '',
-                            markSeen: this.$config.imap.markSeen
-                        });
+  open(): void {
+    this.#open = true;
+  }
 
-                        fetch.on('message', (msg, seqno) => {
-                            this.handleImapMessage(msg, seqno);
-                        });
+  close(): void {
+    this.#open = false;
+  }
 
-                        fetch.once('error', reject);
-                        fetch.once('end', resolve);
-                    });
-                });
-            });
-        } catch (error) {
-            this.logger.error('Error checking for new emails:', error);
-        }
+  async stop(): Promise<void> {
+    this.#open = false;
+    // 先复位 #started，避免 imap.end() 触发的 'end' 事件又武装重连定时器
+    this.#started = false;
+    if (this.#checkTimer) {
+      clearInterval(this.#checkTimer);
+      this.#checkTimer = null;
     }
-
-    private handleImapMessage(msg: any, seqno: number): void {
-        let body = '';
-        let uid = 0;
-
-        msg.on('body', (stream: any) => {
-            stream.on('data', (chunk: any) => {
-                body += chunk.toString('utf8');
-            });
-        });
-
-        msg.once('attributes', (attrs: any) => {
-            uid = attrs.uid;
-        });
-
-        msg.once('end', async () => {
-            try {
-                const parsed = await simpleParser(body);
-                const emailMessage = this.parseEmailMessage(parsed, uid);
-                const formattedMessage = this.$formatMessage(emailMessage);
-                this.adapter.emit('message.receive', formattedMessage);
-            } catch (error) {
-                this.logger.error('Error parsing email:', error);
-            }
-        });
+    if (this.#reconnectTimer) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = null;
     }
-
-    private parseEmailMessage(parsed: ParsedMail, uid: number): EmailMessage {
-        const getAddressText = (addr: any): string[] => {
-            if (!addr) return [];
-            if (Array.isArray(addr)) {
-                return addr.map((a: any) => a.text || a.address || a.toString());
-            }
-            return [addr.text || addr.address || addr.toString()];
-        };
-
-        return {
-            messageId: parsed.messageId || '',
-            from: parsed.from ? getAddressText(parsed.from)[0] || '' : '',
-            to: getAddressText(parsed.to),
-            cc: getAddressText(parsed.cc),
-            bcc: getAddressText(parsed.bcc),
-            subject: parsed.subject || '',
-            text: parsed.text || '',
-            html: parsed.html ? parsed.html.toString() : '',
-            attachments: parsed.attachments || [],
-            date: parsed.date || new Date(),
-            uid
-        };
+    if (this.#imap) {
+      try {
+        this.#imap.end();
+      } catch {
+        /* ignore */
+      }
+      this.#imap = null;
     }
-
-    $formatMessage(emailMsg: EmailMessage): Message<EmailMessage> {
-        // 确定频道类型和ID
-        const channelType = 'private';
-        const channelId = emailMsg.from;
-
-        // 解析邮件内容
-        const content = EmailEndpoint.parseEmailContent(emailMsg);
-
-        const result = Message.from(emailMsg, {
-            $id: emailMsg.messageId,
-            $adapter: 'email',
-            $endpoint: this.$config.name,
-            $sender: {
-                id: emailMsg.from,
-                name: emailMsg.from.split('<')[0].trim() || emailMsg.from
-            },
-            $channel: {
-                id: channelId,
-                type: channelType as any
-            },
-            $raw: JSON.stringify(emailMsg),
-            $timestamp: emailMsg.date.getTime(),
-            $content: content,
-            $recall: async () => {
-                // 邮件适配器暂时不支持撤回消息
-            },
-            $reply: async (content: SendContent): Promise<string> => {
-                return await this.adapter.sendMessage({
-                    context: this.$config.context,
-                    endpoint: this.$config.name,
-                    id: emailMsg.from,
-                    type: 'private',
-                    content
-                });
-            }
-        });
-
-        return result;
+    if (this.#smtp) {
+      try {
+        this.#smtp.close();
+      } catch {
+        /* ignore */
+      }
+      this.#smtp = null;
     }
+    this.#logger.debug(formatCompact({ op: 'disconnect' }));
+  }
 
-    static parseEmailContent(email: EmailMessage): MessageSegment[] {
-        const segments: MessageSegment[] = [];
-
-        // 添加主题（如果有且不为空）
-        if (email.subject) {
-            segments.push(segment.text(`Subject: ${email.subject}\n\n`));
-        }
-
-        // 添加文本内容
-        if (email.text) {
-            segments.push(segment.text(email.text));
-        }
-
-        // 如果没有纯文本但有HTML，尝试转换
-        if (!email.text && email.html) {
-            const textFromHtml = EmailEndpoint.htmlToText(email.html);
-            if (textFromHtml) {
-                segments.push(segment.text(textFromHtml));
-            }
-        }
-
-        // 处理附件
-        for (const attachment of email.attachments) {
-            if (attachment.contentType?.startsWith('image/')) {
-                segments.push(segment('image', {
-                    filename: attachment.filename,
-                    contentType: attachment.contentType,
-                    size: attachment.size
-                }));
-            } else {
-                segments.push(segment('file', {
-                    filename: attachment.filename,
-                    contentType: attachment.contentType,
-                    size: attachment.size
-                }));
-            }
-        }
-
-        return segments.length > 0 ? segments : [segment.text('(Empty email)')];
-    }
+  async send({ conversation, payload }: EndpointSendRequest): Promise<string> {
+    const target = conversation.id;
+    const mailOptions = formatOutboundMail(payload, {
+      from: this.#options.config.smtp.auth.user,
+      to: target,
+    });
+    const info = await this.client.sendMail(mailOptions);
+    this.#logger.debug(formatCompact({ op: 'email_send', target, messageId: info.messageId }));
+    return info.messageId || '';
+  }
 
-    async $sendMessage(options: SendOptions): Promise<string> {
-        if (!this.smtpTransporter) {
-            throw new Error('SMTP transporter not initialized');
-        }
+  /** Test / internal: admit a parsed mail when the endpoint is open. */
+  admit(email: EmailMessage): void {
+    if (!this.#open) return;
+    void this.#emitPlatformEvent('mail', email);
+    void this.#admitWithAttachments(email).catch((err) => {
+      this.#logger.warn(formatCompact({
+        op: 'email_gateway_receive_failed',
+        target: email.from,
+        error: err instanceof Error ? err.message : String(err),
+      }));
+    });
+  }
 
-        try {
-            const mailOptions = await this.formatSendContent(options);
-            const info = await this.smtpTransporter.sendMail(mailOptions);
-            this.logger.debug('Email sent:', info.messageId);
-            return info.messageId || '';
-        } catch (error) {
-            this.logger.error('Failed to send email:', error);
-            throw error;
-        }
-    }
+  async #admitWithAttachments(email: EmailMessage): Promise<void> {
+    const savedAttachments = await this.#downloadAttachments(email);
+    const content = formatInboundContent(email);
+    const sender = email.from;
+    const conversation = emailInboundConversation(String(this.#options.id), email);
+    await this.emit('message.receive', {
+      conversation,
+      ...(email.messageId ? { message: { conversation, id: email.messageId } } : {}),
+      content,
+      segments: formatInboundSegments(email, savedAttachments),
+      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(),
+        ...(savedAttachments.length ? { attachments: savedAttachments } : {}),
+      }),
+    });
+  }
 
-    async $recallMessage(id: string): Promise<void> {
-        // 邮件适配器暂时不支持撤回消息
+  /**
+   * attachments.enabled 时把入站附件落盘（恢复旧 downloadAttachment 行为，
+   * 附加 maxFileSize / allowedTypes 过滤）；返回落盘结果供 admit segments/metadata 使用。
+   */
+  async #downloadAttachments(
+    email: EmailMessage,
+  ): Promise<SavedEmailAttachment[]> {
+    const config = this.#options.config.attachments;
+    if (!config?.enabled || email.attachments.length === 0) return [];
+    await mkdir(config.downloadPath, { recursive: true });
+    const downloadRoot = path.resolve(config.downloadPath);
+    const saved: SavedEmailAttachment[] = [];
+    for (const attachment of email.attachments) {
+      // 防路径穿越：发件人可构造 ../../ 等文件名，basename + resolve 后必须落在 downloadPath 内
+      const rawName = attachment.filename || `attachment_${Date.now()}`;
+      const filename = path.basename(rawName) || `attachment_${Date.now()}`;
+      const filepath = path.resolve(downloadRoot, filename);
+      if (filepath !== downloadRoot && !filepath.startsWith(downloadRoot + path.sep)) {
+        this.#logger.warn(formatCompact({ op: 'email_attachment_skipped', filename: rawName, reason: 'path' }));
+        continue;
+      }
+      if (config.allowedTypes?.length && !config.allowedTypes.includes(attachment.contentType ?? '')) {
+        this.#logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'type' }));
+        continue;
+      }
+      if (attachment.size != null && attachment.size > config.maxFileSize) {
+        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) {
+        this.#logger.warn(formatCompact({
+          op: 'email_attachment_download_failed',
+          filename,
+          error: error instanceof Error ? error.message : String(error),
+        }));
+      }
     }
+    return saved;
+  }
 
-    private async formatSendContent(options: SendOptions): Promise<nodemailer.SendMailOptions> {
-        const mailOptions: nodemailer.SendMailOptions = {
-            from: this.$config.smtp.auth.user,
-            to: options.id,
-            subject: 'Message from Bot'
-        };
-
-        if (typeof options.content === 'string') {
-            mailOptions.text = options.content;
-        } else if (Array.isArray(options.content)) {
-            const textParts: string[] = [];
-            const htmlParts: string[] = [];
-            const attachments: any[] = [];
-
-            for (const item of options.content) {
-                if (typeof item === 'string') {
-                    textParts.push(item);
-                    htmlParts.push(item.replace(/\n/g, '<br>'));
-                } else {
-                    const segment = item as MessageSegment;
-                    switch (segment.type) {
-                        case 'text':
-                            const textContent = segment.data.text || segment.data.content || '';
-                            textParts.push(textContent);
-                            htmlParts.push(textContent.replace(/\n/g, '<br>'));
-                            break;
-                        case 'image':
-                            if (segment.data.url) {
-                                attachments.push({
-                                    filename: segment.data.filename || 'image.png',
-                                    path: segment.data.url
-                                });
-                            }
-                            break;
-                        case 'file':
-                            if (segment.data.url) {
-                                attachments.push({
-                                    filename: segment.data.filename || 'file',
-                                    path: segment.data.url
-                                });
-                            }
-                            break;
-                    }
-                }
-            }
-
-            if (textParts.length > 0) {
-                mailOptions.text = textParts.join('\n');
-                mailOptions.html = htmlParts.join('<br>');
-            }
+  #setupImapListeners(imap: EmailImapTransport): void {
+    imap.on('mail', () => {
+      void this.#emitPlatformEvent('imap.mail', Object.freeze({}));
+      void this.#checkForNewEmails();
+    });
+    imap.on('error', (error) => {
+      void this.#emitPlatformEvent('imap.error', error);
+      this.#logger.error('IMAP error:', error);
+      // imap 通常在 error 后紧跟 end；两处都调度，靠已有定时器去重
+      this.#scheduleImapReconnect(imap);
+    });
+    imap.on('end', () => {
+      void this.#emitPlatformEvent('imap.end', Object.freeze({}));
+      this.#logger.debug(formatCompact({
+          op: 'disconnect',
+        mode: 'imap',
+      }));
+      this.#scheduleImapReconnect(imap);
+    });
+  }
 
-            if (attachments.length > 0) {
-                mailOptions.attachments = attachments;
-            }
-        }
+  async #emitPlatformEvent(name: string, event: unknown): Promise<void> {
+    await this.emitPlatform(name, event).catch((error) => {
+      this.#logger.warn(formatCompact({
+        op: 'email_platform_event_failed',
+        event: name,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+    });
+  }
 
-        // 如果有回复对象，可以在这里处理
-        // 邮件适配器暂时不支持回复对象
+  /** IMAP 断线后按指数退避重建连接并恢复监听（基数 reconnectInterval，封顶 5 分钟）。 */
+  #scheduleImapReconnect(source?: EmailImapTransport): void {
+    // A replaced transport may emit a late `end` after its earlier `error`
+    // already caused a successful reconnect. Only the currently owned IMAP
+    // connection may arm the next generation's reconnect timer.
+    if (!this.#started || this.#reconnectTimer || (source && this.#imap !== source)) return;
+    const base = this.#options.config.imap.reconnectInterval;
+    const delay = Math.min(base * 2 ** this.#reconnectAttempts, 300_000);
+    this.#reconnectAttempts += 1;
+    this.#logger.warn(formatCompact({
+      op: 'imap_reconnect_scheduled',
+      endpoint: this.#options.config.id,
+      reconnect_ms: delay,
+    }));
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = null;
+      void this.#reconnectImap();
+    }, delay);
+  }
 
-        return mailOptions;
+  async #reconnectImap(): Promise<void> {
+    if (!this.#started) return;
+    let imap: EmailImapTransport | undefined;
+    try {
+      const nextImap = this.#options.createImap?.(this.#options.config.imap)
+        ?? defaultCreateImap(this.#options.config.imap);
+      imap = nextImap;
+      this.#imap = nextImap;
+      this.#setupImapListeners(nextImap);
+      await new Promise<void>((resolve, reject) => {
+        nextImap.once('ready', () => {
+          void this.#emitPlatformEvent('imap.ready', Object.freeze({ reconnect: true }));
+          resolve();
+        });
+        nextImap.once('error', (error) => reject(error));
+        nextImap.connect();
+      });
+      this.#reconnectAttempts = 0;
+      this.#logger.info(formatCompact({
+        op: 'imap_reconnect',
+        endpoint: this.#options.config.id,
+        ok: true,
+      }));
+      void this.#checkForNewEmails();
+    } catch (error) {
+      this.#logger.warn(formatCompact({
+        op: 'imap_reconnect',
+        endpoint: this.#options.config.id,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+      this.#scheduleImapReconnect(imap);
     }
+  }
 
-    // 下载附件到本地
-    private async downloadAttachment(attachment: Attachment): Promise<string> {
-        if (!this.$config.attachments?.enabled || !this.$config.attachments.downloadPath) {
-            throw new Error('Attachment download is not enabled');
-        }
-
-        const downloadPath = this.$config.attachments.downloadPath;
-        await fs.mkdir(downloadPath, { recursive: true });
-
-        const filename = attachment.filename || `attachment_${Date.now()}`;
-        const filepath = path.join(downloadPath, filename);
-
-        return new Promise((resolve, reject) => {
-            const writeStream = createWriteStream(filepath);
-            writeStream.write(attachment.content);
-            writeStream.end();
+  #startEmailCheck(): void {
+    if (this.#checkTimer) return;
+    this.#checkTimer = setInterval(() => {
+      void this.#checkForNewEmails();
+    }, this.#options.config.imap.checkInterval);
+    void this.#checkForNewEmails();
+  }
 
-            writeStream.on('finish', () => resolve(filepath));
-            writeStream.on('error', reject);
+  async #checkForNewEmails(): Promise<void> {
+    if (!this.#imap || !this.#started || this.#checking) return;
+    // 在飞锁：定时器与 mail 事件可能并发触发，串行化避免重复 admit
+    this.#checking = true;
+    try {
+      await new Promise<void>((resolve, reject) => {
+        this.#imap!.openBox(this.#options.config.imap.mailbox, false, (error) => {
+          if (error) return reject(error);
+          this.#imap!.search(['UNSEEN'], (searchError, results) => {
+            if (searchError) return reject(searchError);
+            if (!results.length) return resolve();
+            const fetch = this.#imap!.fetch(results, {
+              bodies: '',
+              markSeen: this.#options.config.imap.markSeen,
+            });
+            fetch.on('message', (msg, seqno) => {
+              this.#handleImapMessage(msg, seqno);
+            });
+            fetch.once('error', (fetchError) => reject(fetchError));
+            fetch.once('end', () => resolve());
+          });
         });
+      });
+    } catch (error) {
+      this.#logger.error('Error checking for new emails:', error);
+    } finally {
+      this.#checking = false;
     }
+  }
 
-    /**
-     * HTML → 纯文本转换，处理常见标签和实体
-     */
-    static htmlToText(html: string): string {
-        return htmlToPlainTextWithBlockBreaks(html);
-    }
+  #handleImapMessage(msg: EmailImapFetchMessage, _seqno: number): void {
+    let body = '';
+    let uid = 0;
+    msg.on('body', (stream) => {
+      stream.on('data', (chunk: Buffer | string) => {
+        body += typeof chunk === 'string' ? chunk : chunk.toString('utf8');
+      });
+    });
+    msg.once('attributes', (attrs) => {
+      uid = attrs.uid ?? 0;
+    });
+    msg.once('end', () => {
+      void simpleParser(body).then((parsed) => {
+        this.admit(parseEmailMessage(parsed, uid));
+      }).catch((error) => {
+        this.#logger.error('Error parsing email:', error);
+      });
+    });
+  }
 }
-
-// 创建和注册适配器