@tencent-connect/openclaw-qqbot 1.6.7 → 1.7.0-alpha.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.7`
+### 🚀 Current Version: `v1.7.0`
 
 [![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/)
@@ -45,11 +45,50 @@ Scan to join the QQ group chat
 | ⌨️ **Typing Indicator** | "Bot is typing..." status shown in real-time |
 | 📝 **Markdown** | Full Markdown formatting support |
 | 🛠️ **Commands** | Native OpenClaw command integration |
-| 💬 **Quoted Context** | Resolve QQ `REFIDX_*` quoted messages and inject quote body into AI context |
+| 💬 **Quoted Context** | Parses the original message a user is replying to and injects it into AI context, so the model always knows exactly which message is being referenced |
 | 📦 **Large File Support** | Auto chunked upload for large files (parallel upload with retry), up to 100 MB |
 
 ---
 
+## 🆚 Standalone Plugin vs OpenClaw Built-in: Which to Choose?
+
+Starting from **OpenClaw 2026.3.31**, a QQBot plugin is bundled with OpenClaw. The two plugins **cannot run at the same time** — choose one based on your needs.
+
+| Feature | This Plugin (Standalone) | OpenClaw Built-in |
+|---------|:------------------------:|:-----------------:|
+| 🔒 Multi-scene (C2C / Group) | ✅ | ✅ |
+| 🖼️ Rich media (image / voice / video / file) | ✅ | ✅ |
+| 🎙️ Voice STT / TTS | ✅ | ✅ |
+| 🔥 One-click hot upgrade (`/bot-upgrade`) | ✅ | ❌ |
+| ⏰ Scheduled push (proactive messages) | ✅ | ✅ |
+| 🔗 URL support | ✅ | ✅ |
+| ⌨️ Typing indicator | ✅ | ✅ |
+| 📝 Markdown | ✅ | ✅ |
+| 🛠️ Slash commands / native commands | ✅ | ✅ |
+| 💬 Quoted context (injected into AI) | ✅ | ✅ |
+| 📦 Large file support (up to 100MB) | ✅ | ❌ |
+| Installation | Requires separate install | Bundled, zero setup |
+| Update cadence | Independent releases, faster iteration | Ships with OpenClaw |
+
+### Which should I pick?
+
+**Choose the OpenClaw built-in plugin if you:**
+
+- Want zero-setup out of the box
+- Are just getting started and want to try QQ Bot quickly
+
+**Choose this plugin (standalone) if you:**
+
+- Want faster feature iteration and more capabilities
+
+> ⚠️ Both plugins cannot run simultaneously. If you've upgraded to OpenClaw 2026.3.31+, run the following command to install this plugin — the built-in version will be disabled automatically:
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
+> ```
+> After upgrading, you'll unlock large file transfers, message reference context, and all other advanced features.
+
+---
+
 ## 📸 Feature Showcase
 
 > **Note:** This plugin serves as a **message channel** only — it relays messages between QQ and OpenClaw. Capabilities like image understanding, voice transcription, drawing, etc. depend on the **AI model** you configure and the **skills** installed in OpenClaw, not on this plugin itself.
@@ -192,6 +231,11 @@ Credentials are automatically backed up before upgrade. Version existence is ver
 
 > ⚠️ Hot upgrade is currently not supported on Windows. Sending `/bot-upgrade` on Windows will return a manual upgrade guide instead.
 
+> ⚠️ v1.6.6 and below do not support hot upgrade via `/bot-upgrade`. Please upgrade using the following command:
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
+> ```
+
 <img width="360" src="docs/images/hot-update.jpg" alt="Hot Upgrade Demo" />
 
 #### `/bot-logs` — Log Export
@@ -252,7 +296,7 @@ curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main
 
 One command does it all: download script → cleanup old plugins → install → configure channel → restart service. Once done, open QQ and start chatting!
 
-> `--appid` and `--secret` are **required for first-time install**. For subsequent upgrades:
+> `--appid` and `--secret` are **required for first-time install**. For subsequent upgrades, run the following command to upgrade to the latest version:
 > ```bash
 > curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
 > ```

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.7`
+### 🚀 当前版本： `v1.7.0`
 
 [![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/)
@@ -40,7 +40,7 @@
 | ⌨️ **输入状态** | 实时显示"Bot 正在输入中…"状态 |
 | 📝 **Markdown** | 完整支持 Markdown 格式消息 |
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
-| 💬 **引用上下文** | 解析 QQ `REFIDX_*` 引用消息，并将引用内容注入 AI 上下文 |
+| 💬 **引用上下文** | 解析用户回复的原始消息内容，注入 AI 上下文，让模型准确理解"在回复哪条消息" |
 | 📦 **大文件支持** | 大文件自动分片并行上传，最大支持 100 MB |
 
 ---
@@ -49,13 +49,9 @@
 
 > **说明：** 本插件仅作为**消息通道**，负责在 QQ 和 OpenClaw 之间传递消息。图片理解、语音转录、AI 画图等能力取决于你配置的 **AI 模型**以及在 OpenClaw 中安装的 **skill**，而非插件本身提供。
 
-### 💬 引用消息上下文（REFIDX）
+### 💬 引用消息上下文
 
-QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返回原始消息全文。插件已支持从本地持久化索引中解析引用内容，并注入 AI 上下文，帮助模型更准确理解“用户引用的是哪条消息”。
-
-- 入站/出站消息中的 `ref_idx` 会自动建立索引。
-- 存储位置：`~/.openclaw/qqbot/data/ref-index.jsonl`（网关重启后仍可恢复）。
-- 引用内容支持文本 + 媒体摘要（图片/语音/视频/文件）。
+用户在 QQ 中引用某条消息发送时，插件会自动解析被引用的消息内容并注入 AI 上下文，让模型清楚地知道"用户在回复哪条消息"，从而给出更准确的回复。支持文本及媒体消息（图片/语音/视频/文件），换设备后同样可用。
 
 <img width="360" src="docs/images/ref-msg.png" alt="引用消息上下文演示" />
 
@@ -187,6 +183,11 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 
 > ⚠️ 热更新指令暂不支持 Windows 系统，在 Windows 上发送 `/bot-upgrade` 会返回手动升级指引。
 
+> ⚠️ v1.6.6 及以下版本暂不支持通过 `/bot-upgrade` 执行热更新，请通过以下命令升级：
+> ```bash
+> curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
+> ```
+
 <img width="360" src="docs/images/hot-update.jpg" alt="一键热更新演示" />
 
 #### `/bot-logs` — 日志导出
@@ -247,7 +248,7 @@ curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main
 
 一行命令搞定：下载脚本 → 清理旧插件 → 安装 → 配置通道 → 启动服务。完成后打开 QQ 即可开始聊天！
 
-> 首次安装**必须**传 `--appid` 和 `--secret`。后续升级如已有配置：
+> 首次安装**必须**传 `--appid` 和 `--secret`。后续升级执行此指令可以升级为最新版：
 > ```bash
 > curl -fsSL https://raw.githubusercontent.com/tencent-connect/openclaw-qqbot/main/scripts/upgrade-via-npm.sh | bash
 > ```

package/dist/src/api.d.ts

@@ -2,6 +2,17 @@
  * QQ Bot API 鉴权和请求封装
  * [修复版] 已重构为支持多实例并发，消除全局变量冲突
  */
+/** API 模块的日志接口，与 GatewayContext.log 对齐 */
+export interface ApiLogger {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+    warn?: (msg: string) => void;
+    debug?: (msg: string) => void;
+}
+/**
+ * 注入自定义 logger（在 gateway 启动时调用，将 api 模块的日志统一接入框架日志系统）
+ */
+export declare function setApiLogger(logger: ApiLogger): void;
 /** API 请求错误，携带 HTTP status code 和业务错误码 */
 export declare class ApiError extends Error {
     readonly status: number;
@@ -16,7 +27,9 @@ export declare class ApiError extends Error {
     /** 回包中的原始 message 字段（用于向用户展示兜底文案） */
     bizMessage?: string | undefined);
 }
-export declare const PLUGIN_USER_AGENT: string;
+/** 由 setQQBotRuntime 调用，将 api.runtime.version 注入到 User-Agent */
+export declare function setOpenClawVersion(version: string): void;
+export declare function getPluginUserAgent(): string;
 /** 出站消息元信息（结构化存储，不做预格式化） */
 export interface OutboundMeta {
     /** 消息文本内容 */
@@ -91,7 +104,7 @@ 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 同源） */
+/** 获取插件版本号（从 package.json 读取，和 getPluginUserAgent() 同源） */
 export declare function getApiPluginVersion(): string;
 export interface MessageResponse {
     id: string;
@@ -269,7 +282,7 @@ export declare function startBackgroundTokenRefresh(appId: string, clientSecret:
  */
 export declare function stopBackgroundTokenRefresh(appId?: string): void;
 export declare function isBackgroundTokenRefreshRunning(appId?: string): boolean;
-import type { StreamMessageRequest, StreamMessageResponse } from "./types.js";
+import type { StreamMessageRequest } from "./types.js";
 /**
  * 发送流式消息（C2C 私聊）
  *
@@ -278,10 +291,13 @@ import type { StreamMessageRequest, StreamMessageResponse } from "./types.js";
  * - 后续分片携带 stream_msg_id 和递增 msg_seq
  * - input_state="1" 表示生成中，"10" 表示生成结束（终结状态）
  *
+ * 仅在终结分片（input_state=DONE）时触发 refIdx 回调，
+ * 中间分片直接调用 apiRequest，避免存入过多无效的中间态数据。
+ *
  * @param accessToken - access_token
  * @param openid - 用户 openid
  * @param req - 流式消息请求体
- * @returns 流式消息响应
+ * @returns 消息响应（复用 MessageResponse，错误会直接抛出异常）
  */
-export declare function sendC2CStreamMessage(accessToken: string, openid: string, req: StreamMessageRequest): Promise<StreamMessageResponse>;
+export declare function sendC2CStreamMessage(accessToken: string, openid: string, req: StreamMessageRequest): Promise<MessageResponse>;
 export {};

package/dist/src/api.js

@@ -5,6 +5,19 @@
 import os from "node:os";
 import { computeFileHash, getCachedFileInfo, setCachedFileInfo } from "./utils/upload-cache.js";
 import { sanitizeFileName } from "./utils/platform.js";
+/** 默认使用 console，外部可通过 setApiLogger 注入框架 log */
+let log = {
+    info: (msg) => console.log(msg),
+    error: (msg) => console.error(msg),
+    warn: (msg) => console.warn(msg),
+    debug: (msg) => console.debug(msg),
+};
+/**
+ * 注入自定义 logger（在 gateway 启动时调用，将 api 模块的日志统一接入框架日志系统）
+ */
+export function setApiLogger(logger) {
+    log = logger;
+}
 // ============ 自定义错误 ============
 /** API 请求错误，携带 HTTP status code 和业务错误码 */
 export class ApiError extends Error {
@@ -28,11 +41,20 @@ export class ApiError extends Error {
 const API_BASE = "https://api.sgroup.qq.com";
 const TOKEN_URL = "https://bots.qq.com/app/getAppAccessToken";
 // ============ Plugin User-Agent ============
-// 格式: QQBotPlugin/{version} (Node/{nodeVersion}; {os})
-// 示例: QQBotPlugin/1.6.0 (Node/22.14.0; darwin)
+// 格式: QQBotPlugin/{version} (Node/{nodeVersion}; {os}; OpenClaw/{openclawVersion})
+// 示例: QQBotPlugin/1.6.0 (Node/22.14.0; darwin; OpenClaw/2026.3.31)
 import { getPackageVersion } from "./utils/pkg-version.js";
 const _pluginVersion = getPackageVersion(import.meta.url);
-export const PLUGIN_USER_AGENT = `QQBotPlugin/${_pluginVersion} (Node/${process.versions.node}; ${os.platform()})`;
+// 初始值为 "unknown"，由 setQQBotRuntime 注入后更新为真实版本
+let _openclawVersion = "unknown";
+/** 由 setQQBotRuntime 调用，将 api.runtime.version 注入到 User-Agent */
+export function setOpenClawVersion(version) {
+    if (version)
+        _openclawVersion = version;
+}
+export function getPluginUserAgent() {
+    return `QQBotPlugin/${_pluginVersion} (Node/${process.versions.node}; ${os.platform()}; OpenClaw/${_openclawVersion})`;
+}
 // 运行时配置
 let currentMarkdownSupport = false;
 let onMessageSentHook = null;
@@ -83,7 +105,7 @@ export async function getAccessToken(appId, clientSecret) {
     // Singleflight: 如果当前 appId 已有进行中的 Token 获取请求，复用它
     let fetchPromise = tokenFetchPromises.get(normalizedAppId);
     if (fetchPromise) {
-        console.log(`[qqbot-api:${normalizedAppId}] Token fetch in progress, waiting for existing request...`);
+        log.info(`[qqbot-api:${normalizedAppId}] Token fetch in progress, waiting for existing request...`);
         return fetchPromise;
     }
     // 创建新的 Token 获取 Promise（singleflight 入口）
@@ -104,9 +126,9 @@ export async function getAccessToken(appId, clientSecret) {
  */
 async function doFetchToken(appId, clientSecret) {
     const requestBody = { appId, clientSecret };
-    const requestHeaders = { "Content-Type": "application/json", "User-Agent": PLUGIN_USER_AGENT };
+    const requestHeaders = { "Content-Type": "application/json", "User-Agent": getPluginUserAgent() };
     // 打印请求信息（隐藏敏感信息）
-    console.log(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL} [secret: ${clientSecret.slice(0, 6)}...len=${clientSecret.length}]`);
+    log.info(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL} [secret: ${clientSecret.slice(0, 6)}...len=${clientSecret.length}]`);
     let response;
     try {
         response = await fetch(TOKEN_URL, {
@@ -116,7 +138,7 @@ async function doFetchToken(appId, clientSecret) {
         });
     }
     catch (err) {
-        console.error(`[qqbot-api:${appId}] <<< Network error:`, err);
+        log.error(`[qqbot-api:${appId}] <<< Network error: ${err}`);
         throw new Error(`Network error getting access_token: ${err instanceof Error ? err.message : String(err)}`);
     }
     // 打印响应头
@@ -125,18 +147,18 @@ async function doFetchToken(appId, clientSecret) {
         responseHeaders[key] = value;
     });
     const tokenTraceId = response.headers.get("x-tps-trace-id") ?? "";
-    console.log(`[qqbot-api:${appId}] <<< Status: ${response.status} ${response.statusText}${tokenTraceId ? ` | TraceId: ${tokenTraceId}` : ""}`);
+    log.info(`[qqbot-api:${appId}] <<< Status: ${response.status} ${response.statusText}${tokenTraceId ? ` | TraceId: ${tokenTraceId}` : ""}`);
     let data;
     let rawBody;
     try {
         rawBody = await response.text();
         // 隐藏 token 值
         const logBody = rawBody.replace(/"access_token"\s*:\s*"[^"]+"/g, '"access_token": "***"');
-        console.log(`[qqbot-api:${appId}] <<< Body:`, logBody);
+        log.info(`[qqbot-api:${appId}] <<< Body: ${logBody}`);
         data = JSON.parse(rawBody);
     }
     catch (err) {
-        console.error(`[qqbot-api:${appId}] <<< Parse error:`, err);
+        log.error(`[qqbot-api:${appId}] <<< Parse error: ${err}`);
         throw new Error(`Failed to parse access_token response: ${err instanceof Error ? err.message : String(err)}`);
     }
     if (!data.access_token) {
@@ -148,7 +170,7 @@ async function doFetchToken(appId, clientSecret) {
         expiresAt,
         appId,
     });
-    console.log(`[qqbot-api:${appId}] Token cached, expires at: ${new Date(expiresAt).toISOString()}`);
+    log.info(`[qqbot-api:${appId}] Token cached, expires at: ${new Date(expiresAt).toISOString()}`);
     return data.access_token;
 }
 /**
@@ -159,11 +181,11 @@ export function clearTokenCache(appId) {
     if (appId) {
         const normalizedAppId = String(appId).trim();
         tokenCacheMap.delete(normalizedAppId);
-        console.log(`[qqbot-api:${normalizedAppId}] Token cache cleared manually.`);
+        log.info(`[qqbot-api:${normalizedAppId}] Token cache cleared manually.`);
     }
     else {
         tokenCacheMap.clear();
-        console.log(`[qqbot-api] All token caches cleared.`);
+        log.info(`[qqbot-api] All token caches cleared.`);
     }
 }
 /**
@@ -198,10 +220,11 @@ const FILE_UPLOAD_TIMEOUT = 120000; // 文件上传 120 秒
  */
 export async function apiRequest(accessToken, method, path, body, timeoutMs) {
     const url = `${API_BASE}${path}`;
+    const reqTs = Date.now(); // 毫秒时间戳，用于关联同一次请求的所有日志
     const headers = {
         Authorization: `QQBot ${accessToken}`,
         "Content-Type": "application/json",
-        "User-Agent": PLUGIN_USER_AGENT,
+        "User-Agent": getPluginUserAgent(),
     };
     const isFileUpload = path.includes("/files");
     const timeout = timeoutMs ?? (isFileUpload ? FILE_UPLOAD_TIMEOUT : DEFAULT_API_TIMEOUT);
@@ -218,13 +241,13 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
         options.body = JSON.stringify(body);
     }
     // 打印请求信息
-    console.log(`[qqbot-api] >>> ${method} ${url} (timeout: ${timeout}ms)`);
+    log.info(`[qqbot-api][${reqTs}] >>> ${method} ${url} (timeout: ${timeout}ms)`);
     if (body) {
         const logBody = { ...body };
         if (typeof logBody.file_data === "string") {
             logBody.file_data = `<base64 ${logBody.file_data.length} chars>`;
         }
-        console.log(`[qqbot-api] >>> Body:`, JSON.stringify(logBody));
+        log.info(`[qqbot-api][${reqTs}] >>> Body: ${JSON.stringify(logBody)}`);
     }
     let res;
     try {
@@ -233,10 +256,10 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
     catch (err) {
         clearTimeout(timeoutId);
         if (err instanceof Error && err.name === "AbortError") {
-            console.error(`[qqbot-api] <<< Request timeout after ${timeout}ms`);
+            log.error(`[qqbot-api][${reqTs}] <<< Request timeout after ${timeout}ms`);
             throw new Error(`Request timeout[${path}]: exceeded ${timeout}ms`);
         }
-        console.error(`[qqbot-api] <<< Network error:`, err);
+        log.error(`[qqbot-api][${reqTs}] <<< Network error: ${err}`);
         throw new Error(`Network error [${path}]: ${err instanceof Error ? err.message : String(err)}`);
     }
     finally {
@@ -247,7 +270,7 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
         responseHeaders[key] = value;
     });
     const traceId = res.headers.get("x-tps-trace-id") ?? "";
-    console.log(`[qqbot-api] <<< Status: ${res.status} ${res.statusText}${traceId ? ` | TraceId: ${traceId}` : ""}`);
+    log.info(`[qqbot-api][${reqTs}] <<< Status: ${res.status} ${res.statusText}${traceId ? ` | TraceId: ${traceId}` : ""}`);
     let rawBody;
     try {
         rawBody = await res.text();
@@ -255,7 +278,7 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
     catch (err) {
         throw new Error(`读取响应失败[${path}]: ${err instanceof Error ? err.message : String(err)}`);
     }
-    console.log(`[qqbot-api] <<< Body:`, rawBody);
+    log.info(`[qqbot-api][${reqTs}] <<< Body: ${rawBody}`);
     // 检测非 JSON 响应（HTML 网关错误页 / CDN 限流页等）
     const contentType = res.headers.get("content-type") ?? "";
     const isHtmlResponse = contentType.includes("text/html") || rawBody.trimStart().startsWith("<");
@@ -283,13 +306,13 @@ export async function apiRequest(accessToken, method, path, body, timeoutMs) {
     }
     // 成功响应但不是 JSON（极端异常情况）
     if (isHtmlResponse) {
-        throw new Error(`QQ 服务端返回了非 JSON 响应（${path}），可能是临时故障，请稍后重试`);
+        throw new ApiError(`QQ 服务端返回了非 JSON 响应（${path}），可能是临时故障，请稍后重试`, res.status, path);
     }
     try {
         return JSON.parse(rawBody);
     }
     catch {
-        throw new Error(`开放平台响应格式异常（${path}），请稍后重试`);
+        throw new ApiError(`开放平台响应格式异常（${path}），请稍后重试`, res.status, path);
     }
 }
 // ============ 上传重试（指数退避） ============
@@ -310,7 +333,7 @@ async function apiRequestWithRetry(accessToken, method, path, body, maxRetries =
             }
             if (attempt < maxRetries) {
                 const delay = UPLOAD_BASE_DELAY_MS * Math.pow(2, attempt);
-                console.log(`[qqbot-api] Upload attempt ${attempt + 1} failed, retrying in ${delay}ms: ${errMsg.slice(0, 100)}`);
+                log.info(`[qqbot-api] Upload attempt ${attempt + 1} failed, retrying in ${delay}ms: ${errMsg.slice(0, 100)}`);
                 await new Promise(resolve => setTimeout(resolve, delay));
             }
         }
@@ -334,7 +357,7 @@ async function completeUploadWithRetry(accessToken, method, path, body) {
             lastError = err instanceof Error ? err : new Error(String(err));
             if (attempt < COMPLETE_UPLOAD_MAX_RETRIES) {
                 const delay = COMPLETE_UPLOAD_BASE_DELAY_MS * Math.pow(2, attempt);
-                console.warn(`[qqbot-api] CompleteUpload attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 200)}`);
+                (log.warn ?? log.error)(`[qqbot-api] CompleteUpload attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 200)}`);
                 await new Promise(resolve => setTimeout(resolve, delay));
             }
         }
@@ -397,13 +420,13 @@ async function partFinishWithRetry(accessToken, method, path, body, retryTimeout
             // 命中特定错误码 → 进入持续重试模式
             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)...`);
+                (log.warn ?? log.error)(`[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)}`);
+                (log.warn ?? log.error)(`[qqbot-api] PartFinish attempt ${attempt + 1} failed, retrying in ${delay}ms: ${lastError.message.slice(0, 200)}`);
                 await new Promise(resolve => setTimeout(resolve, delay));
             }
         }
@@ -421,14 +444,14 @@ async function partFinishPersistentRetry(accessToken, method, path, body, timeou
     while (Date.now() < deadline) {
         try {
             await apiRequest(accessToken, method, path, body);
-            console.log(`[qqbot-api] PartFinish persistent retry succeeded after ${attempt} retries`);
+            log.info(`[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`);
+                log.error(`[qqbot-api] PartFinish persistent retry: error is no longer retryable (bizCode=${err.bizCode ?? "N/A"}), aborting`);
                 throw lastError;
             }
             attempt++;
@@ -436,12 +459,12 @@ async function partFinishPersistentRetry(accessToken, method, path, body, timeou
             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)`);
+            (log.warn ?? log.error)(`[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)`);
+    log.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) {
@@ -452,7 +475,7 @@ export async function getGatewayUrl(accessToken) {
 export async function acknowledgeInteraction(accessToken, interactionId, code = 0, data) {
     await apiRequest(accessToken, "PUT", `/interactions/${interactionId}`, { code, ...(data ? { data } : {}) });
 }
-/** 获取插件版本号（从 package.json 读取，和 PLUGIN_USER_AGENT 同源） */
+/** 获取插件版本号（从 package.json 读取，和 getPluginUserAgent() 同源） */
 export function getApiPluginVersion() {
     return _pluginVersion;
 }
@@ -467,7 +490,7 @@ async function sendAndNotify(accessToken, method, path, body, meta) {
             onMessageSentHook(result.ext_info.ref_idx, meta);
         }
         catch (err) {
-            console.error(`[qqbot-api] onMessageSent hook error: ${err}`);
+            log.error(`[qqbot-api] onMessageSent hook error: ${err}`);
         }
     }
     return result;
@@ -755,15 +778,15 @@ export async function sendGroupVideoMessage(accessToken, groupOpenid, videoUrl,
 const backgroundRefreshControllers = new Map();
 export function startBackgroundTokenRefresh(appId, clientSecret, options) {
     if (backgroundRefreshControllers.has(appId)) {
-        console.log(`[qqbot-api:${appId}] Background token refresh already running`);
+        log.info(`[qqbot-api:${appId}] Background token refresh already running`);
         return;
     }
-    const { refreshAheadMs = 5 * 60 * 1000, randomOffsetMs = 30 * 1000, minRefreshIntervalMs = 60 * 1000, retryDelayMs = 5 * 1000, log, } = options ?? {};
+    const { refreshAheadMs = 5 * 60 * 1000, randomOffsetMs = 30 * 1000, minRefreshIntervalMs = 60 * 1000, retryDelayMs = 5 * 1000, log: refreshLog, } = options ?? {};
     const controller = new AbortController();
     backgroundRefreshControllers.set(appId, controller);
     const signal = controller.signal;
     const refreshLoop = async () => {
-        log?.info?.(`[qqbot-api:${appId}] Background token refresh started`);
+        refreshLog?.info?.(`[qqbot-api:${appId}] Background token refresh started`);
         while (!signal.aborted) {
             try {
                 await getAccessToken(appId, clientSecret);
@@ -772,27 +795,27 @@ export function startBackgroundTokenRefresh(appId, clientSecret, options) {
                     const expiresIn = cached.expiresAt - Date.now();
                     const randomOffset = Math.random() * randomOffsetMs;
                     const refreshIn = Math.max(expiresIn - refreshAheadMs - randomOffset, minRefreshIntervalMs);
-                    log?.debug?.(`[qqbot-api:${appId}] Token valid, next refresh in ${Math.round(refreshIn / 1000)}s`);
+                    refreshLog?.debug?.(`[qqbot-api:${appId}] Token valid, next refresh in ${Math.round(refreshIn / 1000)}s`);
                     await sleep(refreshIn, signal);
                 }
                 else {
-                    log?.debug?.(`[qqbot-api:${appId}] No cached token, retrying soon`);
+                    refreshLog?.debug?.(`[qqbot-api:${appId}] No cached token, retrying soon`);
                     await sleep(minRefreshIntervalMs, signal);
                 }
             }
             catch (err) {
                 if (signal.aborted)
                     break;
-                log?.error?.(`[qqbot-api:${appId}] Background token refresh failed: ${err}`);
+                refreshLog?.error?.(`[qqbot-api:${appId}] Background token refresh failed: ${err}`);
                 await sleep(retryDelayMs, signal);
             }
         }
         backgroundRefreshControllers.delete(appId);
-        log?.info?.(`[qqbot-api:${appId}] Background token refresh stopped`);
+        refreshLog?.info?.(`[qqbot-api:${appId}] Background token refresh stopped`);
     };
     refreshLoop().catch((err) => {
         backgroundRefreshControllers.delete(appId);
-        log?.error?.(`[qqbot-api:${appId}] Background token refresh crashed: ${err}`);
+        refreshLog?.error?.(`[qqbot-api:${appId}] Background token refresh crashed: ${err}`);
     });
 }
 /**
@@ -844,10 +867,13 @@ async function sleep(ms, signal) {
  * - 后续分片携带 stream_msg_id 和递增 msg_seq
  * - input_state="1" 表示生成中，"10" 表示生成结束（终结状态）
  *
+ * 仅在终结分片（input_state=DONE）时触发 refIdx 回调，
+ * 中间分片直接调用 apiRequest，避免存入过多无效的中间态数据。
+ *
  * @param accessToken - access_token
  * @param openid - 用户 openid
  * @param req - 流式消息请求体
- * @returns 流式消息响应
+ * @returns 消息响应（复用 MessageResponse，错误会直接抛出异常）
  */
 export async function sendC2CStreamMessage(accessToken, openid, req) {
     const path = `/v2/users/${openid}/stream_messages`;

package/dist/src/channel.js

@@ -1,6 +1,6 @@
 import { applyAccountNameToChannelSection, deleteAccountFromConfigSection, setAccountEnabledInConfigSection, } from "openclaw/plugin-sdk/core";
 import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount, applyQQBotAccountConfig, resolveDefaultQQBotAccountId, resolveRequireMention, resolveToolPolicy, resolveGroupConfig } from "./config.js";
-import { sendText, sendMedia } from "./outbound.js";
+import { sendText, sendMedia, resolveUserFacingMediaError } from "./outbound.js";
 import { startGateway } from "./gateway.js";
 import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
@@ -17,6 +17,16 @@ export function chunkText(text, limit) {
     const runtime = getQQBotRuntime();
     return runtime.channel.text.chunkMarkdownText(text, limit);
 }
+function buildChannelMediaError(result) {
+    const err = new Error(resolveUserFacingMediaError(result));
+    if (result.errorCode) {
+        err.code = result.errorCode;
+    }
+    if (result.qqBizCode !== undefined) {
+        err.qqBizCode = result.qqBizCode;
+    }
+    return err;
+}
 export const qqbotPlugin = {
     id: "qqbot",
     meta: {
@@ -264,18 +274,12 @@ export const qqbotPlugin = {
             const result = await sendMedia({ to, text: text ?? "", mediaUrl: mediaUrl ?? "", accountId, replyToId, account });
             console.log(`[qqbot:channel] sendMedia result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
             // 此 sendMedia 是框架 Channel Plugin 的标准出站接口，
-            // 用于非 gateway deliver 场景（如 API 直接发送、cron 等）。
-            // gateway 消息响应走的是 deliver 回调 → sendPlainReply，不经过此处。
-            // 框架拿到 error 后不一定会给用户发文字兜底，所以这里主动发一条。
+            // 由框架 deliver.js (deliverOutboundPayloads) 或 message-actions 调用。
+            // 当 throw Error 后，框架 pi-tool-definition-adapter 会将错误转化为
+            // tool 的 { status: "error" } 返回给 AI 模型，模型会自行生成错误回复给用户。
+            // 因此此处不应主动发送兜底文本，否则会与模型的回复重复。
             if (result.error) {
-                try {
-                    const fallbackResult = await sendText({ to, text: result.error, accountId, replyToId, account });
-                    console.log(`[qqbot:channel] sendMedia fallback text sent: messageId=${fallbackResult.messageId}, error=${fallbackResult.error ?? "none"}`);
-                }
-                catch (fallbackErr) {
-                    console.error(`[qqbot:channel] sendMedia fallback text failed: ${fallbackErr}`);
-                }
-                throw new Error(result.error);
+                throw buildChannelMediaError(result);
             }
             return {
                 channel: "qqbot",