@tencent-connect/openclaw-qqbot 1.6.4-alpha.11 → 1.6.4-alpha.13

package/README.md

@@ -10,7 +10,7 @@
 
 **Connect your AI assistant to QQ — private chat, group chat, and rich media, all in one plugin.**
 
-### 🚀 Current Version: `v1.6.2`
+### 🚀 Current Version: `v1.6.4`
 
 [![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/)
@@ -36,13 +36,13 @@ Scan to join the QQ group chat
 
 | Feature | Description |
 |---------|-------------|
-| 🔒 **Multi-Scene** | C2C private chat, group @messages, channel messages, channel DMs |
+| 🔒 **Multi-Scene** | C2C private chat, group @messages |
 | 🖼️ **Rich Media** | Send & receive images, voice, video, and files |
 | 🎙️ **Voice (STT/TTS)** | Speech-to-text transcription & text-to-speech replies |
+| 🔥 **One-Click Hot Upgrade** | Send `/bot-upgrade` in private chat to upgrade — no server login needed |
 | ⏰ **Scheduled Push** | Proactive message delivery via scheduled tasks |
 | 🔗 **URL Support** | Direct URL sending in private chat (no restrictions) |
 | ⌨️ **Typing Indicator** | "Bot is typing..." status shown in real-time |
-| 🔄 **Hot Reload** | Install via npm with seamless hot updates |
 | 📝 **Markdown** | Full Markdown formatting support |
 | 🛠️ **Commands** | Native OpenClaw command integration |
 | 💬 **Quoted Context** | Resolve QQ `REFIDX_*` quoted messages and inject quote body into AI context |
@@ -177,15 +177,24 @@ Shows framework version, plugin version, and a direct link to the official repos
 
 <img width="360" src="docs/images/slash-help.jpg" alt="Help Demo" />
 
-#### `/bot-upgrade` — Upgrade Guide
+#### `/bot-upgrade` — One-Click Hot Upgrade
 
 > **You**: `/bot-upgrade`
 >
-> **QQBot**: 📌 Current version / ✅ Up to date / ⬆️ Upgrade guide / 🌟 GitHub repo
+> **QQBot**: 📌 Current: v1.6.4-alpha.12 / ✅ New version v1.6.4 available / Click button below to confirm
 
-Shows current version, update status, upgrade guide link, and official repository.
+Send in private chat to upgrade the plugin without server login. Supported usage:
 
-<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade Demo" /> 
+| Command | Description |
+|---------|-------------|
+| `/bot-upgrade` | Check for updates, show confirmation button |
+| `/bot-upgrade --latest` | Confirm upgrade to the latest version |
+| `/bot-upgrade --version 1.6.4` | Upgrade to a specific version |
+| `/bot-upgrade --force` | Force reinstall current version |
+
+Credentials are automatically backed up before upgrade. Version existence is verified against npm before proceeding. Auto-recovery on failure.
+
+<!-- TODO: add /bot-upgrade screenshot -->
 
 #### `/bot-logs` — Log Export
 
@@ -197,6 +206,14 @@ 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" />
 
+#### Usage Help
+
+All commands support a `?` suffix to show usage:
+
+> **You**: `/bot-upgrade ?`
+>
+> **QQBot**: 📖 /bot-upgrade usage: …
+
 ---
 
 ## 🚀 Getting Started

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.2`
+### 🚀 当前版本： `v1.6.4`
 
 [![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/)
@@ -31,13 +31,13 @@
 
 | 功能 | 说明 |
 |------|------|
-| 🔒 **多场景支持** | C2C 私聊、群聊 @消息、频道消息、频道私信 |
+| 🔒 **多场景支持** | C2C 私聊、群聊 @消息 |
 | 🖼️ **富媒体消息** | 支持图片、语音、视频、文件的收发 |
 | 🎙️ **语音能力 (STT/TTS)** | 语音转文字自动转录 & 文字转语音回复 |
+| 🔥 **一键热更新** | 私聊发送 `/bot-upgrade` 即可完成版本升级，无需登录服务器 |
 | ⏰ **定时推送** | 支持定时任务触发后主动推送消息 |
 | 🔗 **URL 无限制** | 私聊可直接发送 URL |
 | ⌨️ **输入状态** | 实时显示"Bot 正在输入中…"状态 |
-| 🔄 **热更新** | 支持 npm 方式安装和无缝热更新 |
 | 📝 **Markdown** | 完整支持 Markdown 格式消息 |
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
 | 💬 **引用上下文** | 解析 QQ `REFIDX_*` 引用消息，并将引用内容注入 AI 上下文 |
@@ -172,15 +172,24 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 
 <img width="360" src="docs/images/slash-help.jpg" alt="Help 演示" />
 
-#### `/bot-upgrade` — 升级指引
+#### `/bot-upgrade` — 一键热更新
 
 > **你**：`/bot-upgrade`
 >
-> **QQBot**：📌当前版本 / ✅当前已是最新版本 / ⬆️升级指引 / 🌟官方 GitHub 仓库
+> **QQBot**：📌当前版本 v1.6.4-alpha.12 / ✅发现新版本 v1.6.4 / 点击下方按钮确认升级
 
-显示当前版本、更新状态、升级文档链接及官方仓库入口。
+在私聊中发送即可完成版本升级，全程无需登录服务器。支持的用法：
 
-<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade 演示" /> 
+| 命令 | 说明 |
+|------|------|
+| `/bot-upgrade` | 检查是否有新版本，展示确认按钮 |
+| `/bot-upgrade --latest` | 确认升级到最新版本 |
+| `/bot-upgrade --version 1.6.4` | 升级到指定版本 |
+| `/bot-upgrade --force` | 强制重新安装当前版本 |
+
+升级流程自动备份凭证，升级前校验版本是否存在于 npm，升级失败自动恢复。
+
+<!-- TODO: 补充 /bot-upgrade 截图 -->
 
 #### `/bot-logs` — 日志导出
 
@@ -192,6 +201,14 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 
 <img width="360" src="docs/images/slash-logs.jpg" alt="Logs 演示" />
 
+#### 用法查询
+
+所有指令都支持 `?` 后缀查看用法说明：
+
+> **你**：`/bot-upgrade ?`
+>
+> **QQBot**：📖 /bot-upgrade 用法：…
+
 ---
 
 ## 🚀 快速开始

package/dist/src/channel.js

@@ -59,7 +59,13 @@ export const qqbotPlugin = {
             accountId,
             clearBaseFields: ["appId", "clientSecret", "clientSecretFile", "name"],
         }),
-        isConfigured: (account) => Boolean(account?.appId && account?.clientSecret),
+        isConfigured: (account) => {
+            if (account?.appId && account?.clientSecret)
+                return true;
+            // 配置为空但有凭证备份时仍返回 true，让 startAccount 有机会恢复凭证
+            const backup = loadCredentialBackup(account?.accountId);
+            return backup !== null;
+        },
         describeAccount: (account) => ({
             accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
             name: account?.name,

package/dist/src/slash-commands.js

@@ -54,6 +54,103 @@ function getFrameworkVersion() {
     _frameworkVersion = "unknown";
     return _frameworkVersion;
 }
+// ============ 热更新兼容性检查 ============
+/**
+ * 热更新可执行的环境要求：
+ * - 最低 OpenClaw 框架版本
+ * - 支持的操作系统
+ * - 最低 Node.js 版本
+ */
+const UPGRADE_REQUIREMENTS = {
+    /** OpenClaw 最低版本（YYYY.M.D 格式，如 "2026.3.10"） */
+    minFrameworkVersion: "2026.3.10",
+    /** 支持的操作系统列表（process.platform 值） */
+    supportedPlatforms: ["darwin", "linux", "win32"],
+    /** 最低 Node.js 版本 */
+    minNodeVersion: "18.0.0",
+};
+/**
+ * 解析框架版本字符串中的日期版本号
+ * 输入示例: "OpenClaw 2026.3.13 (61d171a)" → "2026.3.13"
+ */
+function parseFrameworkDateVersion(versionStr) {
+    const m = versionStr.match(/(\d{4}\.\d{1,2}\.\d{1,2})/);
+    return m ? m[1] : null;
+}
+/**
+ * 比较 YYYY.M.D 格式的版本号
+ * @returns >0 if a > b, <0 if a < b, 0 if equal
+ */
+function compareDateVersions(a, b) {
+    const pa = a.split(".").map(Number);
+    const pb = b.split(".").map(Number);
+    for (let i = 0; i < 3; i++) {
+        const diff = (pa[i] || 0) - (pb[i] || 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * 比较 semver 版本号（简化版，仅比较 major.minor.patch）
+ */
+function compareSemver(a, b) {
+    const parse = (v) => v.replace(/^v/, "").split(".").map(Number);
+    const pa = parse(a);
+    const pb = parse(b);
+    for (let i = 0; i < 3; i++) {
+        const diff = (pa[i] || 0) - (pb[i] || 0);
+        if (diff !== 0)
+            return diff;
+    }
+    return 0;
+}
+/**
+ * 检查当前环境是否满足热更新要求
+ */
+function checkUpgradeCompatibility() {
+    const errors = [];
+    const req = UPGRADE_REQUIREMENTS;
+    // 1. 检查操作系统
+    const platform = process.platform;
+    if (!req.supportedPlatforms.includes(platform)) {
+        const supported = req.supportedPlatforms.map(p => {
+            if (p === "darwin")
+                return "macOS";
+            if (p === "linux")
+                return "Linux";
+            if (p === "win32")
+                return "Windows";
+            return p;
+        }).join("、");
+        const current = platform === "win32" ? "Windows"
+            : platform === "darwin" ? "macOS"
+                : platform;
+        errors.push(`❌ 当前操作系统 **${current}** 不支持热更新（支持：${supported}）`);
+    }
+    // 2. 检查 OpenClaw 框架版本
+    const fwVersion = getFrameworkVersion();
+    if (fwVersion === "unknown") {
+        errors.push(`⚠️ 无法检测 OpenClaw 框架版本，热更新可能失败`);
+    }
+    else {
+        const dateVer = parseFrameworkDateVersion(fwVersion);
+        if (dateVer && compareDateVersions(dateVer, req.minFrameworkVersion) < 0) {
+            errors.push(`❌ OpenClaw 框架版本过低：当前 **${dateVer}**，热更新要求最低 **${req.minFrameworkVersion}**。请先升级框架：\`openclaw upgrade\``);
+        }
+    }
+    // 3. 检查 Node.js 版本
+    const nodeVer = process.version.replace(/^v/, "");
+    if (compareSemver(nodeVer, req.minNodeVersion) < 0) {
+        errors.push(`❌ Node.js 版本过低：当前 **v${nodeVer}**，热更新要求最低 **v${req.minNodeVersion}**`);
+    }
+    // 4. 检查系统架构（arm 等特殊架构提示）
+    const arch = process.arch;
+    if (arch !== "x64" && arch !== "arm64") {
+        errors.push(`⚠️ 当前 CPU 架构 **${arch}** 未经充分测试，热更新可能存在兼容性问题`);
+    }
+    return { ok: errors.length === 0, errors };
+}
 // ============ 指令注册表 ============
 const commands = new Map();
 function registerCommand(cmd) {
@@ -103,13 +200,13 @@ registerCommand({
         `查看当前 QQBot 插件版本和 OpenClaw 框架版本。`,
         `同时检查是否有新版本可用。`,
     ].join("\n"),
-    handler: () => {
+    handler: async () => {
         const frameworkVersion = getFrameworkVersion();
         const lines = [
             `🦞框架版本：${frameworkVersion}`,
             `🤖QQBot 插件版本：v${PLUGIN_VERSION}`,
         ];
-        const info = getUpdateInfo();
+        const info = await getUpdateInfo();
         if (info.checkedAt === 0) {
             lines.push(`⏳ 版本检查中...`);
         }
@@ -180,18 +277,20 @@ function findCli() {
 }
 /**
  * 找到升级脚本路径（兼容源码运行、dist 运行、已安装扩展目录）
+ * Windows 优先查找 .ps1，Mac/Linux 查找 .sh
  */
 function getUpgradeScriptPath() {
     const currentFile = fileURLToPath(import.meta.url);
     const currentDir = path.dirname(currentFile);
+    const scriptName = isWindows() ? "upgrade-via-npm.ps1" : "upgrade-via-npm.sh";
     const candidates = [
-        path.resolve(currentDir, "..", "..", "scripts", "upgrade-via-npm.sh"),
-        path.resolve(currentDir, "..", "scripts", "upgrade-via-npm.sh"),
-        path.resolve(process.cwd(), "scripts", "upgrade-via-npm.sh"),
+        path.resolve(currentDir, "..", "..", "scripts", scriptName),
+        path.resolve(currentDir, "..", "scripts", scriptName),
+        path.resolve(process.cwd(), "scripts", scriptName),
     ];
     const homeDir = getHomeDir();
     for (const cli of ["openclaw", "clawdbot", "moltbot"]) {
-        candidates.push(path.join(homeDir, `.${cli}`, "extensions", "openclaw-qqbot", "scripts", "upgrade-via-npm.sh"));
+        candidates.push(path.join(homeDir, `.${cli}`, "extensions", "openclaw-qqbot", "scripts", scriptName));
     }
     for (const p of candidates) {
         if (fs.existsSync(p))
@@ -201,6 +300,7 @@ function getUpgradeScriptPath() {
 }
 /**
  * 在 Windows 上查找可用的 bash（Git Bash / WSL 等）
+ * 仅作为 Windows 上的 fallback（优先使用 PowerShell）
  */
 function findBash() {
     if (!isWindows())
@@ -227,6 +327,8 @@ function findBash() {
 /**
  * 将 openclaw.json 中的 qqbot 插件 source 从 "path" 切换为 "npm"。
  * 用于热更新场景：从 npm 拉取新版本后，确保 openclaw 不再从本地源码加载。
+ *
+ * 安全保障：写回配置前验证 channels.qqbot 未丢失，防止竞态写入导致凭证消失。
  */
 function switchPluginSourceToNpm() {
     try {
@@ -235,13 +337,26 @@ function switchPluginSourceToNpm() {
             const cfgPath = path.join(homeDir, `.${cli}`, `${cli}.json`);
             if (!fs.existsSync(cfgPath))
                 continue;
-            const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf8"));
+            // 读取当前配置
+            const raw = fs.readFileSync(cfgPath, "utf8");
+            const cfg = JSON.parse(raw);
             const inst = cfg?.plugins?.installs?.["openclaw-qqbot"];
-            if (inst && inst.source !== "npm") {
-                inst.source = "npm";
-                delete inst.sourcePath;
-                fs.writeFileSync(cfgPath, JSON.stringify(cfg, null, 4) + "\n");
+            if (!inst || inst.source === "npm") {
+                break; // 无需修改
             }
+            // 记录修改前的 channels.qqbot 快照，用于写后校验
+            const channelsBefore = JSON.stringify(cfg.channels?.qqbot ?? null);
+            inst.source = "npm";
+            delete inst.sourcePath;
+            const newRaw = JSON.stringify(cfg, null, 4) + "\n";
+            // 写后校验：重新解析确认 channels.qqbot 未被破坏
+            const verify = JSON.parse(newRaw);
+            const channelsAfter = JSON.stringify(verify.channels?.qqbot ?? null);
+            if (channelsBefore !== channelsAfter) {
+                // channels 数据异常，放弃写入
+                break;
+            }
+            fs.writeFileSync(cfgPath, newRaw);
             break;
         }
     }
@@ -285,17 +400,31 @@ function preUpgradeCredentialBackup(accountId, appId) {
         // 非关键操作，静默忽略
     }
 }
+/**
+ * 在 Windows 上查找 PowerShell（pwsh 优先，powershell.exe 兜底）
+ */
+function findPowerShell() {
+    // pwsh = PowerShell 7+（跨平台），powershell.exe = Windows 内置 5.1
+    for (const ps of ["pwsh", "powershell"]) {
+        try {
+            execFileSync("where", [ps], { timeout: 3000, encoding: "utf8", stdio: "pipe" });
+            return ps;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
 /**
  * 执行热更新：执行脚本(--no-restart) → 立即触发 gateway restart
  *
  * fire-and-forget 操作：
- * - 异步执行升级脚本（--no-restart，只做文件替换）
+ * - 异步执行升级脚本（--no-restart / -NoRestart，只做文件替换）
  * - 脚本完成后**立即**触发 gateway restart（当前进程会被杀掉）
  * - 新进程启动时 getStartupGreeting() 检测到版本变更，自动通知管理员
  *
- * 注意：gateway restart 必须在文件替换完成后尽快执行，
- * 否则 openclaw 的配置热加载轮询（~1s）会不断检测到插件目录
- * 已变更但进程未重启，从而产生 "plugin not found" warning 刷屏。
+ * Windows 使用 PowerShell 执行 .ps1 脚本，Mac/Linux 使用 bash 执行 .sh 脚本。
  */
 function fireHotUpgrade(targetVersion) {
     const scriptPath = getUpgradeScriptPath();
@@ -304,11 +433,31 @@ function fireHotUpgrade(targetVersion) {
     const cli = findCli();
     if (!cli)
         return { ok: false, reason: "no-cli" };
-    const bash = findBash();
-    if (!bash)
-        return { ok: false, reason: "no-bash" };
+    let shell;
+    let shellArgs;
+    if (isWindows()) {
+        // Windows: PowerShell 执行 .ps1
+        const ps = findPowerShell();
+        if (!ps)
+            return { ok: false, reason: "no-powershell" };
+        shell = ps;
+        shellArgs = [
+            "-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass",
+            "-File", scriptPath,
+            "-NoRestart",
+            ...(targetVersion ? ["-Version", targetVersion] : []),
+        ];
+    }
+    else {
+        // Mac / Linux: bash 执行 .sh
+        const bash = findBash();
+        if (!bash)
+            return { ok: false, reason: "no-bash" };
+        shell = bash;
+        shellArgs = [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : [])];
+    }
     // 异步执行升级脚本
-    execFile(bash, [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : [])], {
+    execFile(shell, shellArgs, {
         timeout: 120_000,
         env: { ...process.env },
         ...(isWindows() ? { windowsHide: true } : {}),
@@ -325,10 +474,8 @@ function fireHotUpgrade(targetVersion) {
         }
         // 文件替换成功，在 restart 之前把 source 从 path 切换为 npm，
         // 确保新进程启动时读到的是 npm source，不会被本地源码覆盖。
-        // 必须在 restart 之前同步完成，避免 openclaw 轮询检测到配置变更后
-        // 先于我们的 restart 触发非预期的 reload。
         switchPluginSourceToNpm();
-        // 文件替换成功，立即触发 gateway restart（不再等后续步骤）
+        // 文件替换成功，立即触发 gateway restart
         execFile(cli, ["gateway", "restart"], { timeout: 30_000 }, (restartErr) => {
             if (restartErr) {
                 // restart 失败，尝试 stop + start 作为 fallback
@@ -362,6 +509,11 @@ registerCommand({
         `/bot-upgrade --force      强制重新安装当前版本`,
         ``,
         `⚠️ 仅在私聊中可用。升级过程约 30~60 秒，期间服务短暂不可用。`,
+        ``,
+        `环境要求：`,
+        `  - 操作系统：macOS / Linux / Windows`,
+        `  - OpenClaw 框架版本 ≥ ${UPGRADE_REQUIREMENTS.minFrameworkVersion}`,
+        `  - Node.js ≥ v${UPGRADE_REQUIREMENTS.minNodeVersion}`,
     ].join("\n"),
     handler: async (ctx) => {
         // 升级相关指令仅在私聊中可用
@@ -374,7 +526,7 @@ registerCommand({
         }
         const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
         const args = ctx.args.trim();
-        const info = getUpdateInfo();
+        const info = await getUpdateInfo();
         let isForce = false;
         let isLatest = false;
         let versionArg;
@@ -475,6 +627,17 @@ registerCommand({
             }
         }
         const targetVersion = versionArg || info.latest || undefined;
+        // ── 环境兼容性检查 ──
+        const compat = checkUpgradeCompatibility();
+        if (!compat.ok) {
+            return [
+                `🚫 当前环境不满足热更新要求：`,
+                ``,
+                ...compat.errors,
+                ``,
+                `查看手动升级指引：[点击查看](${url})`,
+            ].join("\n");
+        }
         // 加锁
         _upgrading = true;
         // 热更新前保存凭证快照，防止更新过程被打断导致 appId/secret 丢失
@@ -497,10 +660,17 @@ registerCommand({
                     `查看手动升级指引：[点击查看](${url})`,
                 ].join("\n");
             }
+            if (startResult.reason === "no-powershell") {
+                return [
+                    `❌ 未找到 PowerShell，无法执行热更新`,
+                    ``,
+                    `请确认系统中已安装 PowerShell（Windows 10+ 自带）`,
+                    `查看手动升级指引：[点击查看](${url})`,
+                ].join("\n");
+            }
             return [
                 `❌ 当前环境不支持热更新（需要 bash）`,
                 ``,
-                `Windows 用户请安装 Git for Windows 后重试`,
                 `查看手动升级指引：[点击查看](${url})`,
             ].join("\n");
         }

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

@@ -1,8 +1,8 @@
 /**
- * 后台版本检查器
+ * 版本检查器
  *
- * - triggerUpdateCheck(): gateway 启动时调用，后台检查 npm registry 是否有新版本
- * - getUpdateInfo(): 返回上次检查结果（供 /bot-version、/bot-help 指令使用）
+ * - triggerUpdateCheck(): gateway 启动时调用，后台预热缓存
+ * - getUpdateInfo(): 每次实时查询 npm registry，返回最新结果
  *
  * 使用 HTTPS 直接请求 npm registry API（不依赖 npm CLI），
  * 支持多 registry fallback：npmjs.org → npmmirror.com，解决国内网络问题。
@@ -14,12 +14,14 @@ export interface UpdateInfo {
     checkedAt: number;
     error?: string;
 }
+/** gateway 启动时调用，保存 log 引用 */
 export declare function triggerUpdateCheck(log?: {
     info: (msg: string) => void;
     error: (msg: string) => void;
     debug?: (msg: string) => void;
 }): void;
-export declare function getUpdateInfo(): UpdateInfo;
+/** 每次实时查询 npm registry */
+export declare function getUpdateInfo(): Promise<UpdateInfo>;
 /**
  * 检查指定版本是否存在于 npm registry
  * 用于 /bot-upgrade --version 的前置校验

package/dist/src/update-checker.js

@@ -1,8 +1,8 @@
 /**
- * 后台版本检查器
+ * 版本检查器
  *
- * - triggerUpdateCheck(): gateway 启动时调用，后台检查 npm registry 是否有新版本
- * - getUpdateInfo(): 返回上次检查结果（供 /bot-version、/bot-help 指令使用）
+ * - triggerUpdateCheck(): gateway 启动时调用，后台预热缓存
+ * - getUpdateInfo(): 每次实时查询 npm registry，返回最新结果
  *
  * 使用 HTTPS 直接请求 npm registry API（不依赖 npm CLI），
  * 支持多 registry fallback：npmjs.org → npmmirror.com，解决国内网络问题。
@@ -24,13 +24,7 @@ try {
 catch {
     // fallback
 }
-let _lastInfo = {
-    current: CURRENT_VERSION,
-    latest: null,
-    hasUpdate: false,
-    checkedAt: 0,
-};
-let _checking = false;
+let _log;
 function fetchJson(url, timeoutMs) {
     return new Promise((resolve, reject) => {
         const req = https.get(url, { timeout: timeoutMs, headers: { Accept: "application/json" } }, (res) => {
@@ -54,7 +48,7 @@ function fetchJson(url, timeoutMs) {
         req.on("timeout", () => { req.destroy(); reject(new Error(`timeout fetching ${url}`)); });
     });
 }
-async function fetchDistTags(log) {
+async function fetchDistTags() {
     for (const url of REGISTRIES) {
         try {
             const json = await fetchJson(url, 10_000);
@@ -63,43 +57,42 @@ async function fetchDistTags(log) {
                 return tags;
         }
         catch (e) {
-            log?.debug?.(`[qqbot:update-checker] ${url} failed: ${e.message}`);
+            _log?.debug?.(`[qqbot:update-checker] ${url} failed: ${e.message}`);
         }
     }
     throw new Error("all registries failed");
 }
+function buildUpdateInfo(tags) {
+    const currentIsPrerelease = CURRENT_VERSION.includes("-");
+    const compareTarget = currentIsPrerelease
+        ? (tags.alpha || tags.latest || null)
+        : (tags.latest || null);
+    const hasUpdate = typeof compareTarget === "string"
+        && compareTarget !== CURRENT_VERSION
+        && compareVersions(compareTarget, CURRENT_VERSION) > 0;
+    return { current: CURRENT_VERSION, latest: compareTarget, hasUpdate, checkedAt: Date.now() };
+}
+/** gateway 启动时调用，保存 log 引用 */
 export function triggerUpdateCheck(log) {
-    if (_checking)
-        return;
-    const INTERVAL_MS = 1 * 60 * 1000;
-    if (_lastInfo.checkedAt > 0 && Date.now() - _lastInfo.checkedAt < INTERVAL_MS) {
-        return;
-    }
-    _checking = true;
-    log?.debug?.(`[qqbot:update-checker] checking (current: ${CURRENT_VERSION})...`);
-    fetchDistTags(log).then((tags) => {
-        const now = Date.now();
-        const currentIsPrerelease = CURRENT_VERSION.includes("-");
-        const compareTarget = currentIsPrerelease
-            ? (tags.alpha || tags.latest || null)
-            : (tags.latest || null);
-        const hasUpdate = typeof compareTarget === "string"
-            && compareTarget !== CURRENT_VERSION
-            && compareVersions(compareTarget, CURRENT_VERSION) > 0;
-        _lastInfo = { current: CURRENT_VERSION, latest: compareTarget, hasUpdate, checkedAt: now };
-        if (hasUpdate) {
-            log?.info?.(`[qqbot:update-checker] new version available: ${compareTarget} (current: ${CURRENT_VERSION})`);
+    if (log)
+        _log = log;
+    // 预热：fire-and-forget
+    getUpdateInfo().then((info) => {
+        if (info.hasUpdate) {
+            _log?.info?.(`[qqbot:update-checker] new version available: ${info.latest} (current: ${CURRENT_VERSION})`);
         }
-    }).catch((err) => {
-        const now = Date.now();
-        log?.debug?.(`[qqbot:update-checker] check failed: ${err.message}`);
-        _lastInfo = { current: CURRENT_VERSION, latest: null, hasUpdate: false, checkedAt: now, error: err.message };
-    }).finally(() => {
-        _checking = false;
-    });
+    }).catch(() => { });
 }
-export function getUpdateInfo() {
-    return { ..._lastInfo };
+/** 每次实时查询 npm registry */
+export async function getUpdateInfo() {
+    try {
+        const tags = await fetchDistTags();
+        return buildUpdateInfo(tags);
+    }
+    catch (err) {
+        _log?.debug?.(`[qqbot:update-checker] check failed: ${err.message}`);
+        return { current: CURRENT_VERSION, latest: null, hasUpdate: false, checkedAt: Date.now(), error: err.message };
+    }
 }
 /**
  * 检查指定版本是否存在于 npm registry

package/package.json

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