@tencent-connect/openclaw-qqbot 1.6.6-alpha.3 → 1.6.6

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.5`
+### 🚀 Current Version: `v1.6.6`
 
 [![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/)
@@ -25,7 +25,7 @@
 
 Scan to join the QQ group chat
 
-<img width="400" alt="QQ QR Code" src="./docs/images/developer_group.png" />
+<img width="400" alt="QQ QR Code" src="./docs/images/developer-group.png" />
 
 
 </div>
@@ -61,7 +61,7 @@ QQ quote events carry index keys (e.g. `REFIDX_xxx`) instead of full original me
 - Store path: `~/.openclaw/qqbot/data/ref-index.jsonl` (survives gateway restart).
 - Quote body may include text + media summary (image/voice/video/file).
 
-<img width="360" src="docs/images/ref_msg.png" alt="Quoted Message Context Demo" />
+<img width="360" src="docs/images/ref-msg.png" alt="Quoted Message Context Demo" />
 
 ### 🎙️ Voice Messages (STT)
 
@@ -71,7 +71,7 @@ With STT configured, the plugin automatically transcribes voice messages to text
 >
 > **QQBot**: Tomorrow (March 7, Saturday) Shenzhen weather forecast 🌤️ ...
 
-<img width="360" src="docs/images/fc7b2236896cfba3a37c94be5d59ce3e_720.jpg" alt="Voice STT Demo" />
+<img width="360" src="docs/images/voice-stt.jpg" alt="Voice STT Demo" />
 
 ### 📄 File Understanding
 
@@ -81,7 +81,7 @@ Send any file to the bot — novels, reports, spreadsheets — AI automatically
 >
 > **QQBot**: Got it! You uploaded the Chinese version of "War and Peace" by Leo Tolstoy. This appears to be the opening of Chapter 1...
 
-<img width="360" src="docs/images/07bff56ab68e03173d2af586eeb3bcee_720.jpg" alt="File Understanding Demo" />
+<img width="360" src="docs/images/file-understand.jpg" alt="File Understanding Demo" />
 
 ### 🖼️ Image Understanding
 
@@ -91,7 +91,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 >
 > **QQBot**: Haha, so cute! Is that a QQ penguin in a lobster costume? 🦞🐧 ...
 
-<img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="Image Understanding Demo" />
+<img width="360" src="docs/images/image-understand.jpg" alt="Image Understanding Demo" />
 
 ### 🎨 Image Sending
 
@@ -101,7 +101,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 
 AI can send images directly. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.
 
-<img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="Image Generation Demo" />
+<img width="360" src="docs/images/image-send.jpg" alt="Image Generation Demo" />
 
 ### 🔊 Voice Sending
 
@@ -111,7 +111,7 @@ AI can send images directly. Supports local paths and URLs. Formats: jpg/png/gif
 
 AI can send voice messages directly. Formats: mp3/wav/silk/ogg. No ffmpeg required.
 
-<img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="TTS Voice Demo" />
+<img width="360" src="docs/images/voice-send.jpg" alt="TTS Voice Demo" />
 
 ### ⏰ Scheduled Reminder (Proactive Message)
 
@@ -129,9 +129,13 @@ 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 20MB.
+AI can send files directly, in any format.
 
-<img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="File Sending Demo" />
+<img width="360" src="docs/images/file-send.jpg" alt="File Sending Demo" />
+
+Since v1.6.6, large file transfer is supported: images up to 20MB, videos up to 30MB, attachments up to 100MB, with a daily transfer limit of 2GB.
+
+<img width="360" src="docs/images/large-file-transfer.jpg" alt="Large File Transfer Demo" />
 
 ### 🎬 Video Sending
 
@@ -141,7 +145,7 @@ AI can send files directly. Any format, up to 20MB.
 
 AI can send videos directly. Supports local files and URLs.
 
-<img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="Video Sending Demo" />
+<img width="360" src="docs/images/video-send.jpg" alt="Video Sending Demo" />
 
 > **Under the hood:** Upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.
 
@@ -220,15 +224,15 @@ All commands support a `?` suffix to show usage:
 2. After scanning, tap **Agree** on your phone — you'll land on the bot configuration page.
 3. Click **Create Bot** to create a new QQ bot.
 
-<img width="720" alt="Create Bot" src="docs/images/create_robot.png" />
+<img width="720" alt="Create Bot" src="docs/images/create-robot.png" />
 
 > ⚠️ The bot will automatically appear in your QQ message list and send a first message. However, it will reply "The bot has gone to Mars" until you complete the configuration steps below.
 
-<img width="400" alt="Bot Say Hello" src="docs/images/bot_say_hello.jpg" />
+<img width="400" alt="Bot Say Hello" src="docs/images/bot-say-hello.jpg" />
 
 4. Find **AppID** and **AppSecret** on the bot's page, click **Copy** for each, and save them somewhere safe (e.g., a notepad). **AppSecret is not stored in plaintext — if you leave the page without saving it, you'll have to regenerate a new one.**
 
-<img width="720" alt="Find AppID and AppSecret" src="docs/images/find_appid_secret.png" />
+<img width="720" alt="Find AppID and AppSecret" src="docs/images/find-appid-secret.png" />
 
 > For a step-by-step walkthrough with screenshots, see the [official guide](https://cloud.tencent.com/developer/article/2626045).
 
@@ -458,7 +462,7 @@ Special thanks to [@sliverp](https://github.com/sliverp) for outstanding contrib
 Thanks to [Tencent Cloud Lighthouse](https://cloud.tencent.com/product/lighthouse) for the deep collaboration. For raising crawfish, choose Tencent Cloud Lighthouse!
 
 <a href="https://cloud.tencent.com/product/lighthouse">
-  <img alt="Tencent Cloud Lighthouse" src="./docs/images/lighthouse_head.png" height="500" style="max-width:80%; height:auto;"/>
+  <img alt="Tencent Cloud Lighthouse" src="./docs/images/lighthouse-head.png" height="500" style="max-width:80%; height:auto;"/>
 </a>
 
 ## ⭐ Star History

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.5`
+### 🚀 当前版本： `v1.6.6`
 
 [![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/)
@@ -21,7 +21,7 @@
 
 扫描二维码加入群聊，一起交流
 
-<img width="400" alt="QQ 群二维码" src="./docs/images/developer_group.png" />
+<img width="400" alt="QQ 群二维码" src="./docs/images/developer-group.png" />
 
 </div>
 
@@ -56,7 +56,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 - 存储位置：`~/.openclaw/qqbot/data/ref-index.jsonl`（网关重启后仍可恢复）。
 - 引用内容支持文本 + 媒体摘要（图片/语音/视频/文件）。
 
-<img width="360" src="docs/images/ref_msg.png" alt="引用消息上下文演示" />
+<img width="360" src="docs/images/ref-msg.png" alt="引用消息上下文演示" />
 
 ### 🎙️ 语音消息（STT）
 
@@ -66,7 +66,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 >
 > **QQBot**：明天（3月7日 周六）深圳的天气预报 🌤️ ...
 
-<img width="360" src="docs/images/fc7b2236896cfba3a37c94be5d59ce3e_720.jpg" alt="听语音演示" />
+<img width="360" src="docs/images/voice-stt.jpg" alt="听语音演示" />
 
 ### 📄 文件理解
 
@@ -76,7 +76,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 >
 > **QQBot**：收到！你上传了列夫·托尔斯泰的《战争与和平》中文版文本。从内容来看，这是第一章的开头……你想让我做什么？
 
-<img width="360" src="docs/images/07bff56ab68e03173d2af586eeb3bcee_720.jpg" alt="AI理解用户发送的文件" />
+<img width="360" src="docs/images/file-understand.jpg" alt="AI理解用户发送的文件" />
 
 ### 🖼️ 图片理解
 
@@ -86,7 +86,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 >
 > **QQBot**：哈哈，好可爱！这是QQ企鹅穿上小龙虾套装吗？🦞🐧 ...
 
-<img width="360" src="docs/images/59d421891f813b0d3c0cbe12574b6a72_720.jpg" alt="图片理解演示" />
+<img width="360" src="docs/images/image-understand.jpg" alt="图片理解演示" />
 
 ### 🎨 图片发送
 
@@ -96,7 +96,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 
 AI 可直接发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
 
-<img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
+<img width="360" src="docs/images/image-send.jpg" alt="发图片演示" />
 
 ### 🔊 语音发送
 
@@ -106,7 +106,7 @@ AI 可直接发送图片，支持本地文件路径和网络 URL。格式：jpg/
 
 AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
 
-<img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="发语音演示" />
+<img width="360" src="docs/images/voice-send.jpg" alt="发语音演示" />
 
 ### ⏰ 定时提醒（主动消息）
 
@@ -124,9 +124,13 @@ AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg
 >
 > **QQBot**：*（发送 .txt 文件）*
 
-AI 可直接发送文件。任意格式，最大 20MB。
+AI 可直接发送文件，任意格式均可。
 
-<img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="发文件演示" />
+<img width="360" src="docs/images/file-send.jpg" alt="发文件演示" />
+
+v1.6.6 起支持大文件传输：图片最大 20MB，视频最大 30MB，附件最大 100MB，每日累计传输上限 2GB。
+
+<img width="360" src="docs/images/large-file-transfer.jpg" alt="大文件传输演示" />
 
 ### 🎬 视频发送
 
@@ -136,7 +140,7 @@ AI 可直接发送文件。任意格式，最大 20MB。
 
 AI 可直接发送视频，支持本地文件和公网 URL。
 
-<img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="发视频演示" />
+<img width="360" src="docs/images/video-send.jpg" alt="发视频演示" />
 
 > **底层细节：** 上传去重缓存、有序队列发送、音频格式多层降级。
 
@@ -215,15 +219,15 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 2. 手机 QQ 扫码后选择**同意**，即完成注册，进入 QQ 机器人配置页。
 3. 点击**创建机器人**，即可直接新建一个 QQ 机器人。
 
-<img width="720" alt="创建机器人" src="docs/images/create_robot.png" />
+<img width="720" alt="创建机器人" src="docs/images/create-robot.png" />
 
 > ⚠️ 机器人创建后会自动出现在你的 QQ 消息列表中，并发送第一条消息。但在完成下面的配置之前，发消息会提示"该机器人去火星了"，属于正常现象。
 
-<img width="400" alt="机器人打招呼" src="docs/images/bot_say_hello.jpg" />
+<img width="400" alt="机器人打招呼" src="docs/images/bot-say-hello.jpg" />
 
 4. 在机器人页面中找到 **AppID** 和 **AppSecret**，分别点击右侧**复制**按钮，保存到记事本或备忘录中。**AppSecret 不支持明文保存，离开页面后再查看会强制重置，请务必妥善保存。**
 
-<img width="720" alt="找到 AppID 和 AppSecret" src="docs/images/find_appid_secret.png" />
+<img width="720" alt="找到 AppID 和 AppSecret" src="docs/images/find-appid-secret.png" />
 
 > 详细图文教程请参阅 [官方指南](https://cloud.tencent.com/developer/article/2626045)。
 
@@ -453,7 +457,7 @@ STT 支持两级配置，按优先级查找：
 感谢[腾讯云Lighthouse](https://cloud.tencent.com/product/lighthouse)的深度合作，养小龙虾，首选腾讯云Lighthouse！
 
 <a href="https://cloud.tencent.com/product/lighthouse">
-  <img alt="腾讯云 Lighthouse" src="./docs/images/lighthouse_head.png" height="500" style="max-width:80%; height:auto;"/>
+  <img alt="腾讯云 Lighthouse" src="./docs/images/lighthouse-head.png" height="500" style="max-width:80%; height:auto;"/>
 </a>
 
 ## ⭐ Star History

package/dist/src/api.d.ts

@@ -83,11 +83,16 @@ export declare function apiRequest<T = unknown>(accessToken: string, method: str
  */
 export declare const PART_FINISH_RETRYABLE_CODES: Set<number>;
 /**
- * upload_prepare 接口命中此错误码时，使用回包中的 message 字段作为兜底文案发送给用户
+ * 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;
@@ -113,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;

package/dist/src/api.js

@@ -353,7 +353,8 @@ export const PART_FINISH_RETRYABLE_CODES = new Set([
     40093001,
 ]);
 /**
- * upload_prepare 接口命中此错误码时，使用回包中的 message 字段作为兜底文案发送给用户
+ * upload_prepare 接口命中此错误码时，携带文件信息抛出 UploadDailyLimitExceededError，
+ * 由上层（outbound.ts）构造包含文件路径和大小的兜底文案发送给用户，
  * 而非走通用的"文件发送失败，请稍后重试"
  */
 export const UPLOAD_PREPARE_FALLBACK_CODE = 40093002;
@@ -447,6 +448,14 @@ 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 都被捕获
@@ -519,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) {

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 "";