@xmanrui/dsh-im 0.1.0

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

@@ -0,0 +1,140 @@
+export const DINGTALK_STYLE_ID = 'xmanrui-dsh-dingtalk-settings';
+
+const CSS = String.raw`
+.ddt-page {
+  --ddt-accent: #1677ff;
+  --ddt-accent-deep: #0958d9;
+  --ddt-accent-wash: #eaf3ff;
+  --ddt-success: var(--dsw-alias-state-success-primary, #20a162);
+  --ddt-warning: var(--dsw-alias-state-warning-primary, #d97706);
+  --ddt-error: var(--dsw-alias-state-error-primary, #d54941);
+  width: 100%;
+  max-width: 880px;
+  display: flex;
+  flex-direction: column;
+  gap: 18px;
+  padding: 2px 0 28px;
+  container-type: inline-size;
+  color: var(--dsw-alias-label-primary, #1f2329);
+  box-sizing: border-box;
+}
+.ddt-page *, .ddt-page *::before, .ddt-page *::after { box-sizing: border-box; }
+.ddt-heading { display: flex; align-items: flex-start; justify-content: space-between; gap: 20px; }
+.ddt-headingCopy { min-width: 0; }
+.ddt-heading h2, .ddt-heading p, .ddt-card h3, .ddt-card h4, .ddt-card p { margin: 0; }
+.ddt-eyebrow { margin-bottom: 3px; color: var(--dsw-alias-label-tertiary, #8f959e); font-size: 12px; font-weight: 650; letter-spacing: .08em; text-transform: uppercase; }
+.ddt-heading h2 { font-size: 20px; line-height: 28px; font-weight: 680; }
+.ddt-heading p { margin-top: 5px; color: var(--dsw-alias-label-secondary, #646a73); font-size: 13px; line-height: 20px; white-space: nowrap; }
+.ddt-tools, .ddt-actions { display: flex; align-items: center; flex-wrap: wrap; gap: 10px; }
+.ddt-tools { width: 100%; justify-content: space-between; flex-wrap: nowrap; }
+.ddt-badge { min-height: 30px; display: inline-flex; align-items: center; gap: 7px; padding: 0 11px; border-radius: 999px; color: var(--dsw-alias-label-secondary, #646a73); background: var(--dsw-alias-fill-secondary, #f2f3f5); font-size: 12px; white-space: nowrap; }
+.ddt-dot { width: 8px; height: 8px; flex: none; border-radius: 50%; background: #aeb3bb; }
+.ddt-dot[data-tone="success"] { background: var(--ddt-success); box-shadow: 0 0 0 3px color-mix(in srgb, var(--ddt-success) 14%, transparent); }
+.ddt-dot[data-tone="warning"] { background: var(--ddt-warning); }
+.ddt-dot[data-tone="error"] { background: var(--ddt-error); }
+.ddt-button { min-height: 34px; display: inline-flex; align-items: center; justify-content: center; gap: 7px; padding: 0 13px; border: 1px solid var(--dsw-alias-line-border, #dfe1e5); border-radius: 8px; color: var(--dsw-alias-label-primary, #1f2329); background: var(--dsw-alias-bg-body, #fff); font: inherit; font-size: 13px; font-weight: 560; text-decoration: none; cursor: pointer; transition: border-color .15s ease, background .15s ease, transform .15s ease; }
+.ddt-button:hover:not(:disabled) { border-color: #aeb3bb; background: var(--dsw-alias-fill-tertiary, #f7f8fa); }
+.ddt-button:active:not(:disabled) { transform: translateY(1px); }
+.ddt-button:focus-visible { outline: 2px solid color-mix(in srgb, var(--ddt-accent) 70%, white); outline-offset: 2px; }
+.ddt-button:disabled { cursor: not-allowed; opacity: .55; }
+.ddt-button[data-kind="primary"] { color: #fff; border-color: var(--ddt-accent); background: var(--ddt-accent); }
+.ddt-button[data-kind="primary"]:hover:not(:disabled) { border-color: var(--ddt-accent-deep); background: var(--ddt-accent-deep); }
+.ddt-button[data-kind="danger"] { color: var(--ddt-error); }
+.ddt-button[data-kind="quiet"] { min-height: 30px; padding: 0 10px; border-color: transparent; background: transparent; }
+.ddt-card { overflow: hidden; border: 1px solid var(--dsw-alias-line-border, #e5e6eb); border-radius: 14px; background: var(--dsw-alias-bg-body, #fff); box-shadow: 0 1px 2px rgb(31 35 41 / 3%); }
+.ddt-cardBody { padding: 24px; }
+.ddt-empty { min-height: 230px; display: grid; grid-template-columns: minmax(0, 1fr) 180px; align-items: center; gap: 30px; }
+.ddt-empty h3 { margin: 8px 0; font-size: 18px; }
+.ddt-empty p { max-width: 560px; color: var(--dsw-alias-label-secondary, #646a73); line-height: 1.65; }
+.ddt-empty .ddt-actions { margin-top: 20px; }
+.ddt-brandMark { width: 110px; height: 110px; display: grid; place-items: center; justify-self: center; border-radius: 28px; color: #fff; background: linear-gradient(145deg, #2997ff, var(--ddt-accent)); box-shadow: 0 18px 45px rgb(22 119 255 / 23%); }
+.ddt-brandMark svg { filter: drop-shadow(0 3px 8px rgb(0 35 96 / 16%)); }
+.ddt-qrLayout { display: grid; grid-template-columns: 300px minmax(0, 1fr); gap: 34px; align-items: start; }
+.ddt-qrColumn { display: flex; flex-direction: column; align-items: center; gap: 12px; }
+.ddt-qrFrame { position: relative; width: min(270px, 100%); aspect-ratio: 1; display: grid; place-items: center; overflow: hidden; padding: 10px; border: 1px solid var(--dsw-alias-line-border, #e5e6eb); border-radius: 16px; background: #fff; }
+.ddt-qrFrame::before { content: ''; position: absolute; inset: 6px; border: 1px solid rgb(22 119 255 / 10%); border-radius: 11px; pointer-events: none; }
+.ddt-qrFrame img { display: block; width: 100%; height: 100%; object-fit: contain; }
+.ddt-qrFallback { padding: 24px; color: #646a73; text-align: center; }
+.ddt-expired { position: absolute; inset: 0; display: grid; place-items: center; padding: 30px; color: #fff; text-align: center; font-weight: 650; white-space: pre-line; background: rgb(31 35 41 / 76%); backdrop-filter: blur(3px); }
+.ddt-countdown { width: min(270px, 100%); color: var(--dsw-alias-label-secondary, #646a73); font-size: 12px; }
+.ddt-countdownTop { display: flex; justify-content: space-between; margin-bottom: 6px; }
+.ddt-countdown strong { color: var(--dsw-alias-label-primary, #1f2329); font-variant-numeric: tabular-nums; }
+.ddt-progress { height: 4px; overflow: hidden; border-radius: 99px; background: #eef0f3; }
+.ddt-progress span { display: block; width: var(--ddt-progress); height: 100%; background: var(--ddt-accent); transition: width .2s linear; }
+.ddt-stateLabel { display: inline-flex; align-items: center; gap: 8px; color: var(--dsw-alias-label-secondary, #646a73); font-size: 12px; font-weight: 600; }
+.ddt-qrCopy { min-width: 0; overflow-wrap: anywhere; }
+.ddt-qrCopy h3 { margin: 9px 0 8px; font-size: 18px; }
+.ddt-qrCopy > p { color: var(--dsw-alias-label-secondary, #646a73); line-height: 1.65; }
+.ddt-steps { margin: 18px 0 16px; padding: 0; list-style: none; counter-reset: ddt-step; }
+.ddt-steps li { position: relative; min-height: 28px; padding: 3px 0 3px 36px; color: var(--dsw-alias-label-secondary, #646a73); font-size: 13px; line-height: 22px; counter-increment: ddt-step; }
+.ddt-steps li::before { content: counter(ddt-step); position: absolute; left: 0; top: 1px; width: 26px; height: 26px; display: grid; place-items: center; border-radius: 8px; color: var(--ddt-accent-deep); background: var(--ddt-accent-wash); font-size: 12px; font-weight: 700; }
+.ddt-loading { padding: 38px; color: var(--dsw-alias-label-secondary, #646a73); text-align: center; }
+.ddt-loading h3 { margin: 0 0 7px; color: var(--dsw-alias-label-primary, #1f2329); font-size: 17px; }
+.ddt-loading p { line-height: 1.6; }
+.ddt-spinner { width: 24px; height: 24px; margin: 0 auto 13px; border: 3px solid #e6e8eb; border-top-color: var(--ddt-accent); border-radius: 50%; animation: ddt-spin .8s linear infinite; }
+.ddt-statusNotice, .ddt-inlineError { display: flex; align-items: flex-start; gap: 10px; padding: 13px 15px; border: 1px solid color-mix(in srgb, var(--ddt-error) 28%, transparent); border-radius: 10px; color: var(--ddt-error); background: color-mix(in srgb, var(--ddt-error) 7%, transparent); font-size: 13px; }
+.ddt-inlineError { flex-direction: column; padding: 22px; }
+.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-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; }
+.ddt-accountTop { display: flex; align-items: flex-start; justify-content: space-between; gap: 16px; }
+.ddt-accountIdentity { min-width: 0; display: flex; align-items: center; gap: 12px; }
+.ddt-avatar { width: 42px; height: 42px; display: grid; place-items: center; flex: none; border-radius: 12px; color: #fff; background: linear-gradient(145deg, #2997ff, var(--ddt-accent)); }
+.ddt-accountIdentity h3 { overflow: hidden; font-size: 15px; text-overflow: ellipsis; white-space: nowrap; }
+.ddt-accountIdentity p { margin-top: 4px; color: var(--dsw-alias-label-secondary, #646a73); font: 12px ui-monospace, SFMono-Regular, monospace; }
+.ddt-health { display: inline-flex; align-items: center; gap: 7px; color: var(--dsw-alias-label-secondary, #646a73); font-size: 12px; white-space: nowrap; }
+.ddt-metrics { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: 10px; margin: 20px 0; }
+.ddt-metric { min-width: 0; padding: 12px; border-radius: 9px; background: var(--dsw-alias-fill-tertiary, #f7f8fa); }
+.ddt-metric dt { color: var(--dsw-alias-label-tertiary, #8f959e); font-size: 11px; }
+.ddt-metric dd { overflow: hidden; margin: 5px 0 0; font-size: 13px; text-overflow: ellipsis; white-space: nowrap; }
+.ddt-accountFooter { display: flex; align-items: center; justify-content: space-between; gap: 15px; padding-top: 16px; border-top: 1px solid var(--dsw-alias-line-divider, #eef0f3); }
+.ddt-accountFooter .ddt-actions { flex: none; flex-wrap: nowrap; gap: 8px; margin-top: 0; }
+.ddt-accountFooter .ddt-button { flex: none; white-space: nowrap; }
+.ddt-summary { color: var(--dsw-alias-label-secondary, #646a73); font-size: 12px; }
+.ddt-confirm { padding: 18px 24px; border-top: 1px solid color-mix(in srgb, var(--ddt-error) 25%, transparent); background: color-mix(in srgb, var(--ddt-error) 5%, transparent); }
+.ddt-confirm strong { display: block; margin-bottom: 6px; font-size: 14px; }
+.ddt-confirm p { color: var(--dsw-alias-label-secondary, #646a73); font-size: 12px; line-height: 1.55; }
+.ddt-confirm .ddt-actions { margin-top: 13px; }
+.ddt-visuallyHidden { position: absolute !important; width: 1px; height: 1px; overflow: hidden; clip: rect(0 0 0 0); white-space: nowrap; }
+@keyframes ddt-spin { to { transform: rotate(360deg); } }
+@container (max-width: 680px) {
+  .ddt-heading { flex-direction: column; align-items: stretch; }
+  .ddt-tools { width: 100%; flex-wrap: nowrap; gap: 6px; }
+  .ddt-tools .ddt-badge { min-height: 34px; padding-inline: 8px; }
+  .ddt-tools .ddt-button { flex: none; padding-inline: 10px; white-space: nowrap; }
+  .ddt-empty { grid-template-columns: minmax(0, 1fr); }
+  .ddt-brandMark { display: none; }
+  .ddt-qrLayout { grid-template-columns: minmax(0, 1fr); justify-items: center; gap: 24px; }
+  .ddt-qrColumn { width: 100%; min-width: 0; }
+  .ddt-qrCopy { width: 100%; }
+  .ddt-metrics { gap: 8px; }
+  .ddt-metric { padding: 10px; }
+}
+@media (max-width: 720px) {
+  .ddt-heading, .ddt-accountTop { flex-direction: column; align-items: stretch; }
+  .ddt-heading p { white-space: normal; }
+  .ddt-empty { grid-template-columns: minmax(0, 1fr); }
+  .ddt-brandMark { display: none; }
+  .ddt-qrLayout { grid-template-columns: minmax(0, 1fr); justify-items: center; }
+  .ddt-qrCopy { width: 100%; }
+  .ddt-cardBody { padding: 20px; }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ddt-page *, .ddt-page *::before, .ddt-page *::after { animation-duration: .01ms !important; transition-duration: .01ms !important; }
+}
+`;
+
+export function installDingtalkStyles() {
+  if (typeof document === 'undefined') return () => {};
+  const existing = document.querySelector(`style[data-plugin-css="${DINGTALK_STYLE_ID}"]`);
+  if (existing) return () => {};
+  const style = document.createElement('style');
+  style.dataset.plugin = '@xmanrui/dsh-dingtalk';
+  style.dataset.pluginCss = DINGTALK_STYLE_ID;
+  style.textContent = CSS;
+  document.head.appendChild(style);
+  return () => style.remove();
+}

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

@@ -0,0 +1,11 @@
+import { TOKEN_BOT_ENDPOINTS, createTokenChannelApi } from '../shared/token-api.js';
+
+export const DISCORD_RPC_CHANNEL = '/discord';
+export const DISCORD_ENDPOINTS = TOKEN_BOT_ENDPOINTS;
+
+const api = createTokenChannelApi('Discord', ' Gateway 长连接');
+
+export const unwrapRpcResult = api.unwrapRpcResult;
+export const normalizeSnapshot = api.normalizeSnapshot;
+export const presentError = api.presentError;
+export { api as discordClientApi };

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

@@ -0,0 +1,25 @@
+import { DiscordLogoGlyph } from '../../channel-logos.js';
+import { createTokenChannelSettings } from '../shared/token-channel.js';
+import {
+  DISCORD_ENDPOINTS,
+  discordClientApi,
+} from './api.js';
+import { installDiscordStyles } from './styles.js';
+
+const channel = createTokenChannelSettings({
+  channel: 'Discord',
+  endpoints: DISCORD_ENDPOINTS,
+  api: discordClientApi,
+  LogoGlyph: DiscordLogoGlyph,
+  installStyles: installDiscordStyles,
+  pageClass: 'ddc-page',
+  avatarClass: 'ddc-avatar',
+  connectionLabel: 'Gateway 长连接',
+  tokenPlaceholder: '填写 Discord Developer Portal 的 Bot Token',
+  emptyTitle: '接入 Discord 机器人',
+  emptyDescription: '先在 Developer Portal 创建 Bot 并邀请到服务器，再在这里完成接入。',
+  platformLabel: 'Discord Developer Portal',
+});
+
+export const DiscordSettingsTab = channel.SettingsTab;
+export const DiscordAccountCard = channel.AccountCard;

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

@@ -0,0 +1,19 @@
+export const DISCORD_STYLE_ID = 'xmanrui-dsh-im-discord-settings';
+
+const CSS = String.raw`
+.ddc-page { --ddt-accent: #5865f2; --ddt-accent-deep: #4752c4; --ddt-accent-wash: #eef0ff; }
+.ddc-avatar { color: #fff; background: #5865f2; }
+.ddc-avatar svg { display: block; }
+`;
+
+export function installDiscordStyles() {
+  if (typeof document === 'undefined') return () => {};
+  const existing = document.querySelector(`style[data-plugin-css="${DISCORD_STYLE_ID}"]`);
+  if (existing) return () => {};
+  const style = document.createElement('style');
+  style.dataset.plugin = '@xmanrui/dsh-im';
+  style.dataset.pluginCss = DISCORD_STYLE_ID;
+  style.textContent = CSS;
+  document.head.appendChild(style);
+  return () => style.remove();
+}

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

@@ -0,0 +1,325 @@
+/**
+ * Browser-safe contract for the Feishu Host plugin.
+ *
+ * The Host owns app registration and credentials. This module deliberately
+ * models only redacted presentation data; app secrets and credential refs
+ * must never be returned by any endpoint on this channel.
+ */
+
+export const FEISHU_RPC_CHANNEL = "/feishu";
+
+export const FEISHU_ENDPOINTS = Object.freeze({
+  status: "connection.status",
+  beginProvisioning: "provision.begin",
+  pollProvisioning: "provision.poll",
+  cancelProvisioning: "provision.cancel",
+  bindCredentials: "bot.bind-credentials",
+  reconnectBot: "bot.reconnect",
+  disconnectBot: "bot.disconnect",
+  deleteBot: "bot.delete",
+  // Kept for rolling upgrades. The multi-bot UI never calls these endpoints.
+  testConnection: "connection.test",
+  disconnect: "connection.disconnect",
+});
+
+const CONNECTION_STATES = new Set([
+  "disconnected",
+  "offline",
+  "provisioning",
+  "connecting",
+  "reconnecting",
+  "connected",
+  "error",
+]);
+
+const POLL_STATES = new Set([
+  "pending",
+  "scanned",
+  "connecting",
+  "connected",
+  "expired",
+  "failed",
+]);
+
+function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function optionalString(value) {
+  return typeof value === "string" && value.trim().length > 0
+    ? value.trim()
+    : undefined;
+}
+
+function optionalTimestamp(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (typeof value === "string" && value.length > 0) {
+    const parsed = Date.parse(value);
+    return Number.isNaN(parsed) ? undefined : parsed;
+  }
+  return undefined;
+}
+
+function clamp(value, min, max, fallback) {
+  return typeof value === "number" && Number.isFinite(value)
+    ? Math.min(max, Math.max(min, value))
+    : fallback;
+}
+
+export function unwrapRpcResult(result) {
+  if (!isRecord(result) || typeof result.ok !== "boolean") {
+    throw new Error("飞书服务返回了无法识别的响应");
+  }
+  if (!result.ok) {
+    const message = optionalString(result.error?.message) ?? "飞书服务请求失败";
+    const error = new Error(message);
+    error.code = optionalString(result.error?.code) ?? "FEISHU_RPC_ERROR";
+    throw error;
+  }
+  return result.value;
+}
+
+export function normalizeProvisioning(value, now = Date.now()) {
+  const source = isRecord(value?.provisioning) ? value.provisioning : value;
+  if (!isRecord(source)) throw new Error("飞书服务没有返回二维码信息");
+
+  const attemptId = optionalString(source.attemptId)
+    ?? optionalString(source.provisioningId);
+  const verificationUrl = optionalString(source.verificationUrl);
+  const qrCodeDataUrl = optionalString(source.qrCodeDataUrl);
+  if (!attemptId || (!verificationUrl && !qrCodeDataUrl)) {
+    throw new Error("飞书服务返回的二维码信息不完整");
+  }
+
+  const explicitExpiry = optionalTimestamp(source.expiresAt);
+  const expireIn = clamp(source.expireIn, 1, 60 * 60, 5 * 60);
+  return {
+    attemptId,
+    verificationUrl,
+    qrCodeDataUrl,
+    expiresAt: explicitExpiry ?? now + expireIn * 1000,
+    pollIntervalMs: clamp(source.pollIntervalMs, 800, 10_000, 1_800),
+  };
+}
+
+function normalizeBot(value) {
+  const source = isRecord(value) ? value : {};
+  return {
+    name: optionalString(source.name) ?? "飞书机器人",
+    avatarUrl: optionalString(source.avatarUrl),
+    appIdMasked: optionalString(source.appIdMasked),
+    tenantName: optionalString(source.tenantName),
+    domain: source.domain === "lark" ? "lark" : "feishu",
+    activated: typeof source.activated === "boolean" || typeof source.activated === "number"
+      ? source.activated
+      : undefined,
+  };
+}
+
+function normalizeHealth(value, connected = false) {
+  const source = isRecord(value) ? value : {};
+  const fallbackStatus = connected ? "healthy" : "offline";
+  const status = ["healthy", "degraded", "offline", "checking"].includes(source.status)
+    ? source.status
+    : fallbackStatus;
+  return {
+    status,
+    summary: optionalString(source.summary)
+      ?? (connected ? "长连接运行正常" : "机器人尚未连接"),
+    lastCheckedAt: optionalTimestamp(source.lastCheckedAt),
+    lastConnectedAt: optionalTimestamp(source.lastConnectedAt),
+  };
+}
+
+function normalizeError(value) {
+  if (!isRecord(value)) return undefined;
+  const message = optionalString(value.message);
+  if (!message) return undefined;
+  return { message, code: optionalString(value.code) };
+}
+
+function authoritativeState(value, connected) {
+  if (connected) return "connected";
+  const reported = CONNECTION_STATES.has(value) ? value : "disconnected";
+  if (reported === "connected" || reported === "connecting" || reported === "reconnecting") {
+    return "connecting";
+  }
+  if (reported === "error") return "error";
+  return "offline";
+}
+
+/** Normalize one redacted bot connection. `connected` is authoritative. */
+export function normalizeBotConnection(value, fallbackBotId) {
+  if (!isRecord(value)) throw new Error("飞书服务返回了无效的机器人状态");
+  const botId = optionalString(value.botId) ?? optionalString(fallbackBotId);
+  if (!botId) throw new Error("飞书服务返回的机器人缺少 botId");
+  const connected = value.connected === true;
+  return {
+    botId,
+    state: authoritativeState(value.state, connected),
+    connected,
+    configured: value.configured !== false,
+    bot: normalizeBot(value.bot),
+    health: normalizeHealth(value.health, connected),
+    error: normalizeError(value.error),
+  };
+}
+
+/**
+ * Normalize the v2 multi-bot list. A singleton fallback is accepted only so a
+ * browser/Host rolling upgrade does not strand an existing connection.
+ */
+export function normalizeBotsSnapshot(value) {
+  if (!isRecord(value)) throw new Error("飞书服务没有返回连接状态");
+
+  let sourceBots = Array.isArray(value.bots) ? value.bots : [];
+  if (sourceBots.length === 0 && value.configured === true) {
+    sourceBots = [{
+      botId: optionalString(value.botId) ?? "legacy-default",
+      state: value.state,
+      connected: value.connected,
+      configured: true,
+      bot: value.bot,
+      health: value.health,
+      error: value.error,
+    }];
+  }
+
+  const seen = new Set();
+  const bots = [];
+  for (const source of sourceBots) {
+    const bot = normalizeBotConnection(source);
+    if (seen.has(bot.botId)) continue;
+    seen.add(bot.botId);
+    bots.push(bot);
+  }
+
+  const configured = bots.filter((bot) => bot.configured).length;
+  const connected = bots.filter((bot) => bot.connected).length;
+  const revision = Number.isSafeInteger(value.revision) && value.revision >= 0
+    ? value.revision
+    : 0;
+  const state = CONNECTION_STATES.has(value.state) ? value.state : "disconnected";
+
+  return {
+    schemaVersion: value.schemaVersion === 2 ? 2 : 1,
+    revision,
+    state,
+    bots,
+    // Derive counts from the authoritative list so stale summary fields never
+    // make the UI claim that an unavailable bot is online.
+    totals: { configured, connected },
+    provisioning: value.provisioning
+      ? normalizeProvisioning(value.provisioning)
+      : undefined,
+    error: normalizeError(value.error),
+  };
+}
+
+/** Legacy single-bot normalizer retained for the compatibility surface. */
+export function normalizeConnectionSnapshot(value) {
+  if (!isRecord(value)) throw new Error("飞书服务没有返回连接状态");
+  const connected = value.connected === true;
+  const reportedState = CONNECTION_STATES.has(value.state)
+    ? value.state
+    : "disconnected";
+  const state = connected
+    ? "connected"
+    : reportedState === "connected"
+      ? "connecting"
+      : reportedState;
+  const snapshot = {
+    state,
+    configured: value.configured === true,
+    bot: normalizeBot(value.bot),
+    health: normalizeHealth(value.health, connected),
+    provisioning: undefined,
+    errorMessage: optionalString(value.error?.message) ?? optionalString(value.message),
+  };
+  if (value.provisioning) snapshot.provisioning = normalizeProvisioning(value.provisioning);
+  return snapshot;
+}
+
+/** Legacy UI projection retained for tests and rolling upgrades. */
+export function screenFromSnapshot(snapshot) {
+  switch (snapshot.state) {
+    case "connected":
+      return { phase: "connected", configured: snapshot.configured, bot: snapshot.bot, health: snapshot.health };
+    case "provisioning":
+      return snapshot.provisioning
+        ? { phase: "qr", configured: snapshot.configured, provision: snapshot.provisioning, expired: false }
+        : { phase: "creating", configured: snapshot.configured };
+    case "connecting":
+      return { phase: "connecting", configured: snapshot.configured, provision: snapshot.provisioning };
+    case "error":
+      return {
+        phase: "error",
+        configured: snapshot.configured,
+        bot: snapshot.bot,
+        health: snapshot.health,
+        error: { message: snapshot.errorMessage ?? "飞书连接遇到问题", code: "FEISHU_CONNECTION_ERROR" },
+        retry: snapshot.configured ? "test" : "begin",
+      };
+    default:
+      return snapshot.configured
+        ? { phase: "offline", configured: true, bot: snapshot.bot, health: snapshot.health }
+        : { phase: "disconnected", configured: false };
+  }
+}
+
+/** Legacy helper. The new UI uses reconnectBot with an explicit botId. */
+export async function retryConnection(invoke, signal) {
+  if (typeof invoke !== "function") throw new TypeError("retryConnection requires an RPC caller");
+  await invoke(FEISHU_ENDPOINTS.testConnection, {}, signal);
+  return invoke(FEISHU_ENDPOINTS.status, {}, signal);
+}
+
+/** Reconnect exactly one bot, then fetch the authoritative list once. */
+export async function reconnectBot(invoke, botId, signal) {
+  if (typeof invoke !== "function") throw new TypeError("reconnectBot requires an RPC caller");
+  const id = optionalString(botId);
+  if (!id) throw new TypeError("reconnectBot requires a botId");
+  await invoke(FEISHU_ENDPOINTS.reconnectBot, { botId: id }, signal);
+  return invoke(FEISHU_ENDPOINTS.status, {}, signal);
+}
+
+export function normalizePollResult(value) {
+  if (!isRecord(value)) throw new Error("飞书服务没有返回创建进度");
+  const status = POLL_STATES.has(value.status)
+    ? value.status
+    : POLL_STATES.has(value.state)
+      ? value.state
+      : undefined;
+  if (!status) throw new Error("飞书服务返回了未知的创建状态");
+
+  const normalized = {
+    status,
+    botId: optionalString(value.botId),
+    message: optionalString(value.error?.message) ?? optionalString(value.message),
+    connection: undefined,
+    provisioning: undefined,
+  };
+  if (value.provisioning) normalized.provisioning = normalizeProvisioning(value.provisioning);
+  if (status === "connected" && isRecord(value.connection)) {
+    normalized.connection = value.connection.botId
+      ? normalizeBotConnection(value.connection)
+      : normalizeConnectionSnapshot(value.connection);
+  }
+  return normalized;
+}
+
+/** Keep transport and Host details out of the user-facing alert. */
+export function presentError(error) {
+  const raw = optionalString(error?.message) ?? "操作失败，请稍后重试";
+  const message = raw
+    .replace(/(client[_-]?secret|app[_-]?secret|secret|token)\s*[:=]\s*[^\s,;]+/gi, "$1=••••••")
+    .slice(0, 240);
+  return { message, code: optionalString(error?.code) };
+}
+
+export function formatRemaining(milliseconds) {
+  const totalSeconds = Math.max(0, Math.ceil(milliseconds / 1000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return `${String(minutes).padStart(2, "0")}:${String(seconds).padStart(2, "0")}`;
+}