@tencent-connect/openclaw-qqbot 1.6.2-alpha.0 → 1.6.2-alpha.2

package/dist/src/channel.js

@@ -52,7 +52,7 @@ export const qqbotPlugin = {
          * blockStreaming: true 表示该 Channel 支持块流式
          * 框架会收集流式响应，然后通过 deliver 回调发送
          */
-        blockStreaming: true,
+        blockStreaming: false,
     },
     reload: { configPrefixes: ["channels.qqbot"] },
     // CLI onboarding wizard

package/dist/src/gateway.js

@@ -7,7 +7,7 @@ import { recordKnownUser, flushKnownUsers, listKnownUsers } from "./known-users.
 import { getQQBotRuntime } from "./runtime.js";
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, flushRefIndex } from "./ref-index-store.js";
 import { matchSlashCommand, getPluginVersion } from "./slash-commands.js";
-import { triggerUpdateCheck } from "./update-checker.js";
+import { triggerUpdateCheck, onUpdateFound, formatUpdateNotice } from "./update-checker.js";
 import { startImageServer, isImageServerRunning, downloadFile } from "./image-server.js";
 import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize } from "./utils/image-size.js";
 import { parseQQBotPayload, encodePayloadForCron, isCronReminderPayload, isMediaPayload } from "./utils/payload.js";
@@ -15,7 +15,7 @@ import { convertSilkToWav, isVoiceAttachment, formatDuration, resolveTTSConfig,
 import { normalizeMediaTags } from "./utils/media-tags.js";
 import { checkFileSize, readFileAsync, fileExistsAsync, formatFileSize } from "./utils/file-utils.js";
 import { getQQBotDataDir, isLocalPath as isLocalFilePath, normalizePath, sanitizeFileName, runDiagnostics } from "./utils/platform.js";
-import { MSG, formatMediaErrorMessage } from "./user-messages.js";
+import { MSG } from "./user-messages.js";
 import { sendPhoto, sendVoice, sendVideoMsg, sendDocument, sendMedia as sendMediaAuto } from "./outbound.js";
 function resolveSTTConfig(cfg) {
     const c = cfg;
@@ -172,7 +172,6 @@ function parseFaceTags(text) {
         }
     });
 }
-// formatMediaErrorMessage 已移至 user-messages.ts 集中管理
 // ============ 内部标记过滤 ============
 /**
  * 过滤内部标记（如 [[reply_to: xxx]]）
@@ -315,8 +314,36 @@ export async function startGateway(ctx) {
             log?.info(`[qqbot:${account.accountId}] ${w}`);
         }
     }
-    // 后台版本检查（供 /qqbot-version、/qqbot-upgrade 指令被动查询）
+    // 后台版本检查（detached 子进程，零阻塞）
     triggerUpdateCheck(log);
+    // 注册新版本通知回调：仅发给管理员，带防抖
+    let lastUpdateNotifyAt = 0;
+    const UPDATE_NOTIFY_DEBOUNCE_MS = 5 * 60 * 1000; // 5 分钟内不重复通知
+    onUpdateFound(async (info) => {
+        try {
+            // 防抖：避免短时间内重复推送
+            const now = Date.now();
+            if (now - lastUpdateNotifyAt < UPDATE_NOTIFY_DEBOUNCE_MS) {
+                log?.debug?.(`[qqbot:${account.accountId}] Update notification debounced`);
+                return;
+            }
+            const notice = formatUpdateNotice(info);
+            if (!notice)
+                return;
+            const adminId = resolveAdminOpenId();
+            if (!adminId) {
+                log?.debug?.(`[qqbot:${account.accountId}] No admin or known user to send update notification`);
+                return;
+            }
+            const token = await getAccessToken(account.appId, account.clientSecret);
+            await sendProactiveC2CMessage(token, adminId, notice);
+            lastUpdateNotifyAt = Date.now();
+            log?.info(`[qqbot:${account.accountId}] Sent update notification to admin: ${adminId}`);
+        }
+        catch (err) {
+            log?.debug?.(`[qqbot:${account.accountId}] Failed to send update notification to admin: ${err}`);
+        }
+    });
     // 初始化 API 配置（markdown 支持）
     initApiConfig({
         markdownSupport: account.markdownSupport,
@@ -1502,7 +1529,6 @@ export async function startGateway(ctx) {
                                             const result = await sendPhoto(mediaTarget, item.content);
                                             if (result.error) {
                                                 log?.error(`[qqbot:${account.accountId}] sendPhoto error: ${result.error}`);
-                                                await sendErrorMessage(formatMediaErrorMessage("图片", new Error(result.error)));
                                             }
                                         }
                                         else if (item.type === "voice") {
@@ -1517,26 +1543,22 @@ export async function startGateway(ctx) {
                                                 ]);
                                                 if (result.error) {
                                                     log?.error(`[qqbot:${account.accountId}] sendVoice error: ${result.error}`);
-                                                    await sendErrorMessage(formatMediaErrorMessage("语音", new Error(result.error)));
                                                 }
                                             }
                                             catch (err) {
                                                 log?.error(`[qqbot:${account.accountId}] sendVoice unexpected error: ${err}`);
-                                                await sendErrorMessage(formatMediaErrorMessage("语音", err));
                                             }
                                         }
                                         else if (item.type === "video") {
                                             const result = await sendVideoMsg(mediaTarget, item.content);
                                             if (result.error) {
                                                 log?.error(`[qqbot:${account.accountId}] sendVideoMsg error: ${result.error}`);
-                                                await sendErrorMessage(formatMediaErrorMessage("视频", new Error(result.error)));
                                             }
                                         }
                                         else if (item.type === "file") {
                                             const result = await sendDocument(mediaTarget, item.content);
                                             if (result.error) {
                                                 log?.error(`[qqbot:${account.accountId}] sendDocument error: ${result.error}`);
-                                                await sendErrorMessage(formatMediaErrorMessage("文件", new Error(result.error)));
                                             }
                                         }
                                         else if (item.type === "media") {
@@ -1551,7 +1573,6 @@ export async function startGateway(ctx) {
                                             });
                                             if (result.error) {
                                                 log?.error(`[qqbot:${account.accountId}] sendMedia(auto) error: ${result.error}`);
-                                                await sendErrorMessage(formatMediaErrorMessage("媒体", new Error(result.error)));
                                             }
                                         }
                                     }
@@ -1620,12 +1641,12 @@ export async function startGateway(ctx) {
                                                 if (parsedPayload.source === "file") {
                                                     try {
                                                         if (!(await fileExistsAsync(imageUrl))) {
-                                                            await sendErrorMessage(MSG.IMAGE_NOT_FOUND);
+                                                            log?.error(`[qqbot:${account.accountId}] Image not found: ${imageUrl}`);
                                                             return;
                                                         }
                                                         const imgSzCheck = checkFileSize(imageUrl);
                                                         if (!imgSzCheck.ok) {
-                                                            await sendErrorMessage(MSG.IMAGE_SEND_FAILED);
+                                                            log?.error(`[qqbot:${account.accountId}] Image size check failed: ${imgSzCheck.error}`);
                                                             return;
                                                         }
                                                         const fileBuffer = await readFileAsync(imageUrl);
@@ -1649,7 +1670,6 @@ export async function startGateway(ctx) {
                                                     }
                                                     catch (readErr) {
                                                         log?.error(`[qqbot:${account.accountId}] Failed to read local image: ${readErr}`);
-                                                        await sendErrorMessage(MSG.IMAGE_SEND_FAILED);
                                                         return;
                                                     }
                                                 }
@@ -1685,7 +1705,6 @@ export async function startGateway(ctx) {
                                                 }
                                                 catch (err) {
                                                     log?.error(`[qqbot:${account.accountId}] Failed to send image: ${err}`);
-                                                    await sendErrorMessage(formatMediaErrorMessage("图片", err));
                                                 }
                                             }
                                             else if (parsedPayload.mediaType === "audio") {
@@ -1699,7 +1718,6 @@ export async function startGateway(ctx) {
                                                         const ttsCfg = resolveTTSConfig(cfg);
                                                         if (!ttsCfg) {
                                                             log?.error(`[qqbot:${account.accountId}] TTS not configured (channels.qqbot.tts in openclaw.json)`);
-                                                            await sendErrorMessage(MSG.VOICE_NOT_AVAILABLE);
                                                         }
                                                         else {
                                                             log?.info(`[qqbot:${account.accountId}] TTS: "${ttsText.slice(0, 50)}..." via ${ttsCfg.model}`);
@@ -1723,7 +1741,6 @@ export async function startGateway(ctx) {
                                                 }
                                                 catch (err) {
                                                     log?.error(`[qqbot:${account.accountId}] TTS/voice send failed: ${err}`);
-                                                    await sendErrorMessage(formatMediaErrorMessage("语音", err));
                                                 }
                                             }
                                             else if (parsedPayload.mediaType === "video") {
@@ -1791,7 +1808,6 @@ export async function startGateway(ctx) {
                                                 }
                                                 catch (err) {
                                                     log?.error(`[qqbot:${account.accountId}] Video send failed: ${err}`);
-                                                    await sendErrorMessage(formatMediaErrorMessage("视频", err));
                                                 }
                                             }
                                             else if (parsedPayload.mediaType === "file") {
@@ -1843,7 +1859,6 @@ export async function startGateway(ctx) {
                                                 }
                                                 catch (err) {
                                                     log?.error(`[qqbot:${account.accountId}] File send failed: ${err}`);
-                                                    await sendErrorMessage(formatMediaErrorMessage("文件", err));
                                                 }
                                             }
                                             else {
@@ -2196,10 +2211,10 @@ export async function startGateway(ctx) {
                                 // 发送错误提示给用户，显示完整错误信息
                                 const errMsg = String(err);
                                 if (errMsg.includes("401") || errMsg.includes("key") || errMsg.includes("auth")) {
-                                    await sendErrorMessage(MSG.AI_AUTH_ERROR);
+                                    log?.error(`[qqbot:${account.accountId}] AI auth error: ${errMsg}`);
                                 }
                                 else {
-                                    await sendErrorMessage(MSG.AI_PROCESS_ERROR);
+                                    log?.error(`[qqbot:${account.accountId}] AI process error: ${errMsg}`);
                                 }
                             },
                         },
@@ -2217,7 +2232,6 @@ export async function startGateway(ctx) {
                         }
                         if (!hasResponse) {
                             log?.error(`[qqbot:${account.accountId}] No response within timeout`);
-                            await sendErrorMessage(MSG.TIMEOUT_HINT);
                         }
                     }
                     finally {
@@ -2236,7 +2250,6 @@ export async function startGateway(ctx) {
                 }
                 catch (err) {
                     log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
-                    await sendErrorMessage(MSG.GENERIC_ERROR);
                 }
             };
             ws.on("open", () => {

package/dist/src/outbound.js

@@ -208,7 +208,7 @@ export async function sendPhoto(ctx, imagePath) {
     let imageUrl = mediaPath;
     if (isLocal) {
         if (!(await fileExistsAsync(mediaPath))) {
-            return { channel: "qqbot", error: MSG.IMAGE_NOT_FOUND };
+            return { channel: "qqbot", error: "图片不存在或已失效" };
         }
         const sizeCheck = checkFileSize(mediaPath);
         if (!sizeCheck.ok) {
@@ -345,7 +345,7 @@ async function sendVoiceFromLocal(ctx, mediaPath, directUploadFormats, transcode
     // 等待文件就绪（TTS 异步生成，文件可能还没写完）
     const fileSize = await waitForFile(mediaPath);
     if (fileSize === 0) {
-        return { channel: "qqbot", error: MSG.VOICE_GENERATE_FAILED };
+        return { channel: "qqbot", error: "语音文件未就绪" };
     }
     // 精细检测：是否需要转码
     const needsTranscode = shouldTranscodeVoice(mediaPath);
@@ -441,7 +441,7 @@ export async function sendVideoMsg(ctx, videoPath) {
 /** 从本地文件发送视频（sendVideoMsg 的内部辅助） */
 async function sendVideoFromLocal(ctx, mediaPath, prefix) {
     if (!(await fileExistsAsync(mediaPath))) {
-        return { channel: "qqbot", error: MSG.VIDEO_NOT_FOUND };
+        return { channel: "qqbot", error: "视频文件不存在或已失效" };
     }
     const sizeCheck = checkFileSize(mediaPath);
     if (!sizeCheck.ok) {
@@ -528,7 +528,7 @@ export async function sendDocument(ctx, filePath) {
 async function sendDocumentFromLocal(ctx, mediaPath, prefix) {
     const fileName = sanitizeFileName(path.basename(mediaPath));
     if (!(await fileExistsAsync(mediaPath))) {
-        return { channel: "qqbot", error: MSG.FILE_NOT_FOUND };
+        return { channel: "qqbot", error: "文件不存在或已失效" };
     }
     const sizeCheck = checkFileSize(mediaPath);
     if (!sizeCheck.ok) {

package/dist/src/update-checker.d.ts

@@ -12,9 +12,16 @@ export interface UpdateInfo {
     checkedAt: number;
     error?: string;
 }
+type UpdateFoundCallback = (info: UpdateInfo) => void;
+/**
+ * 注册新版本发现回调（仅在首次检测到某个新版本时触发一次）
+ */
+export declare function onUpdateFound(cb: UpdateFoundCallback): void;
 export declare function triggerUpdateCheck(log?: {
     info: (msg: string) => void;
     error: (msg: string) => void;
     debug?: (msg: string) => void;
 }): void;
 export declare function getUpdateInfo(): UpdateInfo;
+export declare function formatUpdateNotice(info: UpdateInfo): string;
+export {};

package/dist/src/update-checker.js

@@ -24,6 +24,15 @@ let _lastInfo = {
     checkedAt: 0,
 };
 let _checking = false;
+/** 已通知过的版本号，避免同一版本重复推送 */
+let _notifiedVersion = null;
+let _onUpdateFound = null;
+/**
+ * 注册新版本发现回调（仅在首次检测到某个新版本时触发一次）
+ */
+export function onUpdateFound(cb) {
+    _onUpdateFound = cb;
+}
 export function triggerUpdateCheck(log) {
     if (_checking)
         return;
@@ -55,6 +64,11 @@ export function triggerUpdateCheck(log) {
             _lastInfo = { current: CURRENT_VERSION, latest: compareTarget, hasUpdate, checkedAt: now };
             if (hasUpdate) {
                 log?.info?.(`[qqbot:update-checker] new version available: ${compareTarget} (current: ${CURRENT_VERSION})`);
+                // 首次发现该版本时触发回调
+                if (_onUpdateFound && compareTarget !== _notifiedVersion) {
+                    _notifiedVersion = compareTarget;
+                    _onUpdateFound(_lastInfo);
+                }
             }
         }
         catch (parseErr) {
@@ -65,6 +79,11 @@ export function triggerUpdateCheck(log) {
 export function getUpdateInfo() {
     return { ..._lastInfo };
 }
+export function formatUpdateNotice(info) {
+    if (!info.hasUpdate || !info.latest)
+        return "";
+    return `\u{1f195} 有新版本可用: v${info.latest}（当前 v${info.current}）\n使用 /qqbot-upgrade 升级`;
+}
 function compareVersions(a, b) {
     const parse = (v) => {
         const clean = v.replace(/^v/, "");

package/dist/src/user-messages.d.ts

@@ -1,43 +1,16 @@
 /**
  * 用户面向的提示文案集中管理
- *
- * 设计原则（参考 Telegram / Discord / Slack / 飞书）：
- * 1. 禁止暴露服务器路径、原始 Error、配置文件结构
- * 2. 错误信息分级：用户只看到通用友好文案，技术细节走日志
- * 3. 统一风格：去掉 [QQBot] 前缀和 [方括号] 格式
- * 4. 所有面向用户的文案集中在此文件，便于维护和国际化
+ * 仅保留格式校验类提示，运行时错误走日志不面向用户
  */
 export declare const MSG: {
-    readonly GENERIC_ERROR: "抱歉，处理消息时遇到了问题，请稍后再试～";
-    readonly AI_AUTH_ERROR: "抱歉，AI 服务暂时不可用，请联系管理员检查配置～";
-    readonly AI_PROCESS_ERROR: "抱歉，AI 处理遇到了问题，请稍后再试～";
-    readonly TIMEOUT_HINT: "已收到消息，正在处理中…";
-    readonly IMAGE_NOT_FOUND: "抱歉，图片不存在或已失效，无法发送～";
     readonly IMAGE_FORMAT_UNSUPPORTED: (ext: string) => string;
-    readonly IMAGE_SEND_FAILED: "抱歉，图片发送失败了，请稍后再试～";
-    readonly IMAGE_UPLOADING: (size: string) => string;
-    readonly VOICE_GENERATE_FAILED: "抱歉，语音生成失败，请稍后重试～";
-    readonly VOICE_CONVERT_FAILED: "抱歉，语音格式转换失败，请稍后重试～";
-    readonly VOICE_SEND_FAILED: "抱歉，语音发送失败了，请稍后再试～";
-    readonly VOICE_NOT_AVAILABLE: "抱歉，语音功能暂未开启～";
-    readonly VOICE_MISSING_TEXT: "抱歉，语音消息缺少内容～";
     readonly VOICE_CHANNEL_UNSUPPORTED: "抱歉，语音消息暂不支持在频道中发送～";
-    readonly VIDEO_NOT_FOUND: "抱歉，视频文件不存在或已失效，无法发送～";
-    readonly VIDEO_SEND_FAILED: "抱歉，视频发送失败了，请稍后再试～";
-    readonly VIDEO_MISSING_PATH: "抱歉，视频消息缺少内容～";
     readonly VIDEO_CHANNEL_UNSUPPORTED: "抱歉，视频消息暂不支持在频道中发送～";
-    readonly VIDEO_UPLOADING: (size: string) => string;
-    readonly FILE_NOT_FOUND: "抱歉，文件不存在或已失效，无法发送～";
-    readonly FILE_SEND_FAILED: "抱歉，文件发送失败了，请稍后再试～";
-    readonly FILE_MISSING_PATH: "抱歉，文件消息缺少内容～";
     readonly FILE_CHANNEL_UNSUPPORTED: "抱歉，文件消息暂不支持在频道中发送～";
-    readonly FILE_UPLOADING: (name: string, size: string) => string;
+    readonly VOICE_MISSING_TEXT: "抱歉，语音消息缺少内容～";
+    readonly VIDEO_MISSING_PATH: "抱歉，视频消息缺少内容～";
+    readonly FILE_MISSING_PATH: "抱歉，文件消息缺少内容～";
     readonly PAYLOAD_PARSE_ERROR: "抱歉，消息格式异常，无法处理～";
     readonly UNSUPPORTED_MEDIA_TYPE: "抱歉，暂不支持该媒体类型～";
     readonly UNSUPPORTED_PAYLOAD_TYPE: "抱歉，暂不支持该消息类型～";
 };
-/**
- * 将媒体上传/发送错误转为对用户友好的提示文案
- * 技术细节不暴露给用户，仅记录到日志
- */
-export declare function formatMediaErrorMessage(mediaType: string, err: unknown): string;

package/dist/src/user-messages.js

@@ -1,65 +1,20 @@
 /**
  * 用户面向的提示文案集中管理
- *
- * 设计原则（参考 Telegram / Discord / Slack / 飞书）：
- * 1. 禁止暴露服务器路径、原始 Error、配置文件结构
- * 2. 错误信息分级：用户只看到通用友好文案，技术细节走日志
- * 3. 统一风格：去掉 [QQBot] 前缀和 [方括号] 格式
- * 4. 所有面向用户的文案集中在此文件，便于维护和国际化
+ * 仅保留格式校验类提示，运行时错误走日志不面向用户
  */
-// ============ 媒体发送错误 ============
 export const MSG = {
-    // 通用错误
-    GENERIC_ERROR: "抱歉，处理消息时遇到了问题，请稍后再试～",
-    AI_AUTH_ERROR: "抱歉，AI 服务暂时不可用，请联系管理员检查配置～",
-    AI_PROCESS_ERROR: "抱歉，AI 处理遇到了问题，请稍后再试～",
-    TIMEOUT_HINT: "已收到消息，正在处理中…",
-    // 图片
-    IMAGE_NOT_FOUND: "抱歉，图片不存在或已失效，无法发送～",
+    // 图片格式校验
     IMAGE_FORMAT_UNSUPPORTED: (ext) => `抱歉，暂不支持 ${ext} 格式的图片～`,
-    IMAGE_SEND_FAILED: "抱歉，图片发送失败了，请稍后再试～",
-    IMAGE_UPLOADING: (size) => `正在上传图片 (${size})...`,
-    // 语音
-    VOICE_GENERATE_FAILED: "抱歉，语音生成失败，请稍后重试～",
-    VOICE_CONVERT_FAILED: "抱歉，语音格式转换失败，请稍后重试～",
-    VOICE_SEND_FAILED: "抱歉，语音发送失败了，请稍后再试～",
-    VOICE_NOT_AVAILABLE: "抱歉，语音功能暂未开启～",
-    VOICE_MISSING_TEXT: "抱歉，语音消息缺少内容～",
+    // 频道不支持的媒体类型
     VOICE_CHANNEL_UNSUPPORTED: "抱歉，语音消息暂不支持在频道中发送～",
-    // 视频
-    VIDEO_NOT_FOUND: "抱歉，视频文件不存在或已失效，无法发送～",
-    VIDEO_SEND_FAILED: "抱歉，视频发送失败了，请稍后再试～",
-    VIDEO_MISSING_PATH: "抱歉，视频消息缺少内容～",
     VIDEO_CHANNEL_UNSUPPORTED: "抱歉，视频消息暂不支持在频道中发送～",
-    VIDEO_UPLOADING: (size) => `正在上传视频 (${size})...`,
-    // 文件
-    FILE_NOT_FOUND: "抱歉，文件不存在或已失效，无法发送～",
-    FILE_SEND_FAILED: "抱歉，文件发送失败了，请稍后再试～",
-    FILE_MISSING_PATH: "抱歉，文件消息缺少内容～",
     FILE_CHANNEL_UNSUPPORTED: "抱歉，文件消息暂不支持在频道中发送～",
-    FILE_UPLOADING: (name, size) => `正在上传文件 ${name} (${size})...`,
-    // 载荷解析
+    // 缺少必要内容
+    VOICE_MISSING_TEXT: "抱歉，语音消息缺少内容～",
+    VIDEO_MISSING_PATH: "抱歉，视频消息缺少内容～",
+    FILE_MISSING_PATH: "抱歉，文件消息缺少内容～",
+    // 载荷解析校验
     PAYLOAD_PARSE_ERROR: "抱歉，消息格式异常，无法处理～",
     UNSUPPORTED_MEDIA_TYPE: "抱歉，暂不支持该媒体类型～",
     UNSUPPORTED_PAYLOAD_TYPE: "抱歉，暂不支持该消息类型～",
 };
-/**
- * 将媒体上传/发送错误转为对用户友好的提示文案
- * 技术细节不暴露给用户，仅记录到日志
- */
-export function formatMediaErrorMessage(mediaType, err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    if (msg.includes("上传超时") || msg.includes("timeout") || msg.includes("Timeout")) {
-        return `抱歉，${mediaType}资源加载超时，可能是网络原因或文件太大，请稍后再试～`;
-    }
-    if (msg.includes("文件不存在") || msg.includes("not found") || msg.includes("Not Found")) {
-        return `抱歉，${mediaType}文件不存在或已失效，无法发送～`;
-    }
-    if (msg.includes("文件大小") || msg.includes("too large") || msg.includes("exceed")) {
-        return `抱歉，${mediaType}文件太大了，超出了发送限制～`;
-    }
-    if (msg.includes("Network error") || msg.includes("ECONNREFUSED") || msg.includes("ENOTFOUND")) {
-        return `抱歉，网络连接异常，${mediaType}发送失败，请稍后再试～`;
-    }
-    return `抱歉，${mediaType}发送失败了，请稍后再试～`;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tencent-connect/openclaw-qqbot",
-  "version": "1.6.2-alpha.0",
+  "version": "1.6.2-alpha.2",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/channel.ts

@@ -66,7 +66,7 @@ export const qqbotPlugin: ChannelPlugin<ResolvedQQBotAccount> = {
      * blockStreaming: true 表示该 Channel 支持块流式
      * 框架会收集流式响应，然后通过 deliver 回调发送
      */
-    blockStreaming: true,
+    blockStreaming: false,
   },
   reload: { configPrefixes: ["channels.qqbot"] },
   // CLI onboarding wizard

package/src/gateway.ts

@@ -8,7 +8,7 @@ import { recordKnownUser, flushKnownUsers, listKnownUsers } from "./known-users.
 import { getQQBotRuntime } from "./runtime.js";
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, flushRefIndex, type RefAttachmentSummary } from "./ref-index-store.js";
 import { matchSlashCommand, getPluginVersion, type SlashCommandContext, type SlashCommandFileResult, type QueueSnapshot } from "./slash-commands.js";
-import { triggerUpdateCheck } from "./update-checker.js";
+import { triggerUpdateCheck, onUpdateFound, formatUpdateNotice } from "./update-checker.js";
 import { startImageServer, isImageServerRunning, downloadFile, type ImageServerConfig } from "./image-server.js";
 import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize, DEFAULT_IMAGE_SIZE } from "./utils/image-size.js";
 import { parseQQBotPayload, encodePayloadForCron, isCronReminderPayload, isMediaPayload, type CronReminderPayload, type MediaPayload } from "./utils/payload.js";
@@ -16,7 +16,7 @@ import { convertSilkToWav, isVoiceAttachment, formatDuration, resolveTTSConfig,
 import { normalizeMediaTags } from "./utils/media-tags.js";
 import { checkFileSize, readFileAsync, fileExistsAsync, isLargeFile, formatFileSize } from "./utils/file-utils.js";
 import { getQQBotDataDir, isLocalPath as isLocalFilePath, normalizePath, sanitizeFileName, runDiagnostics } from "./utils/platform.js";
-import { MSG, formatMediaErrorMessage } from "./user-messages.js";
+import { MSG } from "./user-messages.js";
 import { sendPhoto, sendVoice, sendVideoMsg, sendDocument, sendMedia as sendMediaAuto, type MediaTargetContext } from "./outbound.js";
 
 /**
@@ -221,8 +221,6 @@ function parseFaceTags(text: string): string {
   });
 }
 
-// formatMediaErrorMessage 已移至 user-messages.ts 集中管理
-
 // ============ 内部标记过滤 ============
 
 /**
@@ -410,9 +408,36 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     }
   }
 
-  // 后台版本检查（供 /qqbot-version、/qqbot-upgrade 指令被动查询）
+  // 后台版本检查（detached 子进程，零阻塞）
   triggerUpdateCheck(log);
 
+  // 注册新版本通知回调：仅发给管理员，带防抖
+  let lastUpdateNotifyAt = 0;
+  const UPDATE_NOTIFY_DEBOUNCE_MS = 5 * 60 * 1000; // 5 分钟内不重复通知
+  onUpdateFound(async (info) => {
+    try {
+      // 防抖：避免短时间内重复推送
+      const now = Date.now();
+      if (now - lastUpdateNotifyAt < UPDATE_NOTIFY_DEBOUNCE_MS) {
+        log?.debug?.(`[qqbot:${account.accountId}] Update notification debounced`);
+        return;
+      }
+      const notice = formatUpdateNotice(info);
+      if (!notice) return;
+      const adminId = resolveAdminOpenId();
+      if (!adminId) {
+        log?.debug?.(`[qqbot:${account.accountId}] No admin or known user to send update notification`);
+        return;
+      }
+      const token = await getAccessToken(account.appId, account.clientSecret);
+      await sendProactiveC2CMessage(token, adminId, notice);
+      lastUpdateNotifyAt = Date.now();
+      log?.info(`[qqbot:${account.accountId}] Sent update notification to admin: ${adminId}`);
+    } catch (err) {
+      log?.debug?.(`[qqbot:${account.accountId}] Failed to send update notification to admin: ${err}`);
+    }
+  });
+
   // 初始化 API 配置（markdown 支持）
   initApiConfig({
     markdownSupport: account.markdownSupport,
@@ -1678,7 +1703,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                       const result = await sendPhoto(mediaTarget, item.content);
                       if (result.error) {
                         log?.error(`[qqbot:${account.accountId}] sendPhoto error: ${result.error}`);
-                        await sendErrorMessage(formatMediaErrorMessage("图片", new Error(result.error)));
                       }
                     } else if (item.type === "voice") {
                       const uploadFormats = account.config?.audioFormatPolicy?.uploadDirectFormats ?? account.config?.voiceDirectUploadFormats;
@@ -1694,23 +1718,19 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                         ]);
                         if (result.error) {
                           log?.error(`[qqbot:${account.accountId}] sendVoice error: ${result.error}`);
-                          await sendErrorMessage(formatMediaErrorMessage("语音", new Error(result.error)));
                         }
                       } catch (err) {
                         log?.error(`[qqbot:${account.accountId}] sendVoice unexpected error: ${err}`);
-                        await sendErrorMessage(formatMediaErrorMessage("语音", err));
                       }
                     } else if (item.type === "video") {
                       const result = await sendVideoMsg(mediaTarget, item.content);
                       if (result.error) {
                         log?.error(`[qqbot:${account.accountId}] sendVideoMsg error: ${result.error}`);
-                        await sendErrorMessage(formatMediaErrorMessage("视频", new Error(result.error)));
                       }
                     } else if (item.type === "file") {
                       const result = await sendDocument(mediaTarget, item.content);
                       if (result.error) {
                         log?.error(`[qqbot:${account.accountId}] sendDocument error: ${result.error}`);
-                        await sendErrorMessage(formatMediaErrorMessage("文件", new Error(result.error)));
                       }
                     } else if (item.type === "media") {
                       // qqmedia: 自动根据扩展名路由到 sendPhoto/sendVoice/sendVideoMsg/sendDocument
@@ -1724,7 +1744,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                       });
                       if (result.error) {
                         log?.error(`[qqbot:${account.accountId}] sendMedia(auto) error: ${result.error}`);
-                        await sendErrorMessage(formatMediaErrorMessage("媒体", new Error(result.error)));
                       }
                     }
                   }
@@ -1799,12 +1818,12 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                         if (parsedPayload.source === "file") {
                           try {
                             if (!(await fileExistsAsync(imageUrl))) {
-                              await sendErrorMessage(MSG.IMAGE_NOT_FOUND);
+                              log?.error(`[qqbot:${account.accountId}] Image not found: ${imageUrl}`);
                               return;
                             }
                             const imgSzCheck = checkFileSize(imageUrl);
                             if (!imgSzCheck.ok) {
-                              await sendErrorMessage(MSG.IMAGE_SEND_FAILED);
+                              log?.error(`[qqbot:${account.accountId}] Image size check failed: ${imgSzCheck.error}`);
                               return;
                             }
                             const fileBuffer = await readFileAsync(imageUrl);
@@ -1827,7 +1846,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                             log?.info(`[qqbot:${account.accountId}] Converted local image to Base64 (size: ${formatFileSize(fileBuffer.length)})`);
                           } catch (readErr) {
                             log?.error(`[qqbot:${account.accountId}] Failed to read local image: ${readErr}`);
-                            await sendErrorMessage(MSG.IMAGE_SEND_FAILED);
                             return;
                           }
                         }
@@ -1860,7 +1878,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                           }
                         } catch (err) {
                           log?.error(`[qqbot:${account.accountId}] Failed to send image: ${err}`);
-                          await sendErrorMessage(formatMediaErrorMessage("图片", err));
                         }
                       } else if (parsedPayload.mediaType === "audio") {
                         // TTS 语音发送：文字 → PCM → SILK → QQ 语音
@@ -1872,7 +1889,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                               const ttsCfg = resolveTTSConfig(cfg as Record<string, unknown>);
                               if (!ttsCfg) {
                                 log?.error(`[qqbot:${account.accountId}] TTS not configured (channels.qqbot.tts in openclaw.json)`);
-                                await sendErrorMessage(MSG.VOICE_NOT_AVAILABLE);
                             } else {
                               log?.info(`[qqbot:${account.accountId}] TTS: "${ttsText.slice(0, 50)}..." via ${ttsCfg.model}`);
                               const ttsDir = getQQBotDataDir("tts");
@@ -1893,7 +1909,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                           }
                         } catch (err) {
                           log?.error(`[qqbot:${account.accountId}] TTS/voice send failed: ${err}`);
-                          await sendErrorMessage(formatMediaErrorMessage("语音", err));
                         }
                       } else if (parsedPayload.mediaType === "video") {
                         // 视频发送：支持公网 URL 和本地文件
@@ -1954,7 +1969,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                           }
                         } catch (err) {
                           log?.error(`[qqbot:${account.accountId}] Video send failed: ${err}`);
-                          await sendErrorMessage(formatMediaErrorMessage("视频", err));
                         }
                       } else if (parsedPayload.mediaType === "file") {
                         // 文件发送
@@ -1999,7 +2013,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                           }
                         } catch (err) {
                           log?.error(`[qqbot:${account.accountId}] File send failed: ${err}`);
-                          await sendErrorMessage(formatMediaErrorMessage("文件", err));
                         }
                       } else {
                         log?.error(`[qqbot:${account.accountId}] Unknown media type: ${(parsedPayload as MediaPayload).mediaType}`);
@@ -2359,9 +2372,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                 // 发送错误提示给用户，显示完整错误信息
                 const errMsg = String(err);
                 if (errMsg.includes("401") || errMsg.includes("key") || errMsg.includes("auth")) {
-                  await sendErrorMessage(MSG.AI_AUTH_ERROR);
+                  log?.error(`[qqbot:${account.accountId}] AI auth error: ${errMsg}`);
                 } else {
-                  await sendErrorMessage(MSG.AI_PROCESS_ERROR);
+                  log?.error(`[qqbot:${account.accountId}] AI process error: ${errMsg}`);
                 }
               },
             },
@@ -2379,7 +2392,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
             }
             if (!hasResponse) {
               log?.error(`[qqbot:${account.accountId}] No response within timeout`);
-              await sendErrorMessage(MSG.TIMEOUT_HINT);
             }
           } finally {
             // 清理 tool-only 兜底定时器
@@ -2396,7 +2408,6 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
           }
         } catch (err) {
           log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
-          await sendErrorMessage(MSG.GENERIC_ERROR);
         }
       };
 

package/src/outbound.ts

@@ -313,7 +313,7 @@ export async function sendPhoto(
 
   if (isLocal) {
     if (!(await fileExistsAsync(mediaPath))) {
-      return { channel: "qqbot", error: MSG.IMAGE_NOT_FOUND };
+      return { channel: "qqbot", error: "图片不存在或已失效" };
     }
     const sizeCheck = checkFileSize(mediaPath);
     if (!sizeCheck.ok) {
@@ -464,7 +464,7 @@ async function sendVoiceFromLocal(
   // 等待文件就绪（TTS 异步生成，文件可能还没写完）
   const fileSize = await waitForFile(mediaPath);
   if (fileSize === 0) {
-    return { channel: "qqbot", error: MSG.VOICE_GENERATE_FAILED };
+    return { channel: "qqbot", error: "语音文件未就绪" };
   }
 
   // 精细检测：是否需要转码
@@ -570,7 +570,7 @@ export async function sendVideoMsg(
 /** 从本地文件发送视频（sendVideoMsg 的内部辅助） */
 async function sendVideoFromLocal(ctx: MediaTargetContext, mediaPath: string, prefix: string): Promise<OutboundResult> {
   if (!(await fileExistsAsync(mediaPath))) {
-    return { channel: "qqbot", error: MSG.VIDEO_NOT_FOUND };
+    return { channel: "qqbot", error: "视频文件不存在或已失效" };
   }
   const sizeCheck = checkFileSize(mediaPath);
   if (!sizeCheck.ok) {
@@ -665,7 +665,7 @@ async function sendDocumentFromLocal(ctx: MediaTargetContext, mediaPath: string,
   const fileName = sanitizeFileName(path.basename(mediaPath));
 
   if (!(await fileExistsAsync(mediaPath))) {
-    return { channel: "qqbot", error: MSG.FILE_NOT_FOUND };
+    return { channel: "qqbot", error: "文件不存在或已失效" };
   }
   const sizeCheck = checkFileSize(mediaPath);
   if (!sizeCheck.ok) {

package/src/update-checker.ts

@@ -38,6 +38,19 @@ let _lastInfo: UpdateInfo = {
 
 let _checking = false;
 
+/** 已通知过的版本号，避免同一版本重复推送 */
+let _notifiedVersion: string | null = null;
+
+type UpdateFoundCallback = (info: UpdateInfo) => void;
+let _onUpdateFound: UpdateFoundCallback | null = null;
+
+/**
+ * 注册新版本发现回调（仅在首次检测到某个新版本时触发一次）
+ */
+export function onUpdateFound(cb: UpdateFoundCallback): void {
+  _onUpdateFound = cb;
+}
+
 export function triggerUpdateCheck(log?: {
   info: (msg: string) => void;
   error: (msg: string) => void;
@@ -77,6 +90,11 @@ export function triggerUpdateCheck(log?: {
         _lastInfo = { current: CURRENT_VERSION, latest: compareTarget, hasUpdate, checkedAt: now };
         if (hasUpdate) {
           log?.info?.(`[qqbot:update-checker] new version available: ${compareTarget} (current: ${CURRENT_VERSION})`);
+          // 首次发现该版本时触发回调
+          if (_onUpdateFound && compareTarget !== _notifiedVersion) {
+            _notifiedVersion = compareTarget;
+            _onUpdateFound(_lastInfo);
+          }
         }
       } catch (parseErr) {
         _lastInfo = { current: CURRENT_VERSION, latest: null, hasUpdate: false, checkedAt: now, error: String(parseErr) };
@@ -89,6 +107,11 @@ export function getUpdateInfo(): UpdateInfo {
   return { ..._lastInfo };
 }
 
+export function formatUpdateNotice(info: UpdateInfo): string {
+  if (!info.hasUpdate || !info.latest) return "";
+  return `\u{1f195} 有新版本可用: v${info.latest}（当前 v${info.current}）\n使用 /qqbot-upgrade 升级`;
+}
+
 function compareVersions(a: string, b: string): number {
   const parse = (v: string) => {
     const clean = v.replace(/^v/, "");

package/src/user-messages.ts

@@ -1,73 +1,24 @@
 /**
  * 用户面向的提示文案集中管理
- *
- * 设计原则（参考 Telegram / Discord / Slack / 飞书）：
- * 1. 禁止暴露服务器路径、原始 Error、配置文件结构
- * 2. 错误信息分级：用户只看到通用友好文案，技术细节走日志
- * 3. 统一风格：去掉 [QQBot] 前缀和 [方括号] 格式
- * 4. 所有面向用户的文案集中在此文件，便于维护和国际化
+ * 仅保留格式校验类提示，运行时错误走日志不面向用户
  */
 
-// ============ 媒体发送错误 ============
-
 export const MSG = {
-  // 通用错误
-  GENERIC_ERROR: "抱歉，处理消息时遇到了问题，请稍后再试～",
-  AI_AUTH_ERROR: "抱歉，AI 服务暂时不可用，请联系管理员检查配置～",
-  AI_PROCESS_ERROR: "抱歉，AI 处理遇到了问题，请稍后再试～",
-  TIMEOUT_HINT: "已收到消息，正在处理中…",
-
-  // 图片
-  IMAGE_NOT_FOUND: "抱歉，图片不存在或已失效，无法发送～",
+  // 图片格式校验
   IMAGE_FORMAT_UNSUPPORTED: (ext: string) => `抱歉，暂不支持 ${ext} 格式的图片～`,
-  IMAGE_SEND_FAILED: "抱歉，图片发送失败了，请稍后再试～",
-  IMAGE_UPLOADING: (size: string) => `正在上传图片 (${size})...`,
 
-  // 语音
-  VOICE_GENERATE_FAILED: "抱歉，语音生成失败，请稍后重试～",
-  VOICE_CONVERT_FAILED: "抱歉，语音格式转换失败，请稍后重试～",
-  VOICE_SEND_FAILED: "抱歉，语音发送失败了，请稍后再试～",
-  VOICE_NOT_AVAILABLE: "抱歉，语音功能暂未开启～",
-  VOICE_MISSING_TEXT: "抱歉，语音消息缺少内容～",
+  // 频道不支持的媒体类型
   VOICE_CHANNEL_UNSUPPORTED: "抱歉，语音消息暂不支持在频道中发送～",
-
-  // 视频
-  VIDEO_NOT_FOUND: "抱歉，视频文件不存在或已失效，无法发送～",
-  VIDEO_SEND_FAILED: "抱歉，视频发送失败了，请稍后再试～",
-  VIDEO_MISSING_PATH: "抱歉，视频消息缺少内容～",
   VIDEO_CHANNEL_UNSUPPORTED: "抱歉，视频消息暂不支持在频道中发送～",
-  VIDEO_UPLOADING: (size: string) => `正在上传视频 (${size})...`,
+  FILE_CHANNEL_UNSUPPORTED: "抱歉，文件消息暂不支持在频道中发送～",
 
-  // 文件
-  FILE_NOT_FOUND: "抱歉，文件不存在或已失效，无法发送～",
-  FILE_SEND_FAILED: "抱歉，文件发送失败了，请稍后再试～",
+  // 缺少必要内容
+  VOICE_MISSING_TEXT: "抱歉，语音消息缺少内容～",
+  VIDEO_MISSING_PATH: "抱歉，视频消息缺少内容～",
   FILE_MISSING_PATH: "抱歉，文件消息缺少内容～",
-  FILE_CHANNEL_UNSUPPORTED: "抱歉，文件消息暂不支持在频道中发送～",
-  FILE_UPLOADING: (name: string, size: string) => `正在上传文件 ${name} (${size})...`,
 
-  // 载荷解析
+  // 载荷解析校验
   PAYLOAD_PARSE_ERROR: "抱歉，消息格式异常，无法处理～",
   UNSUPPORTED_MEDIA_TYPE: "抱歉，暂不支持该媒体类型～",
   UNSUPPORTED_PAYLOAD_TYPE: "抱歉，暂不支持该消息类型～",
 } as const;
-
-/**
- * 将媒体上传/发送错误转为对用户友好的提示文案
- * 技术细节不暴露给用户，仅记录到日志
- */
-export function formatMediaErrorMessage(mediaType: string, err: unknown): string {
-  const msg = err instanceof Error ? err.message : String(err);
-  if (msg.includes("上传超时") || msg.includes("timeout") || msg.includes("Timeout")) {
-    return `抱歉，${mediaType}资源加载超时，可能是网络原因或文件太大，请稍后再试～`;
-  }
-  if (msg.includes("文件不存在") || msg.includes("not found") || msg.includes("Not Found")) {
-    return `抱歉，${mediaType}文件不存在或已失效，无法发送～`;
-  }
-  if (msg.includes("文件大小") || msg.includes("too large") || msg.includes("exceed")) {
-    return `抱歉，${mediaType}文件太大了，超出了发送限制～`;
-  }
-  if (msg.includes("Network error") || msg.includes("ECONNREFUSED") || msg.includes("ENOTFOUND")) {
-    return `抱歉，网络连接异常，${mediaType}发送失败，请稍后再试～`;
-  }
-  return `抱歉，${mediaType}发送失败了，请稍后再试～`;
-}