@tencent-connect/openclaw-qqbot 1.6.0-alpha.1 → 1.6.0-alpha.qqchannel

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

@@ -335,6 +335,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

@@ -7,6 +7,7 @@ import { recordKnownUser, flushKnownUsers, listKnownUsers } from "./known-users.
 import { getQQBotRuntime } from "./runtime.js";
 import { setRefIndex, getRefIndex, formatRefEntryForAgent, flushRefIndex } from "./ref-index-store.js";
 import { matchSlashCommand } from "./slash-commands.js";
+import { triggerUpdateCheck } from "./update-checker.js";
 import { startImageServer, isImageServerRunning, downloadFile } from "./image-server.js";
 import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize } from "./utils/image-size.js";
 import { parseQQBotPayload, encodePayloadForCron, isCronReminderPayload, isMediaPayload } from "./utils/payload.js";
@@ -273,6 +274,8 @@ export async function startGateway(ctx) {
             log?.info(`[qqbot:${account.accountId}] ${w}`);
         }
     }
+    // 后台版本检查（detached 子进程，零阻塞）
+    triggerUpdateCheck(log);
     // 初始化 API 配置（markdown 支持）
     initApiConfig({
         markdownSupport: account.markdownSupport,
@@ -345,6 +348,7 @@ export async function startGateway(ctx) {
     let isConnecting = false; // 防止并发连接
     let reconnectTimer = null; // 重连定时器
     let shouldRefreshToken = false; // 下次连接是否需要刷新 token
+    let isFirstReady = true; // 仅 startGateway 后首次 READY 才发送上线通知
     // ============ P1-2: 尝试从持久化存储恢复 Session ============
     // 传入当前 appId，如果 appId 已变更（换了机器人），旧 session 自动失效
     const savedSession = loadSession(account.accountId, account.appId);
@@ -923,7 +927,7 @@ export async function startGateway(ctx) {
                 // TTS 能力声明：仅在启用时告知 AI 可以发语音（与 qqbot-media SKILL.md 互补）
                 // STT 无需声明：转写结果已在动态上下文的 ASR 行中，AI 自然可见
                 if (hasTTS)
-                    staticParts.push("语音合成已启用，可用<qqmedia>发送语音");
+                    staticParts.push("语音合成已启用，发送媒体格式：<qqmedia>路径</qqmedia>");
                 const staticInstruction = staticParts.join(" | ");
                 // 静态指引作为 systemPrompts 的首项注入
                 systemPrompts.unshift(staticInstruction);
@@ -2190,46 +2194,53 @@ export async function startGateway(ctx) {
                                     appId: account.appId,
                                 });
                                 onReady?.(d);
-                                // 启动成功后向已知用户发送上线通知（异步，不阻塞主流程）
-                                (async () => {
-                                    try {
-                                        const greeting = `Haha，我的'灵魂'已上线，随时等你吩咐。`;
-                                        const token = await getAccessToken(account.appId, account.clientSecret);
-                                        const users = listKnownUsers({ accountId: account.accountId, type: "c2c" });
-                                        for (const user of users) {
-                                            try {
-                                                await sendProactiveC2CMessage(token, user.openid, greeting);
-                                                log?.info(`[qqbot:${account.accountId}] Sent startup greeting to c2c:${user.openid}`);
+                                // 仅 startGateway 后的首次 READY 才发送上线通知
+                                // ws 断线重连（resume 失败后重新 Identify）产生的 READY 不发送
+                                if (!isFirstReady) {
+                                    log?.info(`[qqbot:${account.accountId}] Skipping startup greeting (reconnect READY, not first startup)`);
+                                }
+                                else {
+                                    isFirstReady = false;
+                                    (async () => {
+                                        try {
+                                            const greeting = `Haha，我的'灵魂'已上线，随时等你吩咐。`;
+                                            const token = await getAccessToken(account.appId, account.clientSecret);
+                                            const users = listKnownUsers({ accountId: account.accountId, type: "c2c" });
+                                            for (const user of users) {
+                                                try {
+                                                    await sendProactiveC2CMessage(token, user.openid, greeting);
+                                                    log?.info(`[qqbot:${account.accountId}] Sent startup greeting to c2c:${user.openid}`);
+                                                }
+                                                catch (err) {
+                                                    log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to c2c:${user.openid}: ${err}`);
+                                                }
+                                                // 避免频率限制
+                                                await new Promise(r => setTimeout(r, 500));
                                             }
-                                            catch (err) {
-                                                log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to c2c:${user.openid}: ${err}`);
+                                            const groups = listKnownUsers({ accountId: account.accountId, type: "group" });
+                                            // 群组去重（同一群只发一次）
+                                            const sentGroups = new Set();
+                                            for (const user of groups) {
+                                                const gid = user.groupOpenid;
+                                                if (!gid || sentGroups.has(gid))
+                                                    continue;
+                                                sentGroups.add(gid);
+                                                try {
+                                                    await sendProactiveGroupMessage(token, gid, greeting);
+                                                    log?.info(`[qqbot:${account.accountId}] Sent startup greeting to group:${gid}`);
+                                                }
+                                                catch (err) {
+                                                    log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to group:${gid}: ${err}`);
+                                                }
+                                                await new Promise(r => setTimeout(r, 500));
                                             }
-                                            // 避免频率限制
-                                            await new Promise(r => setTimeout(r, 500));
+                                            log?.info(`[qqbot:${account.accountId}] Startup greetings sent (${users.length} c2c, ${sentGroups.size} groups)`);
                                         }
-                                        const groups = listKnownUsers({ accountId: account.accountId, type: "group" });
-                                        // 群组去重（同一群只发一次）
-                                        const sentGroups = new Set();
-                                        for (const user of groups) {
-                                            const gid = user.groupOpenid;
-                                            if (!gid || sentGroups.has(gid))
-                                                continue;
-                                            sentGroups.add(gid);
-                                            try {
-                                                await sendProactiveGroupMessage(token, gid, greeting);
-                                                log?.info(`[qqbot:${account.accountId}] Sent startup greeting to group:${gid}`);
-                                            }
-                                            catch (err) {
-                                                log?.debug?.(`[qqbot:${account.accountId}] Failed to send startup greeting to group:${gid}: ${err}`);
-                                            }
-                                            await new Promise(r => setTimeout(r, 500));
+                                        catch (err) {
+                                            log?.error(`[qqbot:${account.accountId}] Failed to send startup greetings: ${err}`);
                                         }
-                                        log?.info(`[qqbot:${account.accountId}] Startup greetings sent (${users.length} c2c, ${sentGroups.size} groups)`);
-                                    }
-                                    catch (err) {
-                                        log?.error(`[qqbot:${account.accountId}] Failed to send startup greetings: ${err}`);
-                                    }
-                                })();
+                                    })();
+                                } // end isFirstReady
                             }
                             else if (t === "RESUMED") {
                                 log?.info(`[qqbot:${account.accountId}] Session resumed`);

package/dist/src/slash-commands.js

@@ -16,6 +16,7 @@ import { promisify } from "node:util";
 import path from "node:path";
 import fs from "node:fs";
 import { fileURLToPath } from "node:url";
+import { getUpdateInfo, formatUpdateNotice } from "./update-checker.js";
 const require = createRequire(import.meta.url);
 const execFileAsync = promisify(execFile);
 // 读取 package.json 中的版本号
@@ -53,7 +54,13 @@ registerCommand({
     name: "version",
     description: "插件版本号",
     handler: () => {
-        return `QQBot Plugin v${PLUGIN_VERSION}`;
+        const lines = [`QQBot Plugin v${PLUGIN_VERSION}`];
+        const info = getUpdateInfo();
+        const notice = formatUpdateNotice(info);
+        if (notice) {
+            lines.push("", notice);
+        }
+        return lines.join("\n");
     },
 });
 /**
@@ -69,6 +76,12 @@ registerCommand({
             lines.push(`- \`/${name}\` — ${cmd.description}`);
         }
         lines.push(``, `**升级指引**: ${url}`);
+        // 如有更新可用，追加提示
+        const info = getUpdateInfo();
+        const notice = formatUpdateNotice(info);
+        if (notice) {
+            lines.push("", notice);
+        }
         return lines.join("\n");
     },
 });

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/update-checker.d.ts

@@ -0,0 +1,52 @@
+/**
+ * 自动更新检查模块（方案 A + B）
+ *
+ * 灵感来源: update-notifier（npm 生态标准方案）
+ *
+ * 工作原理：
+ * 1. gateway 启动账户时调用 triggerUpdateCheck()
+ * 2. 通过 detached 子进程后台查询 npm registry，零阻塞主进程
+ * 3. 查询结果写入本地 JSON 缓存文件（~/.openclaw/qqbot/update-check.json）
+ * 4. 下次调用 getUpdateInfo() 时读取缓存，对比版本号
+ * 5. /version 指令展示更新提示，gateway 启动日志也输出提醒
+ *
+ * 检查间隔：默认 24 小时（可调），避免频繁网络请求
+ */
+/** 对外暴露的更新信息 */
+export interface UpdateInfo {
+    /** 当前版本 */
+    currentVersion: string;
+    /** 最新 stable 版本 */
+    latestVersion: string | null;
+    /** 最新 alpha 版本（如有） */
+    latestAlphaVersion: string | null;
+    /** 是否有 stable 更新可用 */
+    hasUpdate: boolean;
+    /** 是否有 alpha 更新可用（仅当前是 alpha 时才比较） */
+    hasAlphaUpdate: boolean;
+    /** 最后检查时间 */
+    lastCheck: number;
+}
+/**
+ * 获取更新信息（从缓存读取，不触发网络请求）
+ * 适合在 /version 指令、日志打印等场景调用
+ */
+export declare function getUpdateInfo(): UpdateInfo;
+/**
+ * 格式化更新提示文本（用于 /version 指令和日志输出）
+ */
+export declare function formatUpdateNotice(info: UpdateInfo): string | null;
+/**
+ * 触发后台版本检查（非阻塞）
+ *
+ * - 如果距上次检查不到 CHECK_INTERVAL_MS，跳过
+ * - 通过 spawn detached 子进程执行，主进程不等待
+ * - 子进程查询 npm registry 后将结果写入缓存文件
+ */
+export declare function triggerUpdateCheck(log?: {
+    info: (msg: string) => void;
+}): void;
+/**
+ * 获取当前插件版本
+ */
+export declare function getCurrentVersion(): string;