@xmanrui/dsh-im 4.22.0 → 4.24.0

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

@@ -1,6 +1,7 @@
+import { extractConnectionEvidence, createConnectionDiagnostics, atConnectionStage } from '../shared/connection-error.mjs';
 import { randomInt } from 'node:crypto';
 
-import { createEditableMessageStream, splitMessageText } from '../shared/editable-message-stream.mjs';
+import { createEditableMessageStream } from '../shared/editable-message-stream.mjs';
 import { createTextDeliveryBlock } from '../shared/semantic/delivery.mjs';
 import { t } from '../shared/i18n.mjs';
 import { captureContextEnhancement } from '../shared/context-enhancement.mjs';
@@ -451,7 +452,7 @@ class TelegramDeliveryStream {
       try {
         return await this.#update(block);
       } catch (error) {
-        this.#logger.warn?.('[dsh-im:telegram] rich stream update failed:', error);
+        this.#logger.warn?.('[dsh-im:telegram] rich stream update failed:', extractConnectionEvidence(error).details);
         return undefined;
       }
     });
@@ -467,7 +468,7 @@ class TelegramDeliveryStream {
       try {
         return await this.#update(this.#lastBlock);
       } catch (error) {
-        this.#logger.warn?.('[dsh-im:telegram] rich stream refresh failed:', error);
+        this.#logger.warn?.('[dsh-im:telegram] rich stream refresh failed:', extractConnectionEvidence(error).details);
         return undefined;
       }
     });
@@ -498,6 +499,65 @@ class TelegramDeliveryStream {
   }
 }
 
+// Thinking-trace display rules. Truncation fallback (spoiler / inline-button
+// expansion are follow-ups gated on three-platform client verification):
+// tool traces cap the argument summary, reasoning caps the first paragraph.
+const TOOL_TRACE_ARG_KEYS = Object.freeze([
+  'command', 'pattern', 'query', 'url', 'file_path', 'path', 'text', 'prompt', 'message', 'description',
+]);
+const TOOL_TRACE_SUMMARY_LIMIT = 120;
+const THINKING_LINE_LIMIT = 200;
+
+function truncateCapped(value, limit) {
+  return value.length > limit ? `${value.slice(0, limit)}…` : value;
+}
+
+/** Extract a one-line argument summary from a tool call's `arguments`. */
+export function toolTraceSummary(argumentsValue) {
+  let record = null;
+  if (argumentsValue && typeof argumentsValue === 'object' && !Array.isArray(argumentsValue)) {
+    record = argumentsValue;
+  } else if (typeof argumentsValue === 'string') {
+    const trimmed = argumentsValue.trim();
+    if (!trimmed) return null;
+    let parsed = null;
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch {
+      return truncateCapped(trimmed.replace(/\s+/g, ' ').trim(), TOOL_TRACE_SUMMARY_LIMIT);
+    }
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+      record = parsed;
+    } else {
+      return truncateCapped(trimmed.replace(/\s+/g, ' ').trim(), TOOL_TRACE_SUMMARY_LIMIT);
+    }
+  }
+  if (!record) return null;
+  for (const key of TOOL_TRACE_ARG_KEYS) {
+    const value = record[key];
+    if (typeof value === 'string' && value.trim()) {
+      return truncateCapped(value.replace(/\s+/g, ' ').trim(), TOOL_TRACE_SUMMARY_LIMIT);
+    }
+  }
+  return null;
+}
+
+/** Format one tool-trace line: `🔧 <name> → <summary>` (summary optional). */
+export function formatToolTrace(name, argumentsValue) {
+  const toolName = typeof name === 'string' && name.trim() ? name.trim() : t('工具');
+  const summary = toolTraceSummary(argumentsValue);
+  return summary ? `🔧 ${toolName} → ${summary}` : `🔧 ${toolName}`;
+}
+
+/** Format one reasoning line: `💭 <first paragraph>` (200-char cap). */
+export function formatThinkingLine(text) {
+  const trimmed = typeof text === 'string' ? text.trim() : '';
+  if (!trimmed) return null;
+  const firstParagraph = trimmed.split(/\n{2,}/)[0].trim();
+  if (!firstParagraph) return null;
+  return `💭 ${truncateCapped(firstParagraph, THINKING_LINE_LIMIT)}`;
+}
+
 export class TelegramBotClient {
   #api;
   #signal;
@@ -903,6 +963,142 @@ export class TelegramBotClient {
     });
     return stream.start();
   }
+
+  /**
+   * Thinking-trace stream: every intermediate line is a permanent, separate
+   * Telegram message (no placeholder editing), so the user watches the
+   * "think → act" chain build up. Trace lines are best-effort; the final
+   * answer must still land, falling back to plain sendText delivery.
+   */
+  openThinkingStream(target) {
+    const client = this;
+    const providerMessageIds = [];
+    let firstMessageId = null;
+    let closed = false;
+    const logger = this.#logger;
+    const warnFailure = (label, error) => {
+      logger?.warn?.(`[dsh-im:telegram] thinking stream ${label} failed:`, error);
+    };
+    const sendLine = async (text) => {
+      const message = await this.#api.sendMessage({
+        chatId: target.chatId,
+        text,
+        replyToMessageId: firstMessageId === null ? target.replyToMessageId : undefined,
+        messageThreadId: target.messageThreadId,
+        signal: this.#signal,
+      });
+      const id = message?.message_id;
+      if (Number.isSafeInteger(id)) {
+        if (firstMessageId === null) firstMessageId = id;
+        providerMessageIds.push(String(id));
+      }
+    };
+    return {
+      get messageId() {
+        return firstMessageId;
+      },
+      get providerMessageIds() {
+        return [...providerMessageIds];
+      },
+      presentation: 'telegram-thinking',
+      // The chain is made of permanent messages, but long tool runs still
+      // want the typing indicator; the bridge re-sends it every 4 seconds.
+      keepalive: true,
+      update: async () => {},
+      refresh: async () => {},
+      sendLine,
+      sendToolTrace: (name, argumentsValue) => (async () => {
+        if (closed) return;
+        try {
+          await sendLine(formatToolTrace(name, argumentsValue));
+        } catch (error) {
+          warnFailure('tool trace', error);
+        }
+      })(),
+      sendThinking: (text) => (async () => {
+        if (closed) return;
+        const line = formatThinkingLine(text);
+        if (!line) return;
+        try {
+          await sendLine(line);
+        } catch (error) {
+          warnFailure('thinking line', error);
+        }
+      })(),
+      async finish(answer) {
+        if (closed) throw new Error('Message stream is already closed');
+        closed = true;
+        const format = answer && typeof answer === 'object' && answer.format === 'markdown'
+          ? 'markdown'
+          : 'plain';
+        const text = answer && typeof answer === 'object' && typeof answer.text === 'string'
+          ? answer.text
+          : typeof answer === 'string' ? answer : '';
+        const trimmed = text.trim();
+        const answerText = trimmed || t('处理完成。');
+        // The final answer keeps the channel's normal delivery path, so a
+        // markdown answer renders rich (bold, code fences) exactly like
+        // non-trace mode; trace lines above stay plain permanent messages.
+        // Markdown goes to #sendRich in one shot: splitTelegramRichMarkdown
+        // is fence-aware, so code blocks with inner blank lines stay intact
+        // and no blank line is rewritten. A blank-line pre-split would break
+        // both: unfinished fences fall back to plain, and rejoining with a
+        // fixed separator collapses \n{3,} inside multi-line strings. Plain
+        // answers use the whitespace-preserving regular-text splitter.
+        const chunks = format === 'markdown'
+          ? [answerText]
+          : splitTelegramRegularText(answerText);
+        const remember = (ids) => {
+          for (const id of ids ?? []) {
+            if (!providerMessageIds.includes(id)) providerMessageIds.push(id);
+          }
+        };
+        for (let index = 0; index < chunks.length; index += 1) {
+          let result;
+          try {
+            result = await client.#sendRich(target, createTextDeliveryBlock(chunks[index], format));
+          } catch (error) {
+            const failure = telegramFailure(error);
+            warnFailure('final answer', error);
+            if (failure.outcome === 'unknown') {
+              return deliveryResult('telegram-thinking', providerMessageIds, 'unknown', failure.reason);
+            }
+          }
+          if (result?.deliveryOutcome === 'sent') {
+            remember(result.providerMessageIds);
+            continue;
+          }
+          if (result?.deliveryOutcome === 'unknown') {
+            // 结果未知（超时等）：可能已送达，重发会造成重复，保留 unknown 状态。
+            remember(result.providerMessageIds);
+            return deliveryResult('telegram-thinking', providerMessageIds, 'unknown', result.reason);
+          }
+          // 明确失败：该分片确认未送达。纯文本分片再走一次 plain 重发
+          // （markdown 分片的 plain 回退已在 #sendRich 内尝试过），只重发
+          // 尚未发送的尾部内容，已成功的分片不重复。
+          remember(result?.providerMessageIds);
+          if (format === 'markdown') {
+            return deliveryResult('telegram-thinking', providerMessageIds, 'failed', result.reason);
+          }
+          warnFailure('final answer chunk', new Error('chunk definitively rejected'));
+          try {
+            // Regular-text chunks already retain the original whitespace.
+            const fallback = await client.sendText(target, chunks.slice(index).join(''));
+            remember(fallback.providerMessageIds);
+            return deliveryResult('telegram-thinking', providerMessageIds);
+          } catch (error) {
+            const failure = telegramFailure(error);
+            warnFailure('final answer fallback', error);
+            return deliveryResult('telegram-thinking', providerMessageIds, failure.outcome, failure.reason);
+          }
+        }
+        return deliveryResult('telegram-thinking', providerMessageIds);
+      },
+      cancel() {
+        closed = true;
+      },
+    };
+  }
 }
 
 export function createTelegramRuntimeStatus() {
@@ -926,6 +1122,7 @@ export class TelegramRuntime {
   #contextEnhancement;
   #accessPolicy;
   #logger;
+  #diagnostics;
   #replyTimeoutMs;
   #createApi;
   #createHttpTransport;
@@ -968,7 +1165,7 @@ export class TelegramRuntime {
     this.#state = state;
     this.#contextEnhancement = contextEnhancement;
     this.#accessPolicy = accessPolicy;
-    this.#logger = logger;
+    this.#logger = logger; this.#diagnostics = createConnectionDiagnostics({ channel: 'telegram', logger });
     this.#replyTimeoutMs = replyTimeoutMs;
     this.#createApi = createApi;
     this.#createHttpTransport = createHttpTransport;
@@ -1026,8 +1223,8 @@ export class TelegramRuntime {
     this.#connecting = true;
     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();
@@ -1057,7 +1254,7 @@ export class TelegramRuntime {
       } catch (error) {
         this.#logger.warn?.(
           `[dsh-im:telegram] bot ${this.#config.botId} command menu setup failed:`,
-          error,
+          extractConnectionEvidence(error).details,
         );
       }
       const client = new TelegramBotClient({
@@ -1071,6 +1268,8 @@ export class TelegramRuntime {
         state: this.#state,
         contextEnhancement: this.#contextEnhancement,
         accessPolicy: this.#accessPolicy,
+        // Default ON; an explicit false in the bot config opts out.
+        thinkingTraces: this.#config?.thinkingTraces !== false,
         status: this.#status,
         logger: this.#logger,
         replyTimeoutMs: this.#replyTimeoutMs,
@@ -1099,7 +1298,7 @@ export class TelegramRuntime {
         } catch (error) {
           this.#logger.warn?.(
             `[dsh-im:telegram] bot ${this.#config.botId} command menu catch-up failed:`,
-            error,
+            extractConnectionEvidence(error).details,
           );
         }
       }
@@ -1108,14 +1307,16 @@ export class TelegramRuntime {
         if (controller.signal.aborted) return;
         this.#status.ready = false;
         this.#status.connectionState = 'failed';
-        this.#status.lastError = error?.message ?? String(error);
-        this.#logger.error?.(`[dsh-im:telegram] bot ${this.#config.botId} polling stopped:`, 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;
+
       });
       return this.status;
     } 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;
     } finally {
@@ -1160,7 +1361,7 @@ export class TelegramRuntime {
     } catch (error) {
       this.#logger.warn?.(
         `[dsh-im:telegram] bot ${this.#config.botId} command menu refresh failed:`,
-        error,
+        extractConnectionEvidence(error).details,
       );
       return false;
     }
@@ -1210,7 +1411,7 @@ export class TelegramRuntime {
               if (signal.aborted) return;
               this.#logger.error?.(
                 `[dsh-im:telegram] bot ${this.#config.botId} callback handling failed:`,
-                error,
+                extractConnectionEvidence(error).details,
               );
             });
           }
@@ -1230,7 +1431,7 @@ export class TelegramRuntime {
             if (signal.aborted) return;
             this.#logger.error?.(
               `[dsh-im:telegram] bot ${this.#config.botId} message handling failed:`,
-              error,
+              extractConnectionEvidence(error).details,
             );
           });
         }

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

@@ -1,3 +1,5 @@
+import { imageInputLimits } from '../shared/image-input-policy.mjs';
+import { imageDownloadLimitMessage } from '../shared/image-prompt.mjs';
 import { createDeferredDeliveryCoordinator, deferredOutcomeText } from '../shared/deferred-delivery-coordinator.mjs';
 import { generateReqId } from '@wecom/aibot-node-sdk';
 import { randomUUID } from 'node:crypto';
@@ -216,7 +218,7 @@ function imageSource(client, image) {
         throw new ImagePromptError(
           'image-too-large',
           `Enterprise WeChat image exceeds ${maxBytes} bytes`,
-          t('图片超过 5 MB，请压缩后重试。'),
+          imageDownloadLimitMessage(maxBytes),
         );
       }
       return { data, name: result?.filename };
@@ -280,12 +282,17 @@ function prefetchInboundFiles(message, signal) {
   };
 }
 
-function prefetchInboundImages(message, signal) {
+function prefetchInboundImages(message, signal, limitsPromise) {
   if (!hasInboundImages(message)) return message;
   return {
     ...message,
     images: message.images.map((source) => {
-      const download = source.load({ signal, maxBytes: MAX_IMAGE_BYTES });
+      const download = Promise.resolve(limitsPromise).then((limits) => {
+        if (message.images.length > limits.maxImages) throw new ImagePromptError(
+          'too-many-images', 'Too many inbound images',
+          t('一次最多只能处理 {maxImages} 张图片。', { maxImages: limits.maxImages }));
+        return source.load({ signal, maxBytes: limits.maxDownloadBytes });
+      });
       // The conversation queue may not consume this promise immediately. Keep
       // an attached rejection handler while preserving the original outcome.
       download.catch(() => undefined);
@@ -301,7 +308,7 @@ function prefetchInboundImages(message, signal) {
             throw new ImagePromptError(
               'image-too-large',
               `Enterprise WeChat image exceeds ${maxBytes} bytes`,
-              t('图片超过 5 MB，请压缩后重试。'),
+              imageDownloadLimitMessage(maxBytes),
             );
           }
           return result;
@@ -1060,7 +1067,8 @@ export class WecomHarnessBridge {
       if (this.#prefetchedImageCount + imageCount <= MAX_PREFETCHED_IMAGES) {
         reservedImages = imageCount;
         this.#prefetchedImageCount += reservedImages;
-        preparedMessage = prefetchInboundImages(inboundMessage, this.#signal);
+        preparedMessage = prefetchInboundImages(inboundMessage, this.#signal,
+          this.#harness.getImageInputLimits?.() ?? imageInputLimits());
       } else {
         preparedMessage = imageQueueFullMessage(inboundMessage);
       }
@@ -1356,7 +1364,7 @@ export class WecomHarnessBridge {
       }
 
       let content = hasImages || hasReply
-        ? await promptContentForInboundMessage(message, { signal: this.#signal })
+        ? await promptContentForInboundMessage(message, { signal: this.#signal, deferImages: true })
         : undefined;
       const snapshot = this.#acceptedMessageIds.get(messageId);
       let contextEnhanced = false;
@@ -1408,6 +1416,7 @@ export class WecomHarnessBridge {
           }),
           onInteractionResolved: (resolution) => this.#handleInteractionResolved(resolution),
           files: message.files,
+          images: message.images,
         },
       });
       if (batchSubmission) {

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

@@ -1,3 +1,4 @@
+import { extractConnectionEvidence, atConnectionStage, createConnectionDiagnostics } from '../shared/connection-error.mjs';
 import { randomUUID } from 'node:crypto';
 
 import { deriveWecomBotIdentity, maskWecomBotId } from './config-store.mjs';
@@ -40,6 +41,7 @@ export class WecomController {
   #createRuntime;
   #deleteState;
   #logger;
+  #diagnostics;
   #runtimes = new Map();
   #errors = new Map();
   #attempts = new Map();
@@ -74,6 +76,14 @@ export class WecomController {
     this.#createRuntime = createRuntime;
     this.#deleteState = deleteState;
     this.#logger = logger;
+    this.#diagnostics = createConnectionDiagnostics({ channel: 'wecom', 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,16 +92,16 @@ export class WecomController {
       await this.#withBotTransition(config.botId, async () => {
         const existing = this.#runtimes.get(config.botId)?.status;
         if (this.#closed || existing?.ready || existing?.wecomConnectionState === 'connecting') return;
-        const secret = await this.#resolveSecret(config.secretRef);
-        if (!secret) {
-          this.#errors.set(config.botId, safeError('missing-secret', t('企业微信机器人凭据缺失，请移除后重新扫码。')));
-          return;
-        }
         try {
+          const secret = await this.#resolveSecret(config.secretRef);
+          if (!secret) {
+            this.#errors.set(config.botId, safeError('missing-secret', t('企业微信机器人凭据缺失，请移除后重新扫码。')));
+            return;
+          }
           await this.#startRuntime(config, secret);
           this.#errors.delete(config.botId);
         } catch (error) {
-          this.#errors.set(config.botId, safeError('connection-failed', t('企业微信连接未就绪，插件会自动重试。')));
+          this.#errors.set(config.botId, this.#failure(error, 'connection-failed', t('企业微信连接未就绪，插件会自动重试。')));
           this.#logger.warn?.(`[dsh-im:wecom] bot ${config.botId} failed to initialize`);
         } finally {
           this.#touch();
@@ -137,7 +147,7 @@ export class WecomController {
       record.state = record.controller.signal.aborted ? 'cancelled' : 'failed';
       record.error = record.controller.signal.aborted
         ? safeError('cancelled', t('扫码绑定已取消。'))
-        : safeError('qr-start-failed', t('无法生成企业微信二维码，请稍后重试。'));
+        : this.#failure(error, 'qr-start-failed', t('无法生成企业微信二维码，请稍后重试。'));
       this.#finishAttempt(record);
       throw error;
     }
@@ -180,7 +190,7 @@ export class WecomController {
     await this.#withBotTransition(identity.botId, async () => {
       if (this.#closed) throw new Error('Enterprise WeChat controller is closed');
       const previousConfig = this.#configStore.getByRemoteBotId(remoteBotId);
-      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 new Error('Enterprise WeChat controller is closed');
       const config = {
         botId: identity.botId,
@@ -189,9 +199,9 @@ export class WecomController {
         createdAt: previousConfig?.createdAt ?? new Date().toISOString(),
         connectedAt: new Date().toISOString(),
       };
-      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;
@@ -234,7 +244,7 @@ export class WecomController {
         await this.#startRuntime(config, secret);
         this.#errors.delete(botId);
       } catch (error) {
-        this.#errors.set(botId, safeError('connection-failed', t('企业微信连接仍未就绪，请稍后重试。')));
+        this.#errors.set(botId, this.#failure(error, 'connection-failed', t('企业微信连接仍未就绪，请稍后重试。')));
         throw error;
       } finally {
         this.#touch();
@@ -272,28 +282,32 @@ export class WecomController {
   }
 
   async deleteBot(botId) {
+    const warnings = [];
     const config = this.#configStore.get(botId);
     if (!config) throw new Error('Unknown Enterprise WeChat bot');
     await this.#withBotTransition(botId, async () => {
-      const previous = await this.#credentials.resolve(config.secretRef).catch(() => undefined);
+      const previous = 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 (previous?.value) {
-          await this.#credentials.set(config.secretRef, previous.value).catch(() => undefined);
-          await this.#startRuntime(config, previous.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 (previous?.value) {
+            await atConnectionStage('credential.save', () => this.#credentials.set(config.secretRef, previous.value), 'credential-store').catch(() => undefined);
+            await this.#startRuntime(config, previous.value).catch(() => undefined);
+          }
+          throw new Error('Unable to remove the Enterprise WeChat bot safely.', { cause: error });
         }
-        throw new Error('Unable to remove the Enterprise WeChat bot safely.', { cause: error });
       }
-      await this.#deleteState({ botId, config }).catch((error) => {
-        this.#logger.warn?.(`[dsh-im:wecom] bot ${botId} state cleanup failed:`, error);
-      });
+      await this.#deleteState({ botId, config }).catch(error => { warnings.push(this.#diagnostics.report(error, { reuse: true, operation: 'bot.delete', stage: 'state.cleanup', resource: 'account-state', warning: true, publicError: { code: 'cleanup-failed', message: '账号已移除，但本地状态清理失败。' } }).publicError); });
       this.#errors.delete(botId);
       this.#touch();
     });
-    return this.status();
+    return { ...this.status(), ...(warnings.length ? { warnings } : {}) };
   }
 
   status() {
@@ -324,7 +338,7 @@ export class WecomController {
           messagesReplied: runtimeStatus?.messagesReplied ?? 0,
         },
         lastMessageError: publicMessageFailure(runtimeStatus?.lastMessageError),
-        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;
@@ -379,7 +393,7 @@ export class WecomController {
     } catch (error) {
       if (record.controller.signal.aborted) return;
       record.state = 'failed';
-      record.error = safeError('qr-connect-failed', t('企业微信扫码服务暂时不可用，请重新生成二维码。'));
+      record.error = this.#failure(error, 'qr-connect-failed', t('企业微信扫码服务暂时不可用，请重新生成二维码。'));
       this.#logger.warn?.('[dsh-im:wecom] QR polling failed');
       this.#finishAttempt(record);
     }
@@ -399,7 +413,7 @@ export class WecomController {
         record.error = safeError('cancelled', t('扫码绑定已取消。'));
       } else {
         record.state = 'failed';
-        record.error = safeError('activation-failed', t('企业微信已授权，但无法安全保存接入配置。'));
+        record.error = this.#failure(error, 'activation-failed', t('企业微信已授权，但无法安全保存接入配置。'));
         this.#logger.error?.('[dsh-im:wecom] provisioning failed');
       }
     } finally {
@@ -410,7 +424,7 @@ export class WecomController {
   async #activateBot(record, { remoteBotId, secret }) {
     const identity = deriveWecomBotIdentity(remoteBotId);
     const previousConfig = this.#configStore.getByRemoteBotId(remoteBotId);
-    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,
       remoteBotId,
@@ -419,10 +433,10 @@ export class WecomController {
       connectedAt: new Date().toISOString(),
     };
     return this.#withBotTransition(identity.botId, async () => {
-      await this.#credentials.set(identity.secretRef, secret);
+      await atConnectionStage('credential.save', () => this.#credentials.set(identity.secretRef, secret), 'credential-store');
       try {
         if (record.controller.signal.aborted) throw new DOMException('Cancelled', 'AbortError');
-        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,19 +448,19 @@ export class WecomController {
       } catch (error) {
         if (record.controller.signal.aborted) {
           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 {
-            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-im:wecom] cancelled bot state cleanup failed:', cleanupError);
+                this.#logger.warn?.('[dsh-im:wecom] cancelled bot state cleanup failed:', extractConnectionEvidence(cleanupError).details);
               });
             }
           }
           await this.#restoreCredential(identity.secretRef, previousSecret);
           throw error;
         }
-        this.#errors.set(identity.botId, safeError('connection-failed', t('企业微信机器人已绑定，消息连接暂未就绪。')));
+        this.#errors.set(identity.botId, this.#failure(error, 'connection-failed', t('企业微信机器人已绑定，消息连接暂未就绪。')));
         this.#logger.warn?.(`[dsh-im:wecom] bot ${identity.botId} activation connection failed`);
       }
       this.#touch();
@@ -458,7 +472,7 @@ export class WecomController {
     if (this.#closed) throw new Error('Enterprise WeChat controller is closed');
     await this.#stopRuntime(config.botId);
     if (this.#closed) throw new Error('Enterprise WeChat controller is closed');
-    const runtime = await this.#createRuntime({ botId: config.botId, config, secret });
+    const runtime = await atConnectionStage('runtime.prepare', () => this.#createRuntime({ botId: config.botId, config, secret }));
     if (!runtime || typeof runtime.start !== 'function' || typeof runtime.stop !== 'function') {
       throw new TypeError('createRuntime returned an invalid Enterprise WeChat runtime');
     }
@@ -476,18 +490,18 @@ export class WecomController {
     const runtime = this.#runtimes.get(botId);
     this.#runtimes.delete(botId);
     await runtime?.stop().catch((error) => {
-      this.#logger.warn?.(`[dsh-im:wecom] bot ${botId} failed to stop cleanly:`, error);
+      this.#logger.warn?.(`[dsh-im:wecom] bot ${botId} failed to stop cleanly:`, extractConnectionEvidence(error).details);
     });
   }
 
   async #resolveSecret(ref) {
-    const result = await this.#credentials.resolve(ref).catch(() => undefined);
+    const result = await atConnectionStage('credential.read', () => this.#credentials.resolve(ref), 'credential-store');
     return cleanString(result?.value);
   }
 
   async #restoreCredential(ref, previous) {
-    if (previous?.value) await this.#credentials.set(ref, previous.value).catch(() => undefined);
-    else await this.#credentials.unset(ref).catch(() => undefined);
+    if (previous?.value) await atConnectionStage('credential.save', () => this.#credentials.set(ref, previous.value), 'credential-store').catch(() => undefined);
+    else await atConnectionStage('credential.remove', () => this.#credentials.unset(ref), 'credential-store').catch(() => undefined);
   }
 
   #withBotTransition(botId, operation) {