@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/adapter/lint.ts

@@ -0,0 +1,144 @@
+/**
+ * Lint: 检测 adapter/ 外部直接访问 runtime.channel.* 的代码
+ *
+ * 运行方式：
+ *   npx tsx src/adapter/lint-runtime-access.ts
+ *
+ * 退出码：
+ *   0 = 无违规
+ *   1 = 存在未加白的直接 runtime 访问
+ *
+ * 加白方式（行内注释）：
+ *   // @adapter-bypass: <理由>
+ *
+ * 示例：
+ *   const tts = (runtime as any)?.tts; // @adapter-bypass: TTS 非 channel API，无需经过适配层
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+// ── 配置 ──
+
+const SRC_ROOT = path.resolve(import.meta.dirname, '..');
+const ADAPTER_DIR = path.resolve(SRC_ROOT, 'adapter');
+
+/** 匹配直接使用 runtime.channel / runtime.config / (runtime as any) 的模式 */
+const VIOLATION_PATTERNS: RegExp[] = [
+  /runtime\.channel\b/,
+  /runtime\.config\b/,
+  /\(runtime\s+as\s+any\)/,
+  /channel\??\.(inbound|turn|reply|session|routing|text|media|runtimeContexts)\b/,
+  /config\s+as\s*\{.*writeConfigFile/,
+];
+
+/** 加白注释标记 */
+const BYPASS_MARKER = '@adapter-bypass';
+
+/** 排除的目录/文件 */
+const EXCLUDE_DIRS = ['adapter', 'node_modules', 'dist', 'tests'];
+const EXCLUDE_FILES = ['types.ts', 'types-augment.d.ts', 'openclaw-plugin-sdk.d.ts'];
+
+// ── 扫描逻辑 ──
+
+interface Violation {
+  file: string;
+  line: number;
+  content: string;
+  pattern: string;
+}
+
+function shouldExclude(filePath: string): boolean {
+  const relative = path.relative(SRC_ROOT, filePath);
+  // 排除 adapter 自身
+  if (filePath.startsWith(ADAPTER_DIR)) return true;
+  // 排除配置的目录
+  for (const dir of EXCLUDE_DIRS) {
+    if (relative.startsWith(dir + '/') || relative === dir) return true;
+  }
+  // 排除特定文件
+  const fileName = path.basename(filePath);
+  if (EXCLUDE_FILES.includes(fileName)) return true;
+  return false;
+}
+
+function scanFile(filePath: string): Violation[] {
+  const violations: Violation[] = [];
+  const content = fs.readFileSync(filePath, 'utf8');
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNum = i + 1;
+
+    // 跳过注释行（单行注释、JSDoc 行、多行注释体）
+    const trimmed = line.trimStart();
+    if (trimmed.startsWith('//') || trimmed.startsWith('*') || trimmed.startsWith('/**') || trimmed.startsWith('*/')) continue;
+
+    // 检查加白标记
+    if (line.includes(BYPASS_MARKER)) continue;
+
+    // 检查违规模式
+    for (const pattern of VIOLATION_PATTERNS) {
+      if (pattern.test(line)) {
+        violations.push({
+          file: path.relative(SRC_ROOT, filePath),
+          line: lineNum,
+          content: line.trim(),
+          pattern: pattern.source,
+        });
+        break; // 同一行只报一次
+      }
+    }
+  }
+
+  return violations;
+}
+
+function walkDir(dir: string): string[] {
+  const results: string[] = [];
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (!EXCLUDE_DIRS.includes(entry.name)) {
+        results.push(...walkDir(fullPath));
+      }
+    } else if (entry.isFile() && entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+// ── 主流程 ──
+
+function main(): void {
+  const files = walkDir(SRC_ROOT).filter((f) => !shouldExclude(f));
+  const allViolations: Violation[] = [];
+
+  for (const file of files) {
+    const violations = scanFile(file);
+    allViolations.push(...violations);
+  }
+
+  if (allViolations.length === 0) {
+    console.log('✅ No direct runtime access found outside adapter/');
+    process.exit(0);
+  }
+
+  console.error(`❌ Found ${allViolations.length} direct runtime access violation(s):\n`);
+  for (const v of allViolations) {
+    console.error(`  ${v.file}:${v.line}`);
+    console.error(`    ${v.content}`);
+    console.error(`    → matched: ${v.pattern}`);
+    console.error(`    → fix: use adapter or add "// @adapter-bypass: <reason>"\n`);
+  }
+  console.error(
+    `\nTo bypass a specific line, add an inline comment:\n` +
+    `  // @adapter-bypass: <reason why this cannot go through the adapter>\n`,
+  );
+  process.exit(1);
+}
+
+main();

package/src/adapter/media.ts

@@ -0,0 +1,112 @@
+/**
+ * 远程媒体下载（动态加载 plugin-sdk/media-runtime，降级到 fetch）
+ *
+ * 新版本 openclaw 有 openclaw/plugin-sdk/media-runtime（含 SSRF 防护/重试/大小限制），
+ * 旧版本不可用时降级到原生 fetch 直连。
+ */
+import { createRequire } from 'node:module';
+import * as dns from 'node:dns';
+import * as path from 'node:path';
+import * as fs from 'node:fs';
+import * as crypto from 'node:crypto';
+import { getQQBotMediaDir } from '../utils/platform.js';
+
+const req = createRequire(__filename);
+
+type SaveRemoteMedia = (opts: {
+  url: string;
+  subdir?: string;
+  originalFilename?: string;
+  maxBytes?: number;
+  timeoutMs?: number;
+}) => Promise<{ path: string }>;
+
+let _save: SaveRemoteMedia | null | undefined;
+
+export function downloadRemoteMedia(opts: {
+  url: string;
+  subdir?: string;
+  originalFilename?: string;
+  maxBytes?: number;
+  timeoutMs?: number;
+}): Promise<{ path: string }> {
+  if (_save === undefined) {
+    try {
+      const mod = req('openclaw/plugin-sdk/media-runtime') as { saveRemoteMedia: SaveRemoteMedia };
+      _save = mod.saveRemoteMedia;
+    } catch {
+      _save = null;
+    }
+  }
+  return _save ? _save(opts) : downloadViaFetch(opts);
+}
+
+// ── SSRF 防护 ──
+
+const PRIVATE_RANGES: Array<[netmask: bigint, prefix: number]> = [
+  [0x0A000000n, 8],      // 10.0.0.0/8
+  [0xAC100000n, 12],     // 172.16.0.0/12
+  [0xC0A80000n, 16],     // 192.168.0.0/16
+  [0x7F000000n, 8],      // 127.0.0.0/8
+  [0xA9FE0000n, 16],     // 169.254.0.0/16
+  [0xE0000000n, 4],      // 224.0.0.0/4 (multicast)
+];
+
+function ipToBigInt(ip: string): bigint {
+  return ip.split('.').reduce((acc, octet) => (acc << 8n) | BigInt(Number(octet)), 0n);
+}
+
+function isPrivateIP(ip: string): boolean {
+  const val = ipToBigInt(ip);
+  return PRIVATE_RANGES.some(([mask, prefix]) => (val >> (32n - BigInt(prefix))) === (mask >> (32n - BigInt(prefix))));
+}
+
+async function assertSafeHostname(hostname: string): Promise<void> {
+  const addresses = await dns.promises.resolve4(hostname).catch(() => []);
+  if (addresses.length === 0) throw new Error(`DNS resolution failed: ${hostname}`);
+  for (const addr of addresses) {
+    if (isPrivateIP(addr)) {
+      throw new Error(`SSRF blocked: ${hostname} resolves to private IP ${addr}`);
+    }
+  }
+}
+
+// ── 降级 fetch ──
+
+/** 降级：原生 fetch 直连（含 SSRF 防护、大小限制） */
+async function downloadViaFetch(opts: {
+  url: string;
+  subdir?: string;
+  originalFilename?: string;
+  maxBytes?: number;
+  timeoutMs?: number;
+}): Promise<{ path: string }> {
+  const parsed = new URL(opts.url);
+  if (parsed.protocol !== 'https:') {
+    throw new Error(`Only HTTPS allowed: ${parsed.protocol}`);
+  }
+  await assertSafeHostname(parsed.hostname);
+
+  const dir = getQQBotMediaDir(opts.subdir ?? 'downloads');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  const resp = await fetch(opts.url, {
+    signal: AbortSignal.timeout(opts.timeoutMs ?? 120_000),
+  });
+  if (!resp.ok) throw new Error(`Download HTTP ${resp.status}`);
+
+  const maxBytes = opts.maxBytes ?? 500 * 1024 * 1024;
+  const buf = Buffer.from(await resp.arrayBuffer());
+  if (buf.length > maxBytes) throw new Error(`Download exceeds ${(maxBytes / 1024 / 1024).toFixed(0)}MB`);
+
+  const ext = opts.originalFilename
+    ? path.extname(opts.originalFilename) || '.bin'
+    : '.bin';
+  const name = opts.originalFilename
+    ? path.basename(opts.originalFilename, path.extname(opts.originalFilename))
+    : 'download';
+  const rand = crypto.randomBytes(4).toString('hex');
+  const filePath = path.join(dir, `${name}_${Date.now()}_${rand}${ext}`);
+  fs.writeFileSync(filePath, buf);
+  return { path: filePath };
+}

package/src/adapter/pairing.ts

@@ -0,0 +1,99 @@
+/**
+ * Pairing Runtime 动态加载（兼容旧版框架）
+ *
+ * 从 OpenClaw 安装目录动态加载 conversation-runtime 模块中的配对函数。
+ * 不支持时返回 null，配对功能降级为不可用。
+ */
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+export interface PairingApi {
+  readAllowFromStore: (params: { channel: string; accountId: string }) => Promise<string[]>;
+  issueChallenge: (params: { channel: string; id: string; accountId: string }) => Promise<{ code: string }>;
+  buildReply: (params: { code: string; channel: string }) => string;
+  approveCode: (params: { channel: string; code: string; accountId?: string }) => Promise<{ id: string } | null>;
+}
+
+let _api: PairingApi | null | undefined;
+
+/** 获取 Pairing API，首次调用触发加载并缓存 */
+export function getPairingApi(): PairingApi | null {
+  if (_api !== undefined) return _api;
+  _api = loadPairingApi();
+  return _api;
+}
+
+function loadPairingApi(): PairingApi | null {
+  const currentFile = __filename;
+  const req = createRequire(currentFile);
+  const pluginRoot = path.resolve(path.dirname(currentFile), '..', '..');
+  const fs = req('node:fs') as typeof import('node:fs');
+
+  const tryLoad = (root: string) => {
+    for (const rel of ['dist/plugin-sdk/conversation-runtime.js', 'plugin-sdk/conversation-runtime.js']) {
+      const p = path.join(root, rel);
+      try {
+        if (fs.existsSync(p)) return req(p);
+      } catch { /* try next */ }
+    }
+    return null;
+  };
+
+  let mod: any = null;
+  try {
+    const { findOpenclawRoot } = req(path.join(pluginRoot, 'scripts', 'link-sdk-core.cjs')) as {
+      findOpenclawRoot: (root: string) => string | null;
+    };
+    const root = findOpenclawRoot(pluginRoot);
+    if (root) mod = tryLoad(root);
+  } catch { /* fallback */ }
+
+  if (!mod) {
+    try {
+      const entry = process.argv[1];
+      if (entry) {
+        const realEntry = fs.realpathSync(entry);
+        let dir = path.dirname(realEntry);
+        for (let i = 0; i < 6; i++) {
+          mod = tryLoad(dir);
+          if (mod) break;
+          const parent = path.dirname(dir);
+          if (parent === dir) break;
+          dir = parent;
+        }
+      }
+    } catch { /* fallback */ }
+  }
+
+  if (!mod?.readChannelAllowFromStore) return null;
+
+  return {
+    // readChannelAllowFromStore(channel, env?, accountId?) — 位置参数
+    readAllowFromStore: (params) =>
+      mod.readChannelAllowFromStore(params.channel, undefined, params.accountId),
+
+    // upsertChannelPairingRequest({ channel, id, accountId }) — 对象参数
+    issueChallenge: (params) =>
+      mod.upsertChannelPairingRequest({
+        channel: params.channel,
+        id: params.id,
+        accountId: params.accountId,
+      }).then((r: any) => ({ code: r.code as string })),
+
+    // buildPairingReply({ channel, idLine, code }) — 对象参数
+    buildReply: (params) =>
+      mod.buildPairingReply({
+        channel: params.channel,
+        idLine: '', // qqbot 无额外 ID 信息，留空即可
+        code: params.code,
+      }),
+
+    // approveChannelPairingCode({ channel, code, accountId? }) — 对象参数
+    approveCode: (params) =>
+      mod.approveChannelPairingCode({
+        channel: params.channel,
+        code: params.code,
+        accountId: params.accountId,
+      }),
+  };
+}

package/src/adapter/resolve.ts

@@ -0,0 +1,333 @@
+/**
+ * Runtime Adapters — 一次 resolve，全程复用。
+ *
+ * Capability Probe 模式：按候选 API 路径探测，选出第一个可用函数。
+ * 对每个 runtime API 维护一个"候选列表"（最新在前），未来 API 改名时只需 +1 行。
+ *
+ * 调用方通过 `resolveRuntimeAdapters(runtime)` 获取适配层对象，
+ * 后续所有 dispatch / channel 代码只使用 adapters 上的方法。
+ */
+
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+
+// ── 类型 ──
+
+export interface RuntimeAdapters {
+  /** 入站事件处理（自动适配 inbound.run / turn.run） */
+  inboundRun: ((params: any) => Promise<any>) | null;
+  /** 回复分发（带 block buffer） */
+  dispatchReply: ((params: any) => Promise<any>) | null;
+  /** Agent 路由解析 */
+  resolveAgentRoute: ((params: any) => any) | null;
+  /** 构建入站上下文（自动适配 inbound.buildContext / reply.finalizeInboundContext） */
+  buildInboundContext: ((params: any) => any) | null;
+  /** Session store path 解析 */
+  resolveStorePath: ((storeConfig: any, opts: any) => string) | null;
+  /** Session 记录 */
+  recordInboundSession: ((params: any) => Promise<void>) | null;
+  /** 格式化 envelope（自动适配 formatAgentEnvelope / formatInboundEnvelope） */
+  formatEnvelope: ((params: any) => string) | null;
+  /** 解析 envelope format options */
+  resolveEnvelopeFormatOptions: ((cfg: any) => any) | null;
+  /** Markdown 文本分块 */
+  chunkMarkdownText: ((text: string, limit: number) => string[]) | null;
+  /** 远程媒体保存（图片/语音下载） */
+  saveRemoteMedia: ((opts: { url: string; subdir?: string; originalFilename?: string }) => Promise<{ path: string } | null>) | null;
+  /** 获取当前配置快照 */
+  getConfig: (() => any) | null;
+  /**
+   * 持久化配置变更（高低版本兼容）。
+   *
+   * 内部优先级：
+   *   1. mutateConfigFile（新版 API，原子操作，支持 afterWrite 策略）
+   *   2. writeConfigFile（旧版 API，整体覆盖）
+   *
+   * 调用方只需传入完整 config 对象，不必关心框架版本差异。
+   */
+  /**
+   * 持久化配置变更（高低版本兼容）。
+   *
+   * 接受一个 mutator 回调，接收当前 config 对象（可变），
+   * 可直接修改或返回新对象。适配器负责确保写入和热重载。
+   */
+  persistConfig: ((mutator: (cfg: any) => any) => Promise<void>) | null;
+  /** openclaw 版本 */
+  version: string;
+}
+
+// ── Probe 辅助 ──
+
+type ProbePath = string[];
+
+/**
+ * 从 runtime 对象沿路径探测函数。返回 bound function 或 null。
+ */
+function probeFunction(rt: any, paths: ProbePath[]): ((...args: any[]) => any) | null {
+  for (const path of paths) {
+    let target = rt;
+    let parent = rt;
+    for (let i = 0; i < path.length; i++) {
+      parent = target;
+      target = target?.[path[i]];
+      if (target === undefined || target === null) break;
+    }
+    if (typeof target === 'function') {
+      // bind 到 parent（倒数第二层），确保 this 上下文正确
+      return target.bind(parent);
+    }
+  }
+  return null;
+}
+
+/**
+ * 从 runtime 对象沿路径探测值（非函数也可）。返回值或 null。
+ */
+function probeValue(rt: any, paths: ProbePath[]): any {
+  for (const path of paths) {
+    let target = rt;
+    for (const key of path) {
+      target = target?.[key];
+      if (target === undefined || target === null) break;
+    }
+    if (target !== undefined && target !== null) return target;
+  }
+  return null;
+}
+
+// ── 主入口 ──
+
+/**
+ * 一次性 resolve 所有 runtime adapter。
+ *
+ * 通常在 gateway ready 后（首条消息到来前）调用一次，结果缓存复用。
+ * 返回 null 的字段表示该能力不可用，调用方按需降级或走 fallback。
+ */
+export function resolveRuntimeAdapters(
+  rt: PluginRuntime,
+  log?: PluginLogger,
+): RuntimeAdapters {
+  const version = (rt as any).version ?? 'unknown';
+
+  const inboundRun = probeFunction(rt, [
+    ['channel', 'inbound', 'run'],      // current (2026-05+)
+    ['channel', 'turn', 'run'],          // legacy (removed 2026-05-27)
+  ]);
+
+  const dispatchReply = probeFunction(rt, [
+    ['channel', 'reply', 'dispatchReplyWithBufferedBlockDispatcher'],
+  ]);
+
+  const resolveAgentRoute = probeFunction(rt, [
+    ['channel', 'routing', 'resolveAgentRoute'],
+  ]);
+
+  // 构建入站上下文：新 API 优先，低版本 fallback 到 deprecated finalizeInboundContext
+  // 两个 API 签名不同，通过 wrapper 统一为 buildInboundContext(params) 接口
+  const rawBuildContext = probeFunction(rt, [
+    ['channel', 'inbound', 'buildContext'],
+  ]);
+  const rawFinalizeContext = !rawBuildContext
+    ? probeFunction(rt, [['channel', 'reply', 'finalizeInboundContext']])
+    : null;
+
+  const buildInboundContext: RuntimeAdapters['buildInboundContext'] = rawBuildContext
+    ? (params) => rawBuildContext(params)
+    : rawFinalizeContext
+      ? (params) => {
+          // 将统一参数转换为旧 API 的 rawCtxPayload 格式
+          const isCommand = params.access?.commands?.authorized ?? false;
+          const rawCtx = {
+            Body: params.message.body,
+            BodyForAgent: params.message.bodyForAgent,
+            RawBody: params.message.rawBody,
+            CommandBody: params.message.commandBody ?? params.message.rawBody,
+            CommandSource: isCommand ? 'text' : undefined,
+            CommandTurn: params.command ?? undefined,
+            CommandAuthorized: isCommand,
+            From: params.from,
+            To: params.reply.to,
+            SessionKey: params.route.routeSessionKey,
+            AccountId: params.route.accountId ?? params.accountId,
+            ChatType: params.conversation.kind,
+            GroupSystemPrompt: params.conversation.label,
+            SenderId: params.sender.id,
+            SenderName: params.sender.name,
+            Provider: params.provider ?? params.channel,
+            Surface: params.surface ?? params.channel,
+            MessageSid: params.messageId,
+            Timestamp: params.timestamp ?? Date.now(),
+            OriginatingChannel: params.channel,
+            OriginatingTo: params.reply.originatingTo ?? params.reply.to,
+            ...params.extra,
+          };
+          return rawFinalizeContext(rawCtx);
+        }
+      : null;
+
+  const resolveStorePath = probeFunction(rt, [
+    ['channel', 'session', 'resolveStorePath'],
+  ]);
+
+  const recordInboundSession = probeFunction(rt, [
+    ['channel', 'session', 'recordInboundSession'],
+  ]);
+
+  // 格式化 envelope：新 API 优先，低版本 fallback 到 deprecated formatInboundEnvelope
+  const formatEnvelope = probeFunction(rt, [
+    ['channel', 'reply', 'formatAgentEnvelope'],    // current (2026-06+)
+    ['channel', 'reply', 'formatInboundEnvelope'],  // deprecated，低版本兼容
+  ]);
+
+  const resolveEnvelopeFormatOptions = probeFunction(rt, [
+    ['channel', 'reply', 'resolveEnvelopeFormatOptions'],
+  ]);
+
+  const chunkMarkdownText = probeFunction(rt, [
+    ['channel', 'text', 'chunkMarkdownText'],
+  ]);
+
+  const saveRemoteMedia = probeFunction(rt, [
+    ['channel', 'media', 'saveRemoteMedia'],
+  ]);
+
+  const getConfig = probeFunction(rt, [
+    ['config', 'current'],
+  ]) ?? probeFunction(rt, [
+    ['getConfig'],
+  ]) ?? probeFunction(rt, [
+    ['config', 'loadConfig'],
+  ]);
+
+  // config 持久化：优先 mutateConfigFile（新版，原子操作），fallback writeConfigFile（旧版）
+  const rawMutateConfig = probeFunction(rt, [['config', 'mutateConfigFile']]);
+  const rawWriteConfig = probeFunction(rt, [['config', 'writeConfigFile']]);
+
+  const persistConfig: RuntimeAdapters['persistConfig'] = rawMutateConfig
+    ? async (mutator: (cfg: any) => any) => {
+        // 新版 API：mutate 回调接收当前 config，可直接修改或返回新对象
+        await rawMutateConfig({
+          afterWrite: 'hot-reload',
+          mutate: mutator,
+        });
+      }
+    : rawWriteConfig && getConfig
+      ? async (mutator: (cfg: any) => any) => {
+          // 旧版 API：先读取当前 config → 应用 mutator → 整体写入
+          const current = JSON.parse(JSON.stringify(getConfig()));
+          mutator(current);
+          await rawWriteConfig(current);
+        }
+      : null;
+
+  // 日志汇总
+  const resolved = [
+    inboundRun && 'inboundRun',
+    dispatchReply && 'dispatchReply',
+    resolveAgentRoute && 'resolveAgentRoute',
+    buildInboundContext && 'buildInboundContext',
+    resolveStorePath && 'resolveStorePath',
+    recordInboundSession && 'recordInboundSession',
+    formatEnvelope && 'formatEnvelope',
+    chunkMarkdownText && 'chunkMarkdownText',
+    saveRemoteMedia && 'saveRemoteMedia',
+    getConfig && 'getConfig',
+    persistConfig && `persistConfig(${rawMutateConfig ? 'mutate' : 'write'})`,
+  ].filter(Boolean);
+
+  log?.info(
+    `[qqbot:adapter] openclaw=${version} resolved ${resolved.length} adapters: ${resolved.join(', ')}`,
+  );
+
+  return {
+    inboundRun,
+    dispatchReply,
+    resolveAgentRoute,
+    buildInboundContext,
+    resolveStorePath,
+    recordInboundSession,
+    formatEnvelope,
+    resolveEnvelopeFormatOptions,
+    chunkMarkdownText,
+    saveRemoteMedia,
+    getConfig,
+    persistConfig,
+    version,
+  };
+}
+
+// ── 全局缓存（所有消费者共享同一份 adapters） ──
+
+let _cachedAdapters: RuntimeAdapters | null = null;
+let _cachedRuntimeRef: WeakRef<PluginRuntime> | null = null;
+
+/**
+ * 获取 RuntimeAdapters 的全局缓存版本。
+ *
+ * - 自动基于 runtime 实例的 WeakRef 判断是否需要重新 resolve
+ * - 如果 runtime 被替换（框架热更新、二次 register），自动刷新
+ * - 所有消费者（dispatch / channel / middleware）共用一份，避免重复 probe
+ *
+ * @param rt 当前 PluginRuntime 实例
+ * @param log 可选日志（仅在首次 resolve 或 runtime 变更时输出）
+ */
+export function getAdapters(
+  rt: PluginRuntime,
+  log?: PluginLogger,
+): RuntimeAdapters {
+  const cached = _cachedRuntimeRef?.deref();
+  if (cached === rt && _cachedAdapters) {
+    return _cachedAdapters;
+  }
+  // runtime 引用变化（首次 / 热更新）→ 重新 resolve
+  _cachedAdapters = resolveRuntimeAdapters(rt, log);
+  _cachedRuntimeRef = new WeakRef(rt);
+  return _cachedAdapters;
+}
+
+/**
+ * 持久化配置（auth.login 场景，兼容高低版本）。
+ *
+ * 探测顺序：
+ *   1. config.mutateConfigFile  — 新版原子操作
+ *   2. config.writeConfigFile   — 旧版整体覆盖
+ *   3. writeConfigFile          — 更旧的顶层 API
+ */
+export async function persistAuthConfig(
+  runtime: Record<string, unknown>,
+  cfg: Record<string, unknown>,
+  afterWrite = 'restart',
+): Promise<void> {
+  const config: Record<string, unknown> | undefined = runtime.config as any;
+
+  if (typeof config?.mutateConfigFile === 'function') {
+    await (config.mutateConfigFile as Function)({
+      mutate: () => cfg,
+      afterWrite,
+    });
+    return;
+  }
+  if (typeof config?.writeConfigFile === 'function') {
+    await (config.writeConfigFile as Function)(cfg);
+    return;
+  }
+  if (typeof runtime.writeConfigFile === 'function') {
+    await (runtime.writeConfigFile as Function)(cfg);
+    return;
+  }
+
+  // 最后兜底：裸写文件
+  const { homedir } = await import('node:os');
+  const { join } = await import('node:path');
+  const { writeFileSync } = await import('node:fs');
+  writeFileSync(join(homedir(), '.openclaw', 'openclaw.json'), JSON.stringify(cfg, null, 2) + '\n', 'utf-8');
+}
+
+/**
+ * 强制清除 adapter 缓存（仅测试用）
+ */
+export function _resetAdaptersCache(): void {
+  _cachedAdapters = null;
+  _cachedRuntimeRef = null;
+}
+