@tencent-connect/openclaw-qqbot 1.0.0-alpha.0

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/types.d.ts

@@ -0,0 +1,145 @@
+/**
+ * QQ Bot 配置类型
+ */
+export interface QQBotConfig {
+    appId: string;
+    clientSecret?: string;
+    clientSecretFile?: string;
+}
+/**
+ * 解析后的 QQ Bot 账户
+ */
+export interface ResolvedQQBotAccount {
+    accountId: string;
+    name?: string;
+    enabled: boolean;
+    appId: string;
+    clientSecret: string;
+    secretSource: "config" | "file" | "env" | "none";
+    /** 系统提示词 */
+    systemPrompt?: string;
+    /** 图床服务器公网地址 */
+    imageServerBaseUrl?: string;
+    /** 是否支持 markdown 消息（默认 true） */
+    markdownSupport: boolean;
+    config: QQBotAccountConfig;
+}
+/**
+ * QQ Bot 账户配置
+ */
+export interface QQBotAccountConfig {
+    enabled?: boolean;
+    name?: string;
+    appId?: string;
+    clientSecret?: string;
+    clientSecretFile?: string;
+    dmPolicy?: "open" | "pairing" | "allowlist";
+    allowFrom?: string[];
+    /** 系统提示词，会添加在用户消息前面 */
+    systemPrompt?: string;
+    /** 图床服务器公网地址，用于发送图片，例如 http://your-ip:18765 */
+    imageServerBaseUrl?: string;
+    /** 是否支持 markdown 消息（默认 true，设为 false 可禁用） */
+    markdownSupport?: boolean;
+    /**
+     * @deprecated 请使用 audioFormatPolicy.uploadDirectFormats
+     * 可直接上传的音频格式（不转换为 SILK），向后兼容
+     */
+    voiceDirectUploadFormats?: string[];
+    /**
+     * 音频格式策略配置
+     * 统一管理入站（STT）和出站（上传）的音频格式转换行为
+     */
+    audioFormatPolicy?: AudioFormatPolicy;
+}
+/**
+ * 音频格式策略：控制哪些格式可跳过转换
+ */
+export interface AudioFormatPolicy {
+    /**
+     * STT 模型直接支持的音频格式（入站：跳过 SILK→WAV 转换）
+     * 如果 STT 服务支持直接处理某些格式（如 silk/amr），可将其加入此列表
+     * 例如: [".silk", ".amr", ".wav", ".mp3", ".ogg"]
+     * 默认为空（所有语音都先转换为 WAV 再送 STT）
+     */
+    sttDirectFormats?: string[];
+    /**
+     * QQ 平台支持直传的音频格式（出站：跳过→SILK 转换）
+     * 默认为 [".wav", ".mp3", ".silk"]（QQ Bot API 原生支持的三种格式）
+     * 仅当需要覆盖默认值时才配置此项
+     */
+    uploadDirectFormats?: string[];
+}
+/**
+ * 富媒体附件
+ */
+export interface MessageAttachment {
+    content_type: string;
+    filename?: string;
+    height?: number;
+    width?: number;
+    size?: number;
+    url: string;
+    voice_wav_url?: string;
+}
+/**
+ * C2C 消息事件
+ */
+export interface C2CMessageEvent {
+    author: {
+        id: string;
+        union_openid: string;
+        user_openid: string;
+    };
+    content: string;
+    id: string;
+    timestamp: string;
+    message_scene?: {
+        source: string;
+    };
+    attachments?: MessageAttachment[];
+}
+/**
+ * 频道 AT 消息事件
+ */
+export interface GuildMessageEvent {
+    id: string;
+    channel_id: string;
+    guild_id: string;
+    content: string;
+    timestamp: string;
+    author: {
+        id: string;
+        username?: string;
+        bot?: boolean;
+    };
+    member?: {
+        nick?: string;
+        joined_at?: string;
+    };
+    attachments?: MessageAttachment[];
+}
+/**
+ * 群聊 AT 消息事件
+ */
+export interface GroupMessageEvent {
+    author: {
+        id: string;
+        member_openid: string;
+    };
+    content: string;
+    id: string;
+    timestamp: string;
+    group_id: string;
+    group_openid: string;
+    attachments?: MessageAttachment[];
+}
+/**
+ * WebSocket 事件负载
+ */
+export interface WSPayload {
+    op: number;
+    d?: unknown;
+    s?: number;
+    t?: string;
+}

package/dist/src/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/utils/audio-convert.d.ts

@@ -0,0 +1,73 @@
+/**
+ * 将 SILK/AMR 语音文件转换为 WAV 格式
+ *
+ * @param inputPath 输入文件路径（.amr / .silk / .slk）
+ * @param outputDir 输出目录（默认与输入文件同目录）
+ * @returns 转换后的 WAV 文件路径，失败返回 null
+ */
+export declare function convertSilkToWav(inputPath: string, outputDir?: string): Promise<{
+    wavPath: string;
+    duration: number;
+} | null>;
+/**
+ * 判断是否为语音附件（根据 content_type 或文件扩展名）
+ */
+export declare function isVoiceAttachment(att: {
+    content_type?: string;
+    filename?: string;
+}): boolean;
+/**
+ * 格式化语音时长为可读字符串
+ */
+export declare function formatDuration(durationMs: number): string;
+export declare function isAudioFile(filePath: string): boolean;
+export interface TTSConfig {
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    voice: string;
+    /** Azure OpenAI 风格：使用 api-key header 而非 Bearer token */
+    authStyle?: "bearer" | "api-key";
+    /** 附加在 URL 后的查询参数，如 Azure 的 api-version */
+    queryParams?: Record<string, string>;
+    /** 自定义速度（默认不传） */
+    speed?: number;
+}
+export declare function resolveTTSConfig(cfg: Record<string, unknown>): TTSConfig | null;
+export declare function textToSpeechPCM(text: string, ttsCfg: TTSConfig): Promise<{
+    pcmBuffer: Buffer;
+    sampleRate: number;
+}>;
+export declare function pcmToSilk(pcmBuffer: Buffer, sampleRate: number): Promise<{
+    silkBuffer: Buffer;
+    duration: number;
+}>;
+export declare function textToSilk(text: string, ttsCfg: TTSConfig, outputDir: string): Promise<{
+    silkPath: string;
+    silkBase64: string;
+    duration: number;
+}>;
+/**
+ * 将本地音频文件转换为 QQ Bot 可上传的 Base64
+ *
+ * QQ Bot API 支持直传 WAV、MP3、SILK 三种格式，其他格式仍需转换。
+ * 转换策略（参考 NapCat/go-cqhttp/Discord/Telegram 的做法）：
+ *
+ * 1. WAV / MP3 / SILK → 直传（跳过转换）
+ * 2. 有 ffmpeg → ffmpeg 万能解码为 PCM → silk-wasm 编码
+ *    支持: ogg, opus, aac, flac, wma, m4a, pcm 等所有 ffmpeg 支持的格式
+ * 3. 无 ffmpeg → WASM fallback（仅支持 pcm, wav）
+ *
+ * @param directUploadFormats - 自定义直传格式列表，覆盖默认值。传 undefined 使用 QQ_NATIVE_UPLOAD_FORMATS
+ */
+export declare function audioFileToSilkBase64(filePath: string, directUploadFormats?: string[]): Promise<string | null>;
+/**
+ * 等待文件就绪（轮询直到文件出现且大小稳定）
+ * 用于 TTS 生成后等待文件写入完成
+ *
+ * @param filePath 文件路径
+ * @param timeoutMs 最大等待时间（默认 2 分钟）
+ * @param pollMs 轮询间隔（默认 500ms）
+ * @returns 文件大小（字节），超时或文件始终为空返回 0
+ */
+export declare function waitForFile(filePath: string, timeoutMs?: number, pollMs?: number): Promise<number>;