@ryantest/openclaw-qqbot 0.0.1

package/dist/src/outbound-deliver.js

@@ -0,0 +1,462 @@
+/**
+ * 出站消息投递模块
+ *
+ * 从 gateway deliver 回调中提取的两大发送管线：
+ * 1. parseAndSendMediaTags — 解析 <qqimg/qqvoice/qqvideo/qqfile/qqmedia> 标签并按顺序发送
+ * 2. sendPlainReply — 处理不含媒体标签的普通回复（markdown 图片/纯文本+图片）
+ */
+import { sendC2CMessage, sendGroupMessage, sendChannelMessage, sendC2CImageMessage, sendGroupImageMessage } from "./api.js";
+import { sendPhoto, sendVoice, sendVideoMsg, sendDocument, 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 { normalizeMediaTags } from "./utils/media-tags.js";
+import { normalizePath, 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}]`;
+    // 预处理：纠正小模型常见的标签拼写错误和格式问题
+    const text = normalizeMediaTags(replyText);
+    const mediaTagRegex = /<(qqimg|qqvoice|qqvideo|qqfile|qqmedia)>([^<>]+)<\/(?:qqimg|qqvoice|qqvideo|qqfile|qqmedia|img)>/gi;
+    const mediaTagMatches = [...text.matchAll(mediaTagRegex)];
+    if (mediaTagMatches.length === 0) {
+        return { handled: false, normalizedText: text };
+    }
+    const tagCounts = mediaTagMatches.reduce((acc, m) => { const t = m[1].toLowerCase(); acc[t] = (acc[t] ?? 0) + 1; return acc; }, {});
+    log?.info(`${prefix} Detected media tags: ${Object.entries(tagCounts).map(([k, v]) => `${v} <${k}>`).join(", ")}`);
+    const sendQueue = [];
+    let lastIndex = 0;
+    const regex2 = /<(qqimg|qqvoice|qqvideo|qqfile|qqmedia)>([^<>]+)<\/(?:qqimg|qqvoice|qqvideo|qqfile|qqmedia|img)>/gi;
+    let match;
+    while ((match = regex2.exec(text)) !== null) {
+        const textBefore = text.slice(lastIndex, match.index).replace(/\n{3,}/g, "\n\n").trim();
+        if (textBefore) {
+            sendQueue.push({ type: "text", content: filterInternalMarkers(textBefore) });
+        }
+        const tagName = match[1].toLowerCase();
+        let mediaPath = decodeMediaPath(match[2]?.trim() ?? "", log, prefix);
+        if (mediaPath) {
+            const typeMap = {
+                qqmedia: "media", qqvoice: "voice", qqvideo: "video", qqfile: "file",
+            };
+            const itemType = typeMap[tagName] ?? "image";
+            sendQueue.push({ type: itemType, content: mediaPath });
+            log?.info(`${prefix} Found ${itemType} in <${tagName}>: ${mediaPath}`);
+        }
+        lastIndex = match.index + match[0].length;
+    }
+    const textAfter = text.slice(lastIndex).replace(/\n{3,}/g, "\n\n").trim();
+    if (textAfter) {
+        sendQueue.push({ type: "text", content: filterInternalMarkers(textAfter) });
+    }
+    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,
+    };
+    for (const item of sendQueue) {
+        if (item.type === "text") {
+            await sendTextChunks(item.content, event, actx, sendWithRetry, consumeQuoteRef);
+        }
+        else if (item.type === "image") {
+            const result = await sendPhoto(mediaTarget, item.content);
+            if (result.error)
+                log?.error(`${prefix} sendPhoto error: ${result.error}`);
+        }
+        else if (item.type === "voice") {
+            await sendVoiceWithTimeout(mediaTarget, item.content, account, log, prefix);
+        }
+        else if (item.type === "video") {
+            const result = await sendVideoMsg(mediaTarget, item.content);
+            if (result.error)
+                log?.error(`${prefix} sendVideoMsg error: ${result.error}`);
+        }
+        else if (item.type === "file") {
+            const result = await sendDocument(mediaTarget, item.content);
+            if (result.error)
+                log?.error(`${prefix} sendDocument error: ${result.error}`);
+        }
+        else if (item.type === "media") {
+            const result = await sendMediaAuto({
+                to: actx.qualifiedTarget,
+                text: "",
+                mediaUrl: item.content,
+                accountId: account.accountId,
+                replyToId: event.messageId,
+                account,
+            });
+            if (result.error)
+                log?.error(`${prefix} sendMedia(auto) error: ${result.error}`);
+        }
+    }
+    return { handled: true, normalizedText: text };
+}
+/**
+ * 发送不含媒体标签的普通回复。
+ * 处理 markdown 图片嵌入、Base64 富媒体、纯文本分块、本地媒体自动路由。
+ */
+export async function sendPlainReply(payload, replyText, event, actx, sendWithRetry, consumeQuoteRef, toolMediaUrls) {
+    const { account, qualifiedTarget, log } = actx;
+    const prefix = `[qqbot:${account.accountId}]`;
+    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}`);
+                else
+                    log?.info(`${prefix} Sent local media: ${mediaPath}`);
+            }
+            catch (err) {
+                log?.error(`${prefix} sendMedia(auto) failed for ${mediaPath}: ${err}`);
+            }
+        }
+    }
+    // 转发 tool 阶段收集的媒体
+    if (toolMediaUrls.length > 0) {
+        log?.info(`${prefix} Forwarding ${toolMediaUrls.length} tool-collected media URL(s) after block deliver`);
+        for (const mediaUrl of toolMediaUrls) {
+            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}`);
+                else
+                    log?.info(`${prefix} Forwarded tool media: ${mediaUrl.slice(0, 80)}...`);
+            }
+            catch (err) {
+                log?.error(`${prefix} Tool media forward failed: ${err}`);
+            }
+        }
+        toolMediaUrls.length = 0;
+    }
+}
+// ============ 内部辅助函数 ============
+/** 解码媒体路径：剥离 MEDIA: 前缀、展开 ~、修复转义 */
+function decodeMediaPath(raw, log, prefix) {
+    let mediaPath = raw;
+    if (mediaPath.startsWith("MEDIA:")) {
+        mediaPath = mediaPath.slice("MEDIA:".length);
+    }
+    mediaPath = normalizePath(mediaPath);
+    mediaPath = mediaPath.replace(/\\\\/g, "\\");
+    try {
+        const hasOctal = /\\[0-7]{1,3}/.test(mediaPath);
+        const hasNonASCII = /[\u0080-\u00FF]/.test(mediaPath);
+        if (hasOctal || hasNonASCII) {
+            log?.debug?.(`${prefix} Decoding path with mixed encoding: ${mediaPath}`);
+            let decoded = mediaPath.replace(/\\([0-7]{1,3})/g, (_, octal) => {
+                return String.fromCharCode(parseInt(octal, 8));
+            });
+            const bytes = [];
+            for (let i = 0; i < decoded.length; i++) {
+                const code = decoded.charCodeAt(i);
+                if (code <= 0xFF) {
+                    bytes.push(code);
+                }
+                else {
+                    const charBytes = Buffer.from(decoded[i], "utf8");
+                    bytes.push(...charBytes);
+                }
+            }
+            const buffer = Buffer.from(bytes);
+            const utf8Decoded = buffer.toString("utf8");
+            if (!utf8Decoded.includes("\uFFFD") || utf8Decoded.length < decoded.length) {
+                mediaPath = utf8Decoded;
+                log?.debug?.(`${prefix} Successfully decoded path: ${mediaPath}`);
+            }
+        }
+    }
+    catch (decodeErr) {
+        log?.error(`${prefix} Path decode error: ${decodeErr}`);
+    }
+    return mediaPath;
+}
+/** 发送文本分块（共用逻辑） */
+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}`);
+        }
+    }
+}
+/** 语音发送（带 45s 超时保护） */
+async function sendVoiceWithTimeout(target, voicePath, account, log, prefix) {
+    const uploadFormats = account.config?.audioFormatPolicy?.uploadDirectFormats ?? account.config?.voiceDirectUploadFormats;
+    const transcodeEnabled = account.config?.audioFormatPolicy?.transcodeEnabled !== false;
+    const voiceTimeout = 45000;
+    try {
+        const result = await Promise.race([
+            sendVoice(target, voicePath, uploadFormats, transcodeEnabled),
+            new Promise((resolve) => setTimeout(() => resolve({ channel: "qqbot", error: "语音发送超时，已跳过" }), voiceTimeout)),
+        ]);
+        if (result.error)
+            log?.error(`${prefix} sendVoice error: ${result.error}`);
+    }
+    catch (err) {
+        log?.error(`${prefix} sendVoice unexpected error: ${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}`);
+                else
+                    log?.info(`${prefix} Sent image via sendPhoto: ${imageUrl.slice(0, 80)}...`);
+            }
+            catch (imgErr) {
+                log?.error(`${prefix} Failed to send image: ${imgErr}`);
+            }
+        }
+        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,203 @@
+/**
+ * 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 — 发送图片消息（对齐 Telegram sendPhoto）
+ *
+ * 支持三种来源：
+ * - 本地文件路径（自动读取转 Base64）
+ * - 公网 HTTP/HTTPS URL（urlDirectUpload=true 时先直传平台，失败自动下载重试；=false 时直接下载）
+ * - Base64 Data URL
+ */
+export declare function sendPhoto(ctx: MediaTargetContext, imagePath: string): Promise<OutboundResult>;
+/**
+ * sendVoice — 发送语音消息（对齐 Telegram 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 — 发送视频消息（对齐 Telegram sendVideo）
+ *
+ * 支持公网 URL（urlDirectUpload 控制直传或下载，失败自动 fallback）和本地文件路径。
+ */
+export declare function sendVideoMsg(ctx: MediaTargetContext, videoPath: string): Promise<OutboundResult>;
+/**
+ * sendDocument — 发送文件消息（对齐 Telegram 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>;