@cxyhhhhh/openclaw-qqbot 1.6.7-alpha.1

package/dist/src/outbound-deliver.d.ts

@@ -0,0 +1,48 @@
+/**
+ * 出站消息投递模块
+ *
+ * 从 gateway deliver 回调中提取的两大发送管线：
+ * 1. parseAndSendMediaTags — 解析 <qqimg/qqvoice/qqvideo/qqfile/qqmedia> 标签并按顺序发送
+ * 2. sendPlainReply — 处理不含媒体标签的普通回复（markdown 图片/纯文本+图片）
+ */
+import type { ResolvedQQBotAccount } from "./types.js";
+export interface DeliverEventContext {
+    type: "c2c" | "guild" | "dm" | "group";
+    senderId: string;
+    messageId: string;
+    channelId?: string;
+    groupOpenid?: string;
+    msgIdx?: string;
+}
+export interface DeliverAccountContext {
+    account: ResolvedQQBotAccount;
+    qualifiedTarget: string;
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+/** token 重试包装 */
+export type SendWithRetryFn = <T>(sendFn: (token: string) => Promise<T>) => Promise<T>;
+/** 一次性消费引用 ref */
+export type ConsumeQuoteRefFn = () => string | undefined;
+/**
+ * 解析回复文本中的媒体标签并按顺序发送。
+ *
+ * @returns true 如果检测到媒体标签并已处理；false 表示无媒体标签，调用方继续走普通文本管线
+ */
+export declare function parseAndSendMediaTags(replyText: string, event: DeliverEventContext, actx: DeliverAccountContext, sendWithRetry: SendWithRetryFn, consumeQuoteRef: ConsumeQuoteRefFn): Promise<{
+    handled: boolean;
+    normalizedText: string;
+}>;
+export interface PlainReplyPayload {
+    text?: string;
+    mediaUrls?: string[];
+    mediaUrl?: string;
+}
+/**
+ * 发送不含媒体标签的普通回复。
+ * 处理 markdown 图片嵌入、Base64 富媒体、纯文本分块、本地媒体自动路由。
+ */
+export declare function sendPlainReply(payload: PlainReplyPayload, replyText: string, event: DeliverEventContext, actx: DeliverAccountContext, sendWithRetry: SendWithRetryFn, consumeQuoteRef: ConsumeQuoteRefFn, toolMediaUrls: string[]): Promise<void>;

package/dist/src/outbound-deliver.js

@@ -0,0 +1,392 @@
+/**
+ * 出站消息投递模块
+ *
+ * 从 gateway deliver 回调中提取的两大发送管线：
+ * 1. parseAndSendMediaTags — 解析 <qqimg/qqvoice/qqvideo/qqfile/qqmedia> 标签并按顺序发送
+ * 2. sendPlainReply — 处理不含媒体标签的普通回复（markdown 图片/纯文本+图片）
+ */
+import { sendC2CMessage, sendGroupMessage, sendChannelMessage, sendC2CImageMessage, sendGroupImageMessage } from "./api.js";
+import { sendPhoto, sendMedia as sendMediaAuto } from "./outbound.js";
+import { chunkText, TEXT_CHUNK_LIMIT } from "./channel.js";
+import { getQQBotRuntime } from "./runtime.js";
+import { getImageSize, formatQQBotMarkdownImage, hasQQBotImageSize } from "./utils/image-size.js";
+import { parseMediaTagsToSendQueue, executeSendQueue } from "./utils/media-send.js";
+import { isLocalPath as isLocalFilePath } from "./utils/platform.js";
+import { filterInternalMarkers } from "./utils/text-parsing.js";
+// ============ 1. 媒体标签解析 + 发送 ============
+/**
+ * 解析回复文本中的媒体标签并按顺序发送。
+ *
+ * @returns true 如果检测到媒体标签并已处理；false 表示无媒体标签，调用方继续走普通文本管线
+ */
+export async function parseAndSendMediaTags(replyText, event, actx, sendWithRetry, consumeQuoteRef) {
+    const { account, log } = actx;
+    const prefix = `[qqbot:${account.accountId}]`;
+    // 使用 media-send.ts 的统一解析器（内含 normalizeMediaTags + 路径编码修复）
+    const { hasMediaTags: hasMedia, sendQueue } = parseMediaTagsToSendQueue(replyText, log);
+    if (!hasMedia || sendQueue.length === 0) {
+        return { handled: false, normalizedText: replyText };
+    }
+    log?.info(`${prefix} Send queue: ${sendQueue.map(item => item.type).join(" -> ")}`);
+    // 构建统一的媒体发送上下文
+    const mediaTarget = {
+        targetType: event.type === "c2c" ? "c2c" : event.type === "group" ? "group" : "channel",
+        targetId: event.type === "c2c" ? event.senderId : event.type === "group" ? event.groupOpenid : event.channelId,
+        account,
+        replyToId: event.messageId,
+        logPrefix: prefix,
+    };
+    const mediaSendCtx = {
+        mediaTarget,
+        qualifiedTarget: actx.qualifiedTarget,
+        account,
+        replyToId: event.messageId,
+        log,
+    };
+    // 使用 media-send.ts 的统一执行器
+    await executeSendQueue(sendQueue, mediaSendCtx, {
+        onSendText: async (textContent) => {
+            await sendTextChunks(filterInternalMarkers(textContent), event, actx, sendWithRetry, consumeQuoteRef);
+        },
+    });
+    return { handled: true, normalizedText: replyText };
+}
+/**
+ * 发送不含媒体标签的普通回复。
+ * 处理 markdown 图片嵌入、Base64 富媒体、纯文本分块、本地媒体自动路由。
+ */
+export async function sendPlainReply(payload, replyText, event, actx, sendWithRetry, consumeQuoteRef, toolMediaUrls) {
+    const { account, qualifiedTarget, log } = actx;
+    const prefix = `[qqbot:${account.accountId}]`;
+    // 预去重：把 payload 自带的媒体 URL 从 toolMediaUrls 中移除，
+    // 防止同一个文件既被 payload.mediaUrl/mediaUrls 发送，又被 toolMediaUrls 重复发送
+    if (toolMediaUrls.length > 0) {
+        const payloadUrls = new Set();
+        if (payload.mediaUrl)
+            payloadUrls.add(payload.mediaUrl);
+        if (payload.mediaUrls)
+            for (const u of payload.mediaUrls)
+                payloadUrls.add(u);
+        if (payloadUrls.size > 0) {
+            const before = toolMediaUrls.length;
+            const filtered = toolMediaUrls.filter(url => !payloadUrls.has(url));
+            if (filtered.length < before) {
+                log?.info(`${prefix} Pre-dedup: removed ${before - filtered.length} payload media URL(s) from toolMediaUrls`);
+                toolMediaUrls.length = 0;
+                toolMediaUrls.push(...filtered);
+            }
+        }
+    }
+    const collectedImageUrls = [];
+    const localMediaToSend = [];
+    const collectImageUrl = (url) => {
+        if (!url)
+            return false;
+        const isHttpUrl = url.startsWith("http://") || url.startsWith("https://");
+        const isDataUrl = url.startsWith("data:image/");
+        if (isHttpUrl || isDataUrl) {
+            if (!collectedImageUrls.includes(url)) {
+                collectedImageUrls.push(url);
+                log?.info(`${prefix} Collected ${isDataUrl ? "Base64" : "media URL"}: ${isDataUrl ? `(length: ${url.length})` : url.slice(0, 80) + "..."}`);
+            }
+            return true;
+        }
+        if (isLocalFilePath(url)) {
+            if (!localMediaToSend.includes(url)) {
+                localMediaToSend.push(url);
+                log?.info(`${prefix} Collected local media for auto-routing: ${url}`);
+            }
+            return true;
+        }
+        return false;
+    };
+    if (payload.mediaUrls?.length) {
+        for (const url of payload.mediaUrls)
+            collectImageUrl(url);
+    }
+    if (payload.mediaUrl)
+        collectImageUrl(payload.mediaUrl);
+    // 提取 markdown 图片
+    const mdImageRegex = /!\[([^\]]*)\]\(([^)]+)\)/gi;
+    const mdMatches = [...replyText.matchAll(mdImageRegex)];
+    for (const m of mdMatches) {
+        const url = m[2]?.trim();
+        if (url && !collectedImageUrls.includes(url)) {
+            if (url.startsWith("http://") || url.startsWith("https://")) {
+                collectedImageUrls.push(url);
+                log?.info(`${prefix} Extracted HTTP image from markdown: ${url.slice(0, 80)}...`);
+            }
+            else if (isLocalFilePath(url)) {
+                if (!localMediaToSend.includes(url)) {
+                    localMediaToSend.push(url);
+                    log?.info(`${prefix} Collected local media from markdown for auto-routing: ${url}`);
+                }
+            }
+        }
+    }
+    // 提取裸 URL 图片
+    const bareUrlRegex = /(?<![(\["'])(https?:\/\/[^\s)"'<>]+\.(?:png|jpg|jpeg|gif|webp)(?:\?[^\s"'<>]*)?)/gi;
+    const bareUrlMatches = [...replyText.matchAll(bareUrlRegex)];
+    for (const m of bareUrlMatches) {
+        const url = m[1];
+        if (url && !collectedImageUrls.includes(url)) {
+            collectedImageUrls.push(url);
+            log?.info(`${prefix} Extracted bare image URL: ${url.slice(0, 80)}...`);
+        }
+    }
+    const useMarkdown = account.markdownSupport === true;
+    log?.info(`${prefix} Markdown mode: ${useMarkdown}, images: ${collectedImageUrls.length}`);
+    let textWithoutImages = filterInternalMarkers(replyText);
+    if (useMarkdown) {
+        await sendMarkdownReply(textWithoutImages, collectedImageUrls, mdMatches, bareUrlMatches, event, actx, sendWithRetry, consumeQuoteRef);
+    }
+    else {
+        await sendPlainTextReply(textWithoutImages, collectedImageUrls, mdMatches, bareUrlMatches, event, actx, sendWithRetry, consumeQuoteRef);
+    }
+    // 发送本地媒体（由 payload.mediaUrl 或 markdown 本地路径触发）
+    if (localMediaToSend.length > 0) {
+        log?.info(`${prefix} Sending ${localMediaToSend.length} local media via sendMedia auto-routing`);
+        for (const mediaPath of localMediaToSend) {
+            try {
+                const result = await sendMediaAuto({
+                    to: qualifiedTarget, text: "", mediaUrl: mediaPath,
+                    accountId: account.accountId, replyToId: event.messageId, account,
+                });
+                if (result.error) {
+                    log?.error(`${prefix} sendMedia(auto) error for ${mediaPath}: ${result.error}`);
+                    await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+                }
+                else {
+                    log?.info(`${prefix} Sent local media: ${mediaPath}`);
+                }
+            }
+            catch (err) {
+                log?.error(`${prefix} sendMedia(auto) failed for ${mediaPath}: ${err}`);
+                await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+            }
+        }
+    }
+    // 转发 tool 阶段收集的媒体（去重：跳过已在 localMediaToSend 或 collectedImageUrls 中发送过的路径）
+    if (toolMediaUrls.length > 0) {
+        const alreadySent = new Set([...localMediaToSend, ...collectedImageUrls]);
+        const dedupedToolMedia = toolMediaUrls.filter(url => !alreadySent.has(url));
+        if (dedupedToolMedia.length < toolMediaUrls.length) {
+            log?.info(`${prefix} Deduped tool media: ${toolMediaUrls.length} → ${dedupedToolMedia.length} (skipped ${toolMediaUrls.length - dedupedToolMedia.length} already sent via localMedia/collectedImages)`);
+        }
+        if (dedupedToolMedia.length > 0) {
+            log?.info(`${prefix} Forwarding ${dedupedToolMedia.length} tool-collected media URL(s) after block deliver`);
+            for (const mediaUrl of dedupedToolMedia) {
+                try {
+                    const result = await sendMediaAuto({
+                        to: qualifiedTarget, text: "", mediaUrl,
+                        accountId: account.accountId, replyToId: event.messageId, account,
+                    });
+                    if (result.error) {
+                        log?.error(`${prefix} Tool media forward error: ${result.error}`);
+                        await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+                    }
+                    else {
+                        log?.info(`${prefix} Forwarded tool media: ${mediaUrl.slice(0, 80)}...`);
+                    }
+                }
+                catch (err) {
+                    log?.error(`${prefix} Tool media forward failed: ${err}`);
+                    await sendTextChunks("发送失败，请稍后重试。", event, actx, sendWithRetry, consumeQuoteRef);
+                }
+            }
+        }
+        toolMediaUrls.length = 0;
+    }
+}
+// ============ 内部辅助函数 ============
+/** 发送文本分块（共用逻辑） */
+async function sendTextChunks(text, event, actx, sendWithRetry, consumeQuoteRef) {
+    const { account, log } = actx;
+    const prefix = `[qqbot:${account.accountId}]`;
+    const chunks = getQQBotRuntime().channel.text.chunkMarkdownText(text, TEXT_CHUNK_LIMIT);
+    for (const chunk of chunks) {
+        try {
+            await sendWithRetry(async (token) => {
+                const ref = consumeQuoteRef();
+                if (event.type === "c2c") {
+                    return await sendC2CMessage(token, event.senderId, chunk, event.messageId, ref);
+                }
+                else if (event.type === "group" && event.groupOpenid) {
+                    return await sendGroupMessage(token, event.groupOpenid, chunk, event.messageId);
+                }
+                else if (event.channelId) {
+                    return await sendChannelMessage(token, event.channelId, chunk, event.messageId);
+                }
+            });
+            log?.info(`${prefix} Sent text chunk (${chunk.length}/${text.length} chars): ${chunk.slice(0, 50)}...`);
+        }
+        catch (err) {
+            log?.error(`${prefix} Failed to send text chunk: ${err}`);
+        }
+    }
+}
+/** Markdown 模式发送 */
+async function sendMarkdownReply(textWithoutImages, imageUrls, mdMatches, bareUrlMatches, event, actx, sendWithRetry, consumeQuoteRef) {
+    const { account, log } = actx;
+    const prefix = `[qqbot:${account.accountId}]`;
+    // 分离图片：公网 URL vs Base64
+    const httpImageUrls = [];
+    const base64ImageUrls = [];
+    for (const url of imageUrls) {
+        if (url.startsWith("data:image/"))
+            base64ImageUrls.push(url);
+        else if (url.startsWith("http://") || url.startsWith("https://"))
+            httpImageUrls.push(url);
+    }
+    log?.info(`${prefix} Image classification: httpUrls=${httpImageUrls.length}, base64=${base64ImageUrls.length}`);
+    // 发送 Base64 图片
+    if (base64ImageUrls.length > 0) {
+        log?.info(`${prefix} Sending ${base64ImageUrls.length} image(s) via Rich Media API...`);
+        for (const imageUrl of base64ImageUrls) {
+            try {
+                await sendWithRetry(async (token) => {
+                    if (event.type === "c2c") {
+                        await sendC2CImageMessage(token, event.senderId, imageUrl, event.messageId);
+                    }
+                    else if (event.type === "group" && event.groupOpenid) {
+                        await sendGroupImageMessage(token, event.groupOpenid, imageUrl, event.messageId);
+                    }
+                    else if (event.channelId) {
+                        log?.info(`${prefix} Channel does not support rich media, skipping Base64 image`);
+                    }
+                });
+                log?.info(`${prefix} Sent Base64 image via Rich Media API (size: ${imageUrl.length} chars)`);
+            }
+            catch (imgErr) {
+                log?.error(`${prefix} Failed to send Base64 image via Rich Media API: ${imgErr}`);
+            }
+        }
+    }
+    // 处理公网 URL 图片
+    const existingMdUrls = new Set(mdMatches.map((m) => m[2]));
+    const imagesToAppend = [];
+    for (const url of httpImageUrls) {
+        if (!existingMdUrls.has(url)) {
+            try {
+                const size = await getImageSize(url);
+                imagesToAppend.push(formatQQBotMarkdownImage(url, size));
+                log?.info(`${prefix} Formatted HTTP image: ${size ? `${size.width}x${size.height}` : "default size"} - ${url.slice(0, 60)}...`);
+            }
+            catch (err) {
+                log?.info(`${prefix} Failed to get image size, using default: ${err}`);
+                imagesToAppend.push(formatQQBotMarkdownImage(url, null));
+            }
+        }
+    }
+    // 补充已有 markdown 图片的尺寸信息
+    let result = textWithoutImages;
+    for (const m of mdMatches) {
+        const fullMatch = m[0];
+        const imgUrl = m[2];
+        const isHttpUrl = imgUrl.startsWith("http://") || imgUrl.startsWith("https://");
+        if (isHttpUrl && !hasQQBotImageSize(fullMatch)) {
+            try {
+                const size = await getImageSize(imgUrl);
+                result = result.replace(fullMatch, formatQQBotMarkdownImage(imgUrl, size));
+                log?.info(`${prefix} Updated image with size: ${size ? `${size.width}x${size.height}` : "default"} - ${imgUrl.slice(0, 60)}...`);
+            }
+            catch (err) {
+                log?.info(`${prefix} Failed to get image size for existing md, using default: ${err}`);
+                result = result.replace(fullMatch, formatQQBotMarkdownImage(imgUrl, null));
+            }
+        }
+    }
+    // 移除裸 URL 图片
+    for (const m of bareUrlMatches) {
+        result = result.replace(m[0], "").trim();
+    }
+    // 追加图片
+    if (imagesToAppend.length > 0) {
+        result = result.trim();
+        result = result ? result + "\n\n" + imagesToAppend.join("\n") : imagesToAppend.join("\n");
+    }
+    // 发送 markdown 文本
+    if (result.trim()) {
+        const mdChunks = chunkText(result, TEXT_CHUNK_LIMIT);
+        for (const chunk of mdChunks) {
+            try {
+                await sendWithRetry(async (token) => {
+                    const ref = consumeQuoteRef();
+                    if (event.type === "c2c") {
+                        return await sendC2CMessage(token, event.senderId, chunk, event.messageId, ref);
+                    }
+                    else if (event.type === "group" && event.groupOpenid) {
+                        return await sendGroupMessage(token, event.groupOpenid, chunk, event.messageId);
+                    }
+                    else if (event.channelId) {
+                        return await sendChannelMessage(token, event.channelId, chunk, event.messageId);
+                    }
+                });
+                log?.info(`${prefix} Sent markdown chunk (${chunk.length}/${result.length} chars) with ${httpImageUrls.length} HTTP images (${event.type})`);
+            }
+            catch (err) {
+                log?.error(`${prefix} Failed to send markdown message chunk: ${err}`);
+            }
+        }
+    }
+}
+/** 普通文本模式发送 */
+async function sendPlainTextReply(textWithoutImages, imageUrls, mdMatches, bareUrlMatches, event, actx, sendWithRetry, consumeQuoteRef) {
+    const { account, log } = actx;
+    const prefix = `[qqbot:${account.accountId}]`;
+    const imgMediaTarget = {
+        targetType: event.type === "c2c" ? "c2c" : event.type === "group" ? "group" : "channel",
+        targetId: event.type === "c2c" ? event.senderId : event.type === "group" ? event.groupOpenid : event.channelId,
+        account,
+        replyToId: event.messageId,
+        logPrefix: prefix,
+    };
+    let result = textWithoutImages;
+    for (const m of mdMatches)
+        result = result.replace(m[0], "").trim();
+    for (const m of bareUrlMatches)
+        result = result.replace(m[0], "").trim();
+    // 群聊 URL 点号过滤
+    if (result && event.type !== "c2c") {
+        result = result.replace(/([a-zA-Z0-9])\.([a-zA-Z0-9])/g, "$1_$2");
+    }
+    try {
+        for (const imageUrl of imageUrls) {
+            try {
+                const imgResult = await sendPhoto(imgMediaTarget, imageUrl);
+                if (imgResult.error) {
+                    log?.error(`${prefix} Failed to send image: ${imgResult.error}`);
+                    await sendTextChunks(`发送图片失败：${imgResult.error}`, event, actx, sendWithRetry, consumeQuoteRef);
+                }
+                else {
+                    log?.info(`${prefix} Sent image via sendPhoto: ${imageUrl.slice(0, 80)}...`);
+                }
+            }
+            catch (imgErr) {
+                log?.error(`${prefix} Failed to send image: ${imgErr}`);
+                await sendTextChunks(`发送图片失败：${imgErr}`, event, actx, sendWithRetry, consumeQuoteRef);
+            }
+        }
+        if (result.trim()) {
+            const plainChunks = chunkText(result, TEXT_CHUNK_LIMIT);
+            for (const chunk of plainChunks) {
+                await sendWithRetry(async (token) => {
+                    const ref = consumeQuoteRef();
+                    if (event.type === "c2c") {
+                        return await sendC2CMessage(token, event.senderId, chunk, event.messageId, ref);
+                    }
+                    else if (event.type === "group" && event.groupOpenid) {
+                        return await sendGroupMessage(token, event.groupOpenid, chunk, event.messageId);
+                    }
+                    else if (event.channelId) {
+                        return await sendChannelMessage(token, event.channelId, chunk, event.messageId);
+                    }
+                });
+                log?.info(`${prefix} Sent text chunk (${chunk.length}/${result.length} chars) (${event.type})`);
+            }
+        }
+    }
+    catch (err) {
+        log?.error(`${prefix} Send failed: ${err}`);
+    }
+}

package/dist/src/outbound.d.ts

@@ -0,0 +1,205 @@
+/**
+ * QQ Bot 消息发送模块
+ */
+import type { ResolvedQQBotAccount } from "./types.js";
+/** 限流检查结果 */
+export interface ReplyLimitResult {
+    /** 是否允许被动回复 */
+    allowed: boolean;
+    /** 剩余被动回复次数 */
+    remaining: number;
+    /** 是否需要降级为主动消息（超期或超过次数） */
+    shouldFallbackToProactive: boolean;
+    /** 降级原因 */
+    fallbackReason?: "expired" | "limit_exceeded";
+    /** 提示消息 */
+    message?: string;
+}
+/**
+ * 检查是否可以回复该消息（限流检查）
+ * @param messageId 消息ID
+ * @returns ReplyLimitResult 限流检查结果
+ */
+export declare function checkMessageReplyLimit(messageId: string): ReplyLimitResult;
+/**
+ * 记录一次消息回复
+ * @param messageId 消息ID
+ */
+export declare function recordMessageReply(messageId: string): void;
+/**
+ * 获取消息回复统计信息
+ */
+export declare function getMessageReplyStats(): {
+    trackedMessages: number;
+    totalReplies: number;
+};
+/**
+ * 获取消息回复限制配置（供外部查询）
+ */
+export declare function getMessageReplyConfig(): {
+    limit: number;
+    ttlMs: number;
+    ttlHours: number;
+};
+export interface OutboundContext {
+    to: string;
+    text: string;
+    accountId?: string | null;
+    replyToId?: string | null;
+    account: ResolvedQQBotAccount;
+}
+export interface MediaOutboundContext extends OutboundContext {
+    mediaUrl: string;
+    /** 可选的 MIME 类型，优先于扩展名判断媒体类型 */
+    mimeType?: string;
+}
+export interface OutboundResult {
+    channel: string;
+    messageId?: string;
+    timestamp?: string | number;
+    error?: string;
+    /** 出站消息的引用索引（ext_info.ref_idx），供引用消息缓存使用 */
+    refIdx?: string;
+}
+/** 媒体发送的目标上下文（从 deliver 回调或 sendText 中提取） */
+export interface MediaTargetContext {
+    /** 目标类型 */
+    targetType: "c2c" | "group" | "channel";
+    /** 目标 ID */
+    targetId: string;
+    /** QQ Bot 账户配置 */
+    account: ResolvedQQBotAccount;
+    /** 被动回复消息 ID（可选） */
+    replyToId?: string;
+    /** 日志前缀（可选，用于区分调用来源） */
+    logPrefix?: string;
+}
+/**
+ * sendPhoto — 发送图片消息
+ *
+ * 支持三种来源：
+ * - 本地文件路径 → 分片上传
+ * - 公网 HTTP/HTTPS URL → 下载到本地 → 分片上传（失败发文本链接兜底）
+ * - Base64 Data URL → 直传 QQ API
+ */
+export declare function sendPhoto(ctx: MediaTargetContext, imagePath: string, 
+/** 原始来源 URL（仅 fallback 路径使用，记录到引用索引） */
+sourceUrl?: string): Promise<OutboundResult>;
+/**
+ * sendVoice — 发送语音消息
+ *
+ * 支持本地音频文件和公网 URL：
+ * - urlDirectUpload=true + 公网URL：先直传平台，失败后下载到本地再转码重试
+ * - urlDirectUpload=false + 公网URL：直接下载到本地再转码发送
+ * - 本地文件：自动转换为 SILK 格式后上传
+ *
+ * 支持 transcodeEnabled 配置：禁用时非原生格式 fallback 到文件发送。
+ */
+export declare function sendVoice(ctx: MediaTargetContext, voicePath: string, 
+/** 直传格式列表（跳过 SILK 转换），可选 */
+directUploadFormats?: string[], 
+/** 是否启用转码（默认 true），false 时非原生格式直接返回错误 */
+transcodeEnabled?: boolean): Promise<OutboundResult>;
+/**
+ * sendVideoMsg — 发送视频消息
+ *
+ * 支持公网 URL（urlDirectUpload 控制直传或下载，失败自动 fallback）和本地文件路径。
+ */
+export declare function sendVideoMsg(ctx: MediaTargetContext, videoPath: string): Promise<OutboundResult>;
+/**
+ * sendDocument — 发送文件消息
+ *
+ * 支持本地文件路径和公网 URL（urlDirectUpload 控制直传或下载，失败自动 fallback）。
+ */
+export declare function sendDocument(ctx: MediaTargetContext, filePath: string): Promise<OutboundResult>;
+/**
+ * 发送文本消息
+ * - 有 replyToId: 被动回复，1小时内最多回复4次
+ * - 无 replyToId: 主动发送，有配额限制（每月4条/用户/群）
+ *
+ * 注意：
+ * 1. 主动消息（无 replyToId）必须有消息内容，不支持流式发送
+ * 2. 当被动回复不可用（超期或超过次数）时，自动降级为主动消息
+ * 3. 支持 <qqimg>路径</qqimg> 或 <qqimg>路径</img> 格式发送图片
+ */
+export declare function sendText(ctx: OutboundContext): Promise<OutboundResult>;
+/**
+ * 主动发送消息（不需要 replyToId，有配额限制：每月 4 条/用户/群）
+ *
+ * @param account - 账户配置
+ * @param to - 目标地址，格式：openid（单聊）或 group:xxx（群聊）
+ * @param text - 消息内容
+ */
+export declare function sendProactiveMessage(account: ResolvedQQBotAccount, to: string, text: string): Promise<OutboundResult>;
+/**
+ * 发送富媒体消息（图片）
+ *
+ * 支持以下 mediaUrl 格式：
+ * - 公网 URL: https://example.com/image.png
+ * - Base64 Data URL: data:image/png;base64,xxxxx
+ * - 本地文件路径: /path/to/image.png（自动读取并转换为 Base64）
+ *
+ * @param ctx - 发送上下文，包含 mediaUrl
+ * @returns 发送结果
+ *
+ * @example
+ * ```typescript
+ * // 发送网络图片
+ * const result = await sendMedia({
+ *   to: "group:xxx",
+ *   text: "这是图片说明",
+ *   mediaUrl: "https://example.com/image.png",
+ *   account,
+ *   replyToId: msgId,
+ * });
+ *
+ * // 发送 Base64 图片
+ * const result = await sendMedia({
+ *   to: "group:xxx",
+ *   text: "这是图片说明",
+ *   mediaUrl: "data:image/png;base64,iVBORw0KGgo...",
+ *   account,
+ *   replyToId: msgId,
+ * });
+ *
+ * // 发送本地文件（自动读取并转换为 Base64）
+ * const result = await sendMedia({
+ *   to: "group:xxx",
+ *   text: "这是图片说明",
+ *   mediaUrl: "/tmp/generated-chart.png",
+ *   account,
+ *   replyToId: msgId,
+ * });
+ * ```
+ */
+export declare function sendMedia(ctx: MediaOutboundContext): Promise<OutboundResult>;
+/**
+ * 发送 Cron 触发的消息
+ *
+ * 当 OpenClaw cron 任务触发时，消息内容可能是：
+ * 1. QQBOT_CRON:{base64} 格式的结构化载荷 - 解码后根据 targetType 和 targetAddress 发送
+ * 2. 普通文本 - 直接发送到指定目标
+ *
+ * @param account - 账户配置
+ * @param to - 目标地址（作为后备，如果载荷中没有指定）
+ * @param message - 消息内容（可能是 QQBOT_CRON: 格式或普通文本）
+ * @returns 发送结果
+ *
+ * @example
+ * ```typescript
+ * // 处理结构化载荷
+ * const result = await sendCronMessage(
+ *   account,
+ *   "user_openid",  // 后备地址
+ *   "QQBOT_CRON:eyJ0eXBlIjoiY3Jvbl9yZW1pbmRlciIs..."  // Base64 编码的载荷
+ * );
+ *
+ * // 处理普通文本
+ * const result = await sendCronMessage(
+ *   account,
+ *   "user_openid",
+ *   "这是一条普通的提醒消息"
+ * );
+ * ```
+ */
+export declare function sendCronMessage(account: ResolvedQQBotAccount, to: string, message: string): Promise<OutboundResult>;