@ryantest/openclaw-qqbot 1.6.6-alpha.4 → 1.6.7-beta.2

package/src/types.ts

@@ -26,6 +26,31 @@ export interface ResolvedQQBotAccount {
   config: QQBotAccountConfig;
 }
 
+/** 群消息策略：open=全响应 | allowlist=白名单 | disabled=不响应 */
+export type GroupPolicy = "open" | "allowlist" | "disabled";
+
+/** 工具策略：full=全部 | restricted=限制敏感工具 | none=禁止 */
+export type ToolPolicy = "full" | "restricted" | "none";
+
+/** 单个群的配置 */
+export interface GroupConfig {
+  /** 是否需要 @机器人才响应（默认 true） */
+  requireMention?: boolean;
+  /**
+   * 是否忽略 @了其他用户但没有 @机器人的消息（默认 false）。
+   * 开启后，消息中 @了其他人但未 @bot 时直接丢弃（不记录历史、不触发 AI）。
+   */
+  ignoreOtherMentions?: boolean;
+  /** 群聊中 AI 可使用的工具范围（默认 restricted） */
+  toolPolicy?: ToolPolicy;
+  /** 群名称 */
+  name?: string;
+  /** 群消息行为 PE（未配置时使用内置默认值） */
+  prompt?: string;
+  /** 群历史消息缓存条数（0 禁用，默认 20） */
+  historyLimit?: number;
+}
+
 /**
  * QQ Bot 账户配置
  */
@@ -37,6 +62,12 @@ export interface QQBotAccountConfig {
   clientSecretFile?: string;
   dmPolicy?: "open" | "pairing" | "allowlist";
   allowFrom?: string[];
+  /** 群消息策略（默认 allowlist） */
+  groupPolicy?: GroupPolicy;
+  /** 群白名单（groupPolicy 为 allowlist 时生效） */
+  groupAllowFrom?: string[];
+  /** 群配置映射（按 groupOpenid 索引，"*" 为默认） */
+  groups?: Record<string, GroupConfig>;
   /** 系统提示词，会添加在用户消息前面 */
   systemPrompt?: string;
   /** 图床服务器公网地址，用于发送图片，例如 http://your-ip:18765 */
@@ -66,8 +97,8 @@ export interface QQBotAccountConfig {
   upgradeUrl?: string;
   /**
    * /bot-upgrade 指令的行为模式
-   * - "doc"：展示升级文档链接（默认，安全模式）
-   * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新
+   * - "doc"：展示升级文档链接（安全模式）
+   * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新（默认）
    */
   upgradeMode?: "doc" | "hot-reload";
   /**
@@ -199,6 +230,8 @@ export interface GroupMessageEvent {
   author: {
     id: string;
     member_openid: string;
+    username?: string;
+    bot?: boolean;
   };
   content: string;
   id: string;
@@ -210,6 +243,65 @@ export interface GroupMessageEvent {
     ext?: string[];
   };
   attachments?: MessageAttachment[];
+  /** @提及列表 */
+  mentions?: Array<{
+    scope?: "all" | "single";
+    id?: string;
+    user_openid?: string;
+    member_openid?: string;
+    nickname?: string;
+    bot?: boolean;
+    /** 是否 @机器人自身 */
+    is_you?: boolean;
+  }>;
+}
+
+/**
+ * 按钮交互事件（INTERACTION_CREATE）
+ */
+export interface InteractionEvent {
+  /** 事件 ID，用于回应交互（PUT /interactions/{id}） */
+  id: string;
+  /** 事件类型：11=消息按钮 12=单聊快捷菜单 */
+  type: number;
+  /** 场景：c2c / group / guild */
+  scene?: string;
+  /** 场景类型：0=频道 1=群聊 2=单聊 */
+  chat_type?: number;
+  /** 触发时间 RFC3339 */
+  timestamp?: string;
+  /** 频道 openid（仅频道场景） */
+  guild_id?: string;
+  /** 子频道 openid（仅频道场景） */
+  channel_id?: string;
+  /** 单聊用户 openid（仅 c2c 场景） */
+  user_openid?: string;
+  /** 群 openid（仅群聊场景） */
+  group_openid?: string;
+  /** 群内触发用户 openid（仅群聊场景） */
+  group_member_openid?: string;
+  version: number;
+  data: {
+    type: number;
+    resolved: {
+      /** 按钮 action.data 值 */
+      button_data?: string;
+      /** 按钮 id */
+      button_id?: string;
+      /** 操作用户 userid（仅频道场景） */
+      user_id?: string;
+      /** 自定义菜单 id（仅菜单场景） */
+      feature_id?: string;
+      /** 操作的消息 id（仅频道场景） */
+      message_id?: string;
+      /** 配置更新：群消息模式 "mention"=@机器人时激活 "always"=总是激活 */
+      require_mention?: string;
+      /** 配置更新：群消息策略 */
+      group_policy?: GroupPolicy;
+      /** 配置更新：@文本的名称提及BOT名，多个使用,分隔 */
+      mention_patterns?: string;
+    };
+  };
 }
 
 /**

package/src/utils/audio-convert.ts

@@ -412,7 +412,7 @@ const QQ_NATIVE_UPLOAD_FORMATS = [".wav", ".mp3", ".silk"];
  * 将本地音频文件转换为 QQ Bot 可上传的 Base64
  *
  * QQ Bot API 支持直传 WAV、MP3、SILK 三种格式，其他格式仍需转换。
- * 转换策略（参考 NapCat/go-cqhttp/Discord/Telegram 的做法）：
+ * 转换策略：
  *
  * 1. WAV / MP3 / SILK → 直传（跳过转换）
  * 2. 有 ffmpeg → ffmpeg 万能解码为 PCM → silk-wasm 编码

package/src/utils/chunked-upload.ts

@@ -20,6 +20,8 @@ import {
   type UploadPrepareResponse,
   type UploadPrepareHashes,
   type MediaUploadResponse,
+  ApiError,
+  UPLOAD_PREPARE_FALLBACK_CODE,
   c2cUploadPrepare,
   c2cUploadPartFinish,
   c2cCompleteUpload,
@@ -30,8 +32,32 @@ import {
 } from "../api.js";
 import { formatFileSize } from "./file-utils.js";
 
-/** 分片上传并发控制：最多同时上传 N 个分片 */
-const MAX_CONCURRENT_PARTS = 1;
+/**
+ * upload_prepare 返回特定错误码（40093002）时抛出：文件超过每日累积上传限制
+ * 调用方根据携带的文件信息构造兜底文案发送给用户
+ */
+export class UploadDailyLimitExceededError extends Error {
+  /** 触发错误的本地文件路径 */
+  public readonly filePath: string;
+  /** 文件大小（字节） */
+  public readonly fileSize: number;
+
+  constructor(filePath: string, fileSize: number, originalMessage: string) {
+    super(originalMessage);
+    this.name = "UploadDailyLimitExceededError";
+    this.filePath = filePath;
+    this.fileSize = fileSize;
+  }
+}
+
+/** 分片上传默认并发数（服务端未返回 concurrency 时的兜底） */
+const DEFAULT_CONCURRENT_PARTS = 1;
+
+/** 分片上传并发上限（即使服务端返回更大的值也不超过此限制） */
+const MAX_CONCURRENT_PARTS = 10;
+
+/** partFinish 特定错误码重试超时上限（10 分钟），即使服务端 retry_timeout 更大也不超过此值 */
+const MAX_PART_FINISH_RETRY_TIMEOUT_MS = 10 * 60 * 1000;
 
 /** 单个分片上传超时（毫秒）— 5 分钟，兼容低带宽场景 */
 const PART_UPLOAD_TIMEOUT = 300_000;
@@ -55,8 +81,6 @@ export interface ChunkedUploadProgress {
 export interface ChunkedUploadOptions {
   /** 进度回调 */
   onProgress?: (progress: ChunkedUploadProgress) => void;
-  /** 最大并发数（默认 2） */
-  maxConcurrent?: number;
   /** 日志前缀 */
   logPrefix?: string;
 }
@@ -81,7 +105,6 @@ export async function chunkedUploadC2C(
   options?: ChunkedUploadOptions,
 ): Promise<MediaUploadResponse> {
   const prefix = options?.logPrefix ?? "[chunked-upload]";
-  const maxConcurrent = options?.maxConcurrent ?? MAX_CONCURRENT_PARTS;
 
   // 1. 读取文件信息
   const stat = await fs.promises.stat(filePath);
@@ -98,13 +121,34 @@ export async function chunkedUploadC2C(
   // 3. 申请上传 → 获取 upload_id + block_size + 预签名链接
   const accessToken = await getAccessToken(appId, clientSecret);
   console.log(`${prefix} >>> Calling c2cUploadPrepare(fileType=${fileType}, fileName=${fileName}, fileSize=${fileSize}, md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m})`);
-  const prepareResp = await c2cUploadPrepare(accessToken, userId, fileType, fileName, fileSize, hashes);
+  let prepareResp: UploadPrepareResponse;
+  try {
+    prepareResp = await c2cUploadPrepare(accessToken, userId, fileType, fileName, fileSize, hashes);
+  } catch (err) {
+    // 命中特定错误码 → 携带文件信息抛出，由上层构造兜底文案
+    if (err instanceof ApiError && err.bizCode === UPLOAD_PREPARE_FALLBACK_CODE) {
+      console.warn(`${prefix} c2cUploadPrepare hit fallback code ${UPLOAD_PREPARE_FALLBACK_CODE}`);
+      throw new UploadDailyLimitExceededError(filePath, fileSize, err.message);
+    }
+    throw err;
+  }
   console.log(`${prefix} <<< c2cUploadPrepare response:`, JSON.stringify(prepareResp));
   const { upload_id, parts } = prepareResp;
   // QQ 开放平台返回的 block_size 可能是字符串，需要转为数字
   const block_size = Number(prepareResp.block_size);
 
-  console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}`);
+  // 并发数：使用 API 返回的 concurrency，未返回则用默认值，且不超过上限
+  const maxConcurrent = Math.min(
+    prepareResp.concurrency ? Number(prepareResp.concurrency) : DEFAULT_CONCURRENT_PARTS,
+    MAX_CONCURRENT_PARTS,
+  );
+
+  // partFinish 特定错误码的重试超时：使用 API 返回的 retry_timeout（秒），上限 10 分钟
+  const retryTimeoutMs = prepareResp.retry_timeout
+    ? Math.min(Number(prepareResp.retry_timeout) * 1000, MAX_PART_FINISH_RETRY_TIMEOUT_MS)
+    : undefined;
+
+  console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}, concurrency=${maxConcurrent}, retryTimeout=${retryTimeoutMs ? retryTimeoutMs / 1000 + 's' : 'default'}`);
 
   // 4. 并行上传所有分片（带并发控制）
   let completedParts = 0;
@@ -131,7 +175,7 @@ export async function chunkedUploadC2C(
     // b. 通知开放平台分片上传完成（需要重新获取 token，避免长时间上传后 token 过期）
     const token = await getAccessToken(appId, clientSecret);
     console.log(`${prefix} >>> Calling c2cUploadPartFinish(upload_id=${upload_id}, partIndex=${partIndex}, blockSize=${length}, md5=${md5Hex})`);
-    await c2cUploadPartFinish(token, userId, upload_id, partIndex, length, md5Hex);
+    await c2cUploadPartFinish(token, userId, upload_id, partIndex, length, md5Hex, retryTimeoutMs);
     console.log(`${prefix} <<< c2cUploadPartFinish(partIndex=${partIndex}) done`);
 
     // 更新进度
@@ -188,7 +232,6 @@ export async function chunkedUploadGroup(
   options?: ChunkedUploadOptions,
 ): Promise<MediaUploadResponse> {
   const prefix = options?.logPrefix ?? "[chunked-upload]";
-  const maxConcurrent = options?.maxConcurrent ?? MAX_CONCURRENT_PARTS;
 
   // 1. 读取文件信息
   const stat = await fs.promises.stat(filePath);
@@ -205,13 +248,34 @@ export async function chunkedUploadGroup(
   // 3. 申请上传
   const accessToken = await getAccessToken(appId, clientSecret);
   console.log(`${prefix} >>> Calling groupUploadPrepare(fileType=${fileType}, fileName=${fileName}, fileSize=${fileSize}, md5=${hashes.md5}, sha1=${hashes.sha1}, md5_10m=${hashes.md5_10m})`);
-  const prepareResp = await groupUploadPrepare(accessToken, groupId, fileType, fileName, fileSize, hashes);
+  let prepareResp: UploadPrepareResponse;
+  try {
+    prepareResp = await groupUploadPrepare(accessToken, groupId, fileType, fileName, fileSize, hashes);
+  } catch (err) {
+    // 命中特定错误码 → 携带文件信息抛出，由上层构造兜底文案
+    if (err instanceof ApiError && err.bizCode === UPLOAD_PREPARE_FALLBACK_CODE) {
+      console.warn(`${prefix} groupUploadPrepare hit fallback code ${UPLOAD_PREPARE_FALLBACK_CODE}`);
+      throw new UploadDailyLimitExceededError(filePath, fileSize, err.message);
+    }
+    throw err;
+  }
   console.log(`${prefix} <<< groupUploadPrepare response:`, JSON.stringify(prepareResp));
   const { upload_id, parts } = prepareResp;
   // QQ 开放平台返回的 block_size 可能是字符串，需要转为数字
   const block_size = Number(prepareResp.block_size);
 
-  console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}`);
+  // 并发数：使用 API 返回的 concurrency，未返回则用默认值，且不超过上限
+  const maxConcurrent = Math.min(
+    prepareResp.concurrency ? Number(prepareResp.concurrency) : DEFAULT_CONCURRENT_PARTS,
+    MAX_CONCURRENT_PARTS,
+  );
+
+  // partFinish 特定错误码的重试超时：使用 API 返回的 retry_timeout（秒），上限 10 分钟
+  const retryTimeoutMs = prepareResp.retry_timeout
+    ? Math.min(Number(prepareResp.retry_timeout) * 1000, MAX_PART_FINISH_RETRY_TIMEOUT_MS)
+    : undefined;
+
+  console.log(`${prefix} Upload prepared: upload_id=${upload_id}, block_size=${formatFileSize(block_size)}, parts=${parts.length}, concurrency=${maxConcurrent}, retryTimeout=${retryTimeoutMs ? retryTimeoutMs / 1000 + 's' : 'default'}`);
 
   // 4. 并行上传所有分片（带并发控制）
   let completedParts = 0;
@@ -232,7 +296,7 @@ export async function chunkedUploadGroup(
 
     const token = await getAccessToken(appId, clientSecret);
     console.log(`${prefix} >>> Calling groupUploadPartFinish(upload_id=${upload_id}, partIndex=${partIndex}, blockSize=${length}, md5=${md5Hex})`);
-    await groupUploadPartFinish(token, groupId, upload_id, partIndex, length, md5Hex);
+    await groupUploadPartFinish(token, groupId, upload_id, partIndex, length, md5Hex, retryTimeoutMs);
     console.log(`${prefix} <<< groupUploadPartFinish(partIndex=${partIndex}) done`);
 
     completedParts++;

package/src/utils/media-send.ts

@@ -364,6 +364,7 @@ export async function executeSendQueue(
   };
 
   for (const item of queue) {
+    const FALLBACK_MSG = "发送失败，请稍后重试。";
     try {
       if (item.type === "text") {
         if (options.skipInterTagText) {
@@ -380,8 +381,6 @@ export async function executeSendQueue(
 
       log?.info(`${prefix} executeSendQueue: sending ${item.type}: ${item.content.slice(0, 80)}...`);
 
-      const FALLBACK_MSG = "发送失败，请稍后重试。";
-
       if (item.type === "image") {
         const result = await sendPhoto(mediaTarget, item.content);
         if (result.error) {

package/src/utils/text-parsing.ts

@@ -3,6 +3,7 @@
  */
 
 import type { RefAttachmentSummary } from "../ref-index-store.js";
+import { inferAttachmentType } from "../group-history.js";
 
 /**
  * 解析 QQ 表情标签，将 <faceType=1,faceId="13",ext="base64..."> 格式
@@ -65,18 +66,10 @@ export function buildAttachmentSummaries(
   localPaths?: Array<string | null>,
 ): RefAttachmentSummary[] | undefined {
   if (!attachments || attachments.length === 0) return undefined;
-  return attachments.map((att, idx) => {
-    const ct = att.content_type?.toLowerCase() ?? "";
-    let type: RefAttachmentSummary["type"] = "unknown";
-    if (ct.startsWith("image/")) type = "image";
-    else if (ct === "voice" || ct.startsWith("audio/") || ct.includes("silk") || ct.includes("amr")) type = "voice";
-    else if (ct.startsWith("video/")) type = "video";
-    else if (ct.startsWith("application/") || ct.startsWith("text/")) type = "file";
-    return {
-      type,
-      filename: att.filename,
-      contentType: att.content_type,
-      localPath: localPaths?.[idx] ?? undefined,
-    };
-  });
+  return attachments.map((att, idx) => ({
+    type: inferAttachmentType(att.content_type),
+    filename: att.filename,
+    contentType: att.content_type,
+    localPath: localPaths?.[idx] ?? undefined,
+  }));
 }