@ryantest/openclaw-qqbot 1.6.7-beta.1 → 1.6.7-beta.10

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.6`
+### 🚀 Current Version: `v1.6.7`
 
 [![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/)

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.6`
+### 🚀 当前版本： `v1.6.7`
 
 [![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/)

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,13 +687,106 @@ 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"}, pkg=${pkg || "default"}`);
+    // ── 兼容 openclaw 3.23+ 配置严格校验 ──
+    // openclaw plugins install/update 启动时会校验整个配置文件，
+    // 如果 channels.qqbot 已存在但 qqbot 插件尚未加载，校验会报 "unknown channel id: qqbot"。
+    //
+    // 在 TS 端（而非 shell 脚本端）创建临时配置，确保无论脚本版本新旧都能正确绕过校验。
+    // 通过 OPENCLAW_CONFIG_PATH 环境变量让 openclaw CLI 子进程使用临时配置。
+    const homeDir = getHomeDir();
+    const realConfigPath = path.join(homeDir, ".openclaw", "openclaw.json");
+    let tempConfigPath = null;
+    const childEnv = { ...process.env };
+    try {
+        if (fs.existsSync(realConfigPath)) {
+            const cfg = JSON.parse(fs.readFileSync(realConfigPath, "utf8"));
+            let needsTemp = false;
+            // 检查是否存在会导致校验失败的配置项
+            if (cfg.channels?.qqbot)
+                needsTemp = true;
+            if (Array.isArray(cfg.plugins?.allow) && cfg.plugins.allow.includes("openclaw-qqbot"))
+                needsTemp = true;
+            if (cfg.plugins?.entries?.["openclaw-qqbot"])
+                needsTemp = true;
+            if (needsTemp) {
+                const tmpCfg = JSON.parse(JSON.stringify(cfg)); // deep clone
+                // 移除 channels.qqbot
+                if (tmpCfg.channels?.qqbot) {
+                    delete tmpCfg.channels.qqbot;
+                    if (Object.keys(tmpCfg.channels).length === 0)
+                        delete tmpCfg.channels;
+                }
+                // 移除 plugins.allow 中的 openclaw-qqbot
+                if (Array.isArray(tmpCfg.plugins?.allow)) {
+                    tmpCfg.plugins.allow = tmpCfg.plugins.allow.filter((p) => p !== "openclaw-qqbot");
+                    if (tmpCfg.plugins.allow.length === 0)
+                        delete tmpCfg.plugins.allow;
+                }
+                // 移除 plugins.entries 中的 openclaw-qqbot
+                if (tmpCfg.plugins?.entries?.["openclaw-qqbot"]) {
+                    delete tmpCfg.plugins.entries["openclaw-qqbot"];
+                    if (Object.keys(tmpCfg.plugins.entries).length === 0)
+                        delete tmpCfg.plugins.entries;
+                }
+                const tmpDir = path.join(homeDir, ".openclaw", ".qqbot-upgrade-tmp");
+                fs.mkdirSync(tmpDir, { recursive: true });
+                tempConfigPath = path.join(tmpDir, "openclaw-tmp.json");
+                fs.writeFileSync(tempConfigPath, JSON.stringify(tmpCfg, null, 4) + "\n");
+                childEnv.OPENCLAW_CONFIG_PATH = tempConfigPath;
+                console.log(`[qqbot] fireHotUpgrade: created temp config (without channels.qqbot) at ${tempConfigPath}`);
+            }
+        }
+    }
+    catch (e) {
+        console.warn(`[qqbot] fireHotUpgrade: failed to create temp config: ${e.message}, proceeding with original`);
+        tempConfigPath = null;
+    }
+    /**
+     * 将临时配置中 plugins install/update 写入的记录同步回真实配置，然后清理临时文件。
+     */
+    function syncTempConfigAndCleanup() {
+        if (!tempConfigPath)
+            return;
+        try {
+            if (fs.existsSync(tempConfigPath) && fs.existsSync(realConfigPath)) {
+                const tmp = JSON.parse(fs.readFileSync(tempConfigPath, "utf8"));
+                const real = JSON.parse(fs.readFileSync(realConfigPath, "utf8"));
+                let changed = false;
+                // 同步 plugins.installs
+                if (tmp.plugins?.installs) {
+                    if (!real.plugins)
+                        real.plugins = {};
+                    real.plugins.installs = { ...(real.plugins.installs || {}), ...tmp.plugins.installs };
+                    changed = true;
+                }
+                // 同步 plugins.entries
+                if (tmp.plugins?.entries) {
+                    if (!real.plugins)
+                        real.plugins = {};
+                    real.plugins.entries = { ...(real.plugins.entries || {}), ...tmp.plugins.entries };
+                    changed = true;
+                }
+                if (changed) {
+                    fs.writeFileSync(realConfigPath, JSON.stringify(real, null, 4) + "\n");
+                    console.log("[qqbot] fireHotUpgrade: synced install/entries records from temp config to real config");
+                }
+            }
+        }
+        catch (e) {
+            console.warn(`[qqbot] fireHotUpgrade: failed to sync temp config: ${e.message}`);
+        }
+        try {
+            fs.unlinkSync(tempConfigPath);
+        }
+        catch { /* ignore */ }
     }
-    console.log(`[qqbot] fireHotUpgrade: shell=${shell}, script=${scriptPath}, cli=${cli}, target=${targetVersion || "latest"}`);
     // 异步执行升级脚本
     execFile(shell, shellArgs, {
         timeout: 120_000,
-        env: { ...process.env },
+        env: childEnv,
         ...(isWindows() ? { windowsHide: true } : {}),
     }, (error, stdout, _stderr) => {
         if (error) {
@@ -692,6 +795,7 @@ function fireHotUpgrade(targetVersion) {
                 console.error(`[qqbot] fireHotUpgrade: stdout: ${stdout.slice(0, 2000)}`);
             if (_stderr)
                 console.error(`[qqbot] fireHotUpgrade: stderr: ${_stderr.slice(0, 2000)}`);
+            syncTempConfigAndCleanup();
             cleanupTempScript();
             _upgrading = false;
             return;
@@ -702,12 +806,14 @@ function fireHotUpgrade(targetVersion) {
         const newVersion = versionMatch?.[1];
         if (newVersion === "unknown") {
             console.error(`[qqbot] fireHotUpgrade: script output QQBOT_NEW_VERSION=unknown, aborting restart`);
+            syncTempConfigAndCleanup();
             cleanupTempScript();
             _upgrading = false;
             return;
         }
         console.log(`[qqbot] fireHotUpgrade: new version=${newVersion || "(not detected)"}, triggering restart...`);
-        // 脚本执行成功，清理临时脚本副本
+        // 脚本执行成功，同步临时配置记录并清理
+        syncTempConfigAndCleanup();
         cleanupTempScript();
         // 文件替换成功，在 restart 之前把 source 从 path 切换为 npm，
         // 确保新进程启动时读到的是 npm source，不会被本地源码覆盖。
@@ -750,17 +856,122 @@ function fireHotUpgrade(targetVersion) {
             }
         }
         else {
-            // Mac/Linux: 直接 restart（框架通常以 daemon 模式运行）
-            execCliAsync(cli, ["gateway", "restart"], { timeout: 30_000 }, (restartErr) => {
-                if (restartErr) {
-                    console.error(`[qqbot] fireHotUpgrade: restart failed: ${restartErr.message}, trying stop+start fallback`);
-                    execCliAsync(cli, ["gateway", "stop"], { timeout: 10_000 }, () => {
-                        setTimeout(() => {
-                            execCliAsync(cli, ["gateway", "start"], { timeout: 30_000 }, () => { });
-                        }, 1000);
-                    });
+            // Mac/Linux: 使用 detached shell 脚本执行 stop+start
+            //
+            // 兼容 openclaw 2026.3.24+ 配置严格校验：
+            //   gateway restart 时 openclaw 先校验配置（loadConfig）再加载插件。
+            //   如果 channels.qqbot 存在但 qqbot channel type 尚未注册，校验会失败。
+            //   解决：stop 后临时移除 channels.qqbot → start（插件加载、qqbot type 注册）→ 恢复。
+            const cliInvoke = cli.endsWith(".mjs")
+                ? `"${process.execPath}" "${cli}"`
+                : `"${cli}"`;
+            const homeDir = getHomeDir();
+            const configPath = path.join(homeDir, ".openclaw", "openclaw.json");
+            const qqbotChannelBackup = path.join(homeDir, ".openclaw", ".qqbot-channel-backup.json");
+            const restartScript = path.join(homeDir, ".openclaw", ".qqbot-restart.sh");
+            // 先保存 channels.qqbot 到临时文件（在当前进程中，JSON 处理更安全）
+            let hasChannel = false;
+            try {
+                const cfgRaw = fs.readFileSync(configPath, "utf8");
+                const cfg = JSON.parse(cfgRaw);
+                const qqbot = cfg?.channels?.qqbot;
+                if (qqbot) {
+                    fs.writeFileSync(qqbotChannelBackup, JSON.stringify(qqbot, null, 2), "utf8");
+                    hasChannel = true;
                 }
-            });
+            }
+            catch {
+                // 配置文件不存在或 JSON 解析失败，不做处理
+            }
+            const shContent = `#!/bin/bash
+# 注意：不使用 set -e，因为 gateway start 失败时仍需恢复 channels.qqbot
+CLI="${cliInvoke}"
+CONFIG="${configPath}"
+BACKUP="${qqbotChannelBackup}"
+
+echo "[qqbot-upgrade] Stopping gateway..."
+$CLI gateway stop 2>/dev/null || true
+sleep 2
+
+if [ -f "$BACKUP" ]; then
+  echo "[qqbot-upgrade] Temporarily removing channels.qqbot and plugins.entries for config validation bypass..."
+  node -e "
+    const fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    let changed = false;
+    if (cfg.channels && cfg.channels.qqbot) {
+      delete cfg.channels.qqbot;
+      if (Object.keys(cfg.channels).length === 0) delete cfg.channels;
+      changed = true;
+    }
+    if (cfg.plugins && cfg.plugins.entries && cfg.plugins.entries['openclaw-qqbot']) {
+      delete cfg.plugins.entries['openclaw-qqbot'];
+      if (Object.keys(cfg.plugins.entries).length === 0) delete cfg.plugins.entries;
+      changed = true;
+    }
+    if (changed) {
+      fs.writeFileSync(process.argv[1], JSON.stringify(cfg, null, 4) + '\\n');
+    }
+  " "$CONFIG" 2>/dev/null
+  echo "[qqbot-upgrade] channels.qqbot temporarily removed"
+fi
+
+echo "[qqbot-upgrade] Starting gateway..."
+START_OK=false
+if $CLI gateway start 2>/dev/null; then
+  START_OK=true
+  echo "[qqbot-upgrade] Gateway started successfully"
+else
+  echo "[qqbot-upgrade] WARNING: gateway start failed, will still restore config"
+fi
+
+echo "[qqbot-upgrade] Waiting for plugin to load (8s)..."
+sleep 8
+
+if [ -f "$BACKUP" ]; then
+  echo "[qqbot-upgrade] Restoring channels.qqbot and plugins.entries..."
+  node -e "
+    const fs = require('fs');
+    const cfg = JSON.parse(fs.readFileSync(process.argv[1], 'utf8'));
+    const qqbot = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+    if (!cfg.channels) cfg.channels = {};
+    cfg.channels.qqbot = qqbot;
+    // 恢复 plugins.entries
+    if (!cfg.plugins) cfg.plugins = {};
+    if (!cfg.plugins.entries) cfg.plugins.entries = {};
+    if (!cfg.plugins.entries['openclaw-qqbot']) {
+      cfg.plugins.entries['openclaw-qqbot'] = { enabled: true };
+    }
+    fs.writeFileSync(process.argv[1], JSON.stringify(cfg, null, 4) + '\\n');
+  " "$CONFIG" "$BACKUP" 2>/dev/null
+  rm -f "$BACKUP"
+  echo "[qqbot-upgrade] channels.qqbot restored"
+fi
+
+# 如果 start 失败，尝试再次启动（此时 channels.qqbot 已恢复，插件可能已注册）
+if [ "$START_OK" != "true" ]; then
+  echo "[qqbot-upgrade] Retrying gateway start..."
+  sleep 2
+  $CLI gateway start 2>/dev/null || echo "[qqbot-upgrade] WARNING: retry also failed"
+fi
+
+# 清理自身
+rm -f "$0"
+echo "[qqbot-upgrade] Done."
+`;
+            try {
+                fs.writeFileSync(restartScript, shContent, { mode: 0o755 });
+                const child = spawn("bash", [restartScript], {
+                    detached: true,
+                    stdio: "ignore",
+                });
+                child.unref();
+                console.log(`[qqbot] fireHotUpgrade: launched detached restart script (pid=${child.pid}), hasChannel=${hasChannel}`);
+            }
+            catch (shErr) {
+                console.error(`[qqbot] fireHotUpgrade: failed to launch restart script: ${shErr.message}, falling back to direct restart`);
+                execCliAsync(cli, ["gateway", "restart"], { timeout: 30_000 }, () => { });
+            }
         }
     });
     return { ok: true };
@@ -786,11 +997,13 @@ 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;
-        const upgradeMode = ctx.accountConfig?.upgradeMode || "doc";
+        const upgradeMode = ctx.accountConfig?.upgradeMode || "hot-reload";
         const args = ctx.args.trim();
         const info = await getUpdateInfo();
         const GITHUB_URL = "https://github.com/tencent-connect/openclaw-qqbot/";
@@ -834,7 +1047,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 +1061,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 +1140,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 +1195,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

@@ -92,10 +92,17 @@ export interface QQBotAccountConfig {
     upgradeUrl?: string;
     /**
      * /bot-upgrade 指令的行为模式
-     * - "doc"：展示升级文档链接（默认，安全模式）
-     * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新
+     * - "doc"：展示升级文档链接（安全模式）
+     * - "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.1",
+  "version": "1.6.7-beta.10",
   "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