@xmanrui/dsh-im 4.9.0 → 4.9.1

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

@@ -12,6 +12,11 @@ import {
 } from '../shared/connection-test.mjs';
 import { t } from '../shared/i18n.mjs';
 import { publicMessageFailure } from '../shared/message-failure.mjs';
+import {
+  describeDingtalkConnectionFailure,
+  dingtalkPublicConnectionError,
+  dingtalkRuntimeStartError,
+} from './connection-error.mjs';
 
 const ACTIVE_ATTEMPT_STATES = new Set(['starting', 'pending', 'connecting']);
 const TERMINAL_ATTEMPT_STATES = new Set(['connected', 'expired', 'failed', 'cancelled']);
@@ -216,12 +221,14 @@ export class DingtalkController {
         try {
           await this.#startRuntime(latest, clientSecret);
           this.#errors.delete(latest.botId);
-        } catch {
-          this.#errors.set(
-            latest.botId,
-            safeError('connection-failed', t('钉钉连接未就绪，请稍后重试。')),
-          );
-          this.#logger.warn?.(`[dsh-dingtalk] bot ${latest.botId} failed to initialize`);
+        } catch (error) {
+          this.#rememberConnectionFailure({
+            config: latest,
+            clientSecret,
+            error,
+            fallbackMessage: '钉钉连接未就绪，请稍后重试。',
+            context: `bot ${latest.botId} failed to initialize`,
+          });
         }
         this.#touch();
       });
@@ -318,12 +325,14 @@ export class DingtalkController {
       try {
         await this.#startRuntime(config, normalizedSecret);
         this.#errors.delete(identity.botId);
-      } catch {
-        this.#errors.set(
-          identity.botId,
-          safeError('connection-failed', t('钉钉已接入，但消息连接暂未就绪，请稍后重试。')),
-        );
-        this.#logger.warn?.('[dsh-dingtalk] credential-bound bot saved but its connection is not ready');
+      } catch (error) {
+        this.#rememberConnectionFailure({
+          config,
+          clientSecret: normalizedSecret,
+          error,
+          fallbackMessage: '钉钉已接入，但消息连接暂未就绪，请稍后重试。',
+          context: `credential-bound bot ${identity.botId} is not ready`,
+        });
       }
       this.#touch();
     });
@@ -380,11 +389,14 @@ export class DingtalkController {
         await this.#startRuntime(config, clientSecret);
         this.#errors.delete(botId);
       } catch (error) {
-        this.#errors.set(
-          botId,
-          safeError('connection-failed', t('钉钉连接仍未就绪，请稍后重试。')),
-        );
-        throw error;
+        const publicError = this.#rememberConnectionFailure({
+          config,
+          clientSecret,
+          error,
+          fallbackMessage: '钉钉连接仍未就绪，请稍后重试。',
+          context: `bot ${botId} failed to reconnect`,
+        });
+        throw dingtalkPublicConnectionError(publicError, error);
       } finally {
         this.#touch();
       }
@@ -675,11 +687,13 @@ export class DingtalkController {
           await rollback();
           throw abortError();
         }
-        this.#errors.set(
-          identity.botId,
-          safeError('connection-failed', t('钉钉已接入，但消息连接暂未就绪，请稍后重试。')),
-        );
-        this.#logger.warn?.('[dsh-dingtalk] authorized bot saved but its connection is not ready');
+        this.#rememberConnectionFailure({
+          config,
+          clientSecret,
+          error,
+          fallbackMessage: '钉钉已接入，但消息连接暂未就绪，请稍后重试。',
+          context: `authorized bot ${identity.botId} is not ready`,
+        });
       }
       return { botId: identity.botId, alreadyConnected: Boolean(previousConfig) };
     });
@@ -696,11 +710,14 @@ export class DingtalkController {
       } catch (error) {
         await this.#configStore.save(previousConfig).catch(() => undefined);
         await this.#startRuntime(previousConfig, clientSecret).catch(() => undefined);
-        this.#errors.set(
-          previousConfig.botId,
-          safeError('connection-failed', t('钉钉连接未就绪，请稍后重试。')),
-        );
-        throw error;
+        const publicError = this.#rememberConnectionFailure({
+          config: previousConfig,
+          clientSecret,
+          error,
+          fallbackMessage: '钉钉连接未就绪，请稍后重试。',
+          context: `bot ${previousConfig.botId} failed to apply updated settings`,
+        });
+        throw dingtalkPublicConnectionError(publicError, error);
       } finally {
         this.#touch();
       }
@@ -711,13 +728,21 @@ export class DingtalkController {
     if (this.#closed) throw abortError();
     await this.#stopRuntime(config.botId);
     if (this.#closed) throw abortError();
-    const runtime = await this.#createRuntime({
-      botId: config.botId,
-      config: structuredClone(config),
-      clientSecret,
-    });
+    let runtime;
+    try {
+      runtime = await this.#createRuntime({
+        botId: config.botId,
+        config: structuredClone(config),
+        clientSecret,
+      });
+    } catch (error) {
+      throw dingtalkRuntimeStartError('dingtalk-runtime-prepare-failed', error);
+    }
     if (!runtime || typeof runtime.start !== 'function' || typeof runtime.stop !== 'function') {
-      throw new TypeError('createRuntime returned an invalid DingTalk runtime');
+      throw dingtalkRuntimeStartError(
+        'dingtalk-runtime-prepare-failed',
+        new TypeError('createRuntime returned an invalid DingTalk runtime'),
+      );
     }
     if (this.#closed) {
       await runtime.stop().catch(() => undefined);
@@ -733,10 +758,30 @@ export class DingtalkController {
     } catch (error) {
       if (this.#runtimes.get(config.botId) === runtime) this.#runtimes.delete(config.botId);
       await runtime.stop().catch(() => undefined);
-      throw error;
+      throw dingtalkRuntimeStartError('dingtalk-stream-connect-failed', error);
     }
   }
 
+  #rememberConnectionFailure({
+    config,
+    clientSecret,
+    error,
+    fallbackMessage,
+    context,
+  }) {
+    const failure = describeDingtalkConnectionFailure(error, {
+      fallbackMessage,
+      clientId: config.clientId,
+      clientSecret,
+    });
+    this.#errors.set(config.botId, failure.publicError);
+    this.#logger.error?.(
+      `[dsh-dingtalk] ${context} [${failure.publicError.referenceId}]`,
+      failure.diagnostic,
+    );
+    return failure.publicError;
+  }
+
   async #stopRuntime(botId) {
     const runtime = this.#runtimes.get(botId);
     this.#runtimes.delete(botId);

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

@@ -6,6 +6,7 @@ import {
 import { sendRememberedConnectionTest } from '../shared/connection-test.mjs';
 import { t } from '../shared/i18n.mjs';
 import { captureContextEnhancement } from '../shared/context-enhancement.mjs';
+import { dingtalkRuntimeStartError } from './connection-error.mjs';
 
 function nonEmptyString(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
@@ -223,10 +224,12 @@ export class DingtalkRuntime {
     this.#status.startedAt = new Date().toISOString();
     this.#status.dingtalkStreamState = 'connecting';
     this.#status.lastError = null;
+    let startStage = 'dingtalk-harness-connect-failed';
 
     try {
       await this.#harness.ensureRunning({ signal });
       this.#status.harnessReachable = true;
+      startStage = 'dingtalk-runtime-prepare-failed';
       if (typeof this.#state.removePendingSenderByStaffId === 'function') {
         for (const staffId of approvedSenderIds(this.#config)) {
           await this.#state.removePendingSenderByStaffId(staffId);
@@ -249,6 +252,7 @@ export class DingtalkRuntime {
         signal,
       });
 
+      startStage = 'dingtalk-stream-client-load-failed';
       const created = await this.#streamFactory({
         clientId: this.#config.clientId,
         clientSecret: this.#clientSecret,
@@ -266,6 +270,7 @@ export class DingtalkRuntime {
 
       const client = this.#client;
       const bridge = this.#bridge;
+      startStage = 'dingtalk-stream-listener-failed';
       client.registerCallbackListener(this.#topic, (response) => {
         if (this.#client !== client || this.#bridge !== bridge) return;
         const callbackMessageId = nonEmptyString(response?.headers?.messageId);
@@ -314,6 +319,7 @@ export class DingtalkRuntime {
         this.#callbackTasks.add(task);
       });
 
+      startStage = 'dingtalk-stream-connect-failed';
       await connectStream(
         client,
         this.#connectTimeoutMs,
@@ -336,11 +342,12 @@ export class DingtalkRuntime {
       return this.status;
     } catch (error) {
       const aborted = signal.aborted;
+      const failure = aborted ? error : dingtalkRuntimeStartError(startStage, error);
       this.#status.ready = false;
       this.#status.dingtalkStreamState = aborted ? 'idle' : 'failed';
-      this.#status.lastError = aborted ? null : (error?.message ?? String(error));
+      this.#status.lastError = aborted ? null : (failure?.message ?? String(failure));
       await this.stop({ preserveError: !aborted });
-      throw error;
+      throw failure;
     }
   }
 

package/src/channels/shared/i18n-en/dingtalk.mjs

@@ -38,6 +38,29 @@ export default {
   '钉钉机器人凭据缺失，请移除后重新扫码。': 'The DingTalk bot credentials are missing. Remove the bot and scan the QR code again.',
   '钉钉连接未就绪，请稍后重试。': 'The DingTalk connection is not ready. Please try again later.',
   '钉钉连接仍未就绪，请稍后重试。': 'The DingTalk connection is still not ready. Please try again later.',
+  '钉钉 Stream 连接失败：检测到代理依赖 agent-base 6.0.0。': 'The DingTalk Stream connection failed because proxy dependency agent-base 6.0.0 was detected.',
+  '请将 DSH profile 中的 agent-base@6 固定为 6.0.2 后重新安装依赖，或升级 pnpm 后重新解析 lockfile。': 'Pin agent-base@6 to 6.0.2 in the DSH profile and reinstall dependencies, or upgrade pnpm and re-resolve the lockfile.',
+  '插件无法连接本机 Harness。': 'The plugin could not connect to the local Harness.',
+  '请确认 dsh web 正常运行，并查看 dsh web 日志中相同参考号对应的诊断信息。': 'Make sure dsh web is running, then find the matching reference in the dsh web log.',
+  '钉钉 Stream SDK 加载失败。': 'The DingTalk Stream SDK could not be loaded.',
+  '请重新安装当前 DSH profile 的插件依赖，并查看 dsh web 日志中相同参考号对应的诊断信息。': 'Reinstall plugin dependencies in the current DSH profile, then find the matching reference in the dsh web log.',
+  '钉钉拒绝了当前应用凭据。': 'DingTalk rejected the current app credentials.',
+  '请核对 Client ID、Client Secret 和机器人权限后重试。': 'Verify the app credentials and bot permissions, then try again.',
+  '连接钉钉 Stream 超时。': 'The DingTalk Stream connection timed out.',
+  '请检查网络、代理和防火墙后重试；详细原因可在 dsh web 日志中按参考号查找。': 'Check the network, proxy, and firewall, then try again. Find details in the dsh web log using the reference.',
+  '无法解析钉钉服务地址。': 'The DingTalk service address could not be resolved.',
+  '请检查 DNS、网络和代理设置；详细原因可在 dsh web 日志中按参考号查找。': 'Check DNS, network, and proxy settings. Find details in the dsh web log using the reference.',
+  '钉钉 Stream 的 TLS 连接校验失败。': 'TLS validation failed for the DingTalk Stream connection.',
+  '请检查系统证书、代理证书或 HTTPS 中间代理；详细原因可在 dsh web 日志中按参考号查找。': 'Check system certificates, proxy certificates, or the HTTPS interception proxy. Find details in the dsh web log using the reference.',
+  '钉钉 Stream 无法通过当前代理建立连接。': 'DingTalk Stream could not connect through the current proxy.',
+  '请检查 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 和代理连通性；详细原因可在 dsh web 日志中按参考号查找。': 'Check HTTP_PROXY, HTTPS_PROXY, NO_PROXY, and proxy connectivity. Find details in the dsh web log using the reference.',
+  '钉钉 Stream 消息连接建立失败。': 'The DingTalk Stream message connection could not be established.',
+  '请检查网络和机器人配置；详细原因可在 dsh web 日志中按参考号查找。': 'Check the network and bot configuration. Find details in the dsh web log using the reference.',
+  '钉钉 Stream 消息监听初始化失败。': 'DingTalk Stream message-listener initialization failed.',
+  '请确认 dsh-im 与 dingtalk-stream 版本兼容，并按参考号查看 dsh web 日志。': 'Make sure dsh-im and dingtalk-stream are compatible, then inspect the dsh web log using the reference.',
+  '钉钉机器人运行环境初始化失败。': 'The DingTalk bot runtime could not be initialized.',
+  '请检查 DSH 数据目录、工作区和插件依赖，并按参考号查看 dsh web 日志。': 'Check the DSH data directory, workspace, and plugin dependencies, then inspect the dsh web log using the reference.',
+  '请在 dsh web 日志中查找相同参考号，以获取已脱敏的具体错误。': 'Find the matching reference in the dsh web log for the redacted error details.',
   '扫码接入已取消。': 'QR code setup has been cancelled.',
   '无法生成钉钉二维码，请稍后重试。': 'Could not generate the DingTalk QR code. Please try again later.',
   '二维码已过期，请重新生成。': 'The QR code has expired. Generate a new one.',