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

package/dist/src/utils/file-utils.js

@@ -0,0 +1,107 @@
+/**
+ * 文件操作工具 — 异步读取 + 大小校验 + 进度提示
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+/** QQ Bot API 最大上传文件大小：20MB */
+export const MAX_UPLOAD_SIZE = 20 * 1024 * 1024;
+/** 大文件阈值（超过此值发送进度提示）：5MB */
+export const LARGE_FILE_THRESHOLD = 5 * 1024 * 1024;
+/**
+ * 校验文件大小是否在上传限制内
+ * @param filePath 文件路径
+ * @param maxSize 最大允许大小（字节），默认 20MB
+ */
+export function checkFileSize(filePath, maxSize = MAX_UPLOAD_SIZE) {
+    try {
+        const stat = fs.statSync(filePath);
+        if (stat.size > maxSize) {
+            const sizeMB = (stat.size / (1024 * 1024)).toFixed(1);
+            const limitMB = (maxSize / (1024 * 1024)).toFixed(0);
+            return {
+                ok: false,
+                size: stat.size,
+                error: `文件过大 (${sizeMB}MB)，QQ Bot API 上传限制为 ${limitMB}MB`,
+            };
+        }
+        return { ok: true, size: stat.size };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            size: 0,
+            error: `无法读取文件信息: ${err instanceof Error ? err.message : String(err)}`,
+        };
+    }
+}
+/**
+ * 异步读取文件内容
+ * 替代 fs.readFileSync，避免阻塞事件循环
+ */
+export async function readFileAsync(filePath) {
+    return fs.promises.readFile(filePath);
+}
+/**
+ * 异步检查文件是否存在
+ */
+export async function fileExistsAsync(filePath) {
+    try {
+        await fs.promises.access(filePath, fs.constants.R_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 异步获取文件大小
+ */
+export async function getFileSizeAsync(filePath) {
+    const stat = await fs.promises.stat(filePath);
+    return stat.size;
+}
+/**
+ * 判断文件是否为"大文件"（需要进度提示）
+ */
+export function isLargeFile(sizeBytes) {
+    return sizeBytes >= LARGE_FILE_THRESHOLD;
+}
+/**
+ * 格式化文件大小为人类可读的字符串
+ */
+export function formatFileSize(bytes) {
+    if (bytes < 1024)
+        return `${bytes}B`;
+    if (bytes < 1024 * 1024)
+        return `${(bytes / 1024).toFixed(1)}KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+}
+/**
+ * 根据文件扩展名获取 MIME 类型
+ */
+export function getMimeType(filePath) {
+    const ext = path.extname(filePath).toLowerCase();
+    const mimeTypes = {
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".png": "image/png",
+        ".gif": "image/gif",
+        ".webp": "image/webp",
+        ".bmp": "image/bmp",
+        ".mp4": "video/mp4",
+        ".mov": "video/quicktime",
+        ".avi": "video/x-msvideo",
+        ".mkv": "video/x-matroska",
+        ".webm": "video/webm",
+        ".pdf": "application/pdf",
+        ".doc": "application/msword",
+        ".docx": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
+        ".xls": "application/vnd.ms-excel",
+        ".xlsx": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
+        ".zip": "application/zip",
+        ".tar": "application/x-tar",
+        ".gz": "application/gzip",
+        ".txt": "text/plain",
+    };
+    return mimeTypes[ext] ?? "application/octet-stream";
+}

package/dist/src/utils/image-size.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 图片尺寸工具
+ * 用于获取图片尺寸，生成 QQBot 的 markdown 图片格式
+ *
+ * QQBot markdown 图片格式: ![#宽px #高px](url)
+ */
+import { Buffer } from "buffer";
+export interface ImageSize {
+    width: number;
+    height: number;
+}
+/** 默认图片尺寸（当无法获取时使用） */
+export declare const DEFAULT_IMAGE_SIZE: ImageSize;
+/**
+ * 从图片数据 Buffer 解析尺寸
+ */
+export declare function parseImageSize(buffer: Buffer): ImageSize | null;
+/**
+ * 从公网 URL 获取图片尺寸
+ * 只下载前 64KB 数据，足够解析大部分图片格式的头部
+ */
+export declare function getImageSizeFromUrl(url: string, timeoutMs?: number): Promise<ImageSize | null>;
+/**
+ * 从 Base64 Data URL 获取图片尺寸
+ */
+export declare function getImageSizeFromDataUrl(dataUrl: string): ImageSize | null;
+/**
+ * 获取图片尺寸（自动判断来源）
+ * @param source - 图片 URL 或 Base64 Data URL
+ * @returns 图片尺寸，失败返回 null
+ */
+export declare function getImageSize(source: string): Promise<ImageSize | null>;
+/**
+ * 生成 QQBot markdown 图片格式
+ * 格式: ![#宽px #高px](url)
+ *
+ * @param url - 图片 URL
+ * @param size - 图片尺寸，如果为 null 则使用默认尺寸
+ * @returns QQBot markdown 图片字符串
+ */
+export declare function formatQQBotMarkdownImage(url: string, size: ImageSize | null): string;
+/**
+ * 检查 markdown 图片是否已经包含 QQBot 格式的尺寸信息
+ * 格式: ![#宽px #高px](url)
+ */
+export declare function hasQQBotImageSize(markdownImage: string): boolean;
+/**
+ * 从已有的 QQBot 格式 markdown 图片中提取尺寸
+ * 格式: ![#宽px #高px](url)
+ */
+export declare function extractQQBotImageSize(markdownImage: string): ImageSize | null;

package/dist/src/utils/image-size.js

@@ -0,0 +1,234 @@
+/**
+ * 图片尺寸工具
+ * 用于获取图片尺寸，生成 QQBot 的 markdown 图片格式
+ *
+ * QQBot markdown 图片格式: ![#宽px #高px](url)
+ */
+import { Buffer } from "buffer";
+/** 默认图片尺寸（当无法获取时使用） */
+export const DEFAULT_IMAGE_SIZE = { width: 512, height: 512 };
+/**
+ * 从 PNG 文件头解析图片尺寸
+ * PNG 文件头结构: 前 8 字节是签名，IHDR 块从第 8 字节开始
+ * IHDR 块: 长度(4) + 类型(4, "IHDR") + 宽度(4) + 高度(4) + ...
+ */
+function parsePngSize(buffer) {
+    // PNG 签名: 89 50 4E 47 0D 0A 1A 0A
+    if (buffer.length < 24)
+        return null;
+    if (buffer[0] !== 0x89 || buffer[1] !== 0x50 || buffer[2] !== 0x4E || buffer[3] !== 0x47) {
+        return null;
+    }
+    // IHDR 块从第 8 字节开始，宽度在第 16-19 字节，高度在第 20-23 字节
+    const width = buffer.readUInt32BE(16);
+    const height = buffer.readUInt32BE(20);
+    return { width, height };
+}
+/**
+ * 从 JPEG 文件解析图片尺寸
+ * JPEG 尺寸在 SOF0/SOF2 块中
+ */
+function parseJpegSize(buffer) {
+    // JPEG 签名: FF D8 FF
+    if (buffer.length < 4)
+        return null;
+    if (buffer[0] !== 0xFF || buffer[1] !== 0xD8) {
+        return null;
+    }
+    let offset = 2;
+    while (offset < buffer.length - 9) {
+        if (buffer[offset] !== 0xFF) {
+            offset++;
+            continue;
+        }
+        const marker = buffer[offset + 1];
+        // SOF0 (0xC0) 或 SOF2 (0xC2) 包含图片尺寸
+        if (marker === 0xC0 || marker === 0xC2) {
+            // 格式: FF C0 长度(2) 精度(1) 高度(2) 宽度(2)
+            if (offset + 9 <= buffer.length) {
+                const height = buffer.readUInt16BE(offset + 5);
+                const width = buffer.readUInt16BE(offset + 7);
+                return { width, height };
+            }
+        }
+        // 跳过当前块
+        if (offset + 3 < buffer.length) {
+            const blockLength = buffer.readUInt16BE(offset + 2);
+            offset += 2 + blockLength;
+        }
+        else {
+            break;
+        }
+    }
+    return null;
+}
+/**
+ * 从 GIF 文件头解析图片尺寸
+ * GIF 文件头: GIF87a 或 GIF89a (6字节) + 宽度(2) + 高度(2)
+ */
+function parseGifSize(buffer) {
+    if (buffer.length < 10)
+        return null;
+    const signature = buffer.toString("ascii", 0, 6);
+    if (signature !== "GIF87a" && signature !== "GIF89a") {
+        return null;
+    }
+    const width = buffer.readUInt16LE(6);
+    const height = buffer.readUInt16LE(8);
+    return { width, height };
+}
+/**
+ * 从 WebP 文件解析图片尺寸
+ * WebP 文件头: RIFF(4) + 文件大小(4) + WEBP(4) + VP8/VP8L/VP8X(4) + ...
+ */
+function parseWebpSize(buffer) {
+    if (buffer.length < 30)
+        return null;
+    // 检查 RIFF 和 WEBP 签名
+    const riff = buffer.toString("ascii", 0, 4);
+    const webp = buffer.toString("ascii", 8, 12);
+    if (riff !== "RIFF" || webp !== "WEBP") {
+        return null;
+    }
+    const chunkType = buffer.toString("ascii", 12, 16);
+    // VP8 (有损压缩)
+    if (chunkType === "VP8 ") {
+        // VP8 帧头从第 23 字节开始，检查签名 9D 01 2A
+        if (buffer.length >= 30 && buffer[23] === 0x9D && buffer[24] === 0x01 && buffer[25] === 0x2A) {
+            const width = buffer.readUInt16LE(26) & 0x3FFF;
+            const height = buffer.readUInt16LE(28) & 0x3FFF;
+            return { width, height };
+        }
+    }
+    // VP8L (无损压缩)
+    if (chunkType === "VP8L") {
+        // VP8L 签名: 0x2F
+        if (buffer.length >= 25 && buffer[20] === 0x2F) {
+            const bits = buffer.readUInt32LE(21);
+            const width = (bits & 0x3FFF) + 1;
+            const height = ((bits >> 14) & 0x3FFF) + 1;
+            return { width, height };
+        }
+    }
+    // VP8X (扩展格式)
+    if (chunkType === "VP8X") {
+        if (buffer.length >= 30) {
+            // 宽度和高度在第 24-26 和 27-29 字节（24位小端）
+            const width = (buffer[24] | (buffer[25] << 8) | (buffer[26] << 16)) + 1;
+            const height = (buffer[27] | (buffer[28] << 8) | (buffer[29] << 16)) + 1;
+            return { width, height };
+        }
+    }
+    return null;
+}
+/**
+ * 从图片数据 Buffer 解析尺寸
+ */
+export function parseImageSize(buffer) {
+    // 尝试各种格式
+    return parsePngSize(buffer)
+        ?? parseJpegSize(buffer)
+        ?? parseGifSize(buffer)
+        ?? parseWebpSize(buffer);
+}
+/**
+ * 从公网 URL 获取图片尺寸
+ * 只下载前 64KB 数据，足够解析大部分图片格式的头部
+ */
+export async function getImageSizeFromUrl(url, timeoutMs = 5000) {
+    try {
+        const controller = new AbortController();
+        const timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+        // 使用 Range 请求只获取前 64KB
+        const response = await fetch(url, {
+            signal: controller.signal,
+            headers: {
+                "Range": "bytes=0-65535",
+                "User-Agent": "QQBot-Image-Size-Detector/1.0",
+            },
+        });
+        clearTimeout(timeoutId);
+        if (!response.ok && response.status !== 206) {
+            console.log(`[image-size] Failed to fetch ${url}: ${response.status}`);
+            return null;
+        }
+        const arrayBuffer = await response.arrayBuffer();
+        const buffer = Buffer.from(arrayBuffer);
+        const size = parseImageSize(buffer);
+        if (size) {
+            console.log(`[image-size] Got size from URL: ${size.width}x${size.height} - ${url.slice(0, 60)}...`);
+        }
+        return size;
+    }
+    catch (err) {
+        console.log(`[image-size] Error fetching ${url.slice(0, 60)}...: ${err}`);
+        return null;
+    }
+}
+/**
+ * 从 Base64 Data URL 获取图片尺寸
+ */
+export function getImageSizeFromDataUrl(dataUrl) {
+    try {
+        // 格式: data:image/png;base64,xxxxx
+        const matches = dataUrl.match(/^data:image\/[^;]+;base64,(.+)$/);
+        if (!matches) {
+            return null;
+        }
+        const base64Data = matches[1];
+        const buffer = Buffer.from(base64Data, "base64");
+        const size = parseImageSize(buffer);
+        if (size) {
+            console.log(`[image-size] Got size from Base64: ${size.width}x${size.height}`);
+        }
+        return size;
+    }
+    catch (err) {
+        console.log(`[image-size] Error parsing Base64: ${err}`);
+        return null;
+    }
+}
+/**
+ * 获取图片尺寸（自动判断来源）
+ * @param source - 图片 URL 或 Base64 Data URL
+ * @returns 图片尺寸，失败返回 null
+ */
+export async function getImageSize(source) {
+    if (source.startsWith("data:")) {
+        return getImageSizeFromDataUrl(source);
+    }
+    if (source.startsWith("http://") || source.startsWith("https://")) {
+        return getImageSizeFromUrl(source);
+    }
+    return null;
+}
+/**
+ * 生成 QQBot markdown 图片格式
+ * 格式: ![#宽px #高px](url)
+ *
+ * @param url - 图片 URL
+ * @param size - 图片尺寸，如果为 null 则使用默认尺寸
+ * @returns QQBot markdown 图片字符串
+ */
+export function formatQQBotMarkdownImage(url, size) {
+    const { width, height } = size ?? DEFAULT_IMAGE_SIZE;
+    return `![#${width}px #${height}px](${url})`;
+}
+/**
+ * 检查 markdown 图片是否已经包含 QQBot 格式的尺寸信息
+ * 格式: ![#宽px #高px](url)
+ */
+export function hasQQBotImageSize(markdownImage) {
+    return /!\[#\d+px\s+#\d+px\]/.test(markdownImage);
+}
+/**
+ * 从已有的 QQBot 格式 markdown 图片中提取尺寸
+ * 格式: ![#宽px #高px](url)
+ */
+export function extractQQBotImageSize(markdownImage) {
+    const match = markdownImage.match(/!\[#(\d+)px\s+#(\d+)px\]/);
+    if (match) {
+        return { width: parseInt(match[1], 10), height: parseInt(match[2], 10) };
+    }
+    return null;
+}

package/dist/src/utils/media-tags.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 富媒体标签预处理与纠错
+ *
+ * 小模型常见的标签拼写错误及变体，在正则匹配前统一修正为标准格式。
+ */
+/**
+ * 预处理 LLM 输出文本，将各种畸形/错误的富媒体标签修正为标准格式。
+ *
+ * 标准格式：<qqimg>/path/to/file</qqimg>
+ *
+ * @param text LLM 原始输出
+ * @returns 修正后的文本（如果没有匹配到任何标签则原样返回）
+ */
+export declare function normalizeMediaTags(text: string): string;

package/dist/src/utils/media-tags.js

@@ -0,0 +1,120 @@
+/**
+ * 富媒体标签预处理与纠错
+ *
+ * 小模型常见的标签拼写错误及变体，在正则匹配前统一修正为标准格式。
+ */
+import { expandTilde } from "./platform.js";
+// 标准标签名
+const VALID_TAGS = ["qqimg", "qqvoice", "qqvideo", "qqfile"];
+// 开头标签别名映射（key 全部小写）
+const TAG_ALIASES = {
+    // ---- qqimg 变体 ----
+    "qq_img": "qqimg",
+    "qqimage": "qqimg",
+    "qq_image": "qqimg",
+    "qqpic": "qqimg",
+    "qq_pic": "qqimg",
+    "qqpicture": "qqimg",
+    "qq_picture": "qqimg",
+    "qqphoto": "qqimg",
+    "qq_photo": "qqimg",
+    "img": "qqimg",
+    "image": "qqimg",
+    "pic": "qqimg",
+    "picture": "qqimg",
+    "photo": "qqimg",
+    // ---- qqvoice 变体 ----
+    "qq_voice": "qqvoice",
+    "qqaudio": "qqvoice",
+    "qq_audio": "qqvoice",
+    "voice": "qqvoice",
+    "audio": "qqvoice",
+    // ---- qqvideo 变体 ----
+    "qq_video": "qqvideo",
+    "video": "qqvideo",
+    // ---- qqfile 变体 ----
+    "qq_file": "qqfile",
+    "qqdoc": "qqfile",
+    "qq_doc": "qqfile",
+    "file": "qqfile",
+    "doc": "qqfile",
+    "document": "qqfile",
+};
+// 构建所有可识别的标签名列表（标准名 + 别名）
+const ALL_TAG_NAMES = [...VALID_TAGS, ...Object.keys(TAG_ALIASES)];
+// 按长度降序排列，优先匹配更长的名称（避免 "img" 抢先匹配 "qqimg" 的子串）
+ALL_TAG_NAMES.sort((a, b) => b.length - a.length);
+const TAG_NAME_PATTERN = ALL_TAG_NAMES.join("|");
+/**
+ * 构建一个宽容的正则，能匹配各种畸形标签写法：
+ *
+ * 常见错误模式：
+ *  1. 标签名拼错：<qq_img>, <qqimage>, <image>, <img>, <pic> ...
+ *  2. 标签内多余空格：<qqimg >, < qqimg>, <qqimg >
+ *  3. 闭合标签不匹配：<qqimg>url</qqvoice>, <qqimg>url</img>
+ *  4. 闭合标签缺失斜杠：<qqimg>url<qqimg> (用开头标签代替闭合标签)
+ *  5. 闭合标签缺失尖括号：<qqimg>url/qqimg>
+ *  6. 中文尖括号：＜qqimg＞url＜/qqimg＞ 或 <qqimg>url</qqimg>
+ *  7. 多余引号包裹路径：<qqimg>"path"</qqimg>
+ *  8. Markdown 代码块包裹：`<qqimg>path</qqimg>`
+ */
+const FUZZY_MEDIA_TAG_REGEX = new RegExp(
+// 可选 Markdown 行内代码反引号
+"`?" +
+    // 开头标签：允许中文/英文尖括号，标签名前后可有空格
+    "[<＜<]\\s*(" + TAG_NAME_PATTERN + ")\\s*[>＞>]" +
+    // 内容：非贪婪匹配，允许引号包裹
+    "[\"']?\\s*" +
+    "([^<＜<＞>\"'`]+?)" +
+    "\\s*[\"']?" +
+    // 闭合标签：允许各种不规范写法
+    "[<＜<]\\s*/?\\s*(?:" + TAG_NAME_PATTERN + ")\\s*[>＞>]" +
+    // 可选结尾反引号
+    "`?", "gi");
+/**
+ * 将标签名映射为标准名称
+ */
+function resolveTagName(raw) {
+    const lower = raw.toLowerCase();
+    if (VALID_TAGS.includes(lower)) {
+        return lower;
+    }
+    return TAG_ALIASES[lower] ?? "qqimg";
+}
+/**
+ * 预清理：将富媒体标签内部的换行/回车/制表符压缩为单个空格。
+ *
+ * 部分模型会在标签内部插入 \n \r \t 等空白字符，例如：
+ *   <qqimg>\n  /path/to/file.png\n</qqimg>
+ *   <qqimg>/path/to/\nfile.png</qqimg>
+ *
+ * 此正则匹配从开标签到闭标签之间的内容（允许跨行），
+ * 将内部所有 [\r\n\t] 替换为空格，然后压缩连续空格。
+ */
+const MULTILINE_TAG_CLEANUP = new RegExp("([<＜<]\\s*(?:" + TAG_NAME_PATTERN + ")\\s*[>＞>])" +
+    "([\\s\\S]*?)" +
+    "([<＜<]\\s*/?\\s*(?:" + TAG_NAME_PATTERN + ")\\s*[>＞>])", "gi");
+/**
+ * 预处理 LLM 输出文本，将各种畸形/错误的富媒体标签修正为标准格式。
+ *
+ * 标准格式：<qqimg>/path/to/file</qqimg>
+ *
+ * @param text LLM 原始输出
+ * @returns 修正后的文本（如果没有匹配到任何标签则原样返回）
+ */
+export function normalizeMediaTags(text) {
+    // 先将标签内部的换行/回车/制表符压缩为空格
+    let cleaned = text.replace(MULTILINE_TAG_CLEANUP, (_m, open, body, close) => {
+        const flat = body.replace(/[\r\n\t]+/g, " ").replace(/ {2,}/g, " ");
+        return open + flat + close;
+    });
+    return cleaned.replace(FUZZY_MEDIA_TAG_REGEX, (_match, rawTag, content) => {
+        const tag = resolveTagName(rawTag);
+        const trimmed = content.trim();
+        if (!trimmed)
+            return _match; // 空内容不处理
+        // 展开波浪线路径：~/Desktop/file.png → /Users/xxx/Desktop/file.png
+        const expanded = expandTilde(trimmed);
+        return `<${tag}>${expanded}</${tag}>`;
+    });
+}

package/dist/src/utils/payload.d.ts

@@ -0,0 +1,112 @@
+/**
+ * QQBot 结构化消息载荷工具
+ *
+ * 用于处理 AI 输出的结构化消息载荷，包括：
+ * - 定时提醒载荷 (cron_reminder)
+ * - 媒体消息载荷 (media)
+ */
+/**
+ * 定时提醒载荷
+ */
+export interface CronReminderPayload {
+    type: 'cron_reminder';
+    /** 提醒内容 */
+    content: string;
+    /** 目标类型：c2c (私聊) 或 group (群聊) */
+    targetType: 'c2c' | 'group';
+    /** 目标地址：user_openid 或 group_openid */
+    targetAddress: string;
+    /** 原始消息 ID（可选） */
+    originalMessageId?: string;
+}
+/**
+ * 媒体消息载荷
+ */
+export interface MediaPayload {
+    type: 'media';
+    /** 媒体类型：image, audio, video, file */
+    mediaType: 'image' | 'audio' | 'video' | 'file';
+    /** 来源类型：url 或 file */
+    source: 'url' | 'file';
+    /** 媒体路径或 URL */
+    path: string;
+    /** 媒体描述（可选） */
+    caption?: string;
+}
+/**
+ * QQBot 载荷联合类型
+ */
+export type QQBotPayload = CronReminderPayload | MediaPayload;
+/**
+ * 解析结果
+ */
+export interface ParseResult {
+    /** 是否为结构化载荷 */
+    isPayload: boolean;
+    /** 解析后的载荷对象（如果是结构化载荷） */
+    payload?: QQBotPayload;
+    /** 原始文本（如果不是结构化载荷） */
+    text?: string;
+    /** 解析错误信息（如果解析失败） */
+    error?: string;
+}
+/**
+ * 解析 AI 输出的结构化载荷
+ *
+ * 检测消息是否以 QQBOT_PAYLOAD: 前缀开头，如果是则提取并解析 JSON
+ *
+ * @param text AI 输出的原始文本
+ * @returns 解析结果
+ *
+ * @example
+ * const result = parseQQBotPayload('QQBOT_PAYLOAD:\n{"type": "media", "mediaType": "image", ...}');
+ * if (result.isPayload && result.payload) {
+ *   // 处理结构化载荷
+ * }
+ */
+export declare function parseQQBotPayload(text: string): ParseResult;
+/**
+ * 将定时提醒载荷编码为 Cron 消息格式
+ *
+ * 将 JSON 编码为 Base64，并添加 QQBOT_CRON: 前缀
+ *
+ * @param payload 定时提醒载荷
+ * @returns 编码后的消息字符串，格式为 QQBOT_CRON:{base64}
+ *
+ * @example
+ * const message = encodePayloadForCron({
+ *   type: 'cron_reminder',
+ *   content: '喝水时间到！',
+ *   targetType: 'c2c',
+ *   targetAddress: 'user_openid_xxx'
+ * });
+ * // 返回: QQBOT_CRON:eyJ0eXBlIjoiY3Jvbl9yZW1pbmRlciIs...
+ */
+export declare function encodePayloadForCron(payload: CronReminderPayload): string;
+/**
+ * 解码 Cron 消息中的载荷
+ *
+ * 检测 QQBOT_CRON: 前缀，解码 Base64 并解析 JSON
+ *
+ * @param message Cron 触发时收到的消息
+ * @returns 解码结果，包含是否为 Cron 载荷、解析后的载荷对象或错误信息
+ *
+ * @example
+ * const result = decodeCronPayload('QQBOT_CRON:eyJ0eXBlIjoiY3Jvbl9yZW1pbmRlciIs...');
+ * if (result.isCronPayload && result.payload) {
+ *   // 处理定时提醒
+ * }
+ */
+export declare function decodeCronPayload(message: string): {
+    isCronPayload: boolean;
+    payload?: CronReminderPayload;
+    error?: string;
+};
+/**
+ * 判断载荷是否为定时提醒类型
+ */
+export declare function isCronReminderPayload(payload: QQBotPayload): payload is CronReminderPayload;
+/**
+ * 判断载荷是否为媒体消息类型
+ */
+export declare function isMediaPayload(payload: QQBotPayload): payload is MediaPayload;