@tencent-connect/openclaw-qqbot 1.6.0-alpha.3 → 1.6.0

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.5.7`
+### 🚀 Current Version: `v1.6.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/)
@@ -99,7 +99,7 @@ If your main model supports vision (e.g. Tencent Hunyuan `hunyuan-vision`), AI c
 >
 > **QQBot**: Here you go! 🐱
 
-AI sends images via `<qqimg>path</qqimg>`. Supports local paths and URLs. Formats: jpg/png/gif/webp/bmp.
+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" />
 
@@ -109,7 +109,7 @@ AI sends images via `<qqimg>path</qqimg>`. Supports local paths and URLs. Format
 >
 > **QQBot**: *(sends a voice message)*
 
-AI sends voice via `<qqvoice>path</qqvoice>`. Formats: mp3/wav/silk/ogg. No ffmpeg required.
+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" />
 
@@ -129,7 +129,7 @@ This capability depends on OpenClaw cron scheduling and proactive messaging. If
 >
 > **QQBot**: *(sends a .txt file)*
 
-AI sends files via `<qqfile>path</qqfile>`. Any format, up to 20MB.
+AI can send files directly. Any format, up to 20MB.
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="File Sending Demo" />
 
@@ -139,21 +139,63 @@ AI sends files via `<qqfile>path</qqfile>`. Any format, up to 20MB.
 >
 > **QQBot**: *(sends a video)*
 
-AI sends videos via `<qqvideo>path</qqvideo>`. Supports local files and URLs. Large files (>5MB) auto-show upload progress.
+AI can send videos directly. Supports local files and URLs.
 
 <img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="Video Sending Demo" />
 
-### Rich Media Tag Reference
+> **Under the hood:** Upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.
 
-| Tag | Direction | Notes |
-|-----|-----------|-------|
-| `<qqimg>path</qqimg>` | Send | jpg/png/gif/webp/bmp, local path or URL |
-| `<qqvoice>path</qqvoice>` | Send | mp3/wav/silk/ogg, no ffmpeg required |
-| `<qqfile>path</qqfile>` | Send | Any format, up to 20MB |
-| `<qqvideo>path</qqvideo>` | Send | Local path or URL |
-| Voice / File / Image | Receive | Auto-transcribe (STT), auto-download, or vision analysis |
+### 🛠️ Slash Commands
 
-> **Under the hood:** 30+ tag variant auto-correction, upload dedup caching, ordered queue delivery, and multi-layer audio format fallback.
+The plugin provides built-in slash commands that are intercepted before reaching the AI queue, giving instant responses for diagnostics and management.
+
+#### `/qqbot-ping` — Latency Test
+
+> **You**: `/qqbot-ping`
+>
+> **QQBot**: ✅ pong！⏱ Latency: 602ms (network: 602ms, plugin: 0ms)
+
+Measures end-to-end latency from QQ server push to plugin response, broken down into network transport and plugin processing time.
+
+<img width="360" src="docs/images/slash-ping.jpg" alt="Ping Demo" />
+
+#### `/qqbot-version` — Version Info
+
+> **You**: `/qqbot-version`
+>
+> **QQBot**: 🦞 Framework: OpenClaw 2026.3.13 (61d171a) / 🤖 Plugin: v1.6.0 / 🌟 GitHub repo
+
+Shows framework version, plugin version, and a direct link to the official repository.
+
+<img width="360" src="docs/images/slash-version.jpg" alt="Version Demo" />
+
+#### `/qqbot-help` — Command List
+
+> **You**: `/qqbot-help`
+>
+> **QQBot**: Lists all available slash commands with clickable shortcuts.
+
+<img width="360" src="docs/images/slash-help.jpg" alt="Help Demo" />
+
+#### `/qqbot-upgrade` — Upgrade Guide
+
+> **You**: `/qqbot-upgrade`
+>
+> **QQBot**: 📌 Current version / ✅ Up to date / ⬆️ Upgrade guide / 🌟 GitHub repo
+
+Shows current version, update status, upgrade guide link, and official repository.
+
+<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade Demo" /> 
+
+#### `/qqbot-logs` — Log Export
+
+> **You**: `/qqbot-logs`
+>
+> **QQBot**: 📋 Logs packaged (~2000 lines), sending file... *(sends a .txt file)*
+
+Exports the last ~2000 lines of gateway logs as a file for quick troubleshooting.
+
+<img width="360" src="docs/images/slash-logs.jpg" alt="Logs Demo" />
 
 ---
 
@@ -379,7 +421,7 @@ STT supports two-level configuration with priority fallback:
 - `provider` — references a key in `models.providers` to inherit `baseUrl` and `apiKey`
 - `voice` — voice variant
 - Set `enabled: false` to disable (default: `true`)
-- When configured, AI can use `<qqvoice>` tags to generate and send voice messages
+- When configured, AI can generate and send voice messages
 
 ---
 

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.5.7`
+### 🚀 当前版本： `v1.6.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/)
@@ -94,7 +94,7 @@ QQ 的引用事件通常只携带索引键（如 `REFIDX_xxx`），不直接返
 >
 > **QQBot**：画好啦！一只可爱的简笔小猫咪🐱🎨
 
-AI 通过 `<qqimg>路径</qqimg>` 发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
+AI 可直接发送图片，支持本地文件路径和网络 URL。格式：jpg/png/gif/webp/bmp。
 
 <img width="360" src="docs/images/4645f2b3a20822b7f8d6664a708529eb_720.jpg" alt="发图片演示" />
 
@@ -104,7 +104,7 @@ AI 通过 `<qqimg>路径</qqimg>` 发送图片，支持本地文件路径和网
 >
 > **QQBot**：*（发送一条语音消息）*
 
-AI 通过 `<qqvoice>路径</qqvoice>` 发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
+AI 可直接发送语音消息。格式：mp3/wav/silk/ogg，无需安装 ffmpeg。
 
 <img width="360" src="docs/images/21dce8bfc553ce23d1bd1b270e9c516c.jpg" alt="发语音演示" />
 
@@ -124,7 +124,7 @@ AI 通过 `<qqvoice>路径</qqvoice>` 发送语音消息。格式：mp3/wav/silk
 >
 > **QQBot**：*（发送 .txt 文件）*
 
-AI 通过 `<qqfile>路径</qqfile>` 发送文件。任意格式，最大 20MB。
+AI 可直接发送文件。任意格式，最大 20MB。
 
 <img width="360" src="docs/images/17cada70df90185d45a2d6dd36e92f2f_720.jpg" alt="发文件演示" />
 
@@ -134,21 +134,63 @@ AI 通过 `<qqfile>路径</qqfile>` 发送文件。任意格式，最大 20MB。
 >
 > **QQBot**：*（发送视频）*
 
-AI 通过 `<qqvideo>路径</qqvideo>` 发送视频，支持本地文件和公网 URL。大文件（>5MB）自动提示上传进度。
+AI 可直接发送视频，支持本地文件和公网 URL。
 
 <img width="360" src="docs/images/85d03b8a216f267ab7b2aee248a18a41_720.jpg" alt="发视频演示" />
 
-### 富媒体标签参考
+> **底层细节：** 上传去重缓存、有序队列发送、音频格式多层降级。
 
-| 标签 | 方向 | 说明 |
-|------|------|------|
-| `<qqimg>路径</qqimg>` | 发送 | jpg/png/gif/webp/bmp，本地路径或 URL |
-| `<qqvoice>路径</qqvoice>` | 发送 | mp3/wav/silk/ogg，无需 ffmpeg |
-| `<qqfile>路径</qqfile>` | 发送 | 任意格式，最大 20MB |
-| `<qqvideo>路径</qqvideo>` | 发送 | 本地路径或 URL |
-| 语音 / 文件 / 图片 | 接收 | 自动转录(STT)、自动下载、或视觉分析 |
+### 🛠️ 斜杠指令
 
-> **底层细节：** 30+ 种标签变体自动纠正、上传去重缓存、有序队列发送、音频格式多层降级。
+插件内置一组斜杠指令，在消息进入 AI 队列前拦截处理，即时响应，用于诊断和管理。
+
+#### `/qqbot-ping` — 延迟测试
+
+> **你**：`/qqbot-ping`
+>
+> **QQBot**：✅ pong！⏱ 延迟: 602ms（网络传输: 602ms，插件处理: 0ms）
+
+测量从 QQ 服务器推送到插件响应的端到端延迟，细分网络传输和插件处理两段耗时。
+
+<img width="360" src="docs/images/slash-ping.jpg" alt="Ping 演示" />
+
+#### `/qqbot-version` — 版本信息
+
+> **你**：`/qqbot-version`
+>
+> **QQBot**：🦞框架版本：OpenClaw 2026.3.13 (61d171a) / 🤖QQBot 插件版本：v1.6.0 / 🌟官方 GitHub 仓库
+
+一目了然查看框架版本、插件版本，并可直接跳转官方仓库。
+
+<img width="360" src="docs/images/slash-version.jpg" alt="Version 演示" />
+
+#### `/qqbot-help` — 指令列表
+
+> **你**：`/qqbot-help`
+>
+> **QQBot**：列出所有可用的斜杠指令及说明，指令可点击快速输入。
+
+<img width="360" src="docs/images/slash-help.jpg" alt="Help 演示" />
+
+#### `/qqbot-upgrade` — 升级指引
+
+> **你**：`/qqbot-upgrade`
+>
+> **QQBot**：📌当前版本 / ✅当前已是最新版本 / ⬆️升级指引 / 🌟官方 GitHub 仓库
+
+显示当前版本、更新状态、升级文档链接及官方仓库入口。
+
+<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade 演示" /> 
+
+#### `/qqbot-logs` — 日志导出
+
+> **你**：`/qqbot-logs`
+>
+> **QQBot**：📋 日志已打包（约 2000 行），正在发送文件… *（发送 .txt 文件）*
+
+导出最近约 2000 行网关日志为文件，方便快速排查问题。
+
+<img width="360" src="docs/images/slash-logs.jpg" alt="Logs 演示" />
 
 ---
 
@@ -374,7 +416,7 @@ STT 支持两级配置，按优先级查找：
 - `provider` — 引用 `models.providers` 中的 key，自动继承 `baseUrl` 和 `apiKey`
 - `voice` — 语音音色
 - 设置 `enabled: false` 可禁用（默认：`true`）
-- 配置后，AI 可使用 `<qqvoice>` 标签生成并发送语音消息
+- 配置后，AI 可生成并发送语音消息
 
 ---
 

package/dist/src/api.js

@@ -58,8 +58,12 @@ const tokenFetchPromises = new Map();
 export async function getAccessToken(appId, clientSecret) {
     const normalizedAppId = String(appId).trim();
     const cachedToken = tokenCacheMap.get(normalizedAppId);
-    // 检查缓存：未过期 且 appId 未变化 时复用
-    if (cachedToken && Date.now() < cachedToken.expiresAt - 5 * 60 * 1000) {
+    // 检查缓存：未过期时复用
+    // 提前刷新阈值：取 expiresIn 的 1/3 和 5 分钟的较小值，避免短有效期 token 永远被判定过期
+    const REFRESH_AHEAD_MS = cachedToken
+        ? Math.min(5 * 60 * 1000, (cachedToken.expiresAt - Date.now()) / 3)
+        : 0;
+    if (cachedToken && Date.now() < cachedToken.expiresAt - REFRESH_AHEAD_MS) {
         return cachedToken.token;
     }
     // Singleflight: 如果当前 appId 已有进行中的 Token 获取请求，复用它
@@ -159,7 +163,8 @@ export function getTokenStatus(appId) {
     if (!cached) {
         return { status: "none", expiresAt: null };
     }
-    const isValid = Date.now() < cached.expiresAt - 5 * 60 * 1000;
+    const remaining = cached.expiresAt - Date.now();
+    const isValid = remaining > Math.min(5 * 60 * 1000, remaining / 3);
     return { status: isValid ? "valid" : "expired", expiresAt: cached.expiresAt };
 }
 /**

package/dist/src/gateway.js

@@ -1,13 +1,13 @@
 import WebSocket from "ws";
 import path from "node:path";
 import * as fs from "node:fs";
-import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, sendC2CImageMessage, sendGroupImageMessage, sendC2CVoiceMessage, sendGroupVoiceMessage, sendC2CVideoMessage, sendGroupVideoMessage, sendC2CFileMessage, sendGroupFileMessage, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, PLUGIN_USER_AGENT, sendProactiveC2CMessage, sendProactiveGroupMessage } from "./api.js";
+import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, sendC2CImageMessage, sendGroupImageMessage, sendC2CVoiceMessage, sendGroupVoiceMessage, sendC2CVideoMessage, sendGroupVideoMessage, sendC2CFileMessage, sendGroupFileMessage, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, PLUGIN_USER_AGENT, sendProactiveC2CMessage } from "./api.js";
 import { loadSession, saveSession, clearSession } from "./session-store.js";
 import { recordKnownUser, flushKnownUsers, listKnownUsers } from "./known-users.js";
 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";
@@ -266,30 +266,24 @@ const STARTUP_MARKER_FILE = path.join(getQQBotDataDir("data"), "startup-marker.j
 /**
  * 判断是否为首次安装或版本更新，返回对应的问候语。
  * - 首次安装 / 版本变更 → "Haha，我的'灵魂'已上线，随时等你吩咐。"
- * - 普通重启             → "我重新登上了，有事随时找我。"
- * - 短时间内重复重启（60s 内） → null（跳过，避免刷屏）
+ * - 普通重启（同版本） → null（不发送）
  */
 function getStartupGreeting() {
     const currentVersion = getPluginVersion();
     let isFirstOrUpdated = true;
-    let lastGreetedAt = 0;
     try {
         if (fs.existsSync(STARTUP_MARKER_FILE)) {
             const data = JSON.parse(fs.readFileSync(STARTUP_MARKER_FILE, "utf8"));
             if (data.version === currentVersion) {
                 isFirstOrUpdated = false;
             }
-            if (data.greetedAt) {
-                lastGreetedAt = new Date(data.greetedAt).getTime() || 0;
-            }
         }
     }
     catch {
         // 文件损坏或不存在，视为首次
     }
-    // 防抖：60s 内重复重启不再发送问候（升级场景 stop→start 间隔很短）
-    const GREETING_DEBOUNCE_MS = 60_000;
-    if (!isFirstOrUpdated && lastGreetedAt > 0 && Date.now() - lastGreetedAt < GREETING_DEBOUNCE_MS) {
+    // 普通重启（同版本）不发送问候语
+    if (!isFirstOrUpdated) {
         return null;
     }
     // 更新 marker 文件
@@ -303,9 +297,7 @@ function getStartupGreeting() {
     catch {
         // ignore
     }
-    return isFirstOrUpdated
-        ? `Haha，我的'灵魂'已上线，随时等你吩咐。`
-        : `我重新登上了，有事随时找我。`;
+    return `Haha，我的'灵魂'已上线，随时等你吩咐。`;
 }
 /**
  * 启动 Gateway WebSocket 连接（带自动重连）
@@ -325,6 +317,34 @@ export async function startGateway(ctx) {
     }
     // 后台版本检查（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,
@@ -399,7 +419,47 @@ export async function startGateway(ctx) {
     let shouldRefreshToken = false; // 下次连接是否需要刷新 token
     // 使用模块级 isFirstReadyGlobal，确保只有进程级重启才发送问候语
     // health-monitor 重连不会重新初始化为 true
-    /** 异步发送启动问候语（READY 或 RESUMED 时调用） */
+    const ADMIN_MARKER_FILE = path.join(getQQBotDataDir("data"), `admin-${account.accountId}.json`);
+    /**
+     * 读取已持久化的管理员 openid
+     */
+    const loadAdminOpenId = () => {
+        try {
+            if (fs.existsSync(ADMIN_MARKER_FILE)) {
+                const data = JSON.parse(fs.readFileSync(ADMIN_MARKER_FILE, "utf8"));
+                if (data.openid)
+                    return data.openid;
+            }
+        }
+        catch { /* 文件损坏视为无 */ }
+        return undefined;
+    };
+    /**
+     * 将管理员 openid 持久化到文件
+     */
+    const saveAdminOpenId = (openid) => {
+        try {
+            fs.writeFileSync(ADMIN_MARKER_FILE, JSON.stringify({ openid, savedAt: new Date().toISOString() }));
+        }
+        catch { /* ignore */ }
+    };
+    /**
+     * 解析管理员 openid：
+     * 1. 优先读持久化文件（稳定）
+     * 2. fallback 取第一个私聊用户，并写入文件锁定
+     */
+    const resolveAdminOpenId = () => {
+        const saved = loadAdminOpenId();
+        if (saved)
+            return saved;
+        const first = listKnownUsers({ accountId: account.accountId, type: "c2c", sortBy: "firstSeenAt", sortOrder: "asc", limit: 1 })[0]?.openid;
+        if (first) {
+            saveAdminOpenId(first);
+            log?.info(`[qqbot:${account.accountId}] Auto-detected admin openid: ${first} (persisted)`);
+        }
+        return first;
+    };
+    /** 异步发送启动问候语（仅发给管理员） */
     const sendStartupGreetings = (trigger) => {
         (async () => {
             try {
@@ -408,39 +468,22 @@ export async function startGateway(ctx) {
                     log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (debounced, trigger=${trigger})`);
                     return;
                 }
-                log?.info(`[qqbot:${account.accountId}] Sending startup greeting (trigger=${trigger}): "${greeting}"`);
-                const token = await getAccessToken(account.appId, account.clientSecret);
-                const users = listKnownUsers({ accountId: account.accountId, type: "c2c" });
-                for (const user of users) {
-                    try {
-                        await sendProactiveC2CMessage(token, user.openid, greeting);
-                        log?.info(`[qqbot:${account.accountId}] Sent startup greeting to c2c:${user.openid}`);
-                    }
-                    catch (err) {
-                        log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to c2c:${user.openid}: ${err}`);
-                    }
-                    await new Promise(r => setTimeout(r, 500));
-                }
-                const groups = listKnownUsers({ accountId: account.accountId, type: "group" });
-                const sentGroups = new Set();
-                for (const user of groups) {
-                    const gid = user.groupOpenid;
-                    if (!gid || sentGroups.has(gid))
-                        continue;
-                    sentGroups.add(gid);
-                    try {
-                        await sendProactiveGroupMessage(token, gid, greeting);
-                        log?.info(`[qqbot:${account.accountId}] Sent startup greeting to group:${gid}`);
-                    }
-                    catch (err) {
-                        log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to group:${gid}: ${err}`);
-                    }
-                    await new Promise(r => setTimeout(r, 500));
+                const adminId = resolveAdminOpenId();
+                if (!adminId) {
+                    log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (no admin or known user)`);
+                    return;
                 }
-                log?.info(`[qqbot:${account.accountId}] Startup greetings sent (${users.length} c2c, ${sentGroups.size} groups)`);
+                log?.info(`[qqbot:${account.accountId}] Sending startup greeting to admin (trigger=${trigger}): "${greeting}"`);
+                const token = await getAccessToken(account.appId, account.clientSecret);
+                const GREETING_TIMEOUT_MS = 10_000;
+                await Promise.race([
+                    sendProactiveC2CMessage(token, adminId, greeting),
+                    new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
+                ]);
+                log?.info(`[qqbot:${account.accountId}] Sent startup greeting to admin: ${adminId}`);
             }
             catch (err) {
-                log?.error(`[qqbot:${account.accountId}] Failed to send startup greetings: ${err}`);
+                log?.error(`[qqbot:${account.accountId}] Failed to send startup greeting: ${err}`);
             }
         })();
     };
@@ -1042,10 +1085,10 @@ export async function startGateway(ctx) {
                 const staticParts = [
                     `[QQBot] to=${qualifiedTarget}`,
                 ];
-                // TTS 能力声明：仅在启用时告知 AI 可以发语音（与 qqbot-media SKILL.md 互补）
+                // TTS 能力声明：仅在启用时告知 AI 可以发语音（媒体标签用法由 qqbot-media SKILL.md 提供）
                 // STT 无需声明：转写结果已在动态上下文的 ASR 行中，AI 自然可见
                 if (hasTTS)
-                    staticParts.push("语音合成已启用，发送媒体格式：<qqmedia>路径</qqmedia>");
+                    staticParts.push("语音合成已启用");
                 const staticInstruction = staticParts.join(" | ");
                 // 静态指引作为 systemPrompts 的首项注入
                 systemPrompts.unshift(staticInstruction);

package/dist/src/slash-commands.js

@@ -67,13 +67,13 @@ registerCommand({
         const now = Date.now();
         const eventTime = new Date(ctx.eventTimestamp).getTime();
         if (isNaN(eventTime)) {
-            return `🏓 pong!`;
+            return `✅ pong!`;
         }
         const totalMs = now - eventTime;
         const qqToPlugin = ctx.receivedAt - eventTime;
         const pluginProcess = now - ctx.receivedAt;
         const lines = [
-            `🏓 pong！`,
+            `✅ pong！`,
             ``,
             `⏱ 延迟: ${totalMs}ms`,
             `  ├ 网络传输: ${qqToPlugin}ms`,
@@ -91,23 +91,20 @@ registerCommand({
     handler: () => {
         const frameworkVersion = getFrameworkVersion();
         const lines = [
-            `🦞 框架: ${frameworkVersion}`,
-            `🤖 qqbot插件: v${PLUGIN_VERSION}`,
+            `🦞框架版本：${frameworkVersion}`,
+            `🤖QQBot 插件版本：v${PLUGIN_VERSION}`,
         ];
         const info = getUpdateInfo();
         if (info.checkedAt === 0) {
-            // 尚未检查过
             lines.push(`⏳ 版本检查中...`);
         }
         else if (info.error) {
             lines.push(`⚠️ 版本检查失败`);
         }
         else if (info.hasUpdate && info.latest) {
-            lines.push(`🆕 有新版本: v${info.latest}，使用 /qqbot-upgrade 升级`);
-        }
-        else {
-            lines.push(`✅ 当前已是最新版本`);
+            lines.push(`🆕最新可用版本：v${info.latest}，点击 <qqbot-cmd-input text="/qqbot-upgrade" show="/qqbot-upgrade"/> 查看升级指引`);
         }
+        lines.push(`🌟官方 GitHub 仓库：[点击前往](https://github.com/tencent-connect/openclaw-qqbot/)`);
         return lines.join("\n");
     },
 });
@@ -118,18 +115,15 @@ registerCommand({
     name: "qqbot-help",
     description: "查看所有指令以及用途",
     handler: () => {
-        const lines = [`**qqbot 插件 v${PLUGIN_VERSION}**`, ``];
+        const lines = [`### QQBot插件内置调试指令`, ``];
         for (const [name, cmd] of commands) {
-            lines.push(`- \`/${name}\` — ${cmd.description}`);
+            lines.push(`<qqbot-cmd-input text="/${name}" show="/${name}"/> ${cmd.description}`);
         }
+        lines.push(``, `> 插件版本 v${PLUGIN_VERSION}`);
         return lines.join("\n");
     },
 });
 const DEFAULT_UPGRADE_URL = "https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg";
-/** 升级说明文本 */
-function getUpgradeGuide(url) {
-    return `📖 升级指引:\n${url}`;
-}
 /**
  * /qqbot-upgrade — 查看版本更新状态 + 升级指引
  */
@@ -140,31 +134,30 @@ registerCommand({
         const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
         const info = getUpdateInfo();
         const lines = [];
+        lines.push(`📌当前版本：v${PLUGIN_VERSION}`);
         if (info.checkedAt === 0) {
-            lines.push(`🤖 当前版本: v${PLUGIN_VERSION}`);
             lines.push(`⏳ 版本检查中，请稍后再试`);
         }
         else if (info.error) {
-            lines.push(`🤖 当前版本: v${PLUGIN_VERSION}`);
             lines.push(`⚠️ 版本检查失败`);
         }
         else if (info.hasUpdate && info.latest) {
-            lines.push(`🤖 当前版本: v${PLUGIN_VERSION}`);
-            lines.push(`🆕 最新版本: v${info.latest}`);
+            lines.push(`🆕最新可用版本：v${info.latest}`);
         }
         else {
-            lines.push(`✅ 当前已是最新版本 v${PLUGIN_VERSION}`);
+            lines.push(`✅ 当前已是最新版本`);
         }
-        lines.push("", getUpgradeGuide(url));
+        lines.push(`⬆️升级指引：[点击查看](${url})`);
+        lines.push(`🌟官方 GitHub 仓库：[点击前往](https://github.com/tencent-connect/openclaw-qqbot/)`);
         return lines.join("\n");
     },
 });
 /**
- * /qqbot-logs — 打包本地最近 2000 行日志，发送文件给用户
+ * /qqbot-logs — 导出本地日志文件
  */
 registerCommand({
     name: "qqbot-logs",
-    description: "打包本地最近 2000 行日志，发送文件给用户",
+    description: "导出本地日志文件",
     handler: () => {
         const homeDir = process.env.HOME || "~";
         const logDir = path.join(homeDir, ".openclaw", "logs");

package/dist/src/types.d.ts

@@ -59,7 +59,7 @@ export interface QQBotAccountConfig {
     urlDirectUpload?: boolean;
     /**
      * /qqbot-upgrade 指令返回的升级指引网址
-     * 默认: https://github.com/tencent-connect/openclaw-qqbot
+     * 默认: https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg
      */
     upgradeUrl?: string;
 }

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

@@ -12,6 +12,11 @@ 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;
@@ -19,3 +24,4 @@ export declare function triggerUpdateCheck(log?: {
 }): 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) {

package/package.json

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

package/scripts/cleanup-legacy-plugins.sh

@@ -120,7 +120,7 @@ CMD="$FOUND_INSTALLATION"
 echo ""
 echo "=== 清理完成 ==="
 echo ""
-echo "接下来请执行以下命令重新安装插件:"
+echo "接下来将执行以下命令重新安装插件:"
 echo "  cd /path/to/openclaw-qqbot"
 echo "  $CMD plugins install ."
 echo "  $CMD channels add --channel qqbot --token \"appid:appsecret\""

package/scripts/upgrade-via-npm.sh

@@ -2,19 +2,22 @@
 
 # qqbot 通过 npm 包升级（纯文件操作版本）
 #
-# 重要：此脚本不修改 openclaw.json 配置文件！
-# 配置更新由调用方（TS handler）在脚本完成后统一处理，
-# 避免 gateway config watcher 在安装过程中触发 SIGUSR1 重启导致竞态。
+# 默认只做文件替换，不修改 openclaw.json 配置文件。
+# 但如果提供了 --appid/--secret 参数（首次安装场景），
+# 则在文件安装完成后自动写入通道配置。
 #
 # 用法:
 #   upgrade-via-npm.sh                                    # 升级到 latest（默认）
 #   upgrade-via-npm.sh --version <version>                # 升级到指定版本
 #   upgrade-via-npm.sh --self-version                     # 升级到当前仓库 package.json 版本
+#   upgrade-via-npm.sh --appid <appid> --secret <secret>  # 首次安装时配置 appid/secret
 
 set -eo pipefail
 
 PKG_NAME="@tencent-connect/openclaw-qqbot"
 INSTALL_SRC=""
+APPID=""
+SECRET=""
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
 PROJECT_DIR="$(cd "$SCRIPT_DIR/.." && pwd)"
 
@@ -37,6 +40,14 @@ print_usage() {
     else
         echo "  upgrade-via-npm.sh --self-version               # 升级到当前仓库版本"
     fi
+    echo ""
+    echo "  --appid <appid>       QQ机器人 appid（首次安装时必填）"
+    echo "  --secret <secret>     QQ机器人 secret（首次安装时必填）"
+    echo ""
+    echo "也可以通过环境变量设置:"
+    echo "  QQBOT_APPID           QQ机器人 appid"
+    echo "  QQBOT_SECRET          QQ机器人 secret"
+    echo "  QQBOT_TOKEN           QQ机器人 token (appid:secret)"
 }
 
 while [[ $# -gt 0 ]]; do
@@ -56,6 +67,16 @@ while [[ $# -gt 0 ]]; do
             INSTALL_SRC="${PKG_NAME}@${LOCAL_VERSION}"
             shift 1
             ;;
+        --appid)
+            [ -z "$2" ] && echo "❌ --appid 需要参数" && exit 1
+            APPID="$2"
+            shift 2
+            ;;
+        --secret)
+            [ -z "$2" ] && echo "❌ --secret 需要参数" && exit 1
+            SECRET="$2"
+            shift 2
+            ;;
         -h|--help)
             print_usage
             exit 0
@@ -65,6 +86,14 @@ while [[ $# -gt 0 ]]; do
 done
 INSTALL_SRC="${INSTALL_SRC:-${PKG_NAME}@latest}"
 
+# 环境变量 fallback
+APPID="${APPID:-$QQBOT_APPID}"
+SECRET="${SECRET:-$QQBOT_SECRET}"
+if [ -z "$APPID" ] && [ -z "$SECRET" ] && [ -n "$QQBOT_TOKEN" ]; then
+    APPID="${QQBOT_TOKEN%%:*}"
+    SECRET="${QQBOT_TOKEN#*:}"
+fi
+
 # 检测 CLI（仅用于确定 extensions 目录路径）
 CMD=""
 for name in openclaw clawdbot moltbot; do
@@ -172,3 +201,55 @@ echo ""
 echo "==========================================="
 echo "  ✅ 文件安装完成"
 echo "==========================================="
+
+# [4/4] 配置 appid/secret（仅在提供了参数时执行）
+if [ -n "$APPID" ] && [ -n "$SECRET" ]; then
+    echo ""
+    echo "[配置] 写入 qqbot 通道配置..."
+    DESIRED_TOKEN="${APPID}:${SECRET}"
+
+    # 读取当前已有的 token
+    CURRENT_TOKEN=""
+    for _app in openclaw clawdbot moltbot; do
+        _cfg="$HOME/.$_app/$_app.json"
+        if [ -f "$_cfg" ]; then
+            CURRENT_TOKEN=$(node -e "
+                const cfg = JSON.parse(require('fs').readFileSync('$_cfg', 'utf8'));
+                const keys = ['qqbot', 'openclaw-qqbot', 'openclaw-qq'];
+                for (const key of keys) {
+                    const ch = cfg.channels && cfg.channels[key];
+                    if (!ch) continue;
+                    if (ch.token) { process.stdout.write(ch.token); process.exit(0); }
+                    if (ch.appId && ch.clientSecret) { process.stdout.write(ch.appId + ':' + ch.clientSecret); process.exit(0); }
+                }
+            " 2>/dev/null || true)
+            [ -n "$CURRENT_TOKEN" ] && break
+        fi
+    done
+
+    if [ "$CURRENT_TOKEN" = "$DESIRED_TOKEN" ]; then
+        echo "  ✅ 当前配置已是目标值，跳过写入"
+    elif $CMD channels add --channel qqbot --token "$DESIRED_TOKEN" 2>&1; then
+        echo "  ✅ 通道配置写入成功"
+    else
+        echo "  ⚠️  $CMD channels add 失败，尝试直接编辑配置文件..."
+        CONFIG_FILE="$HOME/.$CMD/$CMD.json"
+        if [ -f "$CONFIG_FILE" ] && node -e "
+            const fs = require('fs');
+            const cfg = JSON.parse(fs.readFileSync('$CONFIG_FILE', 'utf8'));
+            if (!cfg.channels) cfg.channels = {};
+            if (!cfg.channels.qqbot) cfg.channels.qqbot = {};
+            cfg.channels.qqbot.appId = '$APPID';
+            cfg.channels.qqbot.clientSecret = '$SECRET';
+            fs.writeFileSync('$CONFIG_FILE', JSON.stringify(cfg, null, 4) + '\n');
+        " 2>&1; then
+            echo "  ✅ 通道配置写入成功（直接编辑配置文件）"
+        else
+            echo "  ❌ 配置写入失败，请手动配置:"
+            echo "     $CMD channels add --channel qqbot --token \"${APPID}:${SECRET}\""
+        fi
+    fi
+elif [ -n "$APPID" ] || [ -n "$SECRET" ]; then
+    echo ""
+    echo "⚠️  --appid 和 --secret 必须同时提供"
+fi

package/skills/qqbot-cron/SKILL.md

@@ -6,6 +6,14 @@ metadata: {"openclaw":{"emoji":"⏰","requires":{"config":["channels.qqbot"]}}}
 
 # QQ Bot 定时提醒
 
+## ⚠️ 强制规则
+
+**当用户提到「提醒」「闹钟」「定时」「X分钟/小时后」「每天X点」「叫我」等任何涉及延时或定时的请求时，你必须调用 `cron` 工具，绝对不能只用自然语言回复说"好的，我会提醒你"！**
+
+你没有内存或后台线程，口头承诺"到时候提醒"是无效的——只有调用 `cron` 工具才能真正注册定时任务。
+
+---
+
 ## 核心规则
 
 > **payload.kind 必须是 `"agentTurn"`，绝对不能用 `"systemEvent"`！**

package/src/api.ts

@@ -84,8 +84,12 @@ export async function getAccessToken(appId: string, clientSecret: string): Promi
   const normalizedAppId = String(appId).trim();
   const cachedToken = tokenCacheMap.get(normalizedAppId);
 
-  // 检查缓存：未过期 且 appId 未变化 时复用
-  if (cachedToken && Date.now() < cachedToken.expiresAt - 5 * 60 * 1000) {
+  // 检查缓存：未过期时复用
+  // 提前刷新阈值：取 expiresIn 的 1/3 和 5 分钟的较小值，避免短有效期 token 永远被判定过期
+  const REFRESH_AHEAD_MS = cachedToken
+    ? Math.min(5 * 60 * 1000, (cachedToken.expiresAt - Date.now()) / 3)
+    : 0;
+  if (cachedToken && Date.now() < cachedToken.expiresAt - REFRESH_AHEAD_MS) {
     return cachedToken.token;
   }
 
@@ -195,7 +199,8 @@ export function getTokenStatus(appId: string): { status: "valid" | "expired" | "
   if (!cached) {
     return { status: "none", expiresAt: null };
   }
-  const isValid = Date.now() < cached.expiresAt - 5 * 60 * 1000;
+  const remaining = cached.expiresAt - Date.now();
+  const isValid = remaining > Math.min(5 * 60 * 1000, remaining / 3);
   return { status: isValid ? "valid" : "expired", expiresAt: cached.expiresAt };
 }
 

package/src/gateway.ts

@@ -2,13 +2,13 @@ import WebSocket from "ws";
 import path from "node:path";
 import * as fs from "node:fs";
 import type { ResolvedQQBotAccount, WSPayload, C2CMessageEvent, GuildMessageEvent, GroupMessageEvent } from "./types.js";
-import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, sendC2CImageMessage, sendGroupImageMessage, sendC2CVoiceMessage, sendGroupVoiceMessage, sendC2CVideoMessage, sendGroupVideoMessage, sendC2CFileMessage, sendGroupFileMessage, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, PLUGIN_USER_AGENT, sendProactiveC2CMessage, sendProactiveGroupMessage } from "./api.js";
+import { getAccessToken, getGatewayUrl, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, sendC2CImageMessage, sendGroupImageMessage, sendC2CVoiceMessage, sendGroupVoiceMessage, sendC2CVideoMessage, sendGroupVideoMessage, sendC2CFileMessage, sendGroupFileMessage, initApiConfig, startBackgroundTokenRefresh, stopBackgroundTokenRefresh, sendC2CInputNotify, onMessageSent, PLUGIN_USER_AGENT, sendProactiveC2CMessage } from "./api.js";
 import { loadSession, saveSession, clearSession, type SessionState } from "./session-store.js";
 import { recordKnownUser, flushKnownUsers, listKnownUsers } from "./known-users.js";
 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";
@@ -355,13 +355,11 @@ const STARTUP_MARKER_FILE = path.join(getQQBotDataDir("data"), "startup-marker.j
 /**
  * 判断是否为首次安装或版本更新，返回对应的问候语。
  * - 首次安装 / 版本变更 → "Haha，我的'灵魂'已上线，随时等你吩咐。"
- * - 普通重启             → "我重新登上了，有事随时找我。"
- * - 短时间内重复重启（60s 内） → null（跳过，避免刷屏）
+ * - 普通重启（同版本） → null（不发送）
  */
 function getStartupGreeting(): string | null {
   const currentVersion = getPluginVersion();
   let isFirstOrUpdated = true;
-  let lastGreetedAt = 0;
 
   try {
     if (fs.existsSync(STARTUP_MARKER_FILE)) {
@@ -369,17 +367,13 @@ function getStartupGreeting(): string | null {
       if (data.version === currentVersion) {
         isFirstOrUpdated = false;
       }
-      if (data.greetedAt) {
-        lastGreetedAt = new Date(data.greetedAt).getTime() || 0;
-      }
     }
   } catch {
     // 文件损坏或不存在，视为首次
   }
 
-  // 防抖：60s 内重复重启不再发送问候（升级场景 stop→start 间隔很短）
-  const GREETING_DEBOUNCE_MS = 60_000;
-  if (!isFirstOrUpdated && lastGreetedAt > 0 && Date.now() - lastGreetedAt < GREETING_DEBOUNCE_MS) {
+  // 普通重启（同版本）不发送问候语
+  if (!isFirstOrUpdated) {
     return null;
   }
 
@@ -394,9 +388,7 @@ function getStartupGreeting(): string | null {
     // ignore
   }
 
-  return isFirstOrUpdated
-    ? `Haha，我的'灵魂'已上线，随时等你吩咐。`
-    : `我重新登上了，有事随时找我。`;
+  return `Haha，我的'灵魂'已上线，随时等你吩咐。`;
 }
 
 /**
@@ -421,6 +413,33 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
   // 后台版本检查（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,
@@ -498,7 +517,47 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
   // 使用模块级 isFirstReadyGlobal，确保只有进程级重启才发送问候语
   // health-monitor 重连不会重新初始化为 true
 
-  /** 异步发送启动问候语（READY 或 RESUMED 时调用） */
+  const ADMIN_MARKER_FILE = path.join(getQQBotDataDir("data"), `admin-${account.accountId}.json`);
+
+  /**
+   * 读取已持久化的管理员 openid
+   */
+  const loadAdminOpenId = (): string | undefined => {
+    try {
+      if (fs.existsSync(ADMIN_MARKER_FILE)) {
+        const data = JSON.parse(fs.readFileSync(ADMIN_MARKER_FILE, "utf8"));
+        if (data.openid) return data.openid;
+      }
+    } catch { /* 文件损坏视为无 */ }
+    return undefined;
+  };
+
+  /**
+   * 将管理员 openid 持久化到文件
+   */
+  const saveAdminOpenId = (openid: string): void => {
+    try {
+      fs.writeFileSync(ADMIN_MARKER_FILE, JSON.stringify({ openid, savedAt: new Date().toISOString() }));
+    } catch { /* ignore */ }
+  };
+
+  /**
+   * 解析管理员 openid：
+   * 1. 优先读持久化文件（稳定）
+   * 2. fallback 取第一个私聊用户，并写入文件锁定
+   */
+  const resolveAdminOpenId = (): string | undefined => {
+    const saved = loadAdminOpenId();
+    if (saved) return saved;
+    const first = listKnownUsers({ accountId: account.accountId, type: "c2c", sortBy: "firstSeenAt", sortOrder: "asc", limit: 1 })[0]?.openid;
+    if (first) {
+      saveAdminOpenId(first);
+      log?.info(`[qqbot:${account.accountId}] Auto-detected admin openid: ${first} (persisted)`);
+    }
+    return first;
+  };
+
+  /** 异步发送启动问候语（仅发给管理员） */
   const sendStartupGreetings = (trigger: "READY" | "RESUMED") => {
     (async () => {
       try {
@@ -507,35 +566,21 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
           log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (debounced, trigger=${trigger})`);
           return;
         }
-        log?.info(`[qqbot:${account.accountId}] Sending startup greeting (trigger=${trigger}): "${greeting}"`);
-        const token = await getAccessToken(account.appId, account.clientSecret);
-        const users = listKnownUsers({ accountId: account.accountId, type: "c2c" });
-        for (const user of users) {
-          try {
-            await sendProactiveC2CMessage(token, user.openid, greeting);
-            log?.info(`[qqbot:${account.accountId}] Sent startup greeting to c2c:${user.openid}`);
-          } catch (err) {
-            log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to c2c:${user.openid}: ${err}`);
-          }
-          await new Promise(r => setTimeout(r, 500));
-        }
-        const groups = listKnownUsers({ accountId: account.accountId, type: "group" });
-        const sentGroups = new Set<string>();
-        for (const user of groups) {
-          const gid = user.groupOpenid;
-          if (!gid || sentGroups.has(gid)) continue;
-          sentGroups.add(gid);
-          try {
-            await sendProactiveGroupMessage(token, gid, greeting);
-            log?.info(`[qqbot:${account.accountId}] Sent startup greeting to group:${gid}`);
-          } catch (err) {
-            log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to group:${gid}: ${err}`);
-          }
-          await new Promise(r => setTimeout(r, 500));
+        const adminId = resolveAdminOpenId();
+        if (!adminId) {
+          log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (no admin or known user)`);
+          return;
         }
-        log?.info(`[qqbot:${account.accountId}] Startup greetings sent (${users.length} c2c, ${sentGroups.size} groups)`);
+        log?.info(`[qqbot:${account.accountId}] Sending startup greeting to admin (trigger=${trigger}): "${greeting}"`);
+        const token = await getAccessToken(account.appId, account.clientSecret);
+        const GREETING_TIMEOUT_MS = 10_000;
+        await Promise.race([
+          sendProactiveC2CMessage(token, adminId, greeting),
+          new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
+        ]);
+        log?.info(`[qqbot:${account.accountId}] Sent startup greeting to admin: ${adminId}`);
       } catch (err) {
-        log?.error(`[qqbot:${account.accountId}] Failed to send startup greetings: ${err}`);
+        log?.error(`[qqbot:${account.accountId}] Failed to send startup greeting: ${err}`);
       }
     })();
   };
@@ -1187,9 +1232,9 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
         const staticParts: string[] = [
           `[QQBot] to=${qualifiedTarget}`,
         ];
-        // TTS 能力声明：仅在启用时告知 AI 可以发语音（与 qqbot-media SKILL.md 互补）
+        // TTS 能力声明：仅在启用时告知 AI 可以发语音（媒体标签用法由 qqbot-media SKILL.md 提供）
         // STT 无需声明：转写结果已在动态上下文的 ASR 行中，AI 自然可见
-        if (hasTTS) staticParts.push("语音合成已启用，发送媒体格式：<qqmedia>路径</qqmedia>");
+        if (hasTTS) staticParts.push("语音合成已启用");
         const staticInstruction = staticParts.join(" | ");
 
         // 静态指引作为 systemPrompts 的首项注入

package/src/slash-commands.ts

@@ -136,13 +136,13 @@ registerCommand({
     const now = Date.now();
     const eventTime = new Date(ctx.eventTimestamp).getTime();
     if (isNaN(eventTime)) {
-      return `🏓 pong!`;
+      return `✅ pong!`;
     }
     const totalMs = now - eventTime;
     const qqToPlugin = ctx.receivedAt - eventTime;
     const pluginProcess = now - ctx.receivedAt;
     const lines = [
-      `🏓 pong！`,
+      `✅ pong！`,
       ``,
       `⏱ 延迟: ${totalMs}ms`,
       `  ├ 网络传输: ${qqToPlugin}ms`,
@@ -161,20 +161,18 @@ registerCommand({
   handler: () => {
     const frameworkVersion = getFrameworkVersion();
     const lines = [
-      `🦞 框架: ${frameworkVersion}`,
-      `🤖 qqbot插件: v${PLUGIN_VERSION}`,
+      `🦞框架版本：${frameworkVersion}`,
+      `🤖QQBot 插件版本：v${PLUGIN_VERSION}`,
     ];
     const info = getUpdateInfo();
     if (info.checkedAt === 0) {
-      // 尚未检查过
       lines.push(`⏳ 版本检查中...`);
     } else if (info.error) {
       lines.push(`⚠️ 版本检查失败`);
-    } else     if (info.hasUpdate && info.latest) {
-      lines.push(`🆕 有新版本: v${info.latest}，使用 /qqbot-upgrade 升级`);
-    } else {
-      lines.push(`✅ 当前已是最新版本`);
-    }
+    } else if (info.hasUpdate && info.latest) {
+      lines.push(`🆕最新可用版本：v${info.latest}，点击 <qqbot-cmd-input text="/qqbot-upgrade" show="/qqbot-upgrade"/> 查看升级指引`);
+    } 
+    lines.push(`🌟官方 GitHub 仓库：[点击前往](https://github.com/tencent-connect/openclaw-qqbot/)`);
     return lines.join("\n");
   },
 });
@@ -186,21 +184,17 @@ registerCommand({
   name: "qqbot-help",
   description: "查看所有指令以及用途",
   handler: () => {
-    const lines = [`**qqbot 插件 v${PLUGIN_VERSION}**`, ``];
+    const lines = [`### QQBot插件内置调试指令`, ``];
     for (const [name, cmd] of commands) {
-      lines.push(`- \`/${name}\` — ${cmd.description}`);
+      lines.push(`<qqbot-cmd-input text="/${name}" show="/${name}"/> ${cmd.description}`);
     }
+    lines.push(``, `> 插件版本 v${PLUGIN_VERSION}`);
     return lines.join("\n");
   },
 });
 
 const DEFAULT_UPGRADE_URL = "https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg";
 
-/** 升级说明文本 */
-function getUpgradeGuide(url: string): string {
-  return `📖 升级指引:\n${url}`;
-}
-
 /**
  * /qqbot-upgrade — 查看版本更新状态 + 升级指引
  */
@@ -212,30 +206,30 @@ registerCommand({
     const info = getUpdateInfo();
     const lines: string[] = [];
 
+    lines.push(`📌当前版本：v${PLUGIN_VERSION}`);
+
     if (info.checkedAt === 0) {
-      lines.push(`🤖 当前版本: v${PLUGIN_VERSION}`);
       lines.push(`⏳ 版本检查中，请稍后再试`);
     } else if (info.error) {
-      lines.push(`🤖 当前版本: v${PLUGIN_VERSION}`);
       lines.push(`⚠️ 版本检查失败`);
     } else if (info.hasUpdate && info.latest) {
-      lines.push(`🤖 当前版本: v${PLUGIN_VERSION}`);
-      lines.push(`🆕 最新版本: v${info.latest}`);
+      lines.push(`🆕最新可用版本：v${info.latest}`);
     } else {
-      lines.push(`✅ 当前已是最新版本 v${PLUGIN_VERSION}`);
+      lines.push(`✅ 当前已是最新版本`);
     }
 
-    lines.push("", getUpgradeGuide(url));
+    lines.push(`⬆️升级指引：[点击查看](${url})`);
+    lines.push(`🌟官方 GitHub 仓库：[点击前往](https://github.com/tencent-connect/openclaw-qqbot/)`);
     return lines.join("\n");
   },
 });
 
 /**
- * /qqbot-logs — 打包本地最近 2000 行日志，发送文件给用户
+ * /qqbot-logs — 导出本地日志文件
  */
 registerCommand({
   name: "qqbot-logs",
-  description: "打包本地最近 2000 行日志，发送文件给用户",
+  description: "导出本地日志文件",
   handler: () => {
     const homeDir = process.env.HOME || "~";
     const logDir = path.join(homeDir, ".openclaw", "logs");

package/src/types.ts

@@ -61,7 +61,7 @@ export interface QQBotAccountConfig {
   urlDirectUpload?: boolean;
   /**
    * /qqbot-upgrade 指令返回的升级指引网址
-   * 默认: https://github.com/tencent-connect/openclaw-qqbot
+   * 默认: https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg
    */
   upgradeUrl?: string;
 }

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) };