@tencent-connect/openclaw-qqbot 1.6.4 → 1.6.5-alpha.0

package/README.md

@@ -183,18 +183,11 @@ Shows framework version, plugin version, and a direct link to the official repos
 >
 > **QQBot**: 📌 Current: v1.6.3 / ✅ New version v1.6.4 available / Click button below to confirm
 
-Send in private chat to upgrade the plugin without server login. Supported usage:
-
-| 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 -->
+> ⚠️ Hot upgrade is currently not supported on Windows. Sending `/bot-upgrade` on Windows will return a manual upgrade guide instead.
+
+<img width="360" src="docs/images/hot-update.jpg" alt="Hot Upgrade Demo" />
 
 #### `/bot-logs` — Log Export
 

package/README.zh.md

@@ -178,18 +178,11 @@ AI 可直接发送视频，支持本地文件和公网 URL。
 >
 > **QQBot**：📌当前版本 v1.6.3 / ✅发现新版本 v1.6.4 / 点击下方按钮确认升级
 
-在私聊中发送即可完成版本升级，全程无需登录服务器。支持的用法：
-
-| 命令 | 说明 |
-|------|------|
-| `/bot-upgrade` | 检查是否有新版本，展示确认按钮 |
-| `/bot-upgrade --latest` | 确认升级到最新版本 |
-| `/bot-upgrade --version 1.6.4` | 升级到指定版本 |
-| `/bot-upgrade --force` | 强制重新安装当前版本 |
-
 升级流程自动备份凭证，升级前校验版本是否存在于 npm，升级失败自动恢复。
 
-<!-- TODO: 补充 /bot-upgrade 截图 -->
+> ⚠️ 热更新指令暂不支持 Windows 系统，在 Windows 上发送 `/bot-upgrade` 会返回手动升级指引。
+
+<img width="360" src="docs/images/hot-update.jpg" alt="一键热更新演示" />
 
 #### `/bot-logs` — 日志导出
 

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

@@ -13,15 +13,21 @@ export interface AdminResolverContext {
         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;
+/**
+ * 读取 admin openid（按 accountId + appId 区分）
+ * 兼容策略：新路径优先 → fallback 旧路径 → 自动迁移
+ */
+export declare function loadAdminOpenId(accountId: string, appId: string): string | undefined;
+export declare function saveAdminOpenId(accountId: string, appId: string, openid: string): void;
+export declare function loadUpgradeGreetingTargetOpenId(accountId: string, appId: string, log?: {
+    info: (msg: string) => void;
+}): string | undefined;
 export declare function clearUpgradeGreetingTargetOpenId(accountId: string, appId: string): void;
 /**
  * 解析管理员 openid：
- * 1. 优先读持久化文件（稳定）
+ * 1. 优先读持久化文件（按 accountId + appId 区分）
  * 2. fallback 取第一个私聊用户，并写入文件锁定
  */
-export declare function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "log">): string | undefined;
-/** 异步发送启动问候语（仅发给管理员） */
+export declare function resolveAdminOpenId(ctx: Pick<AdminResolverContext, "accountId" | "appId" | "log">): string | undefined;
+/** 异步发送启动问候语（优先发给升级触发者，fallback 发给管理员） */
 export declare function sendStartupGreetings(ctx: AdminResolverContext, trigger: "READY" | "RESUMED"): void;

package/dist/src/admin-resolver.js

@@ -11,49 +11,86 @@ import { listKnownUsers } from "./known-users.js";
 import { getAccessToken, sendProactiveC2CMessage } from "./api.js";
 import { getStartupGreetingPlan, markStartupGreetingSent, markStartupGreetingFailed } from "./startup-greeting.js";
 // ---- 文件路径 ----
-function getAdminMarkerFile(accountId) {
+function safeName(id) {
+    return id.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+/** 新版 admin 文件路径（按 accountId + appId 区分） */
+function getAdminMarkerFile(accountId, appId) {
+    return path.join(getQQBotDataDir("data"), `admin-${safeName(accountId)}-${safeName(appId)}.json`);
+}
+/** 旧版 admin 文件路径（仅按 accountId 区分，用于迁移兼容） */
+function getLegacyAdminMarkerFile(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`);
+    return path.join(getQQBotDataDir("data"), `upgrade-greeting-target-${safeName(accountId)}-${safeName(appId)}.json`);
 }
 // ---- 管理员 openid 持久化 ----
-export function loadAdminOpenId(accountId) {
+/**
+ * 读取 admin openid（按 accountId + appId 区分）
+ * 兼容策略：新路径优先 → fallback 旧路径 → 自动迁移
+ */
+export function loadAdminOpenId(accountId, appId) {
     try {
-        const file = getAdminMarkerFile(accountId);
-        if (fs.existsSync(file)) {
-            const data = JSON.parse(fs.readFileSync(file, "utf8"));
+        // 1. 先尝试新版路径
+        const newFile = getAdminMarkerFile(accountId, appId);
+        if (fs.existsSync(newFile)) {
+            const data = JSON.parse(fs.readFileSync(newFile, "utf8"));
             if (data.openid)
                 return data.openid;
         }
+        // 2. fallback 旧版路径（仅按 accountId）
+        const legacyFile = getLegacyAdminMarkerFile(accountId);
+        if (fs.existsSync(legacyFile)) {
+            const data = JSON.parse(fs.readFileSync(legacyFile, "utf8"));
+            if (data.openid) {
+                // 自动迁移：写到新路径，删除旧文件
+                saveAdminOpenId(accountId, appId, data.openid);
+                try {
+                    fs.unlinkSync(legacyFile);
+                }
+                catch { /* ignore */ }
+                return data.openid;
+            }
+        }
     }
     catch { /* 文件损坏视为无 */ }
     return undefined;
 }
-export function saveAdminOpenId(accountId, openid) {
+export function saveAdminOpenId(accountId, appId, openid) {
     try {
-        fs.writeFileSync(getAdminMarkerFile(accountId), JSON.stringify({ openid, savedAt: new Date().toISOString() }));
+        fs.writeFileSync(getAdminMarkerFile(accountId, appId), JSON.stringify({ accountId, appId, openid, savedAt: new Date().toISOString() }));
     }
     catch { /* ignore */ }
 }
 // ---- 升级问候目标 ----
-export function loadUpgradeGreetingTargetOpenId(accountId, appId) {
+export function loadUpgradeGreetingTargetOpenId(accountId, appId, log) {
     try {
         const file = getUpgradeGreetingTargetFile(accountId, appId);
         if (fs.existsSync(file)) {
             const data = JSON.parse(fs.readFileSync(file, "utf8"));
-            if (!data.openid)
+            if (!data.openid) {
+                log?.info(`[qqbot:${accountId}] upgrade-greeting-target file found but openid is empty`);
                 return undefined;
-            if (data.appId && data.appId !== appId)
+            }
+            if (data.appId && data.appId !== appId) {
+                log?.info(`[qqbot:${accountId}] upgrade-greeting-target appId mismatch: file=${data.appId}, current=${appId}`);
                 return undefined;
-            if (data.accountId && data.accountId !== accountId)
+            }
+            if (data.accountId && data.accountId !== accountId) {
+                log?.info(`[qqbot:${accountId}] upgrade-greeting-target accountId mismatch: file=${data.accountId}, current=${accountId}`);
                 return undefined;
+            }
+            log?.info(`[qqbot:${accountId}] upgrade-greeting-target loaded: openid=${data.openid}`);
             return data.openid;
         }
+        else {
+            log?.info(`[qqbot:${accountId}] upgrade-greeting-target file not found: ${file}`);
+        }
+    }
+    catch (err) {
+        log?.info(`[qqbot:${accountId}] upgrade-greeting-target file read error: ${err}`);
     }
-    catch { /* 文件损坏视为无 */ }
     return undefined;
 }
 export function clearUpgradeGreetingTargetOpenId(accountId, appId) {
@@ -68,33 +105,33 @@ export function clearUpgradeGreetingTargetOpenId(accountId, appId) {
 // ---- 解析管理员 ----
 /**
  * 解析管理员 openid：
- * 1. 优先读持久化文件（稳定）
+ * 1. 优先读持久化文件（按 accountId + appId 区分）
  * 2. fallback 取第一个私聊用户，并写入文件锁定
  */
 export function resolveAdminOpenId(ctx) {
-    const saved = loadAdminOpenId(ctx.accountId);
+    const saved = loadAdminOpenId(ctx.accountId, ctx.appId);
     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);
+        saveAdminOpenId(ctx.accountId, ctx.appId, first);
         ctx.log?.info(`[qqbot:${ctx.accountId}] Auto-detected admin openid: ${first} (persisted)`);
     }
     return first;
 }
 // ---- 启动问候语 ----
-/** 异步发送启动问候语（仅发给管理员） */
+/** 异步发送启动问候语（优先发给升级触发者，fallback 发给管理员） */
 export function sendStartupGreetings(ctx, trigger) {
     (async () => {
-        const plan = getStartupGreetingPlan();
+        const plan = getStartupGreetingPlan(ctx.accountId, ctx.appId);
         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 upgradeTargetOpenId = loadUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId, ctx.log);
         const targetOpenId = upgradeTargetOpenId || resolveAdminOpenId(ctx);
         if (!targetOpenId) {
-            markStartupGreetingFailed(plan.version, "no-admin");
+            markStartupGreetingFailed(ctx.accountId, ctx.appId, plan.version, "no-admin");
             ctx.log?.info(`[qqbot:${ctx.accountId}] Skipping startup greeting (no admin or known user)`);
             return;
         }
@@ -107,7 +144,7 @@ export function sendStartupGreetings(ctx, trigger) {
                 sendProactiveC2CMessage(token, targetOpenId, plan.greeting),
                 new Promise((_, reject) => setTimeout(() => reject(new Error("Startup greeting send timeout (10s)")), GREETING_TIMEOUT_MS)),
             ]);
-            markStartupGreetingSent(plan.version);
+            markStartupGreetingSent(ctx.accountId, ctx.appId, plan.version);
             if (upgradeTargetOpenId) {
                 clearUpgradeGreetingTargetOpenId(ctx.accountId, ctx.appId);
             }
@@ -115,7 +152,7 @@ export function sendStartupGreetings(ctx, trigger) {
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);
-            markStartupGreetingFailed(plan.version, message);
+            markStartupGreetingFailed(ctx.accountId, ctx.appId, plan.version, message);
             ctx.log?.error(`[qqbot:${ctx.accountId}] Failed to send startup greeting: ${message}`);
         }
     })();

package/dist/src/deliver-debounce.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 出站消息合并回复（Deliver Debounce）模块
+ *
+ * 解决的问题：
+ * 当 openclaw 框架层的 embedded agent 超时或快速连续产生多次 deliver 时，
+ * 用户会在短时间内收到大量碎片消息（消息轰炸）。
+ *
+ * 解决方案：
+ * 在 deliver 回调和实际发送之间加入 debounce 层。
+ * 短时间内（windowMs）连续到达的多条纯文本 deliver 会被合并为一条消息发送。
+ * 含媒体的 deliver 会立即 flush 已缓冲的文本并正常处理媒体。
+ */
+import type { DeliverDebounceConfig } from "./types.js";
+export interface DeliverPayload {
+    text?: string;
+    mediaUrls?: string[];
+    mediaUrl?: string;
+}
+export interface DeliverInfo {
+    kind: string;
+}
+/** 实际执行发送的回调 */
+export type DeliverExecutor = (payload: DeliverPayload, info: DeliverInfo) => Promise<void>;
+export declare class DeliverDebouncer {
+    private readonly windowMs;
+    private readonly maxWaitMs;
+    private readonly separator;
+    private readonly executor;
+    private readonly log?;
+    private readonly prefix;
+    /** 缓冲中的文本片段 */
+    private bufferedTexts;
+    /** 缓冲中最后一次 deliver 的 info（用于 flush 时传递 kind） */
+    private lastInfo;
+    /** 缓冲中最后一次 deliver 的 payload（非文本字段，如 mediaUrls） */
+    private lastPayload;
+    /** debounce 定时器 */
+    private debounceTimer;
+    /** 最大等待定时器（从第一条 deliver 开始计算） */
+    private maxWaitTimer;
+    /** 是否正在 flush */
+    private flushing;
+    /** 已销毁标记 */
+    private disposed;
+    constructor(config: DeliverDebounceConfig | undefined, executor: DeliverExecutor, log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+    }, prefix?: string);
+    /**
+     * 接收一次 deliver 调用。
+     * - 纯文本 deliver → 缓冲并设置 debounce 定时器
+     * - 含媒体 deliver → 先 flush 已缓冲文本，再直接执行当前 deliver
+     */
+    deliver(payload: DeliverPayload, info: DeliverInfo): Promise<void>;
+    /**
+     * 将缓冲中的文本合并为一条消息发送
+     */
+    flush(): Promise<void>;
+    /**
+     * 销毁：flush 剩余缓冲并清除定时器
+     */
+    dispose(): Promise<void>;
+    /** 当前是否有缓冲中的文本 */
+    get hasPending(): boolean;
+    /** 缓冲中的文本数量 */
+    get pendingCount(): number;
+}
+/**
+ * 根据配置创建 debouncer 或返回 null（禁用时）
+ */
+export declare function createDeliverDebouncer(config: DeliverDebounceConfig | undefined, executor: DeliverExecutor, log?: {
+    info: (msg: string) => void;
+    error: (msg: string) => void;
+}, prefix?: string): DeliverDebouncer | null;

package/dist/src/deliver-debounce.js

@@ -0,0 +1,174 @@
+/**
+ * 出站消息合并回复（Deliver Debounce）模块
+ *
+ * 解决的问题：
+ * 当 openclaw 框架层的 embedded agent 超时或快速连续产生多次 deliver 时，
+ * 用户会在短时间内收到大量碎片消息（消息轰炸）。
+ *
+ * 解决方案：
+ * 在 deliver 回调和实际发送之间加入 debounce 层。
+ * 短时间内（windowMs）连续到达的多条纯文本 deliver 会被合并为一条消息发送。
+ * 含媒体的 deliver 会立即 flush 已缓冲的文本并正常处理媒体。
+ */
+// ============ 默认值 ============
+const DEFAULT_WINDOW_MS = 1500;
+const DEFAULT_MAX_WAIT_MS = 8000;
+const DEFAULT_SEPARATOR = "\n\n---\n\n";
+// ============ DeliverDebouncer 类 ============
+export class DeliverDebouncer {
+    windowMs;
+    maxWaitMs;
+    separator;
+    executor;
+    log;
+    prefix;
+    /** 缓冲中的文本片段 */
+    bufferedTexts = [];
+    /** 缓冲中最后一次 deliver 的 info（用于 flush 时传递 kind） */
+    lastInfo = null;
+    /** 缓冲中最后一次 deliver 的 payload（非文本字段，如 mediaUrls） */
+    lastPayload = null;
+    /** debounce 定时器 */
+    debounceTimer = null;
+    /** 最大等待定时器（从第一条 deliver 开始计算） */
+    maxWaitTimer = null;
+    /** 是否正在 flush */
+    flushing = false;
+    /** 已销毁标记 */
+    disposed = false;
+    constructor(config, executor, log, prefix = "[debounce]") {
+        this.windowMs = config?.windowMs ?? DEFAULT_WINDOW_MS;
+        this.maxWaitMs = config?.maxWaitMs ?? DEFAULT_MAX_WAIT_MS;
+        this.separator = config?.separator ?? DEFAULT_SEPARATOR;
+        this.executor = executor;
+        this.log = log;
+        this.prefix = prefix;
+    }
+    /**
+     * 接收一次 deliver 调用。
+     * - 纯文本 deliver → 缓冲并设置 debounce 定时器
+     * - 含媒体 deliver → 先 flush 已缓冲文本，再直接执行当前 deliver
+     */
+    async deliver(payload, info) {
+        if (this.disposed)
+            return;
+        const hasMedia = Boolean((payload.mediaUrls && payload.mediaUrls.length > 0) || payload.mediaUrl);
+        const text = (payload.text ?? "").trim();
+        // 含媒体的 deliver：立即 flush 缓冲 + 直接执行
+        if (hasMedia) {
+            this.log?.info(`${this.prefix} Media deliver detected, flushing ${this.bufferedTexts.length} buffered text(s) first`);
+            await this.flush();
+            await this.executor(payload, info);
+            return;
+        }
+        // 空文本 deliver：直接透传（不缓冲）
+        if (!text) {
+            await this.executor(payload, info);
+            return;
+        }
+        // 纯文本 deliver：缓冲
+        this.bufferedTexts.push(text);
+        this.lastInfo = info;
+        this.lastPayload = payload;
+        this.log?.info(`${this.prefix} Buffered text #${this.bufferedTexts.length} (${text.length} chars), window=${this.windowMs}ms`);
+        // 重置 debounce 定时器
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+        }
+        this.debounceTimer = setTimeout(() => {
+            this.flush().catch((err) => {
+                this.log?.error(`${this.prefix} Flush error (debounce timer): ${err}`);
+            });
+        }, this.windowMs);
+        // 首次缓冲时启动最大等待定时器
+        if (this.bufferedTexts.length === 1) {
+            if (this.maxWaitTimer) {
+                clearTimeout(this.maxWaitTimer);
+            }
+            this.maxWaitTimer = setTimeout(() => {
+                this.log?.info(`${this.prefix} Max wait (${this.maxWaitMs}ms) reached, force flushing`);
+                this.flush().catch((err) => {
+                    this.log?.error(`${this.prefix} Flush error (max wait timer): ${err}`);
+                });
+            }, this.maxWaitMs);
+        }
+    }
+    /**
+     * 将缓冲中的文本合并为一条消息发送
+     */
+    async flush() {
+        if (this.flushing || this.bufferedTexts.length === 0)
+            return;
+        this.flushing = true;
+        // 清除定时器
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.maxWaitTimer) {
+            clearTimeout(this.maxWaitTimer);
+            this.maxWaitTimer = null;
+        }
+        // 取出缓冲
+        const texts = this.bufferedTexts;
+        const info = this.lastInfo;
+        const lastPayload = this.lastPayload;
+        this.bufferedTexts = [];
+        this.lastInfo = null;
+        this.lastPayload = null;
+        try {
+            if (texts.length === 1) {
+                // 只有一条，直接透传原始 payload
+                this.log?.info(`${this.prefix} Flushing single buffered text (${texts[0].length} chars)`);
+                await this.executor({ ...lastPayload, text: texts[0] }, info);
+            }
+            else {
+                // 多条合并
+                const merged = texts.join(this.separator);
+                this.log?.info(`${this.prefix} Merged ${texts.length} buffered texts into one (${merged.length} chars)`);
+                await this.executor({ ...lastPayload, text: merged }, info);
+            }
+        }
+        finally {
+            this.flushing = false;
+        }
+    }
+    /**
+     * 销毁：flush 剩余缓冲并清除定时器
+     */
+    async dispose() {
+        this.disposed = true;
+        if (this.debounceTimer) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = null;
+        }
+        if (this.maxWaitTimer) {
+            clearTimeout(this.maxWaitTimer);
+            this.maxWaitTimer = null;
+        }
+        // flush 剩余
+        if (this.bufferedTexts.length > 0) {
+            this.flushing = false; // 确保 flush 能执行
+            await this.flush();
+        }
+    }
+    /** 当前是否有缓冲中的文本 */
+    get hasPending() {
+        return this.bufferedTexts.length > 0;
+    }
+    /** 缓冲中的文本数量 */
+    get pendingCount() {
+        return this.bufferedTexts.length;
+    }
+}
+// ============ 工厂函数 ============
+/**
+ * 根据配置创建 debouncer 或返回 null（禁用时）
+ */
+export function createDeliverDebouncer(config, executor, log, prefix) {
+    // 未配置时默认启用
+    if (config?.enabled === false) {
+        return null;
+    }
+    return new DeliverDebouncer(config, executor, log, prefix);
+}