@xmanrui/dsh-im 0.1.0

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

@@ -0,0 +1,402 @@
+import * as React from 'react';
+
+import { WecomLogoGlyph } from '../../channel-logos.js';
+import { CredentialActionIcon, CredentialBindingPanel, QrActionIcon } from '../../credential-binding.js';
+import { installDingtalkStyles } from '../dingtalk/styles.js';
+import {
+  WECOM_ENDPOINTS,
+  WECOM_RPC_CHANNEL,
+  formatRemaining,
+  normalizeProvisioning,
+  normalizeSnapshot,
+  presentError,
+  safeQrSource,
+  unwrapRpcResult,
+} from './api.js';
+import { installWecomStyles } from './styles.js';
+
+const h = React.createElement;
+const ACTIVE_STATES = new Set(['pending', 'refreshing', 'connecting']);
+
+const Button = React.forwardRef(function Button({ children, kind = 'secondary', className = '', ...props }, ref) {
+  return h('button', {
+    ...props,
+    ref,
+    type: 'button',
+    className: `ddt-button ${className}`.trim(),
+    'data-kind': kind,
+  }, children);
+});
+
+function checkedTime(value) {
+  if (!value) return '尚未检查';
+  try {
+    return new Intl.DateTimeFormat('zh-CN', {
+      hour: '2-digit', minute: '2-digit', second: '2-digit',
+    }).format(new Date(value));
+  } catch {
+    return '刚刚';
+  }
+}
+
+function Heading({ totals, adding, busy, onAdd, onCredential, credentialOpen, addButtonRef }) {
+  return h('div', { className: 'ddt-heading' },
+    h('div', { className: 'ddt-tools' },
+      h('div', { className: 'dim-bindActions' },
+        h(Button, {
+          kind: 'primary',
+          className: 'dim-scanButton',
+          onClick: onAdd,
+          disabled: adding || busy,
+          ref: addButtonRef,
+          'aria-label': '扫码接入企业微信机器人',
+        }, h(QrActionIcon), adding ? '正在接入' : '扫码接入机器人'),
+        h(Button, {
+          kind: 'credential',
+          className: 'dim-credentialButton',
+          onClick: onCredential,
+          disabled: adding || busy,
+          'aria-pressed': credentialOpen,
+          'aria-label': '使用 Bot ID 和 Secret 绑定企业微信机器人',
+        }, h(CredentialActionIcon), credentialOpen ? '收起凭据' : '手动接入')),
+      totals.configured > 0
+        ? h('div', { className: 'ddt-badge dim-onlineBadge' },
+            h('span', null, `${totals.connected} / ${totals.configured} 在线`))
+        : null));
+}
+
+function LoadingView() {
+  return h('div', { className: 'ddt-card ddt-loading dim-surfaceCard dim-loadingView', 'aria-busy': 'true' },
+    h('div', { className: 'ddt-spinner dim-spinner' }),
+    h('span', null, '正在读取企业微信机器人状态…'));
+}
+
+function EmptyView({ busy, onStart }) {
+  return h('div', { className: 'ddt-card dim-surfaceCard' },
+    h('div', { className: 'ddt-cardBody ddt-empty dim-surfaceBody dim-emptyView' },
+      h('div', { className: 'dim-emptyCopy' },
+        h('div', { className: 'ddt-stateLabel dim-stateLabel' },
+          h('span', { className: 'ddt-dot dim-stateDot' }), h('span', null, '尚未绑定企业微信机器人')),
+        h('h3', null, '使用企业微信 App 扫码创建智能机器人'),
+        h('p', null, '扫码由腾讯官方页面完成，不需要手动填写 Bot ID 或 Secret。创建成功后，机器人会自动连接 DeepSeek Harness。'),
+        h('div', { className: 'ddt-actions dim-viewActions' },
+          h(Button, { kind: 'primary', onClick: onStart, disabled: busy },
+            busy ? '正在生成二维码…' : '生成企业微信二维码'))),
+      h('div', { className: 'ddt-brandMark dim-emptyBrand dwecom-brand', 'aria-hidden': 'true' },
+        h(WecomLogoGlyph, { size: 64 }))));
+}
+
+function QrPanel({ provision, now, busy, onRefresh, onCancel }) {
+  const source = safeQrSource(provision.qrCodeDataUrl);
+  const remaining = Math.max(0, provision.expiresAt - now);
+  const duration = Math.max(1, provision.durationMs ?? 5 * 60_000);
+  const progress = Math.round(Math.min(1, remaining / duration) * 100);
+  const refreshing = provision.status === 'refreshing';
+  return h('div', { className: 'ddt-card dim-surfaceCard' },
+    h('div', { className: 'ddt-cardBody ddt-qrLayout dim-surfaceBody dim-qrLayout' },
+      h('div', { className: 'ddt-qrColumn dim-qrColumn' },
+        h('div', { className: 'ddt-qrFrame dim-qrFrame' },
+          source ? h('img', { src: source, alt: '用于绑定企业微信机器人的一次性二维码' })
+            : h('div', { className: 'ddt-qrFallback dim-qrFallback' },
+                refreshing ? '二维码正在自动刷新…' : '二维码图片正在生成…')),
+        h('div', { className: 'ddt-countdown dim-countdown' },
+          h('div', { className: 'ddt-countdownTop dim-countdownTop' },
+            h('span', null, '当前二维码有效时间'),
+            h('strong', null, refreshing ? '--:--' : formatRemaining(remaining))),
+          h('div', { className: 'ddt-progress dim-progress', style: { '--ddt-progress': `${progress}%` } }, h('span')))),
+      h('div', { className: 'ddt-qrCopy dim-qrCopy' },
+        h('div', { className: 'ddt-stateLabel dim-stateLabel' },
+          h('span', { className: 'ddt-dot dim-stateDot', 'data-tone': 'warning' }),
+          h('span', null, refreshing ? '正在刷新二维码' : '等待企业微信 App 扫码')),
+        h('h3', null, '使用企业微信 App 完成智能机器人授权'),
+        h('p', null, '企业微信官方页面会创建一个智能机器人，并把连接凭据安全交给本机 Harness Host。'),
+        h('ol', { className: 'ddt-steps dim-steps' },
+          h('li', null, '打开企业微信 App，扫描左侧二维码'),
+          h('li', null, '在腾讯授权页面确认创建智能机器人'),
+          h('li', null, '返回这里等待连接完成')),
+        h('div', { className: 'ddt-actions dim-viewActions' },
+          h(Button, { onClick: onRefresh, disabled: busy }, '重新生成二维码'),
+          h(Button, { kind: 'quiet', onClick: onCancel, disabled: busy }, '取消')))));
+}
+
+function ProvisionView({ provision, busy, onRetry, onClose }) {
+  if (provision.status === 'connecting') {
+    return h('div', { className: 'ddt-card ddt-loading dim-surfaceCard dim-specialView', 'aria-busy': 'true' },
+      h('div', { className: 'ddt-spinner dim-spinner' }),
+      h('h3', null, '企业微信已授权，正在连接机器人'),
+      h('p', null, '凭据正在写入本机，并启动企业微信 WebSocket 消息连接。'));
+  }
+  const error = provision.error ?? { code: 'WECOM_PROVISION_FAILED', message: '企业微信机器人没有绑定完成' };
+  return h('div', { className: 'ddt-card dim-surfaceCard' },
+    h('div', { className: 'ddt-inlineError dim-inlineError', role: 'alert' },
+      h('h3', null, '企业微信机器人没有绑定完成'),
+      h('p', null, error.message),
+      h('span', { className: 'ddt-errorCode' }, error.code),
+      h('div', { className: 'ddt-actions dim-viewActions' },
+        h(Button, { kind: 'primary', onClick: onRetry, disabled: busy }, '重新生成二维码'),
+        h(Button, { onClick: onClose, disabled: busy }, '关闭'))));
+}
+
+function RemoveConfirmation({ account, busy, onConfirm, onCancel }) {
+  return h('div', { className: 'ddt-confirm dim-confirm', role: 'alertdialog' },
+    h('strong', null, `从 DeepSeek Harness 移除“${account.bot.name}”？`),
+    h('p', null, '这会停止消息连接，并删除本机保存的应用凭据、机器人配置及会话映射。企业微信平台中的机器人不会被自动删除。'),
+    h('div', { className: 'ddt-actions dim-viewActions' },
+      h(Button, { onClick: onCancel, disabled: busy }, '保留机器人'),
+      h(Button, { kind: 'danger', onClick: onConfirm, disabled: busy }, busy ? '正在移除…' : '确认移除接入')));
+}
+
+export function AccountCard({ account, busy, removing, onReconnect, onRequestRemove, onConfirmRemove, onCancelRemove }) {
+  const tone = account.connected ? 'success' : account.state === 'error' ? 'error' : 'warning';
+  const stateLabel = account.connected ? '运行正常' : account.state === 'connecting' ? '正在连接' : '连接未就绪';
+  const summary = account.error?.message ?? (account.connected ? null : account.health.summary);
+  return h('article', { className: 'ddt-card dim-botCard', 'data-bot-id': account.botId },
+    h('div', { className: 'ddt-cardBody dim-botCardBody' },
+      h('div', { className: 'ddt-accountTop dim-botCardTop' },
+        h('div', { className: 'ddt-accountIdentity dim-botIdentity' },
+          h('div', { className: 'ddt-avatar dim-botAvatar dwecom-avatar', 'aria-hidden': 'true' }, h(WecomLogoGlyph, { size: 29 })),
+          h('div', { className: 'dim-botName' },
+            h('h3', null, account.bot.name), h('p', null, account.bot.appIdMasked))),
+        h('div', { className: 'ddt-health dim-botHealth' },
+          h('span', { className: 'ddt-dot dim-healthDot', 'data-tone': tone }), h('span', null, stateLabel))),
+      h('dl', { className: 'ddt-metrics dim-botMetrics' },
+        h('div', { className: 'ddt-metric dim-botMetric' }, h('dt', null, '消息通道'), h('dd', null, account.connected ? 'WebSocket 长连接' : '离线')),
+        h('div', { className: 'ddt-metric dim-botMetric' }, h('dt', null, '最近检查'), h('dd', null, checkedTime(account.health.lastCheckedAt)))),
+      h('div', { className: 'ddt-accountFooter dim-cardFooter' },
+        summary ? h('div', { className: 'ddt-summary dim-cardSummary' }, summary) : null,
+        h('div', { className: 'ddt-actions dim-cardActions' },
+          h(Button, { className: 'dim-cardAction', onClick: onReconnect, disabled: Boolean(busy) }, busy === 'reconnect' ? '检查中…' : account.connected ? '检查连接' : '重试连接'),
+          h(Button, { className: 'dim-cardAction', kind: 'danger', onClick: onRequestRemove, disabled: Boolean(busy) }, '移除接入')))),
+    removing ? h(RemoveConfirmation, {
+      account, busy: busy === 'delete', onConfirm: onConfirmRemove, onCancel: onCancelRemove,
+    }) : null);
+}
+
+export function WecomSettingsTab({ rpcCall }) {
+  const [model, setModel] = React.useState({ phase: 'loading', bots: [], totals: { configured: 0, connected: 0 }, error: null });
+  const [provision, setProvision] = React.useState(null);
+  const [busy, setBusy] = React.useState(false);
+  const [busyByBot, setBusyByBot] = React.useState({});
+  const [removeTarget, setRemoveTarget] = React.useState(null);
+  const [credentialOpen, setCredentialOpen] = React.useState(false);
+  const [credentialError, setCredentialError] = React.useState(null);
+  const [now, setNow] = React.useState(Date.now());
+  const mounted = React.useRef(true);
+  const addButtonRef = React.useRef(null);
+
+  React.useEffect(() => {
+    const disposeDingtalk = installDingtalkStyles();
+    const disposeWecom = installWecomStyles();
+    mounted.current = true;
+    return () => {
+      mounted.current = false;
+      disposeWecom();
+      disposeDingtalk();
+    };
+  }, []);
+
+  const invoke = React.useCallback(async (endpoint, payload = {}, signal) => {
+    if (typeof rpcCall !== 'function') throw new TypeError('企业微信设置页缺少 RPC 连接');
+    return unwrapRpcResult(await rpcCall(endpoint, payload, signal));
+  }, [rpcCall]);
+
+  const loadStatus = React.useCallback(async ({ signal, silent = false, restore = false } = {}) => {
+    if (!silent && mounted.current) setModel((current) => ({ ...current, phase: 'loading', error: null }));
+    try {
+      const snapshot = normalizeSnapshot(await invoke(WECOM_ENDPOINTS.status, {}, signal));
+      if (!mounted.current || signal?.aborted) return undefined;
+      setModel({ phase: 'ready', bots: snapshot.bots, totals: snapshot.totals, error: null });
+      if (restore && snapshot.provisioning) setProvision({
+        ...snapshot.provisioning,
+        durationMs: Math.max(1, snapshot.provisioning.expiresAt - Date.now()),
+      });
+      return snapshot;
+    } catch (error) {
+      if (error?.name !== 'AbortError' && mounted.current && !signal?.aborted) {
+        setModel((current) => ({ ...current, phase: silent ? current.phase : 'error', error: presentError(error) }));
+      }
+      return undefined;
+    }
+  }, [invoke]);
+
+  React.useEffect(() => {
+    const controller = new AbortController();
+    void loadStatus({ signal: controller.signal, restore: true });
+    return () => controller.abort();
+  }, [loadStatus]);
+
+  React.useEffect(() => {
+    if (model.phase !== 'ready') return undefined;
+    const controller = new AbortController();
+    const timer = window.setInterval(() => void loadStatus({ signal: controller.signal, silent: true }), 15_000);
+    return () => { controller.abort(); window.clearInterval(timer); };
+  }, [loadStatus, model.phase]);
+
+  React.useEffect(() => {
+    if (!provision || !ACTIVE_STATES.has(provision.status)) return undefined;
+    const timer = window.setInterval(() => mounted.current && setNow(Date.now()), 1_000);
+    return () => window.clearInterval(timer);
+  }, [provision?.attemptId, provision?.status]);
+
+  const startProvisioning = React.useCallback(async (replace = false) => {
+    setCredentialOpen(false);
+    setCredentialError(null);
+    setBusy(true);
+    try {
+      if (replace && provision?.attemptId) await invoke(WECOM_ENDPOINTS.cancelProvisioning, { attemptId: provision.attemptId });
+      if (!mounted.current) return;
+      setProvision({ status: 'starting' });
+      const started = normalizeProvisioning(await invoke(WECOM_ENDPOINTS.beginProvisioning, { locale: 'zh-CN' }));
+      if (!mounted.current) return;
+      setNow(Date.now());
+      setProvision({ ...started, durationMs: Math.max(1, started.expiresAt - Date.now()) });
+    } catch (error) {
+      if (mounted.current) setProvision({ status: 'failed', error: presentError(error) });
+    } finally {
+      if (mounted.current) setBusy(false);
+    }
+  }, [invoke, provision?.attemptId]);
+
+  const bindCredentials = React.useCallback(async ({ identity, secret }) => {
+    setBusy(true);
+    setCredentialError(null);
+    try {
+      const snapshot = normalizeSnapshot(await invoke(
+        WECOM_ENDPOINTS.bindCredentials,
+        { botId: identity, secret },
+      ));
+      if (!mounted.current) return;
+      setModel({ phase: 'ready', bots: snapshot.bots, totals: snapshot.totals, error: null });
+      setCredentialOpen(false);
+    } catch (error) {
+      if (mounted.current) setCredentialError(presentError(error));
+    } finally {
+      if (mounted.current) setBusy(false);
+    }
+  }, [invoke]);
+
+  const closeProvision = React.useCallback(async () => {
+    setBusy(true);
+    try {
+      if (provision?.attemptId && ACTIVE_STATES.has(provision.status)) {
+        await invoke(WECOM_ENDPOINTS.cancelProvisioning, { attemptId: provision.attemptId });
+      }
+      if (mounted.current) setProvision(null);
+    } finally {
+      if (mounted.current) setBusy(false);
+    }
+  }, [invoke, provision?.attemptId, provision?.status]);
+
+  React.useEffect(() => {
+    const attemptId = provision?.attemptId;
+    if (!attemptId || !ACTIVE_STATES.has(provision.status)) return undefined;
+    const controller = new AbortController();
+    let disposed = false;
+    let timer;
+    const poll = async () => {
+      try {
+        const current = normalizeProvisioning(await invoke(WECOM_ENDPOINTS.pollProvisioning, { attemptId }, controller.signal));
+        if (disposed || controller.signal.aborted || !mounted.current) return;
+        if (current.status === 'connected') {
+          setProvision(null);
+          await loadStatus({ signal: controller.signal, silent: true });
+          return;
+        }
+        setProvision((previous) => previous?.attemptId === attemptId
+          ? { ...previous, ...current, durationMs: current.qrRevision !== previous.qrRevision
+              ? Math.max(1, current.expiresAt - Date.now()) : previous.durationMs }
+          : previous);
+        if (ACTIVE_STATES.has(current.status)) timer = window.setTimeout(poll, current.pollIntervalMs);
+      } catch (error) {
+        if (!disposed && !controller.signal.aborted && mounted.current) {
+          setProvision((current) => ({ ...current, status: 'failed', error: presentError(error) }));
+        }
+      }
+    };
+    timer = window.setTimeout(poll, provision.pollIntervalMs ?? 1_000);
+    return () => { disposed = true; controller.abort(); window.clearTimeout(timer); };
+  }, [invoke, loadStatus, provision?.attemptId, provision?.pollIntervalMs, provision?.status]);
+
+  const botAction = React.useCallback(async (account, operation, endpoint, payload) => {
+    setBusyByBot((current) => ({ ...current, [account.botId]: operation }));
+    try {
+      const snapshot = normalizeSnapshot(await invoke(endpoint, payload));
+      if (mounted.current) setModel({ phase: 'ready', bots: snapshot.bots, totals: snapshot.totals, error: null });
+      return snapshot;
+    } finally {
+      if (mounted.current) setBusyByBot((current) => {
+        const next = { ...current }; delete next[account.botId]; return next;
+      });
+    }
+  }, [invoke]);
+
+  let provisionView = null;
+  if (provision?.status === 'starting') provisionView = h('div', { className: 'ddt-card ddt-loading dim-surfaceCard' }, h('div', { className: 'ddt-spinner' }), '正在申请企业微信二维码…');
+  else if (['pending', 'refreshing'].includes(provision?.status)) provisionView = h(QrPanel, {
+    provision, now, busy, onRefresh: () => void startProvisioning(true), onCancel: () => void closeProvision(),
+  });
+  else if (provision) provisionView = h(ProvisionView, {
+    provision, busy, onRetry: () => void startProvisioning(true), onClose: () => void closeProvision(),
+  });
+
+  const botList = model.bots.length > 0
+    ? h('section', { className: 'dim-listSection' },
+        h('div', { className: 'ddt-listHeading dim-listHeading' },
+          h('h3', null, '已绑定的企业微信机器人')),
+        h('ul', { className: 'ddt-list dim-botList' }, model.bots.map((account) =>
+          h('li', { key: account.botId }, h(AccountCard, {
+            account,
+            busy: busyByBot[account.botId],
+            removing: removeTarget === account.botId,
+            onReconnect: () => void botAction(account, 'reconnect', WECOM_ENDPOINTS.reconnectBot, { botId: account.botId }),
+            onRequestRemove: () => setRemoveTarget(account.botId),
+            onCancelRemove: () => setRemoveTarget(null),
+            onConfirmRemove: async () => {
+              await botAction(account, 'delete', WECOM_ENDPOINTS.deleteBot, { botId: account.botId, confirm: true });
+              if (mounted.current) setRemoveTarget(null);
+            },
+          })))))
+    : null;
+
+  const credentialView = credentialOpen
+    ? h(CredentialBindingPanel, {
+        channel: '企业微信',
+        identityLabel: 'Bot ID',
+        identityPlaceholder: '填写企业微信智能机器人 Bot ID',
+        secretLabel: 'Secret',
+        secretPlaceholder: '填写企业微信智能机器人 Secret',
+        busy,
+        error: credentialError,
+        onSubmit: bindCredentials,
+        onCancel: () => { setCredentialOpen(false); setCredentialError(null); },
+      })
+    : null;
+
+  return h('section', { className: 'ddt-page dwecom-page dim-channelPage', 'aria-label': '企业微信设置' },
+    h(Heading, {
+      totals: model.totals,
+      adding: Boolean(provision),
+      busy,
+      onAdd: () => void startProvisioning(),
+      onCredential: () => { setCredentialOpen((value) => !value); setCredentialError(null); },
+      credentialOpen,
+      addButtonRef,
+    }),
+    model.phase === 'loading' ? h(LoadingView)
+      : model.phase === 'error'
+        ? h('div', { className: 'ddt-card dim-surfaceCard' }, h('div', { className: 'ddt-inlineError dim-inlineError' }, h('h3', null, '无法读取企业微信机器人状态'), h('p', null, model.error?.message), h(Button, { onClick: () => void loadStatus() }, '重新读取')))
+        : h(React.Fragment, null,
+            credentialView,
+            provisionView,
+            model.bots.length === 0 && !provision && !credentialOpen
+              ? h(EmptyView, { busy, onStart: () => void startProvisioning() }) : null,
+            botList));
+}
+
+export function apply(ctx) {
+  ctx.effect(() => installWecomStyles(), 'wecom-settings: install client styles');
+  const rpcCall = (endpoint, payload, signal) => ctx.connection.rpc.call(WECOM_RPC_CHANNEL, endpoint, payload, signal);
+  ctx.slots.inject('settings.plugins.tab', () => ctx.slots.register({
+    name: 'settings.plugins.tab', id: 'wecom', order: 45, label: '企业微信', inject: () => ({ rpcCall }),
+  }, WecomSettingsTab));
+}

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

@@ -0,0 +1,19 @@
+export const WECOM_STYLE_ID = 'xmanrui-dsh-im-wecom-settings';
+
+const CSS = String.raw`
+.dwecom-page { --ddt-accent: #3370ff; --ddt-accent-deep: #245bdb; --ddt-accent-wash: #eef4ff; }
+.dwecom-avatar, .dwecom-brand { color: #3370ff; background: #fff; border: 1px solid var(--dsw-alias-line-border, #e5e6eb); }
+.dwecom-avatar svg, .dwecom-brand svg { display: block; }
+`;
+
+export function installWecomStyles() {
+  if (typeof document === 'undefined') return () => {};
+  const existing = document.querySelector(`style[data-plugin-css="${WECOM_STYLE_ID}"]`);
+  if (existing) return () => {};
+  const style = document.createElement('style');
+  style.dataset.plugin = '@xmanrui/dsh-im';
+  style.dataset.pluginCss = WECOM_STYLE_ID;
+  style.textContent = CSS;
+  document.head.appendChild(style);
+  return () => style.remove();
+}

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

@@ -0,0 +1,156 @@
+export const WEIXIN_RPC_CHANNEL = '/weixin';
+export const WEIXIN_ENDPOINTS = Object.freeze({
+  status: 'connection.status',
+  beginProvisioning: 'provision.begin',
+  pollProvisioning: 'provision.poll',
+  submitVerification: 'provision.verify',
+  cancelProvisioning: 'provision.cancel',
+  reconnectBot: 'bot.reconnect',
+  deleteBot: 'bot.delete',
+});
+
+const ACCOUNT_STATES = new Set(['connected', 'connecting', 'offline', 'error']);
+const PROVISION_STATES = new Set([
+  'starting',
+  'pending',
+  'scanned',
+  'needs_verification',
+  'connecting',
+  'connected',
+  'expired',
+  'failed',
+  'cancelled',
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function string(value, fallback = '') {
+  return typeof value === 'string' && value.trim() ? value.trim() : fallback;
+}
+
+function timestamp(value) {
+  return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+
+export function unwrapRpcResult(result) {
+  if (!isRecord(result) || typeof result.ok !== 'boolean') {
+    throw new Error('微信服务返回了无法识别的响应');
+  }
+  if (!result.ok) {
+    const error = new Error(string(result.error?.message, '微信操作失败'));
+    error.code = string(result.error?.code, 'WEIXIN_RPC_ERROR');
+    throw error;
+  }
+  return result.value;
+}
+
+export function safeQrSource(value) {
+  return typeof value === 'string'
+    && /^data:image\/(?:png|webp|svg\+xml)(?:;charset=[^;,]+)?;base64,/i.test(value)
+    ? value
+    : undefined;
+}
+
+export function safeVerificationUrl(value) {
+  if (typeof value !== 'string') return undefined;
+  try {
+    const url = new URL(value);
+    const host = url.hostname.toLowerCase();
+    return url.protocol === 'https:'
+      && (host === 'weixin.qq.com' || host.endsWith('.weixin.qq.com'))
+      ? url.toString()
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+export function normalizeProvisioning(value) {
+  if (!isRecord(value) || !string(value.attemptId)) {
+    throw new Error('微信扫码服务没有返回有效的绑定任务');
+  }
+  const status = PROVISION_STATES.has(value.status) ? value.status : 'failed';
+  const result = {
+    attemptId: string(value.attemptId),
+    status,
+    expiresAt: timestamp(value.expiresAt) ?? Date.now(),
+    pollIntervalMs: Math.min(5_000, Math.max(500, Number(value.pollIntervalMs) || 1_000)),
+    verificationRequired: value.verificationRequired === true || status === 'needs_verification',
+  };
+  const verificationUrl = safeVerificationUrl(value.verificationUrl);
+  const qrCodeDataUrl = safeQrSource(value.qrCodeDataUrl);
+  if (verificationUrl) result.verificationUrl = verificationUrl;
+  if (qrCodeDataUrl) result.qrCodeDataUrl = qrCodeDataUrl;
+  if (string(value.botId)) result.botId = string(value.botId);
+  if (value.alreadyConnected === true) result.alreadyConnected = true;
+  if (isRecord(value.error)) {
+    result.error = {
+      code: string(value.error.code, 'WEIXIN_PROVISION_FAILED'),
+      message: string(value.error.message, '微信绑定没有完成'),
+    };
+  }
+  return result;
+}
+
+function normalizeBot(value) {
+  if (!isRecord(value) || !string(value.botId) || !isRecord(value.bot)) return null;
+  const state = ACCOUNT_STATES.has(value.state) ? value.state : 'error';
+  const connected = value.connected === true;
+  return {
+    botId: string(value.botId),
+    state: connected ? 'connected' : state,
+    connected,
+    configured: value.configured === true,
+    bot: {
+      name: string(value.bot.name, '微信机器人'),
+      accountIdMasked: string(value.bot.accountIdMasked, '已安全保存'),
+    },
+    health: {
+      status: string(value.health?.status, connected ? 'healthy' : 'offline'),
+      summary: string(value.health?.summary, connected ? '微信连接正常' : '微信连接未就绪'),
+      lastCheckedAt: timestamp(value.health?.lastCheckedAt),
+    },
+    stats: {
+      messagesReceived: Math.max(0, Number(value.stats?.messagesReceived) || 0),
+      messagesReplied: Math.max(0, Number(value.stats?.messagesReplied) || 0),
+    },
+    error: isRecord(value.error)
+      ? {
+          code: string(value.error.code, 'WEIXIN_ACCOUNT_ERROR'),
+          message: string(value.error.message, '微信连接未就绪'),
+        }
+      : null,
+  };
+}
+
+export function normalizeSnapshot(value) {
+  if (!isRecord(value) || !Array.isArray(value.bots)) {
+    throw new Error('微信服务没有返回有效的账号列表');
+  }
+  const bots = value.bots.map(normalizeBot).filter(Boolean);
+  return {
+    schemaVersion: Number(value.schemaVersion) || 1,
+    revision: Number(value.revision) || 0,
+    state: string(value.state, 'offline'),
+    bots,
+    totals: {
+      configured: bots.length,
+      connected: bots.filter((bot) => bot.connected).length,
+    },
+    provisioning: value.provisioning ? normalizeProvisioning(value.provisioning) : null,
+  };
+}
+
+export function presentError(error) {
+  return {
+    code: string(error?.code, 'WEIXIN_ERROR'),
+    message: string(error?.message, '微信操作失败，请稍后重试'),
+  };
+}
+
+export function formatRemaining(milliseconds) {
+  const seconds = Math.max(0, Math.ceil(milliseconds / 1_000));
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
+}