@leoqlin/openclaw-qqbot 1.6.7-alpha1

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

@@ -0,0 +1,499 @@
+/**
+ * 富媒体标签解析与发送队列
+ *
+ * 提供媒体标签（qqimg / qqvoice / qqvideo / qqfile / qqmedia）的检测、
+ * 拆分、路径编码修复，以及统一的发送队列执行器。
+ */
+/* eslint-disable no-undef -- Buffer is a Node.js global */
+import { normalizeMediaTags } from "./media-tags.js";
+import { normalizePath } from "./platform.js";
+import { sendPhoto, sendVoice, sendVideoMsg, sendDocument, sendMedia as sendMediaAuto, } from "../outbound.js";
+/** 统一的媒体标签正则 — 匹配标准化后的 6 种标签 */
+export const MEDIA_TAG_REGEX = /<(qqimg|qqvoice|qqvideo|qqfile|qqmedia|img)>([^<>]+)<\/(?:qqimg|qqvoice|qqvideo|qqfile|qqmedia|img)>/gi;
+/** 创建一个新的全局标签正则实例（每次调用 reset lastIndex） */
+export function createMediaTagRegex() {
+    return new RegExp(MEDIA_TAG_REGEX.source, MEDIA_TAG_REGEX.flags);
+}
+// ============ 路径编码修复 ============
+/**
+ * 修复路径编码问题（双反斜杠、八进制转义、UTF-8 双重编码）
+ *
+ * 这是由于 LLM 输出路径时可能引入的编码问题：
+ * - Markdown 转义导致双反斜杠
+ * - 八进制转义序列（来自某些 shell 工具的输出）
+ * - UTF-8 双重编码（中文路径经过多层处理后的乱码）
+ *
+ * 此方法在 gateway.ts deliver 回调、outbound.ts sendText、
+ * streaming.ts sendMediaQueue 中共用。
+ */
+export function fixPathEncoding(mediaPath, log) {
+    // 1. 双反斜杠 -> 单反斜杠（Markdown 转义）
+    let result = mediaPath.replace(/\\\\/g, "\\");
+    // 2. 八进制转义序列 + UTF-8 双重编码修复
+    try {
+        const hasOctal = /\\[0-7]{1,3}/.test(result);
+        const hasNonASCII = /[\u0080-\u00FF]/.test(result);
+        if (hasOctal || hasNonASCII) {
+            log?.debug?.(`Decoding path with mixed encoding: ${result}`);
+            // Step 1: 将八进制转义转换为字节
+            let decoded = result.replace(/\\([0-7]{1,3})/g, (_, octal) => String.fromCharCode(parseInt(octal, 8)));
+            // Step 2: 提取所有字节（包括 Latin-1 字符）
+            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);
+                }
+            }
+            // Step 3: 尝试按 UTF-8 解码
+            const buffer = Buffer.from(bytes);
+            const utf8Decoded = buffer.toString("utf8");
+            if (!utf8Decoded.includes("\uFFFD") ||
+                utf8Decoded.length < decoded.length) {
+                result = utf8Decoded;
+                log?.debug?.(`Successfully decoded path: ${result}`);
+            }
+        }
+    }
+    catch (decodeErr) {
+        log?.error?.(`Path decode error: ${decodeErr}`);
+    }
+    return result;
+}
+// ============ 代码块检测 ============
+/**
+ * 判断文本中给定位置是否处于围栏代码块内（``` 块）。
+ *
+ * 围栏代码块：行首 ``` 开始，到下一个行首 ``` 结束（或文本末尾）
+ *
+ * @param text 完整文本
+ * @param position 要检测的位置（字符索引）
+ * @returns 如果 position 在围栏代码块内返回 true
+ */
+export function isInsideCodeBlock(text, position) {
+    const fenceRegex = /^(`{3,})[^\n]*$/gm;
+    let fenceMatch;
+    let openFence = null;
+    while ((fenceMatch = fenceRegex.exec(text)) !== null) {
+        const ticks = fenceMatch[1].length;
+        if (!openFence) {
+            openFence = { pos: fenceMatch.index, ticks };
+        }
+        else if (ticks >= openFence.ticks) {
+            // 闭合围栏
+            if (position >= openFence.pos && position < fenceMatch.index + fenceMatch[0].length)
+                return true;
+            openFence = null;
+        }
+    }
+    // 未闭合的围栏一直延伸到文本末尾
+    if (openFence && position >= openFence.pos)
+        return true;
+    return false;
+}
+// ============ 媒体标签解析 ============
+/**
+ * 检测文本是否包含富媒体标签（忽略代码块内的标签）
+ */
+export function hasMediaTags(text) {
+    const normalized = normalizeMediaTags(text);
+    const regex = createMediaTagRegex();
+    let match;
+    while ((match = regex.exec(normalized)) !== null) {
+        if (!isInsideCodeBlock(normalized, match.index))
+            return true;
+    }
+    return false;
+}
+/**
+ * 在文本中查找**第一个**完整闭合的媒体标签
+ *
+ * 与 splitByMediaTags 不同，此函数只匹配一个标签就停止，
+ * 用于流式场景的"循环消费"模式：每次处理一个标签，更新偏移，再找下一个。
+ *
+ * @param text 待检查的文本（应已 normalize 过）
+ * @returns 第一个闭合标签的信息，没有则返回 null
+ */
+export function findFirstClosedMediaTag(text, log) {
+    const regex = createMediaTagRegex();
+    let match;
+    while ((match = regex.exec(text)) !== null) {
+        // 跳过代码块内的媒体标签
+        if (isInsideCodeBlock(text, match.index)) {
+            log?.debug?.(`findFirstClosedMediaTag: skipping <${match[1]}> at index ${match.index} (inside code block)`);
+            continue;
+        }
+        const textBefore = text.slice(0, match.index);
+        const tagName = match[1].toLowerCase();
+        let mediaPath = match[2]?.trim() ?? "";
+        // 剥离 MEDIA: 前缀
+        if (mediaPath.startsWith("MEDIA:")) {
+            mediaPath = mediaPath.slice("MEDIA:".length);
+        }
+        mediaPath = normalizePath(mediaPath);
+        mediaPath = fixPathEncoding(mediaPath, log);
+        const typeMap = {
+            qqimg: "image",
+            qqvoice: "voice",
+            qqvideo: "video",
+            qqfile: "file",
+            qqmedia: "media",
+        };
+        return {
+            textBefore,
+            tagName,
+            mediaPath,
+            tagEndIndex: match.index + match[0].length,
+            itemType: typeMap[tagName] ?? "image",
+        };
+    }
+    return null;
+}
+/**
+ * 将文本按富媒体标签拆分为三部分
+ *
+ * 用于两个场景：
+ * 1. 流式模式：中断-恢复流程（标签前文本 → 结束流式 → 发送媒体 → 新流式 → 标签后文本）
+ * 2. 普通模式：构建按顺序发送的队列
+ */
+export function splitByMediaTags(text, log) {
+    const normalized = normalizeMediaTags(text);
+    const regex = createMediaTagRegex();
+    // 过滤掉代码块内的匹配
+    const matches = [...normalized.matchAll(regex)].filter(m => !isInsideCodeBlock(normalized, m.index));
+    if (matches.length === 0) {
+        return {
+            hasMediaTags: false,
+            textBeforeFirstTag: normalized,
+            textAfterLastTag: "",
+            mediaQueue: [],
+        };
+    }
+    // 第一个标签前的纯文本
+    const firstMatch = matches[0];
+    const textBeforeFirstTag = normalized
+        .slice(0, firstMatch.index)
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    // 最后一个标签后的纯文本
+    const lastMatch = matches[matches.length - 1];
+    const lastMatchEnd = lastMatch.index + lastMatch[0].length;
+    const textAfterLastTag = normalized
+        .slice(lastMatchEnd)
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+    // 构建媒体发送队列
+    const mediaQueue = [];
+    let lastIndex = firstMatch.index;
+    for (const match of matches) {
+        // 标签前的文本（标签之间的间隔文本）
+        const textBetween = normalized
+            .slice(lastIndex, match.index)
+            .replace(/\n{3,}/g, "\n\n")
+            .trim();
+        if (textBetween && lastIndex !== firstMatch.index) {
+            // 只添加非首段的间隔文本（首段由 textBeforeFirstTag 覆盖）
+            mediaQueue.push({ type: "text", content: textBetween });
+        }
+        // 解析标签内容
+        const tagName = match[1].toLowerCase();
+        let mediaPath = match[2]?.trim() ?? "";
+        // 剥离 MEDIA: 前缀
+        if (mediaPath.startsWith("MEDIA:")) {
+            mediaPath = mediaPath.slice("MEDIA:".length);
+        }
+        mediaPath = normalizePath(mediaPath);
+        // 修复路径编码问题
+        mediaPath = fixPathEncoding(mediaPath, log);
+        // 根据标签类型加入队列
+        const typeMap = {
+            qqimg: "image",
+            qqvoice: "voice",
+            qqvideo: "video",
+            qqfile: "file",
+            qqmedia: "media",
+        };
+        const itemType = typeMap[tagName] ?? "image";
+        if (mediaPath) {
+            mediaQueue.push({ type: itemType, content: mediaPath });
+            log?.info?.(`Found ${itemType} in <${tagName}>: ${mediaPath.slice(0, 80)}`);
+        }
+        lastIndex = match.index + match[0].length;
+    }
+    return {
+        hasMediaTags: true,
+        textBeforeFirstTag,
+        textAfterLastTag,
+        mediaQueue,
+    };
+}
+/**
+ * 从文本中解析出完整的发送队列（含标签前后的纯文本）
+ *
+ * 与 splitByMediaTags 的区别：
+ * - splitByMediaTags 分为 before / queue / after 三段（供流式模式的中断-恢复）
+ * - parseMediaTagsToSendQueue 返回一个扁平的完整队列（供普通模式按顺序发送）
+ *
+ * 适用于 gateway.ts deliver 回调和 outbound.ts sendText。
+ */
+export function parseMediaTagsToSendQueue(text, log) {
+    const split = splitByMediaTags(text, log);
+    if (!split.hasMediaTags) {
+        return { hasMediaTags: false, sendQueue: [] };
+    }
+    const sendQueue = [];
+    // 标签前的文本
+    if (split.textBeforeFirstTag) {
+        sendQueue.push({ type: "text", content: split.textBeforeFirstTag });
+    }
+    // 媒体队列（含标签间文本）
+    sendQueue.push(...split.mediaQueue);
+    // 标签后的文本
+    if (split.textAfterLastTag) {
+        sendQueue.push({ type: "text", content: split.textAfterLastTag });
+    }
+    return { hasMediaTags: true, sendQueue };
+}
+// ============ 发送队列执行 ============
+/**
+ * 统一执行发送队列
+ *
+ * 遍历 sendQueue，按类型调用对应的发送函数。
+ * 文本项通过 onSendText 回调处理（不同场景的文本发送方式不同）。
+ * 媒体发送失败时，通过 onSendText 发送兜底文本通知用户。
+ */
+export async function executeSendQueue(queue, ctx, options = {}) {
+    const { mediaTarget, qualifiedTarget, account, replyToId, log } = ctx;
+    const prefix = mediaTarget.logPrefix ?? `[qqbot:${account.accountId}]`;
+    /** 媒体发送失败时的兜底：通过 onSendText 发送错误文本给用户 */
+    const sendFallbackText = async (errorMsg) => {
+        if (!options.onSendText) {
+            log?.info(`${prefix} executeSendQueue: no onSendText handler, cannot send fallback text`);
+            return;
+        }
+        try {
+            await options.onSendText(errorMsg);
+        }
+        catch (fallbackErr) {
+            log?.error(`${prefix} executeSendQueue: fallback text send failed: ${fallbackErr}`);
+        }
+    };
+    for (const item of queue) {
+        const FALLBACK_MSG = "发送失败，请稍后重试。";
+        try {
+            if (item.type === "text") {
+                if (options.skipInterTagText) {
+                    log?.info(`${prefix} executeSendQueue: skipping inter-tag text (${item.content.length} chars)`);
+                    continue;
+                }
+                if (options.onSendText) {
+                    await options.onSendText(item.content);
+                }
+                else {
+                    log?.info(`${prefix} executeSendQueue: no onSendText handler, skipping text`);
+                }
+                continue;
+            }
+            log?.info(`${prefix} executeSendQueue: sending ${item.type}: ${item.content.slice(0, 80)}...`);
+            if (item.type === "image") {
+                const result = await sendPhoto(mediaTarget, item.content);
+                if (result.error) {
+                    log?.error(`${prefix} sendPhoto error: ${result.error}`);
+                    await sendFallbackText(FALLBACK_MSG);
+                }
+            }
+            else if (item.type === "voice") {
+                const uploadFormats = account.config?.audioFormatPolicy?.uploadDirectFormats ??
+                    account.config?.voiceDirectUploadFormats;
+                const transcodeEnabled = account.config?.audioFormatPolicy?.transcodeEnabled !== false;
+                const voiceTimeout = 45000; // 45s
+                try {
+                    const result = await Promise.race([
+                        sendVoice(mediaTarget, item.content, uploadFormats, transcodeEnabled),
+                        new Promise((resolve) => setTimeout(() => resolve({ channel: "qqbot", error: "语音发送超时，已跳过" }), voiceTimeout)),
+                    ]);
+                    if (result.error) {
+                        log?.error(`${prefix} sendVoice error: ${result.error}`);
+                        await sendFallbackText(FALLBACK_MSG);
+                    }
+                }
+                catch (err) {
+                    log?.error(`${prefix} sendVoice unexpected error: ${err}`);
+                    await sendFallbackText(FALLBACK_MSG);
+                }
+            }
+            else if (item.type === "video") {
+                const result = await sendVideoMsg(mediaTarget, item.content);
+                if (result.error) {
+                    log?.error(`${prefix} sendVideoMsg error: ${result.error}`);
+                    await sendFallbackText(FALLBACK_MSG);
+                }
+            }
+            else if (item.type === "file") {
+                const result = await sendDocument(mediaTarget, item.content);
+                if (result.error) {
+                    log?.error(`${prefix} sendDocument error: ${result.error}`);
+                    await sendFallbackText(FALLBACK_MSG);
+                }
+            }
+            else if (item.type === "media") {
+                const result = await sendMediaAuto({
+                    to: qualifiedTarget,
+                    text: "",
+                    mediaUrl: item.content,
+                    accountId: account.accountId,
+                    replyToId,
+                    account,
+                });
+                if (result.error) {
+                    log?.error(`${prefix} sendMedia(auto) error: ${result.error}`);
+                    await sendFallbackText(FALLBACK_MSG);
+                }
+            }
+        }
+        catch (err) {
+            log?.error(`${prefix} executeSendQueue: failed to send ${item.type}: ${err}`);
+            await sendFallbackText(FALLBACK_MSG);
+        }
+    }
+}
+/**
+ * 从文本中剥离所有媒体标签（用于最终显示）
+ */
+export function stripMediaTags(text) {
+    const regex = createMediaTagRegex();
+    return text.replace(regex, "").replace(/\n{3,}/g, "\n\n").trim();
+}
+/**
+ * 检测文本中是否有未闭合的媒体标签，如果有则截断到安全位置。
+ *
+ * 流式输出中 LLM 逐 token 吐出媒体标签，中间态不应直接发给用户。
+ * 只检查最后一行，从右到左扫描 `<`，找到第一个有意义的媒体标签片段并判断是否完整。
+ *
+ * 核心原则：截断只能截到**开标签**前面；闭合标签前缀若找不到对应开标签则原样返回。
+ */
+export function stripIncompleteMediaTag(text) {
+    if (!text)
+        return [text, false];
+    const lastNL = text.lastIndexOf("\n");
+    const lastLine = lastNL === -1 ? text : text.slice(lastNL + 1);
+    if (!lastLine)
+        return [text, false]; // 以换行结尾，安全
+    const lineStart = lastNL === -1 ? 0 : lastNL + 1;
+    // ---- 媒体标签名判断 ----
+    const MEDIA_NAMES = [
+        "qq", "img", "image", "pic", "photo", "voice", "audio", "video",
+        "file", "doc", "media", "attach", "send", "document", "picture",
+        "qqvoice", "qqaudio", "qqvideo", "qqimg", "qqimage", "qqfile",
+        "qqpic", "qqphoto", "qqmedia", "qqattach", "qqsend", "qqdocument", "qqpicture",
+    ];
+    const isMedia = (n) => MEDIA_NAMES.includes(n.toLowerCase());
+    const couldBeMedia = (n) => { const l = n.toLowerCase(); return MEDIA_NAMES.some(m => m.startsWith(l)); };
+    /** 截断到 lastLine 中位置 pos 之前，返回 [safe, true] */
+    const cutAt = (pos) => [
+        text.slice(0, lineStart + pos).trimEnd(),
+        true,
+    ];
+    /** 检查 lastLine 中位置 pos 处的媒体开标签后面是否有完整闭合标签 */
+    const hasClosingAfter = (pos, name) => {
+        const rest = lastLine.slice(pos + 1); // < 之后
+        const gt = rest.search(/[>＞]/);
+        if (gt < 0)
+            return false;
+        const after = rest.slice(gt + 1);
+        return new RegExp(`[<\uFF1C]/${name}\\s*[>\uFF1E]`, "i").test(after);
+    };
+    // ---- 回溯状态 ----
+    // 遇到不完整的闭合标签/孤立 < 时，记录并继续往左找对应的开标签
+    let searchTag = null; // 要找的开标签名，"*" = 来自孤立 <
+    let searchIsClosing = false; // 触发回溯的是闭合类（</、</tag）还是开类（<）
+    let fallbackPos = -1; // 最右边触发回溯的 < 的位置
+    for (let i = lastLine.length - 1; i >= 0; i--) {
+        const ch = lastLine[i];
+        if (ch !== "<" && ch !== "\uFF1C")
+            continue;
+        const after = lastLine.slice(i + 1);
+        const isClosing = after.startsWith("/");
+        const nameStr = isClosing ? after.slice(1) : after;
+        const nameMatch = nameStr.match(/^(\w+)/);
+        // ======== 回溯模式：正在找对应的开标签 ========
+        if (searchTag) {
+            if (!nameMatch || isClosing)
+                continue;
+            const cand = nameMatch[1].toLowerCase();
+            if (!isMedia(cand))
+                continue;
+            // 跳过已有完整闭合对的开标签
+            if (hasClosingAfter(i, cand))
+                continue;
+            if (searchTag === "*") {
+                return cutAt(i); // 通配：任何未闭合的媒体开标签都匹配
+            }
+            // 精确/前缀匹配（闭合标签名可能不完整，如 </qq 对 <qqvoice）
+            const t = searchTag.toLowerCase();
+            if (cand === t || cand.startsWith(t))
+                return cutAt(i);
+            continue;
+        }
+        // ======== 正常扫描 ========
+        // --- 无标签名：孤立 < 或 </ ---
+        if (!nameMatch) {
+            if (!after) {
+                // 孤立 <：可能是新开标签，往左找未闭合的媒体开标签
+                if (fallbackPos < 0)
+                    fallbackPos = i;
+                searchTag = "*";
+                searchIsClosing = false;
+            }
+            else if (after === "/") {
+                // 孤立 </：闭合标签开始，找不到开标签时原样返回
+                if (fallbackPos < 0)
+                    fallbackPos = i;
+                searchTag = "*";
+                searchIsClosing = true;
+            }
+            // 其他（如 "< 3"）：非标签，跳过
+            continue;
+        }
+        const tag = nameMatch[1];
+        const restAfterName = nameStr.slice(tag.length);
+        const hasGT = /[>＞]/.test(restAfterName);
+        // --- 不是媒体标签（也不是前缀） ---
+        if (!isMedia(tag) && !(couldBeMedia(tag) && !hasGT))
+            continue;
+        // --- 标签未闭合（无 >），还在输入中 ---
+        if (!hasGT) {
+            if (isClosing) {
+                // 不完整闭合标签（如 </voice、</i）→ 回溯找开标签
+                if (fallbackPos < 0)
+                    fallbackPos = i;
+                searchTag = tag;
+                searchIsClosing = true;
+                continue;
+            }
+            // 不完整开标签（如 <img、<i）→ 截断
+            return cutAt(i);
+        }
+        // --- 标签有 >，是完整的 ---
+        if (isClosing)
+            return [text, false]; // 完整闭合标签 </tag> → 安全
+        // 完整开标签 <tag...>，检查后面有无对应 </tag>
+        if (hasClosingAfter(i, tag))
+            return [text, false];
+        return cutAt(i); // 无闭合 → 截断
+    }
+    // ---- 循环结束，处理回溯未命中 ----
+    if (searchTag) {
+        if (!searchIsClosing) {
+            // 来自孤立 <，前面没有媒体开标签 → 截断到那个 < 前面
+            return cutAt(fallbackPos);
+        }
+        // 来自闭合类（</、</tag），前面找不到对应开标签 → 不可能是有效媒体标签，原样返回
+        return [text, true];
+    }
+    return [text, false]; // 最后一行无任何 < → 安全
+}

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,165 @@
+/**
+ * 富媒体标签预处理与纠错
+ *
+ * 小模型常见的标签拼写错误及变体，在正则匹配前统一修正为标准格式。
+ */
+import { expandTilde } from "./platform.js";
+// 标准标签名（qqmedia = 统一标签，系统根据文件扩展名自动路由）
+const VALID_TAGS = ["qqimg", "qqvoice", "qqvideo", "qqfile", "qqmedia"];
+// 开头标签别名映射（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",
+    // ---- qqmedia 变体（统一标签，根据扩展名自动路由） ----
+    "qq_media": "qqmedia",
+    "media": "qqmedia",
+    "attachment": "qqmedia",
+    "attach": "qqmedia",
+    "qqattachment": "qqmedia",
+    "qq_attachment": "qqmedia",
+    "qqsend": "qqmedia",
+    "qq_send": "qqmedia",
+    "send": "qqmedia",
+};
+// 构建所有可识别的标签名列表（标准名 + 别名）
+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("|");
+/**
+ * 自闭合属性语法的正则：
+ *   <qqmedia file="/path/to/file.png" />
+ *   <qqimg src="/path" />
+ *   <image file="..." />
+ *   <qqmedia type="file" path="/path/to/file.zip" />   ← 多属性
+ * 支持 file= / src= / path= / url= 属性名，引号可选
+ * 也支持前面有其他属性（如 type="file"）的多属性写法
+ */
+const SELF_CLOSING_TAG_REGEX = new RegExp("`?" +
+    "[<＜<]\\s*(" + TAG_NAME_PATTERN + ")" +
+    // 允许前面有任意其他属性（如 type="file"），非贪婪跳过
+    "(?:\\s+(?!file|src|path|url)[a-z_-]+\\s*=\\s*[\"']?[^\"'/>＞>]*?[\"']?)*" +
+    "\\s+(?:file|src|path|url)\\s*=\\s*" +
+    "[\"']?" +
+    // 注意：文件路径包含 /，不能在字符类中排除 /
+    "([^\"'＞>]+?)" +
+    "[\"']?" +
+    // 允许后面还有其他属性
+    "(?:\\s+[a-z_-]+\\s*=\\s*[\"']?[^\"'/>＞>]*?[\"']?)*" +
+    "\\s*/?" +
+    "\\s*[>＞>]" +
+    "`?", "gi");
+/**
+ * 构建一个宽容的正则，能匹配各种畸形标签写法：
+ *
+ * 常见错误模式：
+ *  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>`
+ *  9. 自闭合属性语法：<qqmedia file="/path" /> (由 SELF_CLOSING_TAG_REGEX 处理)
+ */
+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) {
+    // 第 0 步：将自闭合属性语法转换为标准包裹语法
+    // <qqmedia file="/path/to/file.png" /> → <qqmedia>/path/to/file.png</qqmedia>
+    let cleaned = text.replace(SELF_CLOSING_TAG_REGEX, (_match, rawTag, content) => {
+        const tag = resolveTagName(rawTag);
+        const trimmed = content.trim();
+        if (!trimmed)
+            return _match;
+        const expanded = expandTilde(trimmed);
+        return `<${tag}>${expanded}</${tag}>`;
+    });
+    // 第 1 步：将标签内部的换行/回车/制表符压缩为空格
+    cleaned = cleaned.replace(MULTILINE_TAG_CLEANUP, (_m, open, body, close) => {
+        const flat = body.replace(/[\r\n\t]+/g, " ").replace(/ {2,}/g, " ");
+        return open + flat + close;
+    });
+    // 第 2 步：将各种畸形标签统一为标准格式
+    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}>`;
+    });
+}