@cxyhhhhh/openclaw-qqbot 1.6.7-alpha.1

package/dist/src/ref-index-store.js

@@ -0,0 +1,250 @@
+/**
+ * QQ Bot 引用索引持久化存储
+ *
+ * QQ Bot 使用 REFIDX_xxx 索引体系做引用消息，
+ * 入站事件只有索引值，无 API 可回查内容。
+ * 采用 内存缓存 + JSONL 追加写持久化 方案，确保重启后历史引用仍可命中。
+ *
+ * 存储位置：~/.openclaw/qqbot/data/ref-index.jsonl
+ *
+ * 每行格式：{"k":"REFIDX_xxx","v":{...},"t":1709000000}
+ * - k = refIdx 键
+ * - v = 消息数据
+ * - t = 写入时间（用于 TTL 淘汰和 compact）
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { getQQBotDataDir } from "./utils/platform.js";
+import { formatAttachmentTags } from "./group-history.js";
+// ============ 配置 ============
+const STORAGE_DIR = getQQBotDataDir("data");
+const REF_INDEX_FILE = path.join(STORAGE_DIR, "ref-index.jsonl");
+const MAX_ENTRIES = 50000; // 内存中最大缓存条目数
+const TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 天
+const COMPACT_THRESHOLD_RATIO = 2; // 文件行数超过有效条目 N 倍时 compact
+// ============ 内存缓存 ============
+let cache = null;
+let totalLinesOnDisk = 0; // 磁盘文件总行数（含过期 / 被覆盖的）
+/**
+ * 从 JSONL 文件加载到内存（懒加载，首次访问时触发）
+ */
+function loadFromFile() {
+    if (cache !== null)
+        return cache;
+    cache = new Map();
+    totalLinesOnDisk = 0;
+    try {
+        if (!fs.existsSync(REF_INDEX_FILE)) {
+            return cache;
+        }
+        const raw = fs.readFileSync(REF_INDEX_FILE, "utf-8");
+        const lines = raw.split("\n");
+        const now = Date.now();
+        let expired = 0;
+        for (const line of lines) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            totalLinesOnDisk++;
+            try {
+                const entry = JSON.parse(trimmed);
+                if (!entry.k || !entry.v || !entry.t)
+                    continue;
+                // 跳过过期条目
+                if (now - entry.t > TTL_MS) {
+                    expired++;
+                    continue;
+                }
+                cache.set(entry.k, {
+                    ...entry.v,
+                    _createdAt: entry.t,
+                });
+            }
+            catch {
+                // 跳过损坏的行
+            }
+        }
+        console.log(`[ref-index-store] Loaded ${cache.size} entries from ${totalLinesOnDisk} lines (${expired} expired)`);
+        // 启动时检查是否需要 compact
+        if (shouldCompact()) {
+            compactFile();
+        }
+    }
+    catch (err) {
+        console.error(`[ref-index-store] Failed to load: ${err}`);
+        cache = new Map();
+    }
+    return cache;
+}
+// ============ JSONL 追加写入 ============
+/**
+ * 追加一行到 JSONL 文件
+ */
+function appendLine(line) {
+    try {
+        ensureDir();
+        fs.appendFileSync(REF_INDEX_FILE, JSON.stringify(line) + "\n", "utf-8");
+        totalLinesOnDisk++;
+    }
+    catch (err) {
+        console.error(`[ref-index-store] Failed to append: ${err}`);
+    }
+}
+function ensureDir() {
+    if (!fs.existsSync(STORAGE_DIR)) {
+        fs.mkdirSync(STORAGE_DIR, { recursive: true });
+    }
+}
+// ============ Compact：重写文件，去除过期和被覆盖的条目 ============
+function shouldCompact() {
+    if (!cache)
+        return false;
+    // 文件行数远超有效条目数时 compact
+    return totalLinesOnDisk > cache.size * COMPACT_THRESHOLD_RATIO && totalLinesOnDisk > 1000;
+}
+function compactFile() {
+    if (!cache)
+        return;
+    const before = totalLinesOnDisk;
+    try {
+        ensureDir();
+        const tmpPath = REF_INDEX_FILE + ".tmp";
+        const lines = [];
+        for (const [key, entry] of cache) {
+            const line = {
+                k: key,
+                v: {
+                    content: entry.content,
+                    senderId: entry.senderId,
+                    senderName: entry.senderName,
+                    timestamp: entry.timestamp,
+                    isBot: entry.isBot,
+                    attachments: entry.attachments,
+                },
+                t: entry._createdAt,
+            };
+            lines.push(JSON.stringify(line));
+        }
+        fs.writeFileSync(tmpPath, lines.join("\n") + "\n", "utf-8");
+        fs.renameSync(tmpPath, REF_INDEX_FILE);
+        totalLinesOnDisk = cache.size;
+        console.log(`[ref-index-store] Compacted: ${before} lines → ${totalLinesOnDisk} lines`);
+    }
+    catch (err) {
+        console.error(`[ref-index-store] Compact failed: ${err}`);
+    }
+}
+// ============ 溢出淘汰 ============
+function evictIfNeeded() {
+    if (!cache || cache.size < MAX_ENTRIES)
+        return;
+    const now = Date.now();
+    // 第一轮：清理过期
+    for (const [key, entry] of cache) {
+        if (now - entry._createdAt > TTL_MS) {
+            cache.delete(key);
+        }
+    }
+    // 第二轮：仍超限，按时间删最旧
+    if (cache.size >= MAX_ENTRIES) {
+        const sorted = [...cache.entries()].sort((a, b) => a[1]._createdAt - b[1]._createdAt);
+        const toRemove = sorted.slice(0, cache.size - MAX_ENTRIES + 1000);
+        for (const [key] of toRemove) {
+            cache.delete(key);
+        }
+        console.log(`[ref-index-store] Evicted ${toRemove.length} oldest entries`);
+    }
+}
+// ============ 公共 API ============
+/**
+ * 存储一条消息的 refIdx 映射
+ */
+export function setRefIndex(refIdx, entry) {
+    const store = loadFromFile();
+    evictIfNeeded();
+    const now = Date.now();
+    store.set(refIdx, {
+        content: entry.content,
+        senderId: entry.senderId,
+        senderName: entry.senderName,
+        timestamp: entry.timestamp,
+        isBot: entry.isBot,
+        attachments: entry.attachments,
+        _createdAt: now,
+    });
+    // 追加写入 JSONL
+    appendLine({
+        k: refIdx,
+        v: {
+            content: entry.content,
+            senderId: entry.senderId,
+            senderName: entry.senderName,
+            timestamp: entry.timestamp,
+            isBot: entry.isBot,
+            attachments: entry.attachments,
+        },
+        t: now,
+    });
+    // 检查是否需要 compact
+    if (shouldCompact()) {
+        compactFile();
+    }
+}
+/**
+ * 查找被引用消息
+ */
+export function getRefIndex(refIdx) {
+    const store = loadFromFile();
+    const entry = store.get(refIdx);
+    if (!entry)
+        return null;
+    // 检查过期
+    if (Date.now() - entry._createdAt > TTL_MS) {
+        store.delete(refIdx);
+        return null;
+    }
+    return {
+        content: entry.content,
+        senderId: entry.senderId,
+        senderName: entry.senderName,
+        timestamp: entry.timestamp,
+        isBot: entry.isBot,
+        attachments: entry.attachments,
+    };
+}
+/**
+ * 将引用消息内容格式化为人类可读的描述（供 AI 上下文注入）
+ */
+export function formatRefEntryForAgent(entry) {
+    const parts = [];
+    // 文本内容
+    if (entry.content.trim()) {
+        parts.push(entry.content);
+    }
+    // 附件描述（委托 formatAttachmentTags 统一格式化）
+    const attachmentDesc = formatAttachmentTags(entry.attachments);
+    if (attachmentDesc) {
+        parts.push(attachmentDesc);
+    }
+    return parts.join(" ") || "[空消息]";
+}
+/**
+ * 进程退出前强制 compact（确保数据一致性）
+ */
+export function flushRefIndex() {
+    if (cache && shouldCompact()) {
+        compactFile();
+    }
+}
+/**
+ * 缓存统计（调试用）
+ */
+export function getRefIndexStats() {
+    const store = loadFromFile();
+    return {
+        size: store.size,
+        maxEntries: MAX_ENTRIES,
+        totalLinesOnDisk,
+        filePath: REF_INDEX_FILE,
+    };
+}

package/dist/src/reply-dispatcher.d.ts

@@ -0,0 +1,35 @@
+import type { ResolvedQQBotAccount } from "./types.js";
+export interface MessageTarget {
+    type: "c2c" | "guild" | "dm" | "group";
+    senderId: string;
+    messageId: string;
+    channelId?: string;
+    groupOpenid?: string;
+}
+export interface ReplyContext {
+    target: MessageTarget;
+    account: ResolvedQQBotAccount;
+    cfg: unknown;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+/**
+ * 带 token 过期重试的消息发送
+ */
+export declare function sendWithTokenRetry<T>(appId: string, clientSecret: string, sendFn: (token: string) => Promise<T>, log?: ReplyContext["log"], accountId?: string): Promise<T>;
+/**
+ * 根据消息类型路由发送文本
+ */
+export declare function sendTextToTarget(ctx: ReplyContext, text: string, refIdx?: string): Promise<void>;
+/**
+ * 发送错误提示给用户
+ */
+export declare function sendErrorToTarget(ctx: ReplyContext, errorText: string): Promise<void>;
+/**
+ * 处理结构化载荷（QQBOT_PAYLOAD: 前缀的 JSON）
+ * 返回 true 表示已处理，false 表示不是结构化载荷
+ */
+export declare function handleStructuredPayload(ctx: ReplyContext, replyText: string, recordActivity: () => void): Promise<boolean>;

package/dist/src/reply-dispatcher.js

@@ -0,0 +1,311 @@
+import path from "node:path";
+import { getAccessToken, sendC2CMessage, sendChannelMessage, sendGroupMessage, clearTokenCache, sendC2CImageMessage, sendGroupImageMessage, sendC2CVoiceMessage, sendGroupVoiceMessage, sendC2CVideoMessage, sendGroupVideoMessage, sendC2CFileMessage, sendGroupFileMessage } from "./api.js";
+import { parseQQBotPayload, encodePayloadForCron, isCronReminderPayload, isMediaPayload } from "./utils/payload.js";
+import { resolveTTSConfig, textToSilk, formatDuration } from "./utils/audio-convert.js";
+import { checkFileSize, readFileAsync, fileExistsAsync, formatFileSize, getMaxUploadSize } from "./utils/file-utils.js";
+import { getQQBotDataDir, normalizePath, sanitizeFileName } from "./utils/platform.js";
+/**
+ * 带 token 过期重试的消息发送
+ */
+export async function sendWithTokenRetry(appId, clientSecret, sendFn, log, accountId) {
+    try {
+        const token = await getAccessToken(appId, clientSecret);
+        return await sendFn(token);
+    }
+    catch (err) {
+        const errMsg = String(err);
+        if (errMsg.includes("401") || errMsg.includes("token") || errMsg.includes("access_token")) {
+            log?.info(`[qqbot:${accountId}] Token may be expired, refreshing...`);
+            clearTokenCache(appId);
+            const newToken = await getAccessToken(appId, clientSecret);
+            return await sendFn(newToken);
+        }
+        else {
+            throw err;
+        }
+    }
+}
+/**
+ * 根据消息类型路由发送文本
+ */
+export async function sendTextToTarget(ctx, text, refIdx) {
+    const { target, account } = ctx;
+    await sendWithTokenRetry(account.appId, account.clientSecret, async (token) => {
+        if (target.type === "c2c") {
+            await sendC2CMessage(token, target.senderId, text, target.messageId, refIdx);
+        }
+        else if (target.type === "group" && target.groupOpenid) {
+            await sendGroupMessage(token, target.groupOpenid, text, target.messageId);
+        }
+        else if (target.channelId) {
+            await sendChannelMessage(token, target.channelId, text, target.messageId);
+        }
+        else if (target.type === "dm") {
+            await sendC2CMessage(token, target.senderId, text, target.messageId, refIdx);
+        }
+    }, ctx.log, account.accountId);
+}
+/**
+ * 发送错误提示给用户
+ */
+export async function sendErrorToTarget(ctx, errorText) {
+    try {
+        await sendTextToTarget(ctx, errorText);
+    }
+    catch (sendErr) {
+        ctx.log?.error(`[qqbot:${ctx.account.accountId}] Failed to send error message: ${sendErr}`);
+    }
+}
+/**
+ * 处理结构化载荷（QQBOT_PAYLOAD: 前缀的 JSON）
+ * 返回 true 表示已处理，false 表示不是结构化载荷
+ */
+export async function handleStructuredPayload(ctx, replyText, recordActivity) {
+    const { target, account, cfg, log } = ctx;
+    const payloadResult = parseQQBotPayload(replyText);
+    if (!payloadResult.isPayload)
+        return false;
+    if (payloadResult.error) {
+        log?.error(`[qqbot:${account.accountId}] Payload parse error: ${payloadResult.error}`);
+        return true;
+    }
+    if (!payloadResult.payload)
+        return true;
+    const parsedPayload = payloadResult.payload;
+    log?.info(`[qqbot:${account.accountId}] Detected structured payload, type: ${parsedPayload.type}`);
+    if (isCronReminderPayload(parsedPayload)) {
+        log?.info(`[qqbot:${account.accountId}] Processing cron_reminder payload`);
+        const cronMessage = encodePayloadForCron(parsedPayload);
+        const confirmText = `⏰ 提醒已设置，将在指定时间发送: "${parsedPayload.content}"`;
+        try {
+            await sendTextToTarget(ctx, confirmText);
+            log?.info(`[qqbot:${account.accountId}] Cron reminder confirmation sent, cronMessage: ${cronMessage}`);
+        }
+        catch (err) {
+            log?.error(`[qqbot:${account.accountId}] Failed to send cron confirmation: ${err}`);
+        }
+        recordActivity();
+        return true;
+    }
+    if (isMediaPayload(parsedPayload)) {
+        log?.info(`[qqbot:${account.accountId}] Processing media payload, mediaType: ${parsedPayload.mediaType}`);
+        if (parsedPayload.mediaType === "image") {
+            await handleImagePayload(ctx, parsedPayload);
+        }
+        else if (parsedPayload.mediaType === "audio") {
+            await handleAudioPayload(ctx, parsedPayload);
+        }
+        else if (parsedPayload.mediaType === "video") {
+            await handleVideoPayload(ctx, parsedPayload);
+        }
+        else if (parsedPayload.mediaType === "file") {
+            await handleFilePayload(ctx, parsedPayload);
+        }
+        else {
+            log?.error(`[qqbot:${account.accountId}] Unknown media type: ${parsedPayload.mediaType}`);
+        }
+        recordActivity();
+        return true;
+    }
+    log?.error(`[qqbot:${account.accountId}] Unknown payload type: ${parsedPayload.type}`);
+    return true;
+}
+// ============ 媒体载荷处理 ============
+async function handleImagePayload(ctx, payload) {
+    const { target, account, log } = ctx;
+    let imageUrl = normalizePath(payload.path);
+    const originalImagePath = payload.source === "file" ? imageUrl : undefined;
+    if (payload.source === "file") {
+        try {
+            if (!(await fileExistsAsync(imageUrl))) {
+                log?.error(`[qqbot:${account.accountId}] Image not found: ${imageUrl}`);
+                return;
+            }
+            const imgSzCheck = checkFileSize(imageUrl, getMaxUploadSize(1)); // IMAGE = 1
+            if (!imgSzCheck.ok) {
+                log?.error(`[qqbot:${account.accountId}] Image size check failed: ${imgSzCheck.error}`);
+                return;
+            }
+            const fileBuffer = await readFileAsync(imageUrl);
+            const base64Data = fileBuffer.toString("base64");
+            const ext = path.extname(imageUrl).toLowerCase();
+            const mimeTypes = {
+                ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png",
+                ".gif": "image/gif", ".webp": "image/webp", ".bmp": "image/bmp",
+            };
+            const mimeType = mimeTypes[ext];
+            if (!mimeType) {
+                log?.error(`[qqbot:${account.accountId}] Unsupported image format: ${ext}`);
+                return;
+            }
+            imageUrl = `data:${mimeType};base64,${base64Data}`;
+            log?.info(`[qqbot:${account.accountId}] Converted local image to Base64 (size: ${formatFileSize(fileBuffer.length)})`);
+        }
+        catch (readErr) {
+            log?.error(`[qqbot:${account.accountId}] Failed to read local image: ${readErr}`);
+            return;
+        }
+    }
+    try {
+        await sendWithTokenRetry(account.appId, account.clientSecret, async (token) => {
+            if (target.type === "c2c") {
+                await sendC2CImageMessage(token, target.senderId, imageUrl, target.messageId, undefined, originalImagePath);
+            }
+            else if (target.type === "group" && target.groupOpenid) {
+                await sendGroupImageMessage(token, target.groupOpenid, imageUrl, target.messageId);
+            }
+            else if (target.channelId) {
+                await sendChannelMessage(token, target.channelId, `![](${payload.path})`, target.messageId);
+            }
+        }, log, account.accountId);
+        log?.info(`[qqbot:${account.accountId}] Sent image via media payload`);
+        if (payload.caption) {
+            await sendTextToTarget(ctx, payload.caption);
+        }
+    }
+    catch (err) {
+        log?.error(`[qqbot:${account.accountId}] Failed to send image: ${err}`);
+    }
+}
+async function handleAudioPayload(ctx, payload) {
+    const { target, account, cfg, log } = ctx;
+    try {
+        const ttsText = payload.caption || payload.path;
+        if (!ttsText?.trim()) {
+            log?.error(`[qqbot:${account.accountId}] Voice missing text`);
+        }
+        else {
+            const ttsCfg = resolveTTSConfig(cfg);
+            if (!ttsCfg) {
+                log?.error(`[qqbot:${account.accountId}] TTS not configured (channels.qqbot.tts in openclaw.json)`);
+            }
+            else {
+                log?.info(`[qqbot:${account.accountId}] TTS: "${ttsText.slice(0, 50)}..." via ${ttsCfg.model}`);
+                const ttsDir = getQQBotDataDir("tts");
+                const { silkPath, silkBase64, duration } = await textToSilk(ttsText, ttsCfg, ttsDir);
+                log?.info(`[qqbot:${account.accountId}] TTS done: ${formatDuration(duration)}, file saved: ${silkPath}`);
+                await sendWithTokenRetry(account.appId, account.clientSecret, async (token) => {
+                    if (target.type === "c2c") {
+                        await sendC2CVoiceMessage(token, target.senderId, silkBase64, target.messageId, ttsText, silkPath);
+                    }
+                    else if (target.type === "group" && target.groupOpenid) {
+                        await sendGroupVoiceMessage(token, target.groupOpenid, silkBase64, target.messageId);
+                    }
+                    else if (target.channelId) {
+                        log?.error(`[qqbot:${account.accountId}] Voice not supported in channel, sending text fallback`);
+                        await sendChannelMessage(token, target.channelId, ttsText, target.messageId);
+                    }
+                }, log, account.accountId);
+                log?.info(`[qqbot:${account.accountId}] Voice message sent`);
+            }
+        }
+    }
+    catch (err) {
+        log?.error(`[qqbot:${account.accountId}] TTS/voice send failed: ${err}`);
+    }
+}
+async function handleVideoPayload(ctx, payload) {
+    const { target, account, log } = ctx;
+    try {
+        const videoPath = normalizePath(payload.path ?? "");
+        if (!videoPath?.trim()) {
+            log?.error(`[qqbot:${account.accountId}] Video missing path`);
+        }
+        else {
+            const isHttpUrl = videoPath.startsWith("http://") || videoPath.startsWith("https://");
+            log?.info(`[qqbot:${account.accountId}] Video send: "${videoPath.slice(0, 60)}..."`);
+            await sendWithTokenRetry(account.appId, account.clientSecret, async (token) => {
+                if (isHttpUrl) {
+                    if (target.type === "c2c") {
+                        await sendC2CVideoMessage(token, target.senderId, videoPath, undefined, target.messageId);
+                    }
+                    else if (target.type === "group" && target.groupOpenid) {
+                        await sendGroupVideoMessage(token, target.groupOpenid, videoPath, undefined, target.messageId);
+                    }
+                    else if (target.channelId) {
+                        log?.error(`[qqbot:${account.accountId}] Video not supported in channel`);
+                    }
+                }
+                else {
+                    if (!(await fileExistsAsync(videoPath))) {
+                        throw new Error(`视频文件不存在: ${videoPath}`);
+                    }
+                    const vPaySzCheck = checkFileSize(videoPath, getMaxUploadSize(2)); // VIDEO = 2
+                    if (!vPaySzCheck.ok) {
+                        throw new Error(vPaySzCheck.error);
+                    }
+                    const fileBuffer = await readFileAsync(videoPath);
+                    const videoBase64 = fileBuffer.toString("base64");
+                    log?.info(`[qqbot:${account.accountId}] Read local video (${formatFileSize(fileBuffer.length)}): ${videoPath}`);
+                    if (target.type === "c2c") {
+                        await sendC2CVideoMessage(token, target.senderId, undefined, videoBase64, target.messageId, undefined, videoPath);
+                    }
+                    else if (target.type === "group" && target.groupOpenid) {
+                        await sendGroupVideoMessage(token, target.groupOpenid, undefined, videoBase64, target.messageId);
+                    }
+                    else if (target.channelId) {
+                        log?.error(`[qqbot:${account.accountId}] Video not supported in channel`);
+                    }
+                }
+            }, log, account.accountId);
+            log?.info(`[qqbot:${account.accountId}] Video message sent`);
+            if (payload.caption) {
+                await sendTextToTarget(ctx, payload.caption);
+            }
+        }
+    }
+    catch (err) {
+        log?.error(`[qqbot:${account.accountId}] Video send failed: ${err}`);
+    }
+}
+async function handleFilePayload(ctx, payload) {
+    const { target, account, log } = ctx;
+    try {
+        const filePath = normalizePath(payload.path ?? "");
+        if (!filePath?.trim()) {
+            log?.error(`[qqbot:${account.accountId}] File missing path`);
+        }
+        else {
+            const isHttpUrl = filePath.startsWith("http://") || filePath.startsWith("https://");
+            const fileName = sanitizeFileName(path.basename(filePath));
+            log?.info(`[qqbot:${account.accountId}] File send: "${filePath.slice(0, 60)}..." (${isHttpUrl ? "URL" : "local"})`);
+            await sendWithTokenRetry(account.appId, account.clientSecret, async (token) => {
+                if (isHttpUrl) {
+                    if (target.type === "c2c") {
+                        await sendC2CFileMessage(token, target.senderId, undefined, filePath, target.messageId, fileName);
+                    }
+                    else if (target.type === "group" && target.groupOpenid) {
+                        await sendGroupFileMessage(token, target.groupOpenid, undefined, filePath, target.messageId, fileName);
+                    }
+                    else if (target.channelId) {
+                        log?.error(`[qqbot:${account.accountId}] File not supported in channel`);
+                    }
+                }
+                else {
+                    if (!(await fileExistsAsync(filePath))) {
+                        throw new Error(`文件不存在: ${filePath}`);
+                    }
+                    const fPaySzCheck = checkFileSize(filePath, getMaxUploadSize(4)); // FILE = 4
+                    if (!fPaySzCheck.ok) {
+                        throw new Error(fPaySzCheck.error);
+                    }
+                    const fileBuffer = await readFileAsync(filePath);
+                    const fileBase64 = fileBuffer.toString("base64");
+                    if (target.type === "c2c") {
+                        await sendC2CFileMessage(token, target.senderId, fileBase64, undefined, target.messageId, fileName, filePath);
+                    }
+                    else if (target.type === "group" && target.groupOpenid) {
+                        await sendGroupFileMessage(token, target.groupOpenid, fileBase64, undefined, target.messageId, fileName);
+                    }
+                    else if (target.channelId) {
+                        log?.error(`[qqbot:${account.accountId}] File not supported in channel`);
+                    }
+                }
+            }, log, account.accountId);
+            log?.info(`[qqbot:${account.accountId}] File message sent`);
+        }
+    }
+    catch (err) {
+        log?.error(`[qqbot:${account.accountId}] File send failed: ${err}`);
+    }
+}

package/dist/src/request-context.d.ts

@@ -0,0 +1,18 @@
+export interface RequestContext {
+    /** 投递目标地址，如 qqbot:c2c:xxx 或 qqbot:group:xxx */
+    target: string;
+}
+/**
+ * 在请求级作用域中执行回调。
+ * 作用域内所有同步/异步代码都能通过 getRequestContext() 获取上下文。
+ */
+export declare function runWithRequestContext<T>(ctx: RequestContext, fn: () => T): T;
+/**
+ * 获取当前请求的上下文，不存在时返回 undefined。
+ */
+export declare function getRequestContext(): RequestContext | undefined;
+/**
+ * 获取当前请求的投递目标地址。
+ * 便捷方法，等价于 getRequestContext()?.target。
+ */
+export declare function getRequestTarget(): string | undefined;

package/dist/src/request-context.js

@@ -0,0 +1,30 @@
+/**
+ * 请求级上下文（基于 AsyncLocalStorage）
+ *
+ * 解决并发消息下工具获取当前会话信息的竞态问题。
+ * gateway 在处理每条入站消息时通过 runWithRequestContext() 建立作用域，
+ * 作用域内的所有异步代码（包括 AI agent 调用、tool execute）
+ * 都能通过 getRequestContext() 安全地拿到当前请求的上下文。
+ */
+import { AsyncLocalStorage } from "node:async_hooks";
+const asyncLocalStorage = new AsyncLocalStorage();
+/**
+ * 在请求级作用域中执行回调。
+ * 作用域内所有同步/异步代码都能通过 getRequestContext() 获取上下文。
+ */
+export function runWithRequestContext(ctx, fn) {
+    return asyncLocalStorage.run(ctx, fn);
+}
+/**
+ * 获取当前请求的上下文，不存在时返回 undefined。
+ */
+export function getRequestContext() {
+    return asyncLocalStorage.getStore();
+}
+/**
+ * 获取当前请求的投递目标地址。
+ * 便捷方法，等价于 getRequestContext()?.target。
+ */
+export function getRequestTarget() {
+    return asyncLocalStorage.getStore()?.target;
+}

package/dist/src/runtime.d.ts

@@ -0,0 +1,3 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+export declare function setQQBotRuntime(next: PluginRuntime): void;
+export declare function getQQBotRuntime(): PluginRuntime;

package/dist/src/runtime.js

@@ -0,0 +1,10 @@
+let runtime = null;
+export function setQQBotRuntime(next) {
+    runtime = next;
+}
+export function getQQBotRuntime() {
+    if (!runtime) {
+        throw new Error("QQBot runtime not initialized");
+    }
+    return runtime;
+}