@leoqlin/openclaw-qqbot 1.6.7-alpha1

package/dist/src/inbound-attachments.js

@@ -0,0 +1,248 @@
+/**
+ * 入站附件处理模块
+ *
+ * 负责下载、转换、转录用户发送的附件（图片/语音/文件），
+ * 并归类为统一的 ProcessedAttachments 结构供 gateway 消费。
+ */
+import { downloadFile } from "./image-server.js";
+import { convertSilkToWav, isVoiceAttachment, formatDuration } from "./utils/audio-convert.js";
+import { transcribeAudio, resolveSTTConfig } from "./stt.js";
+import { getQQBotMediaDir } from "./utils/platform.js";
+// ============ 空结果常量 ============
+const EMPTY_RESULT = {
+    attachmentInfo: "",
+    imageUrls: [],
+    imageMediaTypes: [],
+    voiceAttachmentPaths: [],
+    voiceAttachmentUrls: [],
+    voiceAsrReferTexts: [],
+    voiceTranscripts: [],
+    voiceTranscriptSources: [],
+    attachmentLocalPaths: [],
+};
+// ============ 主函数 ============
+/**
+ * 处理入站消息的附件列表。
+ *
+ * 三阶段流水线：
+ * 1. 并行下载所有附件到本地
+ * 2. 并行处理语音转换 + STT 转录
+ * 3. 按原始顺序归类结果
+ */
+export async function processAttachments(attachments, ctx) {
+    if (!attachments?.length)
+        return EMPTY_RESULT;
+    const { appId, peerId, cfg, log } = ctx;
+    const subPaths = ["downloads", appId, ...(peerId ? [peerId] : [])];
+    const downloadDir = getQQBotMediaDir(...subPaths);
+    const prefix = `[qqbot:${appId}]`;
+    // 结果收集
+    const imageUrls = [];
+    const imageMediaTypes = [];
+    const voiceAttachmentPaths = [];
+    const voiceAttachmentUrls = [];
+    const voiceAsrReferTexts = [];
+    const voiceTranscripts = [];
+    const voiceTranscriptSources = [];
+    const attachmentLocalPaths = [];
+    const otherAttachments = [];
+    // 入站附件下载：限制 2 分钟，不限大小
+    const INBOUND_DOWNLOAD_TIMEOUT_MS = 2 * 60 * 1000; // 2 分钟
+    // Phase 1: 并行下载所有附件
+    const downloadTasks = attachments.map(async (att) => {
+        const attUrl = att.url?.startsWith("//") ? `https:${att.url}` : att.url;
+        const isVoice = isVoiceAttachment(att);
+        const wavUrl = isVoice && att.voice_wav_url
+            ? (att.voice_wav_url.startsWith("//") ? `https:${att.voice_wav_url}` : att.voice_wav_url)
+            : "";
+        let localPath = null;
+        let audioPath = null;
+        let dlError;
+        if (isVoice && wavUrl) {
+            const wavResult = await downloadFile(wavUrl, undefined, { destDir: downloadDir, timeoutMs: INBOUND_DOWNLOAD_TIMEOUT_MS });
+            if (wavResult.filePath) {
+                localPath = wavResult.filePath;
+                audioPath = wavResult.filePath;
+                log?.info(`${prefix} Voice attachment: ${att.filename}, downloaded WAV directly (skip SILK→WAV)`);
+            }
+            else {
+                log?.error(`${prefix} Failed to download voice_wav_url (${wavResult.error}), falling back to original URL`);
+            }
+        }
+        if (!localPath) {
+            const dlResult = await downloadFile(attUrl, att.filename, { destDir: downloadDir, timeoutMs: INBOUND_DOWNLOAD_TIMEOUT_MS });
+            localPath = dlResult.filePath;
+            dlError = dlResult.error;
+        }
+        return { att, attUrl, isVoice, localPath, audioPath, dlError };
+    });
+    const downloadResults = await Promise.all(downloadTasks);
+    // Phase 2: 并行处理语音转换 + 转录（非语音附件同步归类）
+    const processTasks = downloadResults.map(async ({ att, attUrl, isVoice, localPath, audioPath, dlError }) => {
+        const asrReferText = typeof att.asr_refer_text === "string" ? att.asr_refer_text.trim() : "";
+        const wavUrl = isVoice && att.voice_wav_url
+            ? (att.voice_wav_url.startsWith("//") ? `https:${att.voice_wav_url}` : att.voice_wav_url)
+            : "";
+        const voiceSourceUrl = wavUrl || attUrl;
+        const meta = {
+            voiceUrl: isVoice && voiceSourceUrl ? voiceSourceUrl : undefined,
+            asrReferText: isVoice && asrReferText ? asrReferText : undefined,
+        };
+        if (localPath) {
+            if (att.content_type?.startsWith("image/")) {
+                log?.info(`${prefix} Downloaded attachment to: ${localPath}`);
+                return { localPath, type: "image", contentType: att.content_type, meta };
+            }
+            else if (isVoice) {
+                log?.info(`${prefix} Downloaded attachment to: ${localPath}`);
+                return processVoiceAttachment(localPath, audioPath, att, asrReferText, cfg, downloadDir, log, prefix);
+            }
+            else {
+                log?.info(`${prefix} Downloaded attachment to: ${localPath}`);
+                return { localPath, type: "other", filename: att.filename, meta };
+            }
+        }
+        else {
+            log?.error(`${prefix} Failed to download: ${attUrl}`);
+            if (att.content_type?.startsWith("image/")) {
+                return { localPath: null, type: "image-fallback", attUrl, contentType: att.content_type, dlError, meta };
+            }
+            else if (isVoice && asrReferText) {
+                log?.info(`${prefix} Voice attachment download failed, using asr_refer_text fallback`);
+                return { localPath: null, type: "voice-fallback", transcript: asrReferText, meta };
+            }
+            else {
+                return { localPath: null, type: "other-fallback", filename: att.filename ?? att.content_type, dlError, meta };
+            }
+        }
+    });
+    const processResults = await Promise.all(processTasks);
+    // Phase 3: 按原始顺序归类结果
+    for (const result of processResults) {
+        if (result.meta.voiceUrl)
+            voiceAttachmentUrls.push(result.meta.voiceUrl);
+        if (result.meta.asrReferText)
+            voiceAsrReferTexts.push(result.meta.asrReferText);
+        if (result.type === "image" && result.localPath) {
+            imageUrls.push(result.localPath);
+            imageMediaTypes.push(result.contentType);
+            attachmentLocalPaths.push(result.localPath);
+        }
+        else if (result.type === "voice" && result.localPath) {
+            voiceAttachmentPaths.push(result.localPath);
+            voiceTranscripts.push(result.transcript);
+            voiceTranscriptSources.push(result.transcriptSource);
+            attachmentLocalPaths.push(result.localPath);
+        }
+        else if (result.type === "other" && result.localPath) {
+            otherAttachments.push(`[附件: ${result.localPath}]`);
+            attachmentLocalPaths.push(result.localPath);
+        }
+        else if (result.type === "image-fallback") {
+            imageUrls.push(result.attUrl);
+            imageMediaTypes.push(result.contentType);
+            attachmentLocalPaths.push(null);
+            // 给模型一个明确的失败提示（和 other-fallback 对齐）
+            const hint = result.dlError?.includes("超时")
+                ? "(图片下载超时)"
+                : "(图片下载失败)";
+            otherAttachments.push(`[图片] ${hint}`);
+        }
+        else if (result.type === "voice-fallback") {
+            voiceTranscripts.push(result.transcript);
+            voiceTranscriptSources.push("asr");
+            attachmentLocalPaths.push(null);
+        }
+        else if (result.type === "other-fallback") {
+            const hint = result.dlError?.includes("超时")
+                ? "(下载超时)"
+                : "(下载失败)";
+            otherAttachments.push(`[附件: ${result.filename}] ${hint}`);
+            attachmentLocalPaths.push(null);
+        }
+    }
+    const attachmentInfo = otherAttachments.length > 0 ? "\n" + otherAttachments.join("\n") : "";
+    return {
+        attachmentInfo,
+        imageUrls,
+        imageMediaTypes,
+        voiceAttachmentPaths,
+        voiceAttachmentUrls,
+        voiceAsrReferTexts,
+        voiceTranscripts,
+        voiceTranscriptSources,
+        attachmentLocalPaths,
+    };
+}
+/**
+ * 将语音转录结果组装为用户消息中的文本片段。
+ */
+export function formatVoiceText(transcripts) {
+    if (transcripts.length === 0)
+        return "";
+    return transcripts.length === 1
+        ? `[语音消息] ${transcripts[0]}`
+        : transcripts.map((t, i) => `[语音${i + 1}] ${t}`).join("\n");
+}
+async function processVoiceAttachment(localPath, audioPath, att, asrReferText, cfg, downloadDir, log, prefix) {
+    const wavUrl = att.voice_wav_url
+        ? (att.voice_wav_url.startsWith("//") ? `https:${att.voice_wav_url}` : att.voice_wav_url)
+        : "";
+    const attUrl = att.url?.startsWith("//") ? `https:${att.url}` : att.url;
+    const voiceSourceUrl = wavUrl || attUrl;
+    const meta = {
+        voiceUrl: voiceSourceUrl || undefined,
+        asrReferText: asrReferText || undefined,
+    };
+    const sttCfg = resolveSTTConfig(cfg);
+    if (!sttCfg) {
+        if (asrReferText) {
+            log?.info(`${prefix} Voice attachment: ${att.filename} (STT not configured, using asr_refer_text fallback)`);
+            return { localPath, type: "voice", transcript: asrReferText, transcriptSource: "asr", meta };
+        }
+        log?.info(`${prefix} Voice attachment: ${att.filename} (STT not configured, skipping transcription)`);
+        return { localPath, type: "voice", transcript: "[语音消息 - 语音识别未配置，无法转录]", transcriptSource: "fallback", meta };
+    }
+    // SILK→WAV 转换
+    if (!audioPath) {
+        log?.info(`${prefix} Voice attachment: ${att.filename}, converting SILK→WAV...`);
+        try {
+            const wavResult = await convertSilkToWav(localPath, downloadDir);
+            if (wavResult) {
+                audioPath = wavResult.wavPath;
+                log?.info(`${prefix} Voice converted: ${wavResult.wavPath} (${formatDuration(wavResult.duration)})`);
+            }
+            else {
+                audioPath = localPath;
+            }
+        }
+        catch (convertErr) {
+            log?.error(`${prefix} Voice conversion failed: ${convertErr}`);
+            if (asrReferText) {
+                return { localPath, type: "voice", transcript: asrReferText, transcriptSource: "asr", meta };
+            }
+            return { localPath, type: "voice", transcript: "[语音消息 - 格式转换失败]", transcriptSource: "fallback", meta };
+        }
+    }
+    // STT 转录
+    try {
+        const transcript = await transcribeAudio(audioPath, cfg);
+        if (transcript) {
+            log?.info(`${prefix} STT transcript: ${transcript.slice(0, 100)}...`);
+            return { localPath, type: "voice", transcript, transcriptSource: "stt", meta };
+        }
+        if (asrReferText) {
+            log?.info(`${prefix} STT returned empty result, using asr_refer_text fallback`);
+            return { localPath, type: "voice", transcript: asrReferText, transcriptSource: "asr", meta };
+        }
+        log?.info(`${prefix} STT returned empty result`);
+        return { localPath, type: "voice", transcript: "[语音消息 - 转录结果为空]", transcriptSource: "fallback", meta };
+    }
+    catch (sttErr) {
+        log?.error(`${prefix} STT failed: ${sttErr}`);
+        if (asrReferText) {
+            return { localPath, type: "voice", transcript: asrReferText, transcriptSource: "asr", meta };
+        }
+        return { localPath, type: "voice", transcript: "[语音消息 - 转录失败]", transcriptSource: "fallback", meta };
+    }
+}

package/dist/src/known-users.d.ts

@@ -0,0 +1,100 @@
+/**
+ * 已知用户存储
+ * 记录与机器人交互过的所有用户
+ * 支持主动消息和批量通知功能
+ */
+export interface KnownUser {
+    /** 用户 openid（唯一标识） */
+    openid: string;
+    /** 消息类型：私聊用户 / 群组 */
+    type: "c2c" | "group";
+    /** 用户昵称（如有） */
+    nickname?: string;
+    /** 群组 openid（如果是群消息） */
+    groupOpenid?: string;
+    /** 关联的机器人账户 ID */
+    accountId: string;
+    /** 首次交互时间戳 */
+    firstSeenAt: number;
+    /** 最后交互时间戳 */
+    lastSeenAt: number;
+    /** 交互次数 */
+    interactionCount: number;
+}
+/**
+ * 强制立即保存（用于进程退出前）
+ */
+export declare function flushKnownUsers(): void;
+/**
+ * 记录已知用户（收到消息时调用）
+ * @param user 用户信息（部分字段）
+ */
+export declare function recordKnownUser(user: {
+    openid: string;
+    type: "c2c" | "group";
+    nickname?: string;
+    groupOpenid?: string;
+    accountId: string;
+}): void;
+/**
+ * 获取单个用户信息
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ * @param type 消息类型
+ * @param groupOpenid 群组 openid（可选）
+ */
+export declare function getKnownUser(accountId: string, openid: string, type?: "c2c" | "group", groupOpenid?: string): KnownUser | undefined;
+/**
+ * 列出所有已知用户
+ * @param options 筛选选项
+ */
+export declare function listKnownUsers(options?: {
+    /** 筛选特定机器人账户的用户 */
+    accountId?: string;
+    /** 筛选消息类型 */
+    type?: "c2c" | "group";
+    /** 最近活跃时间（毫秒，如 86400000 表示最近 24 小时） */
+    activeWithin?: number;
+    /** 返回数量限制 */
+    limit?: number;
+    /** 排序方式 */
+    sortBy?: "lastSeenAt" | "firstSeenAt" | "interactionCount";
+    /** 排序方向 */
+    sortOrder?: "asc" | "desc";
+}): KnownUser[];
+/**
+ * 获取用户统计信息
+ * @param accountId 机器人账户 ID（可选，不传则返回所有账户的统计）
+ */
+export declare function getKnownUsersStats(accountId?: string): {
+    totalUsers: number;
+    c2cUsers: number;
+    groupUsers: number;
+    activeIn24h: number;
+    activeIn7d: number;
+};
+/**
+ * 删除用户记录
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ * @param type 消息类型
+ * @param groupOpenid 群组 openid（可选）
+ */
+export declare function removeKnownUser(accountId: string, openid: string, type?: "c2c" | "group", groupOpenid?: string): boolean;
+/**
+ * 清除所有用户记录
+ * @param accountId 机器人账户 ID（可选，不传则清除所有）
+ */
+export declare function clearKnownUsers(accountId?: string): number;
+/**
+ * 获取用户的所有群组（某用户在哪些群里交互过）
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ */
+export declare function getUserGroups(accountId: string, openid: string): string[];
+/**
+ * 获取群组的所有成员
+ * @param accountId 机器人账户 ID
+ * @param groupOpenid 群组 openid
+ */
+export declare function getGroupMembers(accountId: string, groupOpenid: string): KnownUser[];

package/dist/src/known-users.js

@@ -0,0 +1,263 @@
+/**
+ * 已知用户存储
+ * 记录与机器人交互过的所有用户
+ * 支持主动消息和批量通知功能
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getQQBotDataDir } from "./utils/platform.js";
+// 存储文件路径
+const KNOWN_USERS_DIR = getQQBotDataDir("data");
+const KNOWN_USERS_FILE = path.join(KNOWN_USERS_DIR, "known-users.json");
+// 内存缓存
+let usersCache = null;
+// 写入节流配置
+const SAVE_THROTTLE_MS = 5000; // 5秒写入一次
+let saveTimer = null;
+let isDirty = false;
+/**
+ * 确保目录存在
+ */
+function ensureDir() {
+    if (!fs.existsSync(KNOWN_USERS_DIR)) {
+        fs.mkdirSync(KNOWN_USERS_DIR, { recursive: true });
+    }
+}
+/**
+ * 从文件加载用户数据到缓存
+ */
+function loadUsersFromFile() {
+    if (usersCache !== null) {
+        return usersCache;
+    }
+    usersCache = new Map();
+    try {
+        if (fs.existsSync(KNOWN_USERS_FILE)) {
+            const data = fs.readFileSync(KNOWN_USERS_FILE, "utf-8");
+            const users = JSON.parse(data);
+            for (const user of users) {
+                // 使用复合键：accountId + type + openid（群组还要加 groupOpenid）
+                const key = makeUserKey(user);
+                usersCache.set(key, user);
+            }
+            console.log(`[known-users] Loaded ${usersCache.size} users`);
+        }
+    }
+    catch (err) {
+        console.error(`[known-users] Failed to load users: ${err}`);
+        usersCache = new Map();
+    }
+    return usersCache;
+}
+/**
+ * 保存用户数据到文件（节流版本）
+ */
+function saveUsersToFile() {
+    if (!isDirty)
+        return;
+    if (saveTimer) {
+        return; // 已有定时器在等待
+    }
+    saveTimer = setTimeout(() => {
+        saveTimer = null;
+        doSaveUsersToFile();
+    }, SAVE_THROTTLE_MS);
+}
+/**
+ * 实际执行保存
+ */
+function doSaveUsersToFile() {
+    if (!usersCache || !isDirty)
+        return;
+    try {
+        ensureDir();
+        const users = Array.from(usersCache.values());
+        fs.writeFileSync(KNOWN_USERS_FILE, JSON.stringify(users, null, 2), "utf-8");
+        isDirty = false;
+    }
+    catch (err) {
+        console.error(`[known-users] Failed to save users: ${err}`);
+    }
+}
+/**
+ * 强制立即保存（用于进程退出前）
+ */
+export function flushKnownUsers() {
+    if (saveTimer) {
+        clearTimeout(saveTimer);
+        saveTimer = null;
+    }
+    doSaveUsersToFile();
+}
+/**
+ * 生成用户唯一键
+ */
+function makeUserKey(user) {
+    const base = `${user.accountId}:${user.type}:${user.openid}`;
+    if (user.type === "group" && user.groupOpenid) {
+        return `${base}:${user.groupOpenid}`;
+    }
+    return base;
+}
+/**
+ * 记录已知用户（收到消息时调用）
+ * @param user 用户信息（部分字段）
+ */
+export function recordKnownUser(user) {
+    const cache = loadUsersFromFile();
+    const key = makeUserKey(user);
+    const now = Date.now();
+    const existing = cache.get(key);
+    if (existing) {
+        // 更新已存在的用户
+        existing.lastSeenAt = now;
+        existing.interactionCount++;
+        if (user.nickname && user.nickname !== existing.nickname) {
+            existing.nickname = user.nickname;
+        }
+    }
+    else {
+        // 新用户
+        const newUser = {
+            openid: user.openid,
+            type: user.type,
+            nickname: user.nickname,
+            groupOpenid: user.groupOpenid,
+            accountId: user.accountId,
+            firstSeenAt: now,
+            lastSeenAt: now,
+            interactionCount: 1,
+        };
+        cache.set(key, newUser);
+        console.log(`[known-users] New user: ${user.openid} (${user.type})`);
+    }
+    isDirty = true;
+    saveUsersToFile();
+}
+/**
+ * 获取单个用户信息
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ * @param type 消息类型
+ * @param groupOpenid 群组 openid（可选）
+ */
+export function getKnownUser(accountId, openid, type = "c2c", groupOpenid) {
+    const cache = loadUsersFromFile();
+    const key = makeUserKey({ accountId, openid, type, groupOpenid });
+    return cache.get(key);
+}
+/**
+ * 列出所有已知用户
+ * @param options 筛选选项
+ */
+export function listKnownUsers(options) {
+    const cache = loadUsersFromFile();
+    let users = Array.from(cache.values());
+    // 筛选
+    if (options?.accountId) {
+        users = users.filter(u => u.accountId === options.accountId);
+    }
+    if (options?.type) {
+        users = users.filter(u => u.type === options.type);
+    }
+    if (options?.activeWithin) {
+        const cutoff = Date.now() - options.activeWithin;
+        users = users.filter(u => u.lastSeenAt >= cutoff);
+    }
+    // 排序
+    const sortBy = options?.sortBy ?? "lastSeenAt";
+    const sortOrder = options?.sortOrder ?? "desc";
+    users.sort((a, b) => {
+        const aVal = a[sortBy] ?? 0;
+        const bVal = b[sortBy] ?? 0;
+        return sortOrder === "asc" ? aVal - bVal : bVal - aVal;
+    });
+    // 限制数量
+    if (options?.limit && options.limit > 0) {
+        users = users.slice(0, options.limit);
+    }
+    return users;
+}
+/**
+ * 获取用户统计信息
+ * @param accountId 机器人账户 ID（可选，不传则返回所有账户的统计）
+ */
+export function getKnownUsersStats(accountId) {
+    let users = listKnownUsers({ accountId });
+    const now = Date.now();
+    const day = 24 * 60 * 60 * 1000;
+    return {
+        totalUsers: users.length,
+        c2cUsers: users.filter(u => u.type === "c2c").length,
+        groupUsers: users.filter(u => u.type === "group").length,
+        activeIn24h: users.filter(u => now - u.lastSeenAt < day).length,
+        activeIn7d: users.filter(u => now - u.lastSeenAt < 7 * day).length,
+    };
+}
+/**
+ * 删除用户记录
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ * @param type 消息类型
+ * @param groupOpenid 群组 openid（可选）
+ */
+export function removeKnownUser(accountId, openid, type = "c2c", groupOpenid) {
+    const cache = loadUsersFromFile();
+    const key = makeUserKey({ accountId, openid, type, groupOpenid });
+    if (cache.has(key)) {
+        cache.delete(key);
+        isDirty = true;
+        saveUsersToFile();
+        console.log(`[known-users] Removed user ${openid}`);
+        return true;
+    }
+    return false;
+}
+/**
+ * 清除所有用户记录
+ * @param accountId 机器人账户 ID（可选，不传则清除所有）
+ */
+export function clearKnownUsers(accountId) {
+    const cache = loadUsersFromFile();
+    let count = 0;
+    if (accountId) {
+        // 只清除指定账户的用户
+        for (const [key, user] of cache.entries()) {
+            if (user.accountId === accountId) {
+                cache.delete(key);
+                count++;
+            }
+        }
+    }
+    else {
+        // 清除所有
+        count = cache.size;
+        cache.clear();
+    }
+    if (count > 0) {
+        isDirty = true;
+        doSaveUsersToFile(); // 立即保存
+        console.log(`[known-users] Cleared ${count} users`);
+    }
+    return count;
+}
+/**
+ * 获取用户的所有群组（某用户在哪些群里交互过）
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ */
+export function getUserGroups(accountId, openid) {
+    const users = listKnownUsers({ accountId, type: "group" });
+    return users
+        .filter(u => u.openid === openid && u.groupOpenid)
+        .map(u => u.groupOpenid);
+}
+/**
+ * 获取群组的所有成员
+ * @param accountId 机器人账户 ID
+ * @param groupOpenid 群组 openid
+ */
+export function getGroupMembers(accountId, groupOpenid) {
+    return listKnownUsers({ accountId, type: "group" })
+        .filter(u => u.groupOpenid === groupOpenid);
+}

package/dist/src/message-gating.d.ts

@@ -0,0 +1,53 @@
+/**
+ * 群消息门控 — 统一入口。
+ *
+ * 将 ignoreOtherMentions / shouldBlock / mentionGating 三层判断收敛到
+ * 一个纯函数 resolveGroupMessageGate() 中，让 gateway 主流程只关心一个结果。
+ *
+ * 按优先级串行检查：
+ *   1. ignoreOtherMentions — @了其他人但未 @bot → 丢弃（记历史）
+ *   2. shouldBlock         — 未授权控制命令静默拦截
+ *   3. mentionGating       — requireMention 门控 + 命令旁路
+ */
+export type MentionGateResult = {
+    effectiveWasMentioned: boolean;
+    shouldSkip: boolean;
+};
+export type MentionGateWithBypassResult = MentionGateResult & {
+    shouldBypassMention: boolean;
+};
+export type GroupMessageGateAction = 
+/** @了其他人但未 @bot，丢弃并记录历史 */
+"drop_other_mention"
+/** 未授权控制命令，静默拦截 */
+ | "block_unauthorized_command"
+/** 非 @bot 消息，记录历史后跳过 AI */
+ | "skip_no_mention"
+/** 正常放行，交给 AI */
+ | "pass";
+export type GroupMessageGateResult = {
+    action: GroupMessageGateAction;
+    /** 仅 action=pass|skip_no_mention 时有值 */
+    effectiveWasMentioned: boolean;
+    shouldBypassMention: boolean;
+};
+export type GroupMessageGateParams = {
+    ignoreOtherMentions: boolean;
+    hasAnyMention: boolean;
+    wasMentioned: boolean;
+    implicitMention: boolean;
+    allowTextCommands: boolean;
+    isControlCommand: boolean;
+    commandAuthorized: boolean;
+    requireMention: boolean;
+    canDetectMention: boolean;
+};
+/**
+ * 群消息统一门控，按优先级串行判定：
+ *
+ *   1. ignoreOtherMentions — @了其他人但未 @bot → drop_other_mention
+ *   2. shouldBlock         — 未授权控制命令      → block_unauthorized_command
+ *   3. mentionGating       — 未满足 @bot 条件    → skip_no_mention
+ *   4. 通过所有检查                              → pass
+ */
+export declare function resolveGroupMessageGate(params: GroupMessageGateParams): GroupMessageGateResult;