@zhin.js/adapter-email 3.0.3 → 4.0.1

package/CHANGELOG.md

@@ -1,5 +1,53 @@
 # @zhin.js/adapter-email
 
+## 4.0.1
+
+### Patch Changes
+
+- 5691aba: 第二轮全量审计修复批（8 面 ~60 bug）：
+
+  - **安全**：email 附件路径穿越修复（basename + downloadPath 约束）；lark/telegram/satori webhook 鉴权（缺密钥告警、timingSafeEqual、±5min 时效窗、chat_type 修正）；onebot wss/webhook 缺 token 告警；qq webhook 改原始字节验签；renderJsx/JSX 转义注入修复；console runtime token 401 死循环。
+  - **P0 功能**：sandbox 多 endpoint 解析 + WS 路径隔离；short-url expand（undici opaqueredirect）改 follow；AI 压缩摘要失败不再静默丢历史（熔断恢复生效）；console-ui 实时推送事件名归一化 + IndexedDB schema 对齐；process-monitor 热重载不再误判崩溃。
+  - **生命周期**：email IMAP 断线重连 + 在飞锁；onebot11/12 start 失败清理；line replyToken TTL + push 兜底；wechat-mp token 过期重试 + MsgId 去重；weixin-ilink buf 推进/防抖写盘/媒体 TTL/QR abort；satori PONG 看门狗；退避自毁修复。
+  - **游戏**：text-adventure 终局 restart 复活 + requires 服务端校验；tic-tac-toe PvP 占用/restart/队列清理/TTL；idiom-chain/word-riddle 闲聊不扣失误；别名中间件不劫持普通聊天。
+  - **共享库**：schema falsy 默认值/date/tuple/union 修复；database parseCondition Date/未知操作符、sqlite TEXT 往返、query 分派、belongsToMany 方言、migration dry-run；schedule DST 回拨死循环、重复 id 去重、flush 串行化；game-kit fallback 编号/onboarding 提示/尾缀边界/活引用拷贝。
+  - **渲染语音**：fetch 全部超时 + 渲染并发闸；sanitizeHtml form 保文本；STT 扩展名映射 + 删临时文件；TTS 未知 provider 报错；emojiCache LRU 负缓存/fontCache style/clearFonts 恢复；register 错误分类收窄。
+
+- Updated dependencies [cdf64e7]
+- Updated dependencies [5691aba]
+- Updated dependencies [078e3f7]
+- Updated dependencies [9c997b2]
+- Updated dependencies [09d4f25]
+- Updated dependencies [43485a9]
+- Updated dependencies [f0ec5ab]
+- Updated dependencies [3e925d0]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [fa66c4c]
+- Updated dependencies [6cb6152]
+  - @zhin.js/plugin-runtime@1.1.1
+  - zhin.js@5.0.1
+  - @zhin.js/adapter@1.1.1
+  - @zhin.js/core@1.4.1
+
+## 4.0.0
+
+### Patch Changes
+
+- 7db69c1: 命令前缀改为适配器配置项：`MessageDispatcher` 不再硬编码 `/`，默认按消息所属适配器实例 config 的 `commandPrefix` 解析（默认 `''` 无前缀，任意文本按命令匹配），`endpoints[i].commandPrefix` 逐项覆盖；`ImRuntime({ commandPrefix })` 仍可设全局静态前缀。全部 20 个平台适配器 schema 新增 `commandPrefix` 属性。
+
+  BREAKING（行为变化）：未配置时命令不再需要 `/` 前缀——原 `/zt` 写法不再命中，直接发 `zt` 即可；需要斜杠风格的适配器请在配置里显式设 `commandPrefix: '/'`。
+
+- 713445c: 适配器配置格式定稿（不兼容旧格式）：`plugins.<adapter>` 顶层仅共享字段 + `commandPrefix`，`endpoints[i]` 携带 endpoint 级字段（`name` + 凭据，各 schema 已类型化），`endpoints` 为必填（icqq 另需顶层 `master`）；icqq 新增 `trusted` 列表（顶层/逐项均可）。scaffold-wizard 全部字段式与自定义 configure() 产出改为新格式，examples（full-bot / qq-games-bot）与 20 个适配器 README 同步迁移。
+- Updated dependencies [7db69c1]
+- Updated dependencies [e5c84ed]
+- Updated dependencies [3ea84a0]
+- Updated dependencies [1ddcd70]
+- Updated dependencies [ac9da66]
+  - @zhin.js/core@1.4.0
+  - @zhin.js/adapter@1.1.0
+  - @zhin.js/plugin-runtime@1.1.0
+  - zhin.js@5.0.0
+
 ## 3.0.3
 
 ### Patch Changes

package/README.md

@@ -41,20 +41,21 @@ pnpm add @zhin.js/adapter-email
 # zhin.config.yml（Plugin Runtime）
 plugins:
   email:
-    name: my-email-bot
-    smtp:
-      host: smtp.example.com
-      port: 465
-      secure: true
-      auth:
-        user: bot@example.com
-        pass: "${EMAIL_PASSWORD}"
-    imap:
-      host: imap.example.com
-      port: 993
-      tls: true
-      user: bot@example.com
-      password: "${EMAIL_PASSWORD}"
+    endpoints:
+      - name: my-email-bot
+        smtp:
+          host: smtp.example.com
+          port: 465
+          secure: true
+          auth:
+            user: bot@example.com
+            pass: "${EMAIL_PASSWORD}"
+        imap:
+          host: imap.example.com
+          port: 993
+          tls: true
+          user: bot@example.com
+          password: "${EMAIL_PASSWORD}"
 ```
 
 根插件 `zhin.plugins`（或项目图）需引用 `@zhin.js/adapter-email`（`instanceKey: email`）。

package/adapters/email.ts

@@ -19,6 +19,12 @@ export type {
 
 export default defineAdapter<EmailAdapterConfig>({
   capabilities: ['inbound', 'outbound'],
+  // image/file 段映射为邮件附件：canonical MediaRef kind=url/path 均可作
+  // nodemailer attachment.path（URL 由 nodemailer 拉流）；邮件无交互面，交互段降级纯文本。
+  segments: {
+    outboundMedia: ['url', 'path'],
+    interactive: 'text',
+  },
   create(context) {
     return new EmailEndpoint({
       id: context.id,

package/lib/endpoint.d.ts

@@ -10,6 +10,10 @@ export interface EmailEndpointOptions {
     readonly createSmtp?: (config: ResolvedEmailConfig['smtp']) => EmailSmtpTransport | Promise<EmailSmtpTransport>;
     readonly createImap?: (config: ResolvedEmailConfig['imap']) => EmailImapTransport;
 }
+/**
+ * Email（SMTP/IMAP）无好友/群/频道等社交图谱概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
 export declare class EmailEndpoint implements EndpointInstance {
     #private;
     constructor(options: EmailEndpointOptions);

package/lib/endpoint.js

@@ -5,14 +5,21 @@ 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, formatOutboundMail, parseEmailMessage, senderDisplayName, } from './protocol.js';
+import { 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 {
     #options;
     #smtp = null;
     #imap = null;
     #checkTimer = null;
+    #reconnectTimer = null;
+    #reconnectAttempts = 0;
+    #checking = false;
     #open = false;
     #started = false;
     constructor(options) {
@@ -35,6 +42,7 @@ export class EmailEndpoint {
                 this.#imap.connect();
             });
             logger.debug(formatCompact({ endpoint: name, mode: 'imap' }));
+            this.#reconnectAttempts = 0;
             this.#startEmailCheck();
         }
         catch (error) {
@@ -51,10 +59,16 @@ export class EmailEndpoint {
     }
     async stop() {
         this.#open = false;
+        // 先复位 #started，避免 imap.end() 触发的 'end' 事件又武装重连定时器
+        this.#started = false;
         if (this.#checkTimer) {
             clearInterval(this.#checkTimer);
             this.#checkTimer = null;
         }
+        if (this.#reconnectTimer) {
+            clearTimeout(this.#reconnectTimer);
+            this.#reconnectTimer = null;
+        }
         if (this.#imap) {
             try {
                 this.#imap.end();
@@ -73,7 +87,6 @@ export class EmailEndpoint {
             }
             this.#smtp = null;
         }
-        this.#started = false;
         logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
     }
     async send({ target, payload }) {
@@ -107,6 +120,7 @@ export class EmailEndpoint {
             adapter: this.#options.id,
             target: sender,
             content,
+            segments: formatInboundSegments(email, savedAttachments),
             sender: senderDisplayName(sender),
             id: email.messageId || undefined,
             metadata: Object.freeze({
@@ -122,16 +136,24 @@ export class EmailEndpoint {
     }
     /**
      * attachments.enabled 时把入站附件落盘（恢复旧 downloadAttachment 行为，
-     * 附加 maxFileSize / allowedTypes 过滤）；返回落盘结果供 admit metadata 使用。
+     * 附加 maxFileSize / allowedTypes 过滤）；返回落盘结果供 admit segments/metadata 使用。
      */
     async #downloadAttachments(email) {
         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 = [];
         for (const attachment of email.attachments) {
-            const filename = attachment.filename || `attachment_${Date.now()}`;
+            // 防路径穿越：发件人可构造 ../../ 等文件名，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)) {
+                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' }));
                 continue;
@@ -140,7 +162,6 @@ export class EmailEndpoint {
                 logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'size' }));
                 continue;
             }
-            const filepath = path.join(config.downloadPath, filename);
             try {
                 await writeFile(filepath, attachment.content);
                 saved.push({ filename, path: filepath, contentType: attachment.contentType, size: attachment.size });
@@ -161,6 +182,8 @@ export class EmailEndpoint {
         });
         imap.on('error', (error) => {
             logger.error('IMAP error:', error);
+            // imap 通常在 error 后紧跟 end；两处都调度，靠已有定时器去重
+            this.#scheduleImapReconnect();
         });
         imap.on('end', () => {
             logger.debug(formatCompact({
@@ -168,8 +191,57 @@ export class EmailEndpoint {
                 endpoint: this.#options.config.name,
                 mode: 'imap',
             }));
+            this.#scheduleImapReconnect();
         });
     }
+    /** IMAP 断线后按指数退避重建连接并恢复监听（基数 reconnectInterval，封顶 5 分钟）。 */
+    #scheduleImapReconnect() {
+        if (!this.#started || this.#reconnectTimer)
+            return;
+        const base = this.#options.config.imap.reconnectInterval;
+        const delay = Math.min(base * 2 ** this.#reconnectAttempts, 300_000);
+        this.#reconnectAttempts += 1;
+        logger.warn(formatCompact({
+            op: 'imap_reconnect_scheduled',
+            endpoint: this.#options.config.name,
+            reconnect_ms: delay,
+        }));
+        this.#reconnectTimer = setTimeout(() => {
+            this.#reconnectTimer = null;
+            void this.#reconnectImap();
+        }, delay);
+    }
+    async #reconnectImap() {
+        if (!this.#started)
+            return;
+        try {
+            const imap = this.#options.createImap?.(this.#options.config.imap)
+                ?? defaultCreateImap(this.#options.config.imap);
+            this.#imap = imap;
+            this.#setupImapListeners(imap);
+            await new Promise((resolve, reject) => {
+                imap.once('ready', () => resolve());
+                imap.once('error', (error) => reject(error));
+                imap.connect();
+            });
+            this.#reconnectAttempts = 0;
+            logger.info(formatCompact({
+                op: 'imap_reconnect',
+                endpoint: this.#options.config.name,
+                ok: true,
+            }));
+            void this.#checkForNewEmails();
+        }
+        catch (error) {
+            logger.warn(formatCompact({
+                op: 'imap_reconnect',
+                endpoint: this.#options.config.name,
+                ok: false,
+                error: error instanceof Error ? error.message : String(error),
+            }));
+            this.#scheduleImapReconnect();
+        }
+    }
     #startEmailCheck() {
         if (this.#checkTimer)
             return;
@@ -179,8 +251,10 @@ export class EmailEndpoint {
         void this.#checkForNewEmails();
     }
     async #checkForNewEmails() {
-        if (!this.#imap || !this.#started)
+        if (!this.#imap || !this.#started || this.#checking)
             return;
+        // 在飞锁：定时器与 mail 事件可能并发触发，串行化避免重复 admit
+        this.#checking = true;
         try {
             await new Promise((resolve, reject) => {
                 this.#imap.openBox(this.#options.config.imap.mailbox, false, (error) => {
@@ -207,6 +281,9 @@ export class EmailEndpoint {
         catch (error) {
             logger.error('Error checking for new emails:', error);
         }
+        finally {
+            this.#checking = false;
+        }
     }
     #handleImapMessage(msg, _seqno) {
         let body = '';

package/lib/index.d.ts

@@ -1,3 +1,3 @@
-export { addressListText, formatInboundContent, formatOutboundMail, htmlToText, parseEmailMessage, resolveEmailConfig, senderDisplayName, type EmailAdapterConfig, type EmailAttachmentsConfig, type EmailMessage, type EmailWireSegment, type ImapConfig, type ResolvedEmailConfig, type SmtpConfig, } from './protocol.js';
+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 { 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, formatOutboundMail, htmlToText, parseEmailMessage, resolveEmailConfig, senderDisplayName, } from './protocol.js';
+export { addressListText, 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

@@ -3,6 +3,7 @@
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
 import type { Attachment } from 'mailparser';
+import type { Segment } from '@zhin.js/core/runtime';
 export interface SmtpConfig {
     readonly host: string;
     readonly port: number;
@@ -19,6 +20,8 @@ export interface ImapConfig {
     readonly user: string;
     readonly password: string;
     readonly checkInterval?: number;
+    /** IMAP 断线重连基础间隔（指数退避基数），毫秒。 */
+    readonly reconnectInterval?: number;
     readonly mailbox?: string;
     readonly markSeen?: boolean;
 }
@@ -43,7 +46,7 @@ export interface ResolvedEmailConfig {
     readonly context: 'email';
     readonly name: string;
     readonly smtp: SmtpConfig;
-    readonly imap: Required<Pick<ImapConfig, 'checkInterval' | 'mailbox' | 'markSeen'>> & ImapConfig;
+    readonly imap: Required<Pick<ImapConfig, 'checkInterval' | 'reconnectInterval' | 'mailbox' | 'markSeen'>> & ImapConfig;
     readonly attachments?: {
         readonly enabled: boolean;
         readonly downloadPath: string;
@@ -85,6 +88,19 @@ export declare function parseEmailMessage(parsed: {
 }, uid: number): EmailMessage;
 /** Build inbound text for MessageGateway.receive (gateway owns reply routing). */
 export declare function formatInboundContent(email: EmailMessage): string;
+/** 已落盘的入站附件（attachments.enabled 下载结果）。 */
+export interface SavedEmailAttachment {
+    readonly filename: string;
+    readonly path: string;
+    readonly contentType?: string;
+    readonly size?: number;
+}
+/**
+ * 入站邮件 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 已落盘附件映射为 image/file 段，MediaRef kind=path 指向下载路径；
+ * 未下载的附件（disabled / 被过滤）只保留 content 里的占位文本。
+ */
+export declare function formatInboundSegments(email: EmailMessage, savedAttachments?: readonly SavedEmailAttachment[]): Segment[];
 export declare function senderDisplayName(from: string): string;
 /**
  * Wire-encode an already-rendered outbound payload into nodemailer options.

package/lib/protocol.js

@@ -2,7 +2,7 @@
  * Email SMTP/IMAP helpers (no legacy Adapter/Endpoint / segment-mapper).
  * Canonicalization is owned by gateway/core before endpoint.send.
  */
-import { htmlToPlainTextWithBlockBreaks } from '@zhin.js/core';
+import { htmlToPlainTextWithBlockBreaks, isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
 export function resolveEmailConfig(config = {}) {
     const entry = config.endpoints?.find((item) => item.context === 'email');
     const smtp = config.smtp ?? entry?.smtp;
@@ -19,7 +19,7 @@ export function resolveEmailConfig(config = {}) {
         ? {
             enabled: true,
             downloadPath: attachmentsSource.downloadPath || './downloads/email',
-            maxFileSize: attachmentsSource.maxFileSize || 10 * 1024 * 1024,
+            maxFileSize: Math.max(attachmentsSource.maxFileSize || 10 * 1024 * 1024, 1),
             allowedTypes: attachmentsSource.allowedTypes,
         }
         : undefined;
@@ -29,7 +29,9 @@ export function resolveEmailConfig(config = {}) {
         smtp,
         imap: {
             ...imap,
-            checkInterval: imap.checkInterval ?? 60_000,
+            // 数值下限：0/负数会导致 setInterval(0) 风暴
+            checkInterval: Math.max(imap.checkInterval ?? 60_000, 1_000),
+            reconnectInterval: Math.max(imap.reconnectInterval ?? 5_000, 1_000),
             mailbox: imap.mailbox ?? 'INBOX',
             markSeen: imap.markSeen !== false,
         },
@@ -89,6 +91,33 @@ export function formatInboundContent(email) {
     const text = parts.join('\n').trim();
     return text || '(Empty email)';
 }
+/**
+ * 入站邮件 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 已落盘附件映射为 image/file 段，MediaRef kind=path 指向下载路径；
+ * 未下载的附件（disabled / 被过滤）只保留 content 里的占位文本。
+ */
+export function formatInboundSegments(email, savedAttachments = []) {
+    const out = [];
+    const content = formatInboundContent(email);
+    if (content)
+        out.push({ type: 'text', data: { text: content } });
+    for (const saved of savedAttachments) {
+        const type = saved.contentType?.startsWith('image/') ? 'image' : 'file';
+        out.push({
+            type,
+            data: {
+                media: {
+                    kind: 'path',
+                    value: saved.path,
+                    ...(saved.contentType ? { mime_type: saved.contentType } : {}),
+                },
+                name: saved.filename,
+                ...(type === 'image' ? { alt: saved.filename } : {}),
+            },
+        });
+    }
+    return out;
+}
 export function senderDisplayName(from) {
     const name = from.split('<')[0]?.trim();
     return name || from;
@@ -138,10 +167,13 @@ export function formatOutboundMail(payload, options) {
             }
             case 'image':
             case 'file': {
-                if (typeof data.url === 'string' && data.url) {
+                // 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 || (item.type === 'image' ? 'image.png' : 'file')),
-                        path: data.url,
+                        filename: String(data.filename || data.name || (item.type === 'image' ? 'image.png' : 'file')),
+                        path: media.value,
                     });
                 }
                 break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhin.js/adapter-email",
-  "version": "3.0.3",
+  "version": "4.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.0.1",
-    "@zhin.js/core": "1.3.5",
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/core": "1.4.1",
     "@zhin.js/logger": "1.0.75",
-    "@zhin.js/plugin-runtime": "1.0.1"
+    "@zhin.js/plugin-runtime": "1.1.1"
   },
   "peerDependencies": {
-    "@zhin.js/adapter": "1.0.1",
-    "@zhin.js/core": "1.3.5",
-    "@zhin.js/plugin-runtime": "1.0.1",
-    "zhin.js": "4.1.3"
+    "@zhin.js/adapter": "1.1.1",
+    "@zhin.js/core": "1.4.1",
+    "@zhin.js/plugin-runtime": "1.1.1",
+    "zhin.js": "5.0.1"
   },
   "peerDependenciesMeta": {
     "zhin.js": {

package/schema.json

@@ -3,56 +3,131 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "name": {
-      "type": "string",
-      "default": "email-bot"
-    },
-    "smtp": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "host": { "type": "string" },
-        "port": { "type": "number" },
-        "secure": { "type": "boolean" },
-        "auth": {
-          "type": "object",
-          "additionalProperties": false,
-          "properties": {
-            "user": { "type": "string" },
-            "pass": { "type": "string" }
+    "endpoints": {
+      "type": "array",
+      "description": "多账号：一个插件实例挂多个 endpoint。每项与顶层字段同构（name 必填，其余覆盖顶层）",
+      "items": {
+        "type": "object",
+        "additionalProperties": true,
+        "properties": {
+          "name": {
+            "type": "string",
+            "description": "Email bot name"
           },
-          "required": ["user", "pass"]
-        }
-      },
-      "required": ["host", "port", "secure", "auth"]
-    },
-    "imap": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "host": { "type": "string" },
-        "port": { "type": "number" },
-        "tls": { "type": "boolean" },
-        "user": { "type": "string" },
-        "password": { "type": "string" },
-        "checkInterval": { "type": "number", "default": 60000 },
-        "mailbox": { "type": "string", "default": "INBOX" },
-        "markSeen": { "type": "boolean", "default": true }
-      },
-      "required": ["host", "port", "tls", "user", "password"]
-    },
-    "attachments": {
-      "type": "object",
-      "additionalProperties": false,
-      "properties": {
-        "enabled": { "type": "boolean", "default": false },
-        "downloadPath": { "type": "string" },
-        "maxFileSize": { "type": "number" },
-        "allowedTypes": {
-          "type": "array",
-          "items": { "type": "string" }
-        }
+          "smtp": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "host": {
+                "type": "string"
+              },
+              "port": {
+                "type": "number"
+              },
+              "secure": {
+                "type": "boolean"
+              },
+              "auth": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "user": {
+                    "type": "string"
+                  },
+                  "pass": {
+                    "type": "string"
+                  }
+                },
+                "required": [
+                  "user",
+                  "pass"
+                ]
+              }
+            },
+            "required": [
+              "host",
+              "port",
+              "secure",
+              "auth"
+            ]
+          },
+          "imap": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "host": {
+                "type": "string"
+              },
+              "port": {
+                "type": "number"
+              },
+              "tls": {
+                "type": "boolean"
+              },
+              "user": {
+                "type": "string"
+              },
+              "password": {
+                "type": "string"
+              },
+              "checkInterval": {
+                "type": "number",
+                "default": 60000
+              },
+              "mailbox": {
+                "type": "string",
+                "default": "INBOX"
+              },
+              "markSeen": {
+                "type": "boolean",
+                "default": true
+              }
+            },
+            "required": [
+              "host",
+              "port",
+              "tls",
+              "user",
+              "password"
+            ]
+          },
+          "attachments": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "enabled": {
+                "type": "boolean",
+                "default": false
+              },
+              "downloadPath": {
+                "type": "string"
+              },
+              "maxFileSize": {
+                "type": "number"
+              },
+              "allowedTypes": {
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        },
+        "required": [
+          "name",
+          "smtp",
+          "imap"
+        ]
       }
+    },
+    "commandPrefix": {
+      "type": "string",
+      "default": "",
+      "description": "命令前缀（默认 '' 无前缀，任意文本按命令匹配；如 '/' 要求 / 开头）。endpoints[i] 可逐项覆盖"
     }
-  }
+  },
+  "required": [
+    "endpoints"
+  ]
 }

package/src/endpoint.ts

@@ -10,11 +10,13 @@ import { formatCompact, getLogger } from '@zhin.js/logger';
 import type { CapabilityId } from '@zhin.js/plugin-runtime';
 import {
   formatInboundContent,
+  formatInboundSegments,
   formatOutboundMail,
   parseEmailMessage,
   senderDisplayName,
   type EmailMessage,
   type ResolvedEmailConfig,
+  type SavedEmailAttachment,
 } from './protocol.js';
 import {
   defaultCreateImap,
@@ -34,11 +36,18 @@ export interface EmailEndpointOptions {
   readonly createImap?: (config: ResolvedEmailConfig['imap']) => EmailImapTransport;
 }
 
+/**
+ * Email（SMTP/IMAP）无好友/群/频道等社交图谱概念，
+ * 不适用 EndpointManagement 语义端口；本 endpoint 不暴露该端口。
+ */
 export class EmailEndpoint implements EndpointInstance {
   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;
 
@@ -63,6 +72,7 @@ export class EmailEndpoint implements EndpointInstance {
         this.#imap!.connect();
       });
       logger.debug(formatCompact({ endpoint: name, mode: 'imap' }));
+      this.#reconnectAttempts = 0;
       this.#startEmailCheck();
     } catch (error) {
       await this.stop();
@@ -81,10 +91,16 @@ export class EmailEndpoint implements EndpointInstance {
 
   async stop(): Promise<void> {
     this.#open = false;
+    // 先复位 #started，避免 imap.end() 触发的 'end' 事件又武装重连定时器
+    this.#started = false;
     if (this.#checkTimer) {
       clearInterval(this.#checkTimer);
       this.#checkTimer = null;
     }
+    if (this.#reconnectTimer) {
+      clearTimeout(this.#reconnectTimer);
+      this.#reconnectTimer = null;
+    }
     if (this.#imap) {
       try {
         this.#imap.end();
@@ -101,7 +117,6 @@ export class EmailEndpoint implements EndpointInstance {
       }
       this.#smtp = null;
     }
-    this.#started = false;
     logger.debug(formatCompact({ op: 'disconnect', endpoint: this.#options.config.name }));
   }
 
@@ -136,6 +151,7 @@ export class EmailEndpoint implements EndpointInstance {
       adapter: this.#options.id,
       target: sender,
       content,
+      segments: formatInboundSegments(email, savedAttachments),
       sender: senderDisplayName(sender),
       id: email.messageId || undefined,
       metadata: Object.freeze({
@@ -152,17 +168,25 @@ export class EmailEndpoint implements EndpointInstance {
 
   /**
    * attachments.enabled 时把入站附件落盘（恢复旧 downloadAttachment 行为，
-   * 附加 maxFileSize / allowedTypes 过滤）；返回落盘结果供 admit metadata 使用。
+   * 附加 maxFileSize / allowedTypes 过滤）；返回落盘结果供 admit segments/metadata 使用。
    */
   async #downloadAttachments(
     email: EmailMessage,
-  ): Promise<Array<{ filename: string; path: string; contentType?: string; size?: number }>> {
+  ): Promise<SavedEmailAttachment[]> {
     const config = this.#options.config.attachments;
     if (!config?.enabled || email.attachments.length === 0) return [];
     await mkdir(config.downloadPath, { recursive: true });
-    const saved: Array<{ filename: string; path: string; contentType?: string; size?: number }> = [];
+    const downloadRoot = path.resolve(config.downloadPath);
+    const saved: SavedEmailAttachment[] = [];
     for (const attachment of email.attachments) {
-      const filename = attachment.filename || `attachment_${Date.now()}`;
+      // 防路径穿越：发件人可构造 ../../ 等文件名，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)) {
+        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' }));
         continue;
@@ -171,7 +195,6 @@ export class EmailEndpoint implements EndpointInstance {
         logger.debug(formatCompact({ op: 'email_attachment_skipped', filename, reason: 'size' }));
         continue;
       }
-      const filepath = path.join(config.downloadPath, filename);
       try {
         await writeFile(filepath, attachment.content);
         saved.push({ filename, path: filepath, contentType: attachment.contentType, size: attachment.size });
@@ -192,6 +215,8 @@ export class EmailEndpoint implements EndpointInstance {
     });
     imap.on('error', (error) => {
       logger.error('IMAP error:', error);
+      // imap 通常在 error 后紧跟 end；两处都调度，靠已有定时器去重
+      this.#scheduleImapReconnect();
     });
     imap.on('end', () => {
       logger.debug(formatCompact({
@@ -199,9 +224,57 @@ export class EmailEndpoint implements EndpointInstance {
         endpoint: this.#options.config.name,
         mode: 'imap',
       }));
+      this.#scheduleImapReconnect();
     });
   }
 
+  /** IMAP 断线后按指数退避重建连接并恢复监听（基数 reconnectInterval，封顶 5 分钟）。 */
+  #scheduleImapReconnect(): void {
+    if (!this.#started || this.#reconnectTimer) return;
+    const base = this.#options.config.imap.reconnectInterval;
+    const delay = Math.min(base * 2 ** this.#reconnectAttempts, 300_000);
+    this.#reconnectAttempts += 1;
+    logger.warn(formatCompact({
+      op: 'imap_reconnect_scheduled',
+      endpoint: this.#options.config.name,
+      reconnect_ms: delay,
+    }));
+    this.#reconnectTimer = setTimeout(() => {
+      this.#reconnectTimer = null;
+      void this.#reconnectImap();
+    }, delay);
+  }
+
+  async #reconnectImap(): Promise<void> {
+    if (!this.#started) return;
+    try {
+      const imap = this.#options.createImap?.(this.#options.config.imap)
+        ?? defaultCreateImap(this.#options.config.imap);
+      this.#imap = imap;
+      this.#setupImapListeners(imap);
+      await new Promise<void>((resolve, reject) => {
+        imap.once('ready', () => resolve());
+        imap.once('error', (error) => reject(error));
+        imap.connect();
+      });
+      this.#reconnectAttempts = 0;
+      logger.info(formatCompact({
+        op: 'imap_reconnect',
+        endpoint: this.#options.config.name,
+        ok: true,
+      }));
+      void this.#checkForNewEmails();
+    } catch (error) {
+      logger.warn(formatCompact({
+        op: 'imap_reconnect',
+        endpoint: this.#options.config.name,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+      }));
+      this.#scheduleImapReconnect();
+    }
+  }
+
   #startEmailCheck(): void {
     if (this.#checkTimer) return;
     this.#checkTimer = setInterval(() => {
@@ -211,7 +284,9 @@ export class EmailEndpoint implements EndpointInstance {
   }
 
   async #checkForNewEmails(): Promise<void> {
-    if (!this.#imap || !this.#started) return;
+    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) => {
@@ -233,6 +308,8 @@ export class EmailEndpoint implements EndpointInstance {
       });
     } catch (error) {
       logger.error('Error checking for new emails:', error);
+    } finally {
+      this.#checking = false;
     }
   }
 

package/src/index.ts

@@ -1,6 +1,7 @@
 export {
   addressListText,
   formatInboundContent,
+  formatInboundSegments,
   formatOutboundMail,
   htmlToText,
   parseEmailMessage,
@@ -12,6 +13,7 @@ export {
   type EmailWireSegment,
   type ImapConfig,
   type ResolvedEmailConfig,
+  type SavedEmailAttachment,
   type SmtpConfig,
 } from './protocol.js';
 

package/src/protocol.ts

@@ -4,7 +4,8 @@
  */
 
 import type { Attachment } from 'mailparser';
-import { htmlToPlainTextWithBlockBreaks } from '@zhin.js/core';
+import { htmlToPlainTextWithBlockBreaks, isMediaRef, mediaRefFromLegacyData } from '@zhin.js/core';
+import type { Segment } from '@zhin.js/core/runtime';
 
 export interface SmtpConfig {
   readonly host: string;
@@ -23,6 +24,8 @@ export interface ImapConfig {
   readonly user: string;
   readonly password: string;
   readonly checkInterval?: number;
+  /** IMAP 断线重连基础间隔（指数退避基数），毫秒。 */
+  readonly reconnectInterval?: number;
   readonly mailbox?: string;
   readonly markSeen?: boolean;
 }
@@ -50,7 +53,7 @@ export interface ResolvedEmailConfig {
   readonly context: 'email';
   readonly name: string;
   readonly smtp: SmtpConfig;
-  readonly imap: Required<Pick<ImapConfig, 'checkInterval' | 'mailbox' | 'markSeen'>> & ImapConfig;
+  readonly imap: Required<Pick<ImapConfig, 'checkInterval' | 'reconnectInterval' | 'mailbox' | 'markSeen'>> & ImapConfig;
   readonly attachments?: {
     readonly enabled: boolean;
     readonly downloadPath: string;
@@ -96,7 +99,7 @@ export function resolveEmailConfig(config: EmailAdapterConfig = {}): ResolvedEma
     ? {
       enabled: true as const,
       downloadPath: attachmentsSource.downloadPath || './downloads/email',
-      maxFileSize: attachmentsSource.maxFileSize || 10 * 1024 * 1024,
+      maxFileSize: Math.max(attachmentsSource.maxFileSize || 10 * 1024 * 1024, 1),
       allowedTypes: attachmentsSource.allowedTypes,
     }
     : undefined;
@@ -106,7 +109,9 @@ export function resolveEmailConfig(config: EmailAdapterConfig = {}): ResolvedEma
     smtp,
     imap: {
       ...imap,
-      checkInterval: imap.checkInterval ?? 60_000,
+      // 数值下限：0/负数会导致 setInterval(0) 风暴
+      checkInterval: Math.max(imap.checkInterval ?? 60_000, 1_000),
+      reconnectInterval: Math.max(imap.reconnectInterval ?? 5_000, 1_000),
       mailbox: imap.mailbox ?? 'INBOX',
       markSeen: imap.markSeen !== false,
     },
@@ -181,6 +186,44 @@ export function formatInboundContent(email: EmailMessage): string {
   return text || '(Empty email)';
 }
 
+/** 已落盘的入站附件（attachments.enabled 下载结果）。 */
+export interface SavedEmailAttachment {
+  readonly filename: string;
+  readonly path: string;
+  readonly contentType?: string;
+  readonly size?: number;
+}
+
+/**
+ * 入站邮件 → canonical Segment[]（与 formatInboundContent 纯文本视图同源双轨）。
+ * 已落盘附件映射为 image/file 段，MediaRef kind=path 指向下载路径；
+ * 未下载的附件（disabled / 被过滤）只保留 content 里的占位文本。
+ */
+export function formatInboundSegments(
+  email: EmailMessage,
+  savedAttachments: readonly SavedEmailAttachment[] = [],
+): Segment[] {
+  const out: Segment[] = [];
+  const content = formatInboundContent(email);
+  if (content) out.push({ type: 'text', data: { text: content } });
+  for (const saved of savedAttachments) {
+    const type = saved.contentType?.startsWith('image/') ? 'image' : 'file';
+    out.push({
+      type,
+      data: {
+        media: {
+          kind: 'path',
+          value: saved.path,
+          ...(saved.contentType ? { mime_type: saved.contentType } : {}),
+        },
+        name: saved.filename,
+        ...(type === 'image' ? { alt: saved.filename } : {}),
+      },
+    });
+  }
+  return out;
+}
+
 export function senderDisplayName(from: string): string {
   const name = from.split('<')[0]?.trim();
   return name || from;
@@ -246,10 +289,15 @@ export function formatOutboundMail(
       }
       case 'image':
       case 'file': {
-        if (typeof data.url === 'string' && data.url) {
+        // 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 || (item.type === 'image' ? 'image.png' : 'file')),
-            path: data.url,
+            filename: String(
+              data.filename || data.name || (item.type === 'image' ? 'image.png' : 'file'),
+            ),
+            path: media.value,
           });
         }
         break;