@jerryliang122/openclaw-qqbot 1.0.0

package/src/features/proactive-budget.ts

@@ -0,0 +1,57 @@
+/**
+ * 主动消息每日预算观测
+ *
+ * QQ Bot 平台主动消息（不带 msg_id）有每日额度（接收方维度约 1000 条/天），
+ * 被动回复（带 msg_id）不占此预算。插件全链路被动优先（msgid-cache 挂接 +
+ * 配额预检），主动仅在「静群超 TTL」或「被动配额耗尽」时触发——本模块对
+ * 这些残余的主动发送按账号计数，接近阈值告警，供排障与预算复核。
+ */
+import { createPluginLogger } from '../utils/plugin-logger.js';
+
+const log = createPluginLogger({ prefix: '[proactive-budget]' });
+
+/** 平台每日主动消息额度（保守取 1000） */
+export const DAILY_PROACTIVE_LIMIT = 1000;
+
+/** 告警阈值比例（80%）与之后的步进 */
+const WARN_RATIO = 0.8;
+const WARN_EVERY = 100;
+
+const counters = new Map<string, { date: string; count: number }>();
+
+function today(): string {
+  return new Date().toISOString().slice(0, 10);
+}
+
+/** 记录一次主动发送（无 msg_id 的出站）；跨天自动重置 */
+export function recordProactiveSend(accountId: string): void {
+  let counter = counters.get(accountId);
+  if (!counter || counter.date !== today()) {
+    counter = { date: today(), count: 0 };
+    counters.set(accountId, counter);
+  }
+  counter.count += 1;
+
+  const warnAt = Math.floor(DAILY_PROACTIVE_LIMIT * WARN_RATIO);
+  if (counter.count === warnAt || (counter.count > warnAt && counter.count % WARN_EVERY === 0)) {
+    log.warn(
+      `proactive daily budget ${counter.count}/${DAILY_PROACTIVE_LIMIT} used (accountId=${accountId}); ` +
+        `passive replies (msg_id) don't count — check msgid-cache TTL / passive quota if unexpected`,
+    );
+  }
+}
+
+/** 查询当日用量（诊断/命令展示用） */
+export function getProactiveUsage(accountId: string): { date: string; count: number; limit: number } {
+  const counter = counters.get(accountId);
+  return {
+    date: counter?.date ?? today(),
+    count: counter?.date === today() ? counter.count : 0,
+    limit: DAILY_PROACTIVE_LIMIT,
+  };
+}
+
+/** 测试用：清空计数 */
+export function _resetProactiveBudget(): void {
+  counters.clear();
+}

package/src/features/proactive.ts

@@ -0,0 +1,549 @@
+import { createPluginLogger } from "../utils/plugin-logger.js";
+
+const log = createPluginLogger({ prefix: '[proactive]' });
+
+/**
+ * QQ Bot 主动发送消息模块
+ * 
+ * 该模块提供以下能力：
+ * 1. 记录已知用户（曾与机器人交互过的用户）
+ * 2. 主动发送消息给用户或群组
+ * 3. 查询已知用户列表
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ResolvedQQBotAccount } from "../types.js";
+
+// ============ 类型定义（本地） ============
+
+/**
+ * 已知用户信息
+ */
+export interface KnownUser {
+  type: "c2c" | "group" | "channel";
+  openid: string;
+  accountId: string;
+  nickname?: string;
+  firstInteractionAt: number;
+  lastInteractionAt: number;
+}
+
+/**
+ * 主动发送消息选项
+ */
+export interface ProactiveSendOptions {
+  to: string;
+  text: string;
+  type?: "c2c" | "group" | "channel";
+  imageUrl?: string;
+  accountId?: string;
+}
+
+/**
+ * 主动发送消息结果
+ */
+export interface ProactiveSendResult {
+  success: boolean;
+  messageId?: string;
+  timestamp?: number | string;
+  error?: string;
+}
+
+/**
+ * 列出已知用户选项
+ */
+export interface ListKnownUsersOptions {
+  type?: "c2c" | "group" | "channel";
+  accountId?: string;
+  sortByLastInteraction?: boolean;
+  limit?: number;
+}
+import {
+  getBotForAccount,
+} from "../bot-instance.js";
+import { resolveQQBotAccount } from "../config.js";
+import type { OpenClawConfig } from "openclaw/plugin-sdk";
+
+// ============ 用户存储管理 ============
+
+/**
+ * 已知用户存储
+ * 使用简单的 JSON 文件存储，保存在 .openclaw/qqbot 目录下
+ */
+import { getQQBotDataDir } from "../utils/platform.js";
+
+const STORAGE_DIR = getQQBotDataDir("data");
+const KNOWN_USERS_FILE = path.join(STORAGE_DIR, "known-users.json");
+
+// 内存缓存
+let knownUsersCache: Map<string, KnownUser> | null = null;
+let cacheLastModified = 0;
+
+/**
+ * 确保存储目录存在
+ */
+function ensureStorageDir(): void {
+  if (!fs.existsSync(STORAGE_DIR)) {
+    fs.mkdirSync(STORAGE_DIR, { recursive: true });
+  }
+}
+
+/**
+ * 生成用户唯一键
+ */
+function getUserKey(type: string, openid: string, accountId: string): string {
+  return `${accountId}:${type}:${openid}`;
+}
+
+/**
+ * 从文件加载已知用户
+ */
+function loadKnownUsers(): Map<string, KnownUser> {
+  if (knownUsersCache !== null) {
+    // 检查文件是否被修改
+    try {
+      const stat = fs.statSync(KNOWN_USERS_FILE);
+      if (stat.mtimeMs <= cacheLastModified) {
+        return knownUsersCache;
+      }
+    } catch {
+      // 文件不存在，使用缓存
+      return knownUsersCache;
+    }
+  }
+
+  const users = new Map<string, KnownUser>();
+  
+  try {
+    if (fs.existsSync(KNOWN_USERS_FILE)) {
+      const data = fs.readFileSync(KNOWN_USERS_FILE, "utf-8");
+      const parsed = JSON.parse(data) as KnownUser[];
+      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) {
+    log.error(`Failed to load known users: ${err}`);
+  }
+
+  knownUsersCache = users;
+  return users;
+}
+
+/**
+ * 保存已知用户到文件
+ */
+function saveKnownUsers(users: Map<string, KnownUser>): void {
+  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) {
+    log.error(`Failed to save known users: ${err}`);
+  }
+}
+
+/**
+ * 记录一个已知用户（当收到用户消息时调用）
+ * 
+ * @param user - 用户信息
+ */
+export function recordKnownUser(user: Omit<KnownUser, "firstInteractionAt">): void {
+  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);
+  log.info(`Recorded user: ${key}`);
+}
+
+/**
+ * 获取一个已知用户
+ * 
+ * @param type - 用户类型
+ * @param openid - 用户 openid
+ * @param accountId - 账户 ID
+ */
+export function getKnownUser(type: string, openid: string, accountId: string): KnownUser | undefined {
+  const users = loadKnownUsers();
+  const key = getUserKey(type, openid, accountId);
+  return users.get(key);
+}
+
+/**
+ * 列出已知用户
+ * 
+ * @param options - 过滤选项
+ */
+export function listKnownUsers(options?: ListKnownUsersOptions): KnownUser[] {
+  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: string, openid: string, accountId: string): boolean {
+  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?: string): number {
+  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: ProactiveSendOptions,
+  cfg: OpenClawConfig
+): Promise<ProactiveSendResult> {
+  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 bot = getBotForAccount(account.accountId);
+    const target = { scope: type as "c2c" | "group", targetId: to };
+
+    // 如果有图片，先发送图片
+    if (imageUrl) {
+      try {
+        await bot.sendImage(target, { url: imageUrl });
+        log.info(`Sent image to ${type}:${to}`);
+      } catch (err) {
+        log.error(`Failed to send image: ${err}`);
+      }
+    }
+    
+    // 发送文本消息（主动消息：无 msgId）
+    if (type === "channel") {
+      return {
+        success: false,
+        error: "Channel proactive messages are not supported. Please use group or c2c.",
+      };
+    }
+
+    const result = await bot.sendText(target, text);
+    log.info(`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);
+    log.error(`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: string[],
+  text: string,
+  type: "c2c" | "group",
+  cfg: OpenClawConfig,
+  accountId = "default"
+): Promise<Array<{ to: string; result: ProactiveSendResult }>> {
+  const results: Array<{ to: string; result: ProactiveSendResult }> = [];
+  
+  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: string,
+  cfg: OpenClawConfig,
+  options?: {
+    type?: "c2c" | "group";
+    accountId?: string;
+    limit?: number;
+  }
+): Promise<{
+  total: number;
+  success: number;
+  failed: number;
+  results: Array<{ to: string; result: ProactiveSendResult }>;
+}> {
+  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: Array<{ to: string; result: ProactiveSendResult }> = [];
+  let success = 0;
+  let failed = 0;
+  
+  for (const user of validUsers) {
+    const result = await sendProactive({
+      to: user.openid,
+      text,
+      type: user.type as "c2c" | "group",
+      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: ResolvedQQBotAccount,
+  to: string,
+  text: string,
+  type: "c2c" | "group" = "c2c"
+): Promise<ProactiveSendResult> {
+  if (!account.appId || !account.clientSecret) {
+    return {
+      success: false,
+      error: "QQBot not configured (missing appId or clientSecret)",
+    };
+  }
+  
+  try {
+    const bot = getBotForAccount(account.accountId);
+    const target = { scope: type, targetId: to };
+    const result = await bot.sendText(target, 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?: string): {
+  total: number;
+  c2c: number;
+  group: number;
+  channel: number;
+} {
+  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,
+  };
+}
+
+/**
+ * 获取用户的所有群组（某用户在哪些群里交互过）
+ *
+ * @param accountId 机器人账户 ID
+ * @param openid 用户 openid
+ * @returns 群组 openid 列表
+ */
+export function getUserGroups(accountId: string, openid: string): string[] {
+  const users = loadKnownUsers();
+  const groups: string[] = [];
+  for (const [, user] of users) {
+    if (user.accountId !== accountId) continue;
+    if (user.type !== 'group') continue;
+    // group 类型的 openid 是 groupOpenid，检查该群中是否有此用户交互记录
+    // 注：当前数据模型 group 记录的 openid 是 groupOpenid 本身
+    // 要实现精确的"用户在哪些群"，需要在 recordKnownUser 时同时记录 senderOpenid
+    // 这里降级为：列出该账户的所有群 openid
+    groups.push(user.openid);
+  }
+  return [...new Set(groups)];
+}
+
+/**
+ * 获取群组的所有已知成员
+ *
+ * @param accountId 机器人账户 ID
+ * @param groupOpenid 群组 openid
+ * @returns 在该群中交互过的用户列表
+ */
+export function getGroupMembers(accountId: string, groupOpenid: string): KnownUser[] {
+  const users = loadKnownUsers();
+  const members: KnownUser[] = [];
+  for (const [, user] of users) {
+    if (user.accountId !== accountId) continue;
+    if (user.type === 'group' && user.openid === groupOpenid) {
+      members.push(user);
+    }
+  }
+  return members;
+}