@sliverp/qqbot 1.3.0

package/dist/src/known-users.js

@@ -0,0 +1,264 @@
+/**
+ * 已知用户存储
+ * 记录与机器人交互过的所有用户
+ * 支持主动消息和批量通知功能
+ */
+import fs from "node:fs";
+import path from "node:path";
+// 存储文件路径
+const KNOWN_USERS_DIR = path.join(process.env.HOME || "/tmp", "clawd", "qqbot-data");
+const KNOWN_USERS_FILE = path.join(KNOWN_USERS_DIR, "known-users.json");
+// 内存缓存
+let usersCache = null;
+// 写入节流配置
+const SAVE_THROTTLE_MS = 5000; // 5秒写入一次
+let saveTimer = null;
+let isDirty = false;
+/**
+ * 确保目录存在
+ */
+function ensureDir() {
+    if (!fs.existsSync(KNOWN_USERS_DIR)) {
+        fs.mkdirSync(KNOWN_USERS_DIR, { recursive: true });
+    }
+}
+/**
+ * 从文件加载用户数据到缓存
+ */
+function loadUsersFromFile() {
+    if (usersCache !== null) {
+        return usersCache;
+    }
+    usersCache = new Map();
+    try {
+        if (fs.existsSync(KNOWN_USERS_FILE)) {
+            const data = fs.readFileSync(KNOWN_USERS_FILE, "utf-8");
+            const users = JSON.parse(data);
+            for (const user of users) {
+                // 使用复合键：accountId + type + openid（群组还要加 groupOpenid）
+                const key = makeUserKey(user);
+                usersCache.set(key, user);
+            }
+            console.log(`[known-users] Loaded ${usersCache.size} users from file`);
+        }
+    }
+    catch (err) {
+        console.error(`[known-users] Failed to load users: ${err}`);
+        usersCache = new Map();
+    }
+    return usersCache;
+}
+/**
+ * 保存用户数据到文件（节流版本）
+ */
+function saveUsersToFile() {
+    if (!isDirty)
+        return;
+    if (saveTimer) {
+        return; // 已有定时器在等待
+    }
+    saveTimer = setTimeout(() => {
+        saveTimer = null;
+        doSaveUsersToFile();
+    }, SAVE_THROTTLE_MS);
+}
+/**
+ * 实际执行保存
+ */
+function doSaveUsersToFile() {
+    if (!usersCache || !isDirty)
+        return;
+    try {
+        ensureDir();
+        const users = Array.from(usersCache.values());
+        fs.writeFileSync(KNOWN_USERS_FILE, JSON.stringify(users, null, 2), "utf-8");
+        isDirty = false;
+        console.log(`[known-users] Saved ${users.length} users to file`);
+    }
+    catch (err) {
+        console.error(`[known-users] Failed to save users: ${err}`);
+    }
+}
+/**
+ * 强制立即保存（用于进程退出前）
+ */
+export function flushKnownUsers() {
+    if (saveTimer) {
+        clearTimeout(saveTimer);
+        saveTimer = null;
+    }
+    doSaveUsersToFile();
+}
+/**
+ * 生成用户唯一键
+ */
+function makeUserKey(user) {
+    const base = `${user.accountId}:${user.type}:${user.openid}`;
+    if (user.type === "group" && user.groupOpenid) {
+        return `${base}:${user.groupOpenid}`;
+    }
+    return base;
+}
+/**
+ * 记录已知用户（收到消息时调用）
+ * @param user 用户信息（部分字段）
+ */
+export function recordKnownUser(user) {
+    const cache = loadUsersFromFile();
+    const key = makeUserKey(user);
+    const now = Date.now();
+    const existing = cache.get(key);
+    if (existing) {
+        // 更新已存在的用户
+        existing.lastSeenAt = now;
+        existing.interactionCount++;
+        if (user.nickname && user.nickname !== existing.nickname) {
+            existing.nickname = user.nickname;
+        }
+        console.log(`[known-users] Updated user ${user.openid}, interactions: ${existing.interactionCount}`);
+    }
+    else {
+        // 新用户
+        const newUser = {
+            openid: user.openid,
+            type: user.type,
+            nickname: user.nickname,
+            groupOpenid: user.groupOpenid,
+            accountId: user.accountId,
+            firstSeenAt: now,
+            lastSeenAt: now,
+            interactionCount: 1,
+        };
+        cache.set(key, newUser);
+        console.log(`[known-users] New user recorded: ${user.openid} (${user.type})`);
+    }
+    isDirty = true;
+    saveUsersToFile();
+}
+/**
+ * 获取单个用户信息
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ * @param type 消息类型
+ * @param groupOpenid 群组 openid（可选）
+ */
+export function getKnownUser(accountId, openid, type = "c2c", groupOpenid) {
+    const cache = loadUsersFromFile();
+    const key = makeUserKey({ accountId, openid, type, groupOpenid });
+    return cache.get(key);
+}
+/**
+ * 列出所有已知用户
+ * @param options 筛选选项
+ */
+export function listKnownUsers(options) {
+    const cache = loadUsersFromFile();
+    let users = Array.from(cache.values());
+    // 筛选
+    if (options?.accountId) {
+        users = users.filter(u => u.accountId === options.accountId);
+    }
+    if (options?.type) {
+        users = users.filter(u => u.type === options.type);
+    }
+    if (options?.activeWithin) {
+        const cutoff = Date.now() - options.activeWithin;
+        users = users.filter(u => u.lastSeenAt >= cutoff);
+    }
+    // 排序
+    const sortBy = options?.sortBy ?? "lastSeenAt";
+    const sortOrder = options?.sortOrder ?? "desc";
+    users.sort((a, b) => {
+        const aVal = a[sortBy] ?? 0;
+        const bVal = b[sortBy] ?? 0;
+        return sortOrder === "asc" ? aVal - bVal : bVal - aVal;
+    });
+    // 限制数量
+    if (options?.limit && options.limit > 0) {
+        users = users.slice(0, options.limit);
+    }
+    return users;
+}
+/**
+ * 获取用户统计信息
+ * @param accountId 机器人账户 ID（可选，不传则返回所有账户的统计）
+ */
+export function getKnownUsersStats(accountId) {
+    let users = listKnownUsers({ accountId });
+    const now = Date.now();
+    const day = 24 * 60 * 60 * 1000;
+    return {
+        totalUsers: users.length,
+        c2cUsers: users.filter(u => u.type === "c2c").length,
+        groupUsers: users.filter(u => u.type === "group").length,
+        activeIn24h: users.filter(u => now - u.lastSeenAt < day).length,
+        activeIn7d: users.filter(u => now - u.lastSeenAt < 7 * day).length,
+    };
+}
+/**
+ * 删除用户记录
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ * @param type 消息类型
+ * @param groupOpenid 群组 openid（可选）
+ */
+export function removeKnownUser(accountId, openid, type = "c2c", groupOpenid) {
+    const cache = loadUsersFromFile();
+    const key = makeUserKey({ accountId, openid, type, groupOpenid });
+    if (cache.has(key)) {
+        cache.delete(key);
+        isDirty = true;
+        saveUsersToFile();
+        console.log(`[known-users] Removed user ${openid}`);
+        return true;
+    }
+    return false;
+}
+/**
+ * 清除所有用户记录
+ * @param accountId 机器人账户 ID（可选，不传则清除所有）
+ */
+export function clearKnownUsers(accountId) {
+    const cache = loadUsersFromFile();
+    let count = 0;
+    if (accountId) {
+        // 只清除指定账户的用户
+        for (const [key, user] of cache.entries()) {
+            if (user.accountId === accountId) {
+                cache.delete(key);
+                count++;
+            }
+        }
+    }
+    else {
+        // 清除所有
+        count = cache.size;
+        cache.clear();
+    }
+    if (count > 0) {
+        isDirty = true;
+        doSaveUsersToFile(); // 立即保存
+        console.log(`[known-users] Cleared ${count} users`);
+    }
+    return count;
+}
+/**
+ * 获取用户的所有群组（某用户在哪些群里交互过）
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ */
+export function getUserGroups(accountId, openid) {
+    const users = listKnownUsers({ accountId, type: "group" });
+    return users
+        .filter(u => u.openid === openid && u.groupOpenid)
+        .map(u => u.groupOpenid);
+}
+/**
+ * 获取群组的所有成员
+ * @param accountId 机器人账户 ID
+ * @param groupOpenid 群组 openid
+ */
+export function getGroupMembers(accountId, groupOpenid) {
+    return listKnownUsers({ accountId, type: "group" })
+        .filter(u => u.groupOpenid === groupOpenid);
+}

package/dist/src/onboarding.d.ts

@@ -0,0 +1,10 @@
+/**
+ * QQBot CLI Onboarding Adapter
+ *
+ * 提供 openclaw onboard 命令的交互式配置支持
+ */
+import type { ChannelOnboardingAdapter } from "openclaw/plugin-sdk";
+/**
+ * QQBot Onboarding Adapter
+ */
+export declare const qqbotOnboardingAdapter: ChannelOnboardingAdapter;

package/dist/src/onboarding.js

@@ -0,0 +1,190 @@
+import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount } from "./config.js";
+/**
+ * 解析默认账户 ID
+ */
+function resolveDefaultQQBotAccountId(cfg) {
+    const ids = listQQBotAccountIds(cfg);
+    return ids[0] ?? DEFAULT_ACCOUNT_ID;
+}
+/**
+ * QQBot Onboarding Adapter
+ */
+export const qqbotOnboardingAdapter = {
+    channel: "qqbot",
+    getStatus: async (ctx) => {
+        const cfg = ctx.cfg;
+        const configured = listQQBotAccountIds(cfg).some((accountId) => {
+            const account = resolveQQBotAccount(cfg, accountId);
+            return Boolean(account.appId && account.clientSecret);
+        });
+        return {
+            channel: "qqbot",
+            configured,
+            statusLines: [`QQ Bot: ${configured ? "已配置" : "需要 AppID 和 ClientSecret"}`],
+            selectionHint: configured ? "已配置" : "支持 QQ 群聊和私聊（流式消息）",
+            quickstartScore: configured ? 1 : 20,
+        };
+    },
+    configure: async (ctx) => {
+        const cfg = ctx.cfg;
+        const prompter = ctx.prompter;
+        const accountOverrides = ctx.accountOverrides;
+        const shouldPromptAccountIds = ctx.shouldPromptAccountIds;
+        const qqbotOverride = accountOverrides?.qqbot?.trim();
+        const defaultAccountId = resolveDefaultQQBotAccountId(cfg);
+        let accountId = qqbotOverride ?? defaultAccountId;
+        // 是否需要提示选择账户
+        if (shouldPromptAccountIds && !qqbotOverride) {
+            const existingIds = listQQBotAccountIds(cfg);
+            if (existingIds.length > 1) {
+                accountId = await prompter.select({
+                    message: "选择 QQBot 账户",
+                    options: existingIds.map((id) => ({
+                        value: id,
+                        label: id === DEFAULT_ACCOUNT_ID ? "默认账户" : id,
+                    })),
+                    initialValue: accountId,
+                });
+            }
+        }
+        let next = cfg;
+        const resolvedAccount = resolveQQBotAccount(next, accountId);
+        const accountConfigured = Boolean(resolvedAccount.appId && resolvedAccount.clientSecret);
+        const allowEnv = accountId === DEFAULT_ACCOUNT_ID;
+        const envAppId = typeof process !== "undefined" ? process.env?.QQBOT_APP_ID?.trim() : undefined;
+        const envSecret = typeof process !== "undefined" ? process.env?.QQBOT_CLIENT_SECRET?.trim() : undefined;
+        const canUseEnv = allowEnv && Boolean(envAppId && envSecret);
+        const hasConfigCredentials = Boolean(resolvedAccount.config.appId && resolvedAccount.config.clientSecret);
+        let appId = null;
+        let clientSecret = null;
+        // 显示帮助
+        if (!accountConfigured) {
+            await prompter.note([
+                "1) 打开 QQ 开放平台: https://q.qq.com/",
+                "2) 创建机器人应用，获取 AppID 和 ClientSecret",
+                "3) 在「开发设置」中添加沙箱成员（测试阶段）",
+                "4) 你也可以设置环境变量 QQBOT_APP_ID 和 QQBOT_CLIENT_SECRET",
+                "",
+                "文档: https://bot.q.qq.com/wiki/",
+                "",
+                "此版本支持流式消息发送！",
+            ].join("\n"), "QQ Bot 配置");
+        }
+        // 检测环境变量
+        if (canUseEnv && !hasConfigCredentials) {
+            const keepEnv = await prompter.confirm({
+                message: "检测到环境变量 QQBOT_APP_ID 和 QQBOT_CLIENT_SECRET，是否使用？",
+                initialValue: true,
+            });
+            if (keepEnv) {
+                next = {
+                    ...next,
+                    channels: {
+                        ...next.channels,
+                        qqbot: {
+                            ...(next.channels?.qqbot || {}),
+                            enabled: true,
+                        },
+                    },
+                };
+            }
+            else {
+                // 手动输入
+                appId = String(await prompter.text({
+                    message: "请输入 QQ Bot AppID",
+                    placeholder: "例如: 102146862",
+                    initialValue: resolvedAccount.appId || undefined,
+                    validate: (value) => (value?.trim() ? undefined : "AppID 不能为空"),
+                })).trim();
+                clientSecret = String(await prompter.text({
+                    message: "请输入 QQ Bot ClientSecret",
+                    placeholder: "你的 ClientSecret",
+                    validate: (value) => (value?.trim() ? undefined : "ClientSecret 不能为空"),
+                })).trim();
+            }
+        }
+        else if (hasConfigCredentials) {
+            // 已有配置
+            const keep = await prompter.confirm({
+                message: "QQ Bot 已配置，是否保留当前配置？",
+                initialValue: true,
+            });
+            if (!keep) {
+                appId = String(await prompter.text({
+                    message: "请输入 QQ Bot AppID",
+                    placeholder: "例如: 102146862",
+                    initialValue: resolvedAccount.appId || undefined,
+                    validate: (value) => (value?.trim() ? undefined : "AppID 不能为空"),
+                })).trim();
+                clientSecret = String(await prompter.text({
+                    message: "请输入 QQ Bot ClientSecret",
+                    placeholder: "你的 ClientSecret",
+                    validate: (value) => (value?.trim() ? undefined : "ClientSecret 不能为空"),
+                })).trim();
+            }
+        }
+        else {
+            // 没有配置，需要输入
+            appId = String(await prompter.text({
+                message: "请输入 QQ Bot AppID",
+                placeholder: "例如: 102146862",
+                initialValue: resolvedAccount.appId || undefined,
+                validate: (value) => (value?.trim() ? undefined : "AppID 不能为空"),
+            })).trim();
+            clientSecret = String(await prompter.text({
+                message: "请输入 QQ Bot ClientSecret",
+                placeholder: "你的 ClientSecret",
+                validate: (value) => (value?.trim() ? undefined : "ClientSecret 不能为空"),
+            })).trim();
+        }
+        // 应用配置
+        if (appId && clientSecret) {
+            if (accountId === DEFAULT_ACCOUNT_ID) {
+                next = {
+                    ...next,
+                    channels: {
+                        ...next.channels,
+                        qqbot: {
+                            ...(next.channels?.qqbot || {}),
+                            enabled: true,
+                            appId,
+                            clientSecret,
+                        },
+                    },
+                };
+            }
+            else {
+                next = {
+                    ...next,
+                    channels: {
+                        ...next.channels,
+                        qqbot: {
+                            ...(next.channels?.qqbot || {}),
+                            enabled: true,
+                            accounts: {
+                                ...(next.channels?.qqbot?.accounts || {}),
+                                [accountId]: {
+                                    ...(next.channels?.qqbot?.accounts?.[accountId] || {}),
+                                    enabled: true,
+                                    appId,
+                                    clientSecret,
+                                },
+                            },
+                        },
+                    },
+                };
+            }
+        }
+        return { success: true, cfg: next, accountId };
+    },
+    disable: (cfg) => {
+        const config = cfg;
+        return {
+            ...config,
+            channels: {
+                ...config.channels,
+                qqbot: { ...(config.channels?.qqbot || {}), enabled: false },
+            },
+        };
+    },
+};

package/dist/src/outbound.d.ts

@@ -0,0 +1,149 @@
+/**
+ * QQ Bot 消息发送模块
+ */
+import type { ResolvedQQBotAccount } from "./types.js";
+/** 限流检查结果 */
+export interface ReplyLimitResult {
+    /** 是否允许被动回复 */
+    allowed: boolean;
+    /** 剩余被动回复次数 */
+    remaining: number;
+    /** 是否需要降级为主动消息（超期或超过次数） */
+    shouldFallbackToProactive: boolean;
+    /** 降级原因 */
+    fallbackReason?: "expired" | "limit_exceeded";
+    /** 提示消息 */
+    message?: string;
+}
+/**
+ * 检查是否可以回复该消息（限流检查）
+ * @param messageId 消息ID
+ * @returns ReplyLimitResult 限流检查结果
+ */
+export declare function checkMessageReplyLimit(messageId: string): ReplyLimitResult;
+/**
+ * 记录一次消息回复
+ * @param messageId 消息ID
+ */
+export declare function recordMessageReply(messageId: string): void;
+/**
+ * 获取消息回复统计信息
+ */
+export declare function getMessageReplyStats(): {
+    trackedMessages: number;
+    totalReplies: number;
+};
+/**
+ * 获取消息回复限制配置（供外部查询）
+ */
+export declare function getMessageReplyConfig(): {
+    limit: number;
+    ttlMs: number;
+    ttlHours: number;
+};
+export interface OutboundContext {
+    to: string;
+    text: string;
+    accountId?: string | null;
+    replyToId?: string | null;
+    account: ResolvedQQBotAccount;
+}
+export interface MediaOutboundContext extends OutboundContext {
+    mediaUrl: string;
+}
+export interface OutboundResult {
+    channel: string;
+    messageId?: string;
+    timestamp?: string | number;
+    error?: string;
+}
+/**
+ * 发送文本消息
+ * - 有 replyToId: 被动回复，1小时内最多回复4次
+ * - 无 replyToId: 主动发送，有配额限制（每月4条/用户/群）
+ *
+ * 注意：
+ * 1. 主动消息（无 replyToId）必须有消息内容，不支持流式发送
+ * 2. 当被动回复不可用（超期或超过次数）时，自动降级为主动消息
+ */
+export declare function sendText(ctx: OutboundContext): Promise<OutboundResult>;
+/**
+ * 主动发送消息（不需要 replyToId，有配额限制：每月 4 条/用户/群）
+ *
+ * @param account - 账户配置
+ * @param to - 目标地址，格式：openid（单聊）或 group:xxx（群聊）
+ * @param text - 消息内容
+ */
+export declare function sendProactiveMessage(account: ResolvedQQBotAccount, to: string, text: string): Promise<OutboundResult>;
+/**
+ * 发送富媒体消息（图片）
+ *
+ * 支持以下 mediaUrl 格式：
+ * - 公网 URL: https://example.com/image.png
+ * - Base64 Data URL: data:image/png;base64,xxxxx
+ * - 本地文件路径: /path/to/image.png（自动读取并转换为 Base64）
+ *
+ * @param ctx - 发送上下文，包含 mediaUrl
+ * @returns 发送结果
+ *
+ * @example
+ * ```typescript
+ * // 发送网络图片
+ * const result = await sendMedia({
+ *   to: "group:xxx",
+ *   text: "这是图片说明",
+ *   mediaUrl: "https://example.com/image.png",
+ *   account,
+ *   replyToId: msgId,
+ * });
+ *
+ * // 发送 Base64 图片
+ * const result = await sendMedia({
+ *   to: "group:xxx",
+ *   text: "这是图片说明",
+ *   mediaUrl: "data:image/png;base64,iVBORw0KGgo...",
+ *   account,
+ *   replyToId: msgId,
+ * });
+ *
+ * // 发送本地文件（自动读取并转换为 Base64）
+ * const result = await sendMedia({
+ *   to: "group:xxx",
+ *   text: "这是图片说明",
+ *   mediaUrl: "/tmp/generated-chart.png",
+ *   account,
+ *   replyToId: msgId,
+ * });
+ * ```
+ */
+export declare function sendMedia(ctx: MediaOutboundContext): Promise<OutboundResult>;
+/**
+ * 发送 Cron 触发的消息
+ *
+ * 当 OpenClaw cron 任务触发时，消息内容可能是：
+ * 1. QQBOT_CRON:{base64} 格式的结构化载荷 - 解码后根据 targetType 和 targetAddress 发送
+ * 2. 普通文本 - 直接发送到指定目标
+ *
+ * @param account - 账户配置
+ * @param to - 目标地址（作为后备，如果载荷中没有指定）
+ * @param message - 消息内容（可能是 QQBOT_CRON: 格式或普通文本）
+ * @returns 发送结果
+ *
+ * @example
+ * ```typescript
+ * // 处理结构化载荷
+ * const result = await sendCronMessage(
+ *   account,
+ *   "user_openid",  // 后备地址
+ *   "QQBOT_CRON:eyJ0eXBlIjoiY3Jvbl9yZW1pbmRlciIs..."  // Base64 编码的载荷
+ * );
+ *
+ * // 处理普通文本
+ * const result = await sendCronMessage(
+ *   account,
+ *   "user_openid",
+ *   "这是一条普通的提醒消息"
+ * );
+ * ```
+ */
+export declare function sendCronMessage(account: ResolvedQQBotAccount, to: string, message: string): Promise<OutboundResult>;