@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/features/ref-index-store.ts

@@ -0,0 +1,282 @@
+/**
+ * 持久化 RefIndex 存储
+ *
+ * SDK 提供的 MemoryRefIndexStore 在进程重启后即丢失，
+ * 而 QQ 引用消息（REFIDX_xxx）入站事件只携带 key，必须本地缓存才能回查。
+ *
+ * 设计：
+ *   - 内存 LRU（与 SDK 同款）保证 O(1) 读取
+ *   - JSONL 追加写持久化，进程重启时按时间顺序回放重建 LRU
+ *   - 写入触发 compact 阈值时重写文件（去重 + 截断到 maxEntries）
+ *   - 文件路径: ~/.openclaw/qqbot/data/ref-index.jsonl
+ *
+ * 实现 SDK 的 RefIndexStore 接口，可直接通过 `quoteRef({ store })` 注入。
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import type { RefEntry, RefIndexStore } from '@tencent-connect/qqbot-nodejs';
+import { getQQBotDataDir } from '../utils/platform.js';
+import { createPluginLogger } from '../utils/plugin-logger.js';
+const log = createPluginLogger({ prefix: '[ref-index]' });
+
+
+// ── 常量 ──
+
+const DEFAULT_MAX_ENTRIES = 50000;
+const DEFAULT_FILENAME = 'ref-index.jsonl';
+/** 当磁盘 line 数超过 maxEntries * COMPACT_RATIO 时触发 compact */
+const COMPACT_RATIO = 2;
+/** 内存 LRU 的最小容量保护值 */
+const MIN_MAX_ENTRIES = 100;
+
+// ── 磁盘行结构 ──
+
+interface DiskLine {
+  /** RefIndex 键，例如 REFIDX_xxx 或 messageId */
+  k: string;
+  /** RefEntry 内容 */
+  v: RefEntry;
+  /** 写入时间戳（毫秒） */
+  t: number;
+}
+
+// ── 持久化 Store ──
+
+export interface PersistedRefIndexStoreOptions {
+  /** 内存与磁盘的最大条目数。默认 2000。 */
+  maxEntries?: number;
+  /** 自定义存储文件路径。默认 ~/.openclaw/qqbot/data/ref-index.jsonl */
+  filePath?: string;
+}
+
+/**
+ * 持久化版本的 RefIndexStore
+ *
+ * - get：仅查内存（启动时从磁盘回放重建）
+ * - set：内存 + JSONL 追加写；磁盘行数过多时触发 compact
+ */
+export class PersistedRefIndexStore implements RefIndexStore {
+  private readonly memory = new Map<string, RefEntry>();
+  private readonly maxEntries: number;
+  private readonly filePath: string;
+  /** 当前磁盘累计写入的行数（用于 compact 阈值判断） */
+  private diskLineCount = 0;
+  /** 是否已成功初始化（磁盘回放完成） */
+  private initialized = false;
+  /** 串行化写入，防止并发 append 撕裂行 */
+  private writeChain: Promise<void> = Promise.resolve();
+
+  constructor(options: PersistedRefIndexStoreOptions = {}) {
+    this.maxEntries = Math.max(options.maxEntries ?? DEFAULT_MAX_ENTRIES, MIN_MAX_ENTRIES);
+    this.filePath = options.filePath ?? path.join(getQQBotDataDir('data'), DEFAULT_FILENAME);
+    this.init();
+  }
+
+  /**
+   * 初始化：按时间顺序回放 JSONL 重建内存 LRU
+   */
+  private init(): void {
+    try {
+      if (!fs.existsSync(this.filePath)) {
+        this.initialized = true;
+        return;
+      }
+      const raw = fs.readFileSync(this.filePath, 'utf8');
+      const lines = raw.split('\n').filter((l) => l.length > 0);
+      this.diskLineCount = lines.length;
+
+      // 按时间排序回放（防止文件被外部修改后乱序）
+      const parsed: DiskLine[] = [];
+      for (const line of lines) {
+        try {
+          const obj = JSON.parse(line) as DiskLine;
+          if (obj?.k && obj?.v) {
+            parsed.push(obj);
+          }
+        } catch {
+          // 跳过损坏行
+        }
+      }
+      parsed.sort((a, b) => a.t - b.t);
+
+      for (const { k, v } of parsed) {
+        this.touchMemory(k, v);
+      }
+
+      // 启动时若磁盘行数已超阈值，立刻 compact 一次
+      if (this.diskLineCount > this.maxEntries * COMPACT_RATIO) {
+        this.compactSync();
+      }
+    } catch (err) {
+      log.error(
+        `init failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    } finally {
+      this.initialized = true;
+    }
+  }
+
+  // ── RefIndexStore 接口 ──
+
+  get(key: string): RefEntry | undefined {
+    return this.memory.get(key);
+  }
+
+  set(key: string, entry: RefEntry): void {
+    this.touchMemory(key, entry);
+    // 追加写持久化（串行化）
+    this.writeChain = this.writeChain.then(() => this.appendToDisk(key, entry));
+  }
+
+  // ── 内部：内存 LRU 维护 ──
+
+  private touchMemory(key: string, entry: RefEntry): void {
+    // 已存在则先删除再插入，保证插入顺序 = LRU 顺序
+    if (this.memory.has(key)) {
+      this.memory.delete(key);
+    } else if (this.memory.size >= this.maxEntries) {
+      // 容量已满 → 淘汰最旧的（Map 的迭代顺序即插入顺序）
+      const oldest = this.memory.keys().next().value;
+      if (oldest !== undefined) {
+        this.memory.delete(oldest);
+      }
+    }
+    this.memory.set(key, entry);
+  }
+
+  // ── 内部：磁盘追加 + compact ──
+
+  private async appendToDisk(key: string, entry: RefEntry): Promise<void> {
+    const line: DiskLine = { k: key, v: entry, t: Date.now() };
+    const text = JSON.stringify(line) + '\n';
+    try {
+      await fs.promises.appendFile(this.filePath, text, 'utf8');
+      this.diskLineCount += 1;
+      if (this.diskLineCount > this.maxEntries * COMPACT_RATIO) {
+        await this.compact();
+      }
+    } catch (err) {
+      log.error(
+        `append failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  /**
+   * 异步 compact：将内存 LRU 状态完整重写到磁盘，丢弃历史冗余。
+   */
+  private async compact(): Promise<void> {
+    const tmpPath = `${this.filePath}.tmp`;
+    try {
+      const now = Date.now();
+      // Map 迭代顺序 = 插入顺序（旧 → 新），保持 LRU 顺序
+      const lines: string[] = [];
+      for (const [k, v] of this.memory.entries()) {
+        lines.push(JSON.stringify({ k, v, t: now } satisfies DiskLine));
+      }
+      const content = lines.length > 0 ? lines.join('\n') + '\n' : '';
+      await fs.promises.writeFile(tmpPath, content, 'utf8');
+      await fs.promises.rename(tmpPath, this.filePath);
+      this.diskLineCount = lines.length;
+      log.info(
+        `compacted to ${lines.length} entries`,
+      );
+    } catch (err) {
+      log.error(
+        `compact failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      // 清理可能残留的 tmp 文件
+      try {
+        await fs.promises.unlink(tmpPath);
+      } catch {
+        // ignore
+      }
+    }
+  }
+
+  /**
+   * 同步 compact（仅 init 阶段使用，避免回放后立刻保留巨大磁盘文件）
+   */
+  private compactSync(): void {
+    const tmpPath = `${this.filePath}.tmp`;
+    try {
+      const now = Date.now();
+      const lines: string[] = [];
+      for (const [k, v] of this.memory.entries()) {
+        lines.push(JSON.stringify({ k, v, t: now } satisfies DiskLine));
+      }
+      const content = lines.length > 0 ? lines.join('\n') + '\n' : '';
+      fs.writeFileSync(tmpPath, content, 'utf8');
+      fs.renameSync(tmpPath, this.filePath);
+      this.diskLineCount = lines.length;
+    } catch (err) {
+      log.error(
+        `compactSync failed: ${err instanceof Error ? err.message : String(err)}`,
+      );
+    }
+  }
+
+  // ── 诊断 ──
+
+  /** 当前内存中的条目数 */
+  get size(): number {
+    return this.memory.size;
+  }
+
+  /** 是否已完成初始化（磁盘回放） */
+  get isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  /** 诊断快照 */
+  stats(): {
+    memoryEntries: number;
+    diskLines: number;
+    maxEntries: number;
+    filePath: string;
+  } {
+    return {
+      memoryEntries: this.memory.size,
+      diskLines: this.diskLineCount,
+      maxEntries: this.maxEntries,
+      filePath: this.filePath,
+    };
+  }
+
+  /**
+   * 强制将当前内存状态持久化到磁盘（进程退出前调用）
+   */
+  flush(): void {
+    this.compactSync();
+  }
+}
+
+// ── 默认单例（按 accountId 隔离） ──
+
+const stores = new Map<string, PersistedRefIndexStore>();
+
+/**
+ * 获取按 accountId 隔离的持久化 RefIndexStore 单例。
+ *
+ * 每个账户独立存储文件，避免多账户混用同一个 refIdx 命名空间。
+ */
+
+export function getPersistedRefIndexStore(accountId: string): PersistedRefIndexStore {
+  let store = stores.get(accountId);
+  if (!store) {
+    const filePath = path.join(getQQBotDataDir('data', accountId), DEFAULT_FILENAME);
+    store = new PersistedRefIndexStore({ filePath });
+    stores.set(accountId, store);
+  }
+  return store;
+}
+
+/**
+ * 进程退出前 flush 所有 store
+ */
+export function flushAllRefIndexStores(): void {
+  for (const store of stores.values()) {
+    store.flush();
+  }
+}

package/src/{update-checker.ts → features/update-checker.ts}

@@ -8,11 +8,9 @@
  * 支持多 registry fallback：npmjs.org → npmmirror.com，解决国内网络问题。
  */
 
-import { createRequire } from "node:module";
 import https from "node:https";
-import { getPackageVersion } from "./utils/pkg-version.js";
-
-const require = createRequire(import.meta.url);
+import { getPackageVersion } from "../utils/pkg-version.js";
+import type { PluginLogger } from '../utils/plugin-logger.js';
 
 const PKG_NAME = "@tencent-connect/openclaw-qqbot";
 const ENCODED_PKG = encodeURIComponent(PKG_NAME);
@@ -22,23 +20,18 @@ const REGISTRIES = [
   `https://registry.npmmirror.com/${ENCODED_PKG}`,
 ];
 
-let CURRENT_VERSION = getPackageVersion(import.meta.url);
+let CURRENT_VERSION = getPackageVersion();
 
 export interface UpdateInfo {
   current: string;
-  /** 最佳升级目标（prerelease 用户优先 alpha，稳定版用户取 latest） */
   latest: string | null;
-  /** 稳定版 dist-tag */
   stable: string | null;
-  /** alpha dist-tag */
   alpha: string | null;
   hasUpdate: boolean;
   checkedAt: number;
   error?: string;
 }
 
-let _log: { info: (msg: string) => void; error: (msg: string) => void; debug?: (msg: string) => void } | undefined;
-
 function fetchJson(url: string, timeoutMs: number): Promise<any> {
   return new Promise((resolve, reject) => {
     const req = https.get(url, { timeout: timeoutMs, headers: { Accept: "application/json" } }, (res) => {
@@ -58,14 +51,14 @@ function fetchJson(url: string, timeoutMs: number): Promise<any> {
   });
 }
 
-async function fetchDistTags(): Promise<Record<string, string>> {
+async function fetchDistTags(log?: PluginLogger): Promise<Record<string, string>> {
   for (const url of REGISTRIES) {
     try {
       const json = await fetchJson(url, 10_000);
       const tags = json["dist-tags"];
       if (tags && typeof tags === "object") return tags;
     } catch (e: any) {
-      _log?.debug?.(`[qqbot:update-checker] ${url} failed: ${e.message}`);
+      log?.debug(`[update-checker] ${url} failed: ${e.message}`);
     }
   }
   throw new Error("all registries failed");
@@ -76,7 +69,6 @@ function buildUpdateInfo(tags: Record<string, string>): UpdateInfo {
   const stableTag = tags.latest || null;
   const alphaTag = tags.alpha || null;
 
-  // 严格隔离：alpha 只跟 alpha 比，正式版只跟正式版比，不交叉
   const compareTarget = currentIsPrerelease ? alphaTag : stableTag;
 
   const hasUpdate = typeof compareTarget === "string"
@@ -93,37 +85,31 @@ function buildUpdateInfo(tags: Record<string, string>): UpdateInfo {
   };
 }
 
-/** gateway 启动时调用，保存 log 引用 */
-export function triggerUpdateCheck(log?: {
-  info: (msg: string) => void;
-  error: (msg: string) => void;
-  debug?: (msg: string) => void;
-}): void {
-  if (log) _log = log;
-  // 预热：fire-and-forget
-  getUpdateInfo().then((info) => {
+/**
+ * Gateway 启动时调用，后台预热版本缓存。
+ * log 通过闭包传递，避免模块级可变状态。
+ */
+export function triggerUpdateCheck(log: PluginLogger): void {
+  getUpdateInfo(log).then((info) => {
     if (info.hasUpdate) {
-      _log?.info?.(`[qqbot:update-checker] new version available: ${info.latest} (current: ${CURRENT_VERSION})`);
+      log.info(`[update-checker] new version available: ${info.latest} (current: ${CURRENT_VERSION})`);
     }
   }).catch(() => {});
 }
 
 /** 每次实时查询 npm registry */
-export async function getUpdateInfo(): Promise<UpdateInfo> {
+export async function getUpdateInfo(log?: PluginLogger): Promise<UpdateInfo> {
   try {
-    const tags = await fetchDistTags();
+    const tags = await fetchDistTags(log);
     return buildUpdateInfo(tags);
   } catch (err: any) {
-    _log?.debug?.(`[qqbot:update-checker] check failed: ${err.message}`);
+    log?.debug(`[update-checker] check failed: ${err.message}`);
     return { current: CURRENT_VERSION, latest: null, stable: null, alpha: null, hasUpdate: false, checkedAt: Date.now(), error: err.message };
   }
 }
 
 /**
  * 检查指定版本是否存在于 npm registry
- * 用于 /bot-upgrade --version 的前置校验
- * @param version 要检查的版本号
- * @param pkgName 可选的包名（如 "@ryantest/openclaw-qqbot"），默认使用内置包名
  */
 export async function checkVersionExists(version: string, pkgName?: string): Promise<boolean> {
   const registries = pkgName ? buildRegistries(pkgName) : REGISTRIES;
@@ -139,7 +125,6 @@ export async function checkVersionExists(version: string, pkgName?: string): Pro
   return false;
 }
 
-/** 根据自定义包名构建 registry URL 列表 */
 function buildRegistries(pkgName: string): string[] {
   const encoded = encodeURIComponent(pkgName);
   return [
@@ -156,16 +141,13 @@ function compareVersions(a: string, b: string): number {
   };
   const pa = parse(a);
   const pb = parse(b);
-  // 先比主版本号
   for (let i = 0; i < 3; i++) {
     const diff = (pa.parts[i] || 0) - (pb.parts[i] || 0);
     if (diff !== 0) return diff;
   }
-  // 主版本号相同：正式版 > prerelease
   if (!pa.pre && pb.pre) return 1;
   if (pa.pre && !pb.pre) return -1;
   if (!pa.pre && !pb.pre) return 0;
-  // 都是 prerelease：按段逐一比较（alpha.1 vs alpha.2）
   const aParts = pa.pre!.split(".");
   const bParts = pb.pre!.split(".");
   for (let i = 0; i < Math.max(aParts.length, bParts.length); i++) {
@@ -173,11 +155,9 @@ function compareVersions(a: string, b: string): number {
     const bP = bParts[i] ?? "";
     const aNum = Number(aP);
     const bNum = Number(bP);
-    // 都是数字则按数字比较
     if (!isNaN(aNum) && !isNaN(bNum)) {
       if (aNum !== bNum) return aNum - bNum;
     } else {
-      // 字符串比较
       if (aP < bP) return -1;
       if (aP > bP) return 1;
     }

package/src/gateway/event-handlers.ts

@@ -0,0 +1,241 @@
+/**
+ * QQBotGateway 事件处理
+ *
+ * 处理 SDK 的 message / interaction 事件：
+ * - message: 中间件处理完毕后，将消息转发到 OpenClaw AI
+ * - interaction: 配置更新 / 审批按钮
+ */
+
+import type { MiddlewareContext, QQBotInboundMessage, InteractionEvent } from '@tencent-connect/qqbot-nodejs';
+import type { PluginRuntime } from 'openclaw/plugin-sdk';
+import type { ResolvedQQBotAccount } from '../types.js';
+import type { PluginLogger } from '../utils/plugin-logger.js';
+import { dispatchToOpenClaw } from '../dispatch/index.js';
+import { runWithRequestContext } from '../request-context.js';
+import { getApprovalHandler } from '../features/approval-handler.js';
+import { recordKnownUser } from '../features/proactive.js';
+import { cacheMsgId } from '../features/msgid-cache.js';
+import { getAdapters } from '../adapter/resolve.js';
+import { resolveGroupConfigFromAccount, resolveGroupPolicy, resolveMentionPatterns } from '../config.js';
+import { getPackageVersion } from '../utils/pkg-version.js';
+import { getOpenClawVersion } from '../bot-instance.js';
+
+export async function handleMessage(
+  ctx: MiddlewareContext,
+  msg: QQBotInboundMessage,
+  account: ResolvedQQBotAccount,
+  runtime: PluginRuntime,
+  log: PluginLogger,
+): Promise<void> {
+  const hlog = log.child('handle');
+  const scope = msg.replyTarget.scope;
+  const targetId = scope === 'group'
+    ? `qqbot:group:${msg.replyTarget.targetId}`
+    : `qqbot:c2c:${msg.replyTarget.targetId}`;
+
+  const mergedCount = (ctx.state.mergedMessages as unknown[] | undefined)?.length;
+  if (mergedCount) {
+    hlog.info(`merged batch count=${mergedCount} msgId=${msg.messageId}`);
+  } else {
+    hlog.debug(`enter msgId=${msg.messageId} scope=${scope} contentLen=${(msg.content ?? '').length}`);
+  }
+
+  try {
+    cacheMsgId(scope, msg.replyTarget.targetId, msg.messageId);
+
+    recordKnownUser({
+      type: scope === 'group' ? 'group' : 'c2c',
+      openid: scope === 'group' ? msg.replyTarget.targetId : msg.senderId,
+      accountId: account.accountId,
+      nickname: msg.senderName,
+      lastInteractionAt: Date.now(),
+    });
+
+    await runWithRequestContext(
+      {
+        accountId: account.accountId,
+        messageId: msg.messageId,
+        openId: msg.senderId,
+        target: targetId,
+      },
+      () => dispatchToOpenClaw(ctx, msg, account, runtime, log),
+    );
+  } catch (err) {
+    hlog.error(`dispatch error: ${err}`);
+  }
+  hlog.debug(`done msgId=${msg.messageId}`);
+}
+
+const INTERACTION_QUERY  = 2001;
+const INTERACTION_UPDATE = 2002;
+
+export async function handleInteraction(
+  event: InteractionEvent,
+  account: ResolvedQQBotAccount,
+  runtime: PluginRuntime,
+  log: PluginLogger,
+  acknowledgeInteraction: (id: string, code?: number, data?: Record<string, unknown>) => Promise<void>,
+): Promise<void> {
+  if (event.data?.type === INTERACTION_QUERY) {
+    await handleConfigQuery(event, account, runtime, log, acknowledgeInteraction);
+    return;
+  }
+  if (event.data?.type === INTERACTION_UPDATE) {
+    await handleConfigUpdate(event, account, runtime, log);
+    try {
+      const adapters = getAdapters(runtime);
+      const cfg = adapters.getConfig?.() ?? {};
+      const groupOpenid = (event as any).group_openid ?? '';
+      const updatedCfg = groupOpenid ? resolveGroupConfigFromAccount(account, groupOpenid) : null;
+      const requireMention = updatedCfg?.requireMention ?? true;
+      const clawCfg = buildClawCfg(requireMention, [], resolveGroupPolicy(cfg, account.accountId));
+      await acknowledgeInteraction(event.id, 0, { claw_cfg: clawCfg });
+    } catch {
+      try { await acknowledgeInteraction(event.id); } catch { /* ignore */ }
+    }
+    return;
+  }
+
+  await handleApproval(event, account, log, acknowledgeInteraction);
+}
+
+// ── Interaction 子处理 ──
+
+async function handleConfigQuery(
+  event: InteractionEvent,
+  account: ResolvedQQBotAccount,
+  runtime: PluginRuntime,
+  log: PluginLogger,
+  ack: (id: string, code?: number, data?: Record<string, unknown>) => Promise<void>,
+): Promise<void> {
+  const groupOpenid = (event as any).group_openid ?? '';
+  try {
+    const adapters = getAdapters(runtime);
+    const cfg = adapters.getConfig?.() ?? {};
+    const groupCfg = groupOpenid ? resolveGroupConfigFromAccount(account, groupOpenid) : null;
+    const requireMention = groupCfg?.requireMention ?? true;
+    const agentId = groupOpenid
+      ? adapters.resolveAgentRoute?.({ cfg, channel: 'qqbot', accountId: account.accountId, peer: { kind: 'group', id: groupOpenid } })?.agentId
+      : undefined;
+    const mentionPatterns = resolveMentionPatterns(cfg, agentId);
+    const clawCfg = buildClawCfg(requireMention, mentionPatterns, resolveGroupPolicy(cfg, account.accountId));
+    log.info(`interaction query: group=${groupOpenid} requireMention=${requireMention}`);
+    await ack(event.id, 0, { claw_cfg: clawCfg });
+  } catch (err) {
+    log.warn(`interaction query failed: ${(err as Error)?.message ?? err}, ack without data`);
+    try { await ack(event.id); } catch { /* ignore */ }
+  }
+}
+
+async function handleConfigUpdate(
+  event: InteractionEvent,
+  account: ResolvedQQBotAccount,
+  runtime: PluginRuntime,
+  log: PluginLogger,
+): Promise<void> {
+  const resolved = (event.data as any)?.resolved;
+  const update = resolved?.claw_cfg;
+  const groupOpenid = (event as any).group_openid ?? '';
+
+  if (update?.require_mention !== undefined && groupOpenid) {
+    try {
+      await setGroupRequireMention(runtime, account.accountId, groupOpenid, update.require_mention === 'mention');
+      log.info(`interaction: group=${groupOpenid} requireMention=${update.require_mention}`);
+    } catch (err) {
+      log.error(`interaction update failed: ${err}`);
+    }
+  }
+}
+
+async function handleApproval(
+  event: InteractionEvent,
+  account: ResolvedQQBotAccount,
+  log: PluginLogger,
+  ack: (id: string) => Promise<void>,
+): Promise<void> {
+  try { await ack(event.id); } catch { /* ignore */ }
+
+  const buttonData = event.data?.resolved?.button_data;
+  if (!buttonData?.startsWith('approve:')) return;
+
+  // 身份授权校验：操作者需在 allowFrom 白名单中
+  const operatorId = resolveOperatorId(event);
+  if (!isApprovalAuthorized(account, operatorId)) {
+    log.warn(`[approval] unauthorized operator=${operatorId ?? 'unknown'} account=${account.accountId}`);
+    return;
+  }
+
+  const parts = buttonData.split(':');
+  if (parts.length < 3) return;
+
+  const handler = getApprovalHandler(account.accountId);
+  if (!handler) return;
+
+  const approvalId = parts[1];
+  const decision = parts[2] as 'allow-once' | 'allow-always' | 'deny';
+  try { await handler.resolveApproval(approvalId, decision); } catch (err) {
+    log.error(`interaction approve error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}
+
+const CHANNEL_VER = getPackageVersion();
+
+// ── 审批授权校验 ──
+
+/**
+ * 从交互事件中提取操作者身份标识。
+ * QQ Bot 按钮回调事件中，操作者 openid 通常在 `user_openid` 或 `data.resolved.user_id` 字段。
+ */
+function resolveOperatorId(event: InteractionEvent): string | undefined {
+  const evt = event as any;
+  return evt.user_openid
+    ?? evt.data?.resolved?.user_id
+    ?? evt.data?.resolved?.user_openid
+    ?? evt.openid;
+}
+
+/**
+ * 校验操作者是否有权限执行审批操作。
+ * 规则：allowFrom 为空或含 "*" → 开放；否则操作者必须在 allowFrom 中。
+ */
+function isApprovalAuthorized(account: ResolvedQQBotAccount, operatorId?: string): boolean {
+  if (!operatorId) return false;
+  const allowFrom = account.config?.allowFrom ?? [];
+  if (!allowFrom.length || allowFrom.includes('*')) return true;
+  return allowFrom.includes(operatorId);
+}
+
+function buildClawCfg(
+  requireMention: boolean,
+  mentionPatterns: string[],
+  groupPolicy: string,
+): Record<string, unknown> {
+  return {
+    channel_type: 'qqbot',
+    channel_ver: CHANNEL_VER,
+    claw_type: 'openclaw',
+    claw_ver: getOpenClawVersion(),
+    require_mention: requireMention ? 'mention' : 'always',
+    group_policy: groupPolicy,
+    mention_patterns: mentionPatterns.join(','),
+    online_state: 'online',
+  };
+}
+
+// ── Config 写入 ──
+
+function setGroupRequireMention(
+  runtime: PluginRuntime,
+  accountId: string,
+  groupOpenid: string,
+  requireMention: boolean,
+): Promise<void> {
+  const adapters = getAdapters(runtime);
+  return adapters.persistConfig?.((cfg: any) => {
+    const qqbot = (cfg.channels ?? {})?.qqbot ?? {};
+    const groups = accountId !== 'default' && qqbot.accounts?.[accountId]
+      ? (qqbot.accounts[accountId].groups = { ...qqbot.accounts[accountId].groups })
+      : (qqbot.groups = { ...qqbot.groups });
+    groups[groupOpenid] = { ...groups[groupOpenid], requireMention };
+  }) ?? Promise.resolve();
+}

package/src/gateway/index.ts

@@ -0,0 +1,3 @@
+export { QQBotGateway } from './qqbot-gateway.js';
+export type { GatewayCallbacks } from './qqbot-gateway.js';
+export { startAccountWithCredentialRecovery, logoutAndClearCredentials } from './lifecycle.js';