@sliverp/qqbot 1.3.0

package/dist/src/proactive.js

@@ -0,0 +1,398 @@
+/**
+ * QQ Bot 主动发送消息模块
+ *
+ * 该模块提供以下能力：
+ * 1. 记录已知用户（曾与机器人交互过的用户）
+ * 2. 主动发送消息给用户或群组
+ * 3. 查询已知用户列表
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { getAccessToken, sendProactiveC2CMessage, sendProactiveGroupMessage, sendC2CImageMessage, sendGroupImageMessage, } from "./api.js";
+import { resolveQQBotAccount } from "./config.js";
+// ============ 用户存储管理 ============
+/**
+ * 已知用户存储
+ * 使用简单的 JSON 文件存储，保存在 clawd 目录下
+ */
+const STORAGE_DIR = path.join(process.env.HOME || "/home/ubuntu", "clawd", "qqbot-data");
+const KNOWN_USERS_FILE = path.join(STORAGE_DIR, "known-users.json");
+// 内存缓存
+let knownUsersCache = null;
+let cacheLastModified = 0;
+/**
+ * 确保存储目录存在
+ */
+function ensureStorageDir() {
+    if (!fs.existsSync(STORAGE_DIR)) {
+        fs.mkdirSync(STORAGE_DIR, { recursive: true });
+    }
+}
+/**
+ * 生成用户唯一键
+ */
+function getUserKey(type, openid, accountId) {
+    return `${accountId}:${type}:${openid}`;
+}
+/**
+ * 从文件加载已知用户
+ */
+function loadKnownUsers() {
+    if (knownUsersCache !== null) {
+        // 检查文件是否被修改
+        try {
+            const stat = fs.statSync(KNOWN_USERS_FILE);
+            if (stat.mtimeMs <= cacheLastModified) {
+                return knownUsersCache;
+            }
+        }
+        catch {
+            // 文件不存在，使用缓存
+            return knownUsersCache;
+        }
+    }
+    const users = new Map();
+    try {
+        if (fs.existsSync(KNOWN_USERS_FILE)) {
+            const data = fs.readFileSync(KNOWN_USERS_FILE, "utf-8");
+            const parsed = JSON.parse(data);
+            for (const user of parsed) {
+                const key = getUserKey(user.type, user.openid, user.accountId);
+                users.set(key, user);
+            }
+            cacheLastModified = fs.statSync(KNOWN_USERS_FILE).mtimeMs;
+        }
+    }
+    catch (err) {
+        console.error(`[qqbot:proactive] Failed to load known users: ${err}`);
+    }
+    knownUsersCache = users;
+    return users;
+}
+/**
+ * 保存已知用户到文件
+ */
+function saveKnownUsers(users) {
+    try {
+        ensureStorageDir();
+        const data = Array.from(users.values());
+        fs.writeFileSync(KNOWN_USERS_FILE, JSON.stringify(data, null, 2), "utf-8");
+        cacheLastModified = Date.now();
+        knownUsersCache = users;
+    }
+    catch (err) {
+        console.error(`[qqbot:proactive] Failed to save known users: ${err}`);
+    }
+}
+/**
+ * 记录一个已知用户（当收到用户消息时调用）
+ *
+ * @param user - 用户信息
+ */
+export function recordKnownUser(user) {
+    const users = loadKnownUsers();
+    const key = getUserKey(user.type, user.openid, user.accountId);
+    const existing = users.get(key);
+    const now = user.lastInteractionAt || Date.now();
+    users.set(key, {
+        ...user,
+        lastInteractionAt: now,
+        firstInteractionAt: existing?.firstInteractionAt ?? now,
+        // 更新昵称（如果有新的）
+        nickname: user.nickname || existing?.nickname,
+    });
+    saveKnownUsers(users);
+    console.log(`[qqbot:proactive] Recorded user: ${key}`);
+}
+/**
+ * 获取一个已知用户
+ *
+ * @param type - 用户类型
+ * @param openid - 用户 openid
+ * @param accountId - 账户 ID
+ */
+export function getKnownUser(type, openid, accountId) {
+    const users = loadKnownUsers();
+    const key = getUserKey(type, openid, accountId);
+    return users.get(key);
+}
+/**
+ * 列出已知用户
+ *
+ * @param options - 过滤选项
+ */
+export function listKnownUsers(options) {
+    const users = loadKnownUsers();
+    let result = Array.from(users.values());
+    // 过滤类型
+    if (options?.type) {
+        result = result.filter(u => u.type === options.type);
+    }
+    // 过滤账户
+    if (options?.accountId) {
+        result = result.filter(u => u.accountId === options.accountId);
+    }
+    // 排序
+    if (options?.sortByLastInteraction !== false) {
+        result.sort((a, b) => b.lastInteractionAt - a.lastInteractionAt);
+    }
+    // 限制数量
+    if (options?.limit && options.limit > 0) {
+        result = result.slice(0, options.limit);
+    }
+    return result;
+}
+/**
+ * 删除一个已知用户
+ *
+ * @param type - 用户类型
+ * @param openid - 用户 openid
+ * @param accountId - 账户 ID
+ */
+export function removeKnownUser(type, openid, accountId) {
+    const users = loadKnownUsers();
+    const key = getUserKey(type, openid, accountId);
+    const deleted = users.delete(key);
+    if (deleted) {
+        saveKnownUsers(users);
+    }
+    return deleted;
+}
+/**
+ * 清除所有已知用户
+ *
+ * @param accountId - 可选，只清除指定账户的用户
+ */
+export function clearKnownUsers(accountId) {
+    const users = loadKnownUsers();
+    let count = 0;
+    if (accountId) {
+        for (const [key, user] of users) {
+            if (user.accountId === accountId) {
+                users.delete(key);
+                count++;
+            }
+        }
+    }
+    else {
+        count = users.size;
+        users.clear();
+    }
+    if (count > 0) {
+        saveKnownUsers(users);
+    }
+    return count;
+}
+// ============ 主动发送消息 ============
+/**
+ * 主动发送消息（带配置解析）
+ * 注意：与 outbound.ts 中的 sendProactiveMessage 不同，这个函数接受 OpenClawConfig 并自动解析账户
+ *
+ * @param options - 发送选项
+ * @param cfg - OpenClaw 配置
+ * @returns 发送结果
+ *
+ * @example
+ * ```typescript
+ * // 发送私聊消息
+ * const result = await sendProactive({
+ *   to: "E7A8F3B2C1D4E5F6A7B8C9D0E1F2A3B4",  // 用户 openid
+ *   text: "你好！这是一条主动消息",
+ *   type: "c2c",
+ * }, cfg);
+ *
+ * // 发送群聊消息
+ * const result = await sendProactive({
+ *   to: "A1B2C3D4E5F6A7B8",  // 群组 openid
+ *   text: "群公告：今天有活动",
+ *   type: "group",
+ * }, cfg);
+ *
+ * // 发送带图片的消息
+ * const result = await sendProactive({
+ *   to: "E7A8F3B2C1D4E5F6A7B8C9D0E1F2A3B4",
+ *   text: "看看这张图片",
+ *   imageUrl: "https://example.com/image.png",
+ *   type: "c2c",
+ * }, cfg);
+ * ```
+ */
+export async function sendProactive(options, cfg) {
+    const { to, text, type = "c2c", imageUrl, accountId = "default" } = options;
+    // 解析账户配置
+    const account = resolveQQBotAccount(cfg, accountId);
+    if (!account.appId || !account.clientSecret) {
+        return {
+            success: false,
+            error: "QQBot not configured (missing appId or clientSecret)",
+        };
+    }
+    try {
+        const accessToken = await getAccessToken(account.appId, account.clientSecret);
+        // 如果有图片，先发送图片
+        if (imageUrl) {
+            try {
+                if (type === "c2c") {
+                    await sendC2CImageMessage(accessToken, to, imageUrl, undefined, undefined);
+                }
+                else if (type === "group") {
+                    await sendGroupImageMessage(accessToken, to, imageUrl, undefined, undefined);
+                }
+                console.log(`[qqbot:proactive] Sent image to ${type}:${to}`);
+            }
+            catch (err) {
+                console.error(`[qqbot:proactive] Failed to send image: ${err}`);
+                // 图片发送失败不影响文本发送
+            }
+        }
+        // 发送文本消息
+        let result;
+        if (type === "c2c") {
+            result = await sendProactiveC2CMessage(accessToken, to, text);
+        }
+        else if (type === "group") {
+            result = await sendProactiveGroupMessage(accessToken, to, text);
+        }
+        else if (type === "channel") {
+            // 频道消息需要 channel_id，这里暂时不支持主动发送
+            return {
+                success: false,
+                error: "Channel proactive messages are not supported. Please use group or c2c.",
+            };
+        }
+        else {
+            return {
+                success: false,
+                error: `Unknown message type: ${type}`,
+            };
+        }
+        console.log(`[qqbot:proactive] Sent message to ${type}:${to}, id: ${result.id}`);
+        return {
+            success: true,
+            messageId: result.id,
+            timestamp: result.timestamp,
+        };
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        console.error(`[qqbot:proactive] Failed to send message: ${message}`);
+        return {
+            success: false,
+            error: message,
+        };
+    }
+}
+/**
+ * 批量发送主动消息
+ *
+ * @param recipients - 接收者列表（openid 数组）
+ * @param text - 消息内容
+ * @param type - 消息类型
+ * @param cfg - OpenClaw 配置
+ * @param accountId - 账户 ID
+ * @returns 发送结果列表
+ */
+export async function sendBulkProactiveMessage(recipients, text, type, cfg, accountId = "default") {
+    const results = [];
+    for (const to of recipients) {
+        const result = await sendProactive({ to, text, type, accountId }, cfg);
+        results.push({ to, result });
+        // 添加延迟，避免频率限制
+        await new Promise(resolve => setTimeout(resolve, 500));
+    }
+    return results;
+}
+/**
+ * 发送消息给所有已知用户
+ *
+ * @param text - 消息内容
+ * @param cfg - OpenClaw 配置
+ * @param options - 过滤选项
+ * @returns 发送结果统计
+ */
+export async function broadcastMessage(text, cfg, options) {
+    const users = listKnownUsers({
+        type: options?.type,
+        accountId: options?.accountId,
+        limit: options?.limit,
+        sortByLastInteraction: true,
+    });
+    // 过滤掉频道用户（不支持主动发送）
+    const validUsers = users.filter(u => u.type === "c2c" || u.type === "group");
+    const results = [];
+    let success = 0;
+    let failed = 0;
+    for (const user of validUsers) {
+        const result = await sendProactive({
+            to: user.openid,
+            text,
+            type: user.type,
+            accountId: user.accountId,
+        }, cfg);
+        results.push({ to: user.openid, result });
+        if (result.success) {
+            success++;
+        }
+        else {
+            failed++;
+        }
+        // 添加延迟，避免频率限制
+        await new Promise(resolve => setTimeout(resolve, 500));
+    }
+    return {
+        total: validUsers.length,
+        success,
+        failed,
+        results,
+    };
+}
+// ============ 辅助函数 ============
+/**
+ * 根据账户配置直接发送主动消息（不需要 cfg）
+ *
+ * @param account - 已解析的账户配置
+ * @param to - 目标 openid
+ * @param text - 消息内容
+ * @param type - 消息类型
+ */
+export async function sendProactiveMessageDirect(account, to, text, type = "c2c") {
+    if (!account.appId || !account.clientSecret) {
+        return {
+            success: false,
+            error: "QQBot not configured (missing appId or clientSecret)",
+        };
+    }
+    try {
+        const accessToken = await getAccessToken(account.appId, account.clientSecret);
+        let result;
+        if (type === "c2c") {
+            result = await sendProactiveC2CMessage(accessToken, to, text);
+        }
+        else {
+            result = await sendProactiveGroupMessage(accessToken, to, text);
+        }
+        return {
+            success: true,
+            messageId: result.id,
+            timestamp: result.timestamp,
+        };
+    }
+    catch (err) {
+        return {
+            success: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * 获取已知用户统计
+ */
+export function getKnownUsersStats(accountId) {
+    const users = listKnownUsers({ accountId });
+    return {
+        total: users.length,
+        c2c: users.filter(u => u.type === "c2c").length,
+        group: users.filter(u => u.type === "group").length,
+        channel: users.filter(u => u.type === "channel").length,
+    };
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,3 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+export declare function setQQBotRuntime(next: PluginRuntime): void;
+export declare function getQQBotRuntime(): PluginRuntime;

package/dist/src/runtime.js

@@ -0,0 +1,10 @@
+let runtime = null;
+export function setQQBotRuntime(next) {
+    runtime = next;
+}
+export function getQQBotRuntime() {
+    if (!runtime) {
+        throw new Error("QQBot runtime not initialized");
+    }
+    return runtime;
+}

package/dist/src/session-store.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Session 持久化存储
+ * 将 WebSocket 连接状态（sessionId、lastSeq）持久化到文件
+ * 支持进程重启后通过 Resume 机制快速恢复连接
+ */
+export interface SessionState {
+    /** WebSocket Session ID */
+    sessionId: string | null;
+    /** 最后收到的消息序号 */
+    lastSeq: number | null;
+    /** 上次连接成功的时间戳 */
+    lastConnectedAt: number;
+    /** 上次成功的权限级别索引 */
+    intentLevelIndex: number;
+    /** 关联的机器人账户 ID */
+    accountId: string;
+    /** 保存时间 */
+    savedAt: number;
+}
+/**
+ * 加载 Session 状态
+ * @param accountId 账户 ID
+ * @returns Session 状态，如果不存在或已过期返回 null
+ */
+export declare function loadSession(accountId: string): SessionState | null;
+/**
+ * 保存 Session 状态（带节流，避免频繁写入）
+ * @param state Session 状态
+ */
+export declare function saveSession(state: SessionState): void;
+/**
+ * 清除 Session 状态
+ * @param accountId 账户 ID
+ */
+export declare function clearSession(accountId: string): void;
+/**
+ * 更新 lastSeq（轻量级更新）
+ * @param accountId 账户 ID
+ * @param lastSeq 最新的消息序号
+ */
+export declare function updateLastSeq(accountId: string, lastSeq: number): void;
+/**
+ * 获取所有保存的 Session 状态
+ */
+export declare function getAllSessions(): SessionState[];
+/**
+ * 清理过期的 Session 文件
+ */
+export declare function cleanupExpiredSessions(): number;

package/dist/src/session-store.js

@@ -0,0 +1,242 @@
+/**
+ * Session 持久化存储
+ * 将 WebSocket 连接状态（sessionId、lastSeq）持久化到文件
+ * 支持进程重启后通过 Resume 机制快速恢复连接
+ */
+import fs from "node:fs";
+import path from "node:path";
+// Session 文件目录
+const SESSION_DIR = path.join(process.env.HOME || "/tmp", "clawd", "qqbot-data");
+// Session 过期时间（5分钟）- Resume 要求在断开后一定时间内恢复
+const SESSION_EXPIRE_TIME = 5 * 60 * 1000;
+// 写入节流时间（避免频繁写入）
+const SAVE_THROTTLE_MS = 1000;
+// 每个账户的节流状态
+const throttleState = new Map();
+/**
+ * 确保目录存在
+ */
+function ensureDir() {
+    if (!fs.existsSync(SESSION_DIR)) {
+        fs.mkdirSync(SESSION_DIR, { recursive: true });
+    }
+}
+/**
+ * 获取 Session 文件路径
+ */
+function getSessionPath(accountId) {
+    // 清理 accountId 中的特殊字符
+    const safeId = accountId.replace(/[^a-zA-Z0-9_-]/g, "_");
+    return path.join(SESSION_DIR, `session-${safeId}.json`);
+}
+/**
+ * 加载 Session 状态
+ * @param accountId 账户 ID
+ * @returns Session 状态，如果不存在或已过期返回 null
+ */
+export function loadSession(accountId) {
+    const filePath = getSessionPath(accountId);
+    try {
+        if (!fs.existsSync(filePath)) {
+            return null;
+        }
+        const data = fs.readFileSync(filePath, "utf-8");
+        const state = JSON.parse(data);
+        // 检查是否过期
+        const now = Date.now();
+        if (now - state.savedAt > SESSION_EXPIRE_TIME) {
+            console.log(`[session-store] Session expired for ${accountId}, age: ${Math.round((now - state.savedAt) / 1000)}s`);
+            // 删除过期文件
+            try {
+                fs.unlinkSync(filePath);
+            }
+            catch {
+                // 忽略删除错误
+            }
+            return null;
+        }
+        // 验证必要字段
+        if (!state.sessionId || state.lastSeq === null || state.lastSeq === undefined) {
+            console.log(`[session-store] Invalid session data for ${accountId}`);
+            return null;
+        }
+        console.log(`[session-store] Loaded session for ${accountId}: sessionId=${state.sessionId}, lastSeq=${state.lastSeq}, age=${Math.round((now - state.savedAt) / 1000)}s`);
+        return state;
+    }
+    catch (err) {
+        console.error(`[session-store] Failed to load session for ${accountId}: ${err}`);
+        return null;
+    }
+}
+/**
+ * 保存 Session 状态（带节流，避免频繁写入）
+ * @param state Session 状态
+ */
+export function saveSession(state) {
+    const { accountId } = state;
+    // 获取或初始化节流状态
+    let throttle = throttleState.get(accountId);
+    if (!throttle) {
+        throttle = {
+            pendingState: null,
+            lastSaveTime: 0,
+            throttleTimer: null,
+        };
+        throttleState.set(accountId, throttle);
+    }
+    const now = Date.now();
+    const timeSinceLastSave = now - throttle.lastSaveTime;
+    // 如果距离上次保存时间足够长，立即保存
+    if (timeSinceLastSave >= SAVE_THROTTLE_MS) {
+        doSaveSession(state);
+        throttle.lastSaveTime = now;
+        throttle.pendingState = null;
+        // 清除待定的节流定时器
+        if (throttle.throttleTimer) {
+            clearTimeout(throttle.throttleTimer);
+            throttle.throttleTimer = null;
+        }
+    }
+    else {
+        // 记录待保存的状态
+        throttle.pendingState = state;
+        // 如果没有设置定时器，设置一个
+        if (!throttle.throttleTimer) {
+            const delay = SAVE_THROTTLE_MS - timeSinceLastSave;
+            throttle.throttleTimer = setTimeout(() => {
+                const t = throttleState.get(accountId);
+                if (t && t.pendingState) {
+                    doSaveSession(t.pendingState);
+                    t.lastSaveTime = Date.now();
+                    t.pendingState = null;
+                }
+                if (t) {
+                    t.throttleTimer = null;
+                }
+            }, delay);
+        }
+    }
+}
+/**
+ * 实际执行保存操作
+ */
+function doSaveSession(state) {
+    const filePath = getSessionPath(state.accountId);
+    try {
+        ensureDir();
+        // 更新保存时间
+        const stateToSave = {
+            ...state,
+            savedAt: Date.now(),
+        };
+        fs.writeFileSync(filePath, JSON.stringify(stateToSave, null, 2), "utf-8");
+        console.log(`[session-store] Saved session for ${state.accountId}: sessionId=${state.sessionId}, lastSeq=${state.lastSeq}`);
+    }
+    catch (err) {
+        console.error(`[session-store] Failed to save session for ${state.accountId}: ${err}`);
+    }
+}
+/**
+ * 清除 Session 状态
+ * @param accountId 账户 ID
+ */
+export function clearSession(accountId) {
+    const filePath = getSessionPath(accountId);
+    // 清除节流状态
+    const throttle = throttleState.get(accountId);
+    if (throttle) {
+        if (throttle.throttleTimer) {
+            clearTimeout(throttle.throttleTimer);
+        }
+        throttleState.delete(accountId);
+    }
+    try {
+        if (fs.existsSync(filePath)) {
+            fs.unlinkSync(filePath);
+            console.log(`[session-store] Cleared session for ${accountId}`);
+        }
+    }
+    catch (err) {
+        console.error(`[session-store] Failed to clear session for ${accountId}: ${err}`);
+    }
+}
+/**
+ * 更新 lastSeq（轻量级更新）
+ * @param accountId 账户 ID
+ * @param lastSeq 最新的消息序号
+ */
+export function updateLastSeq(accountId, lastSeq) {
+    const existing = loadSession(accountId);
+    if (existing && existing.sessionId) {
+        saveSession({
+            ...existing,
+            lastSeq,
+        });
+    }
+}
+/**
+ * 获取所有保存的 Session 状态
+ */
+export function getAllSessions() {
+    const sessions = [];
+    try {
+        ensureDir();
+        const files = fs.readdirSync(SESSION_DIR);
+        for (const file of files) {
+            if (file.startsWith("session-") && file.endsWith(".json")) {
+                const filePath = path.join(SESSION_DIR, file);
+                try {
+                    const data = fs.readFileSync(filePath, "utf-8");
+                    const state = JSON.parse(data);
+                    sessions.push(state);
+                }
+                catch {
+                    // 忽略解析错误
+                }
+            }
+        }
+    }
+    catch {
+        // 目录不存在等错误
+    }
+    return sessions;
+}
+/**
+ * 清理过期的 Session 文件
+ */
+export function cleanupExpiredSessions() {
+    let cleaned = 0;
+    try {
+        ensureDir();
+        const files = fs.readdirSync(SESSION_DIR);
+        const now = Date.now();
+        for (const file of files) {
+            if (file.startsWith("session-") && file.endsWith(".json")) {
+                const filePath = path.join(SESSION_DIR, file);
+                try {
+                    const data = fs.readFileSync(filePath, "utf-8");
+                    const state = JSON.parse(data);
+                    if (now - state.savedAt > SESSION_EXPIRE_TIME) {
+                        fs.unlinkSync(filePath);
+                        cleaned++;
+                        console.log(`[session-store] Cleaned expired session: ${file}`);
+                    }
+                }
+                catch {
+                    // 忽略解析错误，但也删除损坏的文件
+                    try {
+                        fs.unlinkSync(filePath);
+                        cleaned++;
+                    }
+                    catch {
+                        // 忽略
+                    }
+                }
+            }
+        }
+    }
+    catch {
+        // 目录不存在等错误
+    }
+    return cleaned;
+}