@xmanrui/dsh-im 4.9.0 → 4.9.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmanrui/dsh-im",
-  "version": "4.9.0",
+  "version": "4.9.1",
   "description": "把九种 IM 机器人和公网 AI Office 接入本机 DeepSeek Harness。 Connect nine IM channels and a public AI Office to a local DeepSeek Harness.",
   "keywords": [
     "deepseek-harness",
@@ -22,10 +22,7 @@
     "whatsapp",
     "ai-office"
   ],
-  "author": {
-    "name": "xmanrui",
-    "url": "https://github.com/xmanrui"
-  },
+  "author": "xmanrui (https://github.com/xmanrui)",
   "contributors": [
     {
       "name": "C3H3-AI",
@@ -47,7 +44,9 @@
     "url": "git+https://github.com/xmanrui/dsh-im.git"
   },
   "homepage": "https://github.com/xmanrui/dsh-im#readme",
-  "bugs": "https://github.com/xmanrui/dsh-im/issues",
+  "bugs": {
+    "url": "https://github.com/xmanrui/dsh-im/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -116,5 +115,10 @@
     "react-dom": "18.3.1",
     "react-test-renderer": "18.3.1",
     "semver": "7.8.5"
+  },
+  "directories": {
+    "doc": "docs",
+    "lib": "lib",
+    "test": "test"
   }
 }

package/plugin-src/client/channels/dingtalk/api.js

@@ -85,11 +85,20 @@ function sanitizeMessage(value, fallback) {
   return message.replace(/([=:]\s*)[^\s,;，。]+/g, '$1••••••').slice(0, 240);
 }
 
+function safeReferenceId(value) {
+  const referenceId = optionalString(value, 40);
+  return referenceId && /^DT-CONN-[A-F0-9]{8}$/.test(referenceId) ? referenceId : undefined;
+}
+
 function normalizeError(value, fallbackCode, fallbackMessage) {
   if (!isRecord(value)) return undefined;
+  const hint = sanitizeMessage(value.hint, '');
+  const referenceId = safeReferenceId(value.referenceId);
   return {
     code: safeErrorCode(value.code, fallbackCode),
     message: sanitizeMessage(value.message, fallbackMessage),
+    ...(hint ? { hint } : {}),
+    ...(referenceId ? { referenceId } : {}),
   };
 }
 
@@ -108,8 +117,15 @@ export function unwrapRpcResult(result) {
     throw new Error('钉钉服务返回了无法识别的响应');
   }
   if (!result.ok) {
-    const error = new Error(sanitizeMessage(result.error?.message, '钉钉操作失败'));
-    error.code = safeErrorCode(result.error?.code, 'DINGTALK_RPC_ERROR');
+    const visible = normalizeError(
+      result.error,
+      'DINGTALK_RPC_ERROR',
+      '钉钉操作失败',
+    ) ?? { code: 'DINGTALK_RPC_ERROR', message: '钉钉操作失败' };
+    const error = new Error(visible.message);
+    error.code = visible.code;
+    if (visible.hint) error.hint = visible.hint;
+    if (visible.referenceId) error.referenceId = visible.referenceId;
     throw error;
   }
   return result.value;
@@ -227,10 +243,11 @@ export function connectionTestFeedback(result) {
 }
 
 export function presentError(error) {
-  return {
-    code: safeErrorCode(error?.code, 'DINGTALK_ERROR'),
-    message: sanitizeMessage(error?.message, '钉钉操作失败，请稍后重试'),
-  };
+  return normalizeError(
+    error,
+    'DINGTALK_ERROR',
+    '钉钉操作失败，请稍后重试',
+  ) ?? { code: 'DINGTALK_ERROR', message: '钉钉操作失败，请稍后重试' };
 }
 
 export function formatRemaining(milliseconds) {

package/plugin-src/client/channels/dingtalk/index.js

@@ -169,19 +169,36 @@ function ProgressPanel({ status, busy, onCancel }) {
       h(Button, { onClick: onCancel, disabled: busy }, '取消接入')));
 }
 
+function ConnectionErrorDiagnostic({ error }) {
+  if (!error) return null;
+  return h('div', { className: 'ddt-errorDiagnostic' },
+    error.hint ? h('p', { className: 'ddt-errorHint' }, error.hint) : null,
+    h('span', { className: 'ddt-errorCode' },
+      h('span', null, '错误码'), `: ${error.code}`,
+      error.referenceId
+        ? h(React.Fragment, null, ' · ', h('span', null, '参考号'), `: ${error.referenceId}`)
+        : null));
+}
+
 function ProvisionError({ provision, busy, onRetry, onClose }) {
   const error = provision.error ?? {
     code: 'DINGTALK_PROVISION_FAILED',
     message: '钉钉机器人没有接入完成',
   };
+  const connectionFailed = Boolean(error.referenceId);
   return h('div', { className: 'ddt-card dim-surfaceCard' },
     h('div', { className: 'ddt-inlineError dim-inlineError', role: 'alert' },
-      h('h3', null, provision.status === 'expired' ? '二维码已过期' : '钉钉机器人没有接入完成'),
+      h('h3', null, provision.status === 'expired'
+        ? '二维码已过期'
+        : connectionFailed ? '机器人已保存，但连接未就绪' : '钉钉机器人没有接入完成'),
       h('p', null, error.message),
-      h('span', { className: 'ddt-errorCode' }, error.code),
+      h(ConnectionErrorDiagnostic, { error }),
       h('div', { className: 'ddt-actions dim-viewActions' },
-        h(Button, { kind: 'primary', onClick: onRetry, disabled: busy }, '重新生成二维码'),
-        h(Button, { onClick: onClose, disabled: busy }, '关闭'))));
+        connectionFailed
+          ? h(Button, { kind: 'primary', onClick: onClose, disabled: busy }, '查看已保存的机器人')
+          : h(React.Fragment, null,
+              h(Button, { kind: 'primary', onClick: onRetry, disabled: busy }, '重新生成二维码'),
+              h(Button, { onClick: onClose, disabled: busy }, '关闭')))));
 }
 
 function checkedTime(value) {
@@ -278,6 +295,7 @@ export function AccountCard({
             h(Button, { className: 'dim-cardAction', kind: 'danger', onClick: onRequestRemove, disabled: Boolean(busy) },
               '移除接入')),
           summary ? h('div', { className: 'ddt-summary dim-cardSummary' }, summary) : null,
+          account.error ? h(ConnectionErrorDiagnostic, { error: account.error }) : null,
           account.lastMessageError ? h(LastMessageErrorSummary, {
             className: 'ddt-summary',
             error: account.lastMessageError,
@@ -614,6 +632,12 @@ export function DingtalkSettingsTab({ rpcCall }) {
             ? snapshot?.bots.find((bot) => bot.botId === result.botId)
             : snapshot?.bots.find((bot) => bot.connected);
           if (!account?.connected) {
+            if (account?.error) {
+              setProvision((current) => current?.attemptId === attemptId
+                ? { ...current, ...result, status: 'failed', error: account.error }
+                : current);
+              return;
+            }
             setProvision((current) => current?.attemptId === attemptId
               ? { ...current, ...result, status: 'connecting' }
               : current);
@@ -698,9 +722,12 @@ export function DingtalkSettingsTab({ rpcCall }) {
       return snapshot;
     } catch (error) {
       if (!mountedRef.current) return undefined;
+      const visibleError = presentError(error);
       const failureMessage = operation === 'reconnect'
-        ? '连接检查失败，请稍后重试。'
-        : `操作失败：${presentError(error).message}`;
+        ? visibleError.referenceId
+          ? `连接检查失败：${visibleError.message}（参考号：${visibleError.referenceId}）`
+          : '连接检查失败，请稍后重试。'
+        : `操作失败：${visibleError.message}`;
       if (operation === 'reconnect') {
         setFeedbackByBot((current) => ({
           ...current,

package/plugin-src/client/channels/dingtalk/styles.js

@@ -77,6 +77,8 @@ const CSS = String.raw`
 .ddt-inlineError h3 { font-size: 17px; }
 .ddt-inlineError p { line-height: 1.55; }
 .ddt-errorCode { font: 11px ui-monospace, SFMono-Regular, monospace; opacity: .8; }
+.ddt-errorDiagnostic { display: grid; gap: 5px; color: var(--ddt-error); }
+.ddt-errorHint { margin: 0; color: var(--dsw-alias-label-secondary, #646a73); font-size: 12px; line-height: 1.55; }
 .ddt-listHeading { display: flex; align-items: center; justify-content: space-between; margin: 2px 0 9px; }
 .ddt-listHeading h3 { margin: 0; font-size: 14px; }
 .ddt-list { display: grid; gap: 12px; margin: 0; padding: 0; list-style: none; }

package/plugin-src/client/i18n.js

@@ -351,6 +351,8 @@ const EN = Object.freeze({
   '检查连接': 'Check connection',
   '检查中…': 'Checking…',
   '连接检查失败，请稍后重试。': 'Connection check failed. Try again later.',
+  '机器人已保存，但连接未就绪': 'The bot was saved, but the connection is not ready',
+  '查看已保存的机器人': 'View saved bot',
   '测试消息已发送，请到对应机器人会话中确认。': 'Test message sent. Check the matching bot conversation.',
   '连接检查完成。机器人尚未收到可用于测试的私聊消息。': 'Connection check completed. The bot has not received a direct message it can use for testing.',
   '连接检查完成，但测试消息发送失败。': 'Connection check completed, but the test message could not be sent.',
@@ -921,6 +923,8 @@ function translateDynamic(text) {
   if (match) return `Automatic status refresh failed: ${match[1]}`;
   match = /^操作失败：(.+)$/.exec(text);
   if (match) return `Operation failed: ${match[1]}`;
+  match = /^连接检查失败：(.+)（参考号：(.+)）$/.exec(text);
+  if (match) return `Connection check failed: ${localizeText(match[1])} (reference: ${match[2]})`;
   match = /^连接检查失败：(.+)$/.exec(text);
   if (match) return `Connection check failed: ${match[1]}`;
   match = /^移除失败：(.+)$/.exec(text);

package/plugin-src/host/channels/dingtalk/rpc.mjs

@@ -140,6 +140,27 @@ function internalFailure() {
   };
 }
 
+function publicConnectionFailure(error) {
+  if (error?.name !== 'DingtalkPublicConnectionError' || !isRecord(error.publicError)) return null;
+  const source = error.publicError;
+  const code = typeof source.code === 'string' && /^[a-z][a-z\d-]{1,79}$/.test(source.code)
+    ? source.code
+    : null;
+  const message = typeof source.message === 'string' && source.message.trim()
+    ? source.message.trim().slice(0, 240)
+    : null;
+  const hint = typeof source.hint === 'string' && source.hint.trim()
+    ? source.hint.trim().slice(0, 480)
+    : null;
+  const referenceId = typeof source.referenceId === 'string'
+    && /^DT-CONN-[A-F0-9]{8}$/.test(source.referenceId)
+      ? source.referenceId
+      : null;
+  return code && message && hint && referenceId
+    ? { code, message, hint, referenceId }
+    : null;
+}
+
 function sanitizePublic(value) {
   if (Array.isArray(value)) return value.map(sanitizePublic);
   if (!isRecord(value)) return value;
@@ -293,8 +314,11 @@ export function createDingtalkRpcHandler(controller, { encodeQr = qrDataUrl } =
       return signal?.aborted ? cancelled() : { ok: true, value };
     } catch (error) {
       const workspaceError = publicWorkspaceError(error);
+      const connectionError = publicConnectionFailure(error);
       return signal?.aborted ? cancelled() : workspaceError
         ? { ok: false, error: workspaceError }
+        : connectionError
+          ? { ok: false, error: connectionError }
         : internalFailure();
     }
   };

package/plugin-src/host/modern-harness-api.mjs

@@ -52,6 +52,15 @@ function questionError(message, code) {
   return error;
 }
 
+function sessionEvents(session) {
+  if (typeof session?.snapshotEvents === 'function') {
+    const events = session.snapshotEvents();
+    if (Array.isArray(events)) return events;
+  }
+  const events = session?.events;
+  return Array.isArray(events) ? events : null;
+}
+
 function matchesQuestions(value, pending) {
   if (!value || typeof value !== 'object'
     || value.sessionId !== pending.sessionId
@@ -385,15 +394,15 @@ class ModernHarnessApi {
   }
 
   #claimableAgent(agent) {
-    const sessionId = agent?.session?.id ?? agent?.id;
-    if (typeof sessionId !== 'string' || !agent?.session || !Array.isArray(agent.session.events)) {
-      return null;
-    }
+    const session = agent?.session;
+    const sessionId = session?.id ?? agent?.id;
+    const events = sessionEvents(session);
+    if (typeof sessionId !== 'string' || !events) return null;
     return hasActiveHarnessInteractionOwner(
       this.#scope,
       sessionId,
-      agent.session.events,
-    ) ? { sessionId, session: agent.session } : null;
+      events,
+    ) ? { sessionId, events } : null;
   }
 
   #questionFrame(pending) {
@@ -464,8 +473,8 @@ class ModernHarnessApi {
     const claimed = new Set([...this.#pendingApprovals.values()].map((entry) => entry.approvalId));
     const decided = new Set();
     let approvalId;
-    for (let index = owner.session.events.length - 1; index >= 0; index -= 1) {
-      const event = owner.session.events[index];
+    for (let index = owner.events.length - 1; index >= 0; index -= 1) {
+      const event = owner.events[index];
       if (event.type === 'approval/decided') {
         decided.add(event.data?.id);
       } else if (event.type === 'approval/asked') {

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

@@ -0,0 +1,299 @@
+import { randomUUID } from 'node:crypto';
+import { createRequire } from 'node:module';
+
+import { t } from '../shared/i18n.mjs';
+
+const require = createRequire(import.meta.url);
+const STAGE_CODES = new Set([
+  'dingtalk-harness-connect-failed',
+  'dingtalk-runtime-prepare-failed',
+  'dingtalk-stream-client-load-failed',
+  'dingtalk-stream-listener-failed',
+  'dingtalk-stream-connect-failed',
+]);
+const PROXY_VARIABLES = Object.freeze([
+  'HTTPS_PROXY',
+  'https_proxy',
+  'HTTP_PROXY',
+  'http_proxy',
+  'ALL_PROXY',
+  'all_proxy',
+]);
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/;
+const PUBLIC_REFERENCE_PATTERN = /^DT-CONN-[A-F0-9]{8}$/;
+let installedDependencyVersions;
+
+function nonEmptyString(value, maxLength = 500) {
+  if (typeof value !== 'string') return null;
+  const text = value.trim();
+  return text ? text.slice(0, maxLength) : null;
+}
+
+function safeVersion(value) {
+  const version = nonEmptyString(value, 80);
+  return version && VERSION_PATTERN.test(version) ? version : null;
+}
+
+function resolvedPackage(name, from = require) {
+  try {
+    const packagePath = from.resolve(`${name}/package.json`);
+    return {
+      version: safeVersion(from(packagePath)?.version),
+      require: createRequire(packagePath),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/** Returns only non-sensitive versions involved in the external DingTalk Stream dependency chain. */
+export function installedDingtalkConnectionDependencies() {
+  if (installedDependencyVersions) return installedDependencyVersions;
+  const dingtalkStream = resolvedPackage('dingtalk-stream');
+  const axios = dingtalkStream ? resolvedPackage('axios', dingtalkStream.require) : null;
+  const httpsProxyAgent = axios ? resolvedPackage('https-proxy-agent', axios.require) : null;
+  const agentBase = httpsProxyAgent ? resolvedPackage('agent-base', httpsProxyAgent.require) : null;
+  installedDependencyVersions = Object.freeze({
+    dingtalkStream: dingtalkStream?.version ?? null,
+    axios: axios?.version ?? null,
+    httpsProxyAgent: httpsProxyAgent?.version ?? null,
+    agentBase: agentBase?.version ?? null,
+  });
+  return installedDependencyVersions;
+}
+
+function errorChain(error) {
+  const chain = [];
+  const seen = new Set();
+  let current = error;
+  while (current && typeof current === 'object' && chain.length < 4 && !seen.has(current)) {
+    seen.add(current);
+    chain.push(current);
+    current = current.cause;
+  }
+  return chain;
+}
+
+function statusFrom(error) {
+  if (Number.isInteger(error?.status)) return error.status;
+  if (Number.isInteger(error?.statusCode)) return error.statusCode;
+  if (Number.isInteger(error?.response?.status)) return error.response.status;
+  return null;
+}
+
+function providerCodeFrom(error) {
+  const value = nonEmptyString(
+    error?.providerCode
+      ?? error?.response?.data?.code
+      ?? error?.response?.data?.errorCode
+      ?? error?.response?.data?.errcode,
+    100,
+  );
+  return value && /^[A-Za-z0-9_.:-]+$/.test(value) ? value : null;
+}
+
+function redactMessage(value, sensitiveValues) {
+  let message = nonEmptyString(value);
+  if (!message) return null;
+  for (const sensitive of sensitiveValues) {
+    const text = nonEmptyString(sensitive, 2_048);
+    if (text && text.length >= 4) message = message.replaceAll(text, '••••');
+  }
+  return message
+    .replace(/(https?:\/\/)[^/\s@]+@/giu, '$1••••@')
+    .replace(/([?&](?:appsecret|client_secret|clientsecret|access_token|token|password)=)[^&\s]*/giu, '$1••••')
+    .replace(/((?:app|client|access)[_-]?secret|authorization|password|token)\s*[=:]\s*[^\s,;，。]+/giu, '$1=••••')
+    .replace(/\b[A-Za-z0-9_.-]*secret[A-Za-z0-9_.-]*\b/giu, '••••')
+    .slice(0, 500);
+}
+
+function safeDependencyVersions(value) {
+  const source = value && typeof value === 'object' ? value : {};
+  return {
+    dingtalkStream: safeVersion(source.dingtalkStream),
+    axios: safeVersion(source.axios),
+    httpsProxyAgent: safeVersion(source.httpsProxyAgent),
+    agentBase: safeVersion(source.agentBase),
+  };
+}
+
+function diagnosticErrors(chain, sensitiveValues) {
+  return chain.map((error) => {
+    const name = nonEmptyString(error?.name, 80);
+    const code = nonEmptyString(error?.code, 100);
+    const status = statusFrom(error);
+    const providerCode = providerCodeFrom(error);
+    const message = redactMessage(error?.message, sensitiveValues);
+    return {
+      ...(name ? { name } : {}),
+      ...(code ? { code } : {}),
+      ...(status !== null ? { status } : {}),
+      ...(providerCode ? { providerCode } : {}),
+      ...(message ? { message } : {}),
+    };
+  });
+}
+
+function publicReference(value) {
+  return PUBLIC_REFERENCE_PATTERN.test(value ?? '')
+    ? value
+    : `DT-CONN-${randomUUID().replaceAll('-', '').slice(0, 8).toUpperCase()}`;
+}
+
+function fixedPublicError(code, message, hint, referenceId) {
+  return Object.freeze({ code, message: t(message), hint: t(hint), referenceId });
+}
+
+/** Adds a stable startup stage without discarding the original exception as `cause`. */
+export function dingtalkRuntimeStartError(code, cause) {
+  if (cause?.name === 'AbortError' || STAGE_CODES.has(cause?.code)) return cause;
+  const error = new Error(
+    nonEmptyString(cause?.message) ?? 'DingTalk runtime startup failed',
+    { cause },
+  );
+  error.name = 'DingtalkRuntimeStartError';
+  error.code = STAGE_CODES.has(code) ? code : 'dingtalk-runtime-prepare-failed';
+  return error;
+}
+
+/** Creates browser-safe guidance plus a redacted Host-log diagnostic for one connection failure. */
+export function describeDingtalkConnectionFailure(error, {
+  fallbackMessage = '钉钉连接未就绪，请稍后重试。',
+  clientId,
+  clientSecret,
+  environment = process.env,
+  dependencies = installedDingtalkConnectionDependencies(),
+  nodeVersion = process.versions.node,
+  referenceId: suppliedReferenceId,
+} = {}) {
+  const referenceId = publicReference(suppliedReferenceId);
+  const chain = errorChain(error);
+  const codes = new Set(chain
+    .map((entry) => nonEmptyString(entry?.code, 100)?.toUpperCase())
+    .filter(Boolean));
+  const messages = chain
+    .map((entry) => nonEmptyString(entry?.message)?.toLowerCase())
+    .filter(Boolean);
+  const statuses = chain.map(statusFrom).filter((status) => status !== null);
+  const stage = chain.map((entry) => entry?.code).find((code) => STAGE_CODES.has(code)) ?? null;
+  const proxyVariables = PROXY_VARIABLES.filter((name) => nonEmptyString(environment?.[name], 4_096));
+  const proxyConfigured = proxyVariables.length > 0;
+  const versions = safeDependencyVersions(dependencies);
+  const messageContains = (pattern) => messages.some((message) => pattern.test(message));
+  const codeContains = (pattern) => [...codes].some((code) => pattern.test(code));
+  const proxyFailureSignal = statuses.includes(407)
+    || codeContains(/(?:PROXY|ERR_INVALID_PROTOCOL)/u)
+    || messageContains(/proxy|tunneling socket/u);
+
+  let publicError;
+  if (stage === 'dingtalk-stream-connect-failed'
+    && proxyConfigured
+    && versions.agentBase === '6.0.0') {
+    publicError = fixedPublicError(
+      'stream-proxy-dependency-incompatible',
+      '钉钉 Stream 连接失败：检测到代理依赖 agent-base 6.0.0。',
+      '请将 DSH profile 中的 agent-base@6 固定为 6.0.2 后重新安装依赖，或升级 pnpm 后重新解析 lockfile。',
+      referenceId,
+    );
+  } else if (stage === 'dingtalk-harness-connect-failed') {
+    publicError = fixedPublicError(
+      'harness-unavailable',
+      '插件无法连接本机 Harness。',
+      '请确认 dsh web 正常运行，并查看 dsh web 日志中相同参考号对应的诊断信息。',
+      referenceId,
+    );
+  } else if (stage === 'dingtalk-stream-client-load-failed') {
+    publicError = fixedPublicError(
+      'stream-sdk-load-failed',
+      '钉钉 Stream SDK 加载失败。',
+      '请重新安装当前 DSH profile 的插件依赖，并查看 dsh web 日志中相同参考号对应的诊断信息。',
+      referenceId,
+    );
+  } else if (statuses.some((status) => status === 401 || status === 403)) {
+    publicError = fixedPublicError(
+      'stream-credentials-rejected',
+      '钉钉拒绝了当前应用凭据。',
+      '请核对 Client ID、Client Secret 和机器人权限后重试。',
+      referenceId,
+    );
+  } else if (codeContains(/(?:TIMEOUT|ETIMEDOUT)/u) || messageContains(/timed? out|timeout/u)) {
+    publicError = fixedPublicError(
+      'stream-handshake-timeout',
+      '连接钉钉 Stream 超时。',
+      '请检查网络、代理和防火墙后重试；详细原因可在 dsh web 日志中按参考号查找。',
+      referenceId,
+    );
+  } else if (codeContains(/^(?:ENOTFOUND|EAI_AGAIN)$/u)) {
+    publicError = fixedPublicError(
+      'stream-dns-failed',
+      '无法解析钉钉服务地址。',
+      '请检查 DNS、网络和代理设置；详细原因可在 dsh web 日志中按参考号查找。',
+      referenceId,
+    );
+  } else if (codeContains(/(?:CERT|TLS|SSL|UNABLE_TO_VERIFY)/u)) {
+    publicError = fixedPublicError(
+      'stream-tls-failed',
+      '钉钉 Stream 的 TLS 连接校验失败。',
+      '请检查系统证书、代理证书或 HTTPS 中间代理；详细原因可在 dsh web 日志中按参考号查找。',
+      referenceId,
+    );
+  } else if (stage === 'dingtalk-stream-connect-failed'
+    && proxyFailureSignal) {
+    publicError = fixedPublicError(
+      'stream-proxy-failed',
+      '钉钉 Stream 无法通过当前代理建立连接。',
+      '请检查 HTTP_PROXY、HTTPS_PROXY、NO_PROXY 和代理连通性；详细原因可在 dsh web 日志中按参考号查找。',
+      referenceId,
+    );
+  } else if (stage === 'dingtalk-stream-connect-failed') {
+    publicError = fixedPublicError(
+      'stream-connect-failed',
+      '钉钉 Stream 消息连接建立失败。',
+      '请检查网络和机器人配置；详细原因可在 dsh web 日志中按参考号查找。',
+      referenceId,
+    );
+  } else if (stage === 'dingtalk-stream-listener-failed') {
+    publicError = fixedPublicError(
+      'stream-listener-failed',
+      '钉钉 Stream 消息监听初始化失败。',
+      '请确认 dsh-im 与 dingtalk-stream 版本兼容，并按参考号查看 dsh web 日志。',
+      referenceId,
+    );
+  } else if (stage === 'dingtalk-runtime-prepare-failed') {
+    publicError = fixedPublicError(
+      'runtime-prepare-failed',
+      '钉钉机器人运行环境初始化失败。',
+      '请检查 DSH 数据目录、工作区和插件依赖，并按参考号查看 dsh web 日志。',
+      referenceId,
+    );
+  } else {
+    publicError = fixedPublicError(
+      'connection-failed',
+      fallbackMessage,
+      '请在 dsh web 日志中查找相同参考号，以获取已脱敏的具体错误。',
+      referenceId,
+    );
+  }
+
+  return Object.freeze({
+    publicError,
+    diagnostic: Object.freeze({
+      referenceId,
+      category: publicError.code,
+      stage,
+      runtime: { node: safeVersion(nodeVersion) },
+      proxy: { configured: proxyConfigured, variables: proxyVariables },
+      dependencies: versions,
+      errors: diagnosticErrors(chain, [clientId, clientSecret]),
+    }),
+  });
+}
+
+/** Carries only a pre-built public projection across the Host RPC boundary. */
+export function dingtalkPublicConnectionError(publicError, cause) {
+  const error = new Error(publicError.message, { cause });
+  error.name = 'DingtalkPublicConnectionError';
+  error.code = publicError.code;
+  error.publicError = structuredClone(publicError);
+  return error;
+}