@ryantest/openclaw-qqbot 0.0.1

package/dist/src/session-store.js

@@ -0,0 +1,254 @@
+/**
+ * Session 持久化存储
+ * 将 WebSocket 连接状态（sessionId、lastSeq）持久化到文件
+ * 支持进程重启后通过 Resume 机制快速恢复连接
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getQQBotDataDir } from "./utils/platform.js";
+// Session 文件目录
+const SESSION_DIR = getQQBotDataDir("sessions");
+// 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
+ * @param expectedAppId 当前使用的 appId，如果与保存时的 appId 不匹配则视为失效
+ * @returns Session 状态，如果不存在、已过期或 appId 不匹配返回 null
+ */
+export function loadSession(accountId, expectedAppId) {
+    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;
+        }
+        // 检查 appId 是否匹配（凭据变更检测）
+        if (expectedAppId && state.appId && state.appId !== expectedAppId) {
+            console.log(`[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) {
+            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}, appId=${state.appId ?? "unknown"}, 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;
+}

package/dist/src/slash-commands.d.ts

@@ -0,0 +1,71 @@
+/**
+ * QQBot 插件级斜杠指令处理器
+ *
+ * 设计原则：
+ * 1. 在消息入队前拦截，匹配到插件级指令后直接回复，不进入 AI 处理队列
+ * 2. 不匹配的 "/" 消息照常入队，交给 OpenClaw 框架处理
+ * 3. 每个指令通过 SlashCommand 接口注册，易于扩展
+ *
+ * 时间线追踪：
+ *   开平推送时间戳 → 插件收到(Date.now()) → 指令处理完成(Date.now())
+ *   从而计算「开平→插件」和「插件处理」两段耗时
+ */
+import type { QQBotAccountConfig } from "./types.js";
+/** 斜杠指令上下文（消息元数据 + 运行时状态） */
+export interface SlashCommandContext {
+    /** 消息类型 */
+    type: "c2c" | "guild" | "dm" | "group";
+    /** 发送者 ID */
+    senderId: string;
+    /** 发送者昵称 */
+    senderName?: string;
+    /** 消息 ID（用于被动回复） */
+    messageId: string;
+    /** 开平推送的事件时间戳（ISO 字符串） */
+    eventTimestamp: string;
+    /** 插件收到消息的本地时间（ms） */
+    receivedAt: number;
+    /** 原始消息内容 */
+    rawContent: string;
+    /** 指令参数（去掉指令名后的部分） */
+    args: string;
+    /** 频道 ID（guild 类型） */
+    channelId?: string;
+    /** 群 openid（group 类型） */
+    groupOpenid?: string;
+    /** 账号 ID */
+    accountId: string;
+    /** Bot App ID */
+    appId: string;
+    /** 账号配置（供指令读取可配置项） */
+    accountConfig?: QQBotAccountConfig;
+    /** 当前用户队列状态快照 */
+    queueSnapshot: QueueSnapshot;
+}
+/** 队列状态快照 */
+export interface QueueSnapshot {
+    /** 各用户队列中的消息总数 */
+    totalPending: number;
+    /** 正在并行处理的用户数 */
+    activeUsers: number;
+    /** 最大并发用户数 */
+    maxConcurrentUsers: number;
+    /** 当前发送者在队列中的待处理消息数 */
+    senderPending: number;
+}
+/** 斜杠指令返回值：文本、带文件的结果、或 null（不处理） */
+export type SlashCommandResult = string | SlashCommandFileResult | null;
+/** 带文件的指令结果（先回复文本，再发送文件） */
+export interface SlashCommandFileResult {
+    text: string;
+    /** 要发送的本地文件路径 */
+    filePath: string;
+}
+/**
+ * 尝试匹配并执行插件级斜杠指令
+ *
+ * @returns 回复文本（匹配成功），null（不匹配，应入队正常处理）
+ */
+export declare function matchSlashCommand(ctx: SlashCommandContext): Promise<SlashCommandResult>;
+/** 获取插件版本号（供外部使用） */
+export declare function getPluginVersion(): string;