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

package/dist/src/gateway.js

@@ -6,7 +6,8 @@ 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 } from "./slash-commands.js";
+import { matchSlashCommand, getPluginVersion } from "./slash-commands.js";
+import { triggerUpdateCheck } 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";
@@ -257,6 +258,55 @@ async function ensureImageServer(log, publicBaseUrl) {
         return null;
     }
 }
+// ============ 启动问候语（首次安装/版本更新 vs 普通重启） ============
+// 模块级变量：进程生命周期内只有首次为 true
+// 区分 gateway restart（进程重启）和 health-monitor 断线重连
+let isFirstReadyGlobal = true;
+const STARTUP_MARKER_FILE = path.join(getQQBotDataDir("data"), "startup-marker.json");
+/**
+ * 判断是否为首次安装或版本更新，返回对应的问候语。
+ * - 首次安装 / 版本变更 → "Haha，我的'灵魂'已上线，随时等你吩咐。"
+ * - 普通重启             → "我重新登上了，有事随时找我。"
+ * - 短时间内重复重启（60s 内） → 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) {
+        return null;
+    }
+    // 更新 marker 文件
+    try {
+        fs.writeFileSync(STARTUP_MARKER_FILE, JSON.stringify({
+            version: currentVersion,
+            startedAt: new Date().toISOString(),
+            greetedAt: new Date().toISOString(),
+        }) + "\n");
+    }
+    catch {
+        // ignore
+    }
+    return isFirstOrUpdated
+        ? `Haha，我的'灵魂'已上线，随时等你吩咐。`
+        : `我重新登上了，有事随时找我。`;
+}
 /**
  * 启动 Gateway WebSocket 连接（带自动重连）
  * 支持流式消息发送
@@ -273,6 +323,8 @@ export async function startGateway(ctx) {
             log?.info(`[qqbot:${account.accountId}] ${w}`);
         }
     }
+    // 后台版本检查（detached 子进程，零阻塞）
+    triggerUpdateCheck(log);
     // 初始化 API 配置（markdown 支持）
     initApiConfig({
         markdownSupport: account.markdownSupport,
@@ -345,6 +397,53 @@ export async function startGateway(ctx) {
     let isConnecting = false; // 防止并发连接
     let reconnectTimer = null; // 重连定时器
     let shouldRefreshToken = false; // 下次连接是否需要刷新 token
+    // 使用模块级 isFirstReadyGlobal，确保只有进程级重启才发送问候语
+    // health-monitor 重连不会重新初始化为 true
+    /** 异步发送启动问候语（READY 或 RESUMED 时调用） */
+    const sendStartupGreetings = (trigger) => {
+        (async () => {
+            try {
+                const greeting = getStartupGreeting();
+                if (!greeting) {
+                    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));
+                }
+                log?.info(`[qqbot:${account.accountId}] Startup greetings sent (${users.length} c2c, ${sentGroups.size} groups)`);
+            }
+            catch (err) {
+                log?.error(`[qqbot:${account.accountId}] Failed to send startup greetings: ${err}`);
+            }
+        })();
+    };
     // ============ P1-2: 尝试从持久化存储恢复 Session ============
     // 传入当前 appId，如果 appId 已变更（换了机器人），旧 session 自动失效
     const savedSession = loadSession(account.accountId, account.appId);
@@ -484,18 +583,41 @@ export async function startGateway(ctx) {
             // 命中插件级指令，直接回复
             log?.info(`[qqbot:${account.accountId}] Slash command matched: ${content}, replying directly`);
             const token = await getAccessToken(account.appId, account.clientSecret);
+            // 解析回复：纯文本 or 带文件的结果
+            const isFileResult = typeof reply === "object" && reply !== null && "filePath" in reply;
+            const replyText = isFileResult ? reply.text : reply;
+            const replyFile = isFileResult ? reply.filePath : null;
+            // 先发送文本回复
             if (msg.type === "c2c") {
-                await sendC2CMessage(token, msg.senderId, reply, msg.messageId);
+                await sendC2CMessage(token, msg.senderId, replyText, msg.messageId);
             }
             else if (msg.type === "group" && msg.groupOpenid) {
-                await sendGroupMessage(token, msg.groupOpenid, reply, msg.messageId);
+                await sendGroupMessage(token, msg.groupOpenid, replyText, msg.messageId);
             }
             else if (msg.channelId) {
-                await sendChannelMessage(token, msg.channelId, reply, msg.messageId);
+                await sendChannelMessage(token, msg.channelId, replyText, msg.messageId);
             }
             else if (msg.type === "dm") {
-                // 频道私信走 C2C
-                await sendC2CMessage(token, msg.senderId, reply, msg.messageId);
+                await sendC2CMessage(token, msg.senderId, replyText, msg.messageId);
+            }
+            // 如果有文件需要发送
+            if (replyFile) {
+                try {
+                    const targetType = msg.type === "group" ? "group" : msg.type === "c2c" || msg.type === "dm" ? "c2c" : "channel";
+                    const targetId = msg.type === "group" ? (msg.groupOpenid || msg.senderId) : msg.type === "c2c" || msg.type === "dm" ? msg.senderId : (msg.channelId || msg.senderId);
+                    const mediaCtx = {
+                        targetType,
+                        targetId,
+                        account,
+                        replyToId: msg.messageId,
+                        logPrefix: `[qqbot:${account.accountId}]`,
+                    };
+                    await sendDocument(mediaCtx, replyFile);
+                    log?.info(`[qqbot:${account.accountId}] Slash command file sent: ${replyFile}`);
+                }
+                catch (fileErr) {
+                    log?.error(`[qqbot:${account.accountId}] Failed to send slash command file: ${fileErr}`);
+                }
             }
         }
         catch (err) {
@@ -923,7 +1045,7 @@ export async function startGateway(ctx) {
                 // TTS 能力声明：仅在启用时告知 AI 可以发语音（与 qqbot-media SKILL.md 互补）
                 // STT 无需声明：转写结果已在动态上下文的 ASR 行中，AI 自然可见
                 if (hasTTS)
-                    staticParts.push("语音合成已启用，可用<qqmedia>发送语音");
+                    staticParts.push("语音合成已启用，发送媒体格式：<qqmedia>路径</qqmedia>");
                 const staticInstruction = staticParts.join(" | ");
                 // 静态指引作为 systemPrompts 的首项注入
                 systemPrompts.unshift(staticInstruction);
@@ -2190,49 +2312,23 @@ export async function startGateway(ctx) {
                                     appId: account.appId,
                                 });
                                 onReady?.(d);
-                                // 启动成功后向已知用户发送上线通知（异步，不阻塞主流程）
-                                (async () => {
-                                    try {
-                                        const greeting = `Haha，我的'灵魂'已上线，随时等你吩咐。`;
-                                        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));
-                                        }
-                                        log?.info(`[qqbot:${account.accountId}] Startup greetings sent (${users.length} c2c, ${sentGroups.size} groups)`);
-                                    }
-                                    catch (err) {
-                                        log?.error(`[qqbot:${account.accountId}] Failed to send startup greetings: ${err}`);
-                                    }
-                                })();
+                                // 仅 startGateway 后的首次 READY 才发送上线通知
+                                // ws 断线重连（resume 失败后重新 Identify）产生的 READY 不发送
+                                if (!isFirstReadyGlobal) {
+                                    log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (reconnect READY, not first startup)`);
+                                }
+                                else {
+                                    isFirstReadyGlobal = false;
+                                    sendStartupGreetings("READY");
+                                } // end isFirstReady
                             }
                             else if (t === "RESUMED") {
                                 log?.info(`[qqbot:${account.accountId}] Session resumed`);
+                                // RESUMED 也属于首次启动（gateway restart 通常走 resume）
+                                if (isFirstReadyGlobal) {
+                                    isFirstReadyGlobal = false;
+                                    sendStartupGreetings("RESUMED");
+                                }
                                 // P1-2: 更新 Session 连接时间
                                 if (sessionId) {
                                     saveSession({

package/dist/src/slash-commands.d.ts

@@ -51,11 +51,19 @@ export interface QueueSnapshot {
     /** 当前发送者在队列中的待处理消息数 */
     senderPending: number;
 }
+/** 斜杠指令返回值：文本、带文件的结果、或 null（不处理） */
+export type SlashCommandResult = string | SlashCommandFileResult | null;
+/** 带文件的指令结果（先回复文本，再发送文件） */
+export interface SlashCommandFileResult {
+    text: string;
+    /** 要发送的本地文件路径 */
+    filePath: string;
+}
 /**
  * 尝试匹配并执行插件级斜杠指令
  *
  * @returns 回复文本（匹配成功），null（不匹配，应入队正常处理）
  */
-export declare function matchSlashCommand(ctx: SlashCommandContext): Promise<string | null>;
+export declare function matchSlashCommand(ctx: SlashCommandContext): Promise<SlashCommandResult>;
 /** 获取插件版本号（供外部使用） */
 export declare function getPluginVersion(): string;

package/dist/src/slash-commands.js

@@ -11,13 +11,11 @@
  *   从而计算「开平→插件」和「插件处理」两段耗时
  */
 import { createRequire } from "node:module";
-import { execFile, spawn } from "node:child_process";
-import { promisify } from "node:util";
+import { execFileSync } from "node:child_process";
 import path from "node:path";
 import fs from "node:fs";
-import { fileURLToPath } from "node:url";
+import { getUpdateInfo } from "./update-checker.js";
 const require = createRequire(import.meta.url);
-const execFileAsync = promisify(execFile);
 // 读取 package.json 中的版本号
 let PLUGIN_VERSION = "unknown";
 try {
@@ -27,6 +25,32 @@ try {
 catch {
     // fallback
 }
+// 获取 openclaw 框架版本（缓存结果，只执行一次）
+let _frameworkVersion = null;
+function getFrameworkVersion() {
+    if (_frameworkVersion !== null)
+        return _frameworkVersion;
+    try {
+        for (const cli of ["openclaw", "clawdbot", "moltbot"]) {
+            try {
+                const out = execFileSync(cli, ["--version"], { timeout: 3000, encoding: "utf8" }).trim();
+                // 输出格式: "OpenClaw 2026.3.13 (61d171a)"
+                if (out) {
+                    _frameworkVersion = out;
+                    return _frameworkVersion;
+                }
+            }
+            catch {
+                continue;
+            }
+        }
+    }
+    catch {
+        // fallback
+    }
+    _frameworkVersion = "unknown";
+    return _frameworkVersion;
+}
 // ============ 指令注册表 ============
 const commands = new Map();
 function registerCommand(cmd) {
@@ -34,103 +58,152 @@ function registerCommand(cmd) {
 }
 // ============ 内置指令 ============
 /**
- * /ping — 轻量连通性检查
+ * /qqbot-ping — 测试当前 openclaw 与 QQ 连接的网络延迟
  */
 registerCommand({
-    name: "ping",
-    description: "连通性检查",
+    name: "qqbot-ping",
+    description: "测试当前 openclaw 与 QQ 连接的网络延迟",
     handler: (ctx) => {
         const now = Date.now();
         const eventTime = new Date(ctx.eventTimestamp).getTime();
-        const latency = isNaN(eventTime) ? "N/A" : `${now - eventTime}ms`;
-        return `🏓 pong! (${latency})`;
+        if (isNaN(eventTime)) {
+            return `🏓 pong!`;
+        }
+        const totalMs = now - eventTime;
+        const qqToPlugin = ctx.receivedAt - eventTime;
+        const pluginProcess = now - ctx.receivedAt;
+        const lines = [
+            `🏓 pong！`,
+            ``,
+            `⏱ 延迟: ${totalMs}ms`,
+            `  ├ 网络传输: ${qqToPlugin}ms`,
+            `  └ 插件处理: ${pluginProcess}ms`,
+        ];
+        return lines.join("\n");
     },
 });
 /**
- * /version — 版本号
+ * /qqbot-version — 查看插件版本号
  */
 registerCommand({
-    name: "version",
-    description: "插件版本号",
+    name: "qqbot-version",
+    description: "查看插件版本号",
     handler: () => {
-        return `QQBot Plugin v${PLUGIN_VERSION}`;
+        const frameworkVersion = getFrameworkVersion();
+        const lines = [
+            `🦞 框架: ${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(`✅ 当前已是最新版本`);
+        }
+        return lines.join("\n");
     },
 });
 /**
- * /help — 列出所有插件级斜杠指令
+ * /qqbot-help — 查看所有指令以及用途
  */
 registerCommand({
-    name: "help",
-    description: "列出所有插件级斜杠指令",
-    handler: (ctx) => {
-        const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
+    name: "qqbot-help",
+    description: "查看所有指令以及用途",
+    handler: () => {
         const lines = [`**qqbot 插件 v${PLUGIN_VERSION}**`, ``];
         for (const [name, cmd] of commands) {
             lines.push(`- \`/${name}\` — ${cmd.description}`);
         }
-        lines.push(``, `**升级指引**: ${url}`);
         return lines.join("\n");
     },
 });
-const DEFAULT_UPGRADE_URL = "https://github.com/tencent-connect/openclaw-qqbot";
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const UPGRADE_SCRIPT = path.resolve(__dirname, "../scripts/upgrade-via-npm.sh");
+const DEFAULT_UPGRADE_URL = "https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg";
+/** 升级说明文本 */
+function getUpgradeGuide(url) {
+    return `📖 升级指引:\n${url}`;
+}
 /**
- * /upgrade [version] — 触发插件版本升级
- * 无参数: 升级到 latest
- * 带参数: 升级到指定版本，如 /upgrade 1.6.1
+ * /qqbot-upgrade — 查看版本更新状态 + 升级指引
  */
 registerCommand({
-    name: "upgrade",
-    description: "升级插件版本（/upgrade [版本号]）",
-    handler: async (ctx) => {
-        const targetVersion = ctx.args.trim();
-        const scriptArgs = targetVersion ? ["--version", targetVersion] : [];
-        let upgradeOk = false;
-        let report = "";
-        try {
-            const { stdout, stderr } = await execFileAsync("bash", [UPGRADE_SCRIPT, ...scriptArgs], {
-                timeout: 120_000,
-                env: { ...process.env, PATH: process.env.PATH },
-            });
-            const output = (stdout + stderr).trim();
-            // 从脚本输出解析报告文本（QQBOT_REPORT=...）和版本号
-            const reportMatch = output.match(/QQBOT_REPORT=(.+)/);
-            const versionMatch = output.match(/QQBOT_NEW_VERSION=(\S+)/);
-            const newVersion = versionMatch?.[1] || "unknown";
-            report = reportMatch?.[1] || `✅ QQBot 升级完成: v${newVersion}`;
-            upgradeOk = newVersion !== "unknown" && newVersion !== PLUGIN_VERSION;
-            if (!upgradeOk && newVersion === PLUGIN_VERSION) {
-                report = `ℹ️ 已是最新版本 v${PLUGIN_VERSION}`;
-            }
+    name: "qqbot-upgrade",
+    description: "查看版本更新与升级指引",
+    handler: (ctx) => {
+        const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
+        const info = getUpdateInfo();
+        const lines = [];
+        if (info.checkedAt === 0) {
+            lines.push(`🤖 当前版本: v${PLUGIN_VERSION}`);
+            lines.push(`⏳ 版本检查中，请稍后再试`);
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            report = `❌ 升级失败: ${msg}`;
+        else if (info.error) {
+            lines.push(`🤖 当前版本: v${PLUGIN_VERSION}`);
+            lines.push(`⚠️ 版本检查失败`);
         }
-        if (upgradeOk) {
-            setTimeout(() => {
-                try {
-                    updatePluginsInstalls();
+        else if (info.hasUpdate && info.latest) {
+            lines.push(`🤖 当前版本: v${PLUGIN_VERSION}`);
+            lines.push(`🆕 最新版本: v${info.latest}`);
+        }
+        else {
+            lines.push(`✅ 当前已是最新版本 v${PLUGIN_VERSION}`);
+        }
+        lines.push("", getUpgradeGuide(url));
+        return lines.join("\n");
+    },
+});
+/**
+ * /qqbot-logs — 打包本地最近 2000 行日志，发送文件给用户
+ */
+registerCommand({
+    name: "qqbot-logs",
+    description: "打包本地最近 2000 行日志，发送文件给用户",
+    handler: () => {
+        const homeDir = process.env.HOME || "~";
+        const logDir = path.join(homeDir, ".openclaw", "logs");
+        const gatewayLog = path.join(logDir, "gateway.log");
+        const errLog = path.join(logDir, "gateway.err.log");
+        const lines = [];
+        // 读取 gateway.log 最后 2000 行
+        for (const logFile of [gatewayLog, errLog]) {
+            if (!fs.existsSync(logFile))
+                continue;
+            try {
+                const content = fs.readFileSync(logFile, "utf8");
+                const allLines = content.split("\n");
+                const tail = allLines.slice(-1000); // 每个文件取最后 1000 行
+                if (tail.length > 0) {
+                    lines.push(`\n========== ${path.basename(logFile)} (last ${tail.length} lines) ==========\n`);
+                    lines.push(...tail);
                 }
-                catch { }
-                const cliNames = ["openclaw", "clawdbot", "moltbot"];
-                const tryRestart = (idx) => {
-                    if (idx >= cliNames.length) {
-                        process.exit(0);
-                        return;
-                    }
-                    const cli = cliNames[idx];
-                    const child = spawn(cli, ["gateway", "restart"], {
-                        detached: true, stdio: "ignore", env: process.env,
-                    });
-                    child.on("error", () => tryRestart(idx + 1));
-                    child.unref();
-                };
-                tryRestart(0);
-            }, 2000);
+            }
+            catch {
+                lines.push(`[读取 ${path.basename(logFile)} 失败]`);
+            }
         }
-        return report;
+        if (lines.length === 0) {
+            return "⚠️ 未找到日志文件";
+        }
+        // 写入临时文件
+        const tmpDir = path.join(homeDir, ".openclaw", "qqbot", "downloads");
+        if (!fs.existsSync(tmpDir)) {
+            fs.mkdirSync(tmpDir, { recursive: true });
+        }
+        const timestamp = new Date().toISOString().replace(/[:.]/g, "-").slice(0, 19);
+        const tmpFile = path.join(tmpDir, `qqbot-logs-${timestamp}.txt`);
+        fs.writeFileSync(tmpFile, lines.join("\n"), "utf8");
+        const totalLines = lines.filter(l => !l.startsWith("=")).length;
+        return {
+            text: `📋 日志已打包（约 ${totalLines} 行），正在发送文件...`,
+            filePath: tmpFile,
+        };
     },
 });
 // ============ 匹配入口 ============
@@ -158,54 +231,3 @@ export async function matchSlashCommand(ctx) {
 export function getPluginVersion() {
     return PLUGIN_VERSION;
 }
-/**
- * 更新 openclaw.json 中的 plugins.installs 记录。
- * - 如果 source 是 "path"（开发目录），改为 "npm" 并删除 sourcePath
- * - 更新 installPath、version、installedAt
- */
-function updatePluginsInstalls() {
-    const cliNames = ["openclaw", "clawdbot", "moltbot"];
-    let configPath = "";
-    let cliName = "";
-    for (const name of cliNames) {
-        const candidate = path.join(process.env.HOME || "~", `.${name}`, `${name}.json`);
-        if (fs.existsSync(candidate)) {
-            configPath = candidate;
-            cliName = name;
-            break;
-        }
-    }
-    if (!configPath)
-        return;
-    const cfg = JSON.parse(fs.readFileSync(configPath, "utf8"));
-    const extensionsDir = path.join(process.env.HOME || "~", `.${cliName}`, "extensions");
-    const installPath = path.join(extensionsDir, "openclaw-qqbot");
-    // 读取新安装的版本号
-    let newVersion = "unknown";
-    try {
-        const pkgPath = path.join(installPath, "package.json");
-        if (fs.existsSync(pkgPath)) {
-            newVersion = JSON.parse(fs.readFileSync(pkgPath, "utf8")).version || "unknown";
-        }
-    }
-    catch { }
-    cfg.plugins = cfg.plugins || {};
-    cfg.plugins.installs = cfg.plugins.installs || {};
-    const existing = cfg.plugins.installs["openclaw-qqbot"] || {};
-    // 保留已有记录，只更新关键字段
-    cfg.plugins.installs["openclaw-qqbot"] = {
-        ...existing,
-        source: "npm",
-        installPath,
-        version: newVersion,
-        installedAt: new Date().toISOString(),
-    };
-    // 如果之前是 source:"path"，清除 sourcePath（指向开发目录）
-    delete cfg.plugins.installs["openclaw-qqbot"].sourcePath;
-    // 确保 plugins.entries 存在
-    cfg.plugins.entries = cfg.plugins.entries || {};
-    if (!cfg.plugins.entries["openclaw-qqbot"]) {
-        cfg.plugins.entries["openclaw-qqbot"] = { enabled: true };
-    }
-    fs.writeFileSync(configPath, JSON.stringify(cfg, null, 4) + "\n");
-}

package/dist/src/types.d.ts

@@ -58,7 +58,7 @@ export interface QQBotAccountConfig {
      */
     urlDirectUpload?: boolean;
     /**
-     * /upgrade 指令返回的升级指引网址
+     * /qqbot-upgrade 指令返回的升级指引网址
      * 默认: https://github.com/tencent-connect/openclaw-qqbot
      */
     upgradeUrl?: string;

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

@@ -0,0 +1,21 @@
+/**
+ * 后台版本检查器
+ *
+ * - triggerUpdateCheck(): gateway 启动时调用，后台检查 npm registry 是否有新版本
+ * - getUpdateInfo(): 返回上次检查结果（供 /qqbot-version、/qqbot-help 指令使用）
+ * - formatUpdateNotice(): 格式化更新提示文本
+ */
+export interface UpdateInfo {
+    current: string;
+    latest: string | null;
+    hasUpdate: boolean;
+    checkedAt: number;
+    error?: string;
+}
+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;