@xmanrui/dsh-im 4.22.0 → 4.24.0

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

@@ -0,0 +1,191 @@
+import { randomUUID } from 'node:crypto';
+import packageInfo from '../../../package.json' with { type: 'json' };
+import { normalizeDiagnosticDetails } from './diagnostic-details.mjs';
+import { t } from './i18n.mjs';
+
+const reported = new WeakMap();
+const lastReport = new WeakMap();
+const stages = new WeakMap();
+const OWNED_REASONS = { 'connect-timeout': 'timeout', 'telegram-timeout': 'timeout', 'cli-timeout': 'timeout', 'telegram-response-invalid': 'invalid-response', 'office-protocol-mismatch': 'invalid-response' };
+const STANDARD_NAMES = new Set(['Error', 'TypeError', 'SyntaxError', 'AggregateError', 'DOMException', 'AxiosError', 'TimeoutError', 'AbortError']);
+const KNOWN_MESSAGES = {
+  'discord-401': 'Discord Bot Token 无效，请重新填写。',
+  'discord-intents': 'Discord Gateway Intents 配置不正确，请检查 Developer Portal 的 Bot 设置。',
+  'webhook-configured': '该 Telegram 机器人已配置 Webhook，请先在原服务中移除 Webhook 后重试。',
+  'invalid-device-token': 'AI Office Device Token 无效。',
+  'office-hook-unavailable': 'AI Office Hook 尚未上线或地址不正确。',
+  'messages-database-permission-required': '请在 macOS 系统设置中授予 DSH 完全磁盘访问权限，以读取 Messages 数据库。',
+  'messages-automation-permission-required': '请在 macOS 系统设置中允许 DSH 自动控制 Messages。',
+  'messages-permission-required': '先在 macOS 系统设置中授予 Messages 权限。',
+};
+
+/** Inspect a bounded error graph, including SDK aggregate failures. Never copy exception text. */
+export function connectionErrorChain(error) {
+  const queue = [error], seen = new Set(), chain = [];
+  while (queue.length && chain.length < 16) {
+    const entry = queue.shift();
+    if (!entry || typeof entry !== 'object' || seen.has(entry)) continue;
+    seen.add(entry);
+    chain.push(entry);
+    if (entry.cause && typeof entry.cause === 'object') queue.push(entry.cause);
+    if (Array.isArray(entry.errors)) queue.push(...entry.errors.slice(0, 16));
+  }
+  return { chain, truncated: queue.some(e => e && typeof e === 'object' && !seen.has(e)) || chain.some(e => Array.isArray(e.errors) && e.errors.length > 16) };
+}
+
+export function extractConnectionEvidence(error) {
+  const { chain, truncated } = connectionErrorChain(error);
+  const errors = chain.map(e => ({
+    type: STANDARD_NAMES.has(e.name) ? e.name : 'Error',
+    ...normalizeDiagnosticDetails({
+      reason: OWNED_REASONS[e.code] ?? e.code ?? (e.name === 'TimeoutError' ? 'timeout' : e instanceof SyntaxError ? 'invalid-json' : undefined),
+      httpStatus: e.status ?? e.statusCode ?? e.response?.status,
+      providerCode: e.providerCode,
+    }),
+    hasCause: Boolean(e.cause && typeof e.cause === 'object'),
+    hasErrors: Array.isArray(e.errors),
+  }));
+  const allReasons = [...new Set(errors.map(e => e.reason).filter(r => r && !['unknown', 'multiple-causes'].includes(r)))];
+  const precise = allReasons.filter(r => !['timeout', 'http-error', 'provider-rejected', 'invalid-response'].includes(r));
+  const reasons = precise.length ? precise : allReasons;
+  const first = field => chain.map(e => normalizeDiagnosticDetails({ [field]: e[field] })[field]).find(v => v !== undefined);
+  return {
+    chain, errors,
+    details: normalizeDiagnosticDetails({
+      reason: reasons.length > 1 ? 'multiple-causes' : reasons[0] ?? 'unknown',
+      ...(reasons.length > 1 ? { reasons } : {}),
+      httpStatus: errors.find(e => e.httpStatus !== undefined)?.httpStatus,
+      providerCode: errors.find(e => e.providerCode !== undefined)?.providerCode,
+      durationMs: first('durationMs'), timeoutMs: first('timeoutMs'), host: first('host'), truncated,
+    }),
+  };
+}
+
+export async function atConnectionStage(stage, operation, resource) {
+  try { return await operation(); }
+  catch (error) { throw connectionStageError(error, stage, resource); }
+}
+
+export function connectionStageError(cause, stage, resource) {
+  if (!cause || typeof cause !== 'object') cause = new Error('Operation failed');
+  if (!stages.has(cause)) stages.set(cause, normalizeDiagnosticDetails({ stage, resource }));
+  return cause;
+}
+
+/** Reuse the Controller's report when the same exception reaches RPC. */
+export function reportedConnectionError(error) {
+  return connectionErrorChain(error).chain.map(e => reported.get(e) ?? lastReport.get(e)).find(Boolean);
+}
+
+export function diagnosticRpcResult(diagnostics, cause, result, context) {
+  if (cause?.name === 'AbortError') return { ok: false, error: { code: 'cancelled', message: t('操作已取消。'), details: {} } };
+  if (result?.ok !== false || ['cancelled', 'bad-request'].includes(result.error?.code)) return result;
+  const error = reportedConnectionError(cause) ?? diagnostics.report(cause, { ...context, publicError: result.error });
+  return { ...result, error: context?.untrustedPublicError ? error.publicError : { ...error.publicError, ...result.error, details: error.publicError.details } };
+}
+
+export function connectionHint(details) {
+  const r = details.reason;
+  if (r === 'multiple-causes') return t('检测到多个底层原因，请展开诊断详情逐项检查。');
+  if (['ENOTFOUND', 'EAI_AGAIN'].includes(r)) return t('服务域名解析失败，请检查运行 DSH 的机器的 DNS 和网络设置。');
+  if (r === 'ECONNREFUSED') return t('目标拒绝连接，请检查服务地址、端口和访问限制。');
+  if (['ECONNRESET', 'EPIPE', 'UND_ERR_SOCKET'].includes(r)) return t('连接已中断，请检查网络和目标服务状态。');
+  if (['ENETUNREACH', 'EHOSTUNREACH', 'ERR_NETWORK_ACCESS_DENIED'].includes(r)) return t('目标网络不可达，请检查运行 DSH 的机器的网络出口和访问限制。');
+  if (/CERT|TLS|SSL|ISSUER|SIGNATURE/.test(r ?? '')) return t('TLS 或证书校验失败，请检查系统时间、证书链和网络设置。');
+  if (/TIMEOUT/.test(r ?? '') || r === 'ETIMEDOUT' || r === 'timeout') return t('请求超时，请检查目标服务和网络；诊断详情中可查看已知的耗时。');
+  if (r === 'ERR_PROXY_CONNECTION_FAILED' || details.httpStatus === 407) return t('代理连接或认证失败，请检查 DSH 进程使用的代理配置。');
+  if (['EAUTH', 'AUTHENTICATIONFAILED'].includes(r)) return t('服务认证失败，请检查账号和授权信息。');
+  if (['EACCES', 'EPERM', 'EROFS'].includes(r)) return t('操作权限不足，请检查对应资源的访问权限。');
+  if (r === 'ENOSPC') return t('磁盘空间不足，请释放空间后重试。');
+  if (r === 'ENOENT') return t('所需文件或本地工具不存在，请检查安装和配置。');
+  if (r === 'invalid-json' || r === 'invalid-response') return t('数据格式无效，请按失败阶段检查服务响应或本地配置。');
+  if (details.httpStatus === 429) return t('服务正在限流，请稍后重试。');
+  if ([401, 403].includes(details.httpStatus)) return t('服务拒绝了请求，请检查凭据、权限或访问限制；HTTP 状态本身不能确认登录失效。');
+  if (details.httpStatus >= 500) return t('目标服务暂时异常，请稍后重试。');
+  if (details.httpStatus) return t('目标服务返回了 HTTP 错误，请查看诊断详情。');
+  return t('暂未识别具体原因，请复制诊断信息，并查看相同参考号的 DSH 日志。');
+}
+
+export function operationStage(operation) {
+  return ({ 'connector.test': 'connection.test', 'connector.configure': 'credential.verify', 'connector.reconnect': 'connection.start', 'connector.remove': 'account.remove', startup: 'startup.load', 'connection.restore': 'connection.start', 'connection.monitor': 'connection.poll',
+    'connection.status': 'status.read', 'connection.close': 'connection.stop', 'provision.begin': 'qr.begin',
+    'provision.poll': 'qr.poll', 'provision.verify': 'qr.verify', 'bot.auth.start': 'qr.begin', 'bot.auth.poll': 'qr.poll',
+    'bot.reconnect': 'connection.start', 'bot.delete': 'account.remove', 'permissions.status': 'permission.check',
+    'bot.bind-credentials': 'credential.verify', 'bot.bind-mailbox': 'credential.verify', 'bot.bind-native': 'permission.check',
+    'connection.test': 'connection.test', 'message.send': 'message.send', 'message.receive': 'message.receive',
+  })[operation] ?? 'operation';
+}
+
+/** One reporter per channel owner. Existing safe business guidance can be supplied as publicError. */
+export function createConnectionDiagnostics({ channel, logger = console, now = Date.now, prefix = 'IM-CONN', describe } = {}) {
+  const recent = new Map();
+  const write = (level, record) => { try { logger[level]?.(`[dsh-${channel}] ${JSON.stringify(record)}`); } catch { /* Logging cannot break an operation. */ } };
+  function report(cause, context = {}) {
+    if (reported.has(cause)) return cause;
+    if (context.reuse && reportedConnectionError(cause)) return reportedConnectionError(cause);
+    const evidence = extractConnectionEvidence(cause);
+    const prior = evidence.chain.map(e => reported.get(e)).find(Boolean);
+    if (prior) return prior;
+    const described = describe?.(cause, context, evidence) ?? {};
+    const known = evidence.chain.find(e => Object.hasOwn(KNOWN_MESSAGES, e.code ?? ''));
+    let safe = described.publicError ?? context.publicError ?? {};
+    if (known && !safe.code?.startsWith('stream-')) safe = { ...safe, code: known.code, message: t(KNOWN_MESSAGES[known.code]) };
+    // These legacy handlers used exception messages as their public error. Keep only owned guidance.
+    if (['email', 'imessage', 'office'].includes(channel) && !known && context.untrustedPublicError) {
+      safe = { code: `${channel}-operation-failed`, message: t('操作失败，请查看原因和诊断详情。') };
+    }
+    const owned = evidence.chain.map(e => stages.get(e)).find(Boolean) ?? {};
+    const details = normalizeDiagnosticDetails({
+      ...evidence.details, ...context, ...safe.details, ...described.details, ...owned,
+      channel, stage: owned.stage ?? described.details?.stage ?? safe.details?.stage ?? context.stage ?? operationStage(context.operation),
+      pluginVersion: packageInfo.version, nodeVersion: process.versions.node, platform: process.platform,
+    });
+    const code = safe.code ?? context.code ?? `${channel}-operation-failed`;
+    const hint = described.hint ?? safe.hint ?? safe.details?.hint ?? connectionHint(details);
+    const message = t(safe.message) ?? t('操作失败，请查看原因和诊断详情。');
+    const key = JSON.stringify([context.botId, context.attemptId, details.operation, details.stage, code, details.reason, details.reasons, details.httpStatus, details.providerCode, details.resource, details.file, details.field, details.issue]);
+    const previous = recent.get(key), time = now();
+    const wrap = publicError => {
+      const error = new Error(publicError.message, { cause });
+      error.code = publicError.code;
+      error.publicError = structuredClone(publicError);
+      reported.set(error, error);
+      if (cause && typeof cause === 'object') lastReport.set(cause, error);
+      return error;
+    };
+    if (context.automatic && previous && time - previous.time < 60_000) {
+      previous.retries += 1;
+      return wrap(previous.publicError);
+    }
+    if (previous?.retries) write('warn', { event: 'connection-retries', referenceId: previous.publicError.details.referenceId, retries: previous.retries });
+    details.referenceId = normalizeDiagnosticDetails({ referenceId: safe.referenceId }).referenceId ?? `${prefix}-${randomUUID().replaceAll('-', '').slice(0, 8).toUpperCase()}`;
+    details.occurredAt = new Date(time).toISOString();
+    details.hint = hint;
+    const publicError = { code, message, details };
+    if (context.automatic) {
+      if (recent.size >= 128) recent.delete(recent.keys().next().value);
+      recent.set(key, { time, publicError, retries: 0, botId: context.botId });
+    }
+    write(context.warning ? 'warn' : 'error', {
+      event: context.warning ? 'connection-warning' : 'connection-failure', code, ...details,
+      errors: evidence.errors,
+      ...(normalizeDiagnosticDetails({ referenceId: context.parentReferenceId }).referenceId ? { parentReferenceId: context.parentReferenceId } : {}),
+    });
+    return wrap(publicError);
+  }
+  function clear(botId) {
+    for (const [key, entry] of recent) {
+      if (botId !== undefined && entry.botId !== botId) continue;
+      if (entry.retries) write('info', { event: 'connection-retries', referenceId: entry.publicError.details.referenceId, retries: entry.retries });
+      recent.delete(key);
+    }
+  }
+  function outcome(error, rollback) {
+    if (!reported.has(error)) return;
+    if (!normalizeDiagnosticDetails({ rollback }).rollback) return;
+    error.publicError.details.rollback = rollback;
+    error.publicError.details.hint = rollback === 'succeeded' ? t('操作未完成，已恢复之前的本机状态。请处理上述问题后重试。') : t('原账号状态尚未确认，请重新读取状态，并反馈诊断信息。');
+    write('info', { event: 'connection-outcome', referenceId: error.publicError.details.referenceId, rollback });
+  }
+  return { report, clear, outcome };
+}

package/src/channels/shared/connection-test.mjs

@@ -45,12 +45,14 @@ export async function sendRememberedConnectionTest({ state, send, text, channelL
   return { sent: true };
 }
 
-export function publicConnectionTestResult(error) {
+export function publicConnectionTestResult(error, { diagnostics, botId } = {}) {
   if (!error) return Object.freeze({ sent: true });
   return Object.freeze({
     sent: false,
     code: error?.code === 'test-target-unavailable'
       ? 'test-target-unavailable'
       : 'test-message-failed',
+    ...(diagnostics && error?.code !== 'test-target-unavailable'
+      ? { error: diagnostics.report(error, { operation: 'connection.test', stage: 'connection.test', botId }).publicError } : {}),
   });
 }

package/src/channels/shared/conversation-state-store.mjs

@@ -2,6 +2,14 @@ import { deferredStateAccess, normalizeDeferredState } from './deferred-state.mj
 import { mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
 import { dirname } from 'node:path';
 
+/**
+ * Additional persisted keys a subclass may own. Kept intentionally small and
+ * explicit: a subclass reads and writes them through extensionState().
+ */
+const EXTENSION_KEYS = Object.freeze([
+  'emailBindings', 'mailCursor', 'pendingAuth', 'threadIds',
+]);
+
 const EMPTY_STATE = Object.freeze({ version: 1, sessions: {}, seenMessageIds: [], cursor: null });
 
 function normalizeState(value) {
@@ -14,7 +22,7 @@ function normalizeState(value) {
       }
     }
   }
-  return {
+  const normalized = {
     version: 1,
     sessions,
     ...(value.deferred ? { deferred: normalizeDeferredState(value.deferred) } : {}),
@@ -23,6 +31,12 @@ function normalizeState(value) {
       : [],
     cursor: Number.isSafeInteger(value.cursor) && value.cursor >= 0 ? value.cursor : null,
   };
+  // Channel-specific extensions survive a reload; each is normalized by the
+  // subclass that owns it (see extensionKeys()).
+  for (const key of EXTENSION_KEYS) {
+    if (Object.hasOwn(value, key)) normalized[key] = value[key];
+  }
+  return normalized;
 }
 
 export class ConversationStateStore {
@@ -83,6 +97,23 @@ export class ConversationStateStore {
     await this.#persist();
   }
 
+  /**
+   * Take back a `markSeen` whose delivery never happened.
+   *
+   * `markSeen` means "this message was handled". A turn that failed before
+   * producing anything is not handled, so keeping the mark makes the id a
+   * permanent tombstone: every later poll short-circuits on `hasSeen` and the
+   * mail is never retried. The bridge calls this to separate "attempted" from
+   * "done". A message that already succeeded is never unmarked.
+   */
+  async unmarkSeen(messageId) {
+    const index = this.#state.seenMessageIds.indexOf(messageId);
+    if (index === -1) return false;
+    this.#state.seenMessageIds.splice(index, 1);
+    await this.#persist();
+    return true;
+  }
+
   cursor() {
     return this.#state.cursor;
   }
@@ -97,6 +128,20 @@ export class ConversationStateStore {
     return structuredClone(this.#state);
   }
 
+  /**
+   * Live view of the private state for subclasses that persist their own keys.
+   * Returns the real object (not a clone) so an extension can be written in
+   * place; call persist() afterwards.
+   */
+  extensionState() {
+    return this.#state;
+  }
+
+  /** Flush the current state to disk after an extension write. */
+  persist() {
+    return this.#persist();
+  }
+
   async remove() {
     try {
       await unlink(this.#path);

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

@@ -0,0 +1,95 @@
+// Shared by Host and Client: only explicitly admitted diagnostic facts cross the UI boundary.
+const OPERATIONS = new Set([
+  'bot.bind-credentials', 'bot.bind-native', 'bot.bind-mailbox', 'bot.mailbox.update', 'bot.auth.start', 'bot.auth.poll',
+  'permissions.status', 'bot.session-binding.get', 'bot.session-binding.set', 'bot.session.list', 'connection.test', 'message.receive', 'message.send',
+  'connector.configure', 'connector.reconnect', 'connector.test', 'connector.remove', 'startup', 'connection.restore', 'connection.monitor', 'connection.close', 'connection.status',
+  'provision.begin', 'provision.poll', 'provision.verify', 'provision.cancel', 'bot.reconnect', 'bot.delete',
+  'bot.workspace.set', 'bot.model.set', 'bot.agent-preset.set', 'bot.context-enhancement.set', 'bot.access-policy.set', 'bot.alias.set',
+]);
+const STAGES = new Set([
+  'credential.verify', 'permission.check', 'sdk.load', 'operation', 'message.receive', 'message.send', 'connection.test', 'startup.load', 'qr.begin', 'qr.encode', 'qr.poll', 'qr.verify', 'qr.cancel', 'credential.read', 'credential.save', 'credential.remove',
+  'account.save', 'account.remove', 'state.load', 'state.write', 'state.cleanup', 'workspace.write', 'workspace.cleanup',
+  'runtime.prepare', 'activation', 'harness.check', 'connection.start', 'connection.poll', 'connection.stop', 'status.read', 'rollback', 'management.request',
+]);
+const REASONS = new Set([
+  'ENOTFOUND', 'EAI_AGAIN', 'ECONNREFUSED', 'ECONNRESET', 'EHOSTUNREACH', 'ENETUNREACH', 'ETIMEDOUT', 'EPIPE',
+  'UND_ERR_CONNECT_TIMEOUT', 'UND_ERR_HEADERS_TIMEOUT', 'UND_ERR_BODY_TIMEOUT', 'UND_ERR_SOCKET',
+  'CERT_HAS_EXPIRED', 'CERT_NOT_YET_VALID', 'DEPTH_ZERO_SELF_SIGNED_CERT', 'SELF_SIGNED_CERT_IN_CHAIN',
+  'UNABLE_TO_VERIFY_LEAF_SIGNATURE', 'UNABLE_TO_GET_ISSUER_CERT_LOCALLY', 'ERR_TLS_CERT_ALTNAME_INVALID', 'ERR_SSL_WRONG_VERSION_NUMBER',
+  'ENOENT', 'EACCES', 'EPERM', 'ENOSPC', 'EROFS', 'ENOTDIR', 'EISDIR', 'EBUSY', 'EIO', 'EXDEV', 'EMFILE', 'ENFILE', 'EEXIST',
+  'unknown', 'multiple-causes', 'timeout', 'http-error', 'provider-rejected', 'invalid-response', 'ERR_PROXY_CONNECTION_FAILED', 'ERR_TLS_HANDSHAKE_TIMEOUT', 'ERR_SSL_TLSV1_ALERT_INTERNAL_ERROR', 'ERR_NETWORK_ACCESS_DENIED', 'AUTHENTICATIONFAILED', 'EAUTH', 'invalid-json', 'invalid-config', 'read-only',
+]);
+const RESOURCES = new Set(['credential-store', 'account-config', 'account-state', 'workspace-config', 'workspace-directory']);
+const CONFIG_FILES = new Set(['config.json', 'workspaces.json']);
+export const CONFIG_ISSUE_LABELS = Object.freeze({
+  'expected-object': '应为 JSON 对象。',
+  'expected-array': '应为 JSON 数组。',
+  'unsupported-version': '配置版本缺失或不受当前插件支持。',
+  'invalid-string': '字段缺失或不是非空字符串。',
+  'invalid-identifier': '标识符格式不符合要求。',
+  'identity-mismatch': '标识符与 accountId 派生结果不一致。',
+  'duplicate-identity': '账号标识重复。',
+  'invalid-api-url': '微信服务地址不是有效 URL。',
+  'untrusted-api-url': '微信服务地址必须使用受信任的 HTTPS 域名和端口。',
+  'invalid-workspace-path': '工作区路径必须是当前操作系统的绝对路径。',
+  'invalid-agent-preset': 'Agent Preset 标识无效。',
+  'invalid-model-selection': '模型设置须包含有效的 provider、model 和可选 reasoningEffort。',
+  'invalid-delivery-target': '投递目标的标识、结构或路由不符合当前配置版本要求。',
+  'unexpected-field': '当前配置版本不允许此字段。',
+});
+// Only schema-owned field names and numeric entry positions may leave the Host.
+// Map keys are replaced with zero-based positions to avoid exposing identities.
+const CONFIG_FIELD = /^(?:\$|version|accounts(?:\[\d{1,10}\](?:\.(?:accountId|ownerUserId|botId|tokenRef|baseUrl))?)?|(?:workspaces|agentPresets|models)(?:\[\d{1,10}\]\.(?:key|value))?|deliveryTargets(?:\[\d{1,10}\]\.(?:key|targets(?:\[\d{1,10}\])?))?)$/;
+
+export function normalizeDiagnosticDetails(value) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
+  const result = {};
+  for (const [field, allowed] of [['operation', OPERATIONS], ['stage', STAGES], ['reason', REASONS], ['resource', RESOURCES]]) {
+    if (allowed.has(value[field])) result[field] = value[field];
+  }
+  if (DIAGNOSTIC_CHANNELS.includes(value.channel)) result.channel = value.channel;
+  if (Array.isArray(value.reasons)) {
+    const reasons = [...new Set(value.reasons.filter(v => REASONS.has(v) && !['unknown', 'multiple-causes'].includes(v)))].slice(0, 16);
+    if (reasons.length) result.reasons = reasons;
+  }
+  for (const field of ['durationMs', 'timeoutMs']) if (Number.isFinite(value[field]) && value[field] >= 0) result[field] = Math.round(value[field]);
+  for (const field of ['nodeVersion', 'dshVersion']) if (typeof value[field] === 'string' && /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value[field]) && value[field].length < 80) result[field] = value[field];
+  if (['darwin', 'linux', 'win32', 'freebsd'].includes(value.platform)) result.platform = value.platform;
+  if (['ilinkai.weixin.qq.com', 'oapi.dingtalk.com', 'api.dingtalk.com', 'api.telegram.org', 'discord.com', 'slack.com', 'open.feishu.cn', 'qyapi.weixin.qq.com'].includes(value.host)) result.host = value.host;
+  if (value.dependencies && typeof value.dependencies === 'object') {
+    const dependencies = {};
+    for (const name of ['dingtalkStream', 'axios', 'httpsProxyAgent', 'agentBase']) {
+      const version = value.dependencies[name];
+      if (typeof version === 'string' && /^\d+\.\d+\.\d+(?:[-+][A-Za-z0-9.-]+)?$/.test(version) && version.length <= 80) dependencies[name] = version;
+    }
+    if (Object.keys(dependencies).length) result.dependencies = dependencies;
+  }
+  if (typeof value.proxyConfigured === 'boolean') result.proxyConfigured = value.proxyConfigured;
+  if (value.truncated === true) result.truncated = true;
+  if (CONFIG_FILES.has(value.file)) result.file = value.file;
+  if (typeof value.field === 'string' && CONFIG_FIELD.test(value.field)) result.field = value.field;
+  if (typeof value.issue === 'string' && Object.hasOwn(CONFIG_ISSUE_LABELS, value.issue)) result.issue = value.issue;
+  if (/^(?:(?:WX|DT|IM)-CONN|MF)-[A-F0-9]{8}$/.test(value.referenceId ?? '')) result.referenceId = value.referenceId;
+  if (typeof value.occurredAt === 'string' && /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/.test(value.occurredAt)
+    && Number.isFinite(Date.parse(value.occurredAt))) result.occurredAt = value.occurredAt;
+  if (Number.isInteger(value.httpStatus) && value.httpStatus >= 100 && value.httpStatus <= 599) result.httpStatus = value.httpStatus;
+  const provider = typeof value.providerCode === 'number' && Number.isSafeInteger(value.providerCode)
+    ? String(value.providerCode) : value.providerCode;
+  if (typeof provider === 'string' && /^-?\d{1,12}$/.test(provider)) result.providerCode = provider;
+  if (typeof value.pluginVersion === 'string' && /^\d+\.\d+\.\d+(?:-[A-Za-z0-9.-]+)?$/.test(value.pluginVersion)
+    && value.pluginVersion.length <= 64) result.pluginVersion = value.pluginVersion;
+  if (['succeeded', 'failed', 'not-attempted', 'unknown'].includes(value.rollback)) result.rollback = value.rollback;
+  if (typeof value.hint === 'string' && value.hint.trim()) result.hint = value.hint.trim().slice(0, 500);
+  return result;
+}
+
+export const DIAGNOSTIC_CHANNELS = Object.freeze(['weixin', 'feishu', 'dingtalk', 'wecom', 'qq', 'slack', 'telegram', 'discord', 'whatsapp', 'wecom-app', 'imessage', 'email', 'office']);
+
+export function diagnosticFields(value) {
+  if (!value?.details) return {};
+  const details = normalizeDiagnosticDetails({ ...value?.details,
+    referenceId: value?.details?.referenceId ?? value?.referenceId,
+    hint: value?.details?.hint ?? value?.hint,
+  });
+  return Object.keys(details).length ? { details } : {};
+}