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

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