@wenbin_wb/dsh-bridge 2.10.9 → 2.10.11

package/lib/index.js

@@ -10,7 +10,7 @@ import { get as httpsGet } from 'node:https';
 import { networkInterfaces, homedir, totalmem, freemem, cpus, loadavg, platform, arch, release, hostname, uptime } from 'node:os';
 import { join, dirname, basename, resolve, normalize } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { readFileSync, existsSync, realpathSync } from 'node:fs';
+import { readFileSync, appendFileSync, existsSync, realpathSync } from 'node:fs';
 import { readFile, writeFile, mkdir, unlink, readdir, stat, access } from 'node:fs/promises';
 import { spawn } from 'node:child_process';
 import QRCode from 'qrcode';
@@ -18,6 +18,7 @@ import { installBridgeRpc } from './bridge-rpc.js';
 import { CustomTunnelClient } from './tunnel-client.mjs';
 import { CloudflaredManager } from './cloudflared-manager.mjs';
 import { PlatformManager } from './platform/manager.js';
+import { applyRestoredPlatformConfig, RESTORED_STRING_FIELDS, PLATFORM_TIMING_FIELDS } from './platform/config-restore.js';
 import { WechatService } from './wechat/index.js';
 import { QqService } from './qq/index.js';
 import { FeishuService } from './feishu/index.js';
@@ -27,7 +28,7 @@ import { getDshLoopbackCookie as getDshLoopbackCookieImpl } from './auth/dsh-nat
 import { renderLoginPage } from './auth/login-template.js';
 import { isSafeWorkspacePath, isSensitiveFolderName } from './security/path-validator.js';
 import { stripSessionProjections } from './session-strip.js';
-import { installAbortSignalCompat, BROWSER_ABORT_SIGNAL_POLYFILL } from './compat.js';
+import { installAbortSignalCompat, BROWSER_ABORT_SIGNAL_POLYFILL, BROWSER_PROMISE_ITERATOR_POLYFILL } from './compat.js';
 
 const name = 'dsh-bridge';
 // 微信 Bot 会话桥依赖 DSH 提供的会话/agent/审批/工作区/持久化服务，需显式 inject
@@ -186,7 +187,8 @@ const HTML_HEAD_INJECTIONS = `<meta name="viewport" content="width=device-width,
 <link rel="apple-touch-icon" href="/__dsh_bridge__/pwa-icon.svg">
 <style data-dsh-bridge-overscroll="1">html,body{overscroll-behavior-y:none;-webkit-overflow-scrolling:touch}</style>
 <script data-dsh-bridge-polyfill="1">!function(){try{if(self.crypto&&!self.crypto.randomUUID){self.crypto.randomUUID=function(){var b=new Uint8Array(16);self.crypto.getRandomValues(b);b[6]=b[6]&15|64;b[8]=b[8]&63|128;var h="";for(var i=0;i<16;i++){var x=b[i].toString(16);h+=(x.length<2?"0":"")+x;if(i===3||i===5||i===7||i===9)h+="-";}return h;}}}catch(e){}}();</script>
-${BROWSER_ABORT_SIGNAL_POLYFILL}`;
+${BROWSER_ABORT_SIGNAL_POLYFILL}
+${BROWSER_PROMISE_ITERATOR_POLYFILL}`;
 const INJECT_MARK = 'data-dsh-bridge-polyfill="1"';
 
 function isCompressed(headers) {
@@ -261,6 +263,47 @@ function sanitizeProxyHeaders(headers, extra) {
  * 关键：改写 Host + Origin，注入 crypto.randomUUID polyfill
  * 并在未授权时拦截并展示 DSH 风格登录页，阻止未授权 WebSocket 与 API 调用
  */
+/**
+ * 从 `/proc/self/cgroup` 内容里取出最内层（最后一段）的 systemd 单元名。
+ *
+ * 形如 `0::/user.slice/user-1000.slice/user@1000.service/app.slice/dsh-web.service`
+ * 时必须取 `dsh-web.service`（祖先里的 `user@1000.service` 是用户管理器，不是本服务）。
+ *
+ * @param {string} cgroup /proc/self/cgroup 的原始内容
+ * @returns {string} 单元名，取不到返回空串
+ */
+export function parseSystemdUnit(cgroup) {
+  const parts = String(cgroup || '').split('/').filter(Boolean);
+  for (let i = parts.length - 1; i >= 0; i -= 1) {
+    if (parts[i].endsWith('.service')) return parts[i];
+  }
+  return '';
+}
+
+/**
+ * 判断当前 DSH 由谁托管，决定重启方式（纯函数，便于单测）。
+ *
+ * @param {object} [opts]
+ * @param {object} [opts.env] 环境变量（默认 process.env）
+ * @param {string} [opts.cgroup] /proc/self/cgroup 内容
+ * @returns {{kind:'daemon'|'systemd'|'self', scope?:'user'|'system', unit?:string, reason:string}}
+ */
+export function detectSupervisor({ env = process.env, cgroup = '' } = {}) {
+  if (env.DSH_DAEMON || env.PM2_HOME) {
+    return { kind: 'daemon', reason: env.PM2_HOME ? 'PM2_HOME' : 'DSH_DAEMON' };
+  }
+  const text = String(cgroup || '');
+  // 只在确实处于 systemd 环境时才认（INVOCATION_ID/JOURNAL_STREAM 是 systemd 注入的标记），
+  // 避免在容器里存在同名 cgroup 文本时误判。
+  const systemdMarked = Boolean(env.INVOCATION_ID || env.JOURNAL_STREAM) || text.includes('.slice');
+  const unit = systemdMarked ? parseSystemdUnit(text) : '';
+  if (unit) {
+    const parts = text.split('/').filter(Boolean);
+    return { kind: 'systemd', scope: parts.includes('user.slice') ? 'user' : 'system', unit, reason: 'cgroup 检出 systemd 单元' };
+  }
+  return { kind: 'self', reason: '未检出托管器（无 DSH_DAEMON/PM2_HOME，也不在 systemd 单元内）' };
+}
+
 class ProxyServer {
   constructor({ localPort, targetPort, authManager, logger, allowedOrigins }) {
     this.localPort = localPort;
@@ -1300,32 +1343,103 @@ class BridgeService {
     return { ok: false, error: lastError?.message ?? '升级命令执行失败', version: targetVersion };
   }
 
-  // 优雅重启 DSH 服务（支持守护进程自动拉起或独立派生子进程重启）
-  async restartDsh() {
-    this.logger?.info('收到 DSH 重启请求，正在调度重启...');
-    setTimeout(() => {
-      try {
-        if (process.env.DSH_DAEMON || process.env.PM2_HOME) {
-          process.exit(0);
-        } else {
-          // 常规 Node/CLI 模式：派生与当前参数一致的独立后台子进程并退出当前进程
-          const child = spawn(process.execPath, process.argv.slice(1), {
-            cwd: process.cwd(),
-            env: process.env,
-            detached: true,
-            stdio: 'ignore',
-            windowsHide: false,
-          });
-          child.unref();
-          process.exit(0);
+  // 优雅重启 DSH 服务。
+  //
+  // 关键教训（真实事故）：DSH 常以 systemd 用户单元（如 dsh-web.service，Restart=on-failure）托管，
+  // 而"自己派生一个子进程再 process.exit(0)"在这种环境下必然失败：
+  //   - 干净退出（code 0）不满足 Restart=on-failure，systemd 不会拉起；
+  //   - 默认 KillMode=control-group，主进程退出时 systemd 会把 cgroup 里刚派生的子进程一起杀掉。
+  //   结果就是"点了重启，dsh 再也没起来"，而且没有任何日志（旧实现 stdio: 'ignore'）。
+  // 因此这里先识别托管方式：
+  //   - systemd（从 /proc/self/cgroup 取单元名）→ 交给 `systemctl [--user] restart --no-block <unit>`，
+  //     由 systemd 负责 stop+start，新进程仍在正确的 cgroup 里；
+  //   - DSH_DAEMON / PM2 → 直接退出，交给守护进程拉起；
+  //   - 无托管器 → 派生独立助手（lib/restart-helper.mjs），等旧进程退出 + 端口释放后才拉起新进程，
+  //     并把全过程写入 ~/.dsh/dsh-bridge/restart.log（失败不再无声）。
+  // opts 仅供单测注入（spawnImpl / readCgroup / env / scheduleExit）。
+  async restartDsh(opts = {}) {
+    const env = opts.env ?? process.env;
+    const spawnImpl = opts.spawnImpl ?? spawn;
+    const readCgroup = opts.readCgroup
+      ?? (() => { try { return readFileSync('/proc/self/cgroup', 'utf8'); } catch { return ''; } });
+    const cgroup = opts.cgroup ?? readCgroup();
+    const scheduleExit = opts.scheduleExit ?? ((ms) => setTimeout(() => process.exit(0), ms));
+
+    const dshHome = env.DSH_HOME ?? join(homedir(), '.dsh');
+    const logFile = join(dshHome, 'dsh-bridge', 'restart.log');
+    const childLog = join(dshHome, 'dsh-bridge', 'restart-child.log');
+    const writeLog = (message) => {
+      try { appendFileSync(logFile, `[${new Date().toISOString()}] ${message}\n`); } catch { /* 日志不可写时忽略 */ }
+    };
+
+    const plan = detectSupervisor({ env, cgroup });
+    writeLog(`重启请求：plan=${plan.kind}${plan.unit ? ` unit=${plan.unit}(${plan.scope})` : ''}（${plan.reason}）pid=${process.pid} cwd=${process.cwd()} argv=${JSON.stringify(process.argv.slice(1))}`);
+    this.logger?.info('收到 DSH 重启请求（%s）', plan.kind === 'systemd' ? `systemd:${plan.unit}` : plan.kind);
+
+    if (plan.kind === 'systemd') {
+      const args = [...(plan.scope === 'user' ? ['--user'] : []), 'restart', '--no-block', plan.unit];
+      const spawnError = await new Promise((resolve) => {
+        let settled = false;
+        const settle = (value) => { if (!settled) { settled = true; resolve(value); } };
+        try {
+          const child = spawnImpl('systemctl', args, { detached: true, stdio: 'ignore', env });
+          child.once?.('error', (err) => settle(err));
+          child.once?.('spawn', () => settle(null));
+          child.unref?.();
+        } catch (err) {
+          settle(err);
         }
+      });
+
+      if (!spawnError) {
+        writeLog(`已请求 systemd 重启：systemctl ${args.join(' ')}`);
+        scheduleExit(1500);
+        const scopeText = plan.scope === 'user' ? '用户会话' : '系统';
+        return { ok: true, message: `已请求 systemd 重启 ${plan.unit}（${scopeText}），由 systemd 负责停止与拉起…` };
+      }
+      writeLog(`调用 systemctl 失败：${spawnError.message}；回退到独立助手方式`);
+    } else if (plan.kind === 'daemon') {
+      writeLog(`交由守护进程拉起（${plan.reason}）`);
+      scheduleExit(600);
+      return { ok: true, message: `DSH 正在重启（由 ${plan.reason} 守护进程拉起）…` };
+    }
+
+    // 无托管器（或 systemd 调用失败）→ 独立助手：等旧进程退出、端口释放后再拉起新进程，全程留日志
+    const helper = join(dirname(fileURLToPath(import.meta.url)), 'restart-helper.mjs');
+    const payload = JSON.stringify({
+      pid: process.pid,
+      port: this.dshPort ?? 3080,
+      argv: process.argv.slice(1),
+      cwd: process.cwd(),
+      execPath: process.execPath,
+      logFile,
+      childLog,
+    });
+    // spawn 的失败是异步事件（'error'），只 try/catch 抓不到——必须挂监听，否则会变成未捕获异常
+    const helperError = await new Promise((resolve) => {
+      let settled = false;
+      const settle = (value) => { if (!settled) { settled = true; resolve(value); } };
+      try {
+        const child = spawnImpl(process.execPath, [helper, payload], {
+          cwd: process.cwd(),
+          env,
+          detached: true,
+          stdio: 'ignore',
+        });
+        child.once?.('error', (err) => settle(err));
+        child.once?.('spawn', () => { writeLog(`已派生重启助手：helperPid=${child.pid ?? '(未知)'}，日志：${logFile}`); settle(null); });
+        child.unref?.();
       } catch (err) {
-        this.logger?.error('派生重启进程失败: %s，执行直接退出', err.message);
-        process.exit(0);
+        settle(err);
       }
-    }, 600);
+    });
 
-    return { ok: true, message: 'DSH 服务正在重启中，前端将在几秒后自动重新连接…' };
+    if (helperError) {
+      writeLog(`派生重启助手失败：${helperError.message}`);
+      return { ok: false, error: `重启失败：${helperError.message}（DSH 仍在运行，未做任何退出）` };
+    }
+    scheduleExit(600);
+    return { ok: true, message: '正在重启：独立助手会在旧进程退出、端口释放后拉起新的 DSH（若失败会记录在 ~/.dsh/dsh-bridge/restart.log）…' };
   }
 
   getSystemMetrics() {
@@ -1954,15 +2068,13 @@ function apply(ctx, config = {}) {
       const cfg = stored?.[platformKey];
       if (!cfg) return;
       const node = service.node;
-      node.config.allowFrom = Array.isArray(cfg.allowFrom) ? cfg.allowFrom : [];
-      for (const field of numericFields) {
-        if (cfg[field] != null) node.config[field] = Number(cfg[field]);
-      }
-      if (cfg.maxMessageChars != null) {
-        const val = Number(cfg.maxMessageChars);
-        node.config.maxMessageChars = (val >= 200) ? val : defaultMaxMessageChars;
-      }
-      if (cfg.groupAutoApprove != null) node.config.groupAutoApprove = cfg.groupAutoApprove === true;
+      // 白名单/数值字段 + 会话字符串字段（cwd/agentPreset/agentProvider/agentModel）一并回写，
+      // 否则"设置里配了、重启就丢"，远程会话会掉到默认或空 preset 层
+      applyRestoredPlatformConfig(node.config, cfg, {
+        numericFields,
+        stringFields: RESTORED_STRING_FIELDS,
+        defaultMaxMessageChars,
+      });
 
       node._restoringConfig = (async () => {
         if (cfg.activeSessionId) {
@@ -1987,7 +2099,7 @@ function apply(ctx, config = {}) {
 
   restorePlatform(wechat, {
     platformKey: 'wechat',
-    numericFields: ['digestIntervalSec', 'approvalTimeoutSec', 'sendChunkDelayMs'],
+    numericFields: PLATFORM_TIMING_FIELDS,
     hasCredentials: (cfg) => Boolean(cfg.token && cfg.accountId),
     applyCredentials: (cfg) => wechat.gateway.setCredentials({
       token: cfg.token,
@@ -1998,6 +2110,7 @@ function apply(ctx, config = {}) {
 
   restorePlatform(qq, {
     platformKey: 'qq',
+    numericFields: PLATFORM_TIMING_FIELDS,
     hasCredentials: (cfg) => Boolean(cfg.appId && cfg.clientSecret),
     applyCredentials: (cfg) => qq.gateway.setCredentials({
       appId: cfg.appId,
@@ -2011,6 +2124,7 @@ function apply(ctx, config = {}) {
 
   restorePlatform(feishu, {
     platformKey: 'feishu',
+    numericFields: PLATFORM_TIMING_FIELDS,
     hasCredentials: (cfg) => Boolean(cfg.appId && cfg.appSecret),
     applyCredentials: (cfg) => feishu.gateway.updateConfig({
       appId: cfg.appId,
@@ -2021,7 +2135,7 @@ function apply(ctx, config = {}) {
 
   restorePlatform(telegram, {
     platformKey: 'telegram',
-    numericFields: ['digestIntervalSec', 'approvalTimeoutSec', 'sendChunkDelayMs'],
+    numericFields: PLATFORM_TIMING_FIELDS,
     defaultMaxMessageChars: 4096,
     hasCredentials: (cfg) => Boolean(cfg.botToken),
     applyCredentials: (cfg) => telegram.gateway.setCredentials({
@@ -2086,22 +2200,24 @@ function apply(ctx, config = {}) {
       if (incoming.customTunnel) {
         service.customTunnelConfig = incoming.customTunnel;
       }
-      // 重新载入各 IM 平台白名单与配置
-      if (incoming.wechat) wechat.node.config.allowFrom = incoming.wechat.allowFrom ?? [];
+      // 重新载入各 IM 平台白名单与配置（含 cwd/agentPreset/agentProvider/agentModel）
+      if (incoming.wechat) {
+        applyRestoredPlatformConfig(wechat.node.config, incoming.wechat, { stringFields: RESTORED_STRING_FIELDS });
+      }
       if (incoming.qq) {
-        qq.node.config.allowFrom = incoming.qq.allowFrom ?? [];
+        applyRestoredPlatformConfig(qq.node.config, incoming.qq, { stringFields: RESTORED_STRING_FIELDS });
         if (incoming.qq.appId && incoming.qq.clientSecret) {
           qq.gateway.setCredentials({ appId: incoming.qq.appId, clientSecret: incoming.qq.clientSecret });
         }
       }
       if (incoming.feishu) {
-        feishu.node.config.allowFrom = incoming.feishu.allowFrom ?? [];
+        applyRestoredPlatformConfig(feishu.node.config, incoming.feishu, { stringFields: RESTORED_STRING_FIELDS });
         if (incoming.feishu.appId && incoming.feishu.appSecret) {
           feishu.gateway.setCredentials({ appId: incoming.feishu.appId, appSecret: incoming.feishu.appSecret });
         }
       }
       if (incoming.telegram) {
-        telegram.node.config.allowFrom = incoming.telegram.allowFrom ?? [];
+        applyRestoredPlatformConfig(telegram.node.config, incoming.telegram, { stringFields: RESTORED_STRING_FIELDS });
         if (incoming.telegram.botToken) {
           telegram.gateway.setCredentials({ botToken: incoming.telegram.botToken, proxy: incoming.telegram.proxy || '' });
         }

package/lib/platform/base.js

@@ -1,147 +1,147 @@
-// dsh-bridge 平台抽象基类
-//
-// 定义 IM 平台适配器的统一接口。每个平台（微信/QQ/飞书/Telegram…）继承本类，
-// 实现协议层（登录、收发消息、typing）。平台无关的会话桥逻辑在 ConversationBridge
-// （lib/platform/conversation-bridge.js）中实现，通过 platform 注入到 bridge。
-//
-// 生命周期：constructor → start() → stop() → dispose()
-// 消息抽象：sendText / sendTyping / sendMedia（由子类实现）
-
-export class Platform {
-  /**
-   * @param {object} opts
-   * @param {object} opts.ctx          Cordis 上下文
-   * @param {object} opts.logger       日志器
-   * @param {object} [opts.config]     已持久化的平台配置（凭证等）
-   * @param {(patch: object) => (void|Promise<void>)} [opts.onPersist]  主插件保存回调
-   * @param {import('./conversation-bridge.js').ConversationBridge} [opts.bridge] 会话桥实例
-   */
-  constructor({ ctx, logger, config = {}, onPersist, bridge } = {}) {
-    this.ctx = ctx
-    this.logger = logger
-    this.config = { ...config }
-    this.onPersist = onPersist ?? (() => {})
-    this.bridge = bridge ?? null
-
-    // 平台标识（子类必须设置）
-    this.id = ''
-    this.name = ''
-
-    // 连接状态与账号：子类可能用 getter 覆盖（如委托给 gateway），
-    // 因此仅在未被子类覆盖时才初始化默认值。
-    if (!('status' in this)) this.status = 'idle'
-    if (!('accountId' in this)) this.accountId = null
-
-    // 扫码/登录的流式状态（RPC 轮询读取）
-    this.loginState = {
-      phase: 'idle',   // idle | qr | scaned | confirmed | done | error
-      qrPayload: null, // 待渲染内容：dataURL 图片 或 二维码文本
-      qrKind: null,    // 'img' | 'text'
-      error: null,
-    }
-
-    this.disposers = []
-  }
-
-  // ---- 平台能力声明（子类可覆盖）----
-
-  get capabilities() {
-    return {
-      supportsGroup: false,   // 是否支持群聊
-      supportsMedia: false,   // 是否支持媒体收发
-      supportsVoice: false,   // 是否支持语音
-      supportsTyping: false,  // 是否支持 typing 状态
-      maxMessageChars: 2000,  // 单条消息最大字符数
-    }
-  }
-
-  get configured() {
-    return false
-  }
-
-  // ---- 生命周期（子类必须实现 start/stop；dispose 已提供默认实现）----
-
-  async start() {
-    throw new Error(`${this.id || 'platform'}: start() not implemented`)
-  }
-
-  async stop() {
-    throw new Error(`${this.id || 'platform'}: stop() not implemented`)
-  }
-
-  dispose() {
-    for (const disposer of this.disposers) {
-      try { disposer() } catch { /* 忽略 */ }
-    }
-    this.disposers = []
-    this.bridge?.dispose?.()
-    this.bridge = null
-  }
-
-  // ---- 消息抽象（子类必须实现）----
-
-  async sendText(peerId, text, opts = {}) {
-    throw new Error(`${this.id || 'platform'}: sendText() not implemented`)
-  }
-
-  async sendTyping(peerId, state) {
-    return Promise.resolve()
-  }
-
-  async sendMedia(peerId, media, opts = {}) {
-    throw new Error(`${this.id || 'platform'}: sendMedia() not implemented`)
-  }
-
-  // ---- 登录（子类必须实现 login；getLoginState 已提供默认）----
-
-  async login(opts = {}) {
-    throw new Error(`${this.id || 'platform'}: login() not implemented`)
-  }
-
-  getLoginState() {
-    return { ...this.loginState }
-  }
-
-  // ---- 状态汇总（供 RPC/UI 读取）----
-
-  getStatus() {
-    return {
-      id: this.id,
-      name: this.name,
-      status: this.status,
-      configured: this.configured,
-      accountId: this.accountId,
-      login: this.getLoginState(),
-      peerId: this.bridge?.peerId ?? null,
-      sessionId: this.bridge?.activeSessionId ?? null,
-      config: this.getEditableConfig?.(),
-    }
-  }
-
-  /** 可编辑配置（供 UI 设置面板读取）；子类可覆盖返回具体字段。 */
-  getEditableConfig() {
-    return {}
-  }
-
-  // ---- 工具 ----
-
-  setStatus(status) {
-    if (this.status === status) return
-    this.status = status
-    try {
-      this.ctx.emit?.(`${this.id}/status`, status)
-    } catch { /* emit 失败不致命 */ }
-  }
-
-  async persist(patch) {
-    try {
-      await this.onPersist(patch)
-    } catch (err) {
-      this.logger?.warn?.(`[dsh-bridge ${this.id}] persist failed: %s`, err?.message ?? err)
-    }
-  }
-
-  async destroy() {
-    this.dispose()
-  }
-}
+// dsh-bridge 平台抽象基类
+//
+// 定义 IM 平台适配器的统一接口。每个平台（微信/QQ/飞书/Telegram…）继承本类，
+// 实现协议层（登录、收发消息、typing）。平台无关的会话桥逻辑在 ConversationBridge
+// （lib/platform/conversation-bridge.js）中实现，通过 platform 注入到 bridge。
+//
+// 生命周期：constructor → start() → stop() → dispose()
+// 消息抽象：sendText / sendTyping / sendMedia（由子类实现）
+
+export class Platform {
+  /**
+   * @param {object} opts
+   * @param {object} opts.ctx          Cordis 上下文
+   * @param {object} opts.logger       日志器
+   * @param {object} [opts.config]     已持久化的平台配置（凭证等）
+   * @param {(patch: object) => (void|Promise<void>)} [opts.onPersist]  主插件保存回调
+   * @param {import('./conversation-bridge.js').ConversationBridge} [opts.bridge] 会话桥实例
+   */
+  constructor({ ctx, logger, config = {}, onPersist, bridge } = {}) {
+    this.ctx = ctx
+    this.logger = logger
+    this.config = { ...config }
+    this.onPersist = onPersist ?? (() => {})
+    this.bridge = bridge ?? null
+
+    // 平台标识（子类必须设置）
+    this.id = ''
+    this.name = ''
+
+    // 连接状态与账号：子类可能用 getter 覆盖（如委托给 gateway），
+    // 因此仅在未被子类覆盖时才初始化默认值。
+    if (!('status' in this)) this.status = 'idle'
+    if (!('accountId' in this)) this.accountId = null
+
+    // 扫码/登录的流式状态（RPC 轮询读取）
+    this.loginState = {
+      phase: 'idle',   // idle | qr | scaned | confirmed | done | error
+      qrPayload: null, // 待渲染内容：dataURL 图片 或 二维码文本
+      qrKind: null,    // 'img' | 'text'
+      error: null,
+    }
+
+    this.disposers = []
+  }
+
+  // ---- 平台能力声明（子类可覆盖）----
+
+  get capabilities() {
+    return {
+      supportsGroup: false,   // 是否支持群聊
+      supportsMedia: false,   // 是否支持媒体收发
+      supportsVoice: false,   // 是否支持语音
+      supportsTyping: false,  // 是否支持 typing 状态
+      maxMessageChars: 2000,  // 单条消息最大字符数
+    }
+  }
+
+  get configured() {
+    return false
+  }
+
+  // ---- 生命周期（子类必须实现 start/stop；dispose 已提供默认实现）----
+
+  async start() {
+    throw new Error(`${this.id || 'platform'}: start() not implemented`)
+  }
+
+  async stop() {
+    throw new Error(`${this.id || 'platform'}: stop() not implemented`)
+  }
+
+  dispose() {
+    for (const disposer of this.disposers) {
+      try { disposer() } catch { /* 忽略 */ }
+    }
+    this.disposers = []
+    this.bridge?.dispose?.()
+    this.bridge = null
+  }
+
+  // ---- 消息抽象（子类必须实现）----
+
+  async sendText(peerId, text, opts = {}) {
+    throw new Error(`${this.id || 'platform'}: sendText() not implemented`)
+  }
+
+  async sendTyping(peerId, state) {
+    return Promise.resolve()
+  }
+
+  async sendMedia(peerId, media, opts = {}) {
+    throw new Error(`${this.id || 'platform'}: sendMedia() not implemented`)
+  }
+
+  // ---- 登录（子类必须实现 login；getLoginState 已提供默认）----
+
+  async login(opts = {}) {
+    throw new Error(`${this.id || 'platform'}: login() not implemented`)
+  }
+
+  getLoginState() {
+    return { ...this.loginState }
+  }
+
+  // ---- 状态汇总（供 RPC/UI 读取）----
+
+  getStatus() {
+    return {
+      id: this.id,
+      name: this.name,
+      status: this.status,
+      configured: this.configured,
+      accountId: this.accountId,
+      login: this.getLoginState(),
+      peerId: this.bridge?.peerId ?? null,
+      sessionId: this.bridge?.activeSessionId ?? null,
+      config: this.getEditableConfig?.(),
+    }
+  }
+
+  /** 可编辑配置（供 UI 设置面板读取）；子类可覆盖返回具体字段。 */
+  getEditableConfig() {
+    return {}
+  }
+
+  // ---- 工具 ----
+
+  setStatus(status) {
+    if (this.status === status) return
+    this.status = status
+    try {
+      this.ctx.emit?.(`${this.id}/status`, status)
+    } catch { /* emit 失败不致命 */ }
+  }
+
+  async persist(patch) {
+    try {
+      await this.onPersist(patch)
+    } catch (err) {
+      this.logger?.warn?.(`[dsh-bridge ${this.id}] persist failed: %s`, err?.message ?? err)
+    }
+  }
+
+  async destroy() {
+    this.dispose()
+  }
+}