@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

package/src/features/approval-utils.ts

@@ -0,0 +1,41 @@
+/**
+ * 审批相关工具函数
+ *
+ * 审批 payload 判断逻辑，供 channel.ts 和 features/approval-handler 使用。
+ */
+
+/** 检查 payload 是否为审批消息（execApproval / plugin approval） */
+export function isApprovalPayload(payload: unknown): boolean {
+  if (!payload || typeof payload !== 'object') return false;
+  const p = payload as Record<string, unknown>;
+  const cd = p.channelData;
+  if (cd && typeof cd === 'object' && !Array.isArray(cd)) {
+    const execApproval = (cd as Record<string, unknown>).execApproval;
+    if (execApproval && typeof execApproval === 'object' && !Array.isArray(execApproval)) {
+      return true;
+    }
+  }
+  const text = typeof p.text === 'string' ? p.text : '';
+  return /(?:Plugin|Exec) approval (?:required|allowed|denied|expired)/i.test(text);
+}
+
+/** 审批 ChannelPlugin stub — 空壳实现（实际审批由 features/approval-handler 处理） */
+export const approvalStubs = {
+  execApprovals: {
+    getInitiatingSurfaceState: () => ({ kind: 'enabled' as const }),
+    shouldSuppressForwardingFallback: () => true,
+    shouldSuppressLocalPrompt: ({ payload }: { payload: unknown }) => isApprovalPayload(payload),
+    buildPendingPayload: () => null,
+    buildResolvedPayload: () => null,
+  },
+  approvals: {
+    delivery: {
+      hasConfiguredDmRoute: () => true,
+      shouldSuppressForwardingFallback: () => true,
+    },
+    render: {
+      exec: { buildPendingPayload: () => null, buildResolvedPayload: () => null },
+      plugin: { buildPendingPayload: () => null, buildResolvedPayload: () => null },
+    },
+  },
+} as const;

package/src/features/credential-backup.ts

@@ -0,0 +1,82 @@
+/**
+ * 凭证暂存与恢复
+ *
+ * 解决热更新被打断时 openclaw.json 中 appId/secret 丢失的问题。
+ *
+ * 存储路径：~/.openclaw/qqbot/data/credential-backup/current.json
+ * 使用子目录避免被框架 SQLite 迁移扫描（迁移只匹配 data/credential-backup.json）。
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getQQBotDataDir } from '../utils/platform.js';
+
+const BACKUP_DIR = 'credential-backup';
+const BACKUP_FILENAME = 'current.json';
+const LEGACY_FILENAME = 'credential-backup.json';
+
+interface CredentialBackup {
+  accountId: string;
+  appId: string;
+  clientSecret: string;
+  savedAt: string;
+}
+
+function getBackupPath(): string {
+  return path.join(getQQBotDataDir('data'), BACKUP_DIR, BACKUP_FILENAME);
+}
+
+/**
+ * 保存凭证快照到暂存文件（gateway 成功启动后调用）
+ */
+export function saveCredentialBackup(accountId: string, appId: string, clientSecret: string): void {
+  if (!appId || !clientSecret) return;
+  try {
+    const backupPath = getBackupPath();
+    const dir = path.dirname(backupPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    const data: CredentialBackup = {
+      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?: string): CredentialBackup | null {
+  try {
+    // 优先读新路径
+    const backupPath = getBackupPath();
+    if (fs.existsSync(backupPath)) {
+      const data = readBackupFile(backupPath, accountId);
+      if (data) return data;
+    }
+    // 兼容旧路径（升级过渡）
+    const legacyPath = path.join(getQQBotDataDir('data'), LEGACY_FILENAME);
+    if (fs.existsSync(legacyPath)) {
+      return readBackupFile(legacyPath, accountId);
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+function readBackupFile(filePath: string, accountId?: string): CredentialBackup | null {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const data: CredentialBackup = JSON.parse(raw);
+  if (!data.appId || !data.clientSecret) return null;
+  if (accountId && data.accountId !== accountId) return null;
+  return data;
+}

package/src/features/history-store.ts

@@ -0,0 +1,19 @@
+import { MemoryHistoryStore } from '@tencent-connect/qqbot-nodejs';
+import type { HistoryStore } from '@tencent-connect/qqbot-nodejs';
+
+let _store: HistoryStore | null = null;
+
+export function getHistoryStore(): HistoryStore {
+  if (!_store) _store = new MemoryHistoryStore();
+  return _store;
+}
+
+/** 用 accountId 前缀隔离多账号，避免同群历史串用 */
+export function historyGroupKey(accountId: string, groupId: string): string {
+  return `${accountId}:${groupId}`;
+}
+
+/** 清空群历史（dispatch 完成后调用） */
+export function clearGroupHistory(accountId: string, groupId: string): void {
+  _store?.clear?.(historyGroupKey(accountId, groupId));
+}

package/src/features/msgid-cache.ts

@@ -0,0 +1,55 @@
+/**
+ * 消息 ID 缓存 — 记录最近处理的 msgId，供被动回复使用。
+ *
+ * 场景：外部调用发送消息时没有上下文，
+ * 从缓存获取最近一条未过期的 msgId 作为被动回复目标。
+ */
+
+interface CachedMsgId {
+  msgId: string;
+  timestamp: number;
+}
+
+const MAX_PER_TARGET = 10;
+const TTL_GROUP = 5 * 60 * 1000;   // 5 分钟
+const TTL_C2C = 30 * 60 * 1000;   // 30 分钟
+const MAX_TARGETS = 200;
+
+const cache = new Map<string, CachedMsgId[]>();
+
+export function cacheMsgId(scope: string, targetId: string, msgId: string): void {
+  if (!scope || !targetId || !msgId) return;
+  const key = `${scope}:${targetId}`;
+  const existing = cache.get(key);
+  if (existing) {
+    // LRU: 删除再重新插入
+    cache.delete(key);
+    existing.push({ msgId, timestamp: Date.now() });
+    if (existing.length > MAX_PER_TARGET) existing.shift();
+    cache.set(key, existing);
+  } else {
+    cache.set(key, [{ msgId, timestamp: Date.now() }]);
+    if (cache.size > MAX_TARGETS) {
+      const oldest = cache.keys().next().value;
+      if (oldest) cache.delete(oldest);
+    }
+  }
+}
+
+export function getCachedMsgId(scope: string, targetId: string): string | undefined {
+  const key = `${scope}:${targetId}`;
+  const list = cache.get(key);
+  if (!list || list.length === 0) return undefined;
+  const now = Date.now();
+  const ttl = scope === 'group' ? TTL_GROUP : TTL_C2C;
+  for (let i = list.length - 1; i >= 0; i--) {
+    if (now - list[i].timestamp < ttl) {
+      return list[i].msgId;
+    }
+  }
+  return undefined;
+}
+
+export function clearMsgIdCache(scope: string, targetId: string): void {
+  cache.delete(`${scope}:${targetId}`);
+}

package/src/features/onboarding.ts

@@ -0,0 +1,38 @@
+/**
+ * QQBot CLI Onboarding Adapter
+ *
+ * 提供 openclaw onboard 命令的交互式配置支持。
+ * 从原 src/onboarding.ts 迁移，保持接口兼容。
+ */
+import type {
+  ChannelOnboardingAdapter,
+  OpenClawConfig,
+} from 'openclaw/plugin-sdk';
+import { DEFAULT_ACCOUNT_ID, listQQBotAccountIds, resolveQQBotAccount } from '../config.js';
+
+/**
+ * Onboarding adapter — 导出给 ChannelPlugin 使用
+ *
+ * 注：完整 onboarding 交互逻辑较复杂（约 300 行），
+ * 此处仅保留 adapter 骨架，完整实现从原文件迁移。
+ */
+export const qqbotOnboardingAdapter: ChannelOnboardingAdapter = {
+  getStatus: (ctx) => {
+    const cfg = ctx.config as OpenClawConfig;
+    const accountIds = listQQBotAccountIds(cfg);
+    if (accountIds.length === 0) {
+      return { configured: false, accountCount: 0 };
+    }
+    const firstAccount = resolveQQBotAccount(cfg, accountIds[0]);
+    return {
+      configured: Boolean(firstAccount.appId && firstAccount.clientSecret),
+      accountCount: accountIds.length,
+      defaultAccountId: accountIds[0],
+    };
+  },
+  configure: async (ctx) => {
+    // 完整实现需要从原 onboarding.ts 迁移交互逻辑
+    // 此处返回默认结果
+    return { success: false, message: 'Onboarding not yet migrated to new architecture' };
+  },
+};

package/src/{proactive.ts → features/proactive.ts}

@@ -1,3 +1,7 @@
+import { createPluginLogger } from "../utils/plugin-logger.js";
+
+const log = createPluginLogger({ prefix: '[proactive]' });
+
 /**
  * QQ Bot 主动发送消息模块
  * 
@@ -9,7 +13,7 @@
 
 import * as fs from "node:fs";
 import * as path from "node:path";
-import type { ResolvedQQBotAccount } from "./types.js";
+import type { ResolvedQQBotAccount } from "../types.js";
 
 // ============ 类型定义（本地） ============
 
@@ -56,14 +60,9 @@ export interface ListKnownUsersOptions {
   limit?: number;
 }
 import {
-  getAccessToken,
-  sendProactiveC2CMessage,
-  sendProactiveGroupMessage,
-  sendChannelMessage,
-  sendC2CImageMessage,
-  sendGroupImageMessage,
-} from "./api.js";
-import { resolveQQBotAccount } from "./config.js";
+  getBotForAccount,
+} from "../bot-instance.js";
+import { resolveQQBotAccount } from "../config.js";
 import type { OpenClawConfig } from "openclaw/plugin-sdk";
 
 // ============ 用户存储管理 ============
@@ -72,7 +71,7 @@ import type { OpenClawConfig } from "openclaw/plugin-sdk";
  * 已知用户存储
  * 使用简单的 JSON 文件存储，保存在 .openclaw/qqbot 目录下
  */
-import { getQQBotDataDir } from "./utils/platform.js";
+import { getQQBotDataDir } from "../utils/platform.js";
 
 const STORAGE_DIR = getQQBotDataDir("data");
 const KNOWN_USERS_FILE = path.join(STORAGE_DIR, "known-users.json");
@@ -127,7 +126,7 @@ function loadKnownUsers(): Map<string, KnownUser> {
       cacheLastModified = fs.statSync(KNOWN_USERS_FILE).mtimeMs;
     }
   } catch (err) {
-    console.error(`[qqbot:proactive] Failed to load known users: ${err}`);
+    log.error(`Failed to load known users: ${err}`);
   }
 
   knownUsersCache = users;
@@ -145,7 +144,7 @@ function saveKnownUsers(users: Map<string, KnownUser>): void {
     cacheLastModified = Date.now();
     knownUsersCache = users;
   } catch (err) {
-    console.error(`[qqbot:proactive] Failed to save known users: ${err}`);
+    log.error(`Failed to save known users: ${err}`);
   }
 }
 
@@ -170,7 +169,7 @@ export function recordKnownUser(user: Omit<KnownUser, "firstInteractionAt">): vo
   });
   
   saveKnownUsers(users);
-  console.log(`[qqbot:proactive] Recorded user: ${key}`);
+  log.info(`Recorded user: ${key}`);
 }
 
 /**
@@ -314,44 +313,29 @@ export async function sendProactive(
   }
   
   try {
-    const accessToken = await getAccessToken(account.appId, account.clientSecret);
-    
+    const bot = getBotForAccount(account.accountId);
+    const target = { scope: type as "c2c" | "group", targetId: to };
+
     // 如果有图片，先发送图片
     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}`);
+        await bot.sendImage(target, { url: imageUrl });
+        log.info(`Sent image to ${type}:${to}`);
       } catch (err) {
-        console.error(`[qqbot:proactive] Failed to send image: ${err}`);
-        // 图片发送失败不影响文本发送
+        log.error(`Failed to send image: ${err}`);
       }
     }
     
-    // 发送文本消息
-    let result: { id: string; timestamp: number | string };
-    
-    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，这里暂时不支持主动发送
+    // 发送文本消息（主动消息：无 msgId）
+    if (type === "channel") {
       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}`);
+
+    const result = await bot.sendText(target, text);
+    log.info(`Sent message to ${type}:${to}, id: ${result.id}`);
     
     return {
       success: true,
@@ -360,7 +344,7 @@ export async function sendProactive(
     };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
-    console.error(`[qqbot:proactive] Failed to send message: ${message}`);
+    log.error(`Failed to send message: ${message}`);
     
     return {
       success: false,
@@ -487,15 +471,9 @@ export async function sendProactiveMessageDirect(
   }
   
   try {
-    const accessToken = await getAccessToken(account.appId, account.clientSecret);
-    
-    let result: { id: string; timestamp: number | string };
-    
-    if (type === "c2c") {
-      result = await sendProactiveC2CMessage(accessToken, to, text);
-    } else {
-      result = await sendProactiveGroupMessage(accessToken, to, text);
-    }
+    const bot = getBotForAccount(account.accountId);
+    const target = { scope: type, targetId: to };
+    const result = await bot.sendText(target, text);
     
     return {
       success: true,
@@ -528,3 +506,44 @@ export function getKnownUsersStats(accountId?: string): {
     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;
+}