@cxyhhhhh/openclaw-qqbot 1.6.7-alpha.1

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-send.d.ts

@@ -0,0 +1,148 @@
+/**
+ * 富媒体标签解析与发送队列
+ *
+ * 提供媒体标签（qqimg / qqvoice / qqvideo / qqfile / qqmedia）的检测、
+ * 拆分、路径编码修复，以及统一的发送队列执行器。
+ */
+import { type MediaTargetContext } from "../outbound.js";
+import type { ResolvedQQBotAccount } from "../types.js";
+/** 发送队列项 */
+export interface SendQueueItem {
+    type: "text" | "image" | "voice" | "video" | "file" | "media";
+    content: string;
+}
+/** 统一的媒体标签正则 — 匹配标准化后的 6 种标签 */
+export declare const MEDIA_TAG_REGEX: RegExp;
+/** 创建一个新的全局标签正则实例（每次调用 reset lastIndex） */
+export declare function createMediaTagRegex(): RegExp;
+/** 媒体发送上下文（统一的，供流式和普通模式共用） */
+export interface MediaSendContext {
+    /** 媒体目标上下文（用于 sendPhoto/sendVoice 等） */
+    mediaTarget: MediaTargetContext;
+    /** qualifiedTarget（格式 "qqbot:c2c:xxx" 或 "qqbot:group:xxx"，用于 sendMediaAuto） */
+    qualifiedTarget: string;
+    /** 账户配置 */
+    account: ResolvedQQBotAccount;
+    /** 事件消息 ID（用于被动回复） */
+    replyToId?: string;
+    /** 日志 */
+    log?: {
+        info: (msg: string) => void;
+        error: (msg: string) => void;
+        debug?: (msg: string) => void;
+    };
+}
+/**
+ * 修复路径编码问题（双反斜杠、八进制转义、UTF-8 双重编码）
+ *
+ * 这是由于 LLM 输出路径时可能引入的编码问题：
+ * - Markdown 转义导致双反斜杠
+ * - 八进制转义序列（来自某些 shell 工具的输出）
+ * - UTF-8 双重编码（中文路径经过多层处理后的乱码）
+ *
+ * 此方法在 gateway.ts deliver 回调、outbound.ts sendText、
+ * streaming.ts sendMediaQueue 中共用。
+ */
+export declare function fixPathEncoding(mediaPath: string, log?: {
+    debug?: (msg: string) => void;
+    error?: (msg: string) => void;
+}): string;
+/**
+ * 检测文本是否包含富媒体标签
+ */
+export declare function hasMediaTags(text: string): boolean;
+/** findFirstClosedMediaTag 的返回值 */
+export interface FirstClosedMediaTag {
+    /** 标签前的纯文本（已 trim） */
+    textBefore: string;
+    /** 标签类型（小写，如 "qqvoice"） */
+    tagName: string;
+    /** 标签内的媒体路径（已 trim、去 MEDIA: 前缀、修复编码） */
+    mediaPath: string;
+    /** 标签在输入文本中的结束索引（紧接标签后的第一个字符位置） */
+    tagEndIndex: number;
+    /** 映射后的发送队列项类型 */
+    itemType: SendQueueItem["type"];
+}
+/**
+ * 在文本中查找**第一个**完整闭合的媒体标签
+ *
+ * 与 splitByMediaTags 不同，此函数只匹配一个标签就停止，
+ * 用于流式场景的"循环消费"模式：每次处理一个标签，更新偏移，再找下一个。
+ *
+ * @param text 待检查的文本（应已 normalize 过）
+ * @returns 第一个闭合标签的信息，没有则返回 null
+ */
+export declare function findFirstClosedMediaTag(text: string, log?: {
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+    error?: (msg: string) => void;
+}): FirstClosedMediaTag | null;
+/**
+ * 媒体标签拆分结果
+ */
+export interface MediaSplitResult {
+    /** 是否包含媒体标签 */
+    hasMediaTags: boolean;
+    /** 媒体标签前的纯文本 */
+    textBeforeFirstTag: string;
+    /** 媒体标签后的剩余文本 */
+    textAfterLastTag: string;
+    /** 完整的发送队列（标签间的文本 + 媒体项） */
+    mediaQueue: SendQueueItem[];
+}
+/**
+ * 将文本按富媒体标签拆分为三部分
+ *
+ * 用于两个场景：
+ * 1. 流式模式：中断-恢复流程（标签前文本 → 结束流式 → 发送媒体 → 新流式 → 标签后文本）
+ * 2. 普通模式：构建按顺序发送的队列
+ */
+export declare function splitByMediaTags(text: string, log?: {
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+    error?: (msg: string) => void;
+}): MediaSplitResult;
+/**
+ * 从文本中解析出完整的发送队列（含标签前后的纯文本）
+ *
+ * 与 splitByMediaTags 的区别：
+ * - splitByMediaTags 分为 before / queue / after 三段（供流式模式的中断-恢复）
+ * - parseMediaTagsToSendQueue 返回一个扁平的完整队列（供普通模式按顺序发送）
+ *
+ * 适用于 gateway.ts deliver 回调和 outbound.ts sendText。
+ */
+export declare function parseMediaTagsToSendQueue(text: string, log?: {
+    info?: (msg: string) => void;
+    debug?: (msg: string) => void;
+    error?: (msg: string) => void;
+}): {
+    hasMediaTags: boolean;
+    sendQueue: SendQueueItem[];
+};
+/**
+ * 统一执行发送队列
+ *
+ * 遍历 sendQueue，按类型调用对应的发送函数。
+ * 文本项通过 onSendText 回调处理（不同场景的文本发送方式不同）。
+ * 媒体发送失败时，通过 onSendText 发送兜底文本通知用户。
+ */
+export declare function executeSendQueue(queue: SendQueueItem[], ctx: MediaSendContext, options?: {
+    /** 文本发送回调（每种场景的文本发送方式不同） */
+    onSendText?: (text: string) => Promise<void>;
+    /** 是否跳过 inter-tag 文本（流式模式下通常跳过，由新流式会话处理） */
+    skipInterTagText?: boolean;
+}): Promise<void>;
+/**
+ * 从文本中剥离所有媒体标签（用于最终显示）
+ */
+export declare function stripMediaTags(text: string): string;
+/**
+ * 检测文本中是否有未闭合的媒体标签，如果有则截断到安全位置。
+ *
+ * 流式输出中 LLM 逐 token 吐出媒体标签，中间态不应直接发给用户。
+ * 只检查最后一行，从右到左扫描 `<`，找到第一个有意义的媒体标签片段并判断是否完整。
+ *
+ * 核心原则：截断只能截到**开标签**前面；闭合标签前缀若找不到对应开标签则原样返回。
+ */
+export declare function stripIncompleteMediaTag(text: string): [safeText: string, hasIncomplete: boolean];