@tencent-connect/openclaw-qqbot 1.6.3 → 1.6.4-alpha.1

package/README.md

@@ -163,7 +163,7 @@ Measures end-to-end latency from QQ server push to plugin response, broken down
 
 > **You**: `/bot-version`
 >
-> **QQBot**: 🦞 Framework: OpenClaw 2026.3.13 (61d171a) / 🤖 Plugin: v1.6.2 / 🌟 GitHub repo
+> **QQBot**: 🦞 Framework: OpenClaw 2026.3.13 (61d171a) / 🤖 Plugin: v1.6.3 / 🌟 GitHub repo
 
 Shows framework version, plugin version, and a direct link to the official repository.
 

package/README.zh.md

@@ -158,7 +158,7 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 
 > **你**：`/bot-version`
 >
-> **QQBot**：🦞框架版本：OpenClaw 2026.3.13 (61d171a) / 🤖QQBot 插件版本：v1.6.2 / 🌟官方 GitHub 仓库
+> **QQBot**：🦞框架版本：OpenClaw 2026.3.13 (61d171a) / 🤖QQBot 插件版本：v1.6.3 / 🌟官方 GitHub 仓库
 
 一目了然查看框架版本、插件版本，并可直接跳转官方仓库。
 

package/clawdbot.plugin.json

@@ -3,7 +3,7 @@
   "name": "OpenClaw QQ Bot",
   "description": "QQ Bot channel plugin with message support, cron jobs, and proactive messaging",
   "channels": ["qqbot"],
-  "skills": ["skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-cron", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/dist/index.js

@@ -1,6 +1,7 @@
 import { emptyPluginConfigSchema } from "openclaw/plugin-sdk";
 import { qqbotPlugin } from "./src/channel.js";
 import { setQQBotRuntime } from "./src/runtime.js";
+import { registerChannelTool } from "./src/tools/channel.js";
 const plugin = {
     id: "openclaw-qqbot",
     name: "QQ Bot",
@@ -9,6 +10,7 @@ const plugin = {
     register(api) {
         setQQBotRuntime(api.runtime);
         api.registerChannel({ plugin: qqbotPlugin });
+        registerChannelTool(api);
     },
 };
 export default plugin;

package/dist/src/api.d.ts

@@ -81,6 +81,15 @@ export declare function sendChannelMessage(accessToken: string, channelId: strin
     id: string;
     timestamp: string;
 }>;
+/**
+ * 发送频道私信消息
+ * @param guildId - 私信会话的 guild_id（由 DIRECT_MESSAGE_CREATE 事件提供）
+ * @param msgId - 被动回复时必填
+ */
+export declare function sendDmMessage(accessToken: string, guildId: string, content: string, msgId?: string): Promise<{
+    id: string;
+    timestamp: string;
+}>;
 export declare function sendGroupMessage(accessToken: string, groupOpenid: string, content: string, msgId?: string): Promise<MessageResponse>;
 export declare function sendProactiveC2CMessage(accessToken: string, openid: string, content: string): Promise<MessageResponse>;
 export declare function sendProactiveGroupMessage(accessToken: string, groupOpenid: string, content: string): Promise<{

package/dist/src/api.js

@@ -340,6 +340,17 @@ export async function sendChannelMessage(accessToken, channelId, content, msgId)
         ...(msgId ? { msg_id: msgId } : {}),
     });
 }
+/**
+ * 发送频道私信消息
+ * @param guildId - 私信会话的 guild_id（由 DIRECT_MESSAGE_CREATE 事件提供）
+ * @param msgId - 被动回复时必填
+ */
+export async function sendDmMessage(accessToken, guildId, content, msgId) {
+    return apiRequest(accessToken, "POST", `/dms/${guildId}/messages`, {
+        content,
+        ...(msgId ? { msg_id: msgId } : {}),
+    });
+}
 export async function sendGroupMessage(accessToken, groupOpenid, content, msgId) {
     const msgSeq = msgId ? getNextMsgSeq(msgId) : 1;
     const body = buildMessageBody(content, msgId, msgSeq);

package/dist/src/gateway.js

@@ -438,21 +438,23 @@ export async function startGateway(ctx) {
                 const greeting = getStartupGreeting();
                 if (!greeting) {
                     log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (debounced, trigger=${trigger})`);
-                    return;
                 }
-                const adminId = resolveAdminOpenId();
-                if (!adminId) {
-                    log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (no admin or known user)`);
-                    return;
+                else {
+                    const adminId = resolveAdminOpenId();
+                    if (!adminId) {
+                        log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (no admin or known user)`);
+                    }
+                    else {
+                        log?.info(`[qqbot:${account.accountId}] Sending startup greeting to admin (trigger=${trigger}): "${greeting}"`);
+                        const token = await getAccessToken(account.appId, account.clientSecret);
+                        const GREETING_TIMEOUT_MS = 10_000;
+                        await Promise.race([
+                            sendProactiveC2CMessage(token, adminId, greeting),
+                            new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
+                        ]);
+                        log?.info(`[qqbot:${account.accountId}] Sent startup greeting to admin: ${adminId}`);
+                    }
                 }
-                log?.info(`[qqbot:${account.accountId}] Sending startup greeting to admin (trigger=${trigger}): "${greeting}"`);
-                const token = await getAccessToken(account.appId, account.clientSecret);
-                const GREETING_TIMEOUT_MS = 10_000;
-                await Promise.race([
-                    sendProactiveC2CMessage(token, adminId, greeting),
-                    new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
-                ]);
-                log?.info(`[qqbot:${account.accountId}] Sent startup greeting to admin: ${adminId}`);
             }
             catch (err) {
                 log?.error(`[qqbot:${account.accountId}] Failed to send startup greeting: ${err}`);

package/dist/src/slash-commands.js

@@ -11,10 +11,12 @@
  *   从而计算「开平→插件」和「插件处理」两段耗时
  */
 import { createRequire } from "node:module";
-import { execFileSync } from "node:child_process";
+import { execFileSync, execFile } from "node:child_process";
 import path from "node:path";
 import fs from "node:fs";
 import { getUpdateInfo } from "./update-checker.js";
+import { getHomeDir, isWindows } from "./utils/platform.js";
+import { fileURLToPath } from "node:url";
 const require = createRequire(import.meta.url);
 // 读取 package.json 中的版本号
 let PLUGIN_VERSION = "unknown";
@@ -124,54 +126,235 @@ registerCommand({
     },
 });
 const DEFAULT_UPGRADE_URL = "https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg";
+// ============ 热更新 ============
 /**
- * /bot-upgrade — 查看版本更新状态 + 升级指引
+ * 找到 CLI 命令名（openclaw / clawdbot / moltbot）
+ */
+function findCli() {
+    const whichCmd = isWindows() ? "where" : "which";
+    for (const cli of ["openclaw", "clawdbot", "moltbot"]) {
+        try {
+            execFileSync(whichCmd, [cli], { timeout: 3000, encoding: "utf8", stdio: "pipe" });
+            return cli;
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+/**
+ * 找到升级脚本路径（兼容源码运行、dist 运行、已安装扩展目录）
+ */
+function getUpgradeScriptPath() {
+    const currentFile = fileURLToPath(import.meta.url);
+    const currentDir = path.dirname(currentFile);
+    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"),
+    ];
+    const homeDir = getHomeDir();
+    for (const cli of ["openclaw", "clawdbot", "moltbot"]) {
+        candidates.push(path.join(homeDir, `.${cli}`, "extensions", "openclaw-qqbot", "scripts", "upgrade-via-npm.sh"));
+    }
+    for (const p of candidates) {
+        if (fs.existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * 在 Windows 上查找可用的 bash（Git Bash / WSL 等）
+ */
+function findBash() {
+    if (!isWindows())
+        return "bash";
+    // Git Bash 常见路径
+    const candidates = [
+        path.join(process.env.ProgramFiles || "C:\\Program Files", "Git", "bin", "bash.exe"),
+        path.join(process.env["ProgramFiles(x86)"] || "C:\\Program Files (x86)", "Git", "bin", "bash.exe"),
+        path.join(process.env.LOCALAPPDATA || "", "Programs", "Git", "bin", "bash.exe"),
+    ];
+    for (const p of candidates) {
+        if (p && fs.existsSync(p))
+            return p;
+    }
+    // 尝试 PATH 中的 bash
+    try {
+        execFileSync("where", ["bash"], { timeout: 3000, encoding: "utf8", stdio: "pipe" });
+        return "bash";
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * 执行热更新：执行脚本(--no-restart) → 触发 gateway restart
+ *
+ * fire-and-forget 操作：
+ * - 异步执行升级脚本（--no-restart，只做文件替换）
+ * - 脚本完成后触发 gateway restart（当前进程会被杀掉）
+ * - 新进程启动时 getStartupGreeting() 检测到版本变更，自动通知管理员
+ */
+function fireHotUpgrade(targetVersion) {
+    const scriptPath = getUpgradeScriptPath();
+    if (!scriptPath)
+        return { ok: false, reason: "no-script" };
+    const cli = findCli();
+    if (!cli)
+        return { ok: false, reason: "no-cli" };
+    const bash = findBash();
+    if (!bash)
+        return { ok: false, reason: "no-bash" };
+    // 异步执行升级脚本
+    execFile(bash, [scriptPath, "--no-restart", ...(targetVersion ? ["--version", targetVersion] : [])], {
+        timeout: 120_000,
+        env: { ...process.env },
+        ...(isWindows() ? { windowsHide: true } : {}),
+    }, (error, _stdout, _stderr) => {
+        if (error) {
+            return;
+        }
+        // 文件替换成功，触发 gateway restart
+        execFile(cli, ["gateway", "restart"], { timeout: 30_000 }, () => { });
+    });
+    return { ok: true };
+}
+/**
+ * /bot-upgrade — 统一升级入口：能热更就热更，失败则返回升级指引
+ *
+ * 支持参数：
+ *   /bot-upgrade           — 检查更新后自动热更
+ *   /bot-upgrade 1.6.4     — 升级到指定版本
+ *   /bot-upgrade --force   — 强制升级（即使当前已是最新版）
  */
 registerCommand({
     name: "bot-upgrade",
-    description: "查看版本更新与升级指引",
+    description: "检查更新并自动热更（失败则返回升级指引）",
     handler: (ctx) => {
+        // 升级相关指令仅在私聊中可用
+        if (ctx.type !== "c2c") {
+            return `💡 请在私聊中使用此指令`;
+        }
         const url = ctx.accountConfig?.upgradeUrl || DEFAULT_UPGRADE_URL;
+        const args = ctx.args.trim();
         const info = getUpdateInfo();
-        const lines = [];
-        lines.push(`📌当前版本：v${PLUGIN_VERSION}`);
-        if (info.checkedAt === 0) {
-            lines.push(`⏳ 版本检查中，请稍后再试`);
-        }
-        else if (info.error) {
-            lines.push(`⚠️ 版本检查失败`);
+        const isForce = args.includes("--force");
+        const versionArg = args.replace("--force", "").trim() || undefined;
+        if (!versionArg && !isForce) {
+            if (info.checkedAt === 0) {
+                return `⏳ 版本检查中，请稍后再试`;
+            }
+            if (info.error) {
+                return `⚠️ 版本检查失败\n⬆️升级指引：[点击查看](${url})`;
+            }
+            if (!info.hasUpdate) {
+                return `✅ 当前版本 v${PLUGIN_VERSION} 已是最新，无需升级\n\n> 💡 使用 /bot-upgrade --force 可强制重新安装`;
+            }
         }
-        else if (info.hasUpdate && info.latest) {
-            lines.push(`🆕最新可用版本：v${info.latest}`);
+        const targetVersion = versionArg || info.latest || undefined;
+        // 异步执行升级
+        const startResult = fireHotUpgrade(targetVersion);
+        if (!startResult.ok) {
+            if (startResult.reason === "no-script") {
+                return `❌ 未找到本地升级脚本\n⬆️升级指引：[点击查看](${url})`;
+            }
+            if (startResult.reason === "no-cli") {
+                return `❌ 未找到 openclaw / clawdbot / moltbot CLI\n⬆️升级指引：[点击查看](${url})`;
+            }
+            return `❌ 当前环境不支持热更新（需要 bash 环境）\n⬆️升级指引：[点击查看](${url})\n\n> Windows 用户请安装 Git for Windows 后重试，或手动执行升级脚本`;
         }
-        else {
-            lines.push(`✅ 当前已是最新版本`);
+        const lines = [
+            `🔄 开始热更新...`,
+            `📌 当前版本：v${PLUGIN_VERSION}`,
+        ];
+        if (targetVersion) {
+            lines.push(`🎯 目标版本：v${targetVersion}`);
         }
-        lines.push(`⬆️升级指引：[点击查看](${url})`);
-        lines.push(`🌟官方 GitHub 仓库：[点击前往](https://github.com/tencent-connect/openclaw-qqbot/)`);
+        lines.push(``);
+        lines.push(`⏳ 升级过程约需 30~60 秒，完成后会自动通知您`);
         return lines.join("\n");
     },
 });
 /**
  * /bot-logs — 导出本地日志文件
+ *
+ * 日志路径检测策略（兼容特殊安装路径和 --profile/--dev 模式）：
+ * 1. OPENCLAW_STATE_DIR 环境变量指定的目录
+ * 2. 扫描 home 目录下所有 .openclaw-xxx/logs/ 目录，取最近修改的 gateway.log
  */
 registerCommand({
     name: "bot-logs",
     description: "导出本地日志文件",
     handler: () => {
-        const homeDir = process.env.HOME || "~";
-        const logDir = path.join(homeDir, ".openclaw", "logs");
-        const gatewayLog = path.join(logDir, "gateway.log");
-        const errLog = path.join(logDir, "gateway.err.log");
+        const homeDir = getHomeDir();
+        // 收集所有可能的日志目录
+        const logDirs = [];
+        // 优先：环境变量指定的状态目录
+        const stateDir = process.env.OPENCLAW_STATE_DIR;
+        if (stateDir) {
+            logDirs.push(path.join(stateDir, "logs"));
+        }
+        // 扫描搜索根目录列表（兼容 Windows APPDATA 路径）
+        const searchRoots = new Set([homeDir]);
+        const appData = process.env.APPDATA; // Windows: C:\Users\xxx\AppData\Roaming
+        if (appData)
+            searchRoots.add(appData);
+        const localAppData = process.env.LOCALAPPDATA; // Windows: C:\Users\xxx\AppData\Local
+        if (localAppData)
+            searchRoots.add(localAppData);
+        for (const root of searchRoots) {
+            try {
+                const entries = fs.readdirSync(root, { withFileTypes: true });
+                for (const entry of entries) {
+                    if (entry.isDirectory() && (entry.name.startsWith(".openclaw") || entry.name.startsWith("openclaw"))) {
+                        const candidate = path.join(root, entry.name, "logs");
+                        if (!logDirs.includes(candidate)) {
+                            logDirs.push(candidate);
+                        }
+                    }
+                }
+            }
+            catch {
+                // 无权限或不存在，跳过
+            }
+        }
+        // 兜底：默认路径
+        const defaultLogDir = path.join(homeDir, ".openclaw", "logs");
+        if (!logDirs.includes(defaultLogDir)) {
+            logDirs.push(defaultLogDir);
+        }
+        // 从所有候选目录中找到存在且最近修改的 gateway.log
+        let bestLogDir = null;
+        let bestMtime = 0;
+        for (const logDir of logDirs) {
+            const gatewayLog = path.join(logDir, "gateway.log");
+            try {
+                const stat = fs.statSync(gatewayLog);
+                if (stat.mtimeMs > bestMtime) {
+                    bestMtime = stat.mtimeMs;
+                    bestLogDir = logDir;
+                }
+            }
+            catch {
+                // 不存在或无权限，跳过
+            }
+        }
+        if (!bestLogDir) {
+            const searched = logDirs.map(d => `  - ${d}`).join("\n");
+            return `⚠️ 未找到日志文件\n\n已搜索以下路径：\n${searched}`;
+        }
+        const gatewayLog = path.join(bestLogDir, "gateway.log");
+        const errLog = path.join(bestLogDir, "gateway.err.log");
         const lines = [];
-        // 读取 gateway.log 最后 2000 行
         for (const logFile of [gatewayLog, errLog]) {
             if (!fs.existsSync(logFile))
                 continue;
             try {
                 const content = fs.readFileSync(logFile, "utf8");
                 const allLines = content.split("\n");
-                const tail = allLines.slice(-1000); // 每个文件取最后 1000 行
+                const tail = allLines.slice(-1000);
                 if (tail.length > 0) {
                     lines.push(`\n========== ${path.basename(logFile)} (last ${tail.length} lines) ==========\n`);
                     lines.push(...tail);
@@ -182,7 +365,7 @@ registerCommand({
             }
         }
         if (lines.length === 0) {
-            return "⚠️ 未找到日志文件";
+            return `⚠️ 日志文件为空（路径：${bestLogDir}）`;
         }
         // 写入临时文件
         const tmpDir = path.join(homeDir, ".openclaw", "qqbot", "downloads");
@@ -194,7 +377,7 @@ registerCommand({
         fs.writeFileSync(tmpFile, lines.join("\n"), "utf8");
         const totalLines = lines.filter(l => !l.startsWith("=")).length;
         return {
-            text: `📋 日志已打包（约 ${totalLines} 行），正在发送文件...`,
+            text: `📋 日志已打包（约 ${totalLines} 行），正在发送文件...\n📂 来源：${bestLogDir}`,
             filePath: tmpFile,
         };
     },

package/dist/src/tools/channel.d.ts

@@ -0,0 +1,16 @@
+import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
+/**
+ * 注册 QQ 频道 API 代理工具。
+ *
+ * 该工具作为 QQ 开放平台频道 API 的 HTTP 代理，自动处理 Token 鉴权。
+ * AI 通过 skill 文档了解各接口的路径、方法和参数，构造请求后由此工具代理发送。
+ *
+ * 支持的能力：
+ * - 频道管理（Guild）
+ * - 子频道管理（Channel）
+ * - 成员管理（Member）
+ * - 公告管理（Announces）
+ * - 论坛管理（Forum Thread）
+ * - 日程管理（Schedule）
+ */
+export declare function registerChannelTool(api: OpenClawPluginApi): void;

package/dist/src/tools/channel.js

@@ -0,0 +1,234 @@
+import { resolveQQBotAccount } from "../config.js";
+import { listQQBotAccountIds } from "../config.js";
+import { getAccessToken } from "../api.js";
+// ========== 常量 ==========
+const API_BASE = "https://api.sgroup.qq.com";
+const DEFAULT_TIMEOUT_MS = 30000;
+// ========== JSON Schema ==========
+const ChannelApiSchema = {
+    type: "object",
+    properties: {
+        method: {
+            type: "string",
+            description: "HTTP 请求方法。可选值：GET, POST, PUT, PATCH, DELETE",
+            enum: ["GET", "POST", "PUT", "PATCH", "DELETE"],
+        },
+        path: {
+            type: "string",
+            description: "API 路径（不含域名），占位符需替换为实际值。" +
+                "示例：/users/@me/guilds, /guilds/{guild_id}/channels, /channels/{channel_id}",
+        },
+        body: {
+            type: "object",
+            description: "请求体（JSON），用于 POST/PUT/PATCH 请求。" +
+                "GET/DELETE 请求不需要此参数。",
+        },
+        query: {
+            type: "object",
+            description: "URL 查询参数（键值对），会拼接到路径后面。" +
+                "如 { \"limit\": \"100\", \"after\": \"0\" } 会拼接为 ?limit=100&after=0",
+            additionalProperties: { type: "string" },
+        },
+    },
+    required: ["method", "path"],
+};
+// ========== 工具函数 ==========
+function json(data) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
+        details: data,
+    };
+}
+/**
+ * 构建完整的请求 URL
+ */
+function buildUrl(path, query) {
+    let url = `${API_BASE}${path}`;
+    if (query && Object.keys(query).length > 0) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query)) {
+            if (value !== undefined && value !== null && value !== "") {
+                params.set(key, value);
+            }
+        }
+        const qs = params.toString();
+        if (qs) {
+            url += `?${qs}`;
+        }
+    }
+    return url;
+}
+/**
+ * 校验 path 防止 SSRF
+ */
+function validatePath(path) {
+    if (!path.startsWith("/")) {
+        return "path 必须以 / 开头";
+    }
+    if (path.includes("..") || path.includes("//")) {
+        return "path 不允许包含 .. 或 //";
+    }
+    // 只允许合法的 URL path 字符
+    if (!/^\/[a-zA-Z0-9\-._~:@!$&'()*+,;=/%]+$/.test(path) && path !== "/") {
+        return "path 包含非法字符";
+    }
+    return null;
+}
+// ========== 注册入口 ==========
+/**
+ * 注册 QQ 频道 API 代理工具。
+ *
+ * 该工具作为 QQ 开放平台频道 API 的 HTTP 代理，自动处理 Token 鉴权。
+ * AI 通过 skill 文档了解各接口的路径、方法和参数，构造请求后由此工具代理发送。
+ *
+ * 支持的能力：
+ * - 频道管理（Guild）
+ * - 子频道管理（Channel）
+ * - 成员管理（Member）
+ * - 公告管理（Announces）
+ * - 论坛管理（Forum Thread）
+ * - 日程管理（Schedule）
+ */
+export function registerChannelTool(api) {
+    const cfg = api.config;
+    if (!cfg) {
+        console.log("[qqbot-channel-api] No config available, skipping");
+        return;
+    }
+    const accountIds = listQQBotAccountIds(cfg);
+    if (accountIds.length === 0) {
+        console.log("[qqbot-channel-api] No QQBot accounts configured, skipping");
+        return;
+    }
+    const firstAccountId = accountIds[0];
+    const account = resolveQQBotAccount(cfg, firstAccountId);
+    if (!account.appId || !account.clientSecret) {
+        console.log("[qqbot-channel-api] Account not fully configured, skipping");
+        return;
+    }
+    api.registerTool({
+        name: "qqbot_channel_api",
+        label: "QQBot Channel API",
+        description: "QQ 开放平台频道 API HTTP 代理，自动填充鉴权 Token。" +
+            "常用接口速查：" +
+            "频道列表 GET /users/@me/guilds | " +
+            "子频道列表 GET /guilds/{guild_id}/channels | " +
+            "子频道详情 GET /channels/{channel_id} | " +
+            "创建子频道 POST /guilds/{guild_id}/channels | " +
+            "成员列表 GET /guilds/{guild_id}/members?after=0&limit=100 | " +
+            "成员详情 GET /guilds/{guild_id}/members/{user_id} | " +
+            "帖子列表 GET /channels/{channel_id}/threads | " +
+            "发帖 PUT /channels/{channel_id}/threads | " +
+            "创建公告 POST /guilds/{guild_id}/announces | " +
+            "创建日程 POST /channels/{channel_id}/schedules。" +
+            "更多接口和参数详情请阅读 qqbot-channel skill。",
+        parameters: ChannelApiSchema,
+        async execute(_toolCallId, params) {
+            const p = params;
+            // 参数校验
+            if (!p.method) {
+                return json({ error: "method 为必填参数" });
+            }
+            if (!p.path) {
+                return json({ error: "path 为必填参数" });
+            }
+            const method = p.method.toUpperCase();
+            if (!["GET", "POST", "PUT", "PATCH", "DELETE"].includes(method)) {
+                return json({ error: `不支持的 HTTP 方法: ${method}，可选值：GET, POST, PUT, PATCH, DELETE` });
+            }
+            // 路径安全校验
+            const pathError = validatePath(p.path);
+            if (pathError) {
+                return json({ error: pathError });
+            }
+            // GET/DELETE 不应有 body
+            if ((method === "GET" || method === "DELETE") && p.body && Object.keys(p.body).length > 0) {
+                console.log(`[qqbot-channel-api] ${method} request with body, body will be ignored`);
+            }
+            try {
+                // 获取鉴权 Token
+                const accessToken = await getAccessToken(account.appId, account.clientSecret);
+                // 构建请求
+                const url = buildUrl(p.path, p.query);
+                const headers = {
+                    Authorization: `QQBot ${accessToken}`,
+                    "Content-Type": "application/json",
+                };
+                const controller = new AbortController();
+                const timeoutId = setTimeout(() => controller.abort(), DEFAULT_TIMEOUT_MS);
+                const fetchOptions = {
+                    method,
+                    headers,
+                    signal: controller.signal,
+                };
+                // POST/PUT/PATCH 才发送 body
+                if (p.body && ["POST", "PUT", "PATCH"].includes(method)) {
+                    fetchOptions.body = JSON.stringify(p.body);
+                }
+                console.log(`[qqbot-channel-api] >>> ${method} ${url} (timeout: ${DEFAULT_TIMEOUT_MS}ms)`);
+                let res;
+                try {
+                    res = await fetch(url, fetchOptions);
+                }
+                catch (err) {
+                    clearTimeout(timeoutId);
+                    if (err instanceof Error && err.name === "AbortError") {
+                        console.error(`[qqbot-channel-api] <<< Request timeout after ${DEFAULT_TIMEOUT_MS}ms`);
+                        return json({ error: `请求超时（${DEFAULT_TIMEOUT_MS}ms）`, path: p.path });
+                    }
+                    console.error(`[qqbot-channel-api] <<< Network error:`, err);
+                    return json({
+                        error: `网络错误: ${err instanceof Error ? err.message : String(err)}`,
+                        path: p.path,
+                    });
+                }
+                finally {
+                    clearTimeout(timeoutId);
+                }
+                console.log(`[qqbot-channel-api] <<< Status: ${res.status} ${res.statusText}`);
+                // 解析响应
+                const rawBody = await res.text();
+                // 空响应（如 DELETE 204）
+                if (!rawBody || rawBody.trim() === "") {
+                    if (res.ok) {
+                        return json({ success: true, status: res.status, path: p.path });
+                    }
+                    return json({
+                        error: `API 返回 ${res.status} ${res.statusText}`,
+                        status: res.status,
+                        path: p.path,
+                    });
+                }
+                let data;
+                try {
+                    data = JSON.parse(rawBody);
+                }
+                catch {
+                    return json({
+                        error: "响应解析失败",
+                        status: res.status,
+                        raw: rawBody.slice(0, 500),
+                        path: p.path,
+                    });
+                }
+                if (!res.ok) {
+                    const errData = data;
+                    return json({
+                        error: errData.message ?? `API 错误 (HTTP ${res.status})`,
+                        code: errData.code,
+                        status: res.status,
+                        path: p.path,
+                        detail: data,
+                    });
+                }
+                return json(data);
+            }
+            catch (err) {
+                const errMsg = err instanceof Error ? err.message : String(err);
+                console.error(`[qqbot-channel-api] Error [${method} ${p.path}]: ${errMsg}`);
+                return json({ error: errMsg, path: p.path });
+            }
+        },
+    }, { name: "qqbot_channel_api" });
+    console.log("[qqbot-channel-api] Registered QQ channel API proxy tool");
+}

package/dist/src/types.d.ts

@@ -62,6 +62,12 @@ export interface QQBotAccountConfig {
      * 默认: https://doc.weixin.qq.com/doc/w3_AKEAGQaeACgCNHrh1CbHzTAKtT2gB?scode=AJEAIQdfAAozxFEnLZAKEAGQaeACg
      */
     upgradeUrl?: string;
+    /**
+     * /bot-upgrade 指令的行为模式
+     * - "doc"：展示升级文档链接（默认，安全模式）
+     * - "hot-reload"：检测到新版本时直接执行 npm 升级脚本进行热更新
+     */
+    upgradeMode?: "doc" | "hot-reload";
 }
 /**
  * 音频格式策略：控制哪些格式可跳过转换