@tencent-connect/openclaw-qqbot 1.5.6 → 1.5.7

package/src/outbound.ts

@@ -170,6 +170,8 @@ export interface OutboundResult {
   messageId?: string;
   timestamp?: string | number;
   error?: string;
+  /** 出站消息的引用索引（ext_info.ref_idx），供引用消息缓存使用 */
+  refIdx?: string;
 }
 
 /**
@@ -398,27 +400,27 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
             if (target.type === "c2c") {
               const result = await sendC2CMessage(accessToken, target.id, item.content, replyToId);
               recordMessageReply(replyToId);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: result.ext_info?.ref_idx };
             } else if (target.type === "group") {
               const result = await sendGroupMessage(accessToken, target.id, item.content, replyToId);
               recordMessageReply(replyToId);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: result.ext_info?.ref_idx };
             } else {
               const result = await sendChannelMessage(accessToken, target.id, item.content, replyToId);
               recordMessageReply(replyToId);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
             }
           } else {
             // 主动消息
             if (target.type === "c2c") {
               const result = await sendProactiveC2CMessage(accessToken, target.id, item.content);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
             } else if (target.type === "group") {
               const result = await sendProactiveGroupMessage(accessToken, target.id, item.content);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
             } else {
               const result = await sendChannelMessage(accessToken, target.id, item.content);
-              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+              lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
             }
           }
           console.log(`[qqbot] sendText: Sent text part: ${item.content.slice(0, 30)}...`);
@@ -458,7 +460,7 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
           
           // 发送图片
           if (target.type === "c2c") {
-            const result = await sendC2CImageMessage(accessToken, target.id, imageUrl, replyToId ?? undefined);
+            const result = await sendC2CImageMessage(accessToken, target.id, imageUrl, replyToId ?? undefined, undefined, isHttpUrl ? undefined : imagePath);
             lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
           } else if (target.type === "group") {
             const result = await sendGroupImageMessage(accessToken, target.id, imageUrl, replyToId ?? undefined);
@@ -559,7 +561,7 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
             console.log(`[qqbot] sendText: Read local video (${formatFileSize(fileBuffer.length)}): ${videoPath}`);
 
             if (target.type === "c2c") {
-              const result = await sendC2CVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined);
+              const result = await sendC2CVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined, undefined, videoPath);
               lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
             } else if (target.type === "group") {
               const result = await sendGroupVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined);
@@ -615,7 +617,7 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
             console.log(`[qqbot] sendText: Read local file (${formatFileSize(fileBuffer.length)}): ${filePath}`);
 
             if (target.type === "c2c") {
-              const result = await sendC2CFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName);
+              const result = await sendC2CFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName, filePath);
               lastResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
             } else if (target.type === "group") {
               const result = await sendGroupFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName);
@@ -665,17 +667,19 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
 
     // 如果没有 replyToId，使用主动发送接口
     if (!replyToId) {
+      let outResult: OutboundResult;
       if (target.type === "c2c") {
         const result = await sendProactiveC2CMessage(accessToken, target.id, text);
-        return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+        outResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
       } else if (target.type === "group") {
         const result = await sendProactiveGroupMessage(accessToken, target.id, text);
-        return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+        outResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
       } else {
         // 频道暂不支持主动消息
         const result = await sendChannelMessage(accessToken, target.id, text);
-        return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+        outResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
       }
+      return outResult;
     }
 
     // 有 replyToId，使用被动回复接口
@@ -683,17 +687,17 @@ export async function sendText(ctx: OutboundContext): Promise<OutboundResult> {
       const result = await sendC2CMessage(accessToken, target.id, text, replyToId);
       // 记录回复次数
       recordMessageReply(replyToId);
-      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: result.ext_info?.ref_idx };
     } else if (target.type === "group") {
       const result = await sendGroupMessage(accessToken, target.id, text, replyToId);
       // 记录回复次数
       recordMessageReply(replyToId);
-      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: result.ext_info?.ref_idx };
     } else {
       const result = await sendChannelMessage(accessToken, target.id, text, replyToId);
       // 记录回复次数
       recordMessageReply(replyToId);
-      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
     }
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
@@ -731,23 +735,25 @@ export async function sendProactiveMessage(
     const target = parseTarget(to);
     console.log(`[${timestamp}] [qqbot] sendProactiveMessage: target parsed, type=${target.type}, id=${target.id}`);
 
+    let outResult: OutboundResult;
     if (target.type === "c2c") {
       console.log(`[${timestamp}] [qqbot] sendProactiveMessage: sending proactive C2C message to user=${target.id}`);
       const result = await sendProactiveC2CMessage(accessToken, target.id, text);
       console.log(`[${timestamp}] [qqbot] sendProactiveMessage: proactive C2C message sent successfully, messageId=${result.id}`);
-      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+      outResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
     } else if (target.type === "group") {
       console.log(`[${timestamp}] [qqbot] sendProactiveMessage: sending proactive group message to group=${target.id}`);
       const result = await sendProactiveGroupMessage(accessToken, target.id, text);
       console.log(`[${timestamp}] [qqbot] sendProactiveMessage: proactive group message sent successfully, messageId=${result.id}`);
-      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+      outResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
     } else {
       // 频道暂不支持主动消息，使用普通发送
       console.log(`[${timestamp}] [qqbot] sendProactiveMessage: sending channel message to channel=${target.id}`);
       const result = await sendChannelMessage(accessToken, target.id, text);
       console.log(`[${timestamp}] [qqbot] sendProactiveMessage: channel message sent successfully, messageId=${result.id}`);
-      return { channel: "qqbot", messageId: result.id, timestamp: result.timestamp };
+      outResult = { channel: "qqbot", messageId: result.id, timestamp: result.timestamp, refIdx: (result as any).ext_info?.ref_idx };
     }
+    return outResult;
   } catch (err) {
     const errorMessage = err instanceof Error ? err.message : String(err);
     console.error(`[${timestamp}] [qqbot] sendProactiveMessage: error: ${errorMessage}`);
@@ -901,7 +907,7 @@ export async function sendMedia(ctx: MediaOutboundContext): Promise<OutboundResu
     let imageResult: { id: string; timestamp: number | string };
     if (target.type === "c2c") {
       imageResult = await sendC2CImageMessage(
-        accessToken, target.id, processedMediaUrl, replyToId ?? undefined, undefined
+        accessToken, target.id, processedMediaUrl, replyToId ?? undefined, undefined, isLocalPath ? mediaUrl : undefined
       );
     } else if (target.type === "group") {
       imageResult = await sendGroupImageMessage(
@@ -926,7 +932,7 @@ export async function sendMedia(ctx: MediaOutboundContext): Promise<OutboundResu
       }
     }
 
-  return { channel: "qqbot", messageId: imageResult.id, timestamp: imageResult.timestamp };
+  return { channel: "qqbot", messageId: imageResult.id, timestamp: imageResult.timestamp, refIdx: (imageResult as any).ext_info?.ref_idx };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     return { channel: "qqbot", error: message };
@@ -1003,7 +1009,7 @@ async function sendVoiceFile(ctx: MediaOutboundContext): Promise<OutboundResult>
     }
 
     console.log(`[qqbot] sendVoiceFile: voice message sent`);
-    return { channel: "qqbot", messageId: voiceResult.id, timestamp: voiceResult.timestamp };
+    return { channel: "qqbot", messageId: voiceResult.id, timestamp: voiceResult.timestamp, refIdx: (voiceResult as any).ext_info?.ref_idx };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     console.error(`[qqbot] sendVoiceFile: failed: ${message}`);
@@ -1065,7 +1071,7 @@ async function sendVideoUrl(ctx: MediaOutboundContext): Promise<OutboundResult>
     }
 
     console.log(`[qqbot] sendVideoUrl: video message sent`);
-    return { channel: "qqbot", messageId: videoResult.id, timestamp: videoResult.timestamp };
+    return { channel: "qqbot", messageId: videoResult.id, timestamp: videoResult.timestamp, refIdx: (videoResult as any).ext_info?.ref_idx };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     console.error(`[qqbot] sendVideoUrl: failed: ${message}`);
@@ -1106,7 +1112,7 @@ async function sendVideoFile(ctx: MediaOutboundContext): Promise<OutboundResult>
 
     let videoResult: { id: string; timestamp: number | string };
     if (target.type === "c2c") {
-      videoResult = await sendC2CVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined);
+      videoResult = await sendC2CVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined, undefined, mediaUrl);
     } else if (target.type === "group") {
       videoResult = await sendGroupVideoMessage(accessToken, target.id, undefined, videoBase64, replyToId ?? undefined);
     } else {
@@ -1128,7 +1134,7 @@ async function sendVideoFile(ctx: MediaOutboundContext): Promise<OutboundResult>
     }
 
     console.log(`[qqbot] sendVideoFile: video message sent`);
-    return { channel: "qqbot", messageId: videoResult.id, timestamp: videoResult.timestamp };
+    return { channel: "qqbot", messageId: videoResult.id, timestamp: videoResult.timestamp, refIdx: (videoResult as any).ext_info?.ref_idx };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     console.error(`[qqbot] sendVideoFile: failed: ${message}`);
@@ -1191,7 +1197,7 @@ async function sendDocumentFile(ctx: MediaOutboundContext): Promise<OutboundResu
       console.log(`[qqbot] sendDocumentFile: read local file (${formatFileSize(fileBuffer.length)}), uploading...`);
 
       if (target.type === "c2c") {
-        fileResult = await sendC2CFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName);
+        fileResult = await sendC2CFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName, mediaUrl);
       } else if (target.type === "group") {
         fileResult = await sendGroupFileMessage(accessToken, target.id, fileBase64, undefined, replyToId ?? undefined, fileName);
       } else {
@@ -1214,7 +1220,7 @@ async function sendDocumentFile(ctx: MediaOutboundContext): Promise<OutboundResu
     }
 
     console.log(`[qqbot] sendDocumentFile: file message sent`);
-    return { channel: "qqbot", messageId: fileResult.id, timestamp: fileResult.timestamp };
+    return { channel: "qqbot", messageId: fileResult.id, timestamp: fileResult.timestamp, refIdx: (fileResult as any).ext_info?.ref_idx };
   } catch (err) {
     const message = err instanceof Error ? err.message : String(err);
     console.error(`[qqbot] sendDocumentFile: failed: ${message}`);

package/src/ref-index-store.ts

@@ -0,0 +1,358 @@
+/**
+ * QQ Bot 引用索引持久化存储
+ *
+ * QQ Bot 使用 REFIDX_xxx 索引体系做引用消息，
+ * 入站事件只有索引值，无 API 可回查内容。
+ * 采用 内存缓存 + JSONL 追加写持久化 方案，确保重启后历史引用仍可命中。
+ *
+ * 存储位置：~/.openclaw/qqbot/data/ref-index.jsonl
+ *
+ * 每行格式：{"k":"REFIDX_xxx","v":{...},"t":1709000000}
+ * - k = refIdx 键
+ * - v = 消息数据
+ * - t = 写入时间（用于 TTL 淘汰和 compact）
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { getQQBotDataDir } from "./utils/platform.js";
+
+// ============ 存储的消息摘要 ============
+
+export interface RefIndexEntry {
+  /** 消息文本内容摘要 */
+  content: string;
+  /** 发送者 ID */
+  senderId: string;
+  /** 发送者名称 */
+  senderName?: string;
+  /** 消息时间戳 (ms) */
+  timestamp: number;
+  /** 是否是 bot 发出的消息 */
+  isBot?: boolean;
+  /** 附件摘要（图片/语音/视频/文件等） */
+  attachments?: RefAttachmentSummary[];
+}
+
+/** 附件摘要：存本地路径、在线 URL 和类型描述 */
+export interface RefAttachmentSummary {
+  /** 附件类型 */
+  type: "image" | "voice" | "video" | "file" | "unknown";
+  /** 文件名（如有） */
+  filename?: string;
+  /** MIME 类型 */
+  contentType?: string;
+  /** 语音转录文本（入站：STT/ASR识别结果；出站：TTS原文本） */
+  transcript?: string;
+  /** 语音转录来源：stt=本地STT、asr=QQ官方ASR、tts=TTS原文本、fallback=兜底文案 */
+  transcriptSource?: "stt" | "asr" | "tts" | "fallback";
+  /** 已下载到本地的文件路径（持久化后可供引用时访问） */
+  localPath?: string;
+  /** 在线来源 URL（公网图片/文件等） */
+  url?: string;
+}
+
+// ============ 配置 ============
+
+const STORAGE_DIR = getQQBotDataDir("data");
+const REF_INDEX_FILE = path.join(STORAGE_DIR, "ref-index.jsonl");
+const MAX_CONTENT_LENGTH = 500; // 存储的消息内容最大字符数
+const MAX_ENTRIES = 50000; // 内存中最大缓存条目数
+const TTL_MS = 7 * 24 * 60 * 60 * 1000; // 7 天
+const COMPACT_THRESHOLD_RATIO = 2; // 文件行数超过有效条目 N 倍时 compact
+
+// ============ JSONL 行格式 ============
+
+interface RefIndexLine {
+  /** refIdx 键 */
+  k: string;
+  /** 消息数据 */
+  v: RefIndexEntry;
+  /** 写入时间 (ms) */
+  t: number;
+}
+
+// ============ 内存缓存 ============
+
+let cache: Map<string, RefIndexEntry & { _createdAt: number }> | null = null;
+let totalLinesOnDisk = 0; // 磁盘文件总行数（含过期 / 被覆盖的）
+
+/**
+ * 从 JSONL 文件加载到内存（懒加载，首次访问时触发）
+ */
+function loadFromFile(): Map<string, RefIndexEntry & { _createdAt: number }> {
+  if (cache !== null) return cache;
+
+  cache = new Map();
+  totalLinesOnDisk = 0;
+
+  try {
+    if (!fs.existsSync(REF_INDEX_FILE)) {
+      return cache;
+    }
+
+    const raw = fs.readFileSync(REF_INDEX_FILE, "utf-8");
+    const lines = raw.split("\n");
+    const now = Date.now();
+    let expired = 0;
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+      totalLinesOnDisk++;
+
+      try {
+        const entry = JSON.parse(trimmed) as RefIndexLine;
+        if (!entry.k || !entry.v || !entry.t) continue;
+
+        // 跳过过期条目
+        if (now - entry.t > TTL_MS) {
+          expired++;
+          continue;
+        }
+
+        cache.set(entry.k, {
+          ...entry.v,
+          _createdAt: entry.t,
+        });
+      } catch {
+        // 跳过损坏的行
+      }
+    }
+
+    console.log(
+      `[ref-index-store] Loaded ${cache.size} entries from ${totalLinesOnDisk} lines (${expired} expired)`,
+    );
+
+    // 启动时检查是否需要 compact
+    if (shouldCompact()) {
+      compactFile();
+    }
+  } catch (err) {
+    console.error(`[ref-index-store] Failed to load: ${err}`);
+    cache = new Map();
+  }
+
+  return cache;
+}
+
+// ============ JSONL 追加写入 ============
+
+/**
+ * 追加一行到 JSONL 文件
+ */
+function appendLine(line: RefIndexLine): void {
+  try {
+    ensureDir();
+    fs.appendFileSync(REF_INDEX_FILE, JSON.stringify(line) + "\n", "utf-8");
+    totalLinesOnDisk++;
+  } catch (err) {
+    console.error(`[ref-index-store] Failed to append: ${err}`);
+  }
+}
+
+function ensureDir(): void {
+  if (!fs.existsSync(STORAGE_DIR)) {
+    fs.mkdirSync(STORAGE_DIR, { recursive: true });
+  }
+}
+
+// ============ Compact：重写文件，去除过期和被覆盖的条目 ============
+
+function shouldCompact(): boolean {
+  if (!cache) return false;
+  // 文件行数远超有效条目数时 compact
+  return totalLinesOnDisk > cache.size * COMPACT_THRESHOLD_RATIO && totalLinesOnDisk > 1000;
+}
+
+function compactFile(): void {
+  if (!cache) return;
+
+  const before = totalLinesOnDisk;
+  try {
+    ensureDir();
+    const tmpPath = REF_INDEX_FILE + ".tmp";
+    const lines: string[] = [];
+
+    for (const [key, entry] of cache) {
+      const line: RefIndexLine = {
+        k: key,
+        v: {
+          content: entry.content,
+          senderId: entry.senderId,
+          senderName: entry.senderName,
+          timestamp: entry.timestamp,
+          isBot: entry.isBot,
+          attachments: entry.attachments,
+        },
+        t: entry._createdAt,
+      };
+      lines.push(JSON.stringify(line));
+    }
+
+    fs.writeFileSync(tmpPath, lines.join("\n") + "\n", "utf-8");
+    fs.renameSync(tmpPath, REF_INDEX_FILE);
+    totalLinesOnDisk = cache.size;
+    console.log(`[ref-index-store] Compacted: ${before} lines → ${totalLinesOnDisk} lines`);
+  } catch (err) {
+    console.error(`[ref-index-store] Compact failed: ${err}`);
+  }
+}
+
+// ============ 溢出淘汰 ============
+
+function evictIfNeeded(): void {
+  if (!cache || cache.size < MAX_ENTRIES) return;
+
+  const now = Date.now();
+  // 第一轮：清理过期
+  for (const [key, entry] of cache) {
+    if (now - entry._createdAt > TTL_MS) {
+      cache.delete(key);
+    }
+  }
+
+  // 第二轮：仍超限，按时间删最旧
+  if (cache.size >= MAX_ENTRIES) {
+    const sorted = [...cache.entries()].sort((a, b) => a[1]._createdAt - b[1]._createdAt);
+    const toRemove = sorted.slice(0, cache.size - MAX_ENTRIES + 1000);
+    for (const [key] of toRemove) {
+      cache.delete(key);
+    }
+    console.log(`[ref-index-store] Evicted ${toRemove.length} oldest entries`);
+  }
+}
+
+// ============ 公共 API ============
+
+/**
+ * 存储一条消息的 refIdx 映射
+ */
+export function setRefIndex(refIdx: string, entry: RefIndexEntry): void {
+  const store = loadFromFile();
+  evictIfNeeded();
+
+  const now = Date.now();
+  store.set(refIdx, {
+    content: entry.content.slice(0, MAX_CONTENT_LENGTH),
+    senderId: entry.senderId,
+    senderName: entry.senderName,
+    timestamp: entry.timestamp,
+    isBot: entry.isBot,
+    attachments: entry.attachments,
+    _createdAt: now,
+  });
+
+  // 追加写入 JSONL
+  appendLine({
+    k: refIdx,
+    v: {
+      content: entry.content.slice(0, MAX_CONTENT_LENGTH),
+      senderId: entry.senderId,
+      senderName: entry.senderName,
+      timestamp: entry.timestamp,
+      isBot: entry.isBot,
+      attachments: entry.attachments,
+    },
+    t: now,
+  });
+
+  // 检查是否需要 compact
+  if (shouldCompact()) {
+    compactFile();
+  }
+}
+
+/**
+ * 查找被引用消息
+ */
+export function getRefIndex(refIdx: string): RefIndexEntry | null {
+  const store = loadFromFile();
+  const entry = store.get(refIdx);
+  if (!entry) return null;
+
+  // 检查过期
+  if (Date.now() - entry._createdAt > TTL_MS) {
+    store.delete(refIdx);
+    return null;
+  }
+
+  return {
+    content: entry.content,
+    senderId: entry.senderId,
+    senderName: entry.senderName,
+    timestamp: entry.timestamp,
+    isBot: entry.isBot,
+    attachments: entry.attachments,
+  };
+}
+
+/**
+ * 将引用消息内容格式化为人类可读的描述（供 AI 上下文注入）
+ */
+export function formatRefEntryForAgent(entry: RefIndexEntry): string {
+  const parts: string[] = [];
+
+  // 文本内容
+  if (entry.content.trim()) {
+    parts.push(entry.content);
+  }
+
+  // 附件描述
+  if (entry.attachments?.length) {
+    for (const att of entry.attachments) {
+      const sourceHint = att.localPath ? ` (${att.localPath})` : att.url ? ` (${att.url})` : "";
+      switch (att.type) {
+        case "image":
+          parts.push(`[图片${att.filename ? `: ${att.filename}` : ""}${sourceHint}]`);
+          break;
+        case "voice":
+          if (att.transcript) {
+            const sourceMap = { stt: "本地识别", asr: "官方识别", tts: "TTS原文", fallback: "兜底文案" };
+            const sourceTag = att.transcriptSource ? ` - ${sourceMap[att.transcriptSource] || att.transcriptSource}` : "";
+            parts.push(`[语音消息（内容: "${att.transcript}"${sourceTag}）${sourceHint}]`);
+          } else {
+            parts.push(`[语音消息${sourceHint}]`);
+          }
+          break;
+        case "video":
+          parts.push(`[视频${att.filename ? `: ${att.filename}` : ""}${sourceHint}]`);
+          break;
+        case "file":
+          parts.push(`[文件${att.filename ? `: ${att.filename}` : ""}${sourceHint}]`);
+          break;
+        default:
+          parts.push(`[附件${att.filename ? `: ${att.filename}` : ""}${sourceHint}]`);
+      }
+    }
+  }
+
+  return parts.join(" ") || "[空消息]";
+}
+
+/**
+ * 进程退出前强制 compact（确保数据一致性）
+ */
+export function flushRefIndex(): void {
+  if (cache && shouldCompact()) {
+    compactFile();
+  }
+}
+
+/**
+ * 缓存统计（调试用）
+ */
+export function getRefIndexStats(): {
+  size: number;
+  maxEntries: number;
+  totalLinesOnDisk: number;
+  filePath: string;
+} {
+  const store = loadFromFile();
+  return {
+    size: store.size,
+    maxEntries: MAX_ENTRIES,
+    totalLinesOnDisk,
+    filePath: REF_INDEX_FILE,
+  };
+}

package/src/types.ts

@@ -102,6 +102,8 @@ export interface C2CMessageEvent {
   timestamp: string;
   message_scene?: {
     source: string;
+    /** ext 数组，可能包含 ref_msg_idx=REFIDX_xxx（引用的消息）和 msg_idx=REFIDX_xxx（自身索引） */
+    ext?: string[];
   };
   attachments?: MessageAttachment[];
 }
@@ -140,6 +142,10 @@ export interface GroupMessageEvent {
   timestamp: string;
   group_id: string;
   group_openid: string;
+  message_scene?: {
+    source: string;
+    ext?: string[];
+  };
   attachments?: MessageAttachment[];
 }
 

package/src/utils/platform.ts

@@ -105,11 +105,22 @@ export function expandTilde(p: string): string {
 }
 
 /**
- * 对路径进行完整的规范化处理：展开波浪线 + 去除首尾空白
+ * 对路径进行完整的规范化处理：剥离 file:// 前缀 + 展开波浪线 + 去除首尾空白
  * 所有文件操作前应通过此函数处理用户输入的路径
  */
 export function normalizePath(p: string): string {
-  return expandTilde(p.trim());
+  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 规范化 ============
@@ -163,6 +174,7 @@ export function sanitizeFileName(name: string): string {
  * - Windows 绝对路径: C:\..., D:/..., \\server\share
  * - 相对路径: ./file, ../file
  * - 波浪线路径: ~/Desktop/file.png
+ * - file:// 协议: file:///Users/..., file:///home/...
  *
  * 不匹配:
  * - http:// / https:// URL
@@ -170,6 +182,8 @@ export function sanitizeFileName(name: string): string {
  */
 export function isLocalPath(p: string): boolean {
   if (!p) return false;
+  // file:// 协议（本地文件 URI）
+  if (p.startsWith("file://")) return true;
   // 波浪线路径（Mac/Linux 用户常用）
   if (p === "~" || p.startsWith("~/") || p.startsWith("~\\")) return true;
   // Unix 绝对路径