@leoqlin/openclaw-qqbot 1.6.7-alpha1

package/dist/src/config.js

@@ -0,0 +1,278 @@
+/**
+ * 解析 mentionPatterns（agent → global → 空数组）
+ *
+ * 优先级：
+ *   1. agents.list[agentId].groupChat.mentionPatterns
+ *   2. messages.groupChat.mentionPatterns
+ *   3. []
+ */
+export function resolveMentionPatterns(cfg, agentId) {
+    // 1. agent 级别
+    if (agentId) {
+        const agents = cfg.agents;
+        const entry = agents?.list?.find((a) => a.id?.trim().toLowerCase() === agentId.trim().toLowerCase());
+        const agentGroupChat = entry?.groupChat;
+        if (agentGroupChat && Object.hasOwn(agentGroupChat, "mentionPatterns")) {
+            return agentGroupChat.mentionPatterns ?? [];
+        }
+    }
+    // 2. 全局级别
+    const globalGroupChat = cfg?.messages?.groupChat;
+    if (globalGroupChat && typeof globalGroupChat === "object" && Object.hasOwn(globalGroupChat, "mentionPatterns")) {
+        return globalGroupChat.mentionPatterns ?? [];
+    }
+    // 3. 空数组
+    return [];
+}
+export const DEFAULT_ACCOUNT_ID = "default";
+function evaluateMatchedGroupAccessForPolicy(params) {
+    if (params.groupPolicy === "disabled") {
+        return { allowed: false, groupPolicy: params.groupPolicy, reason: "disabled" };
+    }
+    if (params.groupPolicy === "allowlist") {
+        if (params.requireMatchInput && !params.hasMatchInput) {
+            return { allowed: false, groupPolicy: params.groupPolicy, reason: "missing_match_input" };
+        }
+        if (!params.allowlistConfigured) {
+            return { allowed: false, groupPolicy: params.groupPolicy, reason: "empty_allowlist" };
+        }
+        if (!params.allowlistMatched) {
+            return { allowed: false, groupPolicy: params.groupPolicy, reason: "not_allowlisted" };
+        }
+    }
+    return { allowed: true, groupPolicy: params.groupPolicy, reason: "allowed" };
+}
+// ============ 群消息策略 ============
+const DEFAULT_GROUP_POLICY = "open";
+/** 群历史缓存条数默认值 */
+const DEFAULT_GROUP_HISTORY_LIMIT = 50;
+const DEFAULT_GROUP_CONFIG = {
+    requireMention: true,
+    ignoreOtherMentions: false,
+    toolPolicy: "restricted",
+    name: "",
+    historyLimit: DEFAULT_GROUP_HISTORY_LIMIT,
+};
+/** 默认群消息行为 PE（可通过配置覆盖） */
+const DEFAULT_GROUP_PROMPT = [
+    "若发送者为机器人，仅在对方明确@你提问或请求协助具体任务时，以简洁明了的内容回复，",
+    "避免与其他机器人产生抢答或多轮无意义对话。",
+    "在群聊中优先让人类用户的消息得到响应，机器人之间保持协作而非竞争，确保对话有序不刷屏。",
+].join("");
+/** 解析群消息策略 */
+export function resolveGroupPolicy(cfg, accountId) {
+    const account = resolveQQBotAccount(cfg, accountId);
+    return account.config?.groupPolicy ?? DEFAULT_GROUP_POLICY;
+}
+/** 解析群白名单（统一转大写） */
+export function resolveGroupAllowFrom(cfg, accountId) {
+    const account = resolveQQBotAccount(cfg, accountId);
+    return (account.config?.groupAllowFrom ?? []).map((id) => String(id).trim().toUpperCase());
+}
+/** 检查指定群是否被允许（使用标准策略引擎） */
+export function isGroupAllowed(cfg, groupOpenid, accountId) {
+    const policy = resolveGroupPolicy(cfg, accountId);
+    const allowList = resolveGroupAllowFrom(cfg, accountId);
+    const allowlistConfigured = allowList.length > 0;
+    const allowlistMatched = allowList.some((id) => id === "*" || id === groupOpenid.toUpperCase());
+    return evaluateMatchedGroupAccessForPolicy({
+        groupPolicy: policy,
+        allowlistConfigured,
+        allowlistMatched,
+    }).allowed;
+}
+/** 解析指定群配置（具体 groupOpenid > 通配符 "*" > 默认值） */
+export function resolveGroupConfig(cfg, groupOpenid, accountId) {
+    const account = resolveQQBotAccount(cfg, accountId);
+    const groups = account.config?.groups ?? {};
+    const wildcardCfg = groups["*"] ?? {};
+    const specificCfg = groups[groupOpenid] ?? {};
+    return {
+        requireMention: specificCfg.requireMention ?? wildcardCfg.requireMention ?? DEFAULT_GROUP_CONFIG.requireMention,
+        ignoreOtherMentions: specificCfg.ignoreOtherMentions ?? wildcardCfg.ignoreOtherMentions ?? DEFAULT_GROUP_CONFIG.ignoreOtherMentions,
+        toolPolicy: specificCfg.toolPolicy ?? wildcardCfg.toolPolicy ?? DEFAULT_GROUP_CONFIG.toolPolicy,
+        name: specificCfg.name ?? wildcardCfg.name ?? DEFAULT_GROUP_CONFIG.name,
+        prompt: specificCfg.prompt ?? wildcardCfg.prompt,
+        historyLimit: specificCfg.historyLimit ?? wildcardCfg.historyLimit ?? DEFAULT_GROUP_CONFIG.historyLimit,
+    };
+}
+/** 解析群历史消息缓存条数 */
+export function resolveHistoryLimit(cfg, groupOpenid, accountId) {
+    return Math.max(0, resolveGroupConfig(cfg, groupOpenid, accountId).historyLimit);
+}
+/** 解析群行为 PE（具体群 > "*" > 默认值） */
+export function resolveGroupPrompt(cfg, groupOpenid, accountId) {
+    const account = resolveQQBotAccount(cfg, accountId);
+    const groups = account.config?.groups ?? {};
+    return groups[groupOpenid]?.prompt ?? groups["*"]?.prompt ?? DEFAULT_GROUP_PROMPT;
+}
+/** 解析群是否需要 @机器人才响应 */
+export function resolveRequireMention(cfg, groupOpenid, accountId) {
+    return resolveGroupConfig(cfg, groupOpenid, accountId).requireMention;
+}
+/** 解析群是否忽略 @了其他人（非 bot）的消息 */
+export function resolveIgnoreOtherMentions(cfg, groupOpenid, accountId) {
+    return resolveGroupConfig(cfg, groupOpenid, accountId).ignoreOtherMentions;
+}
+/** 解析群工具策略 */
+export function resolveToolPolicy(cfg, groupOpenid, accountId) {
+    return resolveGroupConfig(cfg, groupOpenid, accountId).toolPolicy;
+}
+/** 解析群名称（优先配置，fallback 为 openid 前 8 位） */
+export function resolveGroupName(cfg, groupOpenid, accountId) {
+    const name = resolveGroupConfig(cfg, groupOpenid, accountId).name;
+    return name || groupOpenid.slice(0, 8);
+}
+function normalizeAppId(raw) {
+    if (raw === null || raw === undefined)
+        return "";
+    return String(raw).trim();
+}
+/**
+ * 列出所有 QQBot 账户 ID
+ */
+export function listQQBotAccountIds(cfg) {
+    const ids = new Set();
+    const qqbot = cfg.channels?.qqbot;
+    if (qqbot?.appId) {
+        ids.add(DEFAULT_ACCOUNT_ID);
+    }
+    if (qqbot?.accounts) {
+        for (const accountId of Object.keys(qqbot.accounts)) {
+            if (qqbot.accounts[accountId]?.appId) {
+                ids.add(accountId);
+            }
+        }
+    }
+    return Array.from(ids);
+}
+/**
+ * 获取默认账户 ID
+ */
+export function resolveDefaultQQBotAccountId(cfg) {
+    const qqbot = cfg.channels?.qqbot;
+    // 如果有默认账户配置，返回 default
+    if (qqbot?.appId) {
+        return DEFAULT_ACCOUNT_ID;
+    }
+    // 否则返回第一个配置的账户
+    if (qqbot?.accounts) {
+        const ids = Object.keys(qqbot.accounts);
+        if (ids.length > 0) {
+            return ids[0];
+        }
+    }
+    return DEFAULT_ACCOUNT_ID;
+}
+/**
+ * 解析 QQBot 账户配置
+ */
+export function resolveQQBotAccount(cfg, accountId) {
+    const resolvedAccountId = accountId ?? resolveDefaultQQBotAccountId(cfg);
+    const qqbot = cfg.channels?.qqbot;
+    // 基础配置
+    let accountConfig = {};
+    let appId = "";
+    let clientSecret = "";
+    let secretSource = "none";
+    if (resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+        // 默认账户从顶层读取（展开所有字段，避免遗漏新增配置项）
+        const { accounts: _accounts, ...topLevelConfig } = qqbot ?? {};
+        accountConfig = {
+            ...topLevelConfig,
+            markdownSupport: qqbot?.markdownSupport ?? true,
+        };
+        appId = normalizeAppId(qqbot?.appId);
+    }
+    else {
+        // 命名账户从 accounts 读取
+        const account = qqbot?.accounts?.[resolvedAccountId];
+        accountConfig = account ?? {};
+        appId = normalizeAppId(account?.appId);
+    }
+    // 解析 clientSecret
+    if (accountConfig.clientSecret) {
+        clientSecret = accountConfig.clientSecret;
+        secretSource = "config";
+    }
+    else if (accountConfig.clientSecretFile) {
+        // 从文件读取（运行时处理）
+        secretSource = "file";
+    }
+    else if (process.env.QQBOT_CLIENT_SECRET && resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+        clientSecret = process.env.QQBOT_CLIENT_SECRET;
+        secretSource = "env";
+    }
+    // AppId 也可以从环境变量读取
+    if (!appId && process.env.QQBOT_APP_ID && resolvedAccountId === DEFAULT_ACCOUNT_ID) {
+        appId = normalizeAppId(process.env.QQBOT_APP_ID);
+    }
+    return {
+        accountId: resolvedAccountId,
+        name: accountConfig.name,
+        enabled: accountConfig.enabled !== false,
+        appId,
+        clientSecret,
+        secretSource,
+        systemPrompt: accountConfig.systemPrompt,
+        imageServerBaseUrl: accountConfig.imageServerBaseUrl || process.env.QQBOT_IMAGE_SERVER_BASE_URL,
+        markdownSupport: accountConfig.markdownSupport !== false,
+        config: accountConfig,
+    };
+}
+/**
+ * 应用账户配置
+ */
+export function applyQQBotAccountConfig(cfg, accountId, input) {
+    const next = { ...cfg };
+    if (accountId === DEFAULT_ACCOUNT_ID) {
+        // 如果没有设置过 allowFrom，默认设置为 ["*"]
+        const existingConfig = next.channels?.qqbot || {};
+        const allowFrom = existingConfig.allowFrom ?? ["*"];
+        next.channels = {
+            ...next.channels,
+            qqbot: {
+                ...(next.channels?.qqbot || {}),
+                enabled: true,
+                allowFrom,
+                ...(input.appId ? { appId: input.appId } : {}),
+                ...(input.clientSecret
+                    ? { clientSecret: input.clientSecret }
+                    : input.clientSecretFile
+                        ? { clientSecretFile: input.clientSecretFile }
+                        : {}),
+                ...(input.name ? { name: input.name } : {}),
+                ...(input.imageServerBaseUrl ? { imageServerBaseUrl: input.imageServerBaseUrl } : {}),
+            },
+        };
+    }
+    else {
+        // 如果没有设置过 allowFrom，默认设置为 ["*"]
+        const existingAccountConfig = next.channels?.qqbot?.accounts?.[accountId] || {};
+        const allowFrom = existingAccountConfig.allowFrom ?? ["*"];
+        next.channels = {
+            ...next.channels,
+            qqbot: {
+                ...(next.channels?.qqbot || {}),
+                enabled: true,
+                accounts: {
+                    ...(next.channels?.qqbot?.accounts || {}),
+                    [accountId]: {
+                        ...(next.channels?.qqbot?.accounts?.[accountId] || {}),
+                        enabled: true,
+                        allowFrom,
+                        ...(input.appId ? { appId: input.appId } : {}),
+                        ...(input.clientSecret
+                            ? { clientSecret: input.clientSecret }
+                            : input.clientSecretFile
+                                ? { clientSecretFile: input.clientSecretFile }
+                                : {}),
+                        ...(input.name ? { name: input.name } : {}),
+                        ...(input.imageServerBaseUrl ? { imageServerBaseUrl: input.imageServerBaseUrl } : {}),
+                    },
+                },
+            },
+        };
+    }
+    return next;
+}

package/dist/src/credential-backup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 凭证暂存与恢复
+ *
+ * 解决热更新被打断时 openclaw.json 中 appId/secret 丢失的问题。
+ *
+ * 原理：
+ *   - 每次 gateway 成功启动后，把当前账户的 appId/secret 写入暂存文件
+ *   - 插件启动时如果检测到配置中 appId/secret 为空，尝试从暂存文件恢复
+ *   - 暂存文件存储在 ~/.openclaw/qqbot/data/ 下，不受插件目录替换影响
+ *
+ * 安全保障：
+ *   - 只在 appId/secret **确实为空** 时才尝试恢复（不干扰正常配置变更）
+ *   - 恢复后通过 openclaw 的 config API 写回配置文件，确保框架感知到变更
+ *   - 暂存文件使用原子写入（先写 .tmp 再 rename）防止损坏
+ */
+interface CredentialBackup {
+    accountId: string;
+    appId: string;
+    clientSecret: string;
+    savedAt: string;
+}
+/**
+ * 保存凭证快照到暂存文件（gateway 成功启动后调用）
+ */
+export declare function saveCredentialBackup(accountId: string, appId: string, clientSecret: string): void;
+/**
+ * 从暂存文件读取凭证（仅在配置为空时调用）
+ * 返回 null 表示无可用备份
+ */
+export declare function loadCredentialBackup(accountId?: string): CredentialBackup | null;
+export {};

package/dist/src/credential-backup.js

@@ -0,0 +1,66 @@
+/**
+ * 凭证暂存与恢复
+ *
+ * 解决热更新被打断时 openclaw.json 中 appId/secret 丢失的问题。
+ *
+ * 原理：
+ *   - 每次 gateway 成功启动后，把当前账户的 appId/secret 写入暂存文件
+ *   - 插件启动时如果检测到配置中 appId/secret 为空，尝试从暂存文件恢复
+ *   - 暂存文件存储在 ~/.openclaw/qqbot/data/ 下，不受插件目录替换影响
+ *
+ * 安全保障：
+ *   - 只在 appId/secret **确实为空** 时才尝试恢复（不干扰正常配置变更）
+ *   - 恢复后通过 openclaw 的 config API 写回配置文件，确保框架感知到变更
+ *   - 暂存文件使用原子写入（先写 .tmp 再 rename）防止损坏
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getQQBotDataDir } from "./utils/platform.js";
+const BACKUP_FILENAME = "credential-backup.json";
+function getBackupPath() {
+    return path.join(getQQBotDataDir("data"), BACKUP_FILENAME);
+}
+/**
+ * 保存凭证快照到暂存文件（gateway 成功启动后调用）
+ */
+export function saveCredentialBackup(accountId, appId, clientSecret) {
+    if (!appId || !clientSecret)
+        return; // 不保存空凭证
+    try {
+        const backupPath = getBackupPath();
+        const data = {
+            accountId,
+            appId,
+            clientSecret,
+            savedAt: new Date().toISOString(),
+        };
+        const tmpPath = backupPath + ".tmp";
+        fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+        fs.renameSync(tmpPath, backupPath);
+    }
+    catch {
+        // 非关键操作，静默忽略
+    }
+}
+/**
+ * 从暂存文件读取凭证（仅在配置为空时调用）
+ * 返回 null 表示无可用备份
+ */
+export function loadCredentialBackup(accountId) {
+    try {
+        const backupPath = getBackupPath();
+        if (!fs.existsSync(backupPath))
+            return null;
+        const raw = fs.readFileSync(backupPath, "utf8");
+        const data = JSON.parse(raw);
+        if (!data.appId || !data.clientSecret)
+            return null;
+        // 如果指定了 accountId，校验是否匹配
+        if (accountId && data.accountId !== accountId)
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/deliver-debounce.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 出站消息合并回复（Deliver Debounce）模块
+ *
+ * 解决的问题：
+ * 当 openclaw 框架层的 embedded agent 超时或快速连续产生多次 deliver 时，
+ * 用户会在短时间内收到大量碎片消息（消息轰炸）。
+ *
+ * 解决方案：
+ * 在 deliver 回调和实际发送之间加入 debounce 层。
+ * 短时间内（windowMs）连续到达的多条纯文本 deliver 会被合并为一条消息发送。
+ * 含媒体的 deliver 会立即 flush 已缓冲的文本并正常处理媒体。
+ */
+import type { DeliverDebounceConfig } from "./types.js";
+export interface DeliverPayload {
+    text?: string;
+    mediaUrls?: string[];
+    mediaUrl?: string;
+}
+export interface DeliverInfo {
+    kind: string;
+}
+/** 实际执行发送的回调 */
+export type DeliverExecutor = (payload: DeliverPayload, info: DeliverInfo) => Promise<void>;
+export declare class DeliverDebouncer {
+    private readonly windowMs;
+    private readonly maxWaitMs;
+    private readonly separator;
+    private readonly executor;
+    private readonly log?;
+    private readonly prefix;
+    /** 缓冲中的文本片段 */
+    private bufferedTexts;
+    /** 缓冲中最后一次 deliver 的 info（用于 flush 时传递 kind） */
+    private lastInfo;
+    /** 缓冲中最后一次 deliver 的 payload（非文本字段，如 mediaUrls） */
+    private lastPayload;
+    /** debounce 定时器 */
+    private debounceTimer;
+    /** 最大等待定时器（从第一条 deliver 开始计算） */
+    private maxWaitTimer;
+    /** 是否正在 flush */
+    private flushing;
+    /** 已销毁标记 */
+    private disposed;
+    constructor(config: DeliverDebounceConfig | undefined, executor: DeliverExecutor, log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+    }, prefix?: string);
+    /**
+     * 接收一次 deliver 调用。
+     * - 纯文本 deliver → 缓冲并设置 debounce 定时器
+     * - 含媒体 deliver → 先 flush 已缓冲文本，再直接执行当前 deliver
+     */
+    deliver(payload: DeliverPayload, info: DeliverInfo): Promise<void>;
+    /**
+     * 将缓冲中的文本合并为一条消息发送
+     */
+    flush(): Promise<void>;
+    /**
+     * 销毁：flush 剩余缓冲并清除定时器
+     */
+    dispose(): Promise<void>;
+    /** 当前是否有缓冲中的文本 */
+    get hasPending(): boolean;
+    /** 缓冲中的文本数量 */
+    get pendingCount(): number;
+}
+/**
+ * 根据配置创建 debouncer 或返回 null（禁用时）
+ */
+export declare function createDeliverDebouncer(config: DeliverDebounceConfig | undefined, executor: DeliverExecutor, log?: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+}, prefix?: string): DeliverDebouncer | null;

package/dist/src/deliver-debounce.js

@@ -0,0 +1,174 @@
+/**
+ * 出站消息合并回复（Deliver Debounce）模块
+ *
+ * 解决的问题：
+ * 当 openclaw 框架层的 embedded agent 超时或快速连续产生多次 deliver 时，
+ * 用户会在短时间内收到大量碎片消息（消息轰炸）。
+ *
+ * 解决方案：
+ * 在 deliver 回调和实际发送之间加入 debounce 层。
+ * 短时间内（windowMs）连续到达的多条纯文本 deliver 会被合并为一条消息发送。
+ * 含媒体的 deliver 会立即 flush 已缓冲的文本并正常处理媒体。
+ */
+// ============ 默认值 ============
+const DEFAULT_WINDOW_MS = 1500;
+const DEFAULT_MAX_WAIT_MS = 8000;
+const DEFAULT_SEPARATOR = "\n\n---\n\n";
+// ============ DeliverDebouncer 类 ============
+export class DeliverDebouncer {
+    windowMs;
+    maxWaitMs;
+    separator;
+    executor;
+    log;
+    prefix;
+    /** 缓冲中的文本片段 */
+    bufferedTexts = [];
+    /** 缓冲中最后一次 deliver 的 info（用于 flush 时传递 kind） */
+    lastInfo = null;
+    /** 缓冲中最后一次 deliver 的 payload（非文本字段，如 mediaUrls） */
+    lastPayload = null;
+    /** debounce 定时器 */
+    debounceTimer = null;
+    /** 最大等待定时器（从第一条 deliver 开始计算） */
+    maxWaitTimer = null;
+    /** 是否正在 flush */
+    flushing = false;
+    /** 已销毁标记 */
+    disposed = false;
+    constructor(config, executor, log, prefix = "[debounce]") {
+        this.windowMs = config?.windowMs ?? DEFAULT_WINDOW_MS;
+        this.maxWaitMs = config?.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+        this.separator = config?.separator ?? DEFAULT_SEPARATOR;
+        this.executor = executor;
+        this.log = log;
+        this.prefix = prefix;
+    }
+    /**
+     * 接收一次 deliver 调用。
+     * - 纯文本 deliver → 缓冲并设置 debounce 定时器
+     * - 含媒体 deliver → 先 flush 已缓冲文本，再直接执行当前 deliver
+     */
+    async deliver(payload, info) {
+        if (this.disposed)
+            return;
+        const hasMedia = Boolean((payload.mediaUrls && payload.mediaUrls.length > 0) || payload.mediaUrl);
+        const text = (payload.text ?? "").trim();
+        // 含媒体的 deliver：立即 flush 缓冲 + 直接执行
+        if (hasMedia) {
+            this.log?.info(`${this.prefix} Media deliver detected, flushing ${this.bufferedTexts.length} buffered text(s) first`);
+            await this.flush();
+            await this.executor(payload, info);
+            return;
+        }
+        // 空文本 deliver：直接透传（不缓冲）
+        if (!text) {
+            await this.executor(payload, info);
+            return;
+        }
+        // 纯文本 deliver：缓冲
+        this.bufferedTexts.push(text);
+        this.lastInfo = info;
+        this.lastPayload = payload;
+        this.log?.info(`${this.prefix} Buffered text #${this.bufferedTexts.length} (${text.length} chars), window=${this.windowMs}ms`);
+        // 重置 debounce 定时器
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.flush().catch((err) => {
+                this.log?.error(`${this.prefix} Flush error (debounce timer): ${err}`);
+            });
+        }, this.windowMs);
+        // 首次缓冲时启动最大等待定时器
+        if (this.bufferedTexts.length === 1) {
+            if (this.maxWaitTimer) {
+                clearTimeout(this.maxWaitTimer);
+            }
+            this.maxWaitTimer = setTimeout(() => {
+                this.log?.info(`${this.prefix} Max wait (${this.maxWaitMs}ms) reached, force flushing`);
+                this.flush().catch((err) => {
+                    this.log?.error(`${this.prefix} Flush error (max wait timer): ${err}`);
+                });
+            }, this.maxWaitMs);
+        }
+    }
+    /**
+     * 将缓冲中的文本合并为一条消息发送
+     */
+    async flush() {
+        if (this.flushing || this.bufferedTexts.length === 0)
+            return;
+        this.flushing = true;
+        // 清除定时器
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.maxWaitTimer) {
+            clearTimeout(this.maxWaitTimer);
+            this.maxWaitTimer = null;
+        }
+        // 取出缓冲
+        const texts = this.bufferedTexts;
+        const info = this.lastInfo;
+        const lastPayload = this.lastPayload;
+        this.bufferedTexts = [];
+        this.lastInfo = null;
+        this.lastPayload = null;
+        try {
+            if (texts.length === 1) {
+                // 只有一条，直接透传原始 payload
+                this.log?.info(`${this.prefix} Flushing single buffered text (${texts[0].length} chars)`);
+                await this.executor({ ...lastPayload, text: texts[0] }, info);
+            }
+            else {
+                // 多条合并
+                const merged = texts.join(this.separator);
+                this.log?.info(`${this.prefix} Merged ${texts.length} buffered texts into one (${merged.length} chars)`);
+                await this.executor({ ...lastPayload, text: merged }, info);
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /**
+     * 销毁：flush 剩余缓冲并清除定时器
+     */
+    async dispose() {
+        this.disposed = true;
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.maxWaitTimer) {
+            clearTimeout(this.maxWaitTimer);
+            this.maxWaitTimer = null;
+        }
+        // flush 剩余
+        if (this.bufferedTexts.length > 0) {
+            this.flushing = false; // 确保 flush 能执行
+            await this.flush();
+        }
+    }
+    /** 当前是否有缓冲中的文本 */
+    get hasPending() {
+        return this.bufferedTexts.length > 0;
+    }
+    /** 缓冲中的文本数量 */
+    get pendingCount() {
+        return this.bufferedTexts.length;
+    }
+}
+// ============ 工厂函数 ============
+/**
+ * 根据配置创建 debouncer 或返回 null（禁用时）
+ */
+export function createDeliverDebouncer(config, executor, log, prefix) {
+    // 未配置时默认启用
+    if (config?.enabled === false) {
+        return null;
+    }
+    return new DeliverDebouncer(config, executor, log, prefix);
+}

package/dist/src/gateway.d.ts

@@ -0,0 +1,18 @@
+import type { ResolvedQQBotAccount } from "./types.js";
+export interface GatewayContext {
+    account: ResolvedQQBotAccount;
+    abortSignal: AbortSignal;
+    cfg: unknown;
+    onReady?: (data: unknown) => void;
+    onError?: (error: Error) => void;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+/**
+ * 启动 Gateway WebSocket 连接（带自动重连）
+ * 支持流式消息发送
+ */
+export declare function startGateway(ctx: GatewayContext): Promise<void>;