@cxyhhhhh/openclaw-qqbot 1.6.7-alpha.1

package/dist/src/utils/platform.js

@@ -0,0 +1,390 @@
+/**
+ * 跨平台兼容工具
+ *
+ * 统一 Mac / Linux / Windows 三大系统的：
+ * - 用户主目录获取
+ * - 临时目录获取
+ * - 本地路径判断
+ * - ffmpeg / ffprobe 可执行文件路径
+ * - silk-wasm 原生模块兼容性检测
+ * - 启动诊断报告
+ */
+import * as os from "node:os";
+import * as path from "node:path";
+import * as fs from "node:fs";
+import { execFile } from "node:child_process";
+export function getPlatform() {
+    const p = process.platform;
+    if (p === "darwin" || p === "linux" || p === "win32")
+        return p;
+    return "other";
+}
+export function isWindows() {
+    return process.platform === "win32";
+}
+// ============ 用户主目录 ============
+/**
+ * 安全获取用户主目录
+ *
+ * 优先级:
+ * 1. os.homedir()（Node 原生，所有平台）
+ * 2. $HOME（Mac/Linux）或 %USERPROFILE%（Windows）
+ * 3. 降级到 /tmp（Linux/Mac）或 os.tmpdir()（Windows）
+ *
+ * 与之前 `process.env.HOME || "/home/ubuntu"` 的硬编码相比，
+ * 现在能正确处理 Windows 和非 ubuntu 用户。
+ */
+export function getHomeDir() {
+    try {
+        const home = os.homedir();
+        if (home && fs.existsSync(home))
+            return home;
+    }
+    catch { }
+    // fallback 环境变量
+    const envHome = process.env.HOME || process.env.USERPROFILE;
+    if (envHome && fs.existsSync(envHome))
+        return envHome;
+    // 最后降级
+    return os.tmpdir();
+}
+/**
+ * 获取 .openclaw/qqbot 下的子目录路径，并自动创建
+ * 替代各文件中分散的 path.join(HOME, ".openclaw", "qqbot", ...)
+ */
+export function getQQBotDataDir(...subPaths) {
+    const dir = path.join(getHomeDir(), ".openclaw", "qqbot", ...subPaths);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+/**
+ * 获取 .openclaw/media/qqbot 下的子目录路径，并自动创建
+ *
+ * 与 getQQBotDataDir 不同，此目录位于 OpenClaw 核心的媒体安全白名单
+ * (~/.openclaw/media) 之下，下载到这里的文件可以被框架的 image/media
+ * 工具直接访问，不会触发 "Local media path is not under an allowed directory" 错误。
+ *
+ * 用于存放从 QQ 下载的图片、语音等需要被框架处理的媒体文件。
+ */
+export function getQQBotMediaDir(...subPaths) {
+    const dir = path.join(getHomeDir(), ".openclaw", "media", "qqbot", ...subPaths);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    return dir;
+}
+// ============ 临时目录 ============
+/**
+ * 获取系统临时目录（跨平台安全）
+ * Mac: /var/folders/... 或 /tmp
+ * Linux: /tmp
+ * Windows: %TEMP% 或 C:\Users\xxx\AppData\Local\Temp
+ */
+export function getTempDir() {
+    return os.tmpdir();
+}
+// ============ 波浪线路径展开 ============
+/**
+ * 展开路径中的波浪线（~）为用户主目录
+ *
+ * Mac/Linux 用户经常使用 `~/Desktop/file.png` 这样的路径，
+ * 但 Node.js 的 fs 模块不会像 shell 一样自动展开 `~`。
+ *
+ * 支持:
+ * - `~/xxx`  → `/Users/you/xxx`（Mac）或 `/home/you/xxx`（Linux）
+ * - `~`      → `/Users/you`
+ * - 非 `~` 开头的路径原样返回
+ *
+ * 注意: 不支持 `~otheruser/xxx` 语法（极少使用，且需要系统调用获取其他用户信息）
+ */
+export function expandTilde(p) {
+    if (!p)
+        return p;
+    if (p === "~")
+        return getHomeDir();
+    if (p.startsWith("~/") || p.startsWith("~\\")) {
+        return path.join(getHomeDir(), p.slice(2));
+    }
+    return p;
+}
+/**
+ * 对路径进行完整的规范化处理：剥离 file:// 前缀 + 展开波浪线 + 去除首尾空白
+ * 所有文件操作前应通过此函数处理用户输入的路径
+ */
+export function normalizePath(p) {
+    let result = p.trim();
+    // 剥离 file:// 协议前缀: file:///Users/... → /Users/...
+    if (result.startsWith("file://")) {
+        result = result.slice("file://".length);
+        // 处理 URL 编码（file:// 路径中空格等字符可能被编码）
+        try {
+            result = decodeURIComponent(result);
+        }
+        catch {
+            // decodeURIComponent 失败时保留原样
+        }
+    }
+    return expandTilde(result);
+}
+// ============ 文件名 UTF-8 规范化 ============
+/**
+ * 规范化文件名为 QQ Bot API 要求的 UTF-8 编码格式
+ *
+ * 问题场景:
+ * - macOS HFS+/APFS 文件系统使用 NFD（Unicode 分解形式）存储文件名，
+ *   例如「中文.txt」被分解为多个码点，QQ Bot API 可能拒绝
+ * - 文件名可能包含 API 不接受的特殊控制字符
+ * - URL 路径中可能包含 percent-encoded 的文件名需要解码
+ *
+ * 处理:
+ * 1. Unicode NFC 规范化（将 NFD 分解形式合并为 NFC 组合形式）
+ * 2. 去除 ASCII 控制字符（0x00-0x1F, 0x7F）
+ * 3. 去除首尾空白
+ * 4. 对 percent-encoded 的文件名尝试 URI 解码
+ */
+export function sanitizeFileName(name) {
+    if (!name)
+        return name;
+    let result = name.trim();
+    // 尝试 URI 解码（处理 URL 中 percent-encoded 的中文文件名）
+    // 例如 %E4%B8%AD%E6%96%87.txt → 中文.txt
+    if (result.includes("%")) {
+        try {
+            result = decodeURIComponent(result);
+        }
+        catch {
+            // 解码失败（非合法 percent-encoding），保留原始值
+        }
+    }
+    // Unicode NFC 规范化：将 macOS NFD 分解形式合并为标准 NFC 组合形式
+    result = result.normalize("NFC");
+    // 去除 ASCII 控制字符（保留所有可打印字符和非 ASCII Unicode 字符）
+    result = result.replace(/[\x00-\x1F\x7F]/g, "");
+    return result;
+}
+// ============ 本地路径判断 ============
+/**
+ * 判断字符串是否为本地文件路径（非 URL）
+ *
+ * 覆盖:
+ * - Unix 绝对路径: /Users/..., /home/..., /tmp/...
+ * - Windows 绝对路径: C:\..., D:/..., \\server\share
+ * - 相对路径: ./file, ../file
+ * - 波浪线路径: ~/Desktop/file.png
+ * - file:// 协议: file:///Users/..., file:///home/...
+ *
+ * 不匹配:
+ * - http:// / https:// URL
+ * - data: URL
+ */
+export function isLocalPath(p) {
+    if (!p)
+        return false;
+    // file:// 协议（本地文件 URI）
+    if (p.startsWith("file://"))
+        return true;
+    // 波浪线路径（Mac/Linux 用户常用）
+    if (p === "~" || p.startsWith("~/") || p.startsWith("~\\"))
+        return true;
+    // Unix 绝对路径
+    if (p.startsWith("/"))
+        return true;
+    // Windows 盘符: C:\ 或 C:/
+    if (/^[a-zA-Z]:[\\/]/.test(p))
+        return true;
+    // Windows UNC: \\server\share
+    if (p.startsWith("\\\\"))
+        return true;
+    // 相对路径
+    if (p.startsWith("./") || p.startsWith("../"))
+        return true;
+    // Windows 相对路径
+    if (p.startsWith(".\\") || p.startsWith("..\\"))
+        return true;
+    return false;
+}
+/**
+ * 判断 markdown 中提取的路径是否像本地路径
+ * 比 isLocalPath 更宽松，用于从 markdown ![](path) 中检测误用
+ */
+export function looksLikeLocalPath(p) {
+    if (isLocalPath(p))
+        return true;
+    // 常见系统目录前缀（不以 / 开头时也匹配）
+    return /^(?:Users|home|tmp|var|private|[A-Z]:)/i.test(p);
+}
+// ============ ffmpeg 跨平台检测 ============
+let _ffmpegPath; // undefined = 未检测, null = 不可用
+let _ffmpegCheckPromise = null;
+/**
+ * 检测 ffmpeg 是否可用，返回可执行路径
+ *
+ * Windows 上检测 ffmpeg.exe，Mac/Linux 检测 ffmpeg
+ * 支持通过环境变量 FFMPEG_PATH 指定自定义路径
+ *
+ * @returns ffmpeg 可执行文件路径，不可用返回 null
+ */
+export function detectFfmpeg() {
+    if (_ffmpegPath !== undefined)
+        return Promise.resolve(_ffmpegPath);
+    if (_ffmpegCheckPromise)
+        return _ffmpegCheckPromise;
+    _ffmpegCheckPromise = (async () => {
+        // 1. 环境变量自定义路径
+        const envPath = process.env.FFMPEG_PATH;
+        if (envPath) {
+            const ok = await testExecutable(envPath, ["-version"]);
+            if (ok) {
+                _ffmpegPath = envPath;
+                console.log(`[platform] ffmpeg found via FFMPEG_PATH: ${envPath}`);
+                return _ffmpegPath;
+            }
+            console.warn(`[platform] FFMPEG_PATH set but not working: ${envPath}`);
+        }
+        // 2. 系统 PATH 中检测
+        const cmd = isWindows() ? "ffmpeg.exe" : "ffmpeg";
+        const ok = await testExecutable(cmd, ["-version"]);
+        if (ok) {
+            _ffmpegPath = cmd;
+            console.log(`[platform] ffmpeg detected in PATH`);
+            return _ffmpegPath;
+        }
+        // 3. 常见安装位置（Mac brew、Windows choco/scoop）
+        const commonPaths = isWindows()
+            ? [
+                "C:\\ffmpeg\\bin\\ffmpeg.exe",
+                path.join(process.env.LOCALAPPDATA || "", "Programs", "ffmpeg", "bin", "ffmpeg.exe"),
+                path.join(process.env.ProgramFiles || "", "ffmpeg", "bin", "ffmpeg.exe"),
+            ]
+            : [
+                "/usr/local/bin/ffmpeg", // Mac brew
+                "/opt/homebrew/bin/ffmpeg", // Mac ARM brew
+                "/usr/bin/ffmpeg", // Linux apt
+                "/snap/bin/ffmpeg", // Linux snap
+            ];
+        for (const p of commonPaths) {
+            if (p && fs.existsSync(p)) {
+                const works = await testExecutable(p, ["-version"]);
+                if (works) {
+                    _ffmpegPath = p;
+                    console.log(`[platform] ffmpeg found at: ${p}`);
+                    return _ffmpegPath;
+                }
+            }
+        }
+        _ffmpegPath = null;
+        return null;
+    })().finally(() => {
+        _ffmpegCheckPromise = null;
+    });
+    return _ffmpegCheckPromise;
+}
+/** 测试可执行文件是否能正常运行 */
+function testExecutable(cmd, args) {
+    return new Promise((resolve) => {
+        execFile(cmd, args, { timeout: 5000 }, (err) => {
+            resolve(!err);
+        });
+    });
+}
+/** 重置 ffmpeg 缓存（用于测试） */
+export function resetFfmpegCache() {
+    _ffmpegPath = undefined;
+    _ffmpegCheckPromise = null;
+}
+// ============ silk-wasm 兼容性 ============
+let _silkWasmAvailable = null;
+/**
+ * 检测 silk-wasm 是否可用
+ *
+ * silk-wasm 依赖 WASM 运行时，在某些环境（如老版本 Node、某些容器）可能不可用。
+ * 提前检测避免运行时崩溃。
+ */
+export async function checkSilkWasmAvailable() {
+    if (_silkWasmAvailable !== null)
+        return _silkWasmAvailable;
+    try {
+        const { isSilk } = await import("silk-wasm");
+        // 用一个空 buffer 快速测试 WASM 是否能加载
+        isSilk(new Uint8Array(0));
+        _silkWasmAvailable = true;
+        console.log("[platform] silk-wasm: available");
+    }
+    catch (err) {
+        _silkWasmAvailable = false;
+        console.warn(`[platform] silk-wasm: NOT available (${err instanceof Error ? err.message : String(err)})`);
+    }
+    return _silkWasmAvailable;
+}
+/**
+ * 运行启动诊断，返回环境报告
+ * 在 gateway 启动时调用，打印环境信息并给出警告
+ */
+export async function runDiagnostics() {
+    const warnings = [];
+    const platform = `${process.platform} (${os.release()})`;
+    const arch = process.arch;
+    const nodeVersion = process.version;
+    const homeDir = getHomeDir();
+    const tempDir = getTempDir();
+    const dataDir = getQQBotDataDir();
+    // 检测 ffmpeg
+    const ffmpegPath = await detectFfmpeg();
+    if (!ffmpegPath) {
+        warnings.push(isWindows()
+            ? "⚠️ ffmpeg 未安装。语音/视频格式转换将受限。安装方式: choco install ffmpeg 或 scoop install ffmpeg 或从 https://ffmpeg.org 下载"
+            : getPlatform() === "darwin"
+                ? "⚠️ ffmpeg 未安装。语音/视频格式转换将受限。安装方式: brew install ffmpeg"
+                : "⚠️ ffmpeg 未安装。语音/视频格式转换将受限。安装方式: sudo apt install ffmpeg 或 sudo yum install ffmpeg");
+    }
+    // 检测 silk-wasm
+    const silkWasm = await checkSilkWasmAvailable();
+    if (!silkWasm) {
+        warnings.push("⚠️ silk-wasm 不可用。QQ 语音消息的收发将无法工作。请确认 Node.js 版本 >= 16 且 WASM 支持正常");
+    }
+    // 检查数据目录可写性
+    try {
+        const testFile = path.join(dataDir, ".write-test");
+        fs.writeFileSync(testFile, "test");
+        fs.unlinkSync(testFile);
+    }
+    catch {
+        warnings.push(`⚠️ 数据目录不可写: ${dataDir}。请检查权限`);
+    }
+    // Windows 特殊提醒
+    if (isWindows()) {
+        // 检查路径中是否有中文或空格（可能导致某些工具异常）
+        if (/[\u4e00-\u9fa5]/.test(homeDir) || homeDir.includes(" ")) {
+            warnings.push(`⚠️ 用户目录包含中文或空格: ${homeDir}。某些工具可能无法正常工作，建议设置 QQBOT_DATA_DIR 环境变量指定纯英文路径`);
+        }
+    }
+    const report = {
+        platform,
+        arch,
+        nodeVersion,
+        homeDir,
+        tempDir,
+        dataDir,
+        ffmpeg: ffmpegPath,
+        silkWasm,
+        warnings,
+    };
+    // 打印诊断报告
+    console.log("=== QQBot 环境诊断 ===");
+    console.log(`  平台: ${platform} (${arch})`);
+    console.log(`  Node: ${nodeVersion}`);
+    console.log(`  主目录: ${homeDir}`);
+    console.log(`  数据目录: ${dataDir}`);
+    console.log(`  ffmpeg: ${ffmpegPath ?? "未安装"}`);
+    console.log(`  silk-wasm: ${silkWasm ? "可用" : "不可用"}`);
+    if (warnings.length > 0) {
+        console.log("  --- 警告 ---");
+        for (const w of warnings) {
+            console.log(`  ${w}`);
+        }
+    }
+    console.log("======================");
+    return report;
+}

package/dist/src/utils/ssrf-guard.d.ts

@@ -0,0 +1,25 @@
+/**
+ * 远程 URL 安全校验
+ *
+ * 下载外部资源前，确保目标地址不会命中内部网络或云元数据端点，
+ * 避免模型输出的恶意链接触达内网服务。
+ */
+/**
+ * 检查给定 IP 是否落在不可路由 / 私有网段内。
+ *
+ * 覆盖：
+ * - IPv4: 127/8, 10/8, 172.16/12, 192.168/16, 169.254/16, 0.0.0.0
+ * - IPv6: ::1, ::, fe80 (link-local), fc/fd (ULA)
+ */
+export declare function isReservedAddr(ip: string): boolean;
+/**
+ * 校验远程 URL 是否可安全请求。
+ *
+ * 规则：
+ * 1. 仅放行 http / https 协议
+ * 2. 若 URL 直接携带 IP 则即时判定
+ * 3. 若为域名则先做 DNS 解析，逐条检查解析结果
+ *
+ * @throws {Error} 当 URL 指向受限地址时
+ */
+export declare function validateRemoteUrl(raw: string): Promise<void>;

package/dist/src/utils/ssrf-guard.js

@@ -0,0 +1,91 @@
+/**
+ * 远程 URL 安全校验
+ *
+ * 下载外部资源前，确保目标地址不会命中内部网络或云元数据端点，
+ * 避免模型输出的恶意链接触达内网服务。
+ */
+import net from "node:net";
+import dns from "node:dns/promises";
+/* ---------- 内网 / 保留地址判定 ---------- */
+/** IPv4 保留网段前缀（覆盖 RFC 1918、链路本地、回环等） */
+const RESERVED_V4_PREFIXES = [
+    "127.", // loopback
+    "10.", // class-A private
+    "192.168.", // class-C private
+    "169.254.", // link-local / cloud metadata
+];
+/** 172.16.0.0 – 172.31.255.255 需要单独用正则匹配 */
+const PRIVATE_172_RE = /^172\.(1[6-9]|2\d|3[01])\./;
+/**
+ * 检查给定 IP 是否落在不可路由 / 私有网段内。
+ *
+ * 覆盖：
+ * - IPv4: 127/8, 10/8, 172.16/12, 192.168/16, 169.254/16, 0.0.0.0
+ * - IPv6: ::1, ::, fe80 (link-local), fc/fd (ULA)
+ */
+export function isReservedAddr(ip) {
+    // --- IPv4 ---
+    if (ip === "0.0.0.0")
+        return true;
+    for (const pfx of RESERVED_V4_PREFIXES) {
+        if (ip.startsWith(pfx))
+            return true;
+    }
+    if (PRIVATE_172_RE.test(ip))
+        return true;
+    // --- IPv6 ---
+    const lower = ip.toLowerCase();
+    if (lower === "::1" || lower === "::")
+        return true;
+    if (lower.startsWith("fe80:"))
+        return true; // link-local
+    if (lower.startsWith("fc") || lower.startsWith("fd"))
+        return true; // unique local
+    return false;
+}
+/* ---------- URL 合法性校验 ---------- */
+const ALLOWED_SCHEMES = new Set(["http:", "https:"]);
+/**
+ * 校验远程 URL 是否可安全请求。
+ *
+ * 规则：
+ * 1. 仅放行 http / https 协议
+ * 2. 若 URL 直接携带 IP 则即时判定
+ * 3. 若为域名则先做 DNS 解析，逐条检查解析结果
+ *
+ * @throws {Error} 当 URL 指向受限地址时
+ */
+export async function validateRemoteUrl(raw) {
+    const url = new URL(raw);
+    if (!ALLOWED_SCHEMES.has(url.protocol)) {
+        throw new Error(`不支持的协议 "${url.protocol}"，仅允许 http/https（URL: ${raw}）`);
+    }
+    // 去掉 IPv6 方括号
+    const host = url.hostname.replace(/^\[|\]$/g, "");
+    if (net.isIP(host)) {
+        assertPublicAddr(host, raw);
+        return;
+    }
+    // 域名 → 解析后逐条检查
+    try {
+        const ips = await dns.resolve(host);
+        for (const ip of ips) {
+            assertPublicAddr(ip, raw, host);
+        }
+    }
+    catch (err) {
+        // 已经是我们自己抛的安全错误，继续向上传播
+        if (err instanceof Error && err.message.includes("内网"))
+            throw err;
+        // DNS 查询失败不阻塞，后续 fetch 会产生网络错误
+        console.warn(`[url-check] DNS 解析 "${host}" 失败: ${err}`);
+    }
+}
+/* ---------- 内部辅助 ---------- */
+/** 断言 IP 为公网地址，否则抛出错误 */
+function assertPublicAddr(ip, originalUrl, domain) {
+    if (!isReservedAddr(ip))
+        return;
+    const target = domain ? `域名 "${domain}" 解析到内网地址 "${ip}"` : `内网地址 "${ip}"`;
+    throw new Error(`禁止访问${target}，已拦截潜在的 SSRF 请求（URL: ${originalUrl}）`);
+}

package/dist/src/utils/text-parsing.d.ts

@@ -0,0 +1,32 @@
+/**
+ * QQ Bot 文本解析工具函数
+ */
+import type { RefAttachmentSummary } from "../ref-index-store.js";
+/**
+ * 解析 QQ 表情标签，将 <faceType=1,faceId="13",ext="base64..."> 格式
+ * 替换为 【表情: 中文名】 格式
+ * ext 字段为 Base64 编码的 JSON，格式如 {"text":"呲牙"}
+ */
+export declare function parseFaceTags(text: string): string;
+/**
+ * 过滤内部标记（如 [[reply_to: xxx]]）
+ * 这些标记可能被 AI 错误地学习并输出，需要在发送前移除
+ */
+export declare function filterInternalMarkers(text: string): string;
+/**
+ * 从 message_scene.ext 数组中解析引用索引
+ * ext 格式示例: ["", "ref_msg_idx=REFIDX_xxx", "msg_idx=REFIDX_yyy"]
+ */
+export declare function parseRefIndices(ext?: string[]): {
+    refMsgIdx?: string;
+    msgIdx?: string;
+};
+/**
+ * 从附件列表中构建附件摘要（用于引用索引缓存）
+ */
+export declare function buildAttachmentSummaries(attachments?: Array<{
+    content_type: string;
+    url: string;
+    filename?: string;
+    voice_wav_url?: string;
+}>, localPaths?: Array<string | null>): RefAttachmentSummary[] | undefined;

package/dist/src/utils/text-parsing.js

@@ -0,0 +1,69 @@
+/**
+ * QQ Bot 文本解析工具函数
+ */
+import { inferAttachmentType } from "../group-history.js";
+/**
+ * 解析 QQ 表情标签，将 <faceType=1,faceId="13",ext="base64..."> 格式
+ * 替换为 【表情: 中文名】 格式
+ * ext 字段为 Base64 编码的 JSON，格式如 {"text":"呲牙"}
+ */
+export function parseFaceTags(text) {
+    if (!text)
+        return text;
+    return text.replace(/<faceType=\d+,faceId="[^"]*",ext="([^"]*)">/g, (_match, ext) => {
+        try {
+            const decoded = Buffer.from(ext, "base64").toString("utf-8");
+            const parsed = JSON.parse(decoded);
+            const faceName = parsed.text || "未知表情";
+            return `【表情: ${faceName}】`;
+        }
+        catch {
+            return _match;
+        }
+    });
+}
+/**
+ * 过滤内部标记（如 [[reply_to: xxx]]）
+ * 这些标记可能被 AI 错误地学习并输出，需要在发送前移除
+ */
+export function filterInternalMarkers(text) {
+    if (!text)
+        return text;
+    let result = text.replace(/\[\[[a-z_]+:\s*[^\]]*\]\]/gi, "");
+    // 过滤框架内部图片引用标记：@image:image_xxx.png、@voice:voice_xxx.silk 等
+    result = result.replace(/@(?:image|voice|video|file):[a-zA-Z0-9_.-]+/g, "");
+    result = result.replace(/\n{3,}/g, "\n\n").trim();
+    return result;
+}
+/**
+ * 从 message_scene.ext 数组中解析引用索引
+ * ext 格式示例: ["", "ref_msg_idx=REFIDX_xxx", "msg_idx=REFIDX_yyy"]
+ */
+export function parseRefIndices(ext) {
+    if (!ext || ext.length === 0)
+        return {};
+    let refMsgIdx;
+    let msgIdx;
+    for (const item of ext) {
+        if (item.startsWith("ref_msg_idx=")) {
+            refMsgIdx = item.slice("ref_msg_idx=".length);
+        }
+        else if (item.startsWith("msg_idx=")) {
+            msgIdx = item.slice("msg_idx=".length);
+        }
+    }
+    return { refMsgIdx, msgIdx };
+}
+/**
+ * 从附件列表中构建附件摘要（用于引用索引缓存）
+ */
+export function buildAttachmentSummaries(attachments, localPaths) {
+    if (!attachments || attachments.length === 0)
+        return undefined;
+    return attachments.map((att, idx) => ({
+        type: inferAttachmentType(att.content_type),
+        filename: att.filename,
+        contentType: att.content_type,
+        localPath: localPaths?.[idx] ?? undefined,
+    }));
+}

package/dist/src/utils/upload-cache.d.ts

@@ -0,0 +1,34 @@
+/**
+ * file_info 缓存 — 借鉴 Telegram file_id 机制
+ *
+ * QQ Bot API 上传文件后返回 file_info + ttl，在 TTL 内相同文件可直接复用 file_info
+ * 避免重复上传同一文件，节省带宽和时间。
+ *
+ * 缓存 key = md5(fileContent) + targetType(c2c/group) + targetId + fileType
+ */
+/**
+ * 计算文件内容的 MD5 hash（用于缓存 key）
+ * 对于 Base64 数据直接 hash，对于文件路径读取后 hash
+ */
+export declare function computeFileHash(data: string | Buffer): string;
+/**
+ * 从缓存获取 file_info
+ * @returns file_info 字符串，未命中或已过期返回 null
+ */
+export declare function getCachedFileInfo(contentHash: string, scope: "c2c" | "group", targetId: string, fileType: number): string | null;
+/**
+ * 将上传结果写入缓存
+ * @param ttl - API 返回的 TTL（秒），缓存会提前 60 秒失效
+ */
+export declare function setCachedFileInfo(contentHash: string, scope: "c2c" | "group", targetId: string, fileType: number, fileInfo: string, fileUuid: string, ttl: number): void;
+/**
+ * 获取缓存统计
+ */
+export declare function getUploadCacheStats(): {
+    size: number;
+    maxSize: number;
+};
+/**
+ * 清除所有缓存
+ */
+export declare function clearUploadCache(): void;