@xmanrui/dsh-im 4.22.0 → 4.24.0

package/src/channels/dingtalk/dingtalk-controller.mjs

@@ -1,3 +1,4 @@
+import { extractConnectionEvidence, atConnectionStage, createConnectionDiagnostics } from '../shared/connection-error.mjs';
 import { randomUUID } from 'node:crypto';
 
 import {
@@ -135,6 +136,7 @@ export class DingtalkController {
   #createRuntime;
   #deleteState;
   #logger;
+  #diagnostics;
   #clock;
   #runtimes = new Map();
   #errors = new Map();
@@ -193,10 +195,17 @@ export class DingtalkController {
     this.#createRuntime = createRuntime;
     this.#deleteState = deleteState;
     this.#logger = logger;
+    this.#diagnostics = createConnectionDiagnostics({ channel: 'dingtalk', prefix: 'DT-CONN', logger });
     this.#clock = clock;
   }
 
   /** Starts all configured DingTalk runtimes whose secrets are available. */
+  get diagnostics() { return this.#diagnostics; }
+  #failure(error, code, message) {
+    const stage = code.startsWith('poll-') ? 'qr.poll' : code === 'activation-failed' ? 'activation' : 'qr.begin';
+    return this.#diagnostics.report(error, { reuse: true, stage, publicError: { code, message } }).publicError;
+  }
+
   async initialize() {
     if (this.#closed) return this.status();
     for (const config of this.#configStore.list()) {
@@ -209,16 +218,17 @@ export class DingtalkController {
       await this.#withBotTransition(config.botId, async () => {
         const latest = this.#configStore.get(config.botId);
         if (!latest || this.#closed) return;
-        const clientSecret = await this.#resolveSecret(latest.secretRef);
-        if (!clientSecret) {
-          this.#errors.set(
-            latest.botId,
-            safeError('missing-secret', t('钉钉机器人凭据缺失，请移除后重新扫码。')),
-          );
-          this.#touch();
-          return;
-        }
+        let clientSecret;
         try {
+          clientSecret = await this.#resolveSecret(latest.secretRef);
+          if (!clientSecret) {
+            this.#errors.set(
+              latest.botId,
+              safeError('missing-secret', t('钉钉机器人凭据缺失，请移除后重新扫码。')),
+            );
+            this.#touch();
+            return;
+          }
           await this.#startRuntime(latest, clientSecret);
           this.#errors.delete(latest.botId);
         } catch (error) {
@@ -282,7 +292,7 @@ export class DingtalkController {
         record.error = safeError('cancelled', t('扫码接入已取消。'));
       } else {
         record.state = 'failed';
-        record.error = safeError('qr-start-failed', t('无法生成钉钉二维码，请稍后重试。'));
+        record.error = this.#failure(error, 'qr-start-failed', t('无法生成钉钉二维码，请稍后重试。'));
       }
       if (this.#activeAttemptId === record.id) this.#activeAttemptId = null;
       this.#touch();
@@ -307,7 +317,7 @@ export class DingtalkController {
     await this.#withBotTransition(identity.botId, async () => {
       if (this.#closed) throw abortError();
       const previousConfig = this.#configStore.getByClientId(normalizedClientId);
-      const previousSecret = await this.#credentials.resolve(identity.secretRef).catch(() => undefined);
+      const previousSecret = await atConnectionStage('credential.read', () => this.#credentials.resolve(identity.secretRef), 'credential-store');
       if (this.#closed) throw abortError();
       const config = {
         botId: identity.botId,
@@ -315,9 +325,9 @@ export class DingtalkController {
         secretRef: identity.secretRef,
         approvedSenders: previousConfig?.approvedSenders ?? [],
       };
-      await this.#credentials.set(identity.secretRef, normalizedSecret);
+      await atConnectionStage('credential.save', () => this.#credentials.set(identity.secretRef, normalizedSecret), 'credential-store');
       try {
-        await this.#configStore.save(config);
+        await atConnectionStage('account.save', () => this.#configStore.save(config), 'account-config');
       } catch (error) {
         await this.#restoreCredential(identity.secretRef, previousSecret);
         throw error;
@@ -434,30 +444,37 @@ export class DingtalkController {
 
   /** Removes one bot, its secret, runtime, and local conversation state. */
   async deleteBot(botId) {
+    const warnings = [];
     const config = this.#configStore.get(botId);
     if (!config) throw new Error('Unknown DingTalk bot');
     await this.#withBotTransition(botId, async () => {
-      const previousSecret = await this.#credentials.resolve(config.secretRef).catch(() => undefined);
+      const previousSecret = await atConnectionStage('credential.read', () => this.#credentials.resolve(config.secretRef), 'credential-store');
       await this.#stopRuntime(botId);
       try {
-        await this.#credentials.unset(config.secretRef);
-        await this.#configStore.remove(botId);
+        await atConnectionStage('credential.remove', () => this.#credentials.unset(config.secretRef), 'credential-store');
+        await atConnectionStage('account.remove', () => this.#configStore.remove(botId), 'account-config');
       } catch (error) {
-        if (cleanString(previousSecret?.value)) {
-          await this.#credentials.set(config.secretRef, previousSecret.value).catch(() => undefined);
-          await this.#startRuntime(config, previousSecret.value).catch(() => undefined);
+        if (!this.#configStore.get(botId)) {
+          warnings.push(this.#diagnostics.report(error, { operation: 'bot.delete', stage: 'workspace.cleanup', warning: true,
+            publicError: { code: 'workspace-cleanup-failed', message: '账号已移除，但本地状态清理失败。' } }).publicError);
+        } else {
+          if (cleanString(previousSecret?.value)) {
+            await atConnectionStage('credential.save', () => this.#credentials.set(config.secretRef, previousSecret.value), 'credential-store').catch(() => undefined);
+            await this.#startRuntime(config, previousSecret.value).catch(() => undefined);
+          }
+          throw new Error('Unable to remove the DingTalk bot safely.', { cause: error });
         }
-        throw new Error('Unable to remove the DingTalk bot safely.', { cause: error });
       }
       try {
         await this.#deleteState({ botId, config });
-      } catch {
-        this.#logger.warn?.(`[dsh-dingtalk] bot ${botId} state cleanup failed`);
+      } catch (error) {
+        warnings.push(this.#diagnostics.report(error, { reuse: true, operation: 'bot.delete', stage: 'state.cleanup', warning: true,
+          publicError: { code: 'cleanup-failed', message: '账号已移除，但本地状态清理失败。' } }).publicError);
       }
       this.#errors.delete(botId);
       this.#touch();
     });
-    return this.status();
+    return { ...this.status(), ...(warnings.length ? { warnings } : {}) };
   }
 
   /** Approves one opaque pending-sender request for a bot. */
@@ -517,7 +534,7 @@ export class DingtalkController {
         currentStatus = { state: 'error' };
       }
       const connected = isRuntimeConnected(runtime, currentStatus);
-      const accountError = this.#errors.get(config.botId);
+      const accountError = currentStatus.error ?? this.#errors.get(config.botId);
       const state = connected ? 'connected' : accountError ? 'error' : 'offline';
       const approvedIds = new Set(config.approvedSenders.map((sender) => sender.staffId));
       const pending = internalPendingSenders(currentStatus)
@@ -626,7 +643,7 @@ export class DingtalkController {
         if (this.#activeAttemptId === record.id) this.#activeAttemptId = null;
       } else if (record.state === 'connecting') {
         record.state = 'failed';
-        record.error = safeError(
+        record.error = this.#failure(error,
           'activation-failed',
           t('钉钉已授权，但无法安全保存接入配置。'),
         );
@@ -634,7 +651,7 @@ export class DingtalkController {
         this.#logger.error?.('[dsh-dingtalk] bot activation failed');
       } else {
         record.state = 'pending';
-        record.error = safeError('poll-failed', t('钉钉授权查询暂时失败，正在重试。'));
+        record.error = this.#failure(error, 'poll-failed', t('钉钉授权查询暂时失败，正在重试。'));
       }
     } finally {
       this.#touch();
@@ -645,7 +662,7 @@ export class DingtalkController {
   async #activateBot(record, { clientId, clientSecret }) {
     const identity = deriveDingtalkBotIdentity(clientId);
     const previousConfig = this.#configStore.getByClientId(clientId);
-    const previousSecret = await this.#credentials.resolve(identity.secretRef).catch(() => undefined);
+    const previousSecret = await atConnectionStage('credential.read', () => this.#credentials.resolve(identity.secretRef), 'credential-store');
     const config = {
       botId: identity.botId,
       clientId,
@@ -655,12 +672,12 @@ export class DingtalkController {
     return this.#withBotTransition(identity.botId, async () => {
       const rollback = async () => {
         await this.#stopRuntime(identity.botId);
-        if (previousConfig) await this.#configStore.save(previousConfig).catch(() => undefined);
+        if (previousConfig) await atConnectionStage('account.save', () => this.#configStore.save(previousConfig), 'account-config').catch(() => undefined);
         else if (this.#configStore.get(identity.botId)) {
-          const removed = await this.#configStore.remove(identity.botId).catch(() => null);
+          const removed = await atConnectionStage('account.remove', () => this.#configStore.remove(identity.botId), 'account-config').catch(() => null);
           if (removed) {
             await this.#deleteState({ botId: identity.botId, config }).catch((cleanupError) => {
-              this.#logger.warn?.('[dsh-dingtalk] failed to clean up cancelled bot state:', cleanupError);
+              this.#logger.warn?.('[dsh-dingtalk] failed to clean up cancelled bot state:', extractConnectionEvidence(cleanupError).details);
             });
           }
         }
@@ -669,10 +686,10 @@ export class DingtalkController {
           await this.#startRuntime(previousConfig, previousSecret.value).catch(() => undefined);
         }
       };
-      await this.#credentials.set(identity.secretRef, clientSecret);
+      await atConnectionStage('credential.save', () => this.#credentials.set(identity.secretRef, clientSecret), 'credential-store');
       try {
         this.#assertAttemptActive(record);
-        await this.#configStore.save(config);
+        await atConnectionStage('account.save', () => this.#configStore.save(config), 'account-config');
         this.#assertAttemptActive(record);
       } catch (error) {
         await rollback();
@@ -703,12 +720,12 @@ export class DingtalkController {
     return this.#withBotTransition(previousConfig.botId, async () => {
       const clientSecret = await this.#resolveSecret(previousConfig.secretRef);
       if (!clientSecret) throw new Error('The DingTalk client secret is missing');
-      await this.#configStore.save(nextConfig);
+      await atConnectionStage('account.save', () => this.#configStore.save(nextConfig), 'account-config');
       try {
         await this.#startRuntime(nextConfig, clientSecret);
         this.#errors.delete(previousConfig.botId);
       } catch (error) {
-        await this.#configStore.save(previousConfig).catch(() => undefined);
+        await atConnectionStage('account.save', () => this.#configStore.save(previousConfig), 'account-config').catch(() => undefined);
         await this.#startRuntime(previousConfig, clientSecret).catch(() => undefined);
         const publicError = this.#rememberConnectionFailure({
           config: previousConfig,
@@ -730,11 +747,11 @@ export class DingtalkController {
     if (this.#closed) throw abortError();
     let runtime;
     try {
-      runtime = await this.#createRuntime({
+      runtime = await atConnectionStage('runtime.prepare', () => this.#createRuntime({
         botId: config.botId,
         config: structuredClone(config),
         clientSecret,
-      });
+      }));
     } catch (error) {
       throw dingtalkRuntimeStartError('dingtalk-runtime-prepare-failed', error);
     }
@@ -774,12 +791,10 @@ export class DingtalkController {
       clientId: config.clientId,
       clientSecret,
     });
-    this.#errors.set(config.botId, failure.publicError);
-    this.#logger.error?.(
-      `[dsh-dingtalk] ${context} [${failure.publicError.referenceId}]`,
-      failure.diagnostic,
-    );
-    return failure.publicError;
+    const reported = this.#diagnostics.report(error, { reuse: true, botId: config.botId, stage: 'connection.start', publicError: { ...failure.publicError, details: { dependencies: failure.diagnostic.dependencies, proxyConfigured: failure.diagnostic.proxy.configured } } }).publicError;
+    const visible = { ...failure.publicError, details: reported.details };
+    this.#errors.set(config.botId, visible);
+    return visible;
   }
 
   async #stopRuntime(botId) {
@@ -791,14 +806,14 @@ export class DingtalkController {
   }
 
   async #resolveSecret(secretRef) {
-    const result = await this.#credentials.resolve(secretRef).catch(() => undefined);
+    const result = await atConnectionStage('credential.read', () => this.#credentials.resolve(secretRef), 'credential-store');
     return cleanString(result?.value);
   }
 
   async #restoreCredential(secretRef, previous) {
     try {
-      if (cleanString(previous?.value)) await this.#credentials.set(secretRef, previous.value);
-      else await this.#credentials.unset(secretRef);
+      if (cleanString(previous?.value)) await atConnectionStage('credential.save', () => this.#credentials.set(secretRef, previous.value), 'credential-store');
+      else await atConnectionStage('credential.remove', () => this.#credentials.unset(secretRef), 'credential-store');
     } catch {
       this.#logger.error?.(`[dsh-dingtalk] failed to restore credential ${secretRef}`);
     }

package/src/channels/dingtalk/dingtalk-runtime.mjs

@@ -1,3 +1,4 @@
+import { atConnectionStage, createConnectionDiagnostics } from '../shared/connection-error.mjs';
 import { createDingtalkApi } from './dingtalk-api.mjs';
 import {
   createDingtalkBridgeStatus,
@@ -87,7 +88,7 @@ async function connectStream(client, timeoutMs, pollIntervalMs, signal) {
         void connectTask.then(() => client.disconnect()).catch(() => undefined);
       }
       if (signal.aborted) throw signal.reason;
-      throw new Error(`DingTalk Stream handshake timed out after ${timeoutMs}ms`);
+      throw Object.assign(new Error(`DingTalk Stream handshake timed out after ${timeoutMs}ms`), { code: 'ETIMEDOUT', timeoutMs, cause: error });
     }
     throw error;
   }
@@ -134,6 +135,7 @@ export class DingtalkRuntime {
   #contextEnhancement;
   #accessPolicy;
   #logger;
+  #diagnostics;
   #replyTimeoutMs;
   #maxMessageChars;
   #connectTimeoutMs;
@@ -176,6 +178,7 @@ export class DingtalkRuntime {
     this.#contextEnhancement = contextEnhancement;
     this.#accessPolicy = accessPolicy;
     this.#logger = logger;
+    this.#diagnostics = createConnectionDiagnostics({ channel: 'dingtalk', logger, prefix: 'DT-CONN' });
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#maxMessageChars = maxMessageChars;
     this.#connectTimeoutMs = connectTimeoutMs;
@@ -228,7 +231,7 @@ export class DingtalkRuntime {
     let startStage = 'dingtalk-harness-connect-failed';
 
     try {
-      await this.#harness.ensureRunning({ signal });
+      await atConnectionStage('harness.check', () => this.#harness.ensureRunning({ signal }));
       this.#status.harnessReachable = true;
       startStage = 'dingtalk-runtime-prepare-failed';
       if (typeof this.#state.removePendingSenderByStaffId === 'function') {
@@ -348,12 +351,22 @@ export class DingtalkRuntime {
       this.#status.lastConnectedAt = Date.now();
       this.#status.lastCheckedAt = Date.now();
       this.#status.lastError = null;
+      this.#status.error = null;
+      this.#diagnostics.clear();
       this.#connectionMonitor = setInterval(() => {
         const connected = streamIsOpen(client);
         this.#status.ready = connected;
         this.#status.dingtalkStreamState = connected ? 'connected' : 'reconnecting';
         this.#status.lastCheckedAt = Date.now();
-        if (connected) this.#status.lastError = null;
+        if (connected) {
+          this.#status.lastError = null;
+          this.#status.error = null;
+          this.#diagnostics.clear();
+        } else {
+          this.#status.error = this.#diagnostics.report(null, { operation: 'connection.monitor', automatic: true, botId: this.#config.botId,
+            publicError: { code: 'stream-connect-failed', message: t('钉钉连接未就绪，请稍后重试。') } }).publicError;
+          this.#status.lastError = this.#status.error.message;
+        }
       }, 1_000);
       this.#connectionMonitor.unref?.();
       return this.status;
@@ -362,7 +375,7 @@ export class DingtalkRuntime {
       const failure = aborted ? error : dingtalkRuntimeStartError(startStage, error);
       this.#status.ready = false;
       this.#status.dingtalkStreamState = aborted ? 'idle' : 'failed';
-      this.#status.lastError = aborted ? null : (failure?.message ?? String(failure));
+      this.#status.lastError = aborted ? null : t('钉钉连接未就绪，请稍后重试。');
       await this.stop({ preserveError: !aborted });
       throw failure;
     }
@@ -370,6 +383,7 @@ export class DingtalkRuntime {
 
   async stop({ preserveError = false } = {}) {
     const lastError = preserveError ? this.#status.lastError : null;
+    const publicError = preserveError ? this.#status.error : null;
     const abortController = this.#abortController;
     this.#abortController = null;
     abortController?.abort(new DOMException('DingTalk runtime stopped', 'AbortError'));
@@ -393,6 +407,8 @@ export class DingtalkRuntime {
     this.#bridge = null;
     this.#status.dingtalkStreamState = preserveError ? 'failed' : 'idle';
     this.#status.lastError = lastError;
+    this.#status.error = publicError;
+    if (!preserveError) this.#diagnostics.clear();
     return this.status;
   }
 

package/src/channels/discord/discord-api.mjs

@@ -295,16 +295,16 @@ export class DiscordApi {
       });
     } catch (error) {
       if (error?.name === 'AbortError' || error?.name === 'TimeoutError') throw error;
-      throw new Error(`Discord ${method} transport failed`);
+      throw new Error(`Discord ${method} transport failed`, { cause: error });
     }
 
     let parsed = null;
     if (expectBody || response.status === 429 || !response.ok) {
       try {
         parsed = await response.json();
-      } catch {
+      } catch (cause) {
         if (expectBody) {
-          const error = new Error(`Discord ${method} returned invalid JSON`);
+          const error = new Error(`Discord ${method} returned invalid JSON`, { cause });
           error.status = response?.status;
           throw error;
         }

package/src/channels/discord/discord-runtime.mjs

@@ -1,3 +1,4 @@
+import { extractConnectionEvidence, createConnectionDiagnostics, atConnectionStage } from '../shared/connection-error.mjs';
 import { createEditableMessageStream, splitMessageText } from '../shared/editable-message-stream.mjs';
 import { fetchFileStream } from '../shared/file-download.mjs';
 import { fetchImageBuffer } from '../shared/image-prompt.mjs';
@@ -534,6 +535,7 @@ export class DiscordRuntime {
   #contextEnhancement;
   #accessPolicy;
   #logger;
+  #diagnostics;
   #replyTimeoutMs;
   #connectTimeoutMs;
   #createApi;
@@ -582,7 +584,7 @@ export class DiscordRuntime {
     this.#state = state;
     this.#contextEnhancement = contextEnhancement;
     this.#accessPolicy = accessPolicy;
-    this.#logger = logger;
+    this.#logger = logger; this.#diagnostics = createConnectionDiagnostics({ channel: 'discord', logger });
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#connectTimeoutMs = connectTimeoutMs;
     this.#createApi = createApi;
@@ -639,8 +641,8 @@ export class DiscordRuntime {
     this.#routing.clear();
     this.#status.startedAt = new Date().toISOString();
     this.#status.connectionState = 'connecting';
-    this.#status.lastError = null;
-    await this.#harness.ensureRunning();
+    this.#status.lastError = null; this.#status.error = null; this.#diagnostics.clear();
+    await atConnectionStage('harness.check', () => this.#harness.ensureRunning());
     this.#status.harnessReachable = true;
     const controller = new AbortController();
     this.#abortController = controller;
@@ -672,7 +674,7 @@ export class DiscordRuntime {
         await Promise.race([
           this.#openSocket(false),
           new Promise((_, reject) => {
-            timer = setTimeout(() => reject(new Error('Discord Gateway did not become ready in time')), this.#connectTimeoutMs);
+            timer = setTimeout(() => reject(Object.assign(new Error('Discord Gateway did not become ready in time'), { code: 'ETIMEDOUT', timeoutMs: this.#connectTimeoutMs })), this.#connectTimeoutMs);
           }),
         ]);
       } finally {
@@ -682,7 +684,8 @@ export class DiscordRuntime {
     } catch (error) {
       this.#status.ready = false;
       this.#status.connectionState = 'failed';
-      this.#status.lastError = error?.message ?? String(error);
+      this.#status.error = this.#diagnostics.report(error, { operation: 'connection.restore', reuse: true, botId: this.#config?.botId, automatic: true }).publicError;
+      this.#status.lastError = this.#status.error.message;
       await this.stop();
       throw error;
     }
@@ -705,7 +708,7 @@ export class DiscordRuntime {
         this.#status.connectionState = 'connected';
         this.#status.lastCheckedAt = now;
         this.#status.lastConnectedAt = now;
-        this.#status.lastError = null;
+        this.#status.lastError = null; this.#status.error = null; this.#diagnostics.clear();
         resolve();
       };
       addSocketListener(socket, 'message', (event) => {
@@ -790,7 +793,7 @@ export class DiscordRuntime {
               if (generation !== this.#generation || this.#stopped) return;
               this.#logger.error?.(
                 `[dsh-im:discord] bot ${this.#config.botId} message handling failed:`,
-                error,
+                extractConnectionEvidence(error).details,
               );
             });
           }
@@ -807,7 +810,8 @@ export class DiscordRuntime {
         const error = gatewayCloseError(Number(event.code) || 0);
         this.#status.ready = false;
         this.#status.connectionState = 'connecting';
-        this.#status.lastError = error.message;
+        this.#status.error = this.#diagnostics.report(error, { operation: 'connection.monitor', botId: this.#config?.botId, automatic: true }).publicError;
+        this.#status.lastError = this.#status.error.message;
         if (!settled) {
           settled = true;
           reject(error);
@@ -818,9 +822,11 @@ export class DiscordRuntime {
         }
         this.#scheduleReconnect();
       });
-      addSocketListener(socket, 'error', () => {
+      addSocketListener(socket, 'error', (event) => {
+        const error = event?.error ?? new Error('WebSocket error');
         if (generation !== this.#generation || this.#stopped) return;
-        this.#status.lastError = 'Discord Gateway WebSocket error';
+        this.#status.error = this.#diagnostics.report(error, { operation: 'connection.monitor', botId: this.#config?.botId, automatic: true }).publicError;
+        this.#status.lastError = this.#status.error.message;
       });
     });
   }
@@ -931,7 +937,7 @@ export class DiscordRuntime {
       this.#reconnectTimer = null;
       void this.#openSocket(Boolean(this.#sessionId)).catch((error) => {
         if (this.#stopped) return;
-        this.#logger.warn?.('[dsh-im:discord] Gateway reconnect failed:', error);
+        this.#logger.warn?.('[dsh-im:discord] Gateway reconnect failed:', extractConnectionEvidence(error).details);
         this.#scheduleReconnect();
       });
     }, delay);
@@ -955,7 +961,7 @@ export class DiscordRuntime {
     try {
       if (socket && socket.readyState < 2) socket.close(1000, 'Plugin stopped');
     } catch (error) {
-      this.#logger.warn?.(`[dsh-im:discord] bot ${this.#config.botId} failed to close Gateway:`, error);
+      this.#logger.warn?.(`[dsh-im:discord] bot ${this.#config.botId} failed to close Gateway:`, extractConnectionEvidence(error).details);
     }
     await Promise.race([
       bridge?.waitForIdle() ?? Promise.resolve(),

package/src/channels/email/config-store.mjs

@@ -0,0 +1,194 @@
+import { t } from '../shared/i18n.mjs';
+import {
+  deriveTokenBotIdentity,
+  maskPlatformId,
+  TokenBotConfigStore,
+} from '../shared/token-config-store.mjs';
+
+const IDENTITY_OPTIONS = Object.freeze({
+  botPrefix: 'email',
+  tokenRefPrefix: 'DSH_EMAIL_PASSWORD',
+});
+
+const EMAIL_ADDRESS = /^[^\s@<>]+@[^\s@<>]+\.[^\s@<>]+$/;
+const HOSTNAME = /^[a-z0-9]([a-z0-9-]*[a-z0-9])?(\.[a-z0-9]([a-z0-9-]*[a-z0-9])?)*$/i;
+
+/**
+ * How the mailbox is reached. Each value maps to one transport implementation,
+ * so adding a mail protocol adds a transport rather than another channel.
+ */
+export const EMAIL_TRANSPORTS = Object.freeze({
+  'imap-smtp': Object.freeze({
+    key: 'imap-smtp',
+    label: 'IMAP / SMTP（任意邮箱）',
+    // Needs the address plus an app password, and knows its server hosts.
+    fields: Object.freeze(['address', 'password', 'provider', 'hosts', 'allowedSenders']),
+  }),
+  'agent-mail': Object.freeze({
+    key: 'agent-mail',
+    label: '腾讯 Agent 邮箱',
+    // Authorizes by QR code, so no password and no server hosts.
+    fields: Object.freeze(['address', 'allowedSenders']),
+  }),
+});
+
+export const DEFAULT_EMAIL_TRANSPORT = 'imap-smtp';
+
+/** Normalize a transport key, defaulting to the standard IMAP/SMTP one. */
+export function normalizeEmailTransport(value) {
+  const key = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!key) return DEFAULT_EMAIL_TRANSPORT;
+  if (!Object.hasOwn(EMAIL_TRANSPORTS, key)) {
+    throw new TypeError(`Unsupported email transport: ${value}`);
+  }
+  return key;
+}
+
+/** Well-known provider presets so users do not have to know IMAP/SMTP hosts. */
+export const EMAIL_PROVIDERS = Object.freeze({
+  qq: Object.freeze({
+    key: 'qq', label: 'QQ 邮箱',
+    imapHost: 'imap.qq.com', imapPort: 993,
+    smtpHost: 'smtp.qq.com', smtpPort: 465,
+  }),
+  '163': Object.freeze({
+    key: '163', label: '163 邮箱',
+    imapHost: 'imap.163.com', imapPort: 993,
+    smtpHost: 'smtp.163.com', smtpPort: 465,
+  }),
+  gmail: Object.freeze({
+    key: 'gmail', label: 'Gmail',
+    imapHost: 'imap.gmail.com', imapPort: 993,
+    smtpHost: 'smtp.gmail.com', smtpPort: 465,
+  }),
+  custom: Object.freeze({ key: 'custom', label: '自定义' }),
+});
+
+/**
+ * Email access is allowlist-only: a mail address is trivially forgeable, so an
+ * open mailbox would let anyone drive the Harness. Unlike other channels the
+ * policy is therefore not optional — `allowedSenders` must be non-empty.
+ */
+export function normalizeEmailAllowedSenders(value) {
+  if (value === undefined) return Object.freeze([]);
+  if (!Array.isArray(value)) throw new TypeError('allowedSenders must be an array of email addresses');
+  const normalized = value.map((entry) => {
+    const address = typeof entry === 'string' ? entry.trim().toLowerCase() : '';
+    if (!EMAIL_ADDRESS.test(address)) {
+      throw new TypeError('allowedSenders contains an invalid email address');
+    }
+    return address;
+  });
+  return Object.freeze([...new Set(normalized)]);
+}
+
+export function normalizeEmailAccessPolicy(value = {}) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw new TypeError('Email access policy must be an object');
+  }
+  return Object.freeze({ allowedSenders: normalizeEmailAllowedSenders(value.allowedSenders) });
+}
+
+function normalizePort(value, fallback, label) {
+  if (value === undefined || value === null || value === '') return fallback;
+  const port = typeof value === 'number' ? value : Number.parseInt(String(value).trim(), 10);
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+    throw new TypeError(`${label} must be a valid TCP port`);
+  }
+  return port;
+}
+
+function normalizeHost(value, label) {
+  if (value === undefined || value === null || value === '') return undefined;
+  const host = String(value).trim();
+  if (!HOSTNAME.test(host)) throw new TypeError(`${label} must be a valid hostname`);
+  return host;
+}
+
+/**
+ * Channel-specific fields persisted alongside the shared token identity.
+ * Only keys the caller actually supplied are written, so a later partial save
+ * spreads over the previous record (see `save`).
+ */
+function normalizeEmailBotExtension(value) {
+  const provider = typeof value.provider === 'string' ? value.provider.trim() : undefined;
+  const present = [
+    'transport', 'provider', 'imapHost', 'imapPort', 'smtpHost', 'smtpPort',
+    'allowedSenders',
+  ];
+  if (!present.some((key) => Object.hasOwn(value, key))) return {};
+  const preset = EMAIL_PROVIDERS[provider] ?? null;
+  try {
+    const policy = normalizeEmailAccessPolicy({ allowedSenders: value.allowedSenders ?? [] });
+    const transport = Object.hasOwn(value, 'transport')
+      ? normalizeEmailTransport(value.transport)
+      : undefined;
+    return {
+      ...(transport ? { transport } : {}),
+      ...(provider ? { provider } : {}),
+      imapHost: normalizeHost(value.imapHost, 'imapHost') ?? preset?.imapHost,
+      imapPort: normalizePort(value.imapPort, preset?.imapPort ?? 993, 'imapPort'),
+      smtpHost: normalizeHost(value.smtpHost, 'smtpHost') ?? preset?.smtpHost,
+      smtpPort: normalizePort(value.smtpPort, preset?.smtpPort ?? 465, 'smtpPort'),
+      allowedSenders: policy.allowedSenders,
+    };
+  } catch {
+    return null;
+  }
+}
+
+export function deriveEmailBotIdentity(address) {
+  return deriveTokenBotIdentity(address, IDENTITY_OPTIONS);
+}
+
+export function maskEmailBotId(address) {
+  const value = String(address ?? '');
+  const at = value.indexOf('@');
+  if (at <= 0) return maskPlatformId(value, t('邮箱'));
+  const name = value.slice(0, at);
+  const domain = value.slice(at);
+  const head = name.slice(0, Math.min(2, name.length));
+  return `${head}${'*'.repeat(Math.max(1, name.length - head.length))}${domain}`;
+}
+
+/**
+ * The mailbox address is the platform identity; the password lives in the
+ * credential store behind `tokenRef`.
+ */
+export function normalizeEmailAddress(value) {
+  const address = typeof value === 'string' ? value.trim().toLowerCase() : '';
+  if (!EMAIL_ADDRESS.test(address)) throw new TypeError(t('邮箱地址格式不正确'));
+  return address;
+}
+
+export const EMAIL_CLIENT_DEFAULTS = Object.freeze({
+  mailbox: 'INBOX',
+  pollIntervalMs: 20_000,
+});
+
+
+export class EmailConfigStore extends TokenBotConfigStore {
+  constructor(path) {
+    super(path, {
+      channel: 'Email',
+      ...IDENTITY_OPTIONS,
+      normalizeBotExtension: normalizeEmailBotExtension,
+    });
+  }
+
+  async save(value) {
+    // Merge over the stored record so a settings dialog can patch one field
+    // without resending hosts and the allowlist. The bot id and credential ref
+    // are derived from the address here, so callers only supply the mailbox.
+    const previous = value?.platformId ? this.getByPlatformId(String(value.platformId)) : null;
+    const merged = { ...previous, ...value };
+    const platformId = typeof merged.platformId === 'string' ? merged.platformId.trim().toLowerCase() : '';
+    if (platformId) {
+      const identity = deriveEmailBotIdentity(platformId);
+      merged.botId = identity.botId;
+      merged.tokenRef = identity.tokenRef;
+      merged.name = merged.name || platformId;
+    }
+    return super.save(merged);
+  }
+}