@tencent-connect/openclaw-qqbot 1.7.1 → 2.0.0

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

@@ -1,48 +0,0 @@
-/**
- * 出站消息投递模块
- *
- * 从 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

@@ -1,392 +0,0 @@
-/**
- * 出站消息投递模块
- *
- * 从 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, DEFAULT_MEDIA_SEND_ERROR, resolveUserFacingMediaError, } 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(resolveUserFacingMediaError(result), 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(DEFAULT_MEDIA_SEND_ERROR, 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(resolveUserFacingMediaError(result), 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(DEFAULT_MEDIA_SEND_ERROR, 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(resolveUserFacingMediaError(imgResult), 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(DEFAULT_MEDIA_SEND_ERROR, 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

@@ -1,220 +0,0 @@
-/**
- * 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 declare const OUTBOUND_ERROR_CODES: {
-    readonly FILE_TOO_LARGE: "file_too_large";
-    readonly UPLOAD_DAILY_LIMIT_EXCEEDED: "upload_daily_limit_exceeded";
-};
-export declare const DEFAULT_MEDIA_SEND_ERROR = "\u53D1\u9001\u5931\u8D25\uFF0C\u8BF7\u7A0D\u540E\u91CD\u8BD5\u3002";
-export type OutboundErrorCode = typeof OUTBOUND_ERROR_CODES[keyof typeof OUTBOUND_ERROR_CODES];
-export interface OutboundResult {
-    channel: string;
-    messageId?: string;
-    timestamp?: string | number;
-    error?: string;
-    /** 稳定错误码，供上层按类型处理，避免依赖 error 文案 */
-    errorCode?: OutboundErrorCode;
-    /** QQ 开放平台业务错误码（如 upload_prepare 的 40093002） */
-    qqBizCode?: number;
-    /** 出站消息的引用索引（ext_info.ref_idx），供引用消息缓存使用 */
-    refIdx?: string;
-}
-/**
- * 将媒体发送结果映射为可展示给用户的文案。
- * 只对明确标记为可直接展示的错误码透传原文，其余统一走通用兜底。
- */
-export declare function resolveUserFacingMediaError(result: Pick<OutboundResult, "error" | "errorCode" | "qqBizCode">): 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>;