@ryantest/openclaw-qqbot 1.6.6-alpha.3 → 1.6.7-beta.1

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>
@@ -46,6 +46,7 @@ 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 |
 
 ---
 
@@ -61,7 +62,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 +72,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 +82,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 +92,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 +102,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 +112,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 +130,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 +146,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.
 
@@ -207,6 +212,10 @@ All commands support a `?` suffix to show usage:
 >
 > **QQBot**: 📖 /bot-upgrade usage: …
 
+#### `/bot-clear-storage` — Clear files generated through QQBot conversations and downloaded resources (stored on the host running OpenClaw)
+
+`/bot-clear-storage` lists files generated by the conversation and files in the downloaded resources directory. Use `/bot-clear-storage --force` to confirm deletion.
+
 ---
 
 ## 🚀 Getting Started
@@ -220,15 +229,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 +467,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>
 
@@ -41,6 +41,7 @@
 | 📝 **Markdown** | 完整支持 Markdown 格式消息 |
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
 | 💬 **引用上下文** | 解析 QQ `REFIDX_*` 引用消息，并将引用内容注入 AI 上下文 |
+| 📦 **大文件支持** | 大文件自动分片并行上传，最大支持 100 MB |
 
 ---
 
@@ -56,7 +57,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 +67,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 +77,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 +87,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 +97,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 +107,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 +125,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 +141,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="发视频演示" />
 
 > **底层细节：** 上传去重缓存、有序队列发送、音频格式多层降级。
 
@@ -202,6 +207,10 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 >
 > **QQBot**：📖 /bot-upgrade 用法：…
 
+#### `/bot-clear-storage` — 清理通过 QQBot 对话产生的文件以及下载的资源（保存在 OpenClaw 运行环境的主机上）
+
+`/bot-clear-storage` 列出对话产生的文件以及下载的资源目录里的文件，使用`/bot-clear-storage -- force`确定删除。
+
 ---
 
 ## 🚀 快速开始
@@ -215,15 +224,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 +462,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

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