@ryantest/openclaw-qqbot 1.6.7-beta.2 → 1.6.7-beta.3

package/dist/src/api.js

@@ -106,7 +106,7 @@ async function doFetchToken(appId, clientSecret) {
     const requestBody = { appId, clientSecret };
     const requestHeaders = { "Content-Type": "application/json", "User-Agent": PLUGIN_USER_AGENT };
     // 打印请求信息（隐藏敏感信息）
-    console.log(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL}`);
+    console.log(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL} [secret: ${clientSecret.slice(0, 6)}...len=${clientSecret.length}]`);
     let response;
     try {
         response = await fetch(TOKEN_URL, {

package/dist/src/slash-commands.js

@@ -152,7 +152,7 @@ function checkUpgradeCompatibility() {
     // 3. 检查 Node.js 版本
     const nodeVer = process.version.replace(/^v/, "");
     if (compareSemver(nodeVer, req.minNodeVersion) < 0) {
-        errors.push(`❌ Node.js 版本过低：当前 **v${nodeVer}**，热更新要求最低 **v${req.minNodeVersion}**`);
+        errors.push(`❌ NoVBNde.js 版本过低：当前 **v${nodeVer}**，热更新要求最低 **v${req.minNodeVersion}**`);
     }
     // 4. 检查系统架构（arm 等特殊架构提示）
     const arch = process.arch;
@@ -642,15 +642,24 @@ function cleanupTempScript() {
  *
  * 安全机制：脚本会被复制到临时目录再执行，避免升级过程中插件目录被操作导致脚本自身丢失。
  */
-function fireHotUpgrade(targetVersion) {
-    // 优先从远端下载升级脚本，避免使用本地可能过时的版本
-    const scriptPath = downloadRemoteUpgradeScript() || (() => {
-        const local = getUpgradeScriptPath();
-        if (!local)
-            return null;
-        console.log(`[qqbot] fireHotUpgrade: remote download failed, falling back to local script: ${local}`);
-        return copyScriptToTemp(local) || local;
-    })();
+function fireHotUpgrade(targetVersion, pkg, useLocal) {
+    // --local: 直接使用本地脚本，跳过远端下载
+    // 默认: 优先从远端下载升级脚本，避免使用本地可能过时的版本
+    const scriptPath = useLocal
+        ? (() => {
+            const local = getUpgradeScriptPath();
+            if (!local)
+                return null;
+            console.log(`[qqbot] fireHotUpgrade: --local specified, using local script: ${local}`);
+            return copyScriptToTemp(local) || local;
+        })()
+        : downloadRemoteUpgradeScript() || (() => {
+            const local = getUpgradeScriptPath();
+            if (!local)
+                return null;
+            console.log(`[qqbot] fireHotUpgrade: remote download failed, falling back to local script: ${local}`);
+            return copyScriptToTemp(local) || local;
+        })();
     if (!scriptPath)
         return { ok: false, reason: "no-script" };
     const cli = findCli();
@@ -669,6 +678,7 @@ function fireHotUpgrade(targetVersion) {
             "-File", scriptPath,
             "-NoRestart",
             ...(targetVersion ? ["-Version", targetVersion] : []),
+            ...(pkg ? ["-Pkg", pkg] : []),
         ];
     }
     else {
@@ -677,9 +687,9 @@ function fireHotUpgrade(targetVersion) {
         if (!bash)
             return { ok: false, reason: "no-bash" };
         shell = bash;
-        shellArgs = [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : [])];
+        shellArgs = [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : []), ...(pkg ? ["--pkg", pkg] : [])];
     }
-    console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}`);
+    console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}, pkg=${pkg || "default"}`);
     // 异步执行升级脚本
     execFile(shell, shellArgs, {
         timeout: 120_000,
@@ -786,7 +796,9 @@ registerCommand({
         `/bot-upgrade              检查是否有新版本`,
         `/bot-upgrade --latest     确认升级到最新版本（需 upgradeMode=hot-reload）`,
         `/bot-upgrade --version X  升级到指定版本（需 upgradeMode=hot-reload）`,
+        `/bot-upgrade --pkg scope/name  指定 npm 包（如 ryantest/openclaw-qqbot）`,
         `/bot-upgrade --force      强制重新安装当前版本（需 upgradeMode=hot-reload）`,
+        `/bot-upgrade --local      使用本地升级脚本（跳过远端下载）`,
     ].join("\n"),
     handler: async (ctx) => {
         const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
@@ -834,7 +846,9 @@ registerCommand({
         }
         let isForce = false;
         let isLatest = false;
+        let isLocal = false;
         let versionArg;
+        let pkgArg;
         const tokens = args ? args.split(/\s+/).filter(Boolean) : [];
         for (let i = 0; i < tokens.length; i += 1) {
             const t = tokens[i];
@@ -846,6 +860,27 @@ registerCommand({
                 isLatest = true;
                 continue;
             }
+            if (t === "--local") {
+                isLocal = true;
+                continue;
+            }
+            if (t === "--pkg") {
+                const next = tokens[i + 1];
+                if (!next || next.startsWith("--")) {
+                    return `❌ 参数错误：--pkg 需要包名\n\n示例：/bot-upgrade --pkg ryantest/openclaw-qqbot`;
+                }
+                pkgArg = next;
+                i += 1;
+                continue;
+            }
+            if (t.startsWith("--pkg=")) {
+                const v = t.slice("--pkg=".length).trim();
+                if (!v) {
+                    return `❌ 参数错误：--pkg 需要包名\n\n示例：/bot-upgrade --pkg ryantest/openclaw-qqbot`;
+                }
+                pkgArg = v;
+                continue;
+            }
             if (t === "--version") {
                 const next = tokens[i + 1];
                 if (!next || next.startsWith("--")) {
@@ -904,9 +939,17 @@ registerCommand({
                 `🌟官方 GitHub 仓库：[点击前往](${GITHUB_URL})`,
             ].join("\n");
         }
+        // 解析 npm 包名：--pkg 参数 > 配置项 upgradePkg > 默认
+        // 支持 "scope/name"（自动补 @）和 "@scope/name" 两种格式
+        let upgradePkg = pkgArg || ctx.accountConfig?.upgradePkg;
+        if (upgradePkg) {
+            upgradePkg = upgradePkg.trim();
+            if (!upgradePkg.startsWith("@"))
+                upgradePkg = `@${upgradePkg}`;
+        }
         // ── --version 指定版本：先校验版本号是否存在 ──
         if (versionArg) {
-            const exists = await checkVersionExists(versionArg);
+            const exists = await checkVersionExists(versionArg, upgradePkg);
             if (!exists) {
                 return `❌ 版本 ${versionArg} 不存在，请检查版本号`;
             }
@@ -951,7 +994,7 @@ registerCommand({
         // 热更新前保存凭证快照，防止更新过程被打断导致 appId/secret 丢失
         preUpgradeCredentialBackup(ctx.accountId, ctx.appId);
         // 异步执行升级
-        const startResult = fireHotUpgrade(targetVersion);
+        const startResult = fireHotUpgrade(targetVersion, upgradePkg, isLocal);
         if (!startResult.ok) {
             _upgrading = false;
             if (startResult.reason === "no-script") {

package/dist/src/types.d.ts

@@ -96,6 +96,13 @@ export interface QQBotAccountConfig {
      * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新（默认）
      */
     upgradeMode?: "doc" | "hot-reload";
+    /**
+     * /bot-upgrade 热更新时使用的 npm 包名
+     * 支持 "scope/name"（自动补 @）或 "@scope/name" 格式
+     * 默认: "@tencent-connect/openclaw-qqbot"
+     * 示例: "ryantest/openclaw-qqbot"
+     */
+    upgradePkg?: string;
     /**
      * 出站消息合并回复（debounce）配置
      * 当短时间内收到多次 deliver 时，将文本合并为一条消息发送，避免消息轰炸

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

@@ -30,5 +30,7 @@ export declare function getUpdateInfo(): Promise<UpdateInfo>;
 /**
  * 检查指定版本是否存在于 npm registry
  * 用于 /bot-upgrade --version 的前置校验
+ * @param version 要检查的版本号
+ * @param pkgName 可选的包名（如 "@ryantest/openclaw-qqbot"），默认使用内置包名
  */
-export declare function checkVersionExists(version: string): Promise<boolean>;
+export declare function checkVersionExists(version: string, pkgName?: string): Promise<boolean>;

package/dist/src/update-checker.js

@@ -99,9 +99,12 @@ export async function getUpdateInfo() {
 /**
  * 检查指定版本是否存在于 npm registry
  * 用于 /bot-upgrade --version 的前置校验
+ * @param version 要检查的版本号
+ * @param pkgName 可选的包名（如 "@ryantest/openclaw-qqbot"），默认使用内置包名
  */
-export async function checkVersionExists(version) {
-    for (const baseUrl of REGISTRIES) {
+export async function checkVersionExists(version, pkgName) {
+    const registries = pkgName ? buildRegistries(pkgName) : REGISTRIES;
+    for (const baseUrl of registries) {
         try {
             const url = `${baseUrl}/${version}`;
             const json = await fetchJson(url, 10_000);
@@ -114,6 +117,14 @@ export async function checkVersionExists(version) {
     }
     return false;
 }
+/** 根据自定义包名构建 registry URL 列表 */
+function buildRegistries(pkgName) {
+    const encoded = encodeURIComponent(pkgName);
+    return [
+        `https://registry.npmjs.org/${encoded}`,
+        `https://registry.npmmirror.com/${encoded}`,
+    ];
+}
 function compareVersions(a, b) {
     const parse = (v) => {
         const clean = v.replace(/^v/, "");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ryantest/openclaw-qqbot",
-  "version": "1.6.7-beta.2",
+  "version": "1.6.7-beta.3",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/scripts/upgrade-via-npm.ps1

@@ -17,6 +17,7 @@ param(
     [string]$Secret = "",
     [switch]$NoRestart,
     [string]$Tag = "",
+    [string]$Pkg = "",
     [switch]$Help
 )
 
@@ -25,6 +26,13 @@ $PKG_NAME = "@tencent-connect/openclaw-qqbot"
 $SCRIPT_DIR = Split-Path -Parent $MyInvocation.MyCommand.Definition
 $PROJECT_DIR = Split-Path -Parent $SCRIPT_DIR
 
+# -Pkg 覆盖包名（支持 "scope/name" 自动补 @）
+if ($Pkg) {
+    $Pkg = $Pkg.Trim()
+    if (-not $Pkg.StartsWith("@")) { $Pkg = "@$Pkg" }
+    $PKG_NAME = $Pkg
+}
+
 # Read local version
 $LOCAL_VERSION = ""
 try {
@@ -41,6 +49,7 @@ if ($Help) {
     Write-Host "  .\upgrade-via-npm.ps1 -Version [version]           # upgrade to specific version"
     Write-Host "  .\upgrade-via-npm.ps1 -SelfVersion                 # upgrade to repo version ($LOCAL_VERSION)"
     Write-Host ""
+    Write-Host "  -Pkg [scope/name]    Custom npm package (e.g. ryantest/openclaw-qqbot)"
     Write-Host "  -AppId [appid]       QQ bot appid (required on first install)"
     Write-Host "  -Secret [secret]     QQ bot secret (required on first install)"
     exit 0

package/scripts/upgrade-via-npm.sh

@@ -63,6 +63,7 @@ print_usage() {
         echo "  upgrade-via-npm.sh --self-version               # 升级到当前仓库版本"
     fi
     echo ""
+    echo "  --pkg <scope/name>    指定 npm 包名（如 ryantest/openclaw-qqbot）"
     echo "  --appid <appid>       QQ机器人 appid（首次安装时必填）"
     echo "  --secret <secret>     QQ机器人 secret（首次安装时必填）"
     echo ""
@@ -76,22 +77,17 @@ while [[ $# -gt 0 ]]; do
     case "$1" in
         --tag)
             [ -z "$2" ] && echo "❌ --tag 需要参数" && exit 1
-            _ver="${2#v}"  # 去掉 v 前缀（npm 版本号不带 v）
-            TARGET_VERSION="$_ver"
-            INSTALL_SRC="${PKG_NAME}@$_ver"
+            TARGET_VERSION="${2#v}"  # 去掉 v 前缀（npm 版本号不带 v）
             shift 2
             ;;
         --version)
             [ -z "$2" ] && echo "❌ --version 需要参数" && exit 1
-            _ver="${2#v}"  # 去掉 v 前缀（npm 版本号不带 v）
-            TARGET_VERSION="$_ver"
-            INSTALL_SRC="${PKG_NAME}@$_ver"
+            TARGET_VERSION="${2#v}"  # 去掉 v 前缀（npm 版本号不带 v）
             shift 2
             ;;
         --self-version)
             [ -z "$LOCAL_VERSION" ] && echo "❌ 无法从 package.json 读取版本" && exit 1
             TARGET_VERSION="$LOCAL_VERSION"
-            INSTALL_SRC="${PKG_NAME}@${LOCAL_VERSION}"
             shift 1
             ;;
         --appid)
@@ -104,6 +100,14 @@ while [[ $# -gt 0 ]]; do
             SECRET="$2"
             shift 2
             ;;
+        --pkg)
+            [ -z "$2" ] && echo "❌ --pkg 需要参数" && exit 1
+            _pkg="$2"
+            # 支持 "scope/name" 自动补 @
+            if [[ "$_pkg" != @* ]]; then _pkg="@$_pkg"; fi
+            PKG_NAME="$_pkg"
+            shift 2
+            ;;
         --no-restart)
             NO_RESTART=true
             shift 1
@@ -115,7 +119,12 @@ while [[ $# -gt 0 ]]; do
         *) echo "未知选项: $1"; print_usage; exit 1 ;;
     esac
 done
-INSTALL_SRC="${INSTALL_SRC:-${PKG_NAME}@latest}"
+# 参数解析完毕后统一拼接 INSTALL_SRC（确保 --pkg 无论在 --version 前后都能生效）
+if [ -n "$TARGET_VERSION" ]; then
+    INSTALL_SRC="${PKG_NAME}@${TARGET_VERSION}"
+else
+    INSTALL_SRC="${PKG_NAME}@latest"
+fi
 
 # 环境变量 fallback
 APPID="${APPID:-$QQBOT_APPID}"

package/scripts/upgrade-via-source.sh

@@ -344,13 +344,13 @@ if [ ! -f "$_INSTALL_DIR/dist/index.js" ] || [ ! -f "$_INSTALL_DIR/preload.cjs"
             echo "请先解决安装问题后再运行此脚本。"
             # 恢复 channels.qqbot 后再退出
             if [ -n "$_QQBOT_CHANNEL_STASH" ] && [ -n "$_STASH_CFG" ] && [ -f "$_STASH_CFG" ]; then
-                node -e "
-                    const fs = require('fs');
-                    const cfg = JSON.parse(fs.readFileSync('$_STASH_CFG', 'utf8'));
+                _STASH="$_QQBOT_CHANNEL_STASH" _CFG="$_STASH_CFG" node -e '
+                    const fs = require("fs");
+                    const cfg = JSON.parse(fs.readFileSync(process.env._CFG, "utf8"));
                     if (!cfg.channels) cfg.channels = {};
-                    cfg.channels.qqbot = $_QQBOT_CHANNEL_STASH;
-                    fs.writeFileSync('$_STASH_CFG', JSON.stringify(cfg, null, 4) + '\n');
-                " 2>/dev/null || true
+                    cfg.channels.qqbot = JSON.parse(process.env._STASH);
+                    fs.writeFileSync(process.env._CFG, JSON.stringify(cfg, null, 4) + "\n");
+                ' 2>/dev/null || true
             fi
             exit 1
             ;;  
@@ -592,11 +592,11 @@ echo "[4/6] 准备机器人通道配置..."
 # 注意：channels.qqbot 已被暂存移除，所以从 _QQBOT_CHANNEL_STASH 读取
 CURRENT_QQBOT_TOKEN=""
 if [ -n "$_QQBOT_CHANNEL_STASH" ]; then
-    CURRENT_QQBOT_TOKEN=$(node -e "
-        const ch = $_QQBOT_CHANNEL_STASH;
+    CURRENT_QQBOT_TOKEN=$(_STASH="$_QQBOT_CHANNEL_STASH" node -e '
+        const ch = JSON.parse(process.env._STASH);
         if (ch.token) { process.stdout.write(ch.token); }
-        else if (ch.appId && ch.clientSecret) { process.stdout.write(ch.appId + ':' + ch.clientSecret); }
-    " 2>/dev/null || true)
+        else if (ch.appId && ch.clientSecret) { process.stdout.write(ch.appId + ":" + ch.clientSecret); }
+    ' 2>/dev/null || true)
 fi
 
 DESIRED_QQBOT_TOKEN=""
@@ -787,34 +787,39 @@ case "$start_choice" in
 
             if [ -n "$_target_cfg" ]; then
                 # 构建完整的 channels.qqbot 对象（合并暂存配置 + 新 token + markdown）
-                node -e "
-                    const fs = require('fs');
-                    const cfg = JSON.parse(fs.readFileSync('$_target_cfg', 'utf8'));
+                # 通过环境变量传递，避免 JSON 双引号在 node -e "..." 中被 shell 错误解析
+                _STASH="$_QQBOT_CHANNEL_STASH" \
+                _DESIRED="$DESIRED_QQBOT_TOKEN" \
+                _MD="$MARKDOWN_VALUE" \
+                _CFG="$_target_cfg" \
+                node -e '
+                    const fs = require("fs");
+                    const cfg = JSON.parse(fs.readFileSync(process.env._CFG, "utf8"));
                     if (!cfg.channels) cfg.channels = {};
 
                     // 从暂存恢复基础配置
-                    const stash = '$_QQBOT_CHANNEL_STASH';
+                    const stash = process.env._STASH;
                     if (stash) {
                         try { cfg.channels.qqbot = JSON.parse(stash); } catch {}
                     }
                     if (!cfg.channels.qqbot) cfg.channels.qqbot = {};
 
                     // 覆盖 token（如果有新值）
-                    const desired = '$DESIRED_QQBOT_TOKEN';
-                    if (desired && desired.includes(':')) {
-                        const [appId, ...rest] = desired.split(':');
+                    const desired = process.env._DESIRED;
+                    if (desired && desired.includes(":")) {
+                        const [appId, ...rest] = desired.split(":");
                         cfg.channels.qqbot.appId = appId;
-                        cfg.channels.qqbot.clientSecret = rest.join(':');
+                        cfg.channels.qqbot.clientSecret = rest.join(":");
                         delete cfg.channels.qqbot.token;
                     }
 
                     // 覆盖 markdown（如果有指定）
-                    const md = '$MARKDOWN_VALUE';
-                    if (md === 'true') cfg.channels.qqbot.markdownSupport = true;
-                    else if (md === 'false') cfg.channels.qqbot.markdownSupport = false;
+                    const md = process.env._MD;
+                    if (md === "true") cfg.channels.qqbot.markdownSupport = true;
+                    else if (md === "false") cfg.channels.qqbot.markdownSupport = false;
 
-                    fs.writeFileSync('$_target_cfg', JSON.stringify(cfg, null, 4) + '\n');
-                " 2>/dev/null || true
+                    fs.writeFileSync(process.env._CFG, JSON.stringify(cfg, null, 4) + "\n");
+                ' 2>&1 || echo "  ⚠️  配置写入失败"
                 echo "  ✅ 已恢复 channels.qqbot 配置（含 token/markdown）"
                 _need_reload=1
             fi
@@ -884,13 +889,13 @@ case "$start_choice" in
         # 注意：下次 gateway 启动可能因 "unknown channel id" 失败，
         # 需要用户手动 stop → 移除 channels.qqbot → start → 恢复
         if [ -n "$_QQBOT_CHANNEL_STASH" ] && [ -n "$_STASH_CFG" ] && [ -f "$_STASH_CFG" ]; then
-            node -e "
-                const fs = require('fs');
-                const cfg = JSON.parse(fs.readFileSync('$_STASH_CFG', 'utf8'));
+            _STASH="$_QQBOT_CHANNEL_STASH" _CFG="$_STASH_CFG" node -e '
+                const fs = require("fs");
+                const cfg = JSON.parse(fs.readFileSync(process.env._CFG, "utf8"));
                 if (!cfg.channels) cfg.channels = {};
-                cfg.channels.qqbot = $_QQBOT_CHANNEL_STASH;
-                fs.writeFileSync('$_STASH_CFG', JSON.stringify(cfg, null, 4) + '\n');
-            " 2>/dev/null || true
+                cfg.channels.qqbot = JSON.parse(process.env._STASH);
+                fs.writeFileSync(process.env._CFG, JSON.stringify(cfg, null, 4) + "\n");
+            ' 2>/dev/null || true
             echo "  已恢复 channels.qqbot 配置"
         fi
         echo ""

package/src/api.ts

@@ -137,7 +137,7 @@ async function doFetchToken(appId: string, clientSecret: string): Promise<string
   const requestHeaders = { "Content-Type": "application/json", "User-Agent": PLUGIN_USER_AGENT };
   
   // 打印请求信息（隐藏敏感信息）
-  console.log(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL}`);
+  console.log(`[qqbot-api:${appId}] >>> POST ${TOKEN_URL} [secret: ${clientSecret.slice(0, 6)}...len=${clientSecret.length}]`);
 
   let response: Response;
   try {

package/src/slash-commands.ts

@@ -162,7 +162,7 @@ function checkUpgradeCompatibility(): UpgradeCompatResult {
   // 3. 检查 Node.js 版本
   const nodeVer = process.version.replace(/^v/, "");
   if (compareSemver(nodeVer, req.minNodeVersion) < 0) {
-    errors.push(`❌ Node.js 版本过低：当前 **v${nodeVer}**，热更新要求最低 **v${req.minNodeVersion}**`);
+    errors.push(`❌ NoVBNde.js 版本过低：当前 **v${nodeVer}**，热更新要求最低 **v${req.minNodeVersion}**`);
   }
 
   // 4. 检查系统架构（arm 等特殊架构提示）
@@ -746,14 +746,22 @@ function cleanupTempScript(): void {
  *
  * 安全机制：脚本会被复制到临时目录再执行，避免升级过程中插件目录被操作导致脚本自身丢失。
  */
-function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
-  // 优先从远端下载升级脚本，避免使用本地可能过时的版本
-  const scriptPath = downloadRemoteUpgradeScript() || (() => {
-    const local = getUpgradeScriptPath();
-    if (!local) return null;
-    console.log(`[qqbot] fireHotUpgrade: remote download failed, falling back to local script: ${local}`);
-    return copyScriptToTemp(local) || local;
-  })();
+function fireHotUpgrade(targetVersion?: string, pkg?: string, useLocal?: boolean): HotUpgradeStartResult {
+  // --local: 直接使用本地脚本，跳过远端下载
+  // 默认: 优先从远端下载升级脚本，避免使用本地可能过时的版本
+  const scriptPath = useLocal
+    ? (() => {
+      const local = getUpgradeScriptPath();
+      if (!local) return null;
+      console.log(`[qqbot] fireHotUpgrade: --local specified, using local script: ${local}`);
+      return copyScriptToTemp(local) || local;
+    })()
+    : downloadRemoteUpgradeScript() || (() => {
+      const local = getUpgradeScriptPath();
+      if (!local) return null;
+      console.log(`[qqbot] fireHotUpgrade: remote download failed, falling back to local script: ${local}`);
+      return copyScriptToTemp(local) || local;
+    })();
   if (!scriptPath) return { ok: false, reason: "no-script" };
 
   const cli = findCli();
@@ -772,16 +780,17 @@ function fireHotUpgrade(targetVersion?: string): HotUpgradeStartResult {
       "-File", scriptPath,
       "-NoRestart",
       ...(targetVersion ? ["-Version", targetVersion] : []),
+      ...(pkg ? ["-Pkg", pkg] : []),
     ];
   } 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] : [])];
+    shellArgs = [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : []), ...(pkg ? ["--pkg", pkg] : [])];
   }
 
-  console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}`);
+  console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}, pkg=${pkg || "default"}`);
 
   // 异步执行升级脚本
   execFile(shell, shellArgs, {
@@ -894,7 +903,9 @@ registerCommand({
     `/bot-upgrade              检查是否有新版本`,
     `/bot-upgrade --latest     确认升级到最新版本（需 upgradeMode=hot-reload）`,
     `/bot-upgrade --version X  升级到指定版本（需 upgradeMode=hot-reload）`,
+    `/bot-upgrade --pkg scope/name  指定 npm 包（如 ryantest/openclaw-qqbot）`,
     `/bot-upgrade --force      强制重新安装当前版本（需 upgradeMode=hot-reload）`,
+    `/bot-upgrade --local      使用本地升级脚本（跳过远端下载）`,
   ].join("\n"),
   handler: async (ctx) => {
     const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
@@ -949,7 +960,9 @@ registerCommand({
 
     let isForce = false;
     let isLatest = false;
+    let isLocal = false;
     let versionArg: string | undefined;
+    let pkgArg: string | undefined;
     const tokens = args ? args.split(/\s+/).filter(Boolean) : [];
     for (let i = 0; i < tokens.length; i += 1) {
       const t = tokens[i]!;
@@ -961,6 +974,27 @@ registerCommand({
         isLatest = true;
         continue;
       }
+      if (t === "--local") {
+        isLocal = true;
+        continue;
+      }
+      if (t === "--pkg") {
+        const next = tokens[i + 1];
+        if (!next || next.startsWith("--")) {
+          return `❌ 参数错误：--pkg 需要包名\n\n示例：/bot-upgrade --pkg ryantest/openclaw-qqbot`;
+        }
+        pkgArg = next;
+        i += 1;
+        continue;
+      }
+      if (t.startsWith("--pkg=")) {
+        const v = t.slice("--pkg=".length).trim();
+        if (!v) {
+          return `❌ 参数错误：--pkg 需要包名\n\n示例：/bot-upgrade --pkg ryantest/openclaw-qqbot`;
+        }
+        pkgArg = v;
+        continue;
+      }
       if (t === "--version") {
         const next = tokens[i + 1];
         if (!next || next.startsWith("--")) {
@@ -1022,9 +1056,17 @@ registerCommand({
       ].join("\n");
     }
 
+    // 解析 npm 包名：--pkg 参数 > 配置项 upgradePkg > 默认
+    // 支持 "scope/name"（自动补 @）和 "@scope/name" 两种格式
+    let upgradePkg = pkgArg || ctx.accountConfig?.upgradePkg;
+    if (upgradePkg) {
+      upgradePkg = upgradePkg.trim();
+      if (!upgradePkg.startsWith("@")) upgradePkg = `@${upgradePkg}`;
+    }
+
     // ── --version 指定版本：先校验版本号是否存在 ──
     if (versionArg) {
-      const exists = await checkVersionExists(versionArg);
+      const exists = await checkVersionExists(versionArg, upgradePkg);
       if (!exists) {
         return `❌ 版本 ${versionArg} 不存在，请检查版本号`;
       }
@@ -1077,7 +1119,7 @@ registerCommand({
     preUpgradeCredentialBackup(ctx.accountId, ctx.appId);
 
     // 异步执行升级
-    const startResult = fireHotUpgrade(targetVersion);
+    const startResult = fireHotUpgrade(targetVersion, upgradePkg, isLocal);
     if (!startResult.ok) {
       _upgrading = false;
       if (startResult.reason === "no-script") {

package/src/types.ts

@@ -101,6 +101,13 @@ export interface QQBotAccountConfig {
    * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新（默认）
    */
   upgradeMode?: "doc" | "hot-reload";
+  /**
+   * /bot-upgrade 热更新时使用的 npm 包名
+   * 支持 "scope/name"（自动补 @）或 "@scope/name" 格式
+   * 默认: "@tencent-connect/openclaw-qqbot"
+   * 示例: "ryantest/openclaw-qqbot"
+   */
+  upgradePkg?: string;
   /**
    * 出站消息合并回复（debounce）配置
    * 当短时间内收到多次 deliver 时，将文本合并为一条消息发送，避免消息轰炸

package/src/update-checker.ts

@@ -122,9 +122,12 @@ export async function getUpdateInfo(): Promise<UpdateInfo> {
 /**
  * 检查指定版本是否存在于 npm registry
  * 用于 /bot-upgrade --version 的前置校验
+ * @param version 要检查的版本号
+ * @param pkgName 可选的包名（如 "@ryantest/openclaw-qqbot"），默认使用内置包名
  */
-export async function checkVersionExists(version: string): Promise<boolean> {
-  for (const baseUrl of REGISTRIES) {
+export async function checkVersionExists(version: string, pkgName?: string): Promise<boolean> {
+  const registries = pkgName ? buildRegistries(pkgName) : REGISTRIES;
+  for (const baseUrl of registries) {
     try {
       const url = `${baseUrl}/${version}`;
       const json = await fetchJson(url, 10_000);
@@ -136,6 +139,15 @@ export async function checkVersionExists(version: string): Promise<boolean> {
   return false;
 }
 
+/** 根据自定义包名构建 registry URL 列表 */
+function buildRegistries(pkgName: string): string[] {
+  const encoded = encodeURIComponent(pkgName);
+  return [
+    `https://registry.npmjs.org/${encoded}`,
+    `https://registry.npmmirror.com/${encoded}`,
+  ];
+}
+
 function compareVersions(a: string, b: string): number {
   const parse = (v: string) => {
     const clean = v.replace(/^v/, "");