@tencent-connect/openclaw-qqbot 1.6.4-alpha.2 → 1.6.4-alpha.20

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.2`
+### 🚀 Current Version: `v1.6.4`
 
 [![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/)
@@ -36,13 +36,13 @@ Scan to join the QQ group chat
 
 | Feature | Description |
 |---------|-------------|
-| 🔒 **Multi-Scene** | C2C private chat, group @messages, channel messages, channel DMs |
+| 🔒 **Multi-Scene** | C2C private chat, group @messages |
 | 🖼️ **Rich Media** | Send & receive images, voice, video, and files |
 | 🎙️ **Voice (STT/TTS)** | Speech-to-text transcription & text-to-speech replies |
+| 🔥 **One-Click Hot Upgrade** | Send `/bot-upgrade` in private chat to upgrade — no server login needed |
 | ⏰ **Scheduled Push** | Proactive message delivery via scheduled tasks |
 | 🔗 **URL Support** | Direct URL sending in private chat (no restrictions) |
 | ⌨️ **Typing Indicator** | "Bot is typing..." status shown in real-time |
-| 🔄 **Hot Reload** | Install via npm with seamless hot updates |
 | 📝 **Markdown** | Full Markdown formatting support |
 | 🛠️ **Commands** | Native OpenClaw command integration |
 | 💬 **Quoted Context** | Resolve QQ `REFIDX_*` quoted messages and inject quote body into AI context |
@@ -177,15 +177,24 @@ Shows framework version, plugin version, and a direct link to the official repos
 
 <img width="360" src="docs/images/slash-help.jpg" alt="Help Demo" />
 
-#### `/bot-upgrade` — Upgrade Guide
+#### `/bot-upgrade` — One-Click Hot Upgrade
 
 > **You**: `/bot-upgrade`
 >
-> **QQBot**: 📌 Current version / ✅ Up to date / ⬆️ Upgrade guide / 🌟 GitHub repo
+> **QQBot**: 📌 Current: v1.6.4-alpha.12 / ✅ New version v1.6.4 available / Click button below to confirm
 
-Shows current version, update status, upgrade guide link, and official repository.
+Send in private chat to upgrade the plugin without server login. Supported usage:
 
-<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade Demo" /> 
+| Command | Description |
+|---------|-------------|
+| `/bot-upgrade` | Check for updates, show confirmation button |
+| `/bot-upgrade --latest` | Confirm upgrade to the latest version |
+| `/bot-upgrade --version 1.6.4` | Upgrade to a specific version |
+| `/bot-upgrade --force` | Force reinstall current version |
+
+Credentials are automatically backed up before upgrade. Version existence is verified against npm before proceeding. Auto-recovery on failure.
+
+<!-- TODO: add /bot-upgrade screenshot -->
 
 #### `/bot-logs` — Log Export
 
@@ -197,6 +206,14 @@ Exports the last ~2000 lines of gateway logs as a file for quick troubleshooting
 
 <img width="360" src="docs/images/slash-logs.jpg" alt="Logs Demo" />
 
+#### Usage Help
+
+All commands support a `?` suffix to show usage:
+
+> **You**: `/bot-upgrade ?`
+>
+> **QQBot**: 📖 /bot-upgrade usage: …
+
 ---
 
 ## 🚀 Getting Started

package/README.zh.md

@@ -9,7 +9,7 @@
 
 **让你的 AI 助手接入 QQ — 私聊、群聊、富媒体，一个插件全搞定。**
 
-### 🚀 当前版本： `v1.6.2`
+### 🚀 当前版本： `v1.6.4`
 
 [![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/)
@@ -31,13 +31,13 @@
 
 | 功能 | 说明 |
 |------|------|
-| 🔒 **多场景支持** | C2C 私聊、群聊 @消息、频道消息、频道私信 |
+| 🔒 **多场景支持** | C2C 私聊、群聊 @消息 |
 | 🖼️ **富媒体消息** | 支持图片、语音、视频、文件的收发 |
 | 🎙️ **语音能力 (STT/TTS)** | 语音转文字自动转录 & 文字转语音回复 |
+| 🔥 **一键热更新** | 私聊发送 `/bot-upgrade` 即可完成版本升级，无需登录服务器 |
 | ⏰ **定时推送** | 支持定时任务触发后主动推送消息 |
 | 🔗 **URL 无限制** | 私聊可直接发送 URL |
 | ⌨️ **输入状态** | 实时显示"Bot 正在输入中…"状态 |
-| 🔄 **热更新** | 支持 npm 方式安装和无缝热更新 |
 | 📝 **Markdown** | 完整支持 Markdown 格式消息 |
 | 🛠️ **原生命令** | 支持 OpenClaw 原生命令 |
 | 💬 **引用上下文** | 解析 QQ `REFIDX_*` 引用消息，并将引用内容注入 AI 上下文 |
@@ -172,15 +172,24 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 
 <img width="360" src="docs/images/slash-help.jpg" alt="Help 演示" />
 
-#### `/bot-upgrade` — 升级指引
+#### `/bot-upgrade` — 一键热更新
 
 > **你**：`/bot-upgrade`
 >
-> **QQBot**：📌当前版本 / ✅当前已是最新版本 / ⬆️升级指引 / 🌟官方 GitHub 仓库
+> **QQBot**：📌当前版本 v1.6.4-alpha.12 / ✅发现新版本 v1.6.4 / 点击下方按钮确认升级
 
-显示当前版本、更新状态、升级文档链接及官方仓库入口。
+在私聊中发送即可完成版本升级，全程无需登录服务器。支持的用法：
 
-<img width="360" src="docs/images/slash-upgrade.jpg" alt="Upgrade 演示" /> 
+| 命令 | 说明 |
+|------|------|
+| `/bot-upgrade` | 检查是否有新版本，展示确认按钮 |
+| `/bot-upgrade --latest` | 确认升级到最新版本 |
+| `/bot-upgrade --version 1.6.4` | 升级到指定版本 |
+| `/bot-upgrade --force` | 强制重新安装当前版本 |
+
+升级流程自动备份凭证，升级前校验版本是否存在于 npm，升级失败自动恢复。
+
+<!-- TODO: 补充 /bot-upgrade 截图 -->
 
 #### `/bot-logs` — 日志导出
 
@@ -192,6 +201,14 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 
 <img width="360" src="docs/images/slash-logs.jpg" alt="Logs 演示" />
 
+#### 用法查询
+
+所有指令都支持 `?` 后缀查看用法说明：
+
+> **你**：`/bot-upgrade ?`
+>
+> **QQBot**：📖 /bot-upgrade 用法：…
+
 ---
 
 ## 🚀 快速开始

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-channel", "skills/qqbot-cron", "skills/qqbot-media"],
+  "skills": ["skills/qqbot-channel", "skills/qqbot-remind", "skills/qqbot-media"],
   "capabilities": {
     "proactiveMessaging": true,
     "cronJobs": true

package/dist/index.js

@@ -2,6 +2,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";
+import { registerRemindTool } from "./src/tools/remind.js";
 const plugin = {
     id: "openclaw-qqbot",
     name: "QQ Bot",
@@ -11,6 +12,7 @@ const plugin = {
         setQQBotRuntime(api.runtime);
         api.registerChannel({ plugin: qqbotPlugin });
         registerChannelTool(api);
+        registerRemindTool(api);
     },
 };
 export default plugin;

package/dist/src/admin-resolver.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 管理员解析器模块
+ * - 管理员 openid 持久化读写
+ * - 升级问候目标读写
+ * - 启动问候语发送
+ */
+export interface AdminResolverContext {
+    accountId: string;
+    appId: string;
+    clientSecret: string;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+    };
+}
+export declare function loadAdminOpenId(accountId: string): string | undefined;
+export declare function saveAdminOpenId(accountId: string, openid: string): void;
+export declare function loadUpgradeGreetingTargetOpenId(accountId: string, appId: string): string | undefined;
+export declare function clearUpgradeGreetingTargetOpenId(accountId: string, appId: string): void;
+/**
+ * 解析管理员 openid：
+ * 1. 优先读持久化文件（稳定）
+ * 2. fallback 取第一个私聊用户，并写入文件锁定
+ */
+export declare function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "log">): string | undefined;
+/** 异步发送启动问候语（仅发给管理员） */
+export declare function sendStartupGreetings(ctx: AdminResolverContext, trigger: "READY" | "RESUMED"): void;

package/dist/src/admin-resolver.js

@@ -0,0 +1,122 @@
+/**
+ * 管理员解析器模块
+ * - 管理员 openid 持久化读写
+ * - 升级问候目标读写
+ * - 启动问候语发送
+ */
+import path from "node:path";
+import * as fs from "node:fs";
+import { getQQBotDataDir } from "./utils/platform.js";
+import { listKnownUsers } from "./known-users.js";
+import { getAccessToken, sendProactiveC2CMessage } from "./api.js";
+import { getStartupGreetingPlan, markStartupGreetingSent, markStartupGreetingFailed } from "./startup-greeting.js";
+// ---- 文件路径 ----
+function getAdminMarkerFile(accountId) {
+    return path.join(getQQBotDataDir("data"), `admin-${accountId}.json`);
+}
+function getUpgradeGreetingTargetFile(accountId, appId) {
+    const safeAccountId = accountId.replace(/[^a-zA-Z0-9._-]/g, "_");
+    const safeAppId = appId.replace(/[^a-zA-Z0-9._-]/g, "_");
+    return path.join(getQQBotDataDir("data"), `upgrade-greeting-target-${safeAccountId}-${safeAppId}.json`);
+}
+// ---- 管理员 openid 持久化 ----
+export function loadAdminOpenId(accountId) {
+    try {
+        const file = getAdminMarkerFile(accountId);
+        if (fs.existsSync(file)) {
+            const data = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (data.openid)
+                return data.openid;
+        }
+    }
+    catch { /* 文件损坏视为无 */ }
+    return undefined;
+}
+export function saveAdminOpenId(accountId, openid) {
+    try {
+        fs.writeFileSync(getAdminMarkerFile(accountId), JSON.stringify({ openid, savedAt: new Date().toISOString() }));
+    }
+    catch { /* ignore */ }
+}
+// ---- 升级问候目标 ----
+export function loadUpgradeGreetingTargetOpenId(accountId, appId) {
+    try {
+        const file = getUpgradeGreetingTargetFile(accountId, appId);
+        if (fs.existsSync(file)) {
+            const data = JSON.parse(fs.readFileSync(file, "utf8"));
+            if (!data.openid)
+                return undefined;
+            if (data.appId && data.appId !== appId)
+                return undefined;
+            if (data.accountId && data.accountId !== accountId)
+                return undefined;
+            return data.openid;
+        }
+    }
+    catch { /* 文件损坏视为无 */ }
+    return undefined;
+}
+export function clearUpgradeGreetingTargetOpenId(accountId, appId) {
+    try {
+        const file = getUpgradeGreetingTargetFile(accountId, appId);
+        if (fs.existsSync(file)) {
+            fs.unlinkSync(file);
+        }
+    }
+    catch { /* ignore */ }
+}
+// ---- 解析管理员 ----
+/**
+ * 解析管理员 openid：
+ * 1. 优先读持久化文件（稳定）
+ * 2. fallback 取第一个私聊用户，并写入文件锁定
+ */
+export function resolveAdminOpenId(ctx) {
+    const saved = loadAdminOpenId(ctx.accountId);
+    if (saved)
+        return saved;
+    const first = listKnownUsers({ accountId: ctx.accountId, type: "c2c", sortBy: "firstSeenAt", sortOrder: "asc", limit: 1 })[0]?.openid;
+    if (first) {
+        saveAdminOpenId(ctx.accountId, first);
+        ctx.log?.info(`[qqbot:${ctx.accountId}] Auto-detected admin openid: ${first} (persisted)`);
+    }
+    return first;
+}
+// ---- 启动问候语 ----
+/** 异步发送启动问候语（仅发给管理员） */
+export function sendStartupGreetings(ctx, trigger) {
+    (async () => {
+        const plan = getStartupGreetingPlan();
+        if (!plan.shouldSend || !plan.greeting) {
+            ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (${plan.reason ?? "debounced"}, trigger=${trigger})`);
+            return;
+        }
+        const upgradeTargetOpenId = loadUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
+        const targetOpenId = upgradeTargetOpenId || resolveAdminOpenId(ctx);
+        if (!targetOpenId) {
+            markStartupGreetingFailed(plan.version, "no-admin");
+            ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (no admin or known user)`);
+            return;
+        }
+        try {
+            const receiverType = upgradeTargetOpenId ? "upgrade-requester" : "admin";
+            ctx.log?.info(`[qqbot:${ctx.accountId}] Sending startup greeting to ${receiverType} (trigger=${trigger}): "${plan.greeting}"`);
+            const token = await getAccessToken(ctx.appId, ctx.clientSecret);
+            const GREETING_TIMEOUT_MS = 10_000;
+            await Promise.race([
+                sendProactiveC2CMessage(token, targetOpenId, plan.greeting),
+                new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
+            ]);
+            markStartupGreetingSent(plan.version);
+            if (upgradeTargetOpenId) {
+                clearUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
+            }
+            ctx.log?.info(`[qqbot:${ctx.accountId}] Sent startup greeting to ${receiverType}: ${targetOpenId}`);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            markStartupGreetingFailed(plan.version, message);
+            ctx.log?.error(`[qqbot:${ctx.accountId}] Failed to send startup greeting: ${message}`);
+        }
+    })();
+}

package/dist/src/channel.js

@@ -4,6 +4,8 @@ import { sendText, sendMedia } from "./outbound.js";
 import { startGateway } from "./gateway.js";
 import { qqbotOnboardingAdapter } from "./onboarding.js";
 import { getQQBotRuntime } from "./runtime.js";
+import { saveCredentialBackup, loadCredentialBackup } from "./credential-backup.js";
+import { initApiConfig } from "./api.js";
 /** QQ Bot 单条消息文本长度上限 */
 export const TEXT_CHUNK_LIMIT = 5000;
 /**
@@ -58,7 +60,13 @@ export const qqbotPlugin = {
             accountId,
             clearBaseFields: ["appId", "clientSecret", "clientSecretFile", "name"],
         }),
-        isConfigured: (account) => Boolean(account?.appId && account?.clientSecret),
+        isConfigured: (account) => {
+            if (account?.appId && account?.clientSecret)
+                return true;
+            // 配置为空但有凭证备份时仍返回 true，让 startAccount 有机会恢复凭证
+            const backup = loadCredentialBackup(account?.accountId);
+            return backup !== null;
+        },
         describeAccount: (account) => ({
             accountId: account?.accountId ?? DEFAULT_ACCOUNT_ID,
             name: account?.name,
@@ -194,6 +202,7 @@ export const qqbotPlugin = {
             console.log(`[qqbot:channel] sendText called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, text.length=${text?.length ?? 0}`);
             console.log(`[qqbot:channel] sendText text preview: ${text?.slice(0, 100)}${(text?.length ?? 0) > 100 ? "..." : ""}`);
             const account = resolveQQBotAccount(cfg, accountId);
+            initApiConfig({ markdownSupport: account.markdownSupport });
             console.log(`[qqbot:channel] sendText resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
             const result = await sendText({ to, text, accountId, replyToId, account });
             console.log(`[qqbot:channel] sendText result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
@@ -206,6 +215,7 @@ export const qqbotPlugin = {
         sendMedia: async ({ to, text, mediaUrl, accountId, replyToId, cfg }) => {
             console.log(`[qqbot:channel] sendMedia called — accountId=${accountId}, to=${to}, replyToId=${replyToId}, mediaUrl=${mediaUrl?.slice(0, 80)}, text.length=${text?.length ?? 0}`);
             const account = resolveQQBotAccount(cfg, accountId);
+            initApiConfig({ markdownSupport: account.markdownSupport });
             console.log(`[qqbot:channel] sendMedia resolved account: id=${account.accountId}, appId=${account.appId}, enabled=${account.enabled}`);
             const result = await sendMedia({ to, text: text ?? "", mediaUrl: mediaUrl ?? "", accountId, replyToId, account });
             console.log(`[qqbot:channel] sendMedia result: messageId=${result.messageId}, error=${result.error ?? "none"}`);
@@ -218,7 +228,30 @@ export const qqbotPlugin = {
     },
     gateway: {
         startAccount: async (ctx) => {
-            const { account, abortSignal, log, cfg } = ctx;
+            let { account } = ctx;
+            const { abortSignal, log, cfg } = ctx;
+            // 凭证恢复：如果 appId/secret 为空（热更新打断可能导致配置丢失），尝试从暂存文件恢复
+            if (!account.appId || !account.clientSecret) {
+                const backup = loadCredentialBackup(account.accountId);
+                if (backup) {
+                    log?.info(`[qqbot:${account.accountId}] 配置中凭证为空，从暂存文件恢复 (appId=${backup.appId}, savedAt=${backup.savedAt})`);
+                    try {
+                        const runtime = getQQBotRuntime();
+                        const restoredCfg = applyQQBotAccountConfig(cfg, account.accountId, {
+                            appId: backup.appId,
+                            clientSecret: backup.clientSecret,
+                        });
+                        const configApi = runtime.config;
+                        await configApi.writeConfigFile(restoredCfg);
+                        // 重新解析 account 以获取恢复后的值
+                        account = resolveQQBotAccount(restoredCfg, account.accountId);
+                        log?.info(`[qqbot:${account.accountId}] 凭证已恢复`);
+                    }
+                    catch (e) {
+                        log?.error(`[qqbot:${account.accountId}] 凭证恢复失败: ${e}`);
+                    }
+                }
+            }
             log?.info(`[qqbot:${account.accountId}] Starting gateway — appId=${account.appId}, enabled=${account.enabled}, name=${account.name ?? "unnamed"}`);
             console.log(`[qqbot:channel] startAccount: accountId=${account.accountId}, appId=${account.appId}, secretSource=${account.secretSource}`);
             await startGateway({
@@ -228,6 +261,8 @@ export const qqbotPlugin = {
                 log,
                 onReady: () => {
                     log?.info(`[qqbot:${account.accountId}] Gateway ready`);
+                    // 启动成功，保存凭证快照供后续恢复使用
+                    saveCredentialBackup(account.accountId, account.appId, account.clientSecret);
                     ctx.setStatus({
                         ...ctx.getStatus(),
                         running: true,

package/dist/src/credential-backup.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 凭证暂存与恢复
+ *
+ * 解决热更新被打断时 openclaw.json 中 appId/secret 丢失的问题。
+ *
+ * 原理：
+ *   - 每次 gateway 成功启动后，把当前账户的 appId/secret 写入暂存文件
+ *   - 插件启动时如果检测到配置中 appId/secret 为空，尝试从暂存文件恢复
+ *   - 暂存文件存储在 ~/.openclaw/qqbot/data/ 下，不受插件目录替换影响
+ *
+ * 安全保障：
+ *   - 只在 appId/secret **确实为空** 时才尝试恢复（不干扰正常配置变更）
+ *   - 恢复后通过 openclaw 的 config API 写回配置文件，确保框架感知到变更
+ *   - 暂存文件使用原子写入（先写 .tmp 再 rename）防止损坏
+ */
+interface CredentialBackup {
+    accountId: string;
+    appId: string;
+    clientSecret: string;
+    savedAt: string;
+}
+/**
+ * 保存凭证快照到暂存文件（gateway 成功启动后调用）
+ */
+export declare function saveCredentialBackup(accountId: string, appId: string, clientSecret: string): void;
+/**
+ * 从暂存文件读取凭证（仅在配置为空时调用）
+ * 返回 null 表示无可用备份
+ */
+export declare function loadCredentialBackup(accountId?: string): CredentialBackup | null;
+export {};

package/dist/src/credential-backup.js

@@ -0,0 +1,66 @@
+/**
+ * 凭证暂存与恢复
+ *
+ * 解决热更新被打断时 openclaw.json 中 appId/secret 丢失的问题。
+ *
+ * 原理：
+ *   - 每次 gateway 成功启动后，把当前账户的 appId/secret 写入暂存文件
+ *   - 插件启动时如果检测到配置中 appId/secret 为空，尝试从暂存文件恢复
+ *   - 暂存文件存储在 ~/.openclaw/qqbot/data/ 下，不受插件目录替换影响
+ *
+ * 安全保障：
+ *   - 只在 appId/secret **确实为空** 时才尝试恢复（不干扰正常配置变更）
+ *   - 恢复后通过 openclaw 的 config API 写回配置文件，确保框架感知到变更
+ *   - 暂存文件使用原子写入（先写 .tmp 再 rename）防止损坏
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getQQBotDataDir } from "./utils/platform.js";
+const BACKUP_FILENAME = "credential-backup.json";
+function getBackupPath() {
+    return path.join(getQQBotDataDir("data"), BACKUP_FILENAME);
+}
+/**
+ * 保存凭证快照到暂存文件（gateway 成功启动后调用）
+ */
+export function saveCredentialBackup(accountId, appId, clientSecret) {
+    if (!appId || !clientSecret)
+        return; // 不保存空凭证
+    try {
+        const backupPath = getBackupPath();
+        const data = {
+            accountId,
+            appId,
+            clientSecret,
+            savedAt: new Date().toISOString(),
+        };
+        const tmpPath = backupPath + ".tmp";
+        fs.writeFileSync(tmpPath, JSON.stringify(data, null, 2) + "\n", "utf8");
+        fs.renameSync(tmpPath, backupPath);
+    }
+    catch {
+        // 非关键操作，静默忽略
+    }
+}
+/**
+ * 从暂存文件读取凭证（仅在配置为空时调用）
+ * 返回 null 表示无可用备份
+ */
+export function loadCredentialBackup(accountId) {
+    try {
+        const backupPath = getBackupPath();
+        if (!fs.existsSync(backupPath))
+            return null;
+        const raw = fs.readFileSync(backupPath, "utf8");
+        const data = JSON.parse(raw);
+        if (!data.appId || !data.clientSecret)
+            return null;
+        // 如果指定了 accountId，校验是否匹配
+        if (accountId && data.accountId !== accountId)
+            return null;
+        return data;
+    }
+    catch {
+        return null;
+    }
+}