@tencent-connect/openclaw-qqbot 1.6.5-alpha.5 → 1.6.5-alpha.7

package/dist/src/gateway.js

@@ -87,6 +87,22 @@ export async function startGateway(ctx) {
             log?.info(`[qqbot:${account.accountId}] ${w}`);
         }
     }
+    // 预检 openclaw runtime 模块是否可正常解析（兼容性诊断）
+    // openclaw 3.23+ 存在 plugin-sdk/root-alias.cjs 回归 bug，
+    // 内置插件（qwen-portal-auth 等）全部加载失败，导致 AI agent 调用返回
+    // "Unable to resolve plugin runtime module"。提前检测并告警。
+    try {
+        const pluginRuntime = getQQBotRuntime();
+        if (pluginRuntime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+            log?.info(`[qqbot:${account.accountId}] Runtime module preflight: OK`);
+        }
+        else {
+            log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight: dispatchReply API 不可用，AI 消息处理可能失败。请检查 openclaw 版本兼容性`);
+        }
+    }
+    catch (preflightErr) {
+        log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight failed: ${preflightErr}. AI 消息处理可能失败`);
+    }
     // 后台版本检查（供 /bot-version、/bot-upgrade 指令被动查询）
     triggerUpdateCheck(log);
     // 初始化 API 配置（markdown 支持）
@@ -883,8 +899,13 @@ export async function startGateway(ctx) {
                                         clearTimeout(timeoutId);
                                         timeoutId = null;
                                     }
-                                    // 发送错误提示给用户，显示完整错误信息
                                     const errMsg = String(err);
+                                    // 兼容 openclaw 3.23+ 的 plugin-sdk/root-alias.cjs 模块解析失败
+                                    if (errMsg.includes("Unable to resolve plugin runtime module") || errMsg.includes("root-alias.cjs")) {
+                                        log?.error(`[qqbot:${account.accountId}] ⚠️ openclaw 框架 runtime 模块解析失败，可能是 openclaw 版本与 plugin-sdk 不兼容。请尝试: npm install -g openclaw@latest && openclaw gateway restart`);
+                                        await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+                                        return;
+                                    }
                                     if (errMsg.includes("401") || errMsg.includes("key") || errMsg.includes("auth")) {
                                         log?.error(`[qqbot:${account.accountId}] AI auth error: ${errMsg}`);
                                     }
@@ -929,7 +950,15 @@ export async function startGateway(ctx) {
                         }
                     }
                     catch (err) {
+                        const errStr = String(err);
                         log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
+                        // 兼容 openclaw 3.23+ runtime 模块解析失败：给用户发可操作的提示
+                        if (errStr.includes("Unable to resolve plugin runtime module") || errStr.includes("root-alias.cjs")) {
+                            try {
+                                await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+                            }
+                            catch { /* best-effort */ }
+                        }
                     }
                     finally {
                         // 无论成功/失败/超时，都停止输入状态续期

package/dist/src/slash-commands.js

@@ -251,7 +251,7 @@ registerCommand({
         return lines.join("\n");
     },
 });
-const DEFAULT_UPGRADE_URL = "https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg";
+const DEFAULT_UPGRADE_URL = "https://docs.qq.com/doc/DSGxOZk1oVnVKVkpq";
 function saveUpgradeGreetingTarget(accountId, appId, openid) {
     const safeAccountId = accountId.replace(/[^a-zA-Z0-9._-]/g, "_");
     const safeAppId = appId.replace(/[^a-zA-Z0-9._-]/g, "_");
@@ -561,6 +561,38 @@ function findPowerShell() {
     }
     return null;
 }
+/**
+ * 将升级脚本复制到临时位置，避免升级过程中插件目录被清理后脚本丢失。
+ * 返回临时脚本路径，失败返回 null。
+ */
+function copyScriptToTemp(scriptPath) {
+    try {
+        const ext = path.extname(scriptPath);
+        const tmpDir = path.join(getHomeDir(), ".openclaw", ".qqbot-upgrade-tmp");
+        fs.mkdirSync(tmpDir, { recursive: true });
+        const tmpScript = path.join(tmpDir, `upgrade-via-npm${ext}`);
+        fs.copyFileSync(scriptPath, tmpScript);
+        if (!isWindows()) {
+            fs.chmodSync(tmpScript, 0o755);
+        }
+        return tmpScript;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 清理临时升级脚本目录
+ */
+function cleanupTempScript() {
+    try {
+        const tmpDir = path.join(getHomeDir(), ".openclaw", ".qqbot-upgrade-tmp");
+        fs.rmSync(tmpDir, { recursive: true, force: true });
+    }
+    catch {
+        // 非关键，静默忽略
+    }
+}
 /**
  * 执行热更新：执行脚本(--no-restart) → 立即触发 gateway restart
  *
@@ -570,11 +602,15 @@ function findPowerShell() {
  * - 新进程启动时 getStartupGreeting() 检测到版本变更，自动通知管理员
  *
  * Windows 使用 PowerShell 执行 .ps1 脚本，Mac/Linux 使用 bash 执行 .sh 脚本。
+ *
+ * 安全机制：脚本会被复制到临时目录再执行，避免升级过程中插件目录被操作导致脚本自身丢失。
  */
 function fireHotUpgrade(targetVersion) {
-    const scriptPath = getUpgradeScriptPath();
-    if (!scriptPath)
+    const originalScriptPath = getUpgradeScriptPath();
+    if (!originalScriptPath)
         return { ok: false, reason: "no-script" };
+    // 将脚本复制到临时位置，避免升级过程中脚本被删除
+    const scriptPath = copyScriptToTemp(originalScriptPath) || originalScriptPath;
     const cli = findCli();
     if (!cli)
         return { ok: false, reason: "no-cli" };
@@ -601,7 +637,7 @@ function fireHotUpgrade(targetVersion) {
         shell = bash;
         shellArgs = [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : [])];
     }
-    console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}`);
+    console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath} (original: ${originalScriptPath}), cli=${cli}, target=${targetVersion || "latest"}`);
     // 异步执行升级脚本
     execFile(shell, shellArgs, {
         timeout: 120_000,
@@ -614,6 +650,7 @@ function fireHotUpgrade(targetVersion) {
                 console.error(`[qqbot] fireHotUpgrade: stdout: ${stdout.slice(0, 2000)}`);
             if (_stderr)
                 console.error(`[qqbot] fireHotUpgrade: stderr: ${_stderr.slice(0, 2000)}`);
+            cleanupTempScript();
             _upgrading = false;
             return;
         }
@@ -623,10 +660,13 @@ function fireHotUpgrade(targetVersion) {
         const newVersion = versionMatch?.[1];
         if (newVersion === "unknown") {
             console.error(`[qqbot] fireHotUpgrade: script output QQBOT_NEW_VERSION=unknown, aborting restart`);
+            cleanupTempScript();
             _upgrading = false;
             return;
         }
         console.log(`[qqbot] fireHotUpgrade: new version=${newVersion || "(not detected)"}, triggering restart...`);
+        // 脚本执行成功，清理临时脚本副本
+        cleanupTempScript();
         // 文件替换成功，在 restart 之前把 source 从 path 切换为 npm，
         // 确保新进程启动时读到的是 npm source，不会被本地源码覆盖。
         switchPluginSourceToNpm();
@@ -686,7 +726,11 @@ function fireHotUpgrade(targetVersion) {
 /**
  * /bot-upgrade — 统一升级入口
  *
- * 产品流程：
+ * upgradeMode 开关：
+ *   - "doc"（默认）：只展示升级指引文档，不执行热更新
+ *   - "hot-reload"：执行 npm 升级脚本进行热更新
+ *
+ * 热更新模式下的产品流程：
  *   /bot-upgrade              — 展示版本信息+确认按钮（不直接升级）
  *   /bot-upgrade --latest     — 确认升级到最新版本
  *   /bot-upgrade --version X  — 升级到指定版本
@@ -695,21 +739,49 @@ function fireHotUpgrade(targetVersion) {
 let _upgrading = false; // 升级锁
 registerCommand({
     name: "bot-upgrade",
-    description: "检查更新并自动热更",
+    description: "检查更新并查看升级指引",
     usage: [
-        `/bot-upgrade              检查是否有新版本（展示信息+确认按钮）`,
-        `/bot-upgrade --latest     确认升级到最新版本`,
-        `/bot-upgrade --version X  升级到指定版本（如 1.6.5）`,
-        `/bot-upgrade --force      强制重新安装当前版本`,
-        ``,
-        `⚠️ 仅在私聊中可用。升级过程约 30~60 秒，期间服务短暂不可用。`,
-        ``,
-        `环境要求：`,
-        `  - 操作系统：macOS / Linux / Windows`,
-        `  - OpenClaw 框架版本 ≥ ${UPGRADE_REQUIREMENTS.minFrameworkVersion}`,
-        `  - Node.js ≥ v${UPGRADE_REQUIREMENTS.minNodeVersion}`,
+        `/bot-upgrade              检查是否有新版本`,
+        `/bot-upgrade --latest     确认升级到最新版本（需 upgradeMode=hot-reload）`,
+        `/bot-upgrade --version X  升级到指定版本（需 upgradeMode=hot-reload）`,
+        `/bot-upgrade --force      强制重新安装当前版本（需 upgradeMode=hot-reload）`,
     ].join("\n"),
     handler: async (ctx) => {
+        const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
+        const upgradeMode = ctx.accountConfig?.upgradeMode || "doc";
+        const args = ctx.args.trim();
+        const info = await getUpdateInfo();
+        const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
+        // ── doc 模式（默认）：只展示升级指引，不执行热更新 ──
+        if (upgradeMode !== "hot-reload") {
+            if (info.checkedAt === 0) {
+                return `⏳ 版本检查中，请稍后再试`;
+            }
+            if (info.error) {
+                return [
+                    `❌ 主机网络访问异常，无法检查更新`,
+                    ``,
+                    `查看升级指引：[点击查看](${url})`,
+                ].join("\n");
+            }
+            if (!info.hasUpdate) {
+                return [
+                    `✅ 当前已是最新版本 v${PLUGIN_VERSION}`,
+                    ``,
+                    `项目地址：[GitHub](${GITHUB_URL})`,
+                ].join("\n");
+            }
+            return [
+                `🆕 发现新版本`,
+                ``,
+                `当前版本：**v${PLUGIN_VERSION}**`,
+                `最新版本：**v${info.latest}**`,
+                ``,
+                `📖 升级指引：[点击查看](${url})`,
+                `🌟 官方 GitHub 仓库：[点击前往](${GITHUB_URL})`,
+            ].join("\n");
+        }
+        // ── hot-reload 模式：执行热更新 ──
         // 升级相关指令仅在私聊中可用
         if (ctx.type !== "c2c") {
             return `💡 请在私聊中使用此指令`;
@@ -718,9 +790,6 @@ registerCommand({
         if (_upgrading) {
             return `⏳ 正在升级中，请稍候...`;
         }
-        const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
-        const args = ctx.args.trim();
-        const info = await getUpdateInfo();
         let isForce = false;
         let isLatest = false;
         let versionArg;
@@ -757,7 +826,6 @@ registerCommand({
                 continue;
             }
         }
-        const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
         // ── 无参数（也没有 --latest / --version / --force）：只展示信息+确认按钮 ──
         if (!versionArg && !isLatest && !isForce) {
             if (info.checkedAt === 0) {
@@ -778,7 +846,7 @@ registerCommand({
                 ];
                 return lines.join("\n");
             }
-            // 有新版本：展示信息 + 确认按钮（同通道：alpha 只展示 alpha，正式版只展示正式版）
+            // 有新版本：展示信息 + 确认按钮
             return [
                 `🆕 发现新版本`,
                 ``,

package/package.json

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

package/scripts/upgrade-via-npm.sh

@@ -230,20 +230,40 @@ if [ "$USE_UPDATE" = "true" ]; then
 fi
 
 if [ "$UPGRADE_OK" != "true" ]; then
-    # 清理旧目录（包含当前插件和历史遗留名称）
-    for dir_name in "$PLUGIN_ID" qqbot openclaw-qq; do
-        [ -d "$EXTENSIONS_DIR/$dir_name" ] && rm -rf "$EXTENSIONS_DIR/$dir_name" && echo "  已清理: $EXTENSIONS_DIR/$dir_name"
+    # 备份旧目录（而非直接删除），install 失败时可回滚
+    BACKUP_DIR=""
+    if [ -d "$EXTENSIONS_DIR/$PLUGIN_ID" ]; then
+        BACKUP_DIR="$EXTENSIONS_DIR/.openclaw-qqbot-backup-$$"
+        mv "$EXTENSIONS_DIR/$PLUGIN_ID" "$BACKUP_DIR"
+        echo "  已备份旧目录: $BACKUP_DIR"
+    fi
+
+    # 清理历史遗留名称（这些不需要回滚）
+    for dir_name in qqbot openclaw-qq; do
+        [ -d "$EXTENSIONS_DIR/$dir_name" ] && rm -rf "$EXTENSIONS_DIR/$dir_name" && echo "  已清理历史目录: $EXTENSIONS_DIR/$dir_name"
     done
 
     echo "  执行 install: $INSTALL_SRC"
     if $CMD plugins install "$INSTALL_SRC" --pin 2>&1; then
         UPGRADE_OK=true
         echo "  ✅ install 成功"
+        # install 成功，清理备份
+        if [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
+            rm -rf "$BACKUP_DIR"
+            echo "  已清理旧版备份"
+        fi
+        # 清理 openclaw CLI install 可能留下的额外 backup 目录
+        find "$EXTENSIONS_DIR" -maxdepth 1 -name ".openclaw-qqbot-backup-*" -exec rm -rf {} + 2>/dev/null || true
     else
-        echo "❌ install 失败"
+        echo "  ❌ install 失败"
+        # 回滚：恢复旧目录
+        if [ -n "$BACKUP_DIR" ] && [ -d "$BACKUP_DIR" ]; then
+            mv "$BACKUP_DIR" "$EXTENSIONS_DIR/$PLUGIN_ID"
+            echo "  ↩️  已回滚到旧版本"
+        fi
         restore_qqbot_channel
         echo "QQBOT_NEW_VERSION=unknown"
-        echo "QQBOT_REPORT=❌ QQBot 安装失败，请检查网络和 npm registry"
+        echo "QQBOT_REPORT=❌ QQBot 安装失败（已回滚到旧版本），请检查网络和 npm registry"
         exit 1
     fi
 fi
@@ -336,6 +356,19 @@ if [ "$PREFLIGHT_OK" != "true" ]; then
 fi
 echo "  ✅ 验证全部通过"
 
+# 确保 openclaw/plugin-sdk 可解析：
+# openclaw plugins install 不会执行 npm lifecycle scripts，
+# 需要手动调用 postinstall-link-sdk.js 创建 node_modules/openclaw → 全局 openclaw 的符号链接
+POSTINSTALL_SCRIPT="$TARGET_DIR/scripts/postinstall-link-sdk.js"
+if [ -f "$POSTINSTALL_SCRIPT" ]; then
+    echo "  执行 postinstall-link-sdk..."
+    if node "$POSTINSTALL_SCRIPT" 2>&1; then
+        echo "  ✅ plugin-sdk 链接就绪"
+    else
+        echo "  ⚠️  postinstall-link-sdk 失败，插件可能无法加载"
+    fi
+fi
+
 # [3/4] 输出结构化信息（供 TS handler 解析）
 echo ""
 echo "[3/4] 升级结果..."

package/scripts/upgrade-via-source.sh

@@ -444,6 +444,27 @@ else
     # gateway 已在安装前 stop，此时不会有自动 restart 的问题
     # 所有配置写入完成后，在 Step 6 统一启动
 
+    # 确保 openclaw/plugin-sdk 可解析：
+    # openclaw plugins install 不会执行 npm lifecycle scripts，
+    # 需要手动调用 postinstall-link-sdk.js 创建 node_modules/openclaw → 全局 openclaw 的符号链接。
+    # 必须在 peerDeps 清理之后执行，否则 symlink 会被清理逻辑删除。
+    for _candidate_name in openclaw-qqbot qqbot openclaw-qq; do
+        _postinstall="$HOME/.openclaw/extensions/$_candidate_name/scripts/postinstall-link-sdk.js"
+        if [ -f "$_postinstall" ]; then
+            echo "  执行 postinstall-link-sdk..."
+            if node "$_postinstall" 2>&1; then
+                echo "  ✅ plugin-sdk 链接就绪"
+            else
+                echo "  ⚠️  postinstall-link-sdk 失败，插件可能无法加载"
+            fi
+            break
+        fi
+    done
+
+    # 清理 openclaw CLI install 留下的 backup 目录，
+    # 避免 gateway 发现两个同 id 插件不断刷 duplicate plugin id 警告
+    find "$HOME/.openclaw/extensions/" -maxdepth 1 -name ".openclaw-qqbot-backup-*" -exec rm -rf {} + 2>/dev/null || true
+
     # 记录更新后的 qqbot 插件版本
     NEW_QQBOT_VERSION=$(node -e '
         try {

package/src/gateway.ts

@@ -112,6 +112,21 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
     }
   }
 
+  // 预检 openclaw runtime 模块是否可正常解析（兼容性诊断）
+  // openclaw 3.23+ 存在 plugin-sdk/root-alias.cjs 回归 bug，
+  // 内置插件（qwen-portal-auth 等）全部加载失败，导致 AI agent 调用返回
+  // "Unable to resolve plugin runtime module"。提前检测并告警。
+  try {
+    const pluginRuntime = getQQBotRuntime();
+    if (pluginRuntime?.channel?.reply?.dispatchReplyWithBufferedBlockDispatcher) {
+      log?.info(`[qqbot:${account.accountId}] Runtime module preflight: OK`);
+    } else {
+      log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight: dispatchReply API 不可用，AI 消息处理可能失败。请检查 openclaw 版本兼容性`);
+    }
+  } catch (preflightErr) {
+    log?.error(`[qqbot:${account.accountId}] ⚠️ Runtime preflight failed: ${preflightErr}. AI 消息处理可能失败`);
+  }
+
   // 后台版本检查（供 /bot-version、/bot-upgrade 指令被动查询）
   triggerUpdateCheck(log);
 
@@ -1019,8 +1034,15 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
                   timeoutId = null;
                 }
                 
-                // 发送错误提示给用户，显示完整错误信息
                 const errMsg = String(err);
+
+                // 兼容 openclaw 3.23+ 的 plugin-sdk/root-alias.cjs 模块解析失败
+                if (errMsg.includes("Unable to resolve plugin runtime module") || errMsg.includes("root-alias.cjs")) {
+                  log?.error(`[qqbot:${account.accountId}] ⚠️ openclaw 框架 runtime 模块解析失败，可能是 openclaw 版本与 plugin-sdk 不兼容。请尝试: npm install -g openclaw@latest && openclaw gateway restart`);
+                  await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+                  return;
+                }
+
                 if (errMsg.includes("401") || errMsg.includes("key") || errMsg.includes("auth")) {
                   log?.error(`[qqbot:${account.accountId}] AI auth error: ${errMsg}`);
                 } else {
@@ -1062,7 +1084,14 @@ export async function startGateway(ctx: GatewayContext): Promise<void> {
             }
           }
         } catch (err) {
+          const errStr = String(err);
           log?.error(`[qqbot:${account.accountId}] Message processing failed: ${err}`);
+          // 兼容 openclaw 3.23+ runtime 模块解析失败：给用户发可操作的提示
+          if (errStr.includes("Unable to resolve plugin runtime module") || errStr.includes("root-alias.cjs")) {
+            try {
+              await sendErrorMessage("⚠️ AI 服务暂时不可用：openclaw 框架运行时模块加载失败。\n\n请管理员执行：\nnpm install -g openclaw@latest\nopenclaw gateway restart\n\n斜杠命令（如 /bot-ping）不受影响。");
+            } catch { /* best-effort */ }
+          }
         } finally {
           // 无论成功/失败/超时，都停止输入状态续期
           typing.keepAlive?.stop();

package/src/slash-commands.ts

@@ -337,7 +337,7 @@ registerCommand({
   },
 });
 
-const DEFAULT_UPGRADE_URL = "https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg";
+const DEFAULT_UPGRADE_URL = "https://docs.qq.com/doc/DSGxOZk1oVnVKVkpq";
 
 function saveUpgradeGreetingTarget(accountId: string, appId: string, openid: string): void {
   const safeAccountId = accountId.replace(/[^a-zA-Z0-9._-]/g, "_");
@@ -660,6 +660,38 @@ function findPowerShell(): string | null {
   return null;
 }
 
+/**
+ * 将升级脚本复制到临时位置，避免升级过程中插件目录被清理后脚本丢失。
+ * 返回临时脚本路径，失败返回 null。
+ */
+function copyScriptToTemp(scriptPath: string): string | null {
+  try {
+    const ext = path.extname(scriptPath);
+    const tmpDir = path.join(getHomeDir(), ".openclaw", ".qqbot-upgrade-tmp");
+    fs.mkdirSync(tmpDir, { recursive: true });
+    const tmpScript = path.join(tmpDir, `upgrade-via-npm${ext}`);
+    fs.copyFileSync(scriptPath, tmpScript);
+    if (!isWindows()) {
+      fs.chmodSync(tmpScript, 0o755);
+    }
+    return tmpScript;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * 清理临时升级脚本目录
+ */
+function cleanupTempScript(): void {
+  try {
+    const tmpDir = path.join(getHomeDir(), ".openclaw", ".qqbot-upgrade-tmp");
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  } catch {
+    // 非关键，静默忽略
+  }
+}
+
 /**
  * 执行热更新：执行脚本(--no-restart) → 立即触发 gateway restart
  *
@@ -669,10 +701,15 @@ function findPowerShell(): string | null {
  * - 新进程启动时 getStartupGreeting() 检测到版本变更，自动通知管理员
  *
  * Windows 使用 PowerShell 执行 .ps1 脚本，Mac/Linux 使用 bash 执行 .sh 脚本。
+ *
+ * 安全机制：脚本会被复制到临时目录再执行，避免升级过程中插件目录被操作导致脚本自身丢失。
  */
 function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
-  const scriptPath = getUpgradeScriptPath();
-  if (!scriptPath) return { ok: false, reason: "no-script" };
+  const originalScriptPath = getUpgradeScriptPath();
+  if (!originalScriptPath) return { ok: false, reason: "no-script" };
+
+  // 将脚本复制到临时位置，避免升级过程中脚本被删除
+  const scriptPath = copyScriptToTemp(originalScriptPath) || originalScriptPath;
 
   const cli = findCli();
   if (!cli) return { ok: false, reason: "no-cli" };
@@ -699,7 +736,7 @@ function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
     shellArgs = [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : [])];
   }
 
-  console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}`);
+  console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath} (original: ${originalScriptPath}), cli=${cli}, target=${targetVersion || "latest"}`);
 
   // 异步执行升级脚本
   execFile(shell, shellArgs, {
@@ -711,6 +748,7 @@ function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
       console.error(`[qqbot] fireHotUpgrade: script failed: ${error.message}`);
       if (stdout) console.error(`[qqbot] fireHotUpgrade: stdout: ${stdout.slice(0, 2000)}`);
       if (_stderr) console.error(`[qqbot] fireHotUpgrade: stderr: ${_stderr.slice(0, 2000)}`);
+      cleanupTempScript();
       _upgrading = false;
       return;
     }
@@ -722,12 +760,16 @@ function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
     const newVersion = versionMatch?.[1];
     if (newVersion === "unknown") {
       console.error(`[qqbot] fireHotUpgrade: script output QQBOT_NEW_VERSION=unknown, aborting restart`);
+      cleanupTempScript();
       _upgrading = false;
       return;
     }
 
     console.log(`[qqbot] fireHotUpgrade: new version=${newVersion || "(not detected)"}, triggering restart...`);
 
+    // 脚本执行成功，清理临时脚本副本
+    cleanupTempScript();
+
     // 文件替换成功，在 restart 之前把 source 从 path 切换为 npm，
     // 确保新进程启动时读到的是 npm source，不会被本地源码覆盖。
     switchPluginSourceToNpm();
@@ -788,7 +830,11 @@ function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
 /**
  * /bot-upgrade — 统一升级入口
  *
- * 产品流程：
+ * upgradeMode 开关：
+ *   - "doc"（默认）：只展示升级指引文档，不执行热更新
+ *   - "hot-reload"：执行 npm 升级脚本进行热更新
+ *
+ * 热更新模式下的产品流程：
  *   /bot-upgrade              — 展示版本信息+确认按钮（不直接升级）
  *   /bot-upgrade --latest     — 确认升级到最新版本
  *   /bot-upgrade --version X  — 升级到指定版本
@@ -798,21 +844,54 @@ let _upgrading = false; // 升级锁
 
 registerCommand({
   name: "bot-upgrade",
-  description: "检查更新并自动热更",
+  description: "检查更新并查看升级指引",
   usage: [
-    `/bot-upgrade              检查是否有新版本（展示信息+确认按钮）`,
-    `/bot-upgrade --latest     确认升级到最新版本`,
-    `/bot-upgrade --version X  升级到指定版本（如 1.6.5）`,
-    `/bot-upgrade --force      强制重新安装当前版本`,
-    ``,
-    `⚠️ 仅在私聊中可用。升级过程约 30~60 秒，期间服务短暂不可用。`,
-    ``,
-    `环境要求：`,
-    `  - 操作系统：macOS / Linux / Windows`,
-    `  - OpenClaw 框架版本 ≥ ${UPGRADE_REQUIREMENTS.minFrameworkVersion}`,
-    `  - Node.js ≥ v${UPGRADE_REQUIREMENTS.minNodeVersion}`,
+    `/bot-upgrade              检查是否有新版本`,
+    `/bot-upgrade --latest     确认升级到最新版本（需 upgradeMode=hot-reload）`,
+    `/bot-upgrade --version X  升级到指定版本（需 upgradeMode=hot-reload）`,
+    `/bot-upgrade --force      强制重新安装当前版本（需 upgradeMode=hot-reload）`,
   ].join("\n"),
   handler: async (ctx) => {
+    const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
+    const upgradeMode = ctx.accountConfig?.upgradeMode || "doc";
+    const args = ctx.args.trim();
+    const info = await getUpdateInfo();
+
+    const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
+
+    // ── doc 模式（默认）：只展示升级指引，不执行热更新 ──
+    if (upgradeMode !== "hot-reload") {
+      if (info.checkedAt === 0) {
+        return `⏳ 版本检查中，请稍后再试`;
+      }
+      if (info.error) {
+        return [
+          `❌ 主机网络访问异常，无法检查更新`,
+          ``,
+          `查看升级指引：[点击查看](${url})`,
+        ].join("\n");
+      }
+      if (!info.hasUpdate) {
+        return [
+          `✅ 当前已是最新版本 v${PLUGIN_VERSION}`,
+          ``,
+          `项目地址：[GitHub](${GITHUB_URL})`,
+        ].join("\n");
+      }
+
+      return [
+        `🆕 发现新版本`,
+        ``,
+        `当前版本：**v${PLUGIN_VERSION}**`,
+        `最新版本：**v${info.latest}**`,
+        ``,
+        `📖 升级指引：[点击查看](${url})`,
+        `🌟 官方 GitHub 仓库：[点击前往](${GITHUB_URL})`,
+      ].join("\n");
+    }
+
+    // ── hot-reload 模式：执行热更新 ──
+
     // 升级相关指令仅在私聊中可用
     if (ctx.type !== "c2c") {
       return `💡 请在私聊中使用此指令`;
@@ -823,10 +902,6 @@ registerCommand({
       return `⏳ 正在升级中，请稍候...`;
     }
 
-    const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
-    const args = ctx.args.trim();
-    const info = await getUpdateInfo();
-
     let isForce = false;
     let isLatest = false;
     let versionArg: string | undefined;
@@ -864,8 +939,6 @@ registerCommand({
       }
     }
 
-    const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
-
     // ── 无参数（也没有 --latest / --version / --force）：只展示信息+确认按钮 ──
     if (!versionArg && !isLatest && !isForce) {
       if (info.checkedAt === 0) {
@@ -887,7 +960,7 @@ registerCommand({
         return lines.join("\n");
       }
 
-      // 有新版本：展示信息 + 确认按钮（同通道：alpha 只展示 alpha，正式版只展示正式版）
+      // 有新版本：展示信息 + 确认按钮
       return [
         `🆕 发现新版本`,
         ``,