@openclaw/qqbot 2026.5.1-beta.1

package/src/engine/session/known-users.ts

@@ -0,0 +1,254 @@
+/**
+ * Known user tracking — JSON file-based store.
+ *
+ * Migrated from src/known-users.ts. Dependencies are only Node.js
+ * built-ins + log + platform (both zero plugin-sdk).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import type { ChatScope } from "../types.js";
+import { formatErrorMessage } from "../utils/format.js";
+import { debugLog, debugError } from "../utils/log.js";
+import { getQQBotDataDir, getQQBotDataPath } from "../utils/platform.js";
+
+/** Persisted record for a user who has interacted with the bot. */
+export interface KnownUser {
+  openid: string;
+  type: ChatScope;
+  nickname?: string;
+  groupOpenid?: string;
+  accountId: string;
+  firstSeenAt: number;
+  lastSeenAt: number;
+  interactionCount: number;
+}
+
+let usersCache: Map<string, KnownUser> | null = null;
+const SAVE_THROTTLE_MS = 5000;
+let saveTimer: ReturnType<typeof setTimeout> | null = null;
+let isDirty = false;
+
+function ensureDir(): void {
+  getQQBotDataDir("data");
+}
+
+function getKnownUsersFile(): string {
+  return path.join(getQQBotDataPath("data"), "known-users.json");
+}
+
+function makeUserKey(user: Partial<KnownUser>): string {
+  const base = `${user.accountId}:${user.type}:${user.openid}`;
+  return user.type === "group" && user.groupOpenid ? `${base}:${user.groupOpenid}` : base;
+}
+
+function loadUsersFromFile(): Map<string, KnownUser> {
+  if (usersCache !== null) {
+    return usersCache;
+  }
+  usersCache = new Map();
+  try {
+    const knownUsersFile = getKnownUsersFile();
+    if (fs.existsSync(knownUsersFile)) {
+      const data = fs.readFileSync(knownUsersFile, "utf-8");
+      const users = JSON.parse(data) as KnownUser[];
+      for (const user of users) {
+        usersCache.set(makeUserKey(user), user);
+      }
+      debugLog(`[known-users] Loaded ${usersCache.size} users`);
+    }
+  } catch (err) {
+    debugError(`[known-users] Failed to load users: ${formatErrorMessage(err)}`);
+    usersCache = new Map();
+  }
+  return usersCache;
+}
+
+function saveUsersToFile(): void {
+  if (!isDirty || saveTimer) {
+    return;
+  }
+  saveTimer = setTimeout(() => {
+    saveTimer = null;
+    doSaveUsersToFile();
+  }, SAVE_THROTTLE_MS);
+}
+
+function doSaveUsersToFile(): void {
+  if (!usersCache || !isDirty) {
+    return;
+  }
+  try {
+    ensureDir();
+    fs.writeFileSync(
+      getKnownUsersFile(),
+      JSON.stringify(Array.from(usersCache.values()), null, 2),
+      "utf-8",
+    );
+    isDirty = false;
+  } catch (err) {
+    debugError(`[known-users] Failed to save users: ${formatErrorMessage(err)}`);
+  }
+}
+
+/** Flush pending writes immediately, typically during shutdown. */
+export function flushKnownUsers(): void {
+  if (saveTimer) {
+    clearTimeout(saveTimer);
+    saveTimer = null;
+  }
+  doSaveUsersToFile();
+}
+
+/** Record a known user whenever a message is received. */
+export function recordKnownUser(user: {
+  openid: string;
+  type: ChatScope;
+  nickname?: string;
+  groupOpenid?: string;
+  accountId: string;
+}): void {
+  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;
+    }
+  } else {
+    cache.set(key, {
+      openid: user.openid,
+      type: user.type,
+      nickname: user.nickname,
+      groupOpenid: user.groupOpenid,
+      accountId: user.accountId,
+      firstSeenAt: now,
+      lastSeenAt: now,
+      interactionCount: 1,
+    });
+    debugLog(`[known-users] New user: ${user.openid} (${user.type})`);
+  }
+  isDirty = true;
+  saveUsersToFile();
+}
+
+/** Look up one known user. */
+export function getKnownUser(
+  accountId: string,
+  openid: string,
+  type: ChatScope = "c2c",
+  groupOpenid?: string,
+): KnownUser | undefined {
+  return loadUsersFromFile().get(makeUserKey({ accountId, openid, type, groupOpenid }));
+}
+
+/** List known users with optional filtering and sorting. */
+export function listKnownUsers(options?: {
+  accountId?: string;
+  type?: ChatScope;
+  activeWithin?: number;
+  limit?: number;
+  sortBy?: "lastSeenAt" | "firstSeenAt" | "interactionCount";
+  sortOrder?: "asc" | "desc";
+}): KnownUser[] {
+  let users = Array.from(loadUsersFromFile().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 aV = a[sortBy] ?? 0;
+    const bV = b[sortBy] ?? 0;
+    return sortOrder === "asc" ? aV - bV : bV - aV;
+  });
+  if (options?.limit && options.limit > 0) {
+    users = users.slice(0, options.limit);
+  }
+  return users;
+}
+
+/** Return summary stats for known users. */
+export function getKnownUsersStats(accountId?: string): {
+  totalUsers: number;
+  c2cUsers: number;
+  groupUsers: number;
+  activeIn24h: number;
+  activeIn7d: number;
+} {
+  const users = listKnownUsers({ accountId });
+  const now = Date.now();
+  const day = 86400000;
+  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,
+  };
+}
+
+/** Remove one user record. */
+export function removeKnownUser(
+  accountId: string,
+  openid: string,
+  type: ChatScope = "c2c",
+  groupOpenid?: string,
+): boolean {
+  const cache = loadUsersFromFile();
+  const key = makeUserKey({ accountId, openid, type, groupOpenid });
+  if (cache.has(key)) {
+    cache.delete(key);
+    isDirty = true;
+    saveUsersToFile();
+    debugLog(`[known-users] Removed user ${openid}`);
+    return true;
+  }
+  return false;
+}
+
+/** Clear all user records, optionally scoped to one account. */
+export function clearKnownUsers(accountId?: string): number {
+  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();
+    debugLog(`[known-users] Cleared ${count} users`);
+  }
+  return count;
+}
+
+/** Return all groups in which a user has interacted. */
+export function getUserGroups(accountId: string, openid: string): string[] {
+  return listKnownUsers({ accountId, type: "group" })
+    .filter((u) => u.openid === openid && u.groupOpenid)
+    .map((u) => u.groupOpenid!);
+}
+
+/** Return all recorded members for one group. */
+export function getGroupMembers(accountId: string, groupOpenid: string): KnownUser[] {
+  return listKnownUsers({ accountId, type: "group" }).filter((u) => u.groupOpenid === groupOpenid);
+}

package/src/engine/session/session-store.ts

@@ -0,0 +1,284 @@
+/**
+ * Gateway session persistence — JSONL file-based store.
+ *
+ * Migrated from src/session-store.ts. Dependencies are only Node.js
+ * built-ins + log + platform (both zero plugin-sdk).
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { formatErrorMessage } from "../utils/format.js";
+import { debugLog, debugError } from "../utils/log.js";
+import { getQQBotDataDir, getQQBotDataPath } from "../utils/platform.js";
+
+/** Persisted gateway session state. */
+export interface SessionState {
+  sessionId: string | null;
+  lastSeq: number | null;
+  lastConnectedAt: number;
+  intentLevelIndex: number;
+  accountId: string;
+  savedAt: number;
+  appId?: string;
+}
+
+const SESSION_EXPIRE_TIME = 5 * 60 * 1000;
+const SAVE_THROTTLE_MS = 1000;
+
+const throttleState = new Map<
+  string,
+  {
+    pendingState: SessionState | null;
+    lastSaveTime: number;
+    throttleTimer: ReturnType<typeof setTimeout> | null;
+  }
+>();
+
+function ensureDir(): void {
+  getQQBotDataDir("sessions");
+}
+
+function getSessionDir(): string {
+  return getQQBotDataPath("sessions");
+}
+
+function encodeAccountIdForFileName(accountId: string): string {
+  return Buffer.from(accountId, "utf8").toString("base64url");
+}
+
+function getLegacySessionPath(accountId: string): string {
+  const safeId = accountId.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return path.join(getSessionDir(), `session-${safeId}.json`);
+}
+
+function getSessionPath(accountId: string): string {
+  const encodedId = encodeAccountIdForFileName(accountId);
+  return path.join(getSessionDir(), `session-${encodedId}.json`);
+}
+
+function getCandidateSessionPaths(accountId: string): string[] {
+  const primaryPath = getSessionPath(accountId);
+  const legacyPath = getLegacySessionPath(accountId);
+  return primaryPath === legacyPath ? [primaryPath] : [primaryPath, legacyPath];
+}
+
+function isSessionFileName(file: string): boolean {
+  return file.startsWith("session-") && file.endsWith(".json");
+}
+
+function readSessionStateFile(file: string): { filePath: string; state: SessionState } {
+  const filePath = path.join(getSessionDir(), file);
+  const data = fs.readFileSync(filePath, "utf-8");
+  return { filePath, state: JSON.parse(data) as SessionState };
+}
+
+/** Load a saved session, rejecting expired or mismatched appId entries. */
+export function loadSession(accountId: string, expectedAppId?: string): SessionState | null {
+  try {
+    let filePath: string | null = null;
+    for (const candidatePath of getCandidateSessionPaths(accountId)) {
+      if (fs.existsSync(candidatePath)) {
+        filePath = candidatePath;
+        break;
+      }
+    }
+    if (!filePath) {
+      return null;
+    }
+
+    const data = fs.readFileSync(filePath, "utf-8");
+    const state = JSON.parse(data) as SessionState;
+    const now = Date.now();
+
+    if (now - state.savedAt > SESSION_EXPIRE_TIME) {
+      debugLog(
+        `[session-store] Session expired for ${accountId}, age: ${Math.round((now - state.savedAt) / 1000)}s`,
+      );
+      try {
+        fs.unlinkSync(filePath);
+      } catch {}
+      return null;
+    }
+
+    if (expectedAppId && state.appId && state.appId !== expectedAppId) {
+      debugLog(
+        `[session-store] appId mismatch for ${accountId}: saved=${state.appId}, current=${expectedAppId}. Discarding stale session.`,
+      );
+      try {
+        fs.unlinkSync(filePath);
+      } catch {}
+      return null;
+    }
+
+    if (!state.sessionId || state.lastSeq === null || state.lastSeq === undefined) {
+      debugLog(`[session-store] Invalid session data for ${accountId}`);
+      return null;
+    }
+
+    debugLog(
+      `[session-store] Loaded session for ${accountId}: sessionId=${state.sessionId}, lastSeq=${state.lastSeq}, appId=${state.appId ?? "unknown"}, age=${Math.round((now - state.savedAt) / 1000)}s`,
+    );
+    return state;
+  } catch (err) {
+    debugError(
+      `[session-store] Failed to load session for ${accountId}: ${formatErrorMessage(err)}`,
+    );
+    return null;
+  }
+}
+
+/** Save session state with throttling. */
+export function saveSession(state: SessionState): void {
+  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?.pendingState) {
+          doSaveSession(t.pendingState);
+          t.lastSaveTime = Date.now();
+          t.pendingState = null;
+        }
+        if (t) {
+          t.throttleTimer = null;
+        }
+      }, delay);
+    }
+  }
+}
+
+function doSaveSession(state: SessionState): void {
+  const filePath = getSessionPath(state.accountId);
+  const legacyPath = getLegacySessionPath(state.accountId);
+  try {
+    ensureDir();
+    const stateToSave: SessionState = { ...state, savedAt: Date.now() };
+    fs.writeFileSync(filePath, JSON.stringify(stateToSave, null, 2), "utf-8");
+    if (legacyPath !== filePath && fs.existsSync(legacyPath)) {
+      fs.unlinkSync(legacyPath);
+    }
+    debugLog(
+      `[session-store] Saved session for ${state.accountId}: sessionId=${state.sessionId}, lastSeq=${state.lastSeq}`,
+    );
+  } catch (err) {
+    debugError(
+      `[session-store] Failed to save session for ${state.accountId}: ${formatErrorMessage(err)}`,
+    );
+  }
+}
+
+/** Clear a saved session and any pending throttle state. */
+export function clearSession(accountId: string): void {
+  const throttle = throttleState.get(accountId);
+  if (throttle) {
+    if (throttle.throttleTimer) {
+      clearTimeout(throttle.throttleTimer);
+    }
+    throttleState.delete(accountId);
+  }
+  try {
+    let cleared = false;
+    for (const filePath of getCandidateSessionPaths(accountId)) {
+      if (fs.existsSync(filePath)) {
+        fs.unlinkSync(filePath);
+        cleared = true;
+      }
+    }
+    if (cleared) {
+      debugLog(`[session-store] Cleared session for ${accountId}`);
+    }
+  } catch (err) {
+    debugError(
+      `[session-store] Failed to clear session for ${accountId}: ${formatErrorMessage(err)}`,
+    );
+  }
+}
+
+/** Update only lastSeq on the persisted session. */
+export function updateLastSeq(accountId: string, lastSeq: number): void {
+  const existing = loadSession(accountId);
+  if (existing?.sessionId) {
+    saveSession({ ...existing, lastSeq });
+  }
+}
+
+/** Load all saved sessions from disk. */
+export function getAllSessions(): SessionState[] {
+  const sessions = new Map<string, SessionState>();
+  try {
+    const sessionDir = getSessionDir();
+    if (!fs.existsSync(sessionDir)) {
+      return [];
+    }
+    const files = fs.readdirSync(sessionDir);
+
+    for (const file of files) {
+      if (isSessionFileName(file)) {
+        try {
+          const { state } = readSessionStateFile(file);
+          if (typeof state.accountId !== "string" || !state.accountId) {
+            continue;
+          }
+          const existing = sessions.get(state.accountId);
+          if (!existing || (state.savedAt ?? 0) >= (existing.savedAt ?? 0)) {
+            sessions.set(state.accountId, state);
+          }
+        } catch {}
+      }
+    }
+  } catch {}
+  return [...sessions.values()];
+}
+
+/** Remove expired session files from disk. */
+export function cleanupExpiredSessions(): number {
+  let cleaned = 0;
+  try {
+    const sessionDir = getSessionDir();
+    if (!fs.existsSync(sessionDir)) {
+      return 0;
+    }
+    const now = Date.now();
+    const files = fs.readdirSync(sessionDir);
+
+    for (const file of files) {
+      if (isSessionFileName(file)) {
+        const filePath = path.join(sessionDir, file);
+        try {
+          const { state } = readSessionStateFile(file);
+
+          if (now - state.savedAt > SESSION_EXPIRE_TIME) {
+            fs.unlinkSync(filePath);
+            cleaned++;
+            debugLog(`[session-store] Cleaned expired session: ${file}`);
+          }
+        } catch {
+          try {
+            fs.unlinkSync(filePath);
+            cleaned++;
+          } catch {}
+        }
+      }
+    }
+  } catch {}
+  return cleaned;
+}