@xmanrui/dsh-im 4.21.2 → 4.23.0

package/src/channels/feishu/multi-bot-controller.mjs

@@ -1,3 +1,4 @@
+import { atConnectionStage, createConnectionDiagnostics } from '../shared/connection-error.mjs';
 import { randomUUID } from 'node:crypto';
 import { connectionTestMessage } from '../shared/connection-test.mjs';
 import { publicMessageFailure } from '../shared/message-failure.mjs';
@@ -115,6 +116,7 @@ function optionalNonEmptyString(value) {
  * runtime lifecycles may proceed independently.
  */
 export class MultiBotDshFeishuController {
+  #diagnostics;
   #registerApp;
   #verifyApp;
   #credentials;
@@ -138,6 +140,7 @@ export class MultiBotDshFeishuController {
   constructor({
     registerApp,
     verifyApp,
+    logger = console,
     credentials,
     configStore,
     createRuntime,
@@ -159,6 +162,7 @@ export class MultiBotDshFeishuController {
       || callbackProbeTimeoutMs > MAX_CALLBACK_PROBE_TIMEOUT_MS) {
       throw new TypeError('callbackProbeTimeoutMs must be between 1 and 600000ms');
     }
+    this.#diagnostics = createConnectionDiagnostics({ channel: 'feishu', logger });
     this.#registerApp = registerApp;
     this.#verifyApp = verifyApp;
     this.#credentials = credentials;
@@ -191,12 +195,12 @@ export class MultiBotDshFeishuController {
       }
       let resolved;
       try {
-        resolved = await this.#credentials.resolve(config.secretRef);
-      } catch {
-        this.#botErrors.set(config.id, {
+        resolved = await atConnectionStage('credential.read', () => this.#credentials.resolve(config.secretRef), 'credential-store');
+      } catch (error) {
+        this.#botErrors.set(config.id, this.#diagnostics.report(error, { reuse: true, botId: config.id, publicError: {
           code: 'missing_credentials',
           message: '无法读取机器人凭据，请检查凭据存储。',
-        });
+        } }).publicError);
         return;
       }
       if (!resolved?.value) {
@@ -209,11 +213,11 @@ export class MultiBotDshFeishuController {
       try {
         await this.#startRuntime(config, resolved.value);
         this.#botErrors.delete(config.id);
-      } catch {
-        this.#botErrors.set(config.id, {
+      } catch (error) {
+        this.#botErrors.set(config.id, this.#diagnostics.report(error, { reuse: true, botId: config.id, stage: 'connection.start', publicError: {
           code: 'connection_failed',
           message: '机器人暂时无法连接飞书，请重试。',
-        });
+        } }).publicError);
       }
     })));
     if (attempted) this.#touch();
@@ -228,6 +232,7 @@ export class MultiBotDshFeishuController {
     }
     const record = { id, manager: null, botId: null, createdNew: false, cancelled: false };
     record.manager = new RegistrationManager({
+      diagnostics: this.#diagnostics,
       registerApp: this.#registerApp,
       onCredentials: (result) => this.#serializeConfig(() => this.#acceptCredentials(record, result)),
     });
@@ -290,6 +295,7 @@ export class MultiBotDshFeishuController {
       },
     };
     record.manager = new CallbackRepairManager({
+      diagnostics: this.#diagnostics,
       registerApp: this.#registerApp,
       appId: target.appId,
       domain: target.domain,
@@ -349,6 +355,7 @@ export class MultiBotDshFeishuController {
       initiator: { actorOpenId: null, chatId: null },
     };
     record.manager = new GroupMessagePermissionManager({
+      diagnostics: this.#diagnostics,
       registerApp: this.#registerApp,
       appId: target.appId,
       domain: target.domain,
@@ -407,6 +414,8 @@ export class MultiBotDshFeishuController {
     return this.registrationStatus(attemptId) ?? this.status();
   }
 
+  get diagnostics() { return this.#diagnostics; }
+
   status(botId) {
     return this.#status({
       registration: this.#registrations.get(this.#latestRegistrationId) ?? null,
@@ -440,7 +449,7 @@ export class MultiBotDshFeishuController {
         throw new Error('Bot id generator returned an invalid or duplicate id');
       }
       const secretRef = existing?.secretRef ?? secretRefFor(botId);
-      const previousSecret = await this.#credentials.resolve(secretRef).catch(() => undefined);
+      const previousSecret = await atConnectionStage('credential.read', () => this.#credentials.resolve(secretRef), 'credential-store').catch(() => undefined);
       const config = {
         ...existing,
         id: botId,
@@ -460,7 +469,7 @@ export class MultiBotDshFeishuController {
         createdAt: existing?.createdAt ?? new Date().toISOString(),
       };
 
-      await this.#credentials.set(secretRef, normalizedSecret);
+      await atConnectionStage('credential.save', () => this.#credentials.set(secretRef, normalizedSecret), 'credential-store');
       let saved;
       try {
         saved = await this.#configStore.saveBot(config);
@@ -473,11 +482,11 @@ export class MultiBotDshFeishuController {
         try {
           await this.#startRuntime(saved, normalizedSecret);
           this.#botErrors.delete(botId);
-        } catch {
-          this.#botErrors.set(botId, {
+        } catch (error) {
+          this.#botErrors.set(botId, this.#diagnostics.report(error, { reuse: true, botId: botId, publicError: {
             code: 'connection_failed',
             message: '机器人已经绑定，但长连接未就绪，请点击重试。',
-          });
+          } }).publicError);
         }
       });
       this.#touch();
@@ -501,8 +510,8 @@ export class MultiBotDshFeishuController {
       }
       let resolved;
       try {
-        resolved = await this.#credentials.resolve(config.secretRef);
-      } catch {
+        resolved = await atConnectionStage('credential.read', () => this.#credentials.resolve(config.secretRef), 'credential-store');
+      } catch (error) {
         resolved = null;
       }
       if (!resolved?.value) {
@@ -516,11 +525,11 @@ export class MultiBotDshFeishuController {
       try {
         await this.#startRuntime(config, resolved.value);
         this.#botErrors.delete(botId);
-      } catch {
-        this.#botErrors.set(botId, {
+      } catch (error) {
+        this.#botErrors.set(botId, this.#diagnostics.report(error, { reuse: true, botId: botId, stage: 'connection.start', publicError: {
           code: 'connection_failed',
           message: '机器人暂时无法连接飞书，请重试。',
-        });
+        } }).publicError);
       }
       this.#touch();
       return this.status(botId);
@@ -691,7 +700,7 @@ export class MultiBotDshFeishuController {
     const bots = this.#configStore.list().map((config) => {
       const connection = connectionStatus(this.#runtimes.get(config.id));
       const connected = isConnected(connection);
-      const error = this.#botErrors.get(config.id) ?? null;
+      const error = connectionStatus(this.#runtimes.get(config.id)).error ?? this.#botErrors.get(config.id) ?? null;
       return {
         botId: config.id,
         phase: botPhase({ connected, error, connection }),
@@ -832,7 +841,7 @@ export class MultiBotDshFeishuController {
 
       let previous;
       try {
-        previous = await this.#credentials.resolve(current.secretRef);
+        previous = await atConnectionStage('credential.read', () => this.#credentials.resolve(current.secretRef), 'credential-store');
       } catch (error) {
         throw this.#callbackRepairError(
           record,
@@ -844,9 +853,9 @@ export class MultiBotDshFeishuController {
       if (previous?.value !== appSecret) {
         record.stage = 'persisting_secret';
         try {
-          await this.#credentials.set(current.secretRef, appSecret);
+          await atConnectionStage('credential.save', () => this.#credentials.set(current.secretRef, appSecret), 'credential-store');
         } catch (writeError) {
-          const observed = await this.#credentials.resolve(current.secretRef).catch(() => null);
+          const observed = await atConnectionStage('credential.read', () => this.#credentials.resolve(current.secretRef), 'credential-store').catch(() => null);
           if (observed?.value !== appSecret) {
             throw this.#callbackRepairError(
               record,
@@ -856,7 +865,7 @@ export class MultiBotDshFeishuController {
             );
           }
         }
-        const persisted = await this.#credentials.resolve(current.secretRef).catch(() => null);
+        const persisted = await atConnectionStage('credential.read', () => this.#credentials.resolve(current.secretRef), 'credential-store').catch(() => null);
         if (persisted?.value !== appSecret) {
           throw this.#callbackRepairError(
             record,
@@ -887,10 +896,10 @@ export class MultiBotDshFeishuController {
       try {
         await this.#startRuntime(saved, appSecret);
       } catch (error) {
-        this.#botErrors.set(record.botId, {
+        this.#botErrors.set(record.botId, this.#diagnostics.report(error, { reuse: true, botId: record.botId, stage: 'connection.start', publicError: {
           code: 'connection_failed',
           message: '群消息权限已开通，但机器人长连接未就绪，请点击重试。',
-        });
+        } }).publicError);
         this.#touch();
         throw this.#callbackRepairError(
           record,
@@ -981,7 +990,7 @@ export class MultiBotDshFeishuController {
 
         let previous;
         try {
-          previous = await this.#credentials.resolve(current.secretRef);
+          previous = await atConnectionStage('credential.read', () => this.#credentials.resolve(current.secretRef), 'credential-store');
         } catch (error) {
           throw this.#callbackRepairError(
             record,
@@ -994,9 +1003,9 @@ export class MultiBotDshFeishuController {
         if (credentialChanged) {
           record.stage = 'persisting_secret';
           try {
-            await this.#credentials.set(current.secretRef, appSecret);
+            await atConnectionStage('credential.save', () => this.#credentials.set(current.secretRef, appSecret), 'credential-store');
           } catch (writeError) {
-            const observed = await this.#credentials.resolve(current.secretRef).catch(() => null);
+            const observed = await atConnectionStage('credential.read', () => this.#credentials.resolve(current.secretRef), 'credential-store').catch(() => null);
             if (observed?.value !== appSecret) {
               throw this.#callbackRepairError(
                 record,
@@ -1006,7 +1015,7 @@ export class MultiBotDshFeishuController {
               );
             }
           }
-          const persisted = await this.#credentials.resolve(current.secretRef).catch(() => null);
+          const persisted = await atConnectionStage('credential.read', () => this.#credentials.resolve(current.secretRef), 'credential-store').catch(() => null);
           if (persisted?.value !== appSecret) {
             throw this.#callbackRepairError(
               record,
@@ -1029,10 +1038,10 @@ export class MultiBotDshFeishuController {
           // The returned credential was already verified and persisted. Do
           // not restore a potentially revoked old secret; reconnectBot can
           // safely retry this forward state later.
-          this.#botErrors.set(record.botId, {
+          this.#botErrors.set(record.botId, this.#diagnostics.report(error, { reuse: true, botId: record.botId, publicError: {
             code: 'connection_failed',
             message: '机器人回调修复已保存，但长连接未就绪，请点击重试。',
-          });
+          } }).publicError);
           this.#touch();
           throw this.#callbackRepairError(
             record,
@@ -1120,8 +1129,8 @@ export class MultiBotDshFeishuController {
     }
     const secretRef = existing?.secretRef ?? secretRefFor(botId);
     const previousOwnership = this.#botOwnership.get(botId);
-    const previousSecret = await this.#credentials.resolve(secretRef).catch(() => undefined);
-    await this.#credentials.set(secretRef, appSecret);
+    const previousSecret = await atConnectionStage('credential.read', () => this.#credentials.resolve(secretRef), 'credential-store').catch(() => undefined);
+    await atConnectionStage('credential.save', () => this.#credentials.set(secretRef, appSecret), 'credential-store');
     let config;
     try {
       config = await this.#configStore.saveBot({
@@ -1219,29 +1228,29 @@ export class MultiBotDshFeishuController {
             this.#botErrors.delete(botId);
           } else {
             await this.#withBotTransition(botId, () => this.#stopRuntime(botId));
-            this.#botErrors.set(botId, {
+            this.#botErrors.set(botId, this.#diagnostics.report(error, { reuse: true, botId: botId, publicError: {
               code: 'deletion_pending',
               message: '机器人正在等待完成本地删除，请重试移除。',
-            });
+            } }).publicError);
           }
           this.#touch();
           throw error;
         } catch (restoreError) {
           if (restoreError === error) throw error;
-          this.#botErrors.set(botId, {
+          this.#botErrors.set(botId, this.#diagnostics.report(restoreError, { reuse: true, botId: botId, publicError: {
             code: 'connection_failed',
             message: '机器人连接更新失败，且原连接无法恢复，请重试。',
-          });
+          } }).publicError);
           this.#touch();
           throw new Error('Unable to restore the previous Feishu bot connection.', {
             cause: restoreError,
           });
         }
       }
-      this.#botErrors.set(botId, {
+      this.#botErrors.set(botId, this.#diagnostics.report(error, { reuse: true, botId: botId, publicError: {
         code: 'connection_failed',
         message: '机器人已经创建，但长连接未就绪，请点击重试。',
-      });
+      } }).publicError);
       this.#touch();
       throw error;
     }
@@ -1249,12 +1258,12 @@ export class MultiBotDshFeishuController {
 
   async #startRuntime(config, appSecret) {
     await this.#stopRuntime(config.id);
-    const runtime = await this.#createRuntime({
+    const runtime = await atConnectionStage('runtime.prepare', () => this.#createRuntime({
       botId: config.id,
       config,
       appSecret,
       repair: this.#runtimeRepairCapability(config.id),
-    });
+    }));
     this.#runtimes.set(config.id, runtime);
     try {
       await runtime.start();
@@ -1300,21 +1309,21 @@ export class MultiBotDshFeishuController {
     }
     await this.#stopRuntime(botId);
     try {
-      await this.#credentials.unset(config.secretRef);
+      await atConnectionStage('credential.remove', () => this.#credentials.unset(config.secretRef), 'credential-store');
     } catch (error) {
-      this.#botErrors.set(botId, {
+      this.#botErrors.set(botId, this.#diagnostics.report(error, { reuse: true, botId: botId, publicError: {
         code: 'credential_removal_failed',
         message: '无法删除机器人凭据，请稍后重试。',
-      });
+      } }).publicError);
       throw new Error('Unable to remove the Feishu credential.', { cause: error });
     }
     try {
       await this.#deleteState({ botId, config });
     } catch (error) {
-      this.#botErrors.set(botId, {
+      this.#botErrors.set(botId, this.#diagnostics.report(error, { reuse: true, botId: botId, publicError: {
         code: 'state_cleanup_failed',
         message: '无法删除机器人的本地会话数据，请稍后重试。',
-      });
+      } }).publicError);
       throw new Error('Unable to remove the Feishu bot session state.', { cause: error });
     }
     await this.#configStore.removeBot(botId);
@@ -1323,8 +1332,8 @@ export class MultiBotDshFeishuController {
   }
 
   async #restoreCredential(secretRef, previous) {
-    if (previous?.value) await this.#credentials.set(secretRef, previous.value);
-    else await this.#credentials.unset(secretRef);
+    if (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');
   }
 
   #requireBot(botId) {

package/src/channels/feishu/registration-manager.mjs

@@ -1,3 +1,4 @@
+import { createConnectionDiagnostics } from '../shared/connection-error.mjs';
 const ACTIVE_STATES = new Set([
   'starting',
   'qr_ready',
@@ -74,6 +75,7 @@ function copyUserInfo(userInfo) {
  * `onCredentials` callback.
  */
 export class RegistrationManager {
+  #diagnostics;
   #registerApp;
   #onCredentials;
   #now;
@@ -86,6 +88,7 @@ export class RegistrationManager {
   constructor({
     registerApp,
     onCredentials,
+    diagnostics = createConnectionDiagnostics({ channel: 'feishu' }),
     now = Date.now,
     setTimeout: setTimeoutFn = globalThis.setTimeout,
     clearTimeout: clearTimeoutFn = globalThis.clearTimeout,
@@ -100,6 +103,7 @@ export class RegistrationManager {
       throw new TypeError('RegistrationManager clock dependencies must be functions');
     }
 
+    this.#diagnostics = diagnostics;
     this.#registerApp = registerApp;
     this.#onCredentials = onCredentials;
     this.#now = now;
@@ -263,13 +267,13 @@ export class RegistrationManager {
         client_secret: clientSecret,
         user_info: userInfo,
       });
-    } catch {
+    } catch (error) {
       if (this.#isCurrent(run)) {
         this.#finishRun(run, REGISTRATION_STATES.ERROR, {
-          error: {
+          error: this.#diagnostics.report(error, { operation: 'provision.poll', stage: 'activation', publicError: {
             code: 'credentials_callback_failed',
             message: 'Unable to store the Feishu credentials.',
-          },
+          } }).publicError,
         });
       }
       return;
@@ -297,7 +301,7 @@ export class RegistrationManager {
       return;
     }
     this.#finishRun(run, REGISTRATION_STATES.ERROR, {
-      error: publicError(error),
+      error: this.#diagnostics.report(error, { operation: run.qrCodeUrl ? 'provision.poll' : 'provision.begin', publicError: publicError(error) }).publicError,
     });
   }
 

package/src/channels/feishu/repair-manager.mjs

@@ -85,7 +85,7 @@ export class CallbackRepairManager {
   #appId;
   #domain;
 
-  constructor({ registerApp, onCredentials, appId, domain = 'feishu' } = {}) {
+  constructor({ registerApp, onCredentials, appId, domain = 'feishu', diagnostics } = {}) {
     if (typeof registerApp !== 'function') throw new TypeError('registerApp is required');
     if (typeof onCredentials !== 'function') throw new TypeError('onCredentials is required');
     if (typeof appId !== 'string' || !appId.trim()) throw new TypeError('appId is required');
@@ -94,6 +94,7 @@ export class CallbackRepairManager {
     this.#appId = appId.trim();
     this.#domain = domain;
     this.#manager = new RegistrationManager({
+      diagnostics,
       registerApp: (options) => registerApp({
         ...options,
         onQRCodeReady: (info) => {

package/src/channels/imessage/runtime.mjs

@@ -1,3 +1,4 @@
+import { createConnectionDiagnostics, atConnectionStage } from '../shared/connection-error.mjs';
 import { sendRememberedConnectionTest } from '../shared/connection-test.mjs';
 import { MacOSMessagesApi, normalizeIMessage } from './imessage-api.mjs';
 import { createIMessageBridgeStatus, IMessageHarnessBridge } from './imessage-bridge.mjs';
@@ -26,6 +27,7 @@ export function createIMessageRuntimeStatus() {
 
 export class IMessageRuntime {
   #config; #token; #harness; #state; #contextEnhancement; #accessPolicy; #logger;
+  #diagnostics;
   #replyTimeoutMs; #pollIntervalMs; #createApi; #status = createIMessageRuntimeStatus();
   #api; #bridge; #abortController; #timer; #polling; #stopped = true;
   constructor({ config, token, harness, state, contextEnhancement, accessPolicy, logger = console,
@@ -33,7 +35,7 @@ export class IMessageRuntime {
     createApi = (options) => new MacOSMessagesApi(options) }) {
     if (!config || !token || !harness || !state) throw new TypeError('IMessageRuntime requires config, token, Harness, and state');
     this.#config = config; this.#token = token; this.#harness = harness; this.#state = state;
-    this.#contextEnhancement = contextEnhancement; this.#accessPolicy = accessPolicy; this.#logger = logger;
+    this.#contextEnhancement = contextEnhancement; this.#accessPolicy = accessPolicy; this.#logger = logger; this.#diagnostics = createConnectionDiagnostics({ channel: 'imessage', logger });
     this.#replyTimeoutMs = replyTimeoutMs; this.#pollIntervalMs = pollIntervalMs; this.#createApi = createApi;
   }
   get status() { return structuredClone(this.#status); }
@@ -60,7 +62,7 @@ export class IMessageRuntime {
     await this.stop(); this.#stopped = false; this.#status.startedAt = new Date().toISOString(); this.#status.connectionState = 'connecting';
     this.#abortController = new AbortController();
     try {
-      await this.#harness.ensureRunning(); this.#status.harnessReachable = true;
+      await atConnectionStage('harness.check', () => this.#harness.ensureRunning()); this.#status.harnessReachable = true;
       this.#api = this.#createApi({ signal: this.#abortController.signal });
       const permissions = await this.#api.getPermissions();
       if (permissions.database !== 'granted' || permissions.automation !== 'granted') {
@@ -78,7 +80,8 @@ export class IMessageRuntime {
         logger: this.#logger, replyTimeoutMs: this.#replyTimeoutMs, signal: this.#abortController.signal });
       this.#status.ready = true; this.#status.connectionState = 'connected'; this.#status.lastConnectedAt = Date.now();
       this.#schedulePoll(0); return this.status;
-    } catch (error) { this.#status.ready = false; this.#status.connectionState = 'failed'; this.#status.lastError = error.message; await this.stop(); throw error; }
+    } catch (error) { this.#status.ready = false; this.#status.connectionState = 'failed'; 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; }
   }
   async stop() { this.#stopped = true; clearTimeout(this.#timer); this.#timer = null; this.#abortController?.abort(); await this.#polling?.catch(() => {}); this.#polling = null; this.#bridge = null; this.#api = null; this.#status.ready = false; }
   #schedulePoll(delay) { if (this.#stopped) return; this.#timer = setTimeout(() => { this.#polling = this.#poll().finally(() => this.#schedulePoll(this.#pollIntervalMs)); }, delay); this.#timer.unref?.(); }
@@ -92,7 +95,8 @@ export class IMessageRuntime {
         if (message) await this.#bridge.accept(message);
         if (Number.isSafeInteger(raw.rowid)) await this.#state.setCursor(raw.rowid);
       }
-      this.#status.lastCheckedAt = Date.now(); this.#status.lastError = null;
-    } catch (error) { if (!this.#stopped) { this.#status.lastError = error.message; this.#logger.warn?.('[dsh-im:imessage] polling failed', error); } }
+      this.#status.lastCheckedAt = Date.now(); this.#status.lastError = null; this.#status.error = null; this.#diagnostics.clear();
+    } catch (error) { if (!this.#stopped) { this.#status.error = this.#diagnostics.report(error, { operation: 'connection.monitor', botId: this.#config?.botId, automatic: true }).publicError;
+      this.#status.lastError = this.#status.error.message;  } }
   }
 }

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

@@ -1,3 +1,4 @@
+import { atConnectionStage, createConnectionDiagnostics } from '../shared/connection-error.mjs';
 import { createHash } from 'node:crypto';
 
 import { normalizeOfficeBaseUrl, officeHookUrls } from './protocol.mjs';
@@ -15,6 +16,7 @@ export class OfficeController {
   #credentials;
   #store;
   #logger;
+  #diagnostics;
   #createRuntime;
   #runtime = null;
   #transition = Promise.resolve();
@@ -29,13 +31,16 @@ export class OfficeController {
     this.#credentials = credentials;
     this.#store = configStore;
     this.#logger = logger;
+    this.#diagnostics = createConnectionDiagnostics({ channel: 'office', logger });
     this.#createRuntime = createRuntime ?? ((options) => new OfficeRuntime(options));
   }
 
+  get diagnostics() { return this.#diagnostics; }
+
   async initialize() {
     const config = this.#store.get();
     if (config) {
-      const credential = await this.#credentials.resolve(config.deviceTokenRef).catch(() => undefined);
+      const credential = await atConnectionStage('credential.read', () => this.#credentials.resolve(config.deviceTokenRef), 'credential-store');
       if (credential?.value) await this.#start(config, credential.value);
     }
     return this.status();
@@ -50,7 +55,7 @@ export class OfficeController {
       const baseUrl = normalizeOfficeBaseUrl(requestedBaseUrl).origin;
       const tokenRef = officeTokenRef(baseUrl, deviceId);
       const suppliedToken = clean(input.deviceToken);
-      const priorCredential = await this.#credentials.resolve(tokenRef).catch(() => undefined);
+      const priorCredential = await atConnectionStage('credential.read', () => this.#credentials.resolve(tokenRef), 'credential-store');
       const token = suppliedToken ?? priorCredential?.value;
       if (!token || token.length < 32) throw new TypeError('Device Token must contain at least 32 characters');
       const now = new Date().toISOString();
@@ -68,16 +73,16 @@ export class OfficeController {
       });
       if (!config) throw new TypeError('AI Office connector configuration is invalid');
 
-      await this.#credentials.set(tokenRef, token);
+      await atConnectionStage('credential.save', () => this.#credentials.set(tokenRef, token), 'credential-store');
       try {
-        await this.#store.save(config);
+        await atConnectionStage('account.save', () => this.#store.save(config), 'account-config');
       } catch (error) {
-        if (priorCredential?.value) await this.#credentials.set(tokenRef, priorCredential.value).catch(() => undefined);
-        else await this.#credentials.unset(tokenRef).catch(() => undefined);
+        if (priorCredential?.value) await atConnectionStage('credential.save', () => this.#credentials.set(tokenRef, priorCredential.value), 'credential-store').catch(() => undefined);
+        else await atConnectionStage('credential.remove', () => this.#credentials.unset(tokenRef), 'credential-store').catch(() => undefined);
         throw error;
       }
       if (previous?.deviceTokenRef && previous.deviceTokenRef !== tokenRef) {
-        await this.#credentials.unset(previous.deviceTokenRef).catch(() => undefined);
+        await atConnectionStage('credential.remove', () => this.#credentials.unset(previous.deviceTokenRef), 'credential-store');
       }
       await this.#start(config, token);
       return this.status();
@@ -104,18 +109,24 @@ export class OfficeController {
 
   async remove() {
     return this.#serial(async () => {
+      const warnings = [];
       const config = this.#store.get();
       await this.#stop();
-      if (config?.deviceTokenRef) await this.#credentials.unset(config.deviceTokenRef).catch(() => undefined);
-      await this.#store.clear();
-      return this.status();
+      await atConnectionStage('account.remove', () => this.#store.clear(), 'account-config');
+      if (config?.deviceTokenRef) {
+        await atConnectionStage('credential.remove', () => this.#credentials.unset(config.deviceTokenRef), 'credential-store').catch(error => {
+          warnings.push(this.#diagnostics.report(error, { reuse: true, operation: 'connector.remove', warning: true,
+            publicError: { code: 'cleanup-failed', message: '连接已移除，但登录凭据清理失败。' } }).publicError);
+        });
+      }
+      return { ...await this.status(), ...(warnings.length ? { warnings } : {}) };
     });
   }
 
   async status() {
     const config = this.#store.get();
     if (!config) return { schemaVersion: 1, configured: false, connected: false, state: 'unconfigured' };
-    const credential = await this.#credentials.resolve(config.deviceTokenRef).catch(() => undefined);
+    const credential = await atConnectionStage('credential.read', () => this.#credentials.resolve(config.deviceTokenRef), 'credential-store');
     const runtime = this.#runtime?.status ?? null;
     return {
       schemaVersion: 1,
@@ -140,7 +151,7 @@ export class OfficeController {
   async close() { await this.#transition.catch(() => undefined); await this.#stop(); }
 
   async #resolveToken(config) {
-    const credential = await this.#credentials.resolve(config.deviceTokenRef).catch(() => undefined);
+    const credential = await atConnectionStage('credential.read', () => this.#credentials.resolve(config.deviceTokenRef), 'credential-store');
     if (!credential?.value) throw new Error('AI Office Device Token is missing');
     return credential.value;
   }

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

@@ -1,3 +1,4 @@
+import { extractConnectionEvidence, createConnectionDiagnostics } from '../shared/connection-error.mjs';
 import { setTimeout as sleep } from 'node:timers/promises';
 
 import { t } from '../shared/i18n.mjs';
@@ -22,6 +23,7 @@ export class OfficeRuntime {
   #config;
   #token;
   #logger;
+  #diagnostics;
   #transport;
   #sleep;
   #controller = null;
@@ -41,6 +43,7 @@ export class OfficeRuntime {
     this.#config = config;
     this.#token = token;
     this.#logger = logger;
+    this.#diagnostics = createConnectionDiagnostics({ channel: 'office', logger });
     this.#sleep = sleepImpl;
     this.#transport = transport ?? new OfficeTransport({
       baseUrl: config.baseUrl, deviceId: config.deviceId, token,
@@ -88,7 +91,7 @@ export class OfficeRuntime {
     this.#task = this.#run(this.#controller.signal).finally(() => { this.#task = null; });
     this.#task.catch((error) => {
       if (this.#controller?.signal.aborted) return;
-      this.#logger.error?.('[dsh-im:office] connector stopped:', error);
+      this.#logger.error?.('[dsh-im:office] connector stopped:', extractConnectionEvidence(error).details);
     });
     return this.status;
   }
@@ -112,7 +115,7 @@ export class OfficeRuntime {
           onOpen: () => {
             this.#status.connected = true;
             this.#status.state = 'connected';
-            this.#status.error = null;
+            this.#status.error = null; this.#diagnostics.clear();
             streamOpened = true;
           },
           onEvent: async (event) => {
@@ -129,7 +132,7 @@ export class OfficeRuntime {
         attemptController.abort();
         this.#status.connected = false;
         this.#status.state = 'reconnecting';
-        this.#status.error = safeConnectionError(error);
+        this.#status.error = this.#diagnostics.report(error, { operation: 'connection.monitor', automatic: true, publicError: safeConnectionError(error) }).publicError;
         this.#status.reconnects += 1;
         const delay = RETRY_DELAYS[Math.min(attempt, RETRY_DELAYS.length - 1)];
         attempt += 1;

package/src/channels/office/office-transport.mjs

@@ -2,6 +2,7 @@ import { OFFICE_HOOK_PATHS, OFFICE_PROTOCOL_VERSION, officeHookUrls } from './pr
 
 function safeTransportError(operation, response) {
   const error = new Error(`AI Office ${operation} failed: HTTP ${response.status}`);
+  error.status = response.status;
   error.code = response.status === 401 ? 'invalid-device-token'
     : response.status === 404 ? 'office-hook-unavailable'
       : response.status === 409 ? 'office-job-conflict' : 'office-transport-failed';