@tencent-connect/openclaw-qqbot 1.6.4-alpha.6 → 1.6.4-alpha.8

package/dist/src/gateway.js

@@ -263,8 +263,10 @@ async function ensureImageServer(log, publicBaseUrl) {
 // 区分 gateway restart（进程重启）和 health-monitor 断线重连
 let isFirstReadyGlobal = true;
 const STARTUP_MARKER_FILE = path.join(getQQBotDataDir("data"), "startup-marker.json");
-const STARTUP_GREETING_TEXT = `Haha，我的'灵魂'已上线，随时等你吩咐。`;
 const STARTUP_GREETING_RETRY_COOLDOWN_MS = 10 * 60 * 1000;
+function getStartupGreetingText(version) {
+    return `🎉 QQBot 插件已更新至 v${version}，在线等候你的吩咐。`;
+}
 function readStartupMarker() {
     try {
         if (fs.existsSync(STARTUP_MARKER_FILE)) {
@@ -303,7 +305,7 @@ function getStartupGreetingPlan() {
             return { shouldSend: false, version: currentVersion, reason: "cooldown" };
         }
     }
-    return { shouldSend: true, greeting: STARTUP_GREETING_TEXT, version: currentVersion };
+    return { shouldSend: true, greeting: getStartupGreetingText(currentVersion), version: currentVersion };
 }
 function markStartupGreetingSent(version) {
     writeStartupMarker({

package/dist/src/slash-commands.js

@@ -14,7 +14,7 @@ import { createRequire } from "node:module";
 import { execFileSync, execFile } from "node:child_process";
 import path from "node:path";
 import fs from "node:fs";
-import { getUpdateInfo } from "./update-checker.js";
+import { getUpdateInfo, checkVersionExists } from "./update-checker.js";
 import { getHomeDir, getQQBotDataDir, isWindows } from "./utils/platform.js";
 import { fileURLToPath } from "node:url";
 const require = createRequire(import.meta.url);
@@ -65,6 +65,12 @@ function registerCommand(cmd) {
 registerCommand({
     name: "bot-ping",
     description: "测试当前 openclaw 与 QQ 连接的网络延迟",
+    usage: [
+        `/bot-ping`,
+        ``,
+        `测试 OpenClaw 主机与 QQ 服务器之间的网络延迟。`,
+        `返回网络传输耗时和插件处理耗时。`,
+    ].join("\n"),
     handler: (ctx) => {
         const now = Date.now();
         const eventTime = new Date(ctx.eventTimestamp).getTime();
@@ -90,6 +96,12 @@ registerCommand({
 registerCommand({
     name: "bot-version",
     description: "查看插件版本号",
+    usage: [
+        `/bot-version`,
+        ``,
+        `查看当前 QQBot 插件版本和 OpenClaw 框架版本。`,
+        `同时检查是否有新版本可用。`,
+    ].join("\n"),
     handler: () => {
         const frameworkVersion = getFrameworkVersion();
         const lines = [
@@ -116,6 +128,12 @@ registerCommand({
 registerCommand({
     name: "bot-help",
     description: "查看所有指令以及用途",
+    usage: [
+        `/bot-help`,
+        ``,
+        `列出所有可用的 QQBot 插件内置指令及其简要说明。`,
+        `使用 /指令名 ? 可查看某条指令的详细用法。`,
+    ].join("\n"),
     handler: () => {
         const lines = [`### QQBot插件内置调试指令`, ``];
         for (const [name, cmd] of commands) {
@@ -258,25 +276,40 @@ function fireHotUpgrade(targetVersion) {
     return { ok: true };
 }
 /**
- * /bot-upgrade — 统一升级入口：能热更就热更，失败则返回升级指引
+ * /bot-upgrade — 统一升级入口
  *
- * 支持参数：
- *   /bot-upgrade           — 检查更新后自动热更
- *   /bot-upgrade 1.6.4     — 升级到指定版本
- *   /bot-upgrade --force   — 强制升级（即使当前已是最新版）
+ * 产品流程：
+ *   /bot-upgrade              — 展示版本信息+确认按钮（不直接升级）
+ *   /bot-upgrade --latest     — 确认升级到最新版本
+ *   /bot-upgrade --version X  — 升级到指定版本
+ *   /bot-upgrade --force      — 强制升级（即使当前已是最新版）
  */
+let _upgrading = false; // 升级锁
 registerCommand({
     name: "bot-upgrade",
     description: "检查更新并自动热更（失败则返回升级指引）",
-    handler: (ctx) => {
+    usage: [
+        `/bot-upgrade              检查是否有新版本（展示信息+确认按钮）`,
+        `/bot-upgrade --latest     确认升级到最新版本`,
+        `/bot-upgrade --version X  升级到指定版本（如 1.6.4-alpha.7）`,
+        `/bot-upgrade --force      强制重新安装当前版本`,
+        ``,
+        `⚠️ 仅在私聊中可用。升级过程约 30~60 秒，期间服务短暂不可用。`,
+    ].join("\n"),
+    handler: async (ctx) => {
         // 升级相关指令仅在私聊中可用
         if (ctx.type !== "c2c") {
             return `💡 请在私聊中使用此指令`;
         }
+        // 升级锁：防止重复触发
+        if (_upgrading) {
+            return `⏳ 正在升级中，请稍候...`;
+        }
         const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
         const args = ctx.args.trim();
         const info = getUpdateInfo();
         let isForce = false;
+        let isLatest = false;
         let versionArg;
         const tokens = args ? args.split(/\s+/).filter(Boolean) : [];
         for (let i = 0; i < tokens.length; i += 1) {
@@ -285,6 +318,10 @@ registerCommand({
                 isForce = true;
                 continue;
             }
+            if (t === "--latest") {
+                isLatest = true;
+                continue;
+            }
             if (t === "--version") {
                 const next = tokens[i + 1];
                 if (!next || next.startsWith("--")) {
@@ -307,21 +344,65 @@ registerCommand({
                 continue;
             }
         }
-        if (!versionArg && !isForce) {
+        const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
+        // ── 无参数（也没有 --latest / --version / --force）：只展示信息+确认按钮 ──
+        if (!versionArg && !isLatest && !isForce) {
             if (info.checkedAt === 0) {
                 return `⏳ 版本检查中，请稍后再试`;
             }
             if (info.error) {
-                return `⚠️ 版本检查失败\n⬆️升级指引：[点击查看](${url})`;
+                return `❌ 当前我的主机网络访问 GitHub 异常，查看手动升级指引：[点击查看](${url})`;
             }
             if (!info.hasUpdate) {
-                return `✅ 当前版本 v${PLUGIN_VERSION} 已是最新，无需升级\n\n> 💡 使用 /bot-upgrade --force 可强制重新安装`;
+                const lines = [
+                    `🌟 GitHub：[tencent-connect/openclaw-qqbot](${GITHUB_URL})`,
+                    `✅ 当前使用的已经是最新版本：v${PLUGIN_VERSION}`,
+                ];
+                return lines.join("\n");
+            }
+            // 有新版本：展示信息 + 确认按钮
+            const lines = [
+                `🌟 GitHub：[tencent-connect/openclaw-qqbot](${GITHUB_URL})`,
+                `📌 当前使用版本：v${PLUGIN_VERSION}`,
+                `🆕 最新可用版本：v${info.latest}`,
+                `📖 手动升级指引：[点击查看](${url})`,
+                `--`,
+                `**✅ 当前支持自动升级：**`,
+                `请确认机 OpenClaw 主机网络环境连接 GitHub 是否正常，插件更新会重启一次 OpenClaw 主机的 GateWay 服务，过程中会有服务不可用的状态。`,
+                `‼️点击确认 <qqbot-cmd-enter text="/bot-upgrade --latest" />`,
+            ];
+            return lines.join("\n");
+        }
+        // ── --version 指定版本：先校验版本号是否存在 ──
+        if (versionArg) {
+            const exists = await checkVersionExists(versionArg);
+            if (!exists) {
+                return `❌ 当前不存在 ${versionArg} 版本号，请检查 version 设置`;
+            }
+            // 检查是否就是当前版本
+            if (versionArg === PLUGIN_VERSION && !isForce) {
+                return `😀 当前已是 v${PLUGIN_VERSION} 版本，无需升级`;
+            }
+        }
+        // ── --latest：检查是否需要升级 ──
+        if (isLatest && !versionArg) {
+            if (info.checkedAt === 0) {
+                return `⏳ 版本检查中，请稍后再试`;
+            }
+            if (info.error) {
+                return `❌ 当前我的主机网络访问 GitHub 异常，查看手动升级指引：[点击查看](${url})`;
+            }
+            if (!info.hasUpdate && !isForce) {
+                return `😀 当前已是 v${PLUGIN_VERSION} 版本，无需升级`;
             }
         }
         const targetVersion = versionArg || info.latest || undefined;
+        // 加锁
+        _upgrading = true;
         // 异步执行升级
         const startResult = fireHotUpgrade(targetVersion);
         if (!startResult.ok) {
+            _upgrading = false;
             if (startResult.reason === "no-script") {
                 return `❌ 未找到本地升级脚本\n⬆️升级指引：[点击查看](${url})`;
             }
@@ -452,6 +533,12 @@ function collectRecentLogFiles(logDirs) {
 registerCommand({
     name: "bot-logs",
     description: "导出本地日志文件",
+    usage: [
+        `/bot-logs`,
+        ``,
+        `导出最近的 OpenClaw 日志文件（最多 4 个）。`,
+        `每个文件最多保留最后 1000 行，以文件形式返回。`,
+    ].join("\n"),
     handler: () => {
         const logDirs = collectCandidateLogDirs();
         const recentFiles = collectRecentLogFiles(logDirs).slice(0, 4);
@@ -522,6 +609,13 @@ export async function matchSlashCommand(ctx) {
     const cmd = commands.get(cmdName);
     if (!cmd)
         return null; // 不是插件级指令，交给框架
+    // /指令 ? — 返回用法说明
+    if (args === "?") {
+        if (cmd.usage) {
+            return `📖 /${cmd.name} 用法：\n\n${cmd.usage}`;
+        }
+        return `/${cmd.name} — ${cmd.description}`;
+    }
     ctx.args = args;
     const result = await cmd.handler(ctx);
     return result;

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

@@ -20,3 +20,8 @@ export declare function triggerUpdateCheck(log?: {
     debug?: (msg: string) => void;
 }): void;
 export declare function getUpdateInfo(): UpdateInfo;
+/**
+ * 检查指定版本是否存在于 npm registry
+ * 用于 /bot-upgrade --version 的前置校验
+ */
+export declare function checkVersionExists(version: string): Promise<boolean>;

package/dist/src/update-checker.js

@@ -101,6 +101,24 @@ export function triggerUpdateCheck(log) {
 export function getUpdateInfo() {
     return { ..._lastInfo };
 }
+/**
+ * 检查指定版本是否存在于 npm registry
+ * 用于 /bot-upgrade --version 的前置校验
+ */
+export async function checkVersionExists(version) {
+    for (const baseUrl of REGISTRIES) {
+        try {
+            const url = `${baseUrl}/${version}`;
+            const json = await fetchJson(url, 10_000);
+            if (json && json.version === version)
+                return true;
+        }
+        catch {
+            // try next registry
+        }
+    }
+    return false;
+}
 function compareVersions(a, b) {
     const parse = (v) => {
         const clean = v.replace(/^v/, "");

package/package.json

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

package/src/gateway.ts

@@ -352,9 +352,12 @@ async function ensureImageServer(log?: GatewayContext["log"], publicBaseUrl?: st
 let isFirstReadyGlobal = true;
 
 const STARTUP_MARKER_FILE = path.join(getQQBotDataDir("data"), "startup-marker.json");
-const STARTUP_GREETING_TEXT = `Haha，我的'灵魂'已上线，随时等你吩咐。`;
 const STARTUP_GREETING_RETRY_COOLDOWN_MS = 10 * 60 * 1000;
 
+function getStartupGreetingText(version: string): string {
+  return `🎉 QQBot 插件已更新至 v${version}，在线等候你的吩咐。`;
+}
+
 type StartupMarkerData = {
   version?: string;
   startedAt?: string;
@@ -405,7 +408,7 @@ function getStartupGreetingPlan(): { shouldSend: boolean; greeting?: string; ver
     }
   }
 
-  return { shouldSend: true, greeting: STARTUP_GREETING_TEXT, version: currentVersion };
+  return { shouldSend: true, greeting: getStartupGreetingText(currentVersion), version: currentVersion };
 }
 
 function markStartupGreetingSent(version: string): void {

package/src/slash-commands.ts

@@ -16,7 +16,7 @@ import { createRequire } from "node:module";
 import { execFileSync, execFile } from "node:child_process";
 import path from "node:path";
 import fs from "node:fs";
-import { getUpdateInfo } from "./update-checker.js";
+import { getUpdateInfo, checkVersionExists } from "./update-checker.js";
 import { getHomeDir, getQQBotDataDir, isWindows } from "./utils/platform.js";
 import { fileURLToPath } from "node:url";
 const require = createRequire(import.meta.url);
@@ -116,6 +116,8 @@ interface SlashCommand {
   name: string;
   /** 简要描述 */
   description: string;
+  /** 详细用法说明（支持多行），用于 /指令 ? 查询 */
+  usage?: string;
   /** 处理函数 */
   handler: (ctx: SlashCommandContext) => SlashCommandResult | Promise<SlashCommandResult>;
 }
@@ -136,6 +138,12 @@ function registerCommand(cmd: SlashCommand): void {
 registerCommand({
   name: "bot-ping",
   description: "测试当前 openclaw 与 QQ 连接的网络延迟",
+  usage: [
+    `/bot-ping`,
+    ``,
+    `测试 OpenClaw 主机与 QQ 服务器之间的网络延迟。`,
+    `返回网络传输耗时和插件处理耗时。`,
+  ].join("\n"),
   handler: (ctx) => {
     const now = Date.now();
     const eventTime = new Date(ctx.eventTimestamp).getTime();
@@ -162,6 +170,12 @@ registerCommand({
 registerCommand({
   name: "bot-version",
   description: "查看插件版本号",
+  usage: [
+    `/bot-version`,
+    ``,
+    `查看当前 QQBot 插件版本和 OpenClaw 框架版本。`,
+    `同时检查是否有新版本可用。`,
+  ].join("\n"),
   handler: () => {
     const frameworkVersion = getFrameworkVersion();
     const lines = [
@@ -187,6 +201,12 @@ registerCommand({
 registerCommand({
   name: "bot-help",
   description: "查看所有指令以及用途",
+  usage: [
+    `/bot-help`,
+    ``,
+    `列出所有可用的 QQBot 插件内置指令及其简要说明。`,
+    `使用 /指令名 ? 可查看某条指令的详细用法。`,
+  ].join("\n"),
   handler: () => {
     const lines = [`### QQBot插件内置调试指令`, ``];
     for (const [name, cmd] of commands) {
@@ -346,27 +366,44 @@ function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
 }
 
 /**
- * /bot-upgrade — 统一升级入口：能热更就热更，失败则返回升级指引
+ * /bot-upgrade — 统一升级入口
  *
- * 支持参数：
- *   /bot-upgrade           — 检查更新后自动热更
- *   /bot-upgrade 1.6.4     — 升级到指定版本
- *   /bot-upgrade --force   — 强制升级（即使当前已是最新版）
+ * 产品流程：
+ *   /bot-upgrade              — 展示版本信息+确认按钮（不直接升级）
+ *   /bot-upgrade --latest     — 确认升级到最新版本
+ *   /bot-upgrade --version X  — 升级到指定版本
+ *   /bot-upgrade --force      — 强制升级（即使当前已是最新版）
  */
+let _upgrading = false; // 升级锁
+
 registerCommand({
   name: "bot-upgrade",
   description: "检查更新并自动热更（失败则返回升级指引）",
-  handler: (ctx) => {
+  usage: [
+    `/bot-upgrade              检查是否有新版本（展示信息+确认按钮）`,
+    `/bot-upgrade --latest     确认升级到最新版本`,
+    `/bot-upgrade --version X  升级到指定版本（如 1.6.4-alpha.7）`,
+    `/bot-upgrade --force      强制重新安装当前版本`,
+    ``,
+    `⚠️ 仅在私聊中可用。升级过程约 30~60 秒，期间服务短暂不可用。`,
+  ].join("\n"),
+  handler: async (ctx) => {
     // 升级相关指令仅在私聊中可用
     if (ctx.type !== "c2c") {
       return `💡 请在私聊中使用此指令`;
     }
 
+    // 升级锁：防止重复触发
+    if (_upgrading) {
+      return `⏳ 正在升级中，请稍候...`;
+    }
+
     const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
     const args = ctx.args.trim();
     const info = getUpdateInfo();
 
     let isForce = false;
+    let isLatest = false;
     let versionArg: string | undefined;
     const tokens = args ? args.split(/\s+/).filter(Boolean) : [];
     for (let i = 0; i < tokens.length; i += 1) {
@@ -375,6 +412,10 @@ registerCommand({
         isForce = true;
         continue;
       }
+      if (t === "--latest") {
+        isLatest = true;
+        continue;
+      }
       if (t === "--version") {
         const next = tokens[i + 1];
         if (!next || next.startsWith("--")) {
@@ -398,23 +439,73 @@ registerCommand({
       }
     }
 
-    if (!versionArg && !isForce) {
+    const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
+
+    // ── 无参数（也没有 --latest / --version / --force）：只展示信息+确认按钮 ──
+    if (!versionArg && !isLatest && !isForce) {
       if (info.checkedAt === 0) {
         return `⏳ 版本检查中，请稍后再试`;
       }
       if (info.error) {
-        return `⚠️ 版本检查失败\n⬆️升级指引：[点击查看](${url})`;
+        return `❌ 当前我的主机网络访问 GitHub 异常，查看手动升级指引：[点击查看](${url})`;
       }
       if (!info.hasUpdate) {
-        return `✅ 当前版本 v${PLUGIN_VERSION} 已是最新，无需升级\n\n> 💡 使用 /bot-upgrade --force 可强制重新安装`;
+        const lines = [
+          `🌟 GitHub：[tencent-connect/openclaw-qqbot](${GITHUB_URL})`,
+          `✅ 当前使用的已经是最新版本：v${PLUGIN_VERSION}`,
+        ];
+        return lines.join("\n");
+      }
+
+      // 有新版本：展示信息 + 确认按钮
+      const lines = [
+        `🌟 GitHub：[tencent-connect/openclaw-qqbot](${GITHUB_URL})`,
+        `📌 当前使用版本：v${PLUGIN_VERSION}`,
+        `🆕 最新可用版本：v${info.latest}`,
+        `📖 手动升级指引：[点击查看](${url})`,
+        `--`,
+        `**✅ 当前支持自动升级：**`,
+        `请确认机 OpenClaw 主机网络环境连接 GitHub 是否正常，插件更新会重启一次 OpenClaw 主机的 GateWay 服务，过程中会有服务不可用的状态。`,
+        `‼️点击确认 <qqbot-cmd-enter text="/bot-upgrade --latest" />`,
+      ];
+      return lines.join("\n");
+    }
+
+    // ── --version 指定版本：先校验版本号是否存在 ──
+    if (versionArg) {
+      const exists = await checkVersionExists(versionArg);
+      if (!exists) {
+        return `❌ 当前不存在 ${versionArg} 版本号，请检查 version 设置`;
+      }
+
+      // 检查是否就是当前版本
+      if (versionArg === PLUGIN_VERSION && !isForce) {
+        return `😀 当前已是 v${PLUGIN_VERSION} 版本，无需升级`;
+      }
+    }
+
+    // ── --latest：检查是否需要升级 ──
+    if (isLatest && !versionArg) {
+      if (info.checkedAt === 0) {
+        return `⏳ 版本检查中，请稍后再试`;
+      }
+      if (info.error) {
+        return `❌ 当前我的主机网络访问 GitHub 异常，查看手动升级指引：[点击查看](${url})`;
+      }
+      if (!info.hasUpdate && !isForce) {
+        return `😀 当前已是 v${PLUGIN_VERSION} 版本，无需升级`;
       }
     }
 
     const targetVersion = versionArg || info.latest || undefined;
 
+    // 加锁
+    _upgrading = true;
+
     // 异步执行升级
     const startResult = fireHotUpgrade(targetVersion);
     if (!startResult.ok) {
+      _upgrading = false;
       if (startResult.reason === "no-script") {
         return `❌ 未找到本地升级脚本\n⬆️升级指引：[点击查看](${url})`;
       }
@@ -552,6 +643,12 @@ function collectRecentLogFiles(logDirs: string[]): LogCandidate[] {
 registerCommand({
   name: "bot-logs",
   description: "导出本地日志文件",
+  usage: [
+    `/bot-logs`,
+    ``,
+    `导出最近的 OpenClaw 日志文件（最多 4 个）。`,
+    `每个文件最多保留最后 1000 行，以文件形式返回。`,
+  ].join("\n"),
   handler: () => {
     const logDirs = collectCandidateLogDirs();
     const recentFiles = collectRecentLogFiles(logDirs).slice(0, 4);
@@ -628,6 +725,14 @@ export async function matchSlashCommand(ctx: SlashCommandContext): Promise<Slash
   const cmd = commands.get(cmdName);
   if (!cmd) return null; // 不是插件级指令，交给框架
 
+  // /指令 ? — 返回用法说明
+  if (args === "?") {
+    if (cmd.usage) {
+      return `📖 /${cmd.name} 用法：\n\n${cmd.usage}`;
+    }
+    return `/${cmd.name} — ${cmd.description}`;
+  }
+
   ctx.args = args;
   const result = await cmd.handler(ctx);
   return result;

package/src/update-checker.ts

@@ -117,6 +117,23 @@ export function getUpdateInfo(): UpdateInfo {
   return { ..._lastInfo };
 }
 
+/**
+ * 检查指定版本是否存在于 npm registry
+ * 用于 /bot-upgrade --version 的前置校验
+ */
+export async function checkVersionExists(version: string): Promise<boolean> {
+  for (const baseUrl of REGISTRIES) {
+    try {
+      const url = `${baseUrl}/${version}`;
+      const json = await fetchJson(url, 10_000);
+      if (json && json.version === version) return true;
+    } catch {
+      // try next registry
+    }
+  }
+  return false;
+}
+
 function compareVersions(a: string, b: string): number {
   const parse = (v: string) => {
     const clean = v.replace(/^v/, "");