@tencent-connect/openclaw-qqbot 1.6.6-alpha.1 → 1.6.6-alpha.4

package/README.md

@@ -10,7 +10,7 @@
 
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
-### 🚀 Current Version: `v1.6.6`
+### 🚀 Current Version: `v1.6.5`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -46,7 +46,6 @@ Scan to join the QQ group chat
 | 📝 **Markdown** | Full Markdown formatting support |
 | 🛠️ **Commands** | Native OpenClaw command integration |
 | 💬 **Quoted Context** | Resolve QQ `REFIDX_*` quoted messages and inject quote body into AI context |
-| 📦 **Large File Support** | Auto chunked upload for large files (parallel upload with retry), up to 100 MB |
 
 ---
 
@@ -130,7 +129,7 @@ This capability depends on OpenClaw cron scheduling and proactive messaging. If
 >
 > **QQBot**: *(sends a .txt file)*
 
-AI can send files directly. Any format, up to 100MB. Large files are automatically chunked and uploaded in parallel.
+AI can send files directly. Any format, up to 20MB.
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="File Sending Demo" />
 

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.6`
+### 🚀 当前版本： `v1.6.5`
 
 [![License](https://img.shields.io/badge/license-MIT-green)](./LICENSE)
 [![QQ Bot](https://img.shields.io/badge/QQ_Bot-API_v2-red)](https://bot.q.qq.com/wiki/)
@@ -41,7 +41,6 @@
 | 📝 **Markdown** | 完整支持 Markdown 格式消息 |
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
 | 💬 **引用上下文** | 解析 QQ `REFIDX_*` 引用消息，并将引用内容注入 AI 上下文 |
-| 📦 **大文件支持** | 大文件自动分片并行上传，最大支持 100 MB |
 
 ---
 
@@ -125,7 +124,7 @@ AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg
 >
 > **QQBot**：*（发送 .txt 文件）*
 
-AI 可直接发送文件。任意格式，最大 100MB。大文件自动分片并行上传。
+AI 可直接发送文件。任意格式，最大 20MB。
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="发文件演示" />
 

package/dist/src/api.d.ts

@@ -2,11 +2,19 @@
  * QQ Bot API 鉴权和请求封装
  * [修复版] 已重构为支持多实例并发，消除全局变量冲突
  */
-/** API 请求错误，携带 HTTP status code */
+/** API 请求错误，携带 HTTP status code 和业务错误码 */
 export declare class ApiError extends Error {
     readonly status: number;
     readonly path: string;
-    constructor(message: string, status: number, path: string);
+    /** 业务错误码（回包中的 code / err_code 字段），不一定存在 */
+    readonly bizCode?: number | undefined;
+    /** 回包中的原始 message 字段（用于向用户展示兜底文案） */
+    readonly bizMessage?: string | undefined;
+    constructor(message: string, status: number, path: string, 
+    /** 业务错误码（回包中的 code / err_code 字段），不一定存在 */
+    bizCode?: number | undefined, 
+    /** 回包中的原始 message 字段（用于向用户展示兜底文案） */
+    bizMessage?: string | undefined);
 }
 export declare const PLUGIN_USER_AGENT: string;
 /** 出站消息元信息（结构化存储，不做预格式化） */
@@ -69,7 +77,22 @@ export declare function getNextMsgSeq(_msgId: string): number;
  * API 请求封装
  */
 export declare function apiRequest<T = unknown>(accessToken: string, method: string, path: string, body?: unknown, timeoutMs?: number): Promise<T>;
+/**
+ * 需要持续重试的业务错误码集合
+ * 当 upload_part_finish 返回这些错误码时，会以固定 1s 间隔持续重试直到成功或超时
+ */
+export declare const PART_FINISH_RETRYABLE_CODES: Set<number>;
+/**
+ * upload_prepare 接口命中此错误码时，携带文件信息抛出 UploadDailyLimitExceededError，
+ * 由上层（outbound.ts）构造包含文件路径和大小的兜底文案发送给用户，
+ * 而非走通用的"文件发送失败，请稍后重试"
+ */
+export declare const UPLOAD_PREPARE_FALLBACK_CODE = 40093002;
 export declare function getGatewayUrl(accessToken: string): Promise<string>;
+/** 回应按钮交互（INTERACTION_CREATE），避免客户端按钮持续 loading */
+export declare function acknowledgeInteraction(accessToken: string, interactionId: string, code?: 0 | 1 | 2 | 3 | 4 | 5, data?: Record<string, unknown>): Promise<void>;
+/** 获取插件版本号（从 package.json 读取，和 PLUGIN_USER_AGENT 同源） */
+export declare function getApiPluginVersion(): string;
 export interface MessageResponse {
     id: string;
     timestamp: number | string;
@@ -95,7 +118,7 @@ export declare function sendDmMessage(accessToken: string, guildId: string, cont
     id: string;
     timestamp: string;
 }>;
-export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string): Promise<MessageResponse>;
+export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string, messageReference?: string): Promise<MessageResponse>;
 export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<MessageResponse>;
 export declare function sendProactiveGroupMessage(accessToken: string, groupOpenid: string, content: string): Promise<{
     id: string;
@@ -128,6 +151,10 @@ export interface UploadPrepareResponse {
     block_size: number;
     /** 分片列表（含预签名链接） */
     parts: UploadPart[];
+    /** 上传并发数（由服务端控制，可选，不返回时使用客户端默认值） */
+    concurrency?: number;
+    /** upload_part_finish 特定错误码的重试超时时间（秒），由服务端控制，客户端上限 10 分钟 */
+    retry_timeout?: number;
 }
 /** 完成文件上传响应（与 UploadMediaResponse 一致） */
 export interface MediaUploadResponse {
@@ -171,7 +198,7 @@ export declare function c2cUploadPrepare(accessToken: string, userId: string, fi
  * @param blockSize - 分块大小（字节）
  * @param md5 - 分片数据的 MD5（十六进制）
  */
-export declare function c2cUploadPartFinish(accessToken: string, userId: string, uploadId: string, partIndex: number, blockSize: number, md5: string): Promise<void>;
+export declare function c2cUploadPartFinish(accessToken: string, userId: string, uploadId: string, partIndex: number, blockSize: number, md5: string, retryTimeoutMs?: number): Promise<void>;
 /**
  * 完成文件上传（C2C）
  * POST /v2/users/{user_id}/files
@@ -191,7 +218,7 @@ export declare function groupUploadPrepare(accessToken: string, groupId: string,
  * 完成分片上传（Group）
  * POST /v2/groups/{group_id}/upload_part_finish
  */
-export declare function groupUploadPartFinish(accessToken: string, groupId: string, uploadId: string, partIndex: number, blockSize: number, md5: string): Promise<void>;
+export declare function groupUploadPartFinish(accessToken: string, groupId: string, uploadId: string, partIndex: number, blockSize: number, md5: string, retryTimeoutMs?: number): Promise<void>;
 /**
  * 完成文件上传（Group）
  * POST /v2/groups/{group_id}/files

package/dist/src/api.js

@@ -6,14 +6,22 @@ import os from "node:os";
 import { computeFileHash, getCachedFileInfo, setCachedFileInfo } from "./utils/upload-cache.js";
 import { sanitizeFileName } from "./utils/platform.js";
 // ============ 自定义错误 ============
-/** API 请求错误，携带 HTTP status code */
+/** API 请求错误，携带 HTTP status code 和业务错误码 */
 export class ApiError extends Error {
     status;
     path;
-    constructor(message, status, path) {
+    bizCode;
+    bizMessage;
+    constructor(message, status, path, 
+    /** 业务错误码（回包中的 code / err_code 字段），不一定存在 */
+    bizCode, 
+    /** 回包中的原始 message 字段（用于向用户展示兜底文案） */
+    bizMessage) {
         super(message);
         this.status = status;
         this.path = path;
+        this.bizCode = bizCode;
+        this.bizMessage = bizMessage;
         this.name = "ApiError";
     }
 }
@@ -264,7 +272,8 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
         // JSON 错误响应
         try {
             const error = JSON.parse(rawBody);
-            throw new ApiError(`API Error [${path}]: ${error.message ?? rawBody}`, res.status, path);
+            const bizCode = error.code ?? error.err_code;
+            throw new ApiError(`API Error [${path}]: ${error.message ?? rawBody}`, res.status, path, bizCode, error.message);
         }
         catch (parseErr) {
             if (parseErr instanceof ApiError)
@@ -332,10 +341,51 @@ async function completeUploadWithRetry(accessToken, method, path, body) {
     }
     throw lastError;
 }
-// ============ 分片完成重试（无条件，与 completeUpload 策略一致） ============
+// ============ 分片完成重试 ============
+/** 普通错误最大重试次数 */
 const PART_FINISH_MAX_RETRIES = 2;
 const PART_FINISH_BASE_DELAY_MS = 1000;
-async function partFinishWithRetry(accessToken, method, path, body) {
+/**
+ * 需要持续重试的业务错误码集合
+ * 当 upload_part_finish 返回这些错误码时，会以固定 1s 间隔持续重试直到成功或超时
+ */
+export const PART_FINISH_RETRYABLE_CODES = new Set([
+    40093001,
+]);
+/**
+ * upload_prepare 接口命中此错误码时，携带文件信息抛出 UploadDailyLimitExceededError，
+ * 由上层（outbound.ts）构造包含文件路径和大小的兜底文案发送给用户，
+ * 而非走通用的"文件发送失败，请稍后重试"
+ */
+export const UPLOAD_PREPARE_FALLBACK_CODE = 40093002;
+/** 特定错误码持续重试的默认超时（服务端未返回 retry_timeout 时的兜底） */
+const PART_FINISH_RETRYABLE_DEFAULT_TIMEOUT_MS = 2 * 60 * 1000;
+/** 特定错误码重试的固定间隔（1 秒） */
+const PART_FINISH_RETRYABLE_INTERVAL_MS = 1000;
+/**
+ * 判断错误是否命中"需要持续重试"的业务错误码
+ */
+function isRetryableBizCode(err) {
+    if (PART_FINISH_RETRYABLE_CODES.size === 0)
+        return false;
+    if (err instanceof ApiError && err.bizCode !== undefined) {
+        return PART_FINISH_RETRYABLE_CODES.has(err.bizCode);
+    }
+    return false;
+}
+/**
+ * 分片完成接口重试策略：
+ *
+ * 1. 命中 PART_FINISH_RETRYABLE_CODES 的错误码 → 每 1s 重试一次，直到成功或超时
+ *    超时时间 = min(API 返回的 retry_timeout, 10 分钟)
+ * 2. 其他错误 → 最多重试 PART_FINISH_MAX_RETRIES 次（与之前逻辑一致）
+ *
+ * 若持续重试超时或普通重试耗尽，抛出错误，调用方（chunkedUpload）
+ * 可据此中止后续分片上传。
+ *
+ * @param retryTimeoutMs - 持续重试的超时时间（毫秒），由 upload_prepare 返回的 retry_timeout 计算得出
+ */
+async function partFinishWithRetry(accessToken, method, path, body, retryTimeoutMs) {
     let lastError = null;
     for (let attempt = 0; attempt <= PART_FINISH_MAX_RETRIES; attempt++) {
         try {
@@ -344,6 +394,13 @@ async function partFinishWithRetry(accessToken, method, path, body) {
         }
         catch (err) {
             lastError = err instanceof Error ? err : new Error(String(err));
+            // 命中特定错误码 → 进入持续重试模式
+            if (isRetryableBizCode(err)) {
+                const timeoutMs = retryTimeoutMs ?? PART_FINISH_RETRYABLE_DEFAULT_TIMEOUT_MS;
+                console.warn(`[qqbot-api] PartFinish hit retryable bizCode=${err.bizCode}, entering persistent retry (timeout=${timeoutMs / 1000}s, interval=1s)...`);
+                await partFinishPersistentRetry(accessToken, method, path, body, timeoutMs);
+                return;
+            }
             if (attempt < PART_FINISH_MAX_RETRIES) {
                 const delay = PART_FINISH_BASE_DELAY_MS * Math.pow(2, attempt);
                 console.warn(`[qqbot-api] PartFinish attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 200)}`);
@@ -353,10 +410,52 @@ async function partFinishWithRetry(accessToken, method, path, body) {
     }
     throw lastError;
 }
+/**
+ * 特定错误码的持续重试模式
+ * 不限次数，仅受总超时时间约束，固定每 1 秒重试一次
+ */
+async function partFinishPersistentRetry(accessToken, method, path, body, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    let attempt = 0;
+    let lastError = null;
+    while (Date.now() < deadline) {
+        try {
+            await apiRequest(accessToken, method, path, body);
+            console.log(`[qqbot-api] PartFinish persistent retry succeeded after ${attempt} retries`);
+            return;
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err : new Error(String(err));
+            // 如果不再是可重试的错误码，直接抛出（可能是其他类型的错误）
+            if (!isRetryableBizCode(err)) {
+                console.error(`[qqbot-api] PartFinish persistent retry: error is no longer retryable (bizCode=${err.bizCode ?? "N/A"}), aborting`);
+                throw lastError;
+            }
+            attempt++;
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                break;
+            const actualDelay = Math.min(PART_FINISH_RETRYABLE_INTERVAL_MS, remaining);
+            console.warn(`[qqbot-api] PartFinish persistent retry #${attempt}: bizCode=${err.bizCode}, retrying in ${actualDelay}ms (remaining=${Math.round(remaining / 1000)}s)`);
+            await new Promise(resolve => setTimeout(resolve, actualDelay));
+        }
+    }
+    // 超时
+    console.error(`[qqbot-api] PartFinish persistent retry timed out after ${timeoutMs / 1000}s (${attempt} attempts)`);
+    throw new Error(`upload_part_finish 持续重试超时（${timeoutMs / 1000}s, ${attempt} 次重试），中止上传`);
+}
 export async function getGatewayUrl(accessToken) {
     const data = await apiRequest(accessToken, "GET", "/gateway");
     return data.url;
 }
+/** 回应按钮交互（INTERACTION_CREATE），避免客户端按钮持续 loading */
+export async function acknowledgeInteraction(accessToken, interactionId, code = 0, data) {
+    await apiRequest(accessToken, "PUT", `/interactions/${interactionId}`, { code, ...(data ? { data } : {}) });
+}
+/** 获取插件版本号（从 package.json 读取，和 PLUGIN_USER_AGENT 同源） */
+export function getApiPluginVersion() {
+    return _pluginVersion;
+}
 /**
  * 发送消息并自动触发 refIdx 回调
  * 所有消息发送函数统一经过此处，确保每条出站消息的 refIdx 都被捕获
@@ -429,10 +528,10 @@ export async function sendDmMessage(accessToken, guildId, content, msgId) {
         ...(msgId ? { msg_id: msgId } : {}),
     });
 }
-export async function sendGroupMessage(accessToken, groupOpenid, content, msgId) {
+export async function sendGroupMessage(accessToken, groupOpenid, content, msgId, messageReference) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
-    const body = buildMessageBody(content, msgId, msgSeq);
-    return apiRequest(accessToken, "POST", `/v2/groups/${groupOpenid}/messages`, body);
+    const body = buildMessageBody(content, msgId, msgSeq, messageReference);
+    return sendAndNotify(accessToken, "POST", `/v2/groups/${groupOpenid}/messages`, body, { text: content });
 }
 function buildProactiveMessageBody(content) {
     if (!content || content.trim().length === 0) {
@@ -487,8 +586,8 @@ export async function c2cUploadPrepare(accessToken, userId, fileType, fileName,
  * @param blockSize - 分块大小（字节）
  * @param md5 - 分片数据的 MD5（十六进制）
  */
-export async function c2cUploadPartFinish(accessToken, userId, uploadId, partIndex, blockSize, md5) {
-    await partFinishWithRetry(accessToken, "POST", `/v2/users/${userId}/upload_part_finish`, { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 });
+export async function c2cUploadPartFinish(accessToken, userId, uploadId, partIndex, blockSize, md5, retryTimeoutMs) {
+    await partFinishWithRetry(accessToken, "POST", `/v2/users/${userId}/upload_part_finish`, { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 }, retryTimeoutMs);
 }
 /**
  * 完成文件上传（C2C）
@@ -513,8 +612,8 @@ export async function groupUploadPrepare(accessToken, groupId, fileType, fileNam
  * 完成分片上传（Group）
  * POST /v2/groups/{group_id}/upload_part_finish
  */
-export async function groupUploadPartFinish(accessToken, groupId, uploadId, partIndex, blockSize, md5) {
-    await partFinishWithRetry(accessToken, "POST", `/v2/groups/${groupId}/upload_part_finish`, { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 });
+export async function groupUploadPartFinish(accessToken, groupId, uploadId, partIndex, blockSize, md5, retryTimeoutMs) {
+    await partFinishWithRetry(accessToken, "POST", `/v2/groups/${groupId}/upload_part_finish`, { upload_id: uploadId, part_index: partIndex, block_size: blockSize, md5 }, retryTimeoutMs);
 }
 /**
  * 完成文件上传（Group）

package/dist/src/channel.d.ts

@@ -9,3 +9,21 @@ export declare const TEXT_CHUNK_LIMIT = 5000;
  */
 export declare function chunkText(text: string, limit: number): string[];
 export declare const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount>;
+/** 清理 @mention：替换 <@openid> 为 @用户名，去除 @机器人自身 */
+export declare function stripMentionText(text: string, mentions?: Array<{
+    member_openid?: string;
+    id?: string;
+    user_openid?: string;
+    is_you?: boolean;
+    nickname?: string;
+    username?: string;
+}>): string;
+/** 检测消息是否 @了机器人（mentions > eventType > mentionPatterns） */
+export declare function detectWasMentioned({ eventType, mentions, content, mentionPatterns }: {
+    eventType?: string;
+    mentions?: Array<{
+        is_you?: boolean;
+    }>;
+    content?: string;
+    mentionPatterns?: string[];
+}): boolean;

package/dist/src/channel.js

@@ -1,5 +1,5 @@
 import { applyAccountNameToChannelSection, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from "openclaw/plugin-sdk/core";
-import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount, applyQQBotAccountConfig, resolveDefaultQQBotAccountId } from "./config.js";
+import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount, applyQQBotAccountConfig, resolveDefaultQQBotAccountId, resolveRequireMention, resolveToolPolicy, resolveGroupConfig } from "./config.js";
 import { sendText, sendMedia } from "./outbound.js";
 import { startGateway } from "./gateway.js";
 import { qqbotOnboardingAdapter } from "./onboarding.js";
@@ -39,8 +39,50 @@ export const qqbotPlugin = {
         blockStreaming: true,
     },
     reload: { configPrefixes: ["channels.qqbot"] },
+    // ============ 群消息策略适配器 ============
+    groups: {
+        /** 是否需要 @机器人才响应 */
+        resolveRequireMention: ({ cfg, accountId, groupId }) => {
+            if (!groupId)
+                return undefined;
+            return resolveRequireMention(cfg, groupId, accountId ?? undefined);
+        },
+        /** 群聊工具范围 */
+        resolveToolPolicy: ({ cfg, accountId, groupId }) => {
+            if (!groupId)
+                return undefined;
+            const policy = resolveToolPolicy(cfg, groupId, accountId ?? undefined);
+            // 将简单字符串策略映射为 GroupToolPolicyConfig 对象
+            if (policy === "full")
+                return undefined; // full = 默认不限制
+            if (policy === "none")
+                return { allow: [], deny: ["*"] };
+            // restricted: 默认空 allow（框架会使用内置 restricted 列表）
+            return { allow: [] };
+        },
+        /** QQ Bot 平台特有的群聊行为提示 */
+        resolveGroupIntroHint: ({ cfg, accountId, groupId }) => {
+            if (!groupId)
+                return undefined;
+            const groupCfg = resolveGroupConfig(cfg, groupId, accountId ?? undefined);
+            const hints = [];
+            if (groupCfg.name) {
+                hints.push(`当前群: ${groupCfg.name}`);
+            }
+            // bot 互聊防护、@状态行为指引在 gateway.ts 动态注入
+            return hints.join(" ") || undefined;
+        },
+    },
+    // ============ @mention 检测与清理 ============
+    mentions: {
+        /** 清理 @mention 文本（SDK ChannelMentionAdapter 接口） */
+        stripMentions: ({ text, ctx }) => {
+            const mentions = ctx?.mentions;
+            return stripMentionText(text, mentions);
+        },
+    },
     // CLI onboarding wizard
-    // @ts-expect-error onboarding removed from ChannelPlugin type in 2026.3.23 but still supported at runtime
+    // @ts-ignore onboarding removed from ChannelPlugin type in 2026.3.23 but still supported at runtime
     onboarding: qqbotOnboardingAdapter,
     config: {
         listAccountIds: (cfg) => listQQBotAccountIds(cfg),
@@ -367,3 +409,44 @@ export const qqbotPlugin = {
         }),
     },
 };
+// ============ 独立的 mention 工具函数（供 gateway.ts 等直接调用） ============
+/** 清理 @mention：替换 <@openid> 为 @用户名，去除 @机器人自身 */
+export function stripMentionText(text, mentions) {
+    if (!text || !mentions?.length)
+        return text;
+    let cleaned = text;
+    for (const m of mentions) {
+        const openid = m.member_openid ?? m.id ?? m.user_openid;
+        if (!openid)
+            continue;
+        if (m.is_you) {
+            cleaned = cleaned.replace(new RegExp(`<@!?${openid}>`, "g"), "").trim();
+        }
+        else {
+            const displayName = m.nickname ?? m.username;
+            if (displayName) {
+                cleaned = cleaned.replace(new RegExp(`<@!?${openid}>`, "g"), `@${displayName}`);
+            }
+        }
+    }
+    return cleaned;
+}
+/** 检测消息是否 @了机器人（mentions > eventType > mentionPatterns） */
+export function detectWasMentioned({ eventType, mentions, content, mentionPatterns }) {
+    if (mentions?.some((m) => m.is_you))
+        return true;
+    if (eventType === "GROUP_AT_MESSAGE_CREATE")
+        return true;
+    if (mentionPatterns?.length && content) {
+        for (const pattern of mentionPatterns) {
+            try {
+                if (new RegExp(pattern, "i").test(content))
+                    return true;
+            }
+            catch {
+                // 无效正则，跳过
+            }
+        }
+    }
+    return false;
+}

package/dist/src/config.d.ts

@@ -1,6 +1,36 @@
-import type { ResolvedQQBotAccount } from "./types.js";
-import type { OpenClawConfig } from "openclaw/plugin-sdk";
+import type { ResolvedQQBotAccount, ToolPolicy, GroupConfig } from "./types.js";
+import type { OpenClawConfig, GroupPolicy } from "openclaw/plugin-sdk";
+/**
+ * 解析 mentionPatterns（agent → global → 空数组）
+ *
+ * 优先级：
+ *   1. agents.list[agentId].groupChat.mentionPatterns
+ *   2. messages.groupChat.mentionPatterns
+ *   3. []
+ */
+export declare function resolveMentionPatterns(cfg: OpenClawConfig, agentId?: string): string[];
 export declare const DEFAULT_ACCOUNT_ID = "default";
+/** 解析群消息策略 */
+export declare function resolveGroupPolicy(cfg: OpenClawConfig, accountId?: string): GroupPolicy;
+/** 解析群白名单（统一转大写） */
+export declare function resolveGroupAllowFrom(cfg: OpenClawConfig, accountId?: string): string[];
+/** 检查指定群是否被允许（使用标准策略引擎） */
+export declare function isGroupAllowed(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): boolean;
+type ResolvedGroupConfig = Omit<Required<GroupConfig>, "prompt"> & Pick<GroupConfig, "prompt">;
+/** 解析指定群配置（具体 groupOpenid > 通配符 "*" > 默认值） */
+export declare function resolveGroupConfig(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): ResolvedGroupConfig;
+/** 解析群历史消息缓存条数 */
+export declare function resolveHistoryLimit(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): number;
+/** 解析群行为 PE（具体群 > "*" > 默认值） */
+export declare function resolveGroupPrompt(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): string;
+/** 解析群是否需要 @机器人才响应 */
+export declare function resolveRequireMention(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): boolean;
+/** 解析群是否忽略 @了其他人（非 bot）的消息 */
+export declare function resolveIgnoreOtherMentions(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): boolean;
+/** 解析群工具策略 */
+export declare function resolveToolPolicy(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): ToolPolicy;
+/** 解析群名称（优先配置，fallback 为 openid 前 8 位） */
+export declare function resolveGroupName(cfg: OpenClawConfig, groupOpenid: string, accountId?: string): string;
 /**
  * 列出所有 QQBot 账户 ID
  */
@@ -23,3 +53,4 @@ export declare function applyQQBotAccountConfig(cfg: OpenClawConfig, accountId:
     name?: string;
     imageServerBaseUrl?: string;
 }): OpenClawConfig;
+export {};

package/dist/src/config.js

@@ -1,4 +1,128 @@
+/**
+ * 解析 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 "";