@xmanrui/dsh-im 4.22.0 → 4.23.0

package/src/channels/weixin/connection-error.mjs

@@ -1,5 +1,4 @@
-import { randomUUID } from 'node:crypto';
-import packageInfo from '../../../package.json' with { type: 'json' };
+import { createConnectionDiagnostics, connectionHint } from '../shared/connection-error.mjs';
 import { t } from '../shared/i18n.mjs';
 import { CONFIG_ISSUE_LABELS, normalizeWeixinDiagnosticDetails } from './diagnostic-details.mjs';
 import { configReadErrorDetails } from '../shared/config-read-error.mjs';
@@ -73,7 +72,7 @@ const MESSAGES = Object.freeze({
 });
 
 const ownedStages = new WeakMap();
-const reportedErrors = new WeakMap();
+
 const CODE_STAGES = {
   'credential-read-failed': ['credential.read', 'credential-store'],
   'credential-save-failed': ['credential.save', 'credential-store'],
@@ -97,7 +96,7 @@ export function knownWeixinErrorCode(code) { return Object.hasOwn(MESSAGES, code
 
 /** Annotate at the operation that knows the failing resource; do not inspect exception prose. */
 export function weixinStageError(code, cause, stage) {
-  if (reportedErrors.has(cause)) return cause;
+  if (cause?.publicError) return cause;
   const error = new Error('Weixin operation failed', { cause });
   error.code = knownWeixinErrorCode(code) ? code : 'weixin-operation-failed';
   const defaults = CODE_STAGES[error.code] ?? [];
@@ -105,17 +104,6 @@ export function weixinStageError(code, cause, stage) {
   return error;
 }
 
-function chainOf(error) {
-  const chain = [];
-  const seen = new Set();
-  while (error && typeof error === 'object' && !seen.has(error) && chain.length < 4) {
-    seen.add(error);
-    chain.push(error);
-    error = error.cause;
-  }
-  return chain;
-}
-
 function hintFor(code, details) {
   if (details.rollback === 'failed' || details.rollback === 'unknown') return t('原账号状态尚未确认，请重新读取状态，并反馈诊断信息。');
   if (details.rollback === 'succeeded') return t('操作未完成，已恢复之前的本机状态。请处理上述问题后重试。');
@@ -136,84 +124,30 @@ function hintFor(code, details) {
   if (code === 'stale-token' || code === 'missing-token') return t('请移除失效接入并重新扫码绑定。');
   if (details.httpStatus === 429) return t('微信服务限流，请稍后重试。');
   if (details.httpStatus === 401 || details.httpStatus === 403) return t('访问被拒绝，请检查服务访问限制；HTTP 状态本身不能确认登录凭据已失效。');
-  if (code === 'network-error' || code === 'timeout') return t('请检查运行 DSH 的机器能否访问微信服务，然后重试。');
+  if (code === 'network-error' || code === 'timeout' || details.reason === 'multiple-causes') return connectionHint(details);
   return t('请按参考号查看 DSH 日志，并复制诊断信息反馈。');
 }
 
-export function createWeixinDiagnostics({ logger = console, now = Date.now } = {}) {
-  const recent = new Map();
-  function write(level, record) {
-    try { logger[level]?.(`[dsh-weixin] ${JSON.stringify(record)}`); } catch { /* Diagnostics must not change the operation outcome. */ }
-  }
-  function report(cause, context = {}) {
-    if (reportedErrors.has(cause)) return cause;
-    const chain = chainOf(cause);
-    const selected = chain.find(error => knownWeixinErrorCode(error.code));
-    const code = selected?.code ?? (knownWeixinErrorCode(context.code) ? context.code : 'weixin-operation-failed');
-    const staged = chain.map(error => ownedStages.get(error)).find(Boolean) ?? {};
-    const configDetails = chain.map(configReadErrorDetails).find(Boolean) ?? {};
-    const defaults = CODE_STAGES[code] ?? [];
-    const reason = chain.map(error => normalizeWeixinDiagnosticDetails({ reason: error.code }).reason).find(Boolean)
-      ?? (chain.some(error => error instanceof SyntaxError) ? 'invalid-json' : undefined);
-    const numeric = field => chain.map(error => normalizeWeixinDiagnosticDetails({ [field]: field === 'httpStatus' ? error.status : error[field] })[field]).find(value => value !== undefined);
-    const details = normalizeWeixinDiagnosticDetails({
-      ...context, ...configDetails,
-      file: { 'account-config': 'config.json', 'workspace-config': 'workspaces.json' }[configDetails.resource],
-      stage: staged.stage ?? defaults[0] ?? (code.startsWith('harness-') ? 'harness.check' : context.stage),
-      resource: staged.resource ?? defaults[1] ?? configDetails.resource ?? context.resource,
-      reason: reason ?? configDetails.reason ?? context.reason, httpStatus: numeric('httpStatus'), providerCode: numeric('providerCode'), pluginVersion: packageInfo.version,
-    });
-    const botId = /^wx_[a-f0-9]{24}$/.test(context.botId ?? '') ? context.botId : undefined;
-    const key = JSON.stringify([botId, details.operation, details.stage, code, details.reason, details.httpStatus, details.providerCode,
-      details.resource, details.file, details.field, details.issue]);
-    const previous = recent.get(key);
-    const time = now();
-    if (context.automatic && previous && time - previous.time < 60_000) {
-      previous.retries += 1;
-      const wrapped = new Error(previous.publicError.message, { cause });
-      wrapped.code = code;
-      wrapped.publicError = structuredClone(previous.publicError);
-      reportedErrors.set(wrapped, true);
-      return wrapped;
-    }
-    if (previous?.retries) write('warn', { event: 'connection-retries', referenceId: previous.publicError.details.referenceId, retries: previous.retries });
-    details.referenceId = `WX-CONN-${randomUUID().replaceAll('-', '').slice(0, 8).toUpperCase()}`;
-    details.occurredAt = new Date(time).toISOString();
-    details.hint = hintFor(code, details);
-    const message = code === 'weixin-startup-config-invalid' && details.file
-      ? t('微信配置格式错误：{file}。请查看诊断详情，修复后重启 DSH。', { file: details.file })
-      : t(MESSAGES[code], { status: details.httpStatus ?? '?' });
-    const publicError = { code, message, details };
-    const wrapped = new Error(publicError.message, { cause });
-    wrapped.code = code;
-    wrapped.publicError = publicError;
-    reportedErrors.set(wrapped, true);
-    if (context.automatic) {
-      if (recent.size >= 128) recent.delete(recent.keys().next().value);
-      recent.set(key, { time, publicError: structuredClone(publicError), retries: 0, botId });
-    }
-    write(context.warning ? 'warn' : 'error', {
-      event: context.warning ? 'connection-warning' : 'connection-failure', code, ...details,
-      ...(botId ? { botId } : {}), pluginVersion: packageInfo.version, nodeVersion: process.versions.node, platform: process.platform,
-      ...(/^WX-CONN-[A-F0-9]{8}$/.test(context.parentReferenceId ?? '') ? { parentReferenceId: context.parentReferenceId } : {}),
-      ...Object.fromEntries(['durationMs', 'timeoutMs'].filter(field => Number.isFinite(cause?.[field]) && cause[field] >= 0).map(field => [field, cause[field]])),
-    });
-    return wrapped;
-  }
-  function clear(botId) {
-    for (const [key, entry] of recent) {
-      if (botId !== undefined && entry.botId !== botId) continue;
-      if (entry.retries) write('info', { event: 'connection-retries', referenceId: entry.publicError.details.referenceId, retries: entry.retries });
-      recent.delete(key);
-    }
-  }
-  function outcome(error, rollback) {
-    if (!reportedErrors.has(error)) return;
-    const details = normalizeWeixinDiagnosticDetails({ rollback });
-    if (!details.rollback) return;
-    error.publicError.details.rollback = details.rollback;
-    error.publicError.details.hint = hintFor(error.code, error.publicError.details);
-    write('info', { event: 'connection-outcome', referenceId: error.publicError.details.referenceId, ...details });
-  }
-  return { report, clear, outcome };
+export function createWeixinDiagnostics(options = {}) {
+  return createConnectionDiagnostics({ ...options, channel: 'weixin', prefix: 'WX-CONN',
+    describe(cause, context, evidence) {
+      const chain = evidence.chain;
+      const selected = chain.find(error => knownWeixinErrorCode(error.code));
+      const code = selected?.code ?? (knownWeixinErrorCode(context.code) ? context.code : 'weixin-operation-failed');
+      const staged = chain.map(error => ownedStages.get(error)).find(Boolean) ?? {};
+      const configDetails = chain.map(configReadErrorDetails).find(Boolean) ?? {};
+      const defaults = CODE_STAGES[code] ?? [];
+      const details = normalizeWeixinDiagnosticDetails({
+        ...context, ...evidence.details, ...configDetails,
+        file: { 'account-config': 'config.json', 'workspace-config': 'workspaces.json' }[configDetails.resource],
+        stage: staged.stage ?? defaults[0] ?? (code.startsWith('harness-') ? 'harness.check' : context.stage),
+        resource: staged.resource ?? defaults[1] ?? configDetails.resource ?? context.resource,
+        reason: evidence.details.reason === 'unknown' ? configDetails.reason ?? context.reason ?? 'unknown' : evidence.details.reason,
+      });
+      const message = code === 'weixin-startup-config-invalid' && details.file
+        ? t('微信配置格式错误：{file}。请查看诊断详情，修复后重启 DSH。', { file: details.file })
+        : t(MESSAGES[code], { status: details.httpStatus ?? '?' });
+      return { publicError: { code, message }, details, hint: hintFor(code, details) };
+    },
+  });
 }

package/src/channels/weixin/diagnostic-details.mjs

@@ -1,63 +1 @@
-// Shared by Host and Client: only explicitly admitted diagnostic facts cross the UI boundary.
-const OPERATIONS = new Set([
-  'startup', 'connection.restore', 'connection.monitor', 'connection.close', 'connection.status',
-  'provision.begin', 'provision.poll', 'provision.verify', 'provision.cancel', 'bot.reconnect', 'bot.delete',
-  'bot.workspace.set', 'bot.model.set', 'bot.agent-preset.set', 'bot.context-enhancement.set', 'bot.access-policy.set', 'bot.alias.set',
-]);
-const STAGES = new Set([
-  'startup.load', 'qr.begin', 'qr.encode', 'qr.poll', 'qr.verify', 'qr.cancel', 'credential.read', 'credential.save', 'credential.remove',
-  'account.save', 'account.remove', 'state.load', 'state.write', 'state.cleanup', 'workspace.write', 'workspace.cleanup',
-  'runtime.prepare', 'activation', 'harness.check', 'connection.start', 'connection.poll', 'connection.stop', 'status.read', 'rollback', 'management.request',
-]);
-const REASONS = new Set([
-  'ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'ETIMEDOUT', 'EPIPE',
-  'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'UND_ERR_SOCKET',
-  'CERT_HAS_EXPIRED', 'CERT_NOT_YET_VALID', 'DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN',
-  'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'ERR_TLS_CERT_ALTNAME_INVALID', 'ERR_SSL_WRONG_VERSION_NUMBER',
-  'ENOENT', 'EACCES', 'EPERM', 'ENOSPC', 'EROFS', 'ENOTDIR', 'EISDIR', 'EBUSY', 'EIO', 'EXDEV', 'EMFILE', 'ENFILE', 'EEXIST',
-  'invalid-json', 'invalid-config', 'read-only',
-]);
-const RESOURCES = new Set(['credential-store', 'account-config', 'account-state', 'workspace-config', 'workspace-directory']);
-const CONFIG_FILES = new Set(['config.json', 'workspaces.json']);
-export const CONFIG_ISSUE_LABELS = Object.freeze({
-  'expected-object': '应为 JSON 对象。',
-  'expected-array': '应为 JSON 数组。',
-  'unsupported-version': '配置版本缺失或不受当前插件支持。',
-  'invalid-string': '字段缺失或不是非空字符串。',
-  'invalid-identifier': '标识符格式不符合要求。',
-  'identity-mismatch': '标识符与 accountId 派生结果不一致。',
-  'duplicate-identity': '账号标识重复。',
-  'invalid-api-url': '微信服务地址不是有效 URL。',
-  'untrusted-api-url': '微信服务地址必须使用受信任的 HTTPS 域名和端口。',
-  'invalid-workspace-path': '工作区路径必须是当前操作系统的绝对路径。',
-  'invalid-agent-preset': 'Agent Preset 标识无效。',
-  'invalid-model-selection': '模型设置须包含有效的 provider、model 和可选 reasoningEffort。',
-  'invalid-delivery-target': '投递目标的标识、结构或路由不符合当前配置版本要求。',
-  'unexpected-field': '当前配置版本不允许此字段。',
-});
-// Only schema-owned field names and numeric entry positions may leave the Host.
-// Map keys are replaced with zero-based positions to avoid exposing identities.
-const CONFIG_FIELD = /^(?:\$|version|accounts(?:\[\d{1,10}\](?:\.(?:accountId|ownerUserId|botId|tokenRef|baseUrl))?)?|(?:workspaces|agentPresets|models)(?:\[\d{1,10}\]\.(?:key|value))?|deliveryTargets(?:\[\d{1,10}\]\.(?:key|targets(?:\[\d{1,10}\])?))?)$/;
-
-export function normalizeWeixinDiagnosticDetails(value) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
-  const result = {};
-  for (const [field, allowed] of [['operation', OPERATIONS], ['stage', STAGES], ['reason', REASONS], ['resource', RESOURCES]]) {
-    if (allowed.has(value[field])) result[field] = value[field];
-  }
-  if (CONFIG_FILES.has(value.file)) result.file = value.file;
-  if (typeof value.field === 'string' && CONFIG_FIELD.test(value.field)) result.field = value.field;
-  if (typeof value.issue === 'string' && Object.hasOwn(CONFIG_ISSUE_LABELS, value.issue)) result.issue = value.issue;
-  if (/^WX-CONN-[A-F0-9]{8}$/.test(value.referenceId ?? '')) result.referenceId = value.referenceId;
-  if (typeof value.occurredAt === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value.occurredAt)
-    && Number.isFinite(Date.parse(value.occurredAt))) result.occurredAt = value.occurredAt;
-  if (Number.isInteger(value.httpStatus) && value.httpStatus >= 100 && value.httpStatus <= 599) result.httpStatus = value.httpStatus;
-  const provider = typeof value.providerCode === 'number' && Number.isSafeInteger(value.providerCode)
-    ? String(value.providerCode) : value.providerCode;
-  if (typeof provider === 'string' && /^-?\d{1,12}$/.test(provider)) result.providerCode = provider;
-  if (typeof value.pluginVersion === 'string' && /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value.pluginVersion)
-    && value.pluginVersion.length <= 64) result.pluginVersion = value.pluginVersion;
-  if (['succeeded', 'failed', 'not-attempted', 'unknown'].includes(value.rollback)) result.rollback = value.rollback;
-  if (typeof value.hint === 'string' && value.hint.trim()) result.hint = value.hint.trim().slice(0, 500);
-  return result;
-}
+export { CONFIG_ISSUE_LABELS, normalizeDiagnosticDetails as normalizeWeixinDiagnosticDetails } from '../shared/diagnostic-details.mjs';

package/src/channels/weixin/weixin-bridge.mjs

@@ -63,6 +63,7 @@ import {
 } from '../shared/semantic/delivery.mjs';
 import { recoverAssistantTextByTimestamp } from '../shared/session-reply-recovery.mjs';
 import {
+  messageFailureDiagnostic,
   channelDeliveryFailure,
   clearLastMessageFailure,
   messageFailureText,
@@ -467,7 +468,7 @@ export class WeixinHarnessBridge {
         const failure = setLastMessageFailure(this.#status, error);
         this.#logger.error?.(
           `[dsh-weixin] failed to process a command [${failure.referenceId}]:`,
-          error,
+          messageFailureDiagnostic(error, failure),
         );
         return this.#sendOutOfBand(key, sender, messageFailureText(failure), contextToken, runId)
           .catch(() => undefined);
@@ -623,7 +624,7 @@ export class WeixinHarnessBridge {
       const failure = setLastMessageFailure(this.#status, error);
       this.#logger.error?.(
         `[dsh-weixin] failed to process a batch input message [${failure.referenceId}]:`,
-        error,
+        messageFailureDiagnostic(error, failure),
       );
       await this.#sendOutOfBand(key, sender, messageFailureText(failure), contextToken, runId)
         .catch(() => undefined);
@@ -814,7 +815,7 @@ export class WeixinHarnessBridge {
       await this.#startTyping(sender, contextToken);
       try {
         let content = hasImages || hasReply
-          ? await promptContentForInboundMessage(promptMessage, { signal: this.#signal })
+          ? await promptContentForInboundMessage(promptMessage, { signal: this.#signal, deferImages: true })
           : undefined;
         const snapshot = this.#acceptedMessageIds.get(messageId);
         let contextEnhanced = false;
@@ -857,6 +858,7 @@ export class WeixinHarnessBridge {
               await this.#resumeTyping(key, sender, contextToken);
             },
             files: promptMessage.files,
+            images: promptMessage.images,
           },
         }));
         if (batchSubmission) {
@@ -934,7 +936,7 @@ export class WeixinHarnessBridge {
       });
       this.#logger.error?.(
         `[dsh-weixin] failed to process an inbound message [${failure.referenceId}]:`,
-        error,
+        messageFailureDiagnostic(error, failure),
       );
       try {
         await this.#send(
@@ -1251,7 +1253,7 @@ export class WeixinHarnessBridge {
     const failure = setLastMessageFailure(this.#status, error);
     this.#logger.error?.(
       `[dsh-weixin] failed to process an interaction reply [${failure.referenceId}]:`,
-      error,
+      messageFailureDiagnostic(error, failure),
     );
     if (!this.#state.hasSeen(messageId)) {
       await this.#state.markSeen(messageId).catch(() => undefined);

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

@@ -1,3 +1,4 @@
+import { extractConnectionEvidence, atConnectionStage, createConnectionDiagnostics } from '../shared/connection-error.mjs';
 import { randomUUID } from 'node:crypto';
 
 import { connectionTestMessage } from '../shared/connection-test.mjs';
@@ -39,6 +40,7 @@ export class WhatsappController {
   #deleteAuth;
   #deleteState;
   #logger;
+  #diagnostics;
   #runtimes = new Map();
   #errors = new Map();
   #attempts = new Map();
@@ -71,6 +73,14 @@ export class WhatsappController {
     this.#deleteAuth = deleteAuth;
     this.#deleteState = deleteState;
     this.#logger = logger;
+    this.#diagnostics = createConnectionDiagnostics({ channel: 'whatsapp', logger });
+  }
+
+  get diagnostics() { return this.#diagnostics; }
+
+  #failure(error, code, message) {
+    const stage = code.startsWith('qr-') ? 'qr.begin' : code === 'activation-failed' ? 'activation' : 'connection.start';
+    return this.#diagnostics.report(error, { reuse: true, stage, publicError: { code, message } }).publicError;
   }
 
   async initialize() {
@@ -82,7 +92,7 @@ export class WhatsappController {
           await this.#startRuntime(config);
           this.#errors.delete(config.botId);
         } catch (error) {
-          this.#errors.set(config.botId, safeError(
+          this.#errors.set(config.botId, this.#failure(error,
             error?.code === 'relink-required' ? 'relink-required' : 'connection-failed',
             error?.code === 'relink-required'
               ? t('WhatsApp 关联设备已失效，请移除后重新扫码。')
@@ -191,7 +201,7 @@ export class WhatsappController {
         await this.#startRuntime(config);
         this.#errors.delete(botId);
       } catch (error) {
-        this.#errors.set(botId, safeError(
+        this.#errors.set(botId, this.#failure(error,
           error?.code === 'relink-required' ? 'relink-required' : 'connection-failed',
           error?.code === 'relink-required'
             ? t('WhatsApp 关联设备已失效，请移除后重新扫码。')
@@ -245,7 +255,7 @@ export class WhatsappController {
       if (this.#closed) throw new Error('WhatsApp controller is closed');
       const config = this.#configStore.get(botId);
       if (!config) throw new Error('Unknown WhatsApp bot');
-      const saved = await this.#configStore.save({ ...config, ...accessPolicy });
+      const saved = await atConnectionStage('account.save', () => this.#configStore.save({ ...config, ...accessPolicy }), 'account-config');
       this.#runtimes.get(botId)?.setAccessPolicy?.(saved);
       this.#touch();
     });
@@ -253,24 +263,31 @@ export class WhatsappController {
   }
 
   async deleteBot(botId) {
+    const warnings = [];
     const config = this.#configStore.get(botId);
     if (!config) throw new Error('Unknown WhatsApp bot');
     await this.#withBotTransition(botId, async () => {
       await this.#stopRuntime(botId);
       try {
-        await this.#configStore.remove(botId);
+        await atConnectionStage('account.remove', () => this.#configStore.remove(botId), 'account-config');
       } catch (error) {
-        await this.#startRuntime(config).catch(() => undefined);
-        throw error;
+        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 {
+          await this.#startRuntime(config).catch(() => undefined);
+          throw error;
+        }
       }
-      await Promise.allSettled([
+      const cleanup = await Promise.allSettled([
         this.#deleteAuth(config.authDirectory),
         this.#deleteState({ botId, config }),
       ]);
+      for (const result of cleanup) if (result.status === 'rejected') warnings.push(this.#diagnostics.report(result.reason, { 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 } : {}) };
   }
 
   status() {
@@ -302,7 +319,7 @@ export class WhatsappController {
         },
         lastMessageError: publicMessageFailure(runtimeStatus?.lastMessageError),
         accessPolicy: normalizeWhatsappAccessPolicy(config),
-        error: structuredClone(this.#errors.get(config.botId) ?? null),
+        error: structuredClone(runtimeStatus?.error ?? this.#errors.get(config.botId) ?? null),
       };
     });
     const connectedCount = bots.filter((bot) => bot.connected).length;
@@ -351,13 +368,13 @@ export class WhatsappController {
     };
     try {
       if (record.controller.signal.aborted || this.#closed) throw Object.assign(new Error(), { name: 'AbortError' });
-      await this.#configStore.save(config);
+      await atConnectionStage('account.save', () => this.#configStore.save(config), 'account-config');
       if (record.controller.signal.aborted || this.#closed) throw Object.assign(new Error(), { name: 'AbortError' });
       try {
         await this.#startRuntime(config);
         this.#errors.delete(botId);
       } catch (error) {
-        this.#errors.set(botId, safeError('connection-failed', t('WhatsApp 已绑定，消息连接暂未就绪。')));
+        this.#errors.set(botId, this.#failure(error, 'connection-failed', t('WhatsApp 已绑定，消息连接暂未就绪。')));
         this.#logger.warn?.(`[dsh-im:whatsapp] bot ${botId} did not reconnect after QR binding`);
       }
       if (previous?.authDirectory && previous.authDirectory !== config.authDirectory) {
@@ -368,12 +385,12 @@ export class WhatsappController {
     } catch (error) {
       if (record.controller.signal.aborted || this.#closed || error?.name === 'AbortError') {
         await this.#stopRuntime(botId);
-        if (previous) await this.#configStore.save(previous).catch(() => undefined);
+        if (previous) await atConnectionStage('account.save', () => this.#configStore.save(previous), 'account-config').catch(() => undefined);
         else {
-          const removed = await this.#configStore.remove(botId).catch(() => null);
+          const removed = await atConnectionStage('account.remove', () => this.#configStore.remove(botId), 'account-config').catch(() => null);
           if (removed) {
             await this.#deleteState({ botId, config }).catch((cleanupError) => {
-              this.#logger.warn?.('[dsh-im:whatsapp] cancelled bot state cleanup failed:', cleanupError);
+              this.#logger.warn?.('[dsh-im:whatsapp] cancelled bot state cleanup failed:', extractConnectionEvidence(cleanupError).details);
             });
           }
         }
@@ -384,7 +401,7 @@ export class WhatsappController {
       } else {
         await this.#deleteAuth(record.authDirectory).catch(() => undefined);
         record.state = 'failed';
-        record.error = safeError('activation-failed', t('WhatsApp 已扫码，但无法保存关联设备。'));
+        record.error = this.#failure(error, 'activation-failed', t('WhatsApp 已扫码，但无法保存关联设备。'));
         this.#logger.error?.('[dsh-im:whatsapp] unable to persist linked-device session');
       }
     } finally {
@@ -413,11 +430,11 @@ export class WhatsappController {
     if (this.#closed) throw new Error('WhatsApp controller is closed');
     await this.#stopRuntime(config.botId);
     if (this.#closed) throw new Error('WhatsApp controller is closed');
-    const runtime = await this.#createRuntime({
+    const runtime = await atConnectionStage('runtime.prepare', () => this.#createRuntime({
       botId: config.botId,
       config,
       authDir: this.#authPath(config.authDirectory),
-    });
+    }));
     if (!runtime || typeof runtime.start !== 'function' || typeof runtime.stop !== 'function') {
       throw new TypeError('createRuntime returned an invalid WhatsApp runtime');
     }

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

@@ -1,9 +1,11 @@
+import { createConnectionDiagnostics, atConnectionStage } from '../shared/connection-error.mjs';
 import { createHash, randomBytes } from 'node:crypto';
 
 import {
   areJidsSameUser,
   downloadMediaMessage,
   jidDecode,
+  jidNormalizedUser,
   normalizeMessageContent,
 } from '@whiskeysockets/baileys';
 
@@ -14,6 +16,7 @@ import { trackOutboundArtifactProviderPromise } from '../shared/semantic/artifac
 import { createWhatsappBridgeStatus, WhatsappHarnessBridge } from './whatsapp-bridge.mjs';
 import {
   WHATSAPP_ACCESS_MODES,
+  normalizeWhatsappAccountJid,
 } from './config-store.mjs';
 import { createWhatsappWebSession } from './whatsapp-web-session.mjs';
 
@@ -289,8 +292,22 @@ export function createWhatsappMediaDownloader({
   });
 }
 
+function whatsappAccountMatcher(accountJid, aliases) {
+  // PN and LID are separate identities unless the linked account supplies both.
+  const accountJids = new Set(
+    [accountJid, ...(Array.isArray(aliases) ? aliases : [])]
+      .map((jid) => normalizeWhatsappAccountJid(jidNormalizedUser(jid)))
+      .filter(Boolean),
+  );
+  return (jid) => {
+    const normalized = normalizeWhatsappAccountJid(jidNormalizedUser(jid));
+    return normalized !== null && accountJids.has(normalized);
+  };
+}
+
 export function normalizeWhatsappMessage(message, accountJid, {
   download = downloadMediaMessage,
+  accountAliases = [],
 } = {}) {
   const remoteJid = typeof message?.key?.remoteJid === 'string' ? message.key.remoteJid : '';
   const alternateRemoteJid = typeof message?.key?.remoteJidAlt === 'string'
@@ -300,8 +317,9 @@ export function normalizeWhatsappMessage(message, accountJid, {
     || remoteJid.endsWith('@newsletter')) return null;
   const group = remoteJid.endsWith('@g.us');
   const fromMe = message.key.fromMe === true;
+  const matchesAccount = whatsappAccountMatcher(accountJid, accountAliases);
   const selfChat = fromMe && !group
-    && [remoteJid, alternateRemoteJid].some((jid) => jid && areJidsSameUser(jid, accountJid));
+    && [remoteJid, alternateRemoteJid].some(matchesAccount);
   if (fromMe && !selfChat && !group) return null;
   const senderJid = fromMe ? accountJid : group ? message.key.participant : remoteJid;
   const senderAlternateJid = group && !fromMe ? message.key.participantAlt : alternateRemoteJid;
@@ -310,9 +328,9 @@ export function normalizeWhatsappMessage(message, accountJid, {
   const content = normalizeMessageContent(message.message);
   const context = messageContext(content);
   const mentioned = Array.isArray(context?.mentionedJid)
-    && context.mentionedJid.some((jid) => areJidsSameUser(jid, accountJid));
+    && context.mentionedJid.some(matchesAccount);
   const replyToSelf = typeof context?.participant === 'string'
-    && areJidsSameUser(context.participant, accountJid);
+    && matchesAccount(context.participant);
   const image = whatsappImageSource(message, content, download, { viewOnce });
   const file = whatsappFileSource(message, content, download);
   const replyTo = whatsappReplyReference(context);
@@ -677,6 +695,7 @@ export class WhatsappRuntime {
   #contextEnhancement;
   #accessPolicy;
   #logger;
+  #diagnostics;
   #replyTimeoutMs;
   #connectTimeoutMs;
   #mediaUploadTimeoutMs;
@@ -710,7 +729,7 @@ export class WhatsappRuntime {
     this.#state = state;
     this.#contextEnhancement = contextEnhancement;
     this.#accessPolicy = accessPolicy;
-    this.#logger = logger;
+    this.#logger = logger; this.#diagnostics = createConnectionDiagnostics({ channel: 'whatsapp', logger });
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#connectTimeoutMs = connectTimeoutMs;
     if (!Number.isSafeInteger(mediaUploadTimeoutMs) || mediaUploadTimeoutMs <= 0) {
@@ -738,8 +757,8 @@ export class WhatsappRuntime {
     await this.stop();
     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;
@@ -757,7 +776,13 @@ export class WhatsappRuntime {
           { code: 'relink-required' },
         )),
         onMessage: async (raw, context) => {
+          const linkedAccount = context?.socket?.user;
           const message = normalizeWhatsappMessage(raw, this.#config.accountJid, {
+            accountAliases: [
+              linkedAccount?.id,
+              linkedAccount?.lid,
+              linkedAccount?.phoneNumber,
+            ],
             download: createWhatsappMediaDownloader({
               socket: context?.socket,
               logger: this.#logger,
@@ -771,7 +796,8 @@ export class WhatsappRuntime {
           if (controller.signal.aborted) return;
           this.#status.ready = false;
           this.#status.connectionState = 'failed';
-          this.#status.lastError = error?.message ?? 'WhatsApp Web connection closed';
+          this.#status.error = this.#diagnostics.report(error, { operation: 'connection.monitor', botId: this.#config?.botId, automatic: true }).publicError;
+          this.#status.lastError = this.#status.error.message;
         },
       });
       this.#session = session;
@@ -822,7 +848,8 @@ export class WhatsappRuntime {
     } 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.monitor', botId: this.#config?.botId, automatic: true }).publicError;
+      this.#status.lastError = this.#status.error.message;
       await this.stop();
       throw error;
     }